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

9    CPM Library ARM Interface

Security and Cryptography

Exploring Palm OS

The functions documented in this chapter constitute the interface implementation for the Cryptographic Provider Manager library in Palm OS Cobalt. This chapter consists of a single section:

CPM Library ARM Interface Functions and Macros

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

CPM Library ARM Interface Functions and Macros ^TOP^

CPMLibAddRandomSeed Function ^TOP^

Purpose

Puts a number of seed bytes into the pseudo-random number generator maintained by the CPM.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibAddRandomSeed (
   uint8_t *seedDataP,
   uint32_t dataLen
)

Parameters

seedDataP
A buffer of seed bytes.
dataLen
The number of bytes in seedDataP.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibGenerateRandomBytes()

CPMLibClose Function ^TOP^

Purpose

Handles the closing of the CPM library.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibClose (
   void
)

Parameters

None.

Returns

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

cpmErrNotOpen
The CPM library is not open.

Comments

Decrements the reference count. When the reference count reaches zero, memory is cleared out and freed, all resources are returned to the system, and the library is taken out of the system.


WARNING! If you completely close the CPM library (to the point where the reference count is zero), you can prevent other operating system functionality from working (SSL, Authorization Manager, Certification Manager, some areas of the Data Manager and the System library, plus possibly others). Never call CPMLibClose() more times than you have called CPMLibOpen().

See Also

CPMLibOpen(), CPMLibSleep(), CPMLibWake()

CPMLibDecrypt Function ^TOP^

Purpose

Performs the decryption operation in one pass.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibDecrypt (
   APKeyInfoType *keyInfoP,
   APCipherInfoType *cipherInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP
)

Parameters

keyInfoP
An APKeyInfoType structure, allocated and optionally initialized by the application, that holds the key to be used for the operation. Note that for this single-part operation, this structure is not required unless the application wants to pass setting information to or receive setting information from the CPM or provider.
cipherInfoP
An APCipherInfoType structure, allocated and optionally initialized by the application, that holds the context information to be used for this operation. Note that for this single-part operation, this structure is not required unless the application wants to pass setting information to or receive setting information from the CPM or provider.
bufIn
Pointer to a buffer containing the data for the operation. This parameter cannot be NULL.
bufInLen
Size, in bytes, of the buffer specified by bufIn.
bufOut
Pointer to a buffer, allocated by the application, that receives the output of the operation.
bufOutLenP
The length, in bytes, of the buffer specified by bufOut.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType and APCipherInfoType structures. The application must also call CPMLibReleaseKeyInfo() or CPMLibReleaseCipherInfo(), as appropriate, before freeing the structure to allow the CPM and the provider(s) to clean up.

See Also

CPMLibDecryptFinal(), CPMLibDecryptInit(), CPMLibDecryptUpdate(), CPMLibEncrypt(), CPMLibReleaseCipherInfo(), CPMLibReleaseKeyInfo()

CPMLibDecryptFinal Function ^TOP^

Purpose

Finalizes a multi-part decryption operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibDecryptFinal (
   APKeyInfoType *keyInfoP,
   APCipherInfoType *cipherInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP
)

Parameters

keyInfoP
The key to be used for the operation.
cipherInfoP
The context returned from CPMLibDecryptInit().
bufIn
Pointer to a buffer containing the final data for the operation, or NULL if there is no additional data.
bufInLen
Size, in bytes, of the buffer specified by bufIn.
bufOut
Pointer to a buffer, allocated by the application, that receives the output of the operation.
bufOutLenP
The length, in bytes, of the buffer specified by bufOut.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibDecryptInit(), CPMLibDecryptUpdate(), CPMLibEncryptFinal(), CPMLibReleaseCipherInfo()

CPMLibDecryptInit Function ^TOP^

Purpose

