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

10    CPM Library Common Definitions

Security and Cryptography

Exploring Palm OS

The CPMLibCommon.h header file declares the various structures, types, and constants used by the CPM library. These structures, types, and constants are documented in this chapter; this documentation is organized into the following sections:

CPM Library Structures and Types
CPM Library Constants

CPM Library Structures and Types ^TOP^

APCipherInfoType Struct ^TOP^

Purpose

Structure to hold information about a particular operation's context, including generic information about contexts and specific information about the provider's concept of the context.

Declared In

CPMLibCommon.h

Prototype

struct APCipherInfoStruct {
   APProviderContextType providerContext;
   APAlgorithmEnum type;
   APPaddingEnum padding;
   APModeEnum mode;
   uint8_t *iv;
   uint32_t ivLength;
   void *algorithmParams;
} 
typedef struct APCipherInfoStruct 
APCipherInfoType, *APCipherInfoPtr

Fields

providerContext
The provider context of this info type.
type
Cipher type. One of the APAlgorithmEnum values.
padding
The type of padding for this cipher. One of the APPaddingEnum values.
mode
Modes of operation for symmetric encryption/decryption. One of the APModeEnum values.
iv
Initialization vector as specified by the caller.
ivLength
The size, in bytes, of the initialization vector.
algorithmParams
Provider-specific algorithm parameters.

Comments

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

If the application does not care or wants default settings for the APCipherInfoType, allocate the APCipherInfoType structure and zero its contents. Upon return from either CPMLibEncryptInit(), CPMLibEncrypt(), CPMLibDecryptInit(), CPMLibDecrypt(), or CPMLibImportCipherInfo() the APICipherInfoType structure will have been filled in by the CPM and provider with the appropriate information.

if the application does care about the settings for the APCipherInfoType, the application should allocate the APICipherInfoType structure and set the fields as appropriate before passing it in to one of the previously mentioned functions.

APDerivedKeyInfoType Struct ^TOP^

Purpose

Structure to hold the various pieces of information about the derivation functions and parameters.

Declared In

CPMLibCommon.h

Prototype

struct APDerivedKeyInfoStruct {
   APProviderContextType providerContext;
   APKeyDerivationEnum kdType;
   APKeyDerivationUsageEnum kdUsage;
   uint8_t *salt;
   uint32_t saltLen;
   uint32_t iterationCount;
   void *kdInfo;
} 
typedef struct APDerivedKeyInfoStruct
APDerivedKeyInfoType, *APKeyDerivedKeyInfoPtr

Fields

providerContext
The provider context of this info type. See APProviderContextType.
kdType
The type of key derivation to be performed. One of the values specified by APKeyDerivationEnum.
kdUsage
The allowed usage of the subsequently derived key. One of the values specified by APKeyDerivationUsageEnum.
salt
Cryptographic salt to be used for the derivation function.
saltLen
The length, in bytes, of the salt.
iterationCount
The number of iterations for this particular derivation operation.
kdInfo
Other derivation-function-specific parameters as defined by both the provider handling the derivation and the derivation function itself.

APHashInfoType Struct ^TOP^

Purpose

Structure to hold information about a particular hashing operation, including generic information about hashing operations and specific information about the provider's concept of the hashing operation.

Declared In

CPMLibCommon.h

Prototype

struct APHashInfoStruct {
   APProviderContextType providerContext;
   APHashEnum type;
   uint32_t length;
}
typedef struct APHashInfoStruct APHashInfoType, 
*APHashInfoPtr

Fields

providerContext
The provider context of this info type. See APProviderContextType.
type
The type of the hash. One of the values specified by APHashEnum.
length
The length of the hash, in bytes.

Comments

The application is responsible for allocating memory and deallocating memory for this structure.

APKeyInfoType Struct ^TOP^

Purpose

Structure to hold information about a particular key, including generic information about all keys and specific information about the provider's concept of the key.

Declared In

CPMLibCommon.h

Prototype

