Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

15    Signature Verification Library

Security and Cryptography

Exploring Palm OS

Signed code in Palm OS Cobalt is used to validate the authenticity of a program resource. There are several types of resources that can be signed in Palm OS Cobalt, including applications, system patches, shared libraries, system components (add-ons), and system drivers. All of these resources are packaged as PRC files and then loaded onto the device. The APIs in the Signature Verification Library can be used to verify a PRC's signature on the device.

This chapter provides reference documentation for the Signature Verification Library. This chapter is organized into the following sections:

Signature Verification Library Structures and Types
Signature Verification Library Constants
Signature Verification Library Functions and Macros

The header file SignVfy.h declares the API that this chapter describes.

Signature Verification Library Structures and Types ^TOP^

SignCertificateBlockType Struct ^TOP^

Purpose

Data structure that references a signature block.

Declared In

SignVfy.h

Prototype

typedef struct {
   uint16_t encoding;
   SignCertificateIDType certificateID;
} SignCertificateBlockType

Fields

encoding
The certificate encoding.
certificateID
The certificate ID.

Comments

The certificate structure returned by SignGetCertificateByIndex() and SignGetCertificateByID() is byte buffer that contains the X.509 representation of the certificate. The signature verification library does not attempt to interpret the X.509 representation of the certificate; that task is left up to the certificate manager.

SignCertificateIDType Typedef ^TOP^

Purpose

Contains a certificate ID.

Declared In

SignVfy.h

Prototype

typedef uint8_t SignCertificateIDType[20]

Comments

The certificate ID holds the SHA1 digest of the certificate public key.

SignSignatureBlockType Struct ^TOP^

Purpose

Data structure that references a signature block.

Declared In

SignVfy.h

Prototype

typedef struct {
   uint32_t index;
   SignCertificateIDType certificateID;
   uint32_t signingDate;
} SignSignatureBlockType

Fields

index
Index position of the signature block in the sign resource.
certificateID
ID of the certificate used to verify this signature.
signingDate
Date when the PRC file was signed.

SignGetNumSignaturesPtrType Typedef ^TOP^

Purpose

Pointer to the SignGetNumSignatures() function.

Declared In

SignVfy.h

Prototype

typedef status_t (*SignGetNumSignaturesPtrType)


   (DmOpenRef dbP, uint16_t *sigCountP)


SignGetShLibCertIdListPtrType Typedef ^TOP^

Purpose

Pointer to the SignGetShLibCertIdListPtrType() function.

Declared In

SignVfy.h

Prototype

typedef status_t (*SignGetShLibCertIdListPtrType)


   (DmOpenRef dbP, uint8_t *certIdList,


   uint32_t *certIdListSize)


SignVerifySignatureByIDPtrType Typedef ^TOP^

Purpose

Pointer to the SignVerifySignatureByID() function.

Declared In

SignVfy.h

Prototype

typedef status_t (*SignVerifySignatureByIDPtrType)


   (DmOpenRef dbP,


   const SignCertificateIDType certificateID)


SignVerifySignatureByIndexPtrType Typedef ^TOP^

Purpose

Pointer to the SignVerifySignatureByIndex() function.

Declared In

SignVfy.h

Prototype

typedef status_t


   (*SignVerifySignatureByIndexPtrType)


   (DmOpenRef dbP, uint16_t index)


Signature Verification Library Constants ^TOP^

Signature Verification Library Entry Points ^TOP^

Purpose

Each of the functions in the Signature Verification Library is identified by its entry point. These constants define those entry points.

Declared In

SignVfy.h

Constants

#define entryNumSignGetCertificateByID (7)
#define entryNumSignGetCertificateByIndex (5)
#define entryNumSignGetDigest (8)
#define entryNumSignGetNumCertificates (3)
#define entryNumSignGetNumSignatures (2)
#define entryNumSignGetOverlayCertIdList (9)
#define entryNumSignGetShLibCertIdList (10)
#define entryNumSignGetSignatureByID (6)
#define entryNumSignGetSignatureByIndex (4)
#define entryNumSignVerifySignatureByID (1)
#define entryNumSignVerifySignatureByIndex (0)

Signature Verification Library Errors ^TOP^

Purpose

Error codes returned by the various Signature Verification Library functions.

Declared In

SignVfy.h

Constants

