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
APCipherInfoType Struct
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
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
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
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
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
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
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
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
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
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
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
APAlgorithmEnum Typedef
Purpose
Cipher types. Used by the APCipherInfoType
and APKeyInfoType
structures.
Declared In
CPMLibCommon.h
Prototype
typedef uint32_t APAlgorithmEnum
Constants
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
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
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
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
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
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
Purpose
The MAC type. Used by the APMACInfoType
structure.
Declared In
CPMLibCommon.h
Prototype
typedef uint32_t APMACEnum
Constants
APModeEnum Typedef
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
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
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
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
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
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
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:
0x
MMmfsbbb, 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 -