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

84    Cryptography Provider Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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:

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:

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 {
APProviderContextTypeproviderContext;
APAlgorithmEnumtype;
APPaddingEnumpadding;
UInt8*iv;
UInt32ivLength;
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 {
APProviderContextTypeproviderContext;
APHashEnumtype;  
UInt32length; 
};

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 {
APProviderContextTypeproviderContext; 
APAlgorithmEnumtype;
APKeyUsageEnumusage;
APKeyClassEnumkeyclass; 
UInt32length;
UInt32actualLength; 
UInt16exportable; 
UInt16ephemeral;   
};

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 {
UInt32providerID;
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 {
charname[32];
charother[64];
UInt32flags;
UInt8numAlgorithms; 
BooleanbHardware; 
};

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 {
APProviderContextTypeproviderContext;
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 {
UInt8numInstances; 
UInt8numProviders; 
BooleandefaultProviderPresent;
};

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(
    UInt16libRef,
   APKeyInfoType*keyInfo,
   APCipherInfoType*cipherInfo,
   UInt8*inBuffer,
   UInt32inBufferLength,
   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(
   UInt16libRef,
   APKeyInfoType*keyInfo,
   APCipherInfoType*cipherInfo,
   UInt8*inBuffer,
   UInt32inBufferLength,
   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(
    UInt16libRef,
   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(
   UInt16libRef,
   APKeyInfoType*keyInfo,
   APCipherInfoType*cipherInfo,
   UInt8*inBuffer,
   UInt32inBufferLength,
   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(
    UInt16libRef,
   APKeyInfoType*keyInfo,
   APCipherInfoType*cipherInfo,
   UInt8*inBuffer,
   UInt32inBufferLength,
   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.

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 CPMLibEncrypt again.

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(
   UInt16libRef,
   APKeyInfoType*keyInfo,
   APCipherInfoType*cipherInfo,
   UInt8*inBuffer,
   UInt32inBufferLength,
   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(
    UInt16libRef,
   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(
   UInt16libRef,
   APKeyInfoType*keyInfo,
   APCipherInfoType*cipherInfo,
   UInt8*inBuffer,
   UInt32inBufferLength,
   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(
    UInt16libRef,
   APCipherInfoType*cipherInfo,
   UInt8encoding,
   UInt8*exportBuffer,
   UInt32exportBufferLength
)

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(
    UInt16libRef,
   APHashInfoType*hashInfo,
   UInt8encoding,
   UInt8*exportBuffer,
   UInt32exportBufferLength
)

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(
    UInt16libRef,
   APKeyInfoType*keyInfo,
   UInt8encoding,
   UInt8*exportBuffer,
   UInt32exportBufferLength
)

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

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.

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(
    UInt16libRef,
   APVerifyInfoType*verifyInfo,
   UInt8encoding,
   UInt8*exportBuffer,
   UInt32exportBufferLength
)

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

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.

CPMLibGenerateKey Function ^TOP^

Purpose

Generates a new symmetric key.

Declared In

CPMLib68KInterface.h, CPMLibArmInterface.h

Prototype

Err CPMLibGenerateKey(
    UInt16libRef,
   UInt8*seedData,
   UInt32seedLength,
   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(
    UInt16libRef,
   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(
    UInt16libRef,
   UInt32providerID,
   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(
    UInt16libRef,
   APHashEnumtype,
   APHashInfoType*hashInfo,
   UInt8*inBuffer,
   UInt32inBufferLength,
   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(
    UInt16libRef,
   APHashInfoType*hashInfo,
   UInt8*inBuffer,
   UInt32inBufferLength,
   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(
    UInt16libRef,
   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(
    UInt16libRef,
   APHashInfoType*hashInfo,
   UInt8*inBuffer,
   UInt32inBufferLength
)

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(
    UInt16libRef,
   UInt8encoding,
   UInt8*importData,
   UInt32importDataLength,
   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(
    UInt16libRef,
   UInt8encoding,
   UInt8*importData,
   UInt32importDataLength,
   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(
    UInt16libRef,
   UInt8encoding,
   UInt8*importData,
   UInt32importDataLength,
   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(
    UInt16libRef,
   UInt8encoding,
   UInt8*importData,
   UInt32importDataLength,
   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(
    UInt16libRef,
   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(
    UInt16libRef,
   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(
    UInt16libRef,
   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(
    UInt16libRef,
   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(
    UInt16libRef,
   APKeyInfoType*keyInfo,
   APVerifyInfoType*verifyInfo,
   UInt8*inBuffer,
   UInt32inBufferLength,
   UInt8*outBuffer,
   UInt32*outBufferLength,
   UInt8*signature,
   UInt32signatureLength,
   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(
    UInt16libRef,
   APKeyInfoType*keyInfo,
   APVerifyInfoType*verifyInfo,
   UInt8*inBuffer,
   UInt32inBufferLength,
   UInt8*outBuffer,
   UInt32*outBufferLength,
   UInt8*signature,
   UInt32signatureLength,
   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(
    UInt16libRef,
   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(
    UInt16libRef,
   APKeyInfoType*keyInfo,
   APVerifyInfoType*verifyInfo
)UInt8*inBuffer,
   UInt32inBufferLength
)

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.