#define signErrBufferTooSmall (signErrorClass | 10)
The supplied buffer was too small. The required size has been returned through the length parameter.
#define signErrDigestMismatch (signErrorClass | 7)
The signed digest does not match the calculated PRC digest.
#define signErrIndexOutOfBounds (signErrorClass | 3)
The specified index is outside the range of certificate or signature indexes for the PRC.
#define signErrInvalidCertResource (signErrorClass | 5)
The 'cert' resource is malformed, or invalid in some way.
#define signErrInvalidParams (signErrorClass | 9)
One or more function parameters is invalid.
#define signErrInvalidResourceInDB (signErrorClass | 12)
The PRC contains an invalid resource.
#define signErrInvalidSignatureBlock (signErrorClass | 6)
The signature block is invalid.
#define signErrInvalidSignResource (signErrorClass | 4)
The 'sign' resource is malformed, or invalid in some way.
#define signErrNoCertResource (signErrorClass | 2)
No 'cert' resource exists in the PRC file.
#define signErrNoSignResource (signErrorClass | 1)
No 'sign' resource exists in the PRC file.
#define signErrNotFound (signErrorClass | 8)
A certificate or signature with the specified ID was not found.
#define signErrOutOfMemory (signErrorClass | 11)
There was insufficient memory to complete the operation.

Signature Verification Library Functions and Macros ^TOP^

SignGetCertificateByID Function ^TOP^

Purpose

Get a certificate by its ID.

Declared In

SignVfy.h

Prototype

status_t SignGetCertificateByID (
   DmOpenRef dbP,
      const SignCertificateIDType certificateID,
      SignCertificateBlockType *certificateBlock,
      uint32_t *certificateLength,
      uint8_t *certificateData
)
dbP
Pointer to an open PRC database from which to get certificates.
certificateID
The 20-byte ID of the certificate.
certificateBlockP
The PRC's certificate block. See SignCertificateBlockType.
certificateLength
When calling this function, *certificateLength should contain the size of the buffer indicated by certificateData. Upon return, it contains the length of the returned certificate data. If a NULL pointer was passed in for certificateData, signErrBufferTooSmall is returned and the required length is returned through this parameter.
certificateData
A pointer to a caller-allocated buffer to receive the certificate data. To determine how large this buffer should be, set this parameter to NULL; upon return *certificateLength will contain the needed buffer size. After allocating a buffer of the proper size, call this function again to obtain the certificate.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

signErrInvalidParameter
certificateBlockP is NULL.
signErrNoCertResource
No 'cert' resource exists in the PRC file.
signErrInvalidCertResource
The 'cert' resource is malformed, or invalid in some way.
signErrNotFound
A certificate with the specified ID was not found.
signErrBufferTooSmall
The supplied buffer was too small. The required size has been returned through the certificateLength parameter.
signErrInvalidParameter
The certificateLength parameter was set to NULL.

Comments

The ID of a certificate is the SHA1 digest of the DER encoded SubjectPublicKeyInfo field in the certificate, including the sequence tag and length.

The certificate structure returned by this function is a byte buffer that contains the X.509 representation of the certificate. The signature verification library does not attempt to interpret the X.509 representation of the certificate; that task is left up to the Certificate Manager.

See Also

SignGetCertificateByIndex(), SignGetNumCertificates(), SignGetSignatureByID()

SignGetCertificateByIndex Function ^TOP^

Purpose

Get a certificate given its index in the sign resource's certificate block list.

Declared In

SignVfy.h

Prototype

status_t SignGetCertificateByIndex (
   DmOpenRef dbP,
      uint16_t index,
      SignCertificateBlockType *certificateBlock,
      uint32_t *certificateLength,
      uint8_t *certificateData
)

Parameters

dbP
Pointer to an open PRC database from which to get certificates.
index
The position of the certificate within the certificate block list.
certificateBlockP
The PRC's certificate block. See SignCertificateBlockType.
certificateLength
When calling this function, *certificateLength should contain the size of the buffer indicated by certificateData. Upon return, it contains the length of the returned certificate data. If a NULL pointer was passed in for certificateData, signErrBufferTooSmall is returned and the required length is returned through this parameter.
certificateData
A pointer to a caller-allocated buffer to receive the certificate data. To determine how large this buffer should be, set this parameter to NULL; upon return *certificateLength will contain the needed buffer size. After allocating a buffer of the proper size, call this function again to obtain the certificate.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

signErrInvalidParameter
certificateBlockP is NULL.
signErrNoCertResource
No 'cert' resource exists in the PRC file.
signErrInvalidCertResource
The 'cert' resource is malformed, or invalid in some way.
signErrIndexOutOfBounds
The specified index is outside the range of certificate indexes for the PRC's certificate block.
signErrBufferTooSmall
The supplied buffer was too small. The required size has been returned through the certificateLength parameter.
signErrInvalidParameter
The certificateLength parameter was set to NULL.

