RSA BSAFE Cert-C
API Reference

pkcs12.h File Reference

This file provides PKCS #12 import and export APIs.

#include "certapi.h"
#include "service.h"
#include "certio.h"

Go to the source code of this file.

Data Structures

KEY_CONTENT

Represents the contents of a PKCS #12 key bag. More...

PKCS12_BAG

Represents a safe bag used in a PKCS #12 file. More...

SECRET_CONTENT

Represents the contents of a PKCS #12 secret bag. More...

Defines

#define PKCS12_NO_MAC_VERIFICATION

When this flag is set, integrity checking on the PKCS #12 contents (PFX MacData) is not performed. More...

#define PKCS12_MS_EXPLORER

When this flag is set, Cert-C will use the Microsoft Internet Explorer format. More...

#define PKCS12_NS_NAVIGATOR

If this value is specified, Cert-C will use the Netscape Navigator format, except that Cert-C will use DER encoding instead of indefinite-length BER encoding. More...

#define PKCS12_USE_TWO_PASSWORDS

When this flag is set, separate passwords will be used for MAC verification and for decryption. More...

Typedefs

typedef KEY_CONTENT KEY_CONTENT

Represents the contents of a PKCS #12 key bag. More...

typedef CERT_OBJ CERT_CONTENT

A CERT_OBJ that contains a PKCS #12 certificate bag.

typedef CRL_OBJ CRL_CONTENT

A CRL_OBJ that contains a PKCS #12 CRL bag.

typedef SECRET_CONTENT SECRET_CONTENT

Represents the contents of a PKCS #12 secret bag. More...

typedef PKCS12_BAG PKCS12_BAG

Represents a safe bag used in a PKCS #12 file. More...

Functions

int C_ImportPKCS12 (CERTC_CTX ctx, char *pkcs12fileName, ITEM *macPassword, SERVICE db, int flags,...)

Imports the contents of a PKCS #12 file into local storage. More...

int C_ReadFromPKCS12 (CERTC_CTX ctx, STREAM pkcs12Stream, ITEM *macPassword, int flags, LIST_OBJ pkcs12Contents,...)

Reads keys, certificate chains, and CRLs from a PKCS #12 file. More...

int C_ExportPKCS12 (CERTC_CTX ctx, NAME_OBJ subjectName, CERT_PATH_CTX *pathCtx, int encType, int digestType, int iterations, int option, char *pkcs12fileName, ITEM *macPassword,...)

Exports key materials corresponding to a specified subject name. More...

int C_WriteToPKCS12 (CERTC_CTX ctx, LIST_OBJ pkcs12Contents, int encType, int digestType, int iterations, int option, ITEM *macPassword, STREAM pkcs12Stream,...)

Writes keys, certificates, and CRLs to a stream. More...

Variables

LIST_OBJ_ENTRY_HANDLER PKCS12BagEntryHandler

A LIST_OBJ_ENTRY_HANDLER that is used to create a LIST_OBJ that contains a list of PKCS12_BAG structures. More...

Define Documentation

#define PKCS12_MS_EXPLORER

When this flag is set, Cert-C will use the Microsoft Internet Explorer format. That is, Cert-C will use PBE to protect the entire contents and plain key bags to hold keys. This only applies to PKCS #12 exports.

#define PKCS12_NO_MAC_VERIFICATION

When this flag is set, integrity checking on the PKCS #12 contents (PFX MacData) is not performed. This flag only applies to PKCS #12 imports.

#define PKCS12_NS_NAVIGATOR

If this value is specified, Cert-C will use the Netscape Navigator format, except that Cert-C will use DER encoding instead of indefinite-length BER encoding. That is, Cert-C will use plain text for the entire contents and will protect keys inside PKCS #8 shrouded key bags. This only applies to PKCS #12 exports.

#define PKCS12_USE_TWO_PASSWORDS