struct APKeyInfoStruct {
   APProviderContextType providerContext;
   APAlgorithmEnum type;
   APKeyUsageEnum usage;
   APKeyClassEnum keyclass;
   uint32_t length;
   uint32_t actualLength;
   uint16_t exportable;
   uint16_t ephemeral;
} 
typedef struct APKeyInfoStruct APKeyInfoType, 
*APKeyInfoPtr

Fields

providerContext
The provider context of this info type. See APProviderContextType.
type
The type of this key. One of the values specified by APAlgorithmEnum.
usage
The key usage. One of the values specified by APKeyUsageEnum.
keyclass
The key class. One of the values specified by APKeyClassEnum.
length
actualLength
exportable
Whether or not this key is exportable. This field has a value of 1 if it is, or 0 if it is not.
ephemeral
Whether or not this key is permanent. This field has a value of 1 if it is, or 0 if it is not.

Comments

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

If the application does not care or wants default settings for the APKeyInfoType, the application should allocate the APKeyInfoType structure and set its contents to zero. Upon return from either CPMLibImportKeyInfo() or CPMLibGenerateKey() the APKeyInfoType structure would have been filled in by the CPM and the provider with the appropriate information.

If the application does care about the settings for the APKeyInfoType, the application should allocate the APKeyInfoType structure and set the fields appropriately before passing it in to CPMLibGenerateKey().

APMACInfoType Struct ^TOP^

Purpose

Declared In

CPMLibCommon.h

Prototype

struct APMACInfoStruct {
   APProviderContextType providerContext;
   APMACEnum type;
} 
typedef struct APMACInfoStruct APMACInfoType, 
*APMACInfoPtr

Fields

providerContext
The provider context of this info type. See APProviderContextType.
type
The MAC type. One of the APMACEnum values.

APProviderContextType Struct ^TOP^

Purpose

Contains provider-specific information.

Declared In

CPMLibCommon.h

Prototype

struct APProviderContextStruct {
   uint32_t providerID;
   void *localContext;
} 
typedef struct APProviderContextStruct 
APProviderContextType, *APProviderContextPtr

Fields

providerID
The provider handling this operation.
localContext
Provider-specific infomation about this operation.

APProviderInfoType Struct ^TOP^

Purpose

Structure to hold information about a particular provider as it is known by the current instantiation of the CPM library.

Declared In

CPMLibCommon.h

Prototype

struct APProviderInfoStruct {
   char name[32];
   char other[64];
   uint32_t flags;
   uint8_t numAlgorithms;
   Boolean bHardware;
} 
typedef struct APProviderInfoStruct 
APProviderInfoType, *APProviderInfoPtr

Fields

name
Name of the provider.
other
Other textual information.
flags
Flags to indicate functionality supported by the cryptographic provider. This is a combination of the values documented under "Cryptographic Provider Functionality Flags."
numAlgorithms
Number of algorithms supported.
bHardware
Whether or not this is a hardware provider.

APSignInfoType Struct ^TOP^

Purpose

Structure to hold information about a particular operation's signature context, including generic information about signature contexts and specific information about the provider's concept of the signature context. This structure is needed to maintain state across the various multi-part operations.

Declared In

CPMLibCommon.h

Prototype

struct APSignInfoStruct {
   APProviderContextType providerContext;
   APHashInfoType *hashInfoP;
   APCipherInfoType *cipherInfoP;
} 
typedef struct APSignInfoStruct APSignInfoType, 
*APSignInfoPtr

Fields

providerContext
The provider context of this info type. See APProviderContextType.
hashInfoP
The hash to use. See APHashInfoType.
cipherInfoP
The cipher to use. See APCipherInfoType.

Comments

The application is always responsible for allocating and freeing the APSignInfoType structure and the associated APCipherInfoType and APHashInfoType structures. The application must call CPMLibReleaseCipherInfo() with the APCipherInfoType structure to allow the CPM and the provider(s) to clean up the APCipherInfoType structure. The application must call CPMLibReleaseHashInfo() with the APHashInfoType structure to allow the CPM and the provider(s) to clean up the APHashInfoType structure.

