(68K) Cryptography Provider Manager | Palm OS® Programmer's API Reference

The Cryptography Provider Manager (CPM) is a shared library that acts as a framework for cryptographic services. These services are divided into two levels:

At the application level, the CPM provides an API that any application can use to perform cryptographic operations.
The operations themselves are not part of the CPM; instead, they're provided by an algorithm provider (or AP). To export its functionality to the CPM, an algorithm provider implements a set of callback functions. Third party developers can create and distribute their own APs. The Palm OS provides a default algorithm provider that's used in the absence of alternatives.

The CPM provides the glue between an application and an AP. In general, this glue is invisible: You don't need to know anything about the APs that are available to use their cryptographic services. This makes it possible for an application to use common cryptographic operations without having to be overly concerned with the exact implementation of these operations. It also relieves the algorithm providers from the duty of providing their own invocation API.

NOTE: In Palm OS Garnet, only the application level API is offered; the ability to create and install your own algorithm provider will be supported in a later release.

The Default Provider ^TOP^

In Palm OS Garnet, there is only one algorithm provider. Implemented by RSA, it provides three cryptographic services:

Data encryption and decryption using an RC4 symmetric key stream cipher
Message digest creation (hashing) using the SHA-1 algorithm.
Message verification through a combination of the two other operations.

All of the Palm OS Garnet cryptography operations are provided by RSA.

One of the features of the CPM library is that the developer doesn't need to know anything about cryptography. The functions are designed such that the default settings will yield satisfying results.

Fundamental CPM Functions ^TOP^

The fundamental cryptography functions are:

CPMLibEncrypt() performs a data encryption operation.
CPMLibDecrypt() performs a data decryption operation.
CPMLibHash() creates a message digest.
CPMLibVerify() verifies a message that has a signature and certificate.

These functions operate on blocks of data. For example, CPMLibEncrypt() takes a block of data (and a key), encrypts it, and hands back the encrypted data all in one go.

The CPM also provides sets of functions that let you perform these operations sequentially, allowing you to (for example) initialize an encryption "stream," iteratively feed data to the encryption algorithm, and then "finalize" the stream and get the encrypted data back. These functions are (for encryption) CPMLibEncryptInit(), CPMLibEncryptUpdate(), and CPMLibEncryptFinal().

Using the Crypto-Info Structures ^TOP^

The cryptography operations that are currently supported by the CPM library rely on four "crypto-info" data structures:

The APKeyInfoStruct describes a symmetric key,
APCipherInfoStruct describes an encryption/decryption operation.
APHashInfoStruct describes message digest creation.
APVerifyInfoStruct describes a message verification operation.

When you perform a cryptographic operation, you'll be asked for one or more of these structures. In most cases you can pass in an "empty" structure and the function will populate it for you. However, it's important that you zero the structure first.

For example, the CPMLibHash() function takes a APHashInfoStruct as an argument. To use the default hashing operations, simply allocate the structure, zero it, and pass it in:

APHashInfoType hashinfo; 
MemSet ((void *)&hashinfo, sizeof (APHashInfoType), 0); 
CPMLibHash( ..., &hashInfo, ...);

When you're done with a crypto-info structure, you must "release" it:

CPMLibReleaseHashInfo( ..., &hashInfo );

Using the Export Functions ^TOP^

The cryptography structures (key, hash, cipher, verification) can be "exported," or encoded into a form that can be cached. These operations are provided by the CPMLibExport...Info functions. Purposeful details of exporting (and importing, its functional complement) are given in the individual function descriptions, below. This little section touches on a wrinkle of usage.

When you use an export function, you're asked to supply a buffer that can accommodate the encoded data. This means that you have to know how big the encoded data will be; the export function itself tells you the size through its final (reference) argument. Thus, you have to call the export function twice: Once to get the buffer size, and then again to actually get the encoded data. This is demonstrated below:

UInt32 length=0; 
UInt8 *data=NULL; 
Err error; 
 
/* For demo purposes, we're only interested in the last two
 * arguments (the buffer and the buffer length). First, we
 * set the buffer to NULL, and retrieve the length.
 */ 
error = CPMLibExport... (... NULL, &length); 
 
/* At this pass, we expect the function to tell us that 
 * the buffer is too small. Any other return is treated 
 * as an error. Note that the <length> argument is reset to
 * to the required allocation length despite the error
 * return.
 */ 
if (error != cpmErrBufTooSmall) 
  return ...; // or whatever 
 
/* Allocate the buffer (for brevity, the example omits 
 * the error check). 
 */
data = MemPtrNew(length); 
 
/* Call the export function again to retrieve the 
 * encoded data.
 */
error = CPMLibExport... ( ... data, &length); 
 
/* This time we want a 'clean' return. */ 
if (error != errNone) { 
  // handle the error 
}

CPM and AP Constants ^TOP^

AP Capability Constants ^TOP^

The AP capability values are bitfield constants that represent the capabilities that an AP supports. The capability constants are OR'd into the flags field of the APProviderInfoStruct structure.

Declared in CPMLibCommon.h, the constants are:

APF_MP: Streaming operations (initialize/update/finalize) are supported ("MP" stands for "multiple part"). See "Fundamental CPM Functions" for details. Note that all APs are expected to support block operations.
APF_HW: The AP's algorithms are implemented in hardware (such as a SmartCard).
APF_KEYGEN: Symmetric key operations (including key info import and export) are supported.
APF_KEYPAIRGEN: Asymmetric key operations (including key info import and export) are supported.
APF_KEYDERIVE: Key derivation is supported.
APF_HASH: Hashing operations (including hash info import and export) are supported.
APF_CIPHER: Message encryption and decryption operations (including cipher info import and export) are supported.
APF_SIGN: Message signing operations (including sign info import and export) are supported.
APF_VERIFY: Message verification operations (including verify info import and export) are supported.

Block Encryption Mode Constants ^TOP^

Purpose

The constants listed below represent the various block encryption modes that may be supported by an AP. You can request a particular mode by setting the APCipherInfoStruct mode field before passing the structure to the CPMLibEncrypt() or CPMLibDecrypt() function. If you don't specify a mode, the AP will choose one for you, and reset the mode field to the chosen mode.

The APModeEnum data type is used to type the encryption mode constants.

Prototype

typedef UInt32 APModeEnum;

Note that encryption modes apply to block operations only. Specifying a mode for a stream encryption (through CPMLibEncryptInit() et al.) has no effect.

The constants (and the type) are declared in CPMLibConstants.h. The constants are:

Constants

apModeTypeUnspecified = 0: The mode isn't specified; the AP uses its default mode.
apModeTypeNone: The encryption mode doesn't apply.
apModeTypeECB: Electronic codebook mode.
apModeTypeCBC: Cipher block chaining mode.
apModeTypeCBC_CTS: Cipher block chaining with cipher text stealing.
apModeTypeCFB: Cipher feedback mode.
apModeTypeOFB: Output feedback mode.
apModeCounter: Counter mode

Cipher Algorithm Constants ^TOP^

Purpose

These constants represent the different cipher algorithms that an AP may support. The algorithm type is encoded in the type field of the APKeyInfoStruct structure. You can request a specific algorithm by setting the value of the type field before passing the structure to CPMLibGenerateKey(). If you don't care, leave the field zero'd (apAlgorithmTypeUnspecified); the function will set the field to tell you which algorithm was used.