When this flag is set, separate passwords will be used for MAC verification and for decryption. If this flag is not set, any optional arguments are ignored. If this flag is set, the caller must supply a decryption password. This flag applies to both PKCS #12 imports and exports.

Typedef Documentation

typedef struct KEY_CONTENT KEY_CONTENT

Represents the contents of a PKCS #12 key bag. It consists of a private key and a certificate that contains the matching public key for the private key.

On PKCS #12 import, KEY_CONTENT.cert can be set to NULL by the toolkit if no certificate corresponding to the private key is present in the PKCS #12 that is being imported.

On PKCS #12 export, the KEY_CONTENT.cert field is not used.
Having a PKCS12_BAG.content.keyContent present in a list of PKCS12_BAG structures only inserts a private key into the PKCS #12 being created. To add the matching certificate, the caller must provide a PKCS12_BAG.content.CERT_CONTENT.
Parameters:

key A B_KEY_OBJ object that contains the private key object.

cert A CERT_OBJ object that holds the certificate that contains the matching public key for the private key in key.

typedef struct PKCS12_BAG PKCS12_BAG

Represents a safe bag used in a PKCS #12 file. It is either a certificate bag, a CRL bag, a key bag, or a secret bag. Use the PKCS12_BAG structure with the C_ReadFromPKCS12() and C_WriteToPKCS12() functions.
Parameters:

type An int value that identifies the type of data structure in the content union. Cert-C supports the following types of PKCS #12 safe bags:

PKCS #12 Safe Bag Type Description

PKCS12_KEY_BAG_TYPE A bag that contains a key pair

PKCS12_CERT_BAG_TYPE A bag that contains a certificate

PKCS12_CRL_BAG_TYPE A bag that contains a CRL

PKCS12_SECRET_BAG_TYPE A bag that contains a secret

content A union that contains a PKCS #12 safe bag in the format specified by type.

PKCS #12 Safe Bag Type Description

keyContent A KEY_CONTENT structure that represents the contents of a key bag. It holds a private key and a certificate that contains the matching public key for that private key.

certContent A CERT_CONTENT structure that represents the contents of a certificate bag. It is a CERT_OBJ.

crlContent A CRL_CONTENT structure that represents the contents of a CRL bag. It is a CRL_OBJ.

secretContent A SECRET_CONTENT structure that represents the contents of a secret bag. It holds a secret-content type-identifier and a secret-content value.

friendlyName An ITEM structure that specifies the friendly name associated with the PKCS #12 safe bag in content. The value must be a DER-encoded BMPString that consists of 2-byte characters. C_DEREncodeString() can produce this type of string, if the appropriate options are set. The demonstration code routine RSA_FormatPKCS12Password shows how to change an ASCII string containing a single-character representation to a multibyte BMPString.

typedef struct SECRET_CONTENT SECRET_CONTENT

Represents the contents of a PKCS #12 secret bag. It consists of a secret type-identifier and a secret value.
Parameters:

type An ITEM structure that indicates the type of secret in value. The types are defined by your application.

value An ITEM structure that specifies the value of a secret. This value is not processed by Cert-C, but is taken with no change.

Function Documentation

int C_ExportPKCS12 ( CERTC_CTX ctx,

NAME_OBJ subjectName,

CERT_PATH_CTX * pathCtx,

int encType,

int digestType,

int iterations,

int option,

char * pkcs12fileName,

ITEM * macPassword,

...

) ;

Exports key materials corresponding to a specified subject name. If the PKCS12_USE_TWO_PASSWORDS bit is set, the macPassword is used as the password to verify the message integrity, and an optional argument in the form of a pointer to an ITEM containing the password to decrypt any encrypted data must be supplied. Otherwise, if the bit is not set, any optional arguments will be ignored and the macPassword is used for both integrity checking and decryption.
Note: Netscape Navigator and Microsoft Internet Explorer cannot currently import keys that use separate passwords for the MAC and encryption.
Parameters:

ctx This input parameter is the Cert-C context.

subjectName This input parameter is a NAME_OBJ that identifies certificates.

