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
CPMLibAddRandomSeed Function
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_tdataLen
)
Parameters
Returns
errNone
if the operation completed successfully, or one of the error codes listed under "CPM Library Error Codes" otherwise.
See Also
CPMLibClose Function
Purpose
Handles the closing of the CPM library.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibClose ( void )
Parameters
Returns
errNone
if the operation completed successfully, or one of the following otherwise:
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
Purpose
Performs the decryption operation in one pass.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibDecrypt ( APKeyInfoType*keyInfoP
, APCipherInfoType*cipherInfoP
, uint8_t*bufIn
, uint32_tbufInLen
, 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
Purpose
Finalizes a multi-part decryption operation.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibDecryptFinal ( APKeyInfoType*keyInfoP
, APCipherInfoType*cipherInfoP
, uint8_t*bufIn
, uint32_tbufInLen
, 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
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 toCPMLibDecryptUpdate()
andCPMLibDecryptFinal()
. -
↔ 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
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_tbufInLen
, 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
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 tokeyDataP
. If you setkeyDataP
toNULL
, 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
Purpose
Performs an encryption operation in one pass.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibEncrypt ( APKeyInfoType*keyInfoP
, APCipherInfoType*cipherInfoP
, uint8_t*bufIn
, uint32_tbufInLen
, 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
Purpose
Finalizes a multi-part encryption operation.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibEncryptFinal ( APKeyInfoType*keyInfoP
, APCipherInfoType*cipherInfoP
, uint8_t*bufIn
, uint32_tbufInLen
, 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
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 toCPMLibEncryptUpdate()
andCPMLibEncryptFinal()
. -
↔ 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
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_tbufInLen
, 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
Purpose
Enumerates the providers that the CPM library currently knows about.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibEnumerateProviders ( uint32_tproviderIDs[]
, 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
Purpose
Creates a storable instance of an APCipherInfoType
structure.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibExportCipherInfo ( APCipherInfoType*cipherInfoP
, uint8_tencoding
, 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
Purpose
Creates a storable instance of an APHashInfoType
structure.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibExportHashInfo ( APHashInfoType*hashInfoP
, uint8_tencoding
, 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
CPMLibExportKeyInfo Function
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_tencoding
, 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
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_tencoding
, 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
Purpose
Creates a storable instance of an APMACInfoType
structure.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibExportMACInfo ( APMACInfoType*macInfoP
, uint8_tencoding
, 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
Purpose
Creates a storable instance of an APSignInfoType
structure.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibExportSignInfo ( APSignInfoType*signInfoP
, uint8_tencoding
, 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
Purpose
Creates a storable instance of an APVerifyInfoType
structure.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibExportVerifyInfo ( APVerifyInfoType*verifyInfoP
, uint8_tencoding
, 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
Purpose
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibGenerateKey ( uint8_t*keyDataP
, uint32_tdataLen
, 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
Purpose
Generates a new public/private key pair.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibGenerateKeyPair ( uint8_t*keyDataP
, uint32_tdataLen
, 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
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 tobufferP
.
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
CPMLibGetInfo Function
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
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_tproviderID
, 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
Purpose
Performs the hashing operation in one pass.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibHash ( APHashEnumtype
, APHashInfoType*hashinfo
, uint8_t*bufIn
, uint32_tbufInLen
, 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
Purpose
Finalizes a multi-part hash operation.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibHashFinal ( APHashInfoType*hashinfo
, uint8_t*bufIn
, uint32_tbufInLen
, uint8_t*bufOut
, uint32_t*bufOutLenP
)
Parameters
-
→ hashinfo
- The context returned from the call to
CPMLibHashInit()
. This is anAPHashInfoType
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
.
See Also
CPMLibHashInit()
, CPMLibHashUpdate()
, CPMLibReleaseHashInfo()
CPMLibHashInit Function
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 theCPMLibHashUpdate()
andCPMLibHashFinal()
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
Purpose
Updates a multi-part hash operation with more data.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibHashUpdate ( APHashInfoType*hashinfo
, uint8_t*bufIn
, uint32_tbufInLen
)
Parameters
-
→ hashinfo
- The context returned from the call to
CPMLibHashInit()
. This is anAPHashInfoType
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
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_tencoding
, uint8_t*importDataP
, uint32_tdataLen
, 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
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_tencoding
, uint8_t*importDataP
, uint32_tdataLen
, 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
CPMLibImportKeyInfo Function
Purpose
Introduces an existing key to the CPM framework.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibImportKeyInfo ( uint8_tencoding
, uint8_t*importDataP
, uint32_tdataLen
, 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
Purpose
Introduces an existing public/private key pair to the CPM framework.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibImportKeyPairInfo ( uint8_tencoding
, uint8_t*importDataP
, uint32_tdataLen
, 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
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_tencoding
, uint8_t*importDataP
, uint32_tdataLen
, 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
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_tencoding
, uint8_t*importDataP
, uint32_tdataLen
, 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
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_tencoding
, uint8_t*importDataP
, uint32_tdataLen
, 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
Purpose
Performs the message authentication operation in one pass.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibMAC ( APKeyInfoType*keyInfoP
, APHashInfoType*hashInfoP
, APMACEnumtype
, APMACInfoType*macInfoP
, uint8_t*bufIn
, uint32_tbufInLen
, 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
Purpose
Finalizes a multi-part message authentication operation.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibMACFinal ( APMACInfoType*macInfoP
, uint8_t*bufIn
, uint32_tbufInLen
, uint8_t*bufOut
, uint32_t*bufOutLenP
)
Parameters
-
→ macInfoP
- Pointer to the
APMACInfoType
structure that was initialized during the call toCPMLibMACInit()
. -
→ 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
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 toCPMLibMACUpdate()
andCPMLibMACFinal()
. -
↔ hashInfoP
- Pointer to an
APHashInfoType
structure, allocated by the application, that holds information about the hashing operation for use in the subsequent calls toCPMLibMACUpdate()
andCPMLibMACFinal()
. -
↔ 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
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_tbufInLen
, uint8_t*bufOut
, uint32_t*bufOutLenP
)
Parameters
-
→ macInfoP
- Pointer to the
APMACInfoType
structure that was initialized during the call toCPMLibMACInit()
. -
→ 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
Purpose
Handles the open of the CPM library.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibOpen (
uint16_t *numProviders
)
Parameters
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
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
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
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
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
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
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
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
Purpose
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibSetDefaultProvider (
uint32_t providerID
)
Parameters
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
Purpose
Performs the signing operation in one pass.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibSign ( APKeyInfoType*keyInfoP
, APSignInfoType*signInfoP
, uint8_t*bufIn
, uint32_tbufInLen
, 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
Purpose
Finalizes a multi-part signing operation.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibSignFinal ( APKeyInfoType*keyInfoP
, APSignInfoType*signInfoP
, uint8_t*bufIn
, uint32_tbufInLen
, 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 toCPMLibSignInit()
. -
→ 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
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 toCPMLibSignUpdate()
andCPMLibSignFinal()
. -
← 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
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_tbufInLen
)
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 toCPMLibSignInit()
. -
→ 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
Purpose
Allows the library to handle the device going to sleep.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibSleep ( void )
Parameters
Returns
See Also
CPMLibClose()
, CPMLibOpen()
, CPMLibWake()
CPMLibVerify Function
Purpose
Performs the verify operation in one pass.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibVerify ( APKeyInfoType*keyInfoP
, APVerifyInfoType*verifyInfoP
, uint8_t*bufIn
, uint32_tbufInLen
, uint8_t*bufOut
, uint32_t*bufOutLenP
, uint8_t*signature
, uint32_tsignatureLen
, 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 theVerifyResultType
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
Purpose
Finalizes a multi-part verification operation.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibVerifyFinal ( APKeyInfoType*keyInfoP
, APVerifyInfoType*verifyInfoP
, uint8_t*bufIn
, uint32_tbufInLen
, uint8_t*bufOut
, uint32_t*bufOutLenP
, uint8_t*signature
, uint32_tsignatureLen
, 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 toCPMLibVerifyInit()
. -
→ 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 theVerifyResultType
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
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 toCPMLibVerifyUpdate()
andCPMLibVerifyFinal()
. -
← verifyInfoP
- Pointer to an
APVerifyInfoType
structure, allocated by the application, to be used in subsequent calls toCPMLibVerifyUpdate()
andCPMLibVerifyFinal()
.
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
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_tbufInLen
)
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 toCPMLibVerifyInit()
. -
→ 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
Purpose
Allows the library to handle the device waking up.
Declared In
CPMLibARMInterface.h
Prototype
status_t CPMLibWake ( void )
Parameters
Returns
See Also
CPMLibClose()
, CPMLibOpen()
, CPMLibSleep()