In the APKeyInfoStruct structure, the constants are typed as APAlgorithmEnum:

Prototype

typedef UInt32 APAlgorithmEnum;

The constants (and the type) are defined in CPMLibCommon.h. There we see the usual "unspecified" constant:

apAlgorithmTypeUnspecified = 0: No algorithm specified; the AP will use its default.

The rest of the constants are divided into groups, below, and listed with very little additional explanation: The constants' names are reasonably self-documenting.

Block Cipher Algorithms

apSymmetricTypeDES apSymmetricTypeRC2 apSymmetricTypeRC4 apSymmetricTypeRC5 apSymmetricTypeRC6,apSymmetricTypeDESX_XDX3 ("Strong" DES)apSymmetricType3DES_EDE2 apSymmetricType3DES_EDE3 apSymmetricTypeIDEA apSymmetricTypeDiamond2 apSymmetricTypeBlowfish apSymmetricTypeTEA (Tiny Encryption Algorithm), apSymmetricTypeSAFER (Safe and Fast Encryption Routine),apSymmetricType3WAY apSymmetricTypeGOST (USSR Government Standard),
apSymmetricTypeSHARK apSymmetricTypeCAST128, apSymmetricTypeSquare,
apSymmetricTypeSkipjack

Stream Ciphers

apSymmetricTypePanama, apSymmetricTypeARC4,
apSymmetricTypeSEAL, apSymmetricTypeWAKE,
apSymmetricTypeSapphire, apSymmetricTypeBBS

AES Block Ciphers

apSymmetricTypeRijndael, apSymmetricTypeCAST256,
apSymmetricTypeTwofish, apSymmetricTypeMARS,
apSymmetricTypeSerpent

Asymmetric Key Ciphers

apAsymmetricTypeRSA, apAsymmetricTypeDSA,
apAsymmetricTypeElgamal,apAsymmetricTypeNR (Nyberg-Rueppel),
apAsymmetricTypeBlumGoldwasser,
apAsymmetricTypeRabin,apAsymmetricTypeRW (Rabin-Williams),
apAsymmetricTypeLUC, apAsymmetricTypeLUCELG,
apAsymmetricTypeECDSA, apAsymmetricTypeECNR,
apAsymmetricTypeECIES, apAsymmetricTypeECDHC,
apAsymmetricTypeECMQVC

Key Agreement Ciphers

apKeyAgreementTypeDH (Diffie-Hellman),
apKeyAgreementTypeDH2 (Unified Diffie-Hellman),
apKeyAgreementTypeMQV (Menezes-Qu-Vanstone),
apKeyAgreementTypeLUCDIF, apKeyAgreementTypeXTRDH

Export Encoding Constants ^TOP^

Constants that represent different data encoding schemes that are used to convert the crypto-info structs (APKeyInfoStruct, APHashInfoStruct, et al.) into a form that can be cached.

The encoding formats are used by the import and export functions, CPMLibImportKeyInfo(), CPMLibExportKeyInfo(), CPMLibImportHashInfo(), CPMLibExportHashInfo(), CPMLibImportVerifyInfo(), CPMLibExportVerifyInfo(), CPMLibImportCipherInfo(), and CPMLibExportCipherInfo().

Declared in CPMLibCommon.h, the constants are:

IMPORT_EXPORT_TYPE_RAW: The default encoding, as defined by the AP.
IMPORT_EXPORT_TYPE_DER: ASN.1 DER encoding.
IMPORT_EXPORT_TYPE_XML: Standardized XML encoding.

Hashing Algorithm Constants ^TOP^

The hashing constants represent various hashing algorithms. If you want to tell the AP to use a specific algorithm in a hashing operation, you would pass one of these constants as an argument to CPMLibHash() or CPMLibHashInit(). If you want the default, use apHashTypeUnspecified, The algorithm that's actually used is returned through a APHashInfoStruct structure.

Declared in CPMLibCommon.h, the constants are:

apHashTypeUnspecified = 0: Unspecified hash algorithm; when generating a message digest, the AP decides which algorithm to use.
apHashTypeNone: Don't hash. Use this constant if you want the AP to suppress hashing in an operation, such as verification, that normally performs it
apHashTypeMD2: Rivest Message Digest 2 (MD2)
apHashTypeMD5: Rivest Message Digest 5 (MD5)
apHashTypeSHA1: Secure Hash Algorithm-160 (SHA-1)
apHashTypeSHA256: SHA 256-bit algorithm
apHashTypeSHA384: SHA 384-bit algorithm
apHashTypeSHA512: SHA 512-bit algorithm
apHashTypeHAVAL: HAVAL one-way algorithm
apHashTypeRIPEMD160: RIPEMD 160-bit
apHashTypeTiger: Tiger algorithm
apHashTypePanama: PANAMA algorithm

Key Class Constants ^TOP^

Purpose

A key's "class" specifies whether the key is symmetric or asymmetric and, if the latter, whether it's public or private. The key class constants represent these qualities. Key class is encoded in the keyclass field of the APKeyInfoStruct structure.

In the struct, the constants are typed as APKeyClassEnum:

Prototype

typedef UInt32 APKeyClassEnum;

The constants (and the type) are defined in CPMLibCommon.h. The constants are:

Constants

apKeyClassUnspecified = 0: The key's class is unspecified.
apKeyClassSymmetric: This is a symmetric key.
apKeyClassPublic: This is the public part of an asymmetric key.
apKeyClassPrivate: This is the private part of an asymmetric key.

Key Usage Constants ^TOP^

Purpose

NOTE: The key usage constants are currently unused.

The key usage constants describe the different ways that an encryption key can be used. How a key is used is encoded in the usage field of the key's APKeyInfoStruct structure.

Note that the key usage values are mutually exclusive; you can't OR a set of key usage constants to create a "selectively talented" key. The apKeyUsageAll constant is the only "multi-purpose" value currently provided.

The APKeyUsageEnum data type is used to type the key usage constants:

Prototype

typedef UInt32 APKeyUsageEnum;

The constants (and the type) are defined in CPMLibConstants.h. The constants are:

Constants

apKeyUsageUnspecified = 0: The key's usage is unspecified.
apKeyUsageAll: The key can be used in any operation.
apKeyUsageCertificateSigning: The key is intended for certificate signing.
apKeyUsageSigning: The key is intended for message signing operations.
apKeyUsageEncryption: The key is intended for key or data encryption operations.
apKeyUsageKeyEncrypting: The key is intended for key encryption operations
apKeyUsageDataEncrypting: The key is intended for data encryption operations.
apKeyUsageMessageIntegrity: The key is intended for message verification operations.

Plaintext Padding Constants ^TOP^

Purpose

The plaintext padding constants describe the different ways that plaintext is padded before it's encrypted. The padding type is encoded in the padding field of an APCipherInfoStruct structure.

The APPaddingEnum data type is used to type the padding constants:

Prototype

typedef UInt32 APPaddingEnum;

The constants (and the type) are declared in CPMLibCommon.h. The constants are:

Constants