Comments

The ID of a certificate is the SHA1 digest of the DER encoded SubjectPublicKeyInfo field in the certificate, including the sequence tag and length.

The certificate structure returned by this function is a byte buffer that contains the X.509 representation of the certificate. The signature verification library does not attempt to interpret the X.509 representation of the certificate; that task is left up to the Certificate Manager.

See Also

SignGetCertificateByID(), SignGetNumCertificates(), SignGetSignatureByIndex()

SignGetDigest Function ^TOP^

Purpose

Calculate the digest of a PRC.

Declared In

SignVfy.h

Prototype

status_t SignGetDigest (
   DmOpenRef dbP,
      APHashInfoType *hashinfo
)

Parameters

dbP
Pointer to an open PRC database for which the digest is to be calculated.
hashinfo
An initialized APHashInfoType structure.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

signErrOutOfMemory
There was insufficient memory to complete the operation.
signErrInvalidResourceInDB
The PRC contains an invalid resource.

Comments

The caller is responsible for calling CPMLibHashFinal() and releasing any resources allocated by the Crytographic Provider Manager with CPMLibReleaseHashInfo().

SignGetNumCertificates Function ^TOP^

Purpose

Get the number of certificates in the 'cert' resource.

Declared In

SignVfy.h

Prototype

status_t SignGetNumCertificates (
   DmOpenRef dbP,
      uint16_t *num
)

Parameters

dbP
Pointer to an open PRC database from which to get certificates.
num
The number of certificates in the 'cert' resource.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

signErrInvalidParameter
num is NULL.
signErrNoCertResource
No 'cert' resource exists in the PRC file.
signErrInvalidCertResource
The 'cert' resource is malformed, or invalid in some way.

See Also

SignGetCertificateByIndex(), SignGetNumSignatures()

SignGetNumSignatures Function ^TOP^

Purpose

Get the number of signatures in the 'sign' resource.

Declared In

SignVfy.h

Prototype

status_t SignGetNumSignatures (
   DmOpenRef dbP,
      uint16_t *sigCountP
)

Parameters

dbP
Pointer to an open PRC database from which to get signatures.
sigCountP
The number of signature blocks in the 'sign' resource.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

signErrInvalidParameter
sigCountP is NULL.
signErrNoSignResource
No 'sign' resource exists in the PRC file.
signErrInvalidSignResource
The 'sign' resource is malformed, or invalid in some way.

See Also

SignGetNumCertificates(), SignGetSignatureByIndex()

SignGetOverlayCertIdList Function ^TOP^

Purpose

Get the list of certificate IDs that will validate an overlay for a signed base PRC.

Declared In

SignVfy.h

Prototype

status_t SignGetOverlayCertIdList (
   DmOpenRef dbP,
      uint8_t *certIdList,
   uint32_t *certIdListSize
)

Parameters

dbP
Pointer to an open PRC database from which to get certificates.
certIdList
Pointer to a byte buffer tht receives the certificate IDs. To determine how large this buffer should be, set this parameter to NULL; upon return *certIdListSize will contain the needed buffer size. After allocating a buffer of the proper size, call this function again to obtain the certificate ID list.
certIdListSize
When calling this function, *certIdListSize should contain the size of the buffer indicated by certIdList. Upon return, it contains the length of the returned certificate data. If a NULL pointer was passed in for certIdList, signErrBufferTooSmall is returned and the required length is returned through this parameter.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

signErrInvalidParameter
certIDListSize is NULL.
signErrNoSignResource
No 'sign' resource exists in the PRC file.
signErrInvalidSignResource
The 'sign' resource is malformed, or invalid in some way.
signErrBufferTooSmall
The supplied buffer was too small. The required size has been returned through the certIdListSize parameter.
signErrInvalidParameter
The certIdListSize parameter was set to NULL.

See Also

SignGetShLibCertIdList()

SignGetShLibCertIdList Function ^TOP^

Purpose

Get the list of certificate IDs that will validate a shared library (patch) for the signed base PRC.

Declared In

SignVfy.h

Prototype

status_t SignGetShLibCertIdList (
   DmOpenRef dbP,
      uint8_t *certIdList,
   uint32_t *certIdListSize
)

Parameters

dbP
Pointer to an open PRC database from which to get certificates.
certIdList
Pointer to a byte buffer tht receives the certificate IDs. To determine how large this buffer should be, set this parameter to NULL; upon return *certIdListSize will contain the needed buffer size. After allocating a buffer of the proper size, call this function again to obtain the certificate ID list.
certIdListSize
When calling this function, *certIdListSize should contain the size of the buffer indicated by certIdList. Upon return, it contains the length of the returned certificate data. If a NULL pointer was passed in for certIdList, signErrBufferTooSmall is returned and the required length is returned through this parameter.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