If the application does not care or wants default settings for either the APCipherInfoType or the APHashInfoType, allocate and zero the structures. Upon return from CPMLibSign() or CPMLibSignInit() the APCipherInfoType structure and the APHashInfoType structure would have been filled in by the CPM and the provider(s) with the appropriate information.

If the application does care about the settings for either the APCipherInfoType or the APHashInfoType, allocate the structures and set the fields appropriately before calling CPMLibSign() or CPMLibSignInit(). The application may set the fields in one or the other or both.

APVerifyInfoType Struct ^TOP^

Purpose

Structure to hold information about a particular operation's verification context, including generic information about verification contexts and specific information about the provider's concept of the verification context.

Declared In

CPMLibCommon.h

Prototype

struct APVerifyInfoStruct {
   APProviderContextType providerContext;
   APHashInfoType *hashInfoP;
   APCipherInfoType *cipherInfoP;
} 
typedef struct APVerifyInfoStruct 
APVerifyInfoType, *APVerifyInfoPtr

Fields

providerContext
The provider context of this info type. See APProviderContextType.
hashInfoP
The hash to use. See APHashInfoType.
cipherInfoP
The cipher to use. See APCipherInfoType.

Comments

The application is always responsible for allocating and freeing the APSignInfoType structure and the associated APCipherInfoType and APHashInfoType structures. The application must call CPMLibReleaseCipherInfo() with the APCipherInfoType structure to allow the CPM and the provider(s) to clean up the APCipherInfoType structure. The application must call CPMLibReleaseHashInfo() with the APHashInfoType structure to allow the CPM and the provider(s) to clean up the APHashInfoType structure.

If the application does not care or wants default settings for either the APCipherInfoType or the APHashInfoType, allocate and zero the structures. Upon return from CPMLibVerify() or CPMLibVerifyInit() the APCipherInfoType structure and the APHashInfoType structure would have been filled in by the CPM and the provider(s) with the appropriate information.

If the application does care about the settings for either the APCipherInfoType or the APHashInfoType, allocate the structures and set the fields appropriately before calling CPMLibVerify() or CPMLibVerifyInit(). The application may set the fields in one or the other or both.

CPMInfoType Struct ^TOP^

Purpose

Structure to hold information about the CPM library as it is known by the currently running system.

Declared In

CPMLibCommon.h

Prototype

struct CPMInfoStruct {
   uint8_t numInstances;
   uint8_t numProviders;
   Boolean defaultProviderPresent;
} 
typedef struct CPMInfoStruct CPMInfoType, 
*CPMInfoPtr

Fields

numInstances
Number of instances of this library.
numProviders
Number of providers this library knows about.
defaultProviderPresent
Whether or not the default provider is known.

VerifyResultType Typedef ^TOP^

Purpose

Type that holds the result of a verification operation.

Declared In

CPMLibCommon.h

Prototype

typedef uint32_t VerifyResultType, 
*VerifyResultPtr

Comments

This type is used by CPMLibVerify() and CPMLibVerifyFinal(). These functions set a variable of this type to zero if the signature verifies, or to 1 if the signature did not verify.

CPM Library Constants ^TOP^

APAlgorithmEnum Typedef ^TOP^

Purpose

Cipher types. Used by the APCipherInfoType and APKeyInfoType structures.

Declared In

CPMLibCommon.h

Prototype

typedef uint32_t APAlgorithmEnum

Constants

#define apAlgorithmTypeUnspecified 0x00L
The algorithm type is unspecified.

Block Ciphers