apPaddingTypeUnspecified = 0: The padding is unspecified; the AP will use the default
apPaddingTypeNone: Specifically request that padding not be applied.
apPaddingTypePKCS1Type1: Public Key Cryptography Standard 1, type 1
apPaddingTypePKCS1Type2: Public Key Cryptography Standard 1, type 2
apPaddingTypePKCS5: Public Key Cryptography Standard 5
apPaddingTypeOAEP: Optimal Asymmetric Encryption Padding
apPaddingTypeSSLv23: Secure Sockets Layer version 23

CPM Error Codes ^TOP^

The table below lists and explains the error codes that are returned by the CPM functions.

cpmErrAlreadyOpen: Returned by CPMLibOpen() to indicate that the CPM library has already been opened by your application. The open library remains open.
cpmErrNotOpen: All CPM functions (except CPMLibOpen()) expect the CPM library to be open. This code is returned if the library isn't open. To open the library, call CPMLibOpen().
cpmErrStillOpen: Returned by CPMLibClose() if the function was unable to close the library.
cpmErrNoProviders: Returned by CPMLibOpen() if the function was uable to locate (or load) any crytography providers. Without a cryptography provider, none of the other CPM functions will work.
cpmErrNoBaseProvider: Returned by CPMLibOpen() if the function was uable to locate (or load) the default cryptography provider. (Note that this means that at least one non-default provider was found. If no providers were found, the function would have returned cpmErrNoProviders).
cpmErrProviderNotFound: Returned by CPMLibGenerateKey(), CPMLibEncryt(), CPMLibDecrypt() and other algorithm-dependent functions if the requested provider couldn't be found.
cpmErrParamErr: Returned by a number of CPM functions when an argument is invalid (a pointer that points to an unallocated structure; a structure field that isn't properly set, and so on).
cpmErrOutOfMemory: Returned by CPMLibOpen() if the memory for a new library handle (and the structures it represents) couldn't be allocated
cpmErrBufTooSmall: Returned by CPMLibExportKey() and CPMLibExportContext() functions if the storage buffer (allocated by the caller) isn't big enough to accommodate the key or context.
cpmErrBadData: Returned by algorithm functions (CPMLibEncrypt...(), CPMLibDecrypt...(), etc.) when the key or other required data is invalid.
cpmErrUnimplemented: Returned by functions that aren't curently implemented.
cpmErrUnsupported: Returned by functions that aren't currently supported.
cpmErrNoGlobals: Returned by functions that access global CPM data—functions such as CPMLibEnumerateProviders() and CPMLibGetProviderInfo()—when that data doesn't exist.
cpmErrKeyExists: Returned by CPMLibImportKey() when the key you're trying to import already exists.
cpmErrKeyNotFound: Returned by CPMLibExportKey() when the key you're trying to export doesn't exists.

CPM and AP Structures and Data Types ^TOP^

APCipherInfoStruct Struct ^TOP^

Purpose

The APCipherInfoStruct encapsulates information about an instance of a data encryption or decryption operation. The structure is populated and returned by the data encryption and decryption functions (CPMLibEncrypt(), CPMLibDecrypt(), CPMLibEncryptInit(), and CPMLibDecryptInit()). You can set some of the fields' values yourself (before calling an encryption/decryption function) to fine-tune the impending operation.

You're responsible for allocating and freeing the APCipherInfoStructs that you need—the CPM never allocates them for you. The APCipherInfoStructs that you create (and actually use) must be released through CPMLibReleaseCipherInfo() before they're freed.

For more information (including examples) on how to use a crypto-info structure, see "Using the Crypto-Info Structures."

Declared in CPMLibCommon.h, the structure looks like this:

Prototype

struct APCipherInfoStruct {
   APProviderContextType  providerContext;
   APAlgorithmEnum  type;
   APPaddingEnum  padding;
   UInt8  *iv;
   UInt32  ivLength;
   void  *algorithmParams;
};

Fields

providerContext: Information about the AP that performed (or is requested to perform) the operation. See APProviderContextStruct.
type: Constant that represents the cipher algorithm that was used or that's requested. See Cipher Algorithm Constants
padding: Constant that represents the plaintext padding scheme used by the algorithm. See Plaintext Padding Constants.
iv: Initialization vector.
ivLength: The length of the initialization vector, in bytes.
algorithmParams: Additional data that's fed to the algorithm, as specified by the AP.

APHashInfoStruct Struct ^TOP^

Purpose

The APHashInfoStruct contains information about an instance of a message digest operation. You allocate the structure yourself, zero its contents, set the fields that you're interested in (if any), and then pass it as an argument to the message digest functions (CPMLibHash(), CPMLibHashInit(), CPMLibExportHashInfo(), and so on). When you're finished with the struct, you pass it to CPMLibReleaseHashInfo().

For more information (including examples) on how to use the structure, see "Using the Crypto-Info Structures."

Declared in CPMLibCommon.h, the structure looks like this:

Prototype

struct APHashInfoStruct {
  APProviderContextType  providerContext;
  APHashEnum  type;  
  UInt32  length; 
};

Fields

providerContext: Information about the AP that performed (or is requested to perform) the operation. See APProviderContextStruct.
type: The hashing algorithm that was used to create (or is requested to create) the message digest.
length: The length of the digest.

Comments

The APHashInfoStruct is one of the crypto-info structures; it's used as an input/output argument to the message digest functions (CPMLibHash(), CPMLibHashInit(), CPMLibExportHashInfo(), and so on). You allocate the structure yourself; before passing the struct to a function, you must zero its contents. When you're finished with the struct, you pass it to CPMLibReleaseHashInfo(). For more information on how to use a crypto-info structure, see "Using the Crypto-Info Structures."

APKeyInfoStruct Struct ^TOP^

Purpose

The APKeyInfoStruct holds information about an encrytion key.

Prototype

struct APKeyInfoStruct {
  APProviderContextType  providerContext; 
  APAlgorithmEnum  type;
  APKeyUsageEnum  usage;
  APKeyClassEnum  keyclass; 
  UInt32  length;
  UInt32  actualLength; 
  UInt16  exportable; 
  UInt16  ephemeral;   
};

Fields

providerID: Algorithm provider ID number.
type: A code that identifies the type of algorithm, one of the Cipher Algorithm Constants values.
usage: A code that identifies how the algorithm is used, one of the Key Usage Constants values.
keyLength: Length of the key data, in bytes and padded to the next largest word. (Default is 8.)
keyActualLength: The actual, unpadded length of the key data. (Default is 7).
exportable: Can this key be used in a CPMExportKey() call?. 1 if it can, 0 if it can't.
ephemeral: Is this a "one-shot" key? 1 if it is, 0 if it's permanent..

APProviderContextStruct Struct ^TOP^

Purpose

The APProviderContextStruct contains information about an instance of a cryptographic operation. The structure is contained (as an APProviderContextType value) in the four crypto-info structs, APKeyInfoStruct, APHashInfoStruct, APCipherInfoStruct, and APVerifyInfoStruct.

Declared in CPMLibCommon.h, the structure looks like this:

Prototype

struct APProviderContextStruct {
  UInt32  providerID;
  void  *localContext;   
};

Fields

providerID: Integer that uniquely identifies the provider that's being used in the operation.
localContext: Provider-specific information about the operation.

APProviderInfoStruct Struct ^TOP^

Purpose

The APProviderInfoStruct contains information about a specific algorithm provider. The structure is returned (as an APProviderInfoType) by CPMLibGetProviderInfo().

Declared in CPMLibCommon.h, the structure looks like this:

Prototype

struct APProviderInfoStruct {
  char  name[32];
  char  other[64];
  UInt32  flags;
  UInt8  numAlgorithms; 
  Boolean  bHardware; 
};

Fields

name: The human-readable name of the provider.
other: Additional textual information.
flags: A bitfield that publishes the functionality that this provider supports. See AP Capability Constants for a list of values that this field can combine.
numAlgorithms: A count of the algorithms this provider supplies.
bHardware: true if the provider's algorithms are implemented in hardware; false if in software.

APVerifyInfoStruct Struct ^TOP^

Purpose

The APVerifyInfoStruct is used by the verification functions (CPMLibVerify(), et al.) to verify a message. It contains (primarily) the hash operation and cipher operation information that will be used during verification. It's the caller's responsibility to allocate and embed the structure's APHashInfoStruct and APCipherInfoStruct fields before passing the APVerifyInfoStruct to a verification function.

Any APVerifyInfoStructs that you actually use must be released through CPMLibReleaseVerifyInfo() before it's freed. The embedded structures must also be released through CPMLibReleaseCipherInfo() and CPMLibReleaseHashInfo().

For more information (including examples) on how to use a crypto-info structure, see "Using the Crypto-Info Structures."

Declared in CPMLibCommon.h, the structure looks like this:

Prototype

struct APVerifyInfoStruct {
  APProviderContextType  providerContext;
  APHashInfoType  *hashInfoP;    
  APCipherInfoType  *cipherInfoP; 
}

Fields

providerContext: Information about the AP that performed (or is requested to perform) the operation. See APProviderContextStruct.
hashInfoP: APHashInfoStruct that contains the certificate's hash information.
cipherInfoP: APCipherInfoStruct that contains the certificate's cipher information.

CPMInfoStruct Struct ^TOP^

Purpose

Structure that provides information about the CPM library. It's used by the CPMLibGetInfo() function.

Prototype

typedef struct CPMInfoStruct {
  UInt8  numInstances; 
  UInt8   numProviders; 
  Boolean  defaultProviderPresent;
};

Fields

numInstances: The number of clients (applications) that are talking to this library.
numProviders: The number of algorithm providers that this library knows about.
defaultProviderPresent: Does the library contain a default provider? true if it does, otherwise false.

CPM Functions ^TOP^

CPMLibDecrypt Function ^TOP^

Purpose

Decrypts a block of encrypted data.

Declared In

CPMLib68kInterface.h, CPMLibARMInterface.h

Prototype

Err CPMLibDecrypt (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APCipherInfoType *cipherInfo,
   UInt8 *inBuffer,
   UInt32 inBufferLength,
   UInt8 *outBuffer,
   UInt32 *outBufferLength 
)

Parameters

→ libRef: (68k only) CPM Library reference number.
→ keyInfo: APKeyInfoStruct that contains the key that was used to encrypt the data. You obtain the structure by importing the APKeyInfoStruct that was exported by the data encryptor.
↔ cipherInfo: A pointer to an APCipherInfoStruct that describes the parameters that will be used in the decryption operation. You typically retrieve the structure by importing the APCipherInfoStruct that was exported by the data encryptor. If you're using the decryption defaults provided by the CPM library, you can pass in a freshly allocated (and zero'd) APCipherInfoStruct; in this case, the structure will be populated by this function to reflect the actual decryption parameters.
→ inBuffer: A pointer to the (encrypted) data that you want to decrypt.
→ inBufferLength: Length, in bytes, of inBuffer.
← outBuffer: A pointer to the buffer into which the decrypted data will be copied. The buffer must be allocated by the caller, and must be big enough to accommodate all of the decrypted data.
↔ outBufferLength: You pass in the (allocated) length of outBuffer, in bytes. The function resets the argument to the amount of data that was actually copied into outBuffer. If the function returns cpmErrBufTooSmall, outBufferLength is set to the minimum buffer size that's needed to accommodate the decrypted data..

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This functions peforms block decryption. For stream decryption, see CPMLibDecryptInit().