signErrInvalidParameter
certIDListSize is NULL.
signErrNoSignResource
No 'sign' resource exists in the PRC file.
signErrInvalidSignResource
The 'sign' resource is malformed, or invalid in some way.
signErrBufferTooSmall
The supplied buffer was too small. The required size has been returned through the certIdListSize parameter.
signErrInvalidParameter
The certIdListSize parameter was set to NULL.

See Also

SignGetOverlayCertIdList()

SignGetSignatureByID Function ^TOP^

Purpose

Get a signature block given the ID of the signing certificate.

Declared In

SignVfy.h

Prototype

status_t SignGetSignatureByID (
   DmOpenRef dbP,
      const SignCertificateIDType certificateID,
      SignSignatureBlockType *signatureBlockP
)

Parameters

dbP
Pointer to an open PRC database from which to get signatures.
certificateID
The 20-byte ID of the certificate.
signatureBlockP
The returned signature block, which contains meta-data about the signature.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

signErrInvalidParameter
signatureBlockP is NULL.
signErrNoSignResource
No 'sign' resource exists in the PRC file.
signErrInvalidSignResource
The 'sign' resource is malformed, or invalid in some way.
signErrNotFound
A signature with the specified certificate ID was not found.

Comments

A signature block ID is the ID of the public certificate that can be used to verify the signature.

See Also

SignGetCertificateByID(), SignGetNumSignatures(), SignGetSignatureByIndex(), SignVerifySignatureByID()

SignGetSignatureByIndex Function ^TOP^

Purpose

Get a signature block given its index position in the signature block list.

Declared In

SignVfy.h

Prototype

status_t SignGetSignatureByIndex (
   DmOpenRef dbP,
      uint16_t index,
      SignSignatureBlockType *signatureBlockP
)

Parameters

dbP
Pointer to an open PRC database from which to get signatures.
index
The position of the signature within the signature block list.
signatureBlockP
The returned signature block, which contains meta-data about the signature.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

signErrInvalidParameter
signatureBlockP is NULL.
signErrNoSignResource
No 'sign' resource exists in the PRC file.
signErrInvalidSignResource
The 'sign' resource is malformed, or invalid in some way.
signErrIndexOutOfBounds
The specified index is outside the range of signature indexes for the PRC's signature block.

Comments

A signature block ID is the ID of the public certificate that can be used to verify the signature.

See Also

SignGetCertificateByIndex(), SignGetNumSignatures(), SignGetSignatureByID(), SignVerifySignatureByIndex()

SignVerifySignatureByID Function ^TOP^

Purpose

Verify the signature block referenced by the specified ID. The ID is that of the certificate used for verification of the digital signature block.

Declared In

SignVfy.h

Prototype

status_t SignVerifySignatureByID (
   DmOpenRef dbP,
      const SignCertificateIDType certificateID
)

Parameters

dbP
Pointer to an open PRC database from which to get signatures.
certificateID
The 20-byte ID of the certificate.

Returns

Returns errNone if the signature block is valid, or one of the following if an error occurred:

signErrNoSignResource
No 'sign' resource exists in the PRC file.
signErrInvalidSignResource
The 'sign' resource is malformed, or invalid in some way.
signErrInvalidSignatureBlock
The signature block is invalid.
signErrDigestMismatch
The signed digest does not match the calculated PRC digest.

See Also

SignGetSignatureByID(), SignVerifySignatureByIndex()

SignVerifySignatureByIndex Function ^TOP^

Purpose

Verify the signature block referenced by the specified index.

Declared In

SignVfy.h

Prototype

status_t SignVerifySignatureByIndex   (
   DmOpenRef dbP,
   uint16_t index
)

Parameters

dbP
Pointer to an open PRC database from which to get signatures.
index
The position of the signature within the signature block list.

Returns

Returns errNone if the signature block is valid, or one of the following if an error occurred:

signErrNoSignResource
No 'sign' resource exists in the PRC file.
signErrInvalidSignResource
The 'sign' resource is malformed, or invalid in some way.
signErrIndexOutOfBounds
The specified index is outside the range of certificate indexes for the PRC's certificate block.
signErrInvalidSignatureBlock
The signature block is invalid.
signErrDigestMismatch
The signed digest does not match the calculated PRC digest.

See Also

SignGetSignatureByIndex(), SignVerifySignatureByID()