#define apSymmetricTypeDES 0x01L
#define apSymmetricTypeRC2 0x02L
#define apSymmetricTypeRC4 0x03L
#define apSymmetricTypeRC5 0x04L
#define apSymmetricTypeRC6 0x05L
#define apSymmetricTypeDESX_XDX3 0x06L
#define apSymmetricType3DES_EDE2 0x07L
#define apSymmetricType3DES_EDE3 0x08L
#define apSymmetricTypeIDEA 0x09L
#define apSymmetricTypeDiamond2 0x0aL
#define apSymmetricTypeBlowfish 0x0bL
#define apSymmetricTypeTEA 0x0cL
#define apSymmetricTypeSAFER 0x0dL
#define apSymmetricType3WAY 0x0eL
#define apSymmetricTypeGOST 0x0fL
#define apSymmetricTypeSHARK 0x10L
#define apSymmetricTypeCAST128 0x11L
#define apSymmetricTypeSquare 0x12L
#define apSymmetricTypeSkipjack 0x13L

Stream Ciphers

#define apSymmetricTypePanama 0x14L
#define apSymmetricTypeARC4 0x15L
#define apSymmetricTypeSEAL 0x16L
#define apSymmetricTypeWAKE 0x17L
#define apSymmetricTypeSapphire 0x18L
#define apSymmetricTypeBBS 0x19L

AES Block Ciphers

#define apSymmetricTypeRijndael 0x2aL
#define apSymmetricTypeCAST256 0x2bL
#define apSymmetricTypeTwofish 0x2cL
#define apSymmetricTypeMARS 0x2dL
#define apSymmetricTypeSerpent 0x2eL

Asymmetric Key Types

#define apAsymmetricTypeRSA 0x2fL
#define apAsymmetricTypeDSA 0x30L
#define apAsymmetricTypeElgamal 0x31L
#define apAsymmetricTypeNR 0x32L
Nyberg-Rueppel
#define apAsymmetricTypeBlumGoldwasser 0x33L
#define apAsymmetricTypeRabin 0x34L
#define apAsymmetricTypeRW 0x35L
Rabin-Williams
#define apAsymmetricTypeLUC 0x36L
#define apAsymmetricTypeLUCELG 0x37L

Elliptic Curve

#define apAsymmetricTypeECDSA 0x38L
#define apAsymmetricTypeECNR 0x39L
#define apAsymmetricTypeECIES 0x3aL
#define apAsymmetricTypeECDHC 0x3bL
#define apAsymmetricTypeECMQVC 0x3cL

Key Agreement

#define apKeyAgreementTypeDH 0x3dL
#define apKeyAgreementTypeDH2 0x3eL
Unified Diffie-Hellman
#define apKeyAgreementTypeMQV 0x3fL
Menezes-Qu-Vanstone
#define apKeyAgreementTypeLUCDIF 0x40L
#define apKeyAgreementTypeXTRDH 0x41L

APHashEnum Typedef ^TOP^

Purpose

Algorithm provider hash types. Used by the APHashInfoType structure.

Declared In

CPMLibCommon.h

Prototype

typedef uint32_t APHashEnum

Constants

#define apHashTypeHAVAL 0x05L
#define apHashTypeMD2 0x02L
#define apHashTypeMD5 0x03L
#define apHashTypeNone 0x01L
#define apHashTypePanama 0x08L
#define apHashTypeRIPEMD160 0x06L
#define apHashTypeSHA1 0x04L
#define apHashTypeSHA256 0x09L
#define apHashTypeSHA384 0x0aL
#define apHashTypeSHA512 0x0bL
#define apHashTypeTiger 0x07L
#define apHashTypeUnspecified 0x00L

APKeyClassEnum Typedef ^TOP^

Purpose

The key class. Used by the APKeyInfoType structure.

Declared In

CPMLibCommon.h

Prototype

typedef uint32_t APKeyClassEnum

Constants

#define apKeyClassPrivate 0x03L
#define apKeyClassPublic 0x02L
#define apKeyClassSymmetric 0x01L
#define apKeyClassUnspecified 0x00L

APKeyDerivationEnum Typedef ^TOP^

Purpose

The type of key derivation to be performed. Used by the APDerivedKeyInfoType structure.

Declared In

CPMLibCommon.h

Prototype

typedef uint32_t APKeyDerivationEnum

Constants