The keyInfo and cipherInfo must agree on the algorithm type, as specified in their respective APAlgorithmEnum fields.

If outBuffer isn't big enough, the function will fail and outBufferLength will return the "correct" output buffer size (i.e. large enough to accommodate the encrypted data) . When this happens, simply reallocate the output buffer and call CPMLibDecrypt again.

CPMLibDecryptFinal Function ^TOP^

Purpose

Finalizes a stream decryption operation.

Declared In

CPMLib68kInterface.h, CPMLibARMInterface.h

Prototype

Err CPMLibDecryptFinal (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APCipherInfoType *cipherInfo,
   UInt8 *inBuffer,
   UInt32 inBufferLength,
   UInt8 *outBuffer,
   UInt32 *outBufferLength
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ keyInfo: Key used to decrypt the data, as returned by CPMLibGenerateKey() or CPMLibImportKeyInfo().
→ cipherInfo: A pointer to the APCipherInfoStruct that was returned by the stream-initializing CPMLibDecryptInit() call.
→ inBuffer: A pointer to the data that you want to encrypt. If you already supplied all the data through previous CPMLibDecryptUpdate() calls, pass NULL.
→ inBufferLength: The length of inBuffer, in bytes. If inBuffer is NULL, pass 0.
← outBuffer: A pointer to the buffer where the decrypted inBuffer data will be copied. The buffer must be allocated by the caller, and must be big enough to accommodate all of the decrypted data.
↔ outBufferLength: You pass in the (allocated) length of outBuffer, in bytes. The function resets the argument to the amount of data that was actually copied into outBuffer. If the function returns cpmErrBufTooSmall, outBufferLength is set to the minimum buffer size that's needed to accommodate the decrypted inBuffer data..

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function (optionally) decrypts a final buffer of data and then closes the decryption stream that was initialized by CPMLibDecryptInit().

Note that outBuffer contains the decrypted inBuffer data only—it doesn't contain all the data that was decrypted by this stream. It's the callers responsibility to accumulate the data that was decrypted by previous, successive CPMLibDecryptUpdate() calls.

CPMLibDecryptInit Function ^TOP^

Purpose

Initializes a stream decryption session.

Declared In

CPMLib68kInterface.h, CPMLibARMInterface.h

Prototype

Err CPMLibDecryptInit (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APCipherInfoType *cipherInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ keyInfo: APKeyInfoStruct that contains the key that was used to encrypt the data. You obtain the structure by importing the APKeyInfoStruct that was exported by the data encryptor.
↔ cipherInfo: A pointer to an APCipherInfoStruct that describes the parameters that will be used in the decryption operation. You typically retrieve the structure by importing the APCipherInfoStruct that was exported by the data encryptor. If you're using the decryption defaults provided by the CPM library, you can pass in a freshly allocated (and zero'd) APCipherInfoStruct; in this case, the structure will be populated by this function to reflect the actual decryption parameters.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function initializes a stream decryption operation. To feed data to the operation, you call CPMLibDecryptUpdate() followed by CPMLibDecryptFinal(). The "update" function is optional; the "final" function is mandatory. For block encryption, see CPMLibDecrypt().

The keyInfo and cipherInfo must agree on the algorithm type, as specified in their respective APAlgorithmEnum fields.

CPMLibDecryptUpdate Function ^TOP^

Purpose

Feeds data to a stream decryption operation.

Declared In

CPMLib68kInterface.h, CPMLibARMInterface.h

Prototype

Err CPMLibDecryptUpdate (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APCipherInfoType *cipherInfo,
   UInt8 *inBuffer,
   UInt32 inBufferLength,
   UInt8 *outBuffer,
   UInt32 *outBufferLength
)

Parameters

see CPMLibEncryptFinal()

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function feeds data into the stream decryption session that was started by CPMLibDecryptInit(). You can make any number of CPMLibDecryptUpdate calls while the stream is open. When you've finished feeding data into the stream, you call CPMLibDecryptFinal().

This function's arguments, return values, and behavior are nearly identical to CPMLibDecryptFinal() (which see for details). The only difference between them is that this function leaves the stream open, and CPMLibDecryptFinal() closes it.

CPMLibEncrypt Function ^TOP^

Purpose

Encrypts a block of data.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibEncrypt (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APCipherInfoType *cipherInfo,
   UInt8 *inBuffer,
   UInt32 inBufferLength,
   UInt8 *outBuffer,
   UInt32 *outBufferLength
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ keyInfo: A pointer to an APKeyInfoStruct that represents the key that will be used to encrypt the data. The allocate the structure, zero it, and then populate it by calling CPMLibGenerateKey() or CPMLibImportKeyInfo().
→ cipherInfo: A pointer to an APCipherInfoStruct that you can use to set the parameters of the encryption operation. If the CPM can't satisfy the requirements you specify in the structure, the operation will fail. If you want to use the default cipher settings, pass in a zero'd structure. When the function returns, the structure will be filled with information describing the operation.
→ inBuffer: A pointer to the data that you want to encrypt.
→ inBufferLength: The length of inBuffer, in bytes.
← outBuffer: A pointer to the buffer where the encrypted data will be copied. The buffer must be allocated by the caller, and must be big enough to accommodate all of the encrypted data.
↔ outBufferLength: You pass in the (allocated) length of outBuffer, in bytes. The function resets the argument to the amount of data that was actually copied into outBuffer. If the function returns cpmErrBufTooSmall, outBufferLength is set to the minimum buffer size that's needed to accommodate the encrypted data.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This functions peforms block encryption. For stream encryption, see CPMLibEncryptInit().

The keyInfo and cipherInfo must agree on the algorithm type, as specified in their respective APAlgorithmEnum fields.

After you've encrypted the data, you must export the keyInfo and cipherInfo structures (see CPMLibExportKeyInfo() and CPMLibExportCipherInfo()) so they can be imported, later, by the data decryptor. Secure storage and transmission of the encryption key is th caller's responsibility.

To decrypt encrypted data, you call CPMLibDecrypt() or CPMLibDecryptInit().

CPMLibEncryptFinal Function ^TOP^

Purpose

Finalizes a stream encryption operation.

Declared In

CPMLib68kInterface.h, CPMLibARMInterface.h

Prototype

Err CPMLibEncryptFinal (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APCipherInfoType *cipherInfo,
   UInt8 *inBuffer,
   UInt32 inBufferLength,
   UInt8 *outBuffer,
   UInt32 *outBufferLength
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ keyInfo: Key used to encrypt the data, as returned by CPMLibGenerateKey() or CPMLibImportKeyInfo().
→ cipherInfo: A pointer to the APCipherInfoStruct that was returned in the stream-initializing CPMLibEncryptInit() call.
→ inBuffer: A pointer to the data that you want to encrypt. If you already supplied all the data through previous CPMLibEncryptUpdate() calls, pass NULL.
→ inBufferLength: The length of inBuffer, in bytes. If inBuffer is NULL, pass 0.
← outBuffer: A pointer to the buffer where the encrypted inBuffer data will be copied. The buffer must be allocated by the caller, and must be big enough to accommodate the encrypted inBuffer data.
↔ outBufferLength: You pass in the (allocated) length of outBuffer, in bytes. The function resets the argument to the amount of data that was actually copied into outBuffer. If the function returns cpmErrBufTooSmall, outBufferLength is set to the minimum buffer size that's needed to accommodate the encrypted data.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function (optionally) encrypts a final buffer of data and then closes the encryption stream that was initialized by CPMLibEncryptInit().

After you've encrypted the data, you should export the keyInfo and cipherInfo structures (see CPMLibExportKeyInfo() and CPMLibExportCipherInfo()) so they can be imported, later, by the data decryptor. Secure storage and transmission of the encryption key is the caller's responsibility.

Note that outBuffer contains the encrypted inBuffer data only—it doesn't contain all the data that was encrypted by this stream. It's the callers responsibility to accumulate the data that was encrypted by previous, successive CPMLibEncryptUpdate() calls.

To decrypt encrypted data, you call CPMLibDecrypt() or CPMLibDecryptInit().

CPMLibEncryptInit Function ^TOP^

Purpose

Initializes a stream encryption session.

Declared In

CPMLib68kInterface.h, CPMLibARMInterface.h

Prototype

Err CPMLibEncryptInit (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APCipherInfoType *cipherInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ keyInfo: Key used to encrypt the data, as returned by CPMLibGenerateKey() or CPMLibImportKeyInfo().
→ cipherInfo: A pointer to an APCipherInfoStruct that you can use to set the parameters of the encryption operation. If the CPM can't satisfy the requirements you specify in the structure, the operation will fail. If you want to use the default cipher settings, pass in a zero'd structure. When the function returns, the structure will be filled with information describing the operation. The structure is used as a cookie in the subsequent CPMLibEncryptUpdate() and/or CPMLibEncryptFinal() functions.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function initializes a stream encryption operation. To feed data to the operation, you call CPMLibEncryptUpdate() followed by CPMLibEncryptFinal(). The "update" function is optional; the "final" function is mandatory. For block encryption, see CPMLibEncrypt().

The keyInfo and cipherInfo must agree on the algorithm type, as specified in their respective APAlgorithmEnum fields.

To decrypt encrypted data, you call CPMLibDecrypt() or CPMLibDecryptInit().

CPMLibEncryptUpdate Function ^TOP^

Purpose

Feeds data to a stream encryption operation.

Declared In

CPMLib68kInterface.h, CPMLibARMInterface.h

Prototype

Err CPMLibEncryptUpdate (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APCipherInfoType *cipherInfo,
   UInt8 *inBuffer,
   UInt32 inBufferLength,
   UInt8 *outBuffer,
   UInt32 *outBufferLength
)

Parameters

see CPMLibEncryptFinal()

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function feeds data into the stream encryption session that was started by CPMLibEncryptInit(). You can make any number of CPMLibEncryptUpdate calls while the encryption stream is open. When you've finished feeding data into the stream, you call CPMLibEncryptFinal().

This function's arguments, return values, and behavior are nearly identical to CPMLibEncryptFinal() (which see for details). The only difference between them is that this function leaves the stream open, and CPMLibEncryptFinal() closes it.

CPMLibExportCipherInfo Function ^TOP^

Purpose

Encodes a cipher into a form that can be cached. To reconstitute an exported cipher, pass it to CPMLibImportCipherInfo().

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibExportCipherInfo (
    UInt16 libRef,
   APCipherInfoType *cipherInfo,
   UInt8 encoding,
   UInt8 *exportBuffer,
   UInt32 exportBufferLength 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ cipherInfo: Structure that represents the cipher that you want to export, as created and returned by CPMLibGenerateKey(), or as imported through CPMLibImportKeyInfo().
→ encoding: Constant that specifies the type of encoding. One of IMPORT_EXPORT_RAW, IMPORT_EXPORT_DER, or IMPORT_EXPORT_XML. See Export Encoding Constants for details about these formats.
↔ exportBuffer: Buffer into which the function copies the encoded data. The buffer must be allocated by the caller. Point this argument to NULL if you're using the function to retrieve the size of the encoded data.
↔ exportBufferLength: You pass in the size of exportBuffer in bytes. The function returns (through this argument) the size that's required to accommodate the encoded data.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

You call this function twice: Once to get the size of the required exportBuffer, and then again (after allocating the buffer) to get the encoded buffer. See "Using the Export Functions" for more information and a free sample.

CPMLibExportHashInfo Function ^TOP^

Purpose

Encodes an APHashInfoStruct into a form that can be cached. To reconstitute an exported hash info, pass it to CPMLibImportHashInfo().

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibExportKeyInfo (
    UInt16 libRef,
   APHashInfoType *hashInfo,
   UInt8 encoding,
   UInt8 *exportBuffer,
   UInt32 exportBufferLength 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ hashInfo: Structure that you want to export.
→ encoding: Constant that specifies the type of encoding. One of IMPORT_EXPORT_RAW, IMPORT_EXPORT_DER, or IMPORT_EXPORT_XML. See Export Encoding Constants for details about these formats.
↔ exportBuffer: Buffer into which the function copies the encoded data. The buffer must be allocated by the caller. Point this argument to NULL if you're using the function to retrieve the size of the encoded data (see below
↔ exportBufferLength: You pass in the size of exportBuffer in bytes; the function returns (through this argument) the size that's required to accommodate the encoded data.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

You call this function twice: Once to get the size of the export buffer, and then again (after allocating the buffer) to retrieve the encoded data. See "Using the Export Functions" for more information and a free sample.

CPMLibExportKeyInfo Function ^TOP^

Purpose

Encodes a APKeyInfoStruct into a form that can be cached. To reconstitute an exported key, pass it to CPMLibImportKeyInfo().

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibExportKeyInfo (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   UInt8 encoding,
   UInt8 *exportBuffer,
   UInt32 exportBufferLength 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ keyInfo: Structure that you want to export.
→ encoding: Constant that specifies the type of encoding. One of IMPORT_EXPORT_RAW, IMPORT_EXPORT_DER, or IMPORT_EXPORT_XML. See Export Encoding Constants for details about these formats.
↔ exportBuffer: Buffer into which the function copies the encoded data. The buffer must be allocated by the caller. Point this argument to NULL if you're using the function to retrieve the size of the encoded data (see below
↔ exportBufferLength: You pass in the size of exportBuffer in bytes; the function returns (through this argument) the size that's required to accommodate the encoded data.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

CPMLibExportVerifyInfo Function ^TOP^

Purpose

Encodes a APVerifyInfoStruct into a form that can be cached. To reconstitute an exported key, pass it to CPMLibImportVerifyInfo().

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibExportKeyInfo (
    UInt16 libRef,
   APVerifyInfoType *verifyInfo,
   UInt8 encoding,
   UInt8 *exportBuffer,
   UInt32 exportBufferLength 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ keyInfo: Structure that you want to export.
→ encoding: Constant that specifies the type of encoding. One of IMPORT_EXPORT_RAW, IMPORT_EXPORT_DER, or IMPORT_EXPORT_XML. See Export Encoding Constants for details about these formats.
↔ exportBuffer: Buffer into which the function copies the encoded data. The buffer must be allocated by the caller. Point this argument to NULL if you're using the function to retrieve the size of the encoded data (see below
↔ exportBufferLength: You pass in the size of exportBuffer in bytes; the function returns (through this argument) the size that's required to accommodate the encoded data.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

CPMLibGenerateKey Function ^TOP^

Purpose

Generates a new symmetric key.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibGenerateKey (
    UInt16 libRef,
   UInt8 *seedData,
   UInt32 seedLength,
   APKeyInfoType *keyInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ seedData: Optional data that's used to seed the key generator. Because PalmOS Garnet doesn't currently support key "derivation" (identical key generation based on identical seeds) the seed data is, in essence, a no-op, and can be a pointer to 0. However, you may want to supply (and cache) unique seed data today in anticipation of tomorrow's derivation functionality.
→ seedLength: Length of seedData, in bytes. (Pass 0 if *seedData is 0.)
↔ keyInfo: A pointer to a APKeyInfoStruct that will contain the generated key. The keyInfo structure is allocated and owned by the caller. You can specify the desired provider, key-generation scheme, and so on, by setting the APKeyInfoType fields. Or, to retrieve a default key, zero the structure before you pass it in.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

The APKeyInfoStruct that's populated by this function can be used in subsequent encryption, decryption, and verification operations.

When you're finished using the APKeyInfoStruct, you must release it through CPMLibReleaseKeyInfo().

CPMLibGetInfo Function ^TOP^

Purpose

Retrieves information about the CPM library.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibLibGetInfo (
    UInt16 libRef,
   CPMInfoType *info
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ info: Pointer to a CPMInfoStruct that returns the information about the library. See CPMInfoStruct for a description.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

CPMLibGetProviderInfo Function ^TOP^

Purpose

Retrieves information about a specific provider.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibGetProviderInfo (
    UInt16 libRef,
   UInt32 providerID,
   APProviderInfoType *providerInfo
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ providerID: ID number that identifies the provider.
← providerInfo: Structure into which the function places provider information. The structure is allocated and freed by the caller. The function doesn't clear inapplicable fields on the way out.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

CPMLibHash Function ^TOP^

Purpose

Hashes a block of data.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibHash (
    UInt16 libRef,
   APHashEnum type,
   APHashInfoType *hashInfo,
   UInt8 *inBuffer,
   UInt32 inBufferLength,
   UInt8 *outBuffer,
   UInt32 *outBufferLength 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ type: A constant that represents the hashing algorithm that will be used to create the message digest. See Hashing Algorithm Constants for a list of constants. If you want the default algorithm, use apHashTypeUnspecified.
→ hashInfo: A pointer to an APHashInfoStruct that you can use to set the parameters of the hashing operation. If the CPM can't satisfy the requirements you specify in the structure, the operation will fail. If you want to use the default settings, pass in a zero'd structure. When the function returns, the structure will be filled with information describing the operation.
→ inBuffer: A pointer to the data that you want to hash.
→ inBufferLength: The length of inBuffer, in bytes. If inBuffer is NULL, pass 0.
← outBuffer: A pointer to the buffer where the hashed inBuffer data will be copied. The buffer must be allocated by the caller, and must be big enough to accommodate all of the hashed data.
↔ outBufferLength: You pass in the (allocated) length of outBuffer, in bytes. The function resets the argument to the amount of data that was actually copied into outBuffer. If the function returns cpmErrBufTooSmall, outBufferLength is set to the minimum buffer size that's needed to accommodate the hashed data..

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function performs a block hash operation. For stream hashing, use CPMLibHashInit().

CPMLibHashFinal Function ^TOP^

Purpose

Finalizes a hash session and returns the hashed data.

Declared In

CPMLib.h

Prototype

Err CPMLibHashFinal (
    UInt16 libRef,
   APHashInfoType *hashInfo,
   UInt8 *inBuffer,
   UInt32 inBufferLength,
   UInt8 *outBuffer,
   UInt32 *outBufferLength 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ hashInfo: A pointer to the APHashInfoStruct that was returned by CPMLibHashInit().
→ inBuffer: A pointer to the data that you want to hash. If you already supplied all the data through previous CPMLibHashUpdate() calls, pass NULL.
→ inBufferLength: The length of inBuffer, in bytes. If inBuffer is NULL, pass 0.
← outBuffer: A pointer to the buffer where all the data that has been hashed by this stream will be copied. The buffer must be allocated by the caller, and must be big enough to accommodate all of the hashed data.
↔ outBufferLength: You pass in the (allocated) length of outBuffer, in bytes. The function resets the argument to the amount of data that was actually copied into outBuffer. If the function returns cpmErrBufTooSmall, outBufferLength is set to the minimum buffer size that's needed to accommodate the hashed data.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function returns all the data that was hashed by the hash stream, and then closes the stream. It follows an initial call to CPMLibHashInit() and some number of calls to CPMLibHashUpdate().

CPMLibHashInit Function ^TOP^

Purpose

Initiates a streaming hash operation.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibHash (
    UInt16 libRef,
   APHashInfoType *hashInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ hashInfo: A pointer to an APHashInfoStruct that you can use to set the parameters of the hash operation. If the CPM can't satisfy the requirements you specify in the structure, the operation will fail. If you want to use the default settings, pass in a zero'd structure. When the function returns, the structure will be filled with information describing the operation.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function initializes a streaming hash operation. To feed data to the stream, you call CPMLibHashUpdate() followed by CPMLibHashFinal(). The "update" function is optional; the "final" function is mandatory. For a block hash, see CPMLibHash().

CPMLibHashUpdate Function ^TOP^

Purpose

Sends data to streaming hash operation.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibHashUpdate (
    UInt16 libRef,
   APHashInfoType *hashInfo,
   UInt8 *inBuffer,
   UInt32 inBufferLength
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ hashInfo: A pointer to the APHashInfoStruct that was returned by CPMLibHashInit().
→ inBuffer: A pointer to the data that you want to hash.
→ inBufferLength: The length of inBuffer, in bytes.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function feeds data into the streaming hash session that was started by CPMLibHashInit(). You can make any number of CPMLibHashUpdate calls while the hash stream is open. When you've finished feeding data into the stream, you call CPMLibHashFinal().

Note that this function doesn't return any hashed data. All the data that's hashed by the stream is returned through the CPMLibHashFinal() call.

CPMLibImportCipherInfo Function ^TOP^

Purpose

Imports a previously-exported cipher info structure so that it can be used in subsequent operations.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibImportCipherInfo (
    UInt16 libRef,
   UInt8 encoding,
   UInt8 *importData,
   UInt32 importDataLength,
   APCipherInfoType *cipherInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ encoding: Constant that specifies the encoding type that was used to export the key. One of IMPORT_EXPORT_RAW, IMPORT_EXPORT_DER, or IMPORT_EXPORT_XML. See Export Encoding Constants for details about these formats.
→ importData: The encoded data.
→ importDataLength: The length of importData, in bytes.
← cipherInfo: APCipherInfoStruct that returns the imported key. The structure must be allocated before it's passed in.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

CPMLibImportHashInfo Function ^TOP^

Purpose

Imports a previously-exported hash info structure so that it can be used in subsequent operations.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibImportHashInfo (
    UInt16 libRef,
   UInt8 encoding,
   UInt8 *importData,
   UInt32 importDataLength,
   APHashInfoType *keyInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ encoding: Constant that specifies the encoding type that was used to export the key. One of IMPORT_EXPORT_RAW, IMPORT_EXPORT_DER, or IMPORT_EXPORT_XML. See Export Encoding Constants for details about these formats.
→ importData: The encoded data.
→ importDataLength: The length of importData, in bytes.
← hashInfo: APHashInfoStruct that returns the imported hash info. The structure must be allocated before it's passed in.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

CPMLibImportKeyInfo Function ^TOP^

Purpose

Imports a previously-exported key so that it (the key) can be used in subsequent operations.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibImportKeyInfo (
    UInt16 libRef,
   UInt8 encoding,
   UInt8 *importData,
   UInt32 importDataLength,
   APKeyInfoType *keyInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ encoding: Constant that specifies the encoding type that was used to export the key. One of IMPORT_EXPORT_RAW, IMPORT_EXPORT_DER, or IMPORT_EXPORT_XML. See Export Encoding Constants for details about these formats.
→ importData: The encoded data.
→ importDataLength: The length of importData, in bytes.
← keyInfo: APKeyInfoStruct that returns the imported key. The structure must be allocated before it's passed in.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

CPMLibImportVerifyInfo Function ^TOP^

Purpose

Imports a previously-exported verify info structure so that it can be used in subsequent operations.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibImportVerifyInfo (
    UInt16 libRef,
   UInt8 encoding,
   UInt8 *importData,
   UInt32 importDataLength,
   APVerifyInfoType *keyInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ encoding: Constant that specifies the encoding type that was used to export the key. One of IMPORT_EXPORT_RAW, IMPORT_EXPORT_DER, or IMPORT_EXPORT_XML. See Export Encoding Constants for details about these formats.
→ importData: The encoded data.
→ importDataLength: The length of importData, in bytes.
← verifyInfo: APVerifyInfoStruct that returns the imported verify info. The structure must be allocated before it's passed in.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

CPMLibReleaseCipherInfo Function ^TOP^

Purpose

Releases a APCipherInfoStruct, allowing you to free it.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibReleaseCipherInfo (
    UInt16 libRef,
   APCipherInfoType *cipherInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ cipherInfo: A pointer to a APCipherInfoStruct that you want to release.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

CPMLibReleaseHashInfo Function ^TOP^

Purpose

Releases a APKeyInfoStruct, allowing you to free it.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibReleaseHashInfo (
    UInt16 libRef,
   APHashInfoType *hashInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ hashInfo: A pointer to a APHashInfoStruct that you want to release.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

CPMLibReleaseKeyInfo Function ^TOP^

Purpose

Releases a APKeyInfoStruct, allowing you to free it.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibReleaseKeyInfo (
    UInt16 libRef,
   APKeyInfoType *keyInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ keyInfo: A pointer to the APKeyInfoStruct that you want to release.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

CPMLibReleaseVerifyInfo Function ^TOP^

Purpose

Releases a APVerifyInfoStruct, allowing you to free it.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibReleaseVerifyInfo (
    UInt16 libRef,
   APVerifyInfoType *verifyInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ verifyInfo: A pointer to a APVerifyInfoStruct that you want to release.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

CPMLibVerify Function ^TOP^

Purpose

Verifies a message.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibVerify (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APVerifyInfoType *verifyInfo,
   UInt8 *inBuffer,
   UInt32 inBufferLength,
   UInt8 *outBuffer,
   UInt32 *outBufferLength,
   UInt8 *signature,
   UInt32 signatureLength,
   VerifyResultType *verifyResult 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ keyInfo: An APKeyInfoStruct that represents the certificate's encryption key. Extracting the key data from the certificate and constructing the APKeyInfoStruct (through CPMLibImportKeyInfo()) is the caller's responsibility.
→ verifyInfo: A pointer to an APVerifyInfoStruct that specifies the hash and cipher operations that should be performed during verification. This information is embedded as APHashInfoStruct and APCipherInfoStruct structures. If you want to use the default operations, allocate and zero the embedded structures. When the function returns, the structures will be populated with information describing the operations that were used.
→ inBuffer: A pointer to the message data.
→ inBufferLength: The length of inBuffer, in bytes.
← outBuffer: A pointer to the buffer where the decrypted signature will be copied. The buffer must be allocated by the caller, and must be big enough to accommodate all of the decrypted data. If you don't care about the signature, pass NULL.
↔ outBufferLength: If outBuffer is NULL, set this to 0. Otherwise, you pass in the (allocated) length of outBuffer, in bytes. The function resets the argument to the amount of data that was actually copied into outBuffer. If the function returns cpmErrBufTooSmall, outBufferLength is set to the minimum buffer size that's needed to accommodate the verified data.
→ signature: A pointer to the message's signature. Extracting the signature from the message is the caller's responsibility
→ signatureLength: The length of the signature, in bytes.
← verifyResult: An integer point that returns, by reference, the result of the verification. 0 means the message was verified; non-zero means is wasn't. The meaning of a non-zero return is defined by the algorithm provider.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function performs a block verifcation operation. For stream verification, use CPMLibVerifyInit().

Keep in mind that a direct return of errNone doesn't mean that the message has been verified. The verification status is returned by reference in verifyResult.

CPMLibVerifyFinal Function ^TOP^

Purpose

Finalizes a verify session.

Declared In

CPMLib.h

Prototype

Err CPMLibVerifyFinal (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APVerifyInfoType *verifyInfo,
   UInt8 *inBuffer,
   UInt32 inBufferLength,
   UInt8 *outBuffer,
   UInt32 *outBufferLength,
   UInt8 *signature,
   UInt32 signatureLength,
   VerifyResultType *verifyResult 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ verifyInfo: A pointer to the APVerifyInfoStruct that was returned by CPMLibVerifyInit().
→ inBuffer: A pointer to the final buffer of message data, or NULL if there's no more data..
→ inBufferLength: The length of inBuffer, in bytes.
← outBuffer: A pointer to the buffer where the decrypted signature will be copied. The buffer must be allocated by the caller, and must be big enough to accommodate all of the decrypted data. If you don't care about the signature, pass NULL.
↔ outBufferLength: If outBuffer is NULL, set this to 0. Otherwise, you pass in the (allocated) length of outBuffer, in bytes. The function resets the argument to the amount of data that was actually copied into outBuffer. If the function returns cpmErrBufTooSmall, outBufferLength is set to the minimum buffer size that's needed to accommodate the verified data.
→ signature: A pointer to the message's signature. Extracting the signature from the message is the caller's responsibility
→ signatureLength: The length of the signature, in bytes.
← verifyResult: An integer point that returns, by reference, the result of the verification. 0 means the message was verified; non-zero means is wasn't. The meaning of a non-zero return is defined by the algorithm provider.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function feeds a final (optional) buffer of message into a verify stream that was previously initialized by CPMLibVerifyInit() and augmented through successive calls to CPMLibVerifyUpdate(). The entire message is then verified, the results of the verification are returned in verifyResult, and the stream is closed.

CPMLibVerifyInit Function ^TOP^

Purpose

Initiates a streaming verify operation.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibVerify (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APVerifyInfoType *verifyInfo 
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ keyInfo: An APKeyInfoStruct that represents the certificate's encryption key. Extracting the key data from the certificate and constructing the APKeyInfoStruct (through CPMLibImportKeyInfo()) is the caller's responsibility.
→ verifyInfo: A pointer to an APVerifyInfoStruct that specifies the hash and cipher operations that should be performed during verification. This information is embedded as APHashInfoStruct and APCipherInfoStruct structures. If you want to use the default operations, allocate and zero the embedded structures. When the function returns, the structures will be populated with information describing the operations that were used.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function initializes a streaming hash operation. To feed data to the stream, you call CPMLibVerifyUpdate() followed by CPMLibVerifyFinal(). The "update" function is optional; the "final" function is mandatory. For a block hash, see CPMLibVerify().

CPMLibVerifyUpdate Function ^TOP^

Purpose

Sends message data to a streaming verify operation.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibVerifyUpdate (
    UInt16 libRef,
   APKeyInfoType *keyInfo,
   APVerifyInfoType *verifyInfo 
)UInt8 *inBuffer,
   UInt32 inBufferLength
)

Parameters

→ libRef: CPM Library reference number (68k only).
→ keyInfo: The APKeyInfoStruct that was used in the CPMLibVerifyInit() call.
→ verifyInfo: A pointer to the APVerifyInfoStruct that was returned by CPMLibVerifyInit().
→ inBuffer: A pointer to the message data.
→ inBufferLength: The length of inBuffer, in bytes.

Returns

The function returns errNone upon success. For other error codes, see CPM Error Codes.

Comments

This function feeds message data into the verify stream that was intialized by CPMLibVerifyInit(). When you're finished feeding data into the stream, call CPMLibVerifyFinal() to close the stream and return the verification results.

84 Cryptography Provider Manager

The Default Provider ^TOP^

Fundamental CPM Functions ^TOP^

Using the Crypto-Info Structures ^TOP^

Using the Export Functions ^TOP^

CPM and AP Constants ^TOP^

AP Capability Constants ^TOP^

Block Encryption Mode Constants ^TOP^

Purpose

Prototype

Constants

Cipher Algorithm Constants ^TOP^

Purpose

Prototype

Block Cipher Algorithms

Stream Ciphers

AES Block Ciphers

Asymmetric Key Ciphers

Key Agreement Ciphers

Export Encoding Constants ^TOP^

Hashing Algorithm Constants ^TOP^

Key Class Constants ^TOP^

Purpose

Prototype

Constants

Key Usage Constants ^TOP^

Purpose

Prototype

Constants

Plaintext Padding Constants ^TOP^

Purpose

Prototype

Constants

CPM Error Codes ^TOP^

CPM and AP Structures and Data Types ^TOP^

APCipherInfoStruct Struct ^TOP^

Purpose

Prototype

Fields

APHashInfoStruct Struct ^TOP^

Purpose

Prototype

Fields

Comments

APKeyInfoStruct Struct ^TOP^

Purpose

Prototype

Fields

APProviderContextStruct Struct ^TOP^

Purpose

Prototype

Fields

APProviderInfoStruct Struct ^TOP^

Purpose

Prototype

Fields

APVerifyInfoStruct Struct ^TOP^

Purpose

Prototype

Fields

CPMInfoStruct Struct ^TOP^

Purpose

Prototype

Fields

CPM Functions ^TOP^

CPMLibDecrypt Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

CPMLibDecryptFinal Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

CPMLibDecryptInit Function ^TOP^