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
SignCertificateBlockType Struct
Purpose
Data structure that references a signature block.
Declared In
SignVfy.h
Prototype
typedef struct { uint16_t encoding; SignCertificateIDType certificateID; } SignCertificateBlockType
Fields
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
Purpose
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
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
Purpose
Pointer to the SignGetNumSignatures()
function.
Declared In
SignVfy.h
Prototype
typedef status_t (*SignGetNumSignaturesPtrType) (DmOpenRefdbP
, uint16_t*sigCountP
)
SignGetShLibCertIdListPtrType Typedef
Purpose
Pointer to the SignGetShLibCertIdListPtrType()
function.
Declared In
SignVfy.h
Prototype
typedef status_t (*SignGetShLibCertIdListPtrType) (DmOpenRefdbP
, uint8_t*certIdList
, uint32_t*certIdListSize
)
SignVerifySignatureByIDPtrType Typedef
Purpose
Pointer to the SignVerifySignatureByID()
function.
Declared In
SignVfy.h
Prototype
typedef status_t (*SignVerifySignatureByIDPtrType) (DmOpenRefdbP
, const SignCertificateIDTypecertificateID
)
SignVerifySignatureByIndexPtrType Typedef
Purpose
Pointer to the SignVerifySignatureByIndex()
function.
Declared In
SignVfy.h
Prototype
typedef status_t (*SignVerifySignatureByIndexPtrType) (DmOpenRefdbP
, uint16_tindex
)
Signature Verification Library Constants
Signature Verification Library Entry Points
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
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
SignGetCertificateByID Function
Purpose
Declared In
SignVfy.h
Prototype
status_t SignGetCertificateByID ( DmOpenRefdbP
, const SignCertificateIDTypecertificateID
, 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 bycertificateData
. Upon return, it contains the length of the returned certificate data. If aNULL
pointer was passed in forcertificateData
,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
isNULL
. -
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 toNULL
.
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
Purpose
Get a certificate given its index in the sign resource's certificate block list.
Declared In
SignVfy.h
Prototype
status_t SignGetCertificateByIndex ( DmOpenRefdbP
, uint16_tindex
, 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 bycertificateData
. Upon return, it contains the length of the returned certificate data. If aNULL
pointer was passed in forcertificateData
,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
isNULL
. -
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 toNULL
.
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
Purpose
Calculate the digest of a PRC.
Declared In
SignVfy.h
Prototype
status_t SignGetDigest ( DmOpenRefdbP
, 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
Purpose
Get the number of certificates in the 'cert'
resource.
Declared In
SignVfy.h
Prototype
status_t SignGetNumCertificates ( DmOpenRefdbP
, 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
isNULL
. -
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
Purpose
Get the number of signatures in the 'sign'
resource.
Declared In
SignVfy.h
Prototype
status_t SignGetNumSignatures ( DmOpenRefdbP
, 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
isNULL
. -
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
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 ( DmOpenRefdbP
, 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 bycertIdList
. Upon return, it contains the length of the returned certificate data. If aNULL
pointer was passed in forcertIdList
,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
isNULL
. -
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 toNULL
.
See Also
SignGetShLibCertIdList Function
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 ( DmOpenRefdbP
, 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 bycertIdList
. Upon return, it contains the length of the returned certificate data. If aNULL
pointer was passed in forcertIdList
,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
isNULL
. -
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 toNULL
.
See Also
SignGetSignatureByID Function
Purpose
Get a signature block given the ID of the signing certificate.
Declared In
SignVfy.h
Prototype
status_t SignGetSignatureByID ( DmOpenRefdbP
, const SignCertificateIDTypecertificateID
, 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
isNULL
. -
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
Purpose
Get a signature block given its index position in the signature block list.
Declared In
SignVfy.h
Prototype
status_t SignGetSignatureByIndex ( DmOpenRefdbP
, uint16_tindex
, 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
isNULL
. -
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
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 ( DmOpenRefdbP
, const SignCertificateIDTypecertificateID
)
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
Purpose
Verify the signature block referenced by the specified index.
Declared In
SignVfy.h
Prototype
status_t SignVerifySignatureByIndex ( DmOpenRefdbP
, uint16_tindex
)
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()