#define apKeyDerivationTypePKCS12 0x03L
#define apKeyDerivationTypePKCS5v1 0x01L
#define apKeyDerivationTypePKCS5v2 0x02L
#define apKeyDerivationTypePKIX 0x04L
#define apKeyDerivationTypeTLS 0x05L
#define apKeyDerivationUnspecified 0x00L

APKeyDerivationUsageEnum Typedef ^TOP^

Purpose

The allowed usage of the subsequently derived key. Used by the APDerivedKeyInfoType structure.

Declared In

CPMLibCommon.h

Prototype

typedef uint32_t APKeyDerivationUsageEnum

Constants

#define apKeyDerivationUsageEncryption 0x01L
#define apKeyDerivationUsageIV 0x03L
#define apKeyDerivationUsageMAC 0x02L
#define apKeyDerivationUsageUnspecified 0x00L

APKeyUsageEnum Typedef ^TOP^

Purpose

The key usage. Used by the APKeyInfoType structure.

Declared In

CPMLibCommon.h

Prototype

typedef uint32_t APKeyUsageEnum

Constants

#define apKeyUsageAll 0x01L
#define apKeyUsageCertificateSigning 0x04L
#define apKeyUsageDataEncrypting 0x06L
#define apKeyUsageEncryption 0x03L
#define apKeyUsageKeyEncrypting 0x05L
#define apKeyUsageMessageIntegrity 0x07L
#define apKeyUsageSigning 0x02L
#define apKeyUsageUnspecified 0x00L

APMACEnum Typedef ^TOP^

Purpose

The MAC type. Used by the APMACInfoType structure.

Declared In

CPMLibCommon.h

Prototype

typedef uint32_t APMACEnum

Constants

#define apMACHMAC 0x01L
#define apMACUnspecified 0x00L

APModeEnum Typedef ^TOP^

Purpose

Modes of operation for symmetric encryption/decryption. Used by the APCipherInfoType structure.

Declared In

CPMLibCommon.h

Prototype

typedef uint32_t APModeEnum

Constants

#define apModeCounter 0x07L
#define apModeTypeCBC 0x03L
#define apModeTypeCBC_CTS 0x04L
#define apModeTypeCFB 0x05L
#define apModeTypeECB 0x02L
#define apModeTypeNone 0x01L
#define apModeTypeOFB 0x06L
#define apModeTypeUnspecified 0x00L

APPaddingEnum Typedef ^TOP^

Purpose

The type of padding for a cipher. Used by the APCipherInfoType structure.

Declared In

CPMLibCommon.h

Prototype

typedef uint32_t APPaddingEnum

Constants

#define apPaddingTypeNone 0x01L
#define apPaddingTypeOAEP 0x05L
#define apPaddingTypePKCS1Type1 0x02L
#define apPaddingTypePKCS1Type2 0x03L
#define apPaddingTypePKCS5 0x04L
#define apPaddingTypeSSLv23 0x06L
#define apPaddingTypeUnspecified 0x00L

Import/Export Types ^TOP^

Purpose

Indicates the type of encoding to use when importing or exporting using one of the CPMLibImport... or CPMLibExport... functions.

Declared In

CPMLibCommon.h

Constants

#define IMPORT_EXPORT_TYPE_DER 1
A standardized ASN.1 DER encoding
#define IMPORT_EXPORT_TYPE_RAW 0
A raw form of import/export as defined by the provider.
#define IMPORT_EXPORT_TYPE_XML 2
A standardized XML encoding.

Comments

A given CPM import/export format, such as XML, is only supported if the provider supports it. IMPORT_EXPORT_TYPE_RAW is always supported.

Cryptographic Provider Functionality Flags ^TOP^

Purpose

Flags that identify the functionality provided by a given cryptographic provider. The appropriate flags are ORd together to make up the flags field of the APProviderInfoType structure.

Declared In

CPMLibCommon.h

Constants