Begins a multi-part decryption operation with the specified key and returns the context of the operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibDecryptInit (
   APKeyInfoType *keyInfoP,
   APCipherInfoType *cipherInfoP
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure, allocated and optionally initialized by the application, containing the key to be used for the subsequent calls to CPMLibDecryptUpdate() and CPMLibDecryptFinal().
cipherInfoP
An APCipherInfoType structure, allocated and optionally initialized by the application, that holds the context information for use in subsequent calls to the same class of operations.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType and APCipherInfoType structures. The application must also call CPMLibReleaseKeyInfo() or CPMLibReleaseCipherInfo(), as appropriate, before freeing the structure to allow the CPM and the provider(s) to clean up.

You must call CPMLibDecryptFinal() to finalize the operation.

See Also

CPMLibDecrypt(), CPMLibDecryptFinal(), CPMLibDecryptUpdate(), CPMLibEncryptInit(), CPMLibReleaseCipherInfo()

CPMLibDecryptUpdate Function ^TOP^

Purpose

Updates a multi-part decryption operation with more data.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibDecryptUpdate (
   APKeyInfoType *keyInfoP,
   APCipherInfoType *cipherInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP
)

Parameters

keyInfoP
The key to be used for the operation.
cipherInfoP
The context returned from CPMLibDecryptInit().
bufIn
Pointer to a buffer containing the data for the operation. This parameter cannot be NULL.
bufInLen
Size, in bytes, of the buffer specified by bufIn. This value must be greater than zero.
bufOut
Pointer to a buffer, allocated by the application, that receives the output of the operation.
bufOutLenP
The length, in bytes, of the buffer specified by bufOut.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibDecryptFinal(), CPMLibDecryptInit(), CPMLibEncryptUpdate()

CPMLibDeriveKeyData Function ^TOP^

Purpose

Derives a key from the supplied input data.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibDeriveKeyData (
   APDerivedKeyInfoType *derivedKeyInfoP,
   uint8_t *keyDataP,
   uint32_t *dataLen
)

Parameters

derivedKeyInfoP
Pointer to an APDerivedKeyInfoType structure.
keyDataP
Pointer to a buffer into which the derived key data is written. Pass NULL to determine how large this buffer should be.
dataLen
When calling this function, set the variable to which this parameter points to the size of the keyDataP buffer. Upon return, the variable will be set to the number of bytes written to keyDataP. If you set keyDataP to NULL, set this variable to 0.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

Given the same input data, the same key is always derived from that data. Key derivation is useful for operations such as Password-Based Encryption (PBE) where the password is used to derive a key for a particular cryptographic operation (usually encryption or decryption).

Unlike with generated keys, applications typically do not export and save derived keys since they can be re-derived from the same input data.

Example

To determine how large a buffer you need to allocate for the derived key data, set keyDataP to NULL and *dataLen to 0. CPMLibDeriveKeyData() will return an error code of cpmErrBuffTooSmall and will set the variable pointed to by dataLen to the needed buffer size. Your code can then allocate the needed buffer and again call CPMLibDeriveKeyData() with a pointer to the buffer, as shown in the following code excerpt:


uint32_t size; 
uint32_t *key_data; 
 
// The APDerivedKeyInfoType structure is initialized  
// prior to this point 
size = 0; 
err = CPMLibDeriveKeyData(&dki, NULL, &size); 
if (err == cpmErrBufTooSmall) { 
   key_data = MemPtrNew(size); 
   if (key_data != NULL) { 
      err = CPMLibDeriveKeyData(&dki, key_data, &size); 
      if (err) { 
         // handle errors here 
      } else { 
         // The key data was successfully derived; use 
         // key_data as import data to get a key 
         MemSet(&keyInfo, sizeof(APKeyInfoType), 0); 
         err = CPMLibImportKeyInfo(IMPORT_EXPORT_TYPE_RAW,
            key_data, size, &keyInfo); 
         if (err) { 
            // handle errors here 
         } else { 
            // At this point, we have an APKeyInfoType struct 
         } 
      } 
   } 
} 

See Also

CPMLibGenerateKey(), CPMLibGenerateKeyPair()

CPMLibEncrypt Function ^TOP^

Purpose

Performs an encryption operation in one pass.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibEncrypt (
   APKeyInfoType *keyInfoP,
   APCipherInfoType *cipherInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP
)

Parameters

keyInfoP
An APKeyInfoType structure, allocated and optionally initialized by the application, that holds the key to be used for the operation. Note that for this single-part operation, this structure is not required unless the application wants to pass setting information to or receive setting information from the CPM or provider.
cipherInfoP
An APCipherInfoType structure, allocated and optionally initialized by the application, that holds the context information to be used for this operation. Note that for this single-part operation, this structure is not required unless the application wants to pass setting information to or receive setting information from the CPM or provider.
bufIn
Pointer to a buffer containing the data for the operation. This parameter must not be NULL.
bufInLen
Size, in bytes, of the buffer specified by bufIn.
bufOut
Pointer to a buffer, allocated by the application, that receives the output of the operation.
bufOutLenP
The length, in bytes, of the buffer specified by bufOut.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType and APCipherInfoType structures. The application must also call CPMLibReleaseKeyInfo() or CPMLibReleaseCipherInfo(), as appropriate, before freeing the structure to allow the CPM and the provider(s) to clean up.

See Also

CPMLibDecrypt(), CPMLibEncryptFinal(), CPMLibEncryptInit(), CPMLibEncryptUpdate(), CPMLibReleaseCipherInfo()

CPMLibEncryptFinal Function ^TOP^

Purpose

Finalizes a multi-part encryption operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibEncryptFinal (
   APKeyInfoType *keyInfoP,
   APCipherInfoType *cipherInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP
)

Parameters

keyInfoP
The key to be used for the operation.
cipherInfoP
The context information returned from the CPMLibEncryptInit() call.
bufIn
Pointer to a buffer containing the final data for the operation, or NULL if there is no additional data.
bufInLen
Size, in bytes, of the buffer specified by bufIn.
bufOut
Pointer to a buffer, allocated by the application, that receives the output of the operation.
bufOutLenP
The length, in bytes, of the buffer specified by bufOut.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibDecryptFinal(), CPMLibEncryptInit(), CPMLibEncryptUpdate(), CPMLibReleaseCipherInfo()

CPMLibEncryptInit Function ^TOP^

Purpose

Begins multi-part encryption operation with the specified key and returns the context of the operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibEncryptInit (
   APKeyInfoType *keyInfoP,
   APCipherInfoType *cipherInfoP
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure, allocated and optionally initialized by the application, containing the key to be used for the subsequent calls to CPMLibEncryptUpdate() and CPMLibEncryptFinal().
cipherInfoP
An APCipherInfoType structure, allocated and optionally initialized by the application, that holds the context information for use in subsequent calls to the same class of operations.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType and APCipherInfoType structures. The application must also call CPMLibReleaseKeyInfo() or CPMLibReleaseCipherInfo(), as appropriate, before freeing the structure to allow the CPM and the provider(s) to clean up.

You must call CPMLibEncryptFinal() to finalize the operation.

See Also

CPMLibDecryptInit(), CPMLibEncrypt(), CPMLibEncryptFinal(), CPMLibEncryptUpdate(), CPMLibReleaseCipherInfo()

CPMLibEncryptUpdate Function ^TOP^

Purpose

Updates a multi-part encryption operation with more data.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibEncryptUpdate (
   APKeyInfoType *keyInfoP,
   APCipherInfoType *cipherInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP
)

Parameters

keyInfoP
The key to be used for the operation.
cipherInfoP
The context information returned from the CPMLibEncryptInit() call.
bufIn
Pointer to a buffer containing the data for the operation.
bufInLen
Size, in bytes, of the buffer specified by bufIn.
bufOut
Pointer to a buffer, allocated by the application, that receives the output of the operation.
bufOutLenP
The length, in bytes, of the buffer specified by bufOut.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The bufIn parameter may not be NULL and bufInLen may not be zero.

See Also

CPMLibDecryptUpdate(), CPMLibEncryptFinal(), CPMLibEncryptInit()

CPMLibEnumerateProviders Function ^TOP^

Purpose

Enumerates the providers that the CPM library currently knows about.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibEnumerateProviders (
   uint32_t providerIDs[],
   uint16_t *numProviders
)

Parameters

providerIDs
An array of provider IDs for the providers about which the CPM currently knows.
numProviders
The number of providers currently installed under the CPM library. Also the number of IDs in the providerIDs parameter.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The CPM library returns the IDs of the providers. The IDs can be used to specifically reference a particular provider.

See Also

CPMLibGetInfo(), CPMLibGetProviderInfo(), CPMLibOpen

CPMLibExportCipherInfo Function ^TOP^

Purpose

Creates a storable instance of an APCipherInfoType structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibExportCipherInfo (
   APCipherInfoType *cipherInfoP,
   uint8_t encoding,
   uint8_t *exportDataP,
   uint32_t *dataLenP
)

Parameters

cipherInfoP
An APCipherInfoType structure, allocated and optionally initialized by the application, that holds the context information to be used for this operation.
encoding
One of the encodings documented under "Import/Export Types."
exportDataP
Pointer to a buffer to receive the raw exported data.
dataLenP
Size, in bytes, of the buffer specified by exportDataP.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APCipherInfoType structure. The application must also call CPMLibReleaseCipherInfo() before freeing the APICipherInfoType structure to allow the CPM and the provider(s) to clean up.

See Also

CPMLibImportCipherInfo(), CPMLibReleaseCipherInfo()

CPMLibExportHashInfo Function ^TOP^

Purpose

Creates a storable instance of an APHashInfoType structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibExportHashInfo (
   APHashInfoType *hashInfoP,
   uint8_t encoding,
   uint8_t *exportDataP,
   uint32_t *dataLenP
)

Parameters

hashInfoP
An APHashInfoType structure, allocated by the application, that holds information about the hashing operation.
encoding
One of the encodings documented under "Import/Export Types."
exportDataP
Pointer to a buffer, allocated by the application, into which the raw exported data will be placed.
dataLenP
The size, in bytes, of the buffer specified by exportDataP.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibImportHashInfo()

CPMLibExportKeyInfo Function ^TOP^

Purpose

Creates a storable instance of a key that is already familiar to the CPM framework.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibExportKeyInfo (
   APKeyInfoType *keyInfoP,
   uint8_t encoding,
   uint8_t *exportDataP,
   uint32_t *dataLenP
)

Parameters

keyInfoP
An APKeyInfoType structure, allocated and optionally initialized by the application, that holds information about the key to be used for this operation.
encoding
One of the values documented under "Import/Export Types."
exportDataP
Pointer to a buffer, allocated by the application, into which the raw exported data is to be placed.
dataLenP
The size of the buffer specified by exportDataP.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

If a generated key is used for any cryptographic operations, it must be exported and saved in order to be used again. It is statistically improbable that a generated key could be regenerated. Derived keys, on the other hand, are generally not exported since given the same input data (often a password or something similar), the same key is always derived from that data.

The application is always responsible for allocating and freeing the APKeyInfoType structure. The application must call CPMLibReleaseKeyInfo() before freeing the APKeyInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibImportKeyInfo(), CPMLibReleaseKeyInfo()

CPMLibExportKeyPairInfo Function ^TOP^

Purpose

Creates a storable instance of a set of APKeyInfoType structures representing a private key and a public key.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibExportKeyPairInfo (
   APKeyInfoType *privateKeyInfoP,
   APKeyInfoType *publicKeyInfoP,
   uint8_t encoding,
   uint8_t *exportDataP,
   uint32_t *dataLenP
)

Parameters

privateKeyInfoP
Pointer to an APKeyInfoType structure for the private key.
publicKeyInfoP
Pointer to an APKeyInfoType structure for the public key.
encoding
One of the values documented under "Import/Export Types."
exportDataP
Pointer to a buffer, allocated by the application, into which the raw exported data is placed.
dataLenP
The size, in bytes, of the buffer indicated by exportDataP.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType structures. The application must call CPMLibReleaseKeyInfo() before freeing an APKeyInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibImportKeyPairInfo(), CPMLibReleaseKeyInfo()

CPMLibExportMACInfo Function ^TOP^

Purpose

Creates a storable instance of an APMACInfoType structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibExportMACInfo (
   APMACInfoType *macInfoP,
   uint8_t encoding,
   uint8_t *exportDataP,
   uint32_t *dataLenP
)

Parameters

macInfoP
An APMACInfoType structure, allocated and optionally initialized by the application, that holds the message authentication context information to be used for this operation.
encoding
One of the encodings documented under "Import/Export Types."
exportDataP
Pointer to a buffer to receive the raw exported data.
dataLenP
Size, in bytes, of the buffer specified by exportDataP.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APMACInfoType structures. The application must call CPMLibReleaseMACInfo() before freeing an APMACInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibImportMACInfo(), CPMLibReleaseMACInfo()

CPMLibExportSignInfo Function ^TOP^

Purpose

Creates a storable instance of an APSignInfoType structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibExportSignInfo (
   APSignInfoType *signInfoP,
   uint8_t encoding,
   uint8_t *exportDataP,
   uint32_t *dataLenP
)

Parameters

signInfoP
An APSignInfoType structure, allocated and optionally initialized by the application, that holds the context information to be used for this operation.
encoding
One of the encodings documented under "Import/Export Types."
exportDataP
Pointer to a buffer to receive the raw exported data.
dataLenP
Size, in bytes, of the buffer specified by exportDataP.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APSignInfoType structures. The application must call CPMLibReleaseSignInfo() before freeing an APSignInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibImportSignInfo(), CPMLibReleaseSignInfo()

CPMLibExportVerifyInfo Function ^TOP^

Purpose

Creates a storable instance of an APVerifyInfoType structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibExportVerifyInfo (
   APVerifyInfoType *verifyInfoP,
   uint8_t encoding,
   uint8_t *exportDataP,
   uint32_t *dataLenP
)

Parameters

verifyInfoP
An APVerifyInfoType structure, allocated and optionally initialized by the application, that holds the context information to be used for this operation.
encoding
One of the encodings documented under "Import/Export Types."
exportDataP
Pointer to a buffer to receive the raw exported data.
dataLenP
Size, in bytes, of the buffer specified by exportDataP.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APVerifyInfoType structures. The application must call CPMLibReleaseVerifyInfo() before freeing an APSVerifyInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibImportVerifyInfo(), CPMLibReleaseVerifyInfo()

CPMLibGenerateKey Function ^TOP^

Purpose

Generates a new key.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibGenerateKey (
   uint8_t *keyDataP,
   uint32_t dataLen,
   APKeyInfoType *keyInfoP
)

Parameters

keyDataP
Pointer to a buffer of seed bytes to be used by the pseudo-random number generator, or NULL to have the pseudo-random number generator use the seed data it already has.
dataLen
The length, in bytes, of the buffer pointed to by keyDataP.
keyInfoP
An APKeyInfoType structure, allocated and optionally initialized by the application, into which the generated key is written.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

If the newly-generated key is utilized for any cryptographic operations, it must be exported and saved in order to be used again. It is statistically improbably that a generated key could be regenerated.

The application is always responsible for allocating and freeing the APKeyInfoType structure. The application must call CPMLibReleaseKeyInfo() before freeing the APKeyInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibExportKeyInfo(), CPMLibImportKeyInfo()

CPMLibGenerateKeyPair Function ^TOP^

Purpose

Generates a new public/private key pair.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibGenerateKeyPair (
   uint8_t *keyDataP,
   uint32_t dataLen,
   APKeyInfoType *privateKeyInfoP,
   APKeyInfoType *publicKeyInfoP
)

Parameters

keyDataP
Pointer to a buffer of seed bytes to be used by the pseudo-random number generator, or NULL to have the pseudo-random number generator use the seed data it already has.
dataLen
The length, in bytes, of the buffer pointed to by keyDataP.
privateKeyInfoP
Pointer to the APKeyInfoType structure for the private key.
publicKeyInfoP
Pointer to the APKeyInfoType structure for the public key.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

If the newly-generated key pair is utilized for any cryptographic operations, the pair must be exported and saved in order to be used again. It is statistically improbably that a generated key pair could be regenerated.

The application is always responsible for allocating and freeing the APKeyInfoType structures. The application must call CPMLibReleaseKeyInfo() before freeing an APKeyInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibExportKeyPairInfo(), CPMLibImportKeyPairInfo()

CPMLibGenerateRandomBytes Function ^TOP^

Purpose

Returns a requested number of random bytes.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibGenerateRandomBytes (
   uint8_t *bufferP,
   uint32_t *bufLenP
)

Parameters

bufferP
Pointer to a buffer, allocated by the application, into which the random bytes are written.
bufLenP
When calling this function, set the variable pointed to by this parameter to the size of bufferP. Upon return, the variable contains the number of random bytes written to bufferP.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

If there are not bufLenP random bytes available, this function returns the available random bytes and returns the number of available bytes in bufLenP.

See Also

CPMLibAddRandomSeed()

CPMLibGetInfo Function ^TOP^

Purpose

Returns information about the CPM library as its currently known to the system. This includes the number of instances of the CPM library, the number of providers the CPM library is aware of, and whether or not the default provider is known.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibGetInfo (
   CPMInfoType *infoP
)

Parameters

infoP
Information about the CPM library. See CPMInfoType.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibEnumerateProviders(), CPMLibGetProviderInfo()

CPMLibGetProviderInfo Function ^TOP^

Purpose

Gets information about the requested provider. Information returned includes the name of the provider, some additional text about the provider, the "algorithms" supported, and so on.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibGetProviderInfo (
   uint32_t providerID,
   APProviderInfoType *providerInfoP
)

Parameters

providerID
A provider ID referencing the provider for which info is being requested.
providerInfoP
A APProviderInfoType structure, allocated by the application, into which information about the provider is written.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibEnumerateProviders(), CPMLibGetInfo()

CPMLibHash Function ^TOP^

Purpose

Performs the hashing operation in one pass.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibHash (
   APHashEnum type,
   APHashInfoType *hashinfo,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP
)

Parameters

type
The algorithm provider hash type. One of the values defined by the APHashEnum.
hashinfo
Pointer to an APHashInfoType structure, allocated by the application, into which the context is stored.
bufIn
Pointer to a buffer containing the data for the operation. This parameter cannot be NULL.
bufInLen
The size, in bytes, of the buffer specified by the bufIn parameter.
bufOut
Pointer to a buffer, allocated by the application, that receives the output of the operation.
bufOutLenP
The size, in bytes, of the buffer specified by bufOut.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibHashFinal(), CPMLibHashInit(), CPMLibHashUpdate()

CPMLibHashFinal Function ^TOP^

Purpose

Finalizes a multi-part hash operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibHashFinal (
   APHashInfoType *hashinfo,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP
)

Parameters

hashinfo
The context returned from the call to CPMLibHashInit(). This is an APHashInfoType structure.
bufIn
Pointer a buffer containing the final data for the operation, or NULL if there is no additional data.
bufInLen
The size of the buffer specified by the bufIn parameter.
bufOut
Pointer to a buffer, allocated by the application, that receives the output of the operation.
bufOutLenP
The size, in bytes, of the buffer specified by bufOut.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The results of the hash operation are placed in bufOut.


NOTE: When this function returns, the context in *hashinfo is no longer valid.

See Also

CPMLibHashInit(), CPMLibHashUpdate(), CPMLibReleaseHashInfo()

CPMLibHashInit Function ^TOP^

Purpose

Begins a multi-part hash operation of a specified type and returns the context of the hash operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibHashInit (
   APHashInfoType *hashinfo
)

Parameters

hashinfo
Pointer to an APHashInfoType structure, allocated by the application, into which the context is stored. This context is needed by the CPMLibHashUpdate() and CPMLibHashFinal() functions.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

Requires that CPMLibHashFinal() must be called to free the context.

See Also

CPMLibHash(), CPMLibHashFinal(), CPMLibHashUpdate()

CPMLibHashUpdate Function ^TOP^

Purpose

Updates a multi-part hash operation with more data.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibHashUpdate (
   APHashInfoType *hashinfo,
   uint8_t *bufIn,
   uint32_t bufInLen
)

Parameters

hashinfo
The context returned from the call to CPMLibHashInit(). This is an APHashInfoType structure.
bufIn
Pointer to a buffer containing the data for the operation. This parameter must not be NULL.
bufInLen
The size of the buffer specified by the bufIn parameter. This value must be greater than zero.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibHashFinal(), CPMLibHashInit()

CPMLibImportCipherInfo Function ^TOP^

Purpose

Initialize the contents of an APCipherInfoType structure based upon a storable instance of that structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibImportCipherInfo (
   uint8_t encoding,
   uint8_t *importDataP,
   uint32_t dataLen,
   APCipherInfoType *cipherInfoP
)

Parameters

encoding
One of the encodings documented under "Import/Export Types."
importDataP
Pointer to a buffer containing the raw data to be imported.
dataLen
Length, in bytes, of the buffer specified by importDataP.
cipherInfoP
An APCipherInfoType structure, allocated and optionally initialized by the application, that holds the context information to be used for this operation.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APCipherInfoType structure. The application must also call CPMLibReleaseCipherInfo() before freeing the APICipherInfoType structure to allow the CPM and the provider(s) to clean up.

See Also

CPMLibExportCipherInfo(), CPMLibReleaseCipherInfo()

CPMLibImportHashInfo Function ^TOP^

Purpose

Initialize the contents of an APHashInfoType structure based upon a storable instance of that structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibImportHashInfo (
   uint8_t encoding,
   uint8_t *importDataP,
   uint32_t dataLen,
   APHashInfoType *hashInfoP
)

Parameters

encoding
One of the encodings documented under "Import/Export Types."
importDataP
Pointer to a buffer containing the raw data to be imported.
dataLen
The size, in bytes, of the buffer indicated by importDataP.
hashInfoP
An APHashInfoType structure, allocated by the application, that holds information about the hashing operation.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibExportHashInfo()

CPMLibImportKeyInfo Function ^TOP^

Purpose

Introduces an existing key to the CPM framework.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibImportKeyInfo (
   uint8_t encoding,
   uint8_t *importDataP,
   uint32_t dataLen,
   APKeyInfoType *keyInfoP
)

Parameters

encoding
One of the values documented under "Import/Export Types."
importDataP
Pointer to a buffer containing the raw data to be imported.
dataLen
The size of the buffer specified by importDataP.
keyInfoP
An APKeyInfoType structure, allocated and optionally initialized by the application, that holds information about the key to be used for this operation.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

If no previous key exists, use CPMLibGenerateKey() to generate a new key.

The application is always responsible for allocating and freeing the APKeyInfoType structure. The application must call CPMLibReleaseKeyInfo() before freeing the APKeyInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibExportKeyInfo(), CPMLibGenerateKey(), CPMLibReleaseKeyInfo()

CPMLibImportKeyPairInfo Function ^TOP^

Purpose

Introduces an existing public/private key pair to the CPM framework.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibImportKeyPairInfo (
   uint8_t encoding,
   uint8_t *importDataP,
   uint32_t dataLen,
   APKeyInfoType *privateKeyInfoP,
   APKeyInfoType *publicKeyInfoP
)

Parameters

encoding
One of the values documented under "Import/Export Types."
importDataP
Pointer to a buffer containing the raw data to be imported.
dataLen
The size, in bytes, of the buffer indicated by importDataP.
privateKeyInfoP
Pointer to an APKeyInfoType structure for the private key.
publicKeyInfoP
Pointer to an APKeyInfoType structure for the public key.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType structures. The application must call CPMLibReleaseKeyInfo() before freeing an APKeyInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibExportKeyPairInfo(), CPMLibReleaseKeyInfo()

CPMLibImportMACInfo Function ^TOP^

Purpose

Initialize the contents of an APMACInfoType structure based upon a storable instance of that structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibImportMACInfo (
   uint8_t encoding,
   uint8_t *importDataP,
   uint32_t dataLen,
   APMACInfoType *macInfoP
)

Parameters

encoding
One of the values documented under "Import/Export Types."
importDataP
Pointer to a buffer containing the raw data to be imported.
dataLen
The size, in bytes, of the buffer indicated by importDataP.
macInfoP
Pointer to an APMACInfoType structure, allocated by the application, to contain information about the message authentication context.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APMACInfoType structure. The application must call CPMLibReleaseMACInfo() before freeing the APMACInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibExportMACInfo(), CPMLibReleaseMACInfo()

CPMLibImportSignInfo Function ^TOP^

Purpose

Initialize the contents of an APSignInfoType structure based upon a storable instance of that structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibImportSignInfo (
   uint8_t encoding,
   uint8_t *importDataP,
   uint32_t dataLen,
   APSignInfoType *signInfoP
)

Parameters

encoding
One of the values documented under "Import/Export Types."
importDataP
Pointer to a buffer containing the raw data to be imported.
dataLen
The size, in bytes, of the buffer indicated by importDataP.
signInfoP
Pointer to an APSignInfoType structure, allocated by the application, to contain information about the signature context.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APSignInfoType structure. The application must call CPMLibReleaseSignInfo() before freeing the APSignInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibExportSignInfo(), CPMLibReleaseSignInfo()

CPMLibImportVerifyInfo Function ^TOP^

Purpose

Initialize the contents of an APVerifyInfoType structure based upon a storable instance of that structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibImportVerifyInfo (
   uint8_t encoding,
   uint8_t *importDataP,
   uint32_t dataLen,
   APVerifyInfoType *verifyInfoP
)

Parameters

encoding
One of the values documented under "Import/Export Types."
importDataP
Pointer to a buffer containing the raw data to be imported.
dataLen
The size, in bytes, of the buffer indicated by importDataP.
verifyInfoP
Pointer to an APVerifyInfoType structure, allocated by the application, to contain information about the verification context.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APVerifyInfoType structure. The application must call CPMLibReleaseVerifyInfo() before freeing the APVerifyInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibExportVerifyInfo(), CPMLibReleaseVerifyInfo()

CPMLibMAC Function ^TOP^

Purpose

Performs the message authentication operation in one pass.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibMAC (
   APKeyInfoType *keyInfoP,
   APHashInfoType *hashInfoP,
   APMACEnum type,
   APMACInfoType *macInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure, allocated by the application, containing the key to be used for the operation.
hashInfoP
Pointer to an APHashInfoType structure, allocated by the application, that holds information about the hashing operation to be used for the operation.
type
One of the values declared by the APMACEnum enum.
macInfoP
Pointer to an APMACInfoType structure, allocated by the application, to be used in subsequent calls to the same class of operations.
bufIn
Pointer to a buffer containing the data for the operation. This parameter must not be NULL.
bufInLen
The size, in bytes, of the buffer specified by bufIn. This value must be greater than zero.
bufOut
Pointer to a buffer, allocated by the application, to receive the output of the operation.
bufOutLenP
The size, in bytes, of the buffer specified by the bufOut parameter.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType, APHashInfoType, and APMACInfoType structures. The application must call the appropriate release function before freeing the structure to allow the CPM and provider to clean up.

See Also

CPMLibMACFinal()CPMLibMACInit(), CPMLibMACUpdate(), CPMLibReleaseKeyInfo(), CPMLibReleaseMACInfo(), CPMLibReleaseSignInfo()

CPMLibMACFinal Function ^TOP^

Purpose

Finalizes a multi-part message authentication operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibMACFinal (
   APMACInfoType *macInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP
)

Parameters

macInfoP
Pointer to the APMACInfoType structure that was initialized during the call to CPMLibMACInit().
bufIn
Pointer to a buffer containing the data for the operation, or NULL if there is no additional data.
bufInLen
The size, in bytes, of the buffer specified by bufIn.
bufOut
Pointer to a buffer, allocated by the application, to receive the output of the operation.
bufOutLenP
The size, in bytes, of the buffer specified by the bufOut parameter.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibMACInit(), CPMLibMACUpdate(), CPMLibReleaseMACInfo()

CPMLibMACInit Function ^TOP^

Purpose

Begins a multi-part message authentication operation with the specified key and hash info and returns the context of the operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibMACInit (
   APKeyInfoType *keyInfoP,
   APHashInfoType *hashInfoP,
   APMACInfoType *macInfoP
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure, allocated by the application, containing the key to be used in the subsequent calls to CPMLibMACUpdate() and CPMLibMACFinal().
hashInfoP
Pointer to an APHashInfoType structure, allocated by the application, that holds information about the hashing operation for use in the subsequent calls to CPMLibMACUpdate() and CPMLibMACFinal().
macInfoP
Pointer to an APMACInfoType structure, allocated by the application, to be used in subsequent calls to the same class of operations.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType, APHashInfoType, and APMACInfoType structures. The application must call the appropriate release function before freeing the APKeyInfoType or APMACInfoType structure to allow the CPM and provider to clean up.

See Also

CPMLibMAC(), CPMLibMACFinal(), CPMLibMACUpdate(), CPMLibReleaseHashInfo(), CPMLibReleaseKeyInfo(), CPMLibReleaseMACInfo()

CPMLibMACUpdate Function ^TOP^

Purpose

Updates a multi-part message authentication operation with more data.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibMACUpdate (
   APMACInfoType *macInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP
)

Parameters

macInfoP
Pointer to the APMACInfoType structure that was initialized during the call to CPMLibMACInit().
bufIn
Pointer to a buffer containing the data for the operation. This parameter must not be NULL.
bufInLen
The size, in bytes, of the buffer specified by bufIn. This value must be greater than zero.
bufOut
Pointer to a buffer, allocated by the application, to receive the output of the operation.
bufOutLenP
The size, in bytes, of the buffer specified by the bufOut parameter.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibSignFinal(), CPMLibSignInit()

CPMLibOpen Function ^TOP^

Purpose

Handles the open of the CPM library.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibOpen (
   uint16_t *numProviders
)

Parameters

numProviders
The number of providers the CPM currently knows about.

Returns

errNone if the operation completed successfully, one of the errors listed under "Data Manager Error Codes" of Exploring Palm OS: Memory, Databases, Files if the Data Manager couldn't open the library, or one of the following otherwise:

cpmErrAlreadyOpen
The library is already open.
cpmErrOutOfMemory
There wasn't enough memory to open the library.
cpmErrNoProviders
The CPM library is not aware of any providers. With no providers the CPM library has no functionality.
cpmErrNoBaseProvider
The CPM library cannot load the base provider.

Comments

This function establishes the CPM application context to be used in future CPM calls. It also returns the number of providers the CPM currently knows about. This number should be 1 for the base provider plus any additional providers that may be installed. To enumerate those providers, use CPMLibEnumerateProviders().

See Also

CPMLibClose(), CPMLibSleep(), CPMLibWake()

CPMLibReleaseCipherInfo Function ^TOP^

Purpose

Allows the CPM and the provider(s) to clean up before the application frees the APICipherInfoType structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibReleaseCipherInfo (
   APCipherInfoType *cipherInfoP
)

Parameters

cipherInfoP
Pointer to the APCipherInfoType structure.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

CPMLibReleaseHashInfo Function ^TOP^

Purpose

Allows the CPM and the provider(s) to clean up before the application frees the APIHashInfoType structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibReleaseHashInfo (
   APHashInfoType *hashInfoP
)

Parameters

hashInfoP
Pointer to the APHashInfoType structure.

Comments

The application is not required to call this function; APHashInfoType structures need not be released.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

CPMLibReleaseKeyInfo Function ^TOP^

Purpose

Allows the CPM and the provider(s) to clean up before the application frees the APKeyInfoType structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibReleaseKeyInfo (
   APKeyInfoType *keyInfoP
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

CPMLibReleaseMACInfo Function ^TOP^

Purpose

Allows the CPM and the provider(s) to clean up before the application frees the APMACInfoType structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibReleaseMACInfo (
   APMACInfoType *macInfoP
)

Parameters

macInfoP
Pointer to an APMACInfoType structure.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

CPMLibReleaseSignInfo Function ^TOP^

Purpose

Allows the CPM and the provider(s) to clean up before the application frees the APSignInfoType structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibReleaseSignInfo (
   APSignInfoType *signInfoP
)

Parameters

signInfoP
Pointer to an APSignInfoType structure.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

CPMLibReleaseVerifyInfo Function ^TOP^

Purpose

Allows the CPM and the provider(s) to clean up before the application frees the APVerifyInfoType structure.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibReleaseVerifyInfo (
   APVerifyInfoType *verifyInfoP
)

Parameters

verifyInfoP
Pointer to an APVerifyInfoType structure.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

CPMLibSetDebugLevel Function ^TOP^

Purpose

Specify the level of debug output to be sent from the library using DbgMessage().

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibSetDebugLevel (
   uint8_t debugLevel
)

Parameters

debugLevel
The level of debug output to be sent. One of the values listed under "Debug Output Levels."

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

CPMLibSetDefaultProvider Function ^TOP^

Purpose

Sets the default provider.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibSetDefaultProvider (
   uint32_t providerID
)

Parameters

providerID
A provider ID referencing the provider that is to be the default provider.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The default provider is checked first for supporting operations rather than performing a linear search through the known providers. If an operation is not supported by the default provider, the CPM then checks the other providers.

See Also

CPMLibEnumerateProviders(), CPMLibGetProviderInfo()

CPMLibSign Function ^TOP^

Purpose

Performs the signing operation in one pass.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibSign (
   APKeyInfoType *keyInfoP,
   APSignInfoType *signInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP,
   uint8_t *signature,
   uint32_t *signatureLenP
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure, allocated by the application, containing the key to be used for this signing operation. Note that for this single-part operation, this structure is not required unless the application wants to pass setting information to or receive setting information from the CPM or provider.
signInfoP
Pointer to an APSignInfoType structure, allocated by the application, to be used for this signing operation. Note that for this single-part operation, this structure is not required unless the application wants to pass setting information to or receive setting information from the CPM or provider.
bufIn
Pointer to a buffer containing the data for the operation. This parameter must not be NULL.
bufInLen
The size, in bytes, of the buffer specified by bufIn.
bufOut
Pointer to a buffer, allocated by the application, to receive the output of the operation.
bufOutLenP
The size, in bytes, of the buffer specified by the bufOut parameter.
signature
Pointer to a buffer, allocated by the application, to receive the calculated signature.
signatureLenP
The size, in bytes, of the buffer specified by the signature parameter.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType and APSignInfoType structures. The application must call CPMLibReleaseKeyInfo() or CPMLibReleaseSignInfo(), as appropriate, before freeing the structure to allow the CPM and provider to clean up.

See Also

CPMLibSignFinal()CPMLibSignInit(), CPMLibSignUpdate(), CPMLibReleaseKeyInfo(), CPMLibReleaseSignInfo()

CPMLibSignFinal Function ^TOP^

Purpose

Finalizes a multi-part signing operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibSignFinal (
   APKeyInfoType *keyInfoP,
   APSignInfoType *signInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP,
   uint8_t *signature,
   uint32_t *signatureLenP
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure containing the key to be used for the operation.
signInfoP
Pointer to the APSignInfoType structure that was initialized during the call to CPMLibSignInit().
bufIn
Pointer to a buffer containing the final data for the operation, or NULL if there is no additional data.
bufInLen
The size, in bytes, of the buffer specified by bufIn.
bufOut
Pointer to a buffer, allocated by the application, to receive the output of the operation.
bufOutLenP
The size, in bytes, of the buffer specified by the bufOut parameter.
signature
Pointer to a buffer, allocated by the application, to receive the final calculated signature.
signatureLenP
The size, in bytes, of the buffer specified by the signature parameter.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibSignInit(), CPMLibSignUpdate(), CPMLibReleaseKeyInfo(), CPMLibReleaseSignInfo()

CPMLibSignInit Function ^TOP^

Purpose

Begins a multi-part signing operation with the specified key and returns the context of the signing operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibSignInit (
   APKeyInfoType *keyInfoP,
   APSignInfoType *signInfoP
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure, allocated by the application, containing the key to be used for the subsequent calls to CPMLibSignUpdate() and CPMLibSignFinal().
signInfoP
Pointer to an APSignInfoType structure, allocated by the application, to be used in subsequent calls to the same class of operations.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType and APSignInfoType structures. The application must call CPMLibReleaseKeyInfo() or CPMLibReleaseSignInfo(), as appropriate, before freeing the structure to allow the CPM and provider to clean up.

The application must call CPMLibSignFinal() to finalize the operation.

See Also

CPMLibSign(), CPMLibSignFinal(), CPMLibSignUpdate(), CPMLibReleaseKeyInfo(), CPMLibReleaseSignInfo()

CPMLibSignUpdate Function ^TOP^

Purpose

Updates a multi-part signing operation with more data.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibSignUpdate (
   APKeyInfoType *keyInfoP,
   APSignInfoType *signInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure containing the key to be used for the operation.
signInfoP
Pointer to the APSignInfoType structure that was initialized during the call to CPMLibSignInit().
bufIn
Pointer to a buffer containing the data for the operation. This parameter must not be NULL.
bufInLen
The size, in bytes, of the buffer specified by bufIn. This value must be greater than zero.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibSignFinal(), CPMLibSignInit()

CPMLibSleep Function ^TOP^

Purpose

Allows the library to handle the device going to sleep.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibSleep (
   void
)

Parameters

None.

Returns

errNone.

See Also

CPMLibClose(), CPMLibOpen(), CPMLibWake()

CPMLibVerify Function ^TOP^

Purpose

Performs the verify operation in one pass.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibVerify (
   APKeyInfoType *keyInfoP,
   APVerifyInfoType *verifyInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP,
   uint8_t *signature,
   uint32_t signatureLen,
   VerifyResultType *verifyResultP
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure, allocated by the application, containing the key to be used for this signing operation. Note that for this single-part operation, this structure is not required unless the application wants to pass setting information to or receive setting information from the CPM or provider.
verifyInfoP
Pointer to an APVerifyInfoType structure, allocated by the application, to be used for this verify operation. Note that for this single-part operation, this structure is not required unless the application wants to pass setting information to or receive setting information from the CPM or provider.
bufIn
Pointer to a buffer containing the data for the operation. This parameter must not be NULL.
bufInLen
The size, in bytes, of the buffer specified by bufIn.
bufOut
Pointer to a buffer, allocated by the application, to receive the output of the operation.
bufOutLenP
The size, in bytes, of the buffer specified by the bufOut parameter.
signature
Pointer to a buffer containing the previously calculated signature that is being verified.
signatureLen
The length, in bytes, of the buffer specified by signature.
verifyResultP
Supply a pointer to a VerifyResultType. If the function call completed without error, upon return the VerifyResultType variable will be set to zero if the signature verifies or 1 if the signature did not verify.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType and APVerifyInfoType structures. The application must call CPMLibReleaseKeyInfo() or CPMLibReleaseVerifyInfo(), as appropriate, before freeing the structure to allow the CPM and provider to clean up.

See Also

CPMLibVerifyFinal()CPMLibVerifyInit(), CPMLibVerifyUpdate(), CPMLibReleaseKeyInfo(), CPMLibReleaseVerifyInfo()

CPMLibVerifyFinal Function ^TOP^

Purpose

Finalizes a multi-part verification operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibVerifyFinal (
   APKeyInfoType *keyInfoP,
   APVerifyInfoType *verifyInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen,
   uint8_t *bufOut,
   uint32_t *bufOutLenP,
   uint8_t *signature,
   uint32_t signatureLen,
   VerifyResultType *verifyResultP
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure containing the key to be used for the operation.
verifyInfoP
Pointer to the APVerifyInfoType structure that was initialized during the call to CPMLibVerifyInit().
bufIn
Pointer to a buffer containing the final data for the operation, or NULL if there is no additional data.
bufInLen
The size, in bytes, of the buffer specified by bufIn.
bufOut
Pointer to a buffer, allocated by the application, to receive the output of the operation.
bufOutLenP
The size, in bytes, of the buffer specified by the bufOut parameter.
signature
Pointer to a buffer containing the previously calculated signature that is being verified.
signatureLen
The length, in bytes, of the buffer specified by signature.
verifyResultP
Supply a pointer to a VerifyResultType. If the function call completed without error, upon return the VerifyResultType variable will be set to zero if the signature verifies or 1 if the signature did not verify.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibVerifyInit(), CPMLibVerifyUpdate(), CPMLibReleaseKeyInfo(), CPMLibReleaseVerifyInfo()

CPMLibVerifyInit Function ^TOP^

Purpose

Begins a multi-part verification operation with the specified key and returns the context of the verification operation.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibVerifyInit (
   APKeyInfoType *keyInfoP,
   APVerifyInfoType *verifyInfoP
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure, allocated and optionally initialized by the application, containing the key to be used for the subsequent calls to CPMLibVerifyUpdate() and CPMLibVerifyFinal().
verifyInfoP
Pointer to an APVerifyInfoType structure, allocated by the application, to be used in subsequent calls to CPMLibVerifyUpdate() and CPMLibVerifyFinal().

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

Comments

The application is always responsible for allocating and freeing the APKeyInfoType and APVerifyInfoType structures. The application must call CPMLibReleaseKeyInfo() or CPMLibReleaseVerifyInfo(), as appropriate, before freeing the structure to allow the CPM and provider to clean up.

The application must call CPMLibVerifyFinal() to finalize the operation.

See Also

CPMLibVerify(), CPMLibVerifyFinal(), CPMLibVerifyUpdate(), CPMLibReleaseKeyInfo(), CPMLibReleaseVerifyInfo()

CPMLibVerifyUpdate Function ^TOP^

Purpose

Updates a multi-part verification operation with more data.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibVerifyUpdate (
   APKeyInfoType *keyInfoP,
   APVerifyInfoType *verifyInfoP,
   uint8_t *bufIn,
   uint32_t bufInLen
)

Parameters

keyInfoP
Pointer to an APKeyInfoType structure containing the key to be used for the operation.
verifyInfoP
Pointer to the APVerifyInfoType structure that was initialized during the call to CPMLibVerifyInit().
bufIn
Pointer to a buffer containing the data for the operation. This parameter must not be NULL.
bufInLen
The size, in bytes, of the buffer specified by bufIn. This value must be greater than zero.

Returns

errNone if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.

See Also

CPMLibVerifyFinal(), CPMLibVerifyInit()

CPMLibWake Function ^TOP^

Purpose

Allows the library to handle the device waking up.

Declared In

CPMLibARMInterface.h

Prototype

status_t CPMLibWake (
   void
)

Parameters

None.

Returns

errNone.

See Also

CPMLibClose(), CPMLibOpen(), CPMLibSleep()