pathCtx This input parameter is a pointer to a CERT_PATH_CTX object that specifies the certification path.

encType This input parameter is the encryption type, such as RC2_CBC_128BIT.

digestType This input parameter is the digest type, such as DAI_SHA1.

iterations This input parameter is the number of MAC iterations.

option This input parameter contains any desired option flags.

pkcs12fileName This input parameter contains the PKCS #12 filename.

macPassword This input parameter is a pointer to the PKCS #12 MAC password, and possibly to the encryption password, if the PKCS12_USE_TWO_PASSWORDS bit is not set.

int C_ImportPKCS12 ( CERTC_CTX ctx,

char * pkcs12fileName,

ITEM * macPassword,

SERVICE db,

int flags,

...

) ;

Imports the contents of a PKCS #12 file into local storage. If the PKCS12_USE_TWO_PASSWORDS bit is set, the macPassword is used as the password to verify the message integrity. An optional argument in the form of a pointer to an ITEM containing the password to decrypt any encrypted data must be supplied. Otherwise, if the bit is not set, any optional arguments are ignored and the macPassword will be used for both integrity checking and decryption.
Note: When importing from a PKCS#12 file which contains only a DSA private keyand no corresponding certificate in the key bag, the key is inserted into the database in the X9.57 specified format. This situation occurs rarely. It occurs because C_ImportPKCS12() relies on C_ReadFromPKCS12() to parse and decode the PKCS#12 file and the original key format information is lost before the insert operation executes. There will be no problems selecting the key if the user later acquires a certificate whose SPKI value is also in the X9.57 format. However, if the certificate's SPKI format is the OIW secsig-specified format, C_SelectPrivateKeyByCert() does not select the key successfully. If the first key search fails, reformat the SPKI in the X9.57 format with Crypto-C and then repeat the search with C_SelectPrivateKeyBySPKI().
Parameters:

ctx This input parameter is the Cert-C context.

pkcs12fileName This input parameter is the PKCS #12 filename.

macPassword This input parameter is the PKCS #12 MAC password, and possibly the encryption password, if the PKCS12_USE_TWO_PASSWORDS bit is not set.

db This input parameter is the database service.

flags This input parameter contains any desired option flags.

int C_ReadFromPKCS12 ( CERTC_CTX ctx,

STREAM pkcs12Stream,

ITEM * macPassword,

int flags,

LIST_OBJ pkcs12Contents,

...

) ;

Reads keys, certificate chains, and CRLs from a PKCS #12 file. If the PKCS12_USE_TWO_PASSWORDS bit is set, the macPassword is used as the password to verify the message integrity. An optional argument must be supplied, in the form of a pointer to an ITEM containing the password to decrypt any encrypted data. Otherwise, if the bit is not set, any optional arguments will be ignored and the macPassword is used for both integrity checking and decryption.
Parameters:

ctx This input parameter is the Cert-C context.

pkcs12Stream This input parameter is a pointer to the PKCS #12 file stream.

macPassword This input parameter is a pointer to the PKCS #12 MAC password, and possibly to the encryption password, if the PKCS12_USE_TWO_PASSWORDS bit is not set.

flags This input parameter contains any desired option flags.

pkcs12Contents This output parameter holds the contents of the PKCS #12 file.

int C_WriteToPKCS12 ( CERTC_CTX ctx,

LIST_OBJ pkcs12Contents,

int encType,

int digestType,

int iterations,

int option,

ITEM * macPassword,

STREAM pkcs12Stream,

...

) ;

Writes keys, certificates, and CRLs to a stream. If the PKCS12_USE_TWO_PASSWORDS bit is set, the macPassword is used as the password to verify the message integrity. An optional argument must be supplied, in the form of a pointer to an ITEM containing the password to decrypt any encrypted data. Otherwise, if the bit is not set, any optional arguments will be ignored and the macPassword is used for both integrity checking and decryption.
Note: Netscape Navigator and Microsoft Internet Explorer cannot currently import keys that use separate passwords for the MAC and encryption.
Parameters:

ctx This input parameter is the Cert-C context.

pkcs12Contents This input parameter holds the contents of a PKCS #12 file.

encType This input parameter is the encryption type, such as RC2_CBC_128BIT.

digestType This input parameter is the digest type, such as DAI_SHA1.

iterations This input parameter is the number of MAC iterations.

option This input parameter contains any desired option flags.

macPassword This input parameter is a pointer to the PKCS #12 MAC password, and possibly to the encryption password, if the PKCS12_USE_TWO_PASSWORDS bit is not set.

pkcs12Stream This output parameter is the PKCS #12 stream.

Variable Documentation

LIST_OBJ_ENTRY_HANDLER PKCS12BagEntryHandler

A LIST_OBJ_ENTRY_HANDLER that is used to create a LIST_OBJ that contains a list of PKCS12_BAG structures. Use these structures with the C_ReadFromPKCS12() and C_WritetoPKCS12() functions.

RSA BSAFE^® Cert-C 2.7 API Reference

Data Structures
	KEY_CONTENT
	Represents the contents of a PKCS #12 key bag. More...
	PKCS12_BAG
	Represents a safe bag used in a PKCS #12 file. More...
	SECRET_CONTENT
	Represents the contents of a PKCS #12 secret bag. More...
Defines
#define	PKCS12_NO_MAC_VERIFICATION
	When this flag is set, integrity checking on the PKCS #12 contents (PFX MacData) is not performed. More...
#define	PKCS12_MS_EXPLORER
	When this flag is set, Cert-C will use the Microsoft Internet Explorer format. More...
#define	PKCS12_NS_NAVIGATOR
	If this value is specified, Cert-C will use the Netscape Navigator format, except that Cert-C will use DER encoding instead of indefinite-length BER encoding. More...
#define	PKCS12_USE_TWO_PASSWORDS
	When this flag is set, separate passwords will be used for MAC verification and for decryption. More...
Typedefs
typedef KEY_CONTENT	KEY_CONTENT
	Represents the contents of a PKCS #12 key bag. More...
typedef CERT_OBJ	CERT_CONTENT
	A `CERT_OBJ` that contains a PKCS #12 certificate bag.
typedef CRL_OBJ	CRL_CONTENT
	A `CRL_OBJ` that contains a PKCS #12 CRL bag.
typedef SECRET_CONTENT	SECRET_CONTENT
	Represents the contents of a PKCS #12 secret bag. More...
typedef PKCS12_BAG	PKCS12_BAG
	Represents a safe bag used in a PKCS #12 file. More...
Functions
int	C_ImportPKCS12 (CERTC_CTX ctx, char pkcs12fileName, ITEM macPassword, SERVICE db, int flags,...)
	Imports the contents of a PKCS #12 file into local storage. More...
int	C_ReadFromPKCS12 (CERTC_CTX ctx, STREAM pkcs12Stream, ITEM *macPassword, int flags, LIST_OBJ pkcs12Contents,...)
	Reads keys, certificate chains, and CRLs from a PKCS #12 file. More...
int	C_ExportPKCS12 (CERTC_CTX ctx, NAME_OBJ subjectName, CERT_PATH_CTX pathCtx, int encType, int digestType, int iterations, int option, char pkcs12fileName, ITEM *macPassword,...)
	Exports key materials corresponding to a specified subject name. More...
int	C_WriteToPKCS12 (CERTC_CTX ctx, LIST_OBJ pkcs12Contents, int encType, int digestType, int iterations, int option, ITEM *macPassword, STREAM pkcs12Stream,...)
	Writes keys, certificates, and CRLs to a stream. More...
Variables
LIST_OBJ_ENTRY_HANDLER	PKCS12BagEntryHandler
	A `LIST_OBJ_ENTRY_HANDLER` that is used to create a `LIST_OBJ` that contains a list of `PKCS12_BAG` structures. More...