#define APF_CIPHER 0x00000080
The provider supports encryption and decryption, import and export
#define APF_HASH 0x00000040
The provider supports message digests.
#define APF_HW 0x00000002
The provider is implemented in hardware (SmartCard).
#define APF_KEYDERIVE 0x00000020
The provider supports key derivation, import and export.
#define APF_KEYGEN 0x00000004
The provider supports key generation, import and export.
#define APF_KEYPAIRGEN 0x00000010
The provider supports key pair generation, import and export.
#define APF_MAC 0x00000400
The provider supports MAC.
#define APF_MP 0x00000001
Multiple-part operations are supported (Init, Update, Final).
#define APF_SIGN 0x00000100
The provider supports signing.
#define APF_VERIFY 0x00000200
The provider supports verification.

Debug Output Levels ^TOP^

Purpose

Values that specify the level of debug output to be sent from the library using DbgMessage(). Set the debug output level by calling CPMLibSetDebugLevel().

Declared In

CPMLibCommon.h

Constants

#define LOG_ALERT 1
Action must be taken immediately.
#define LOG_CRIT 2
Critical conditions.
#define LOG_DEBUG 7
Debug-level messages.
#define LOG_EMERG 0
The system is unusable.
#define LOG_ERR 3
Error conditions.
#define LOG_INFO 6
Informational.
#define LOG_NOTICE 5
Normal but significant condition.
#define LOG_WARNING 4
Warning conditions.

CPM Library Error Codes ^TOP^

Purpose

Error codes returned by the various CPM library functions.

Declared In

CPMLibCommon.h

Constants

#define cpmErrAlreadyOpen (cpmErrorClass | 1)
The CPM library is already open. Usually returned from CPMLibOpen() indicating that the library is already open.
#define cpmErrBadData (cpmErrorClass | 14)
Data passed to the CPM library was no good.
#define cpmErrBufTooSmall (cpmErrorClass | 13)
A buffer passed to the CPM library was too small.
#define cpmErrKeyExists (cpmErrorClass | 18)
The key you are trying to import already seems to exist.
#define cpmErrKeyNotFound (cpmErrorClass | 19)
The key you are trying to use doesn't seem to exist.
#define cpmErrNoAppContext (cpmErrorClass | 17)
The CPM application context could not be found for this operation. Most likely, the CPM library is not open.
#define cpmErrNoBaseProvider (cpmErrorClass | 5)
The CPM library cannot load the base provider.
#define cpmErrNoProviders (cpmErrorClass | 4)
The CPM library is not aware of any providers. With no providers the CPM library has no functionality.
#define cpmErrNotOpen (cpmErrorClass | 2)
The CPM library is not open.
#define cpmErrOutOfMemory (cpmErrorClass | 12)
The CPM library is out of dynamic heap.
#define cpmErrOutOfResources (cpmErrorClass | 11)
The CPM library is out of resources (such as memory, static heap, and so on).
#define cpmErrParamErr (cpmErrorClass | 10)
A CPM library call was made with an invalid parameter.
#define cpmErrProviderNotFound (cpmErrorClass | 6)
The CPM library cannot find the specified provider.
#define cpmErrStillOpen (cpmErrorClass | 3)
The CPM library is still open after a call to CPMLibClose().
#define cpmErrUnimplemented (cpmErrorClass | 15)
A CPM library function is not implemented.
#define cpmErrUnsupported (cpmErrorClass | 16)
A CPM library function is unsupported in the current version.

Miscellaneous CPM Library Constants ^TOP^

Purpose

The CPMLibCommon.h header file also declares these constants.

Declared In

CPMLibCommon.h

Constants

#define cpmCreator 'cpml'
The CPM creator ID. Used for both the databae that contains the Cryptographic Provider Manager Library and its preferences database.
#define cpmFtrCreator cpmCreator
The feature creator. Intended for use with FtrGet().
#define cpmFtrNumVersion 0
The number of the CPM feature that contains the current version of the CPM library. The value returned from this feature has the following format: 0xMMmfsbbb, where MM is the major version, m is the minor version, f is the bug fix level, s is the build stage (3 = release, 2 = beta, 1 = alpha, 0 = development), and bbb is the build number for non-releases