PKCS#7 Callback Functions

Typedefs
typedef MSTATUS(*	PKCS7_GetCertificate) (const void *arg, CStream cs, struct ASN1_ITEM *pSerialNumber, struct ASN1_ITEM *pIssuerName, ubyte **ppCertificate, ubyte4 *certificateLen)
	Get a certificate for a given issuer name and serial number. More...
typedef MSTATUS(*	PKCS7_GetPrivateKey) (const void *arg, CStream cs, struct ASN1_ITEM *pSerialNumber, struct ASN1_ITEM *pIssuerName, struct AsymmetricKey *pKey)
	Get the private key associated with a given certificate in a PKCS #7 message (CMS message stream). More...
typedef MSTATUS(*	PKCS7_ValidateRootCertificate) (const void *arg, CStream cs, struct ASN1_ITEM *pCertificate, sbyte4 chainLength)
	Validate the certificates in a PKCS #7 message. More...

Detailed Description

Typedef Documentation

PKCS7_GetCertificate

typedef MSTATUS(* PKCS7_GetCertificate) (const void *arg, CStream cs, struct ASN1_ITEM *pSerialNumber, struct ASN1_ITEM *pIssuerName, ubyte **ppCertificate, ubyte4 *certificateLen)

This callback function gets a certificate (that matches a given issuer name and serial number) for a SignedData object whose certificates are external to its data. The PKCS7_VerifySignedData() and PKCS7_VerifySignedDataEx() functions invoke this callback to search for certificates for such SignedData objects.

This callback function should call PKCS_GetCertificates() to search the given CStream, pCertStream, for the first certificate that contains a SignedData object; if none are found, this callback function should then search a private store of certificates. Then you can search for the desired certificate among those found by PCKS_GetCertificates() or among those found in the private store.

pkcs7.h

Parameters

arg	Data that can be passed to the callback.
cs	CStream containing a PKCS #7 message (a ContentInfo object) containing the SignedData object to search for a matching certificate.
pSerialNumber	Pointer to ASN1_ITEM structure containing the certificate serial number of interest. To get this pointer, call X509_getCertificateIssuerSerialNumber() against a certificate that is know to contain the issuer and serial number of interest.
pIssuerName	Pointer to ASN1_ITEM structure containing the issuer name of interest. To get this pointer, call X509_getCertificateIssuerSerialNumber() against a certificate that is known to contain the issuer and serial number of interest.
ppCertificate	On return, pointer to buffer of the matching certificate. If no match is found, the value is NULL (zero).
certificateLen	On return, length of the matching certificate.

Returns

OK (0) under all circumstances.

pkcs7.h

PKCS7_GetPrivateKey

typedef MSTATUS(* PKCS7_GetPrivateKey) (const void *arg, CStream cs, struct ASN1_ITEM *pSerialNumber, struct ASN1_ITEM *pIssuerName, struct AsymmetricKey *pKey)

This callback function searches a given PKCS #7 message (CMS message stream), cs, for a certificate that matches the given serial number and issuer name. To obtain the certificate, you could call the PKCS7_GetCertificate() callback function, which searches both the given CStream, cs, and a private store of certificates. To validate the certificate, call the PKCS7_ValidateRootCertificate() callback function. If the certificate is valid, this callback function (PKCS7_GetPrivateKey()) can get the associated private key.

If the subject's PEM-encoded private key is stored in a file, you can copy the key to an AsymmetricKey structure as follows:

AsymmetricKey key;
ubyte* pemKeyFile = FILE_PATH("key.pem");
ubyte *pPemKey=NULL, *pKeyblob=NULL;
ubyte4 pemKeyLen, keyblobLen;

if (OK > (status = MOCANA_readFile( pemKeyFile, &pPemKey, &pemKeyLen)))
    goto exit;   // at exit, handle error

if (OK > (status = CA_MGMT_convertKeyPEM(pPemKey, pemKeyLen, &pKeyblob, &keyblobLen)))
    goto exit;

if (OK > (status = CRYPTO_initAsymmetricKey( &key)))
    goto exit;

if (OK > (status = CA_MGMT_extractKeyBlobEx(pKeyblob, keyblobLen, &key)))
    goto exit;

Given this code, the callback function returns the private key through the pKey parameter.

pkcs7.h

Parameters

arg	Data that can be passed to the callback.
cs	CStream containing the PKCS 7 message (a ContentInfo object containing a CMS EnvelopedData object) to search.
pSerialNumber	Pointer to ASN1_ITEM structure containing the certificate serial number of interest. To get this pointer, call X509_getCertificateIssuerSerialNumber() against a certificate that is known to contain the issuer and serial number of interest.
pIssuerName	Pointer to ASN1_ITEM structure containing the issuer name of interest. To get this pointer, call X509_getCertificateIssuerSerialNumber() against a certificate that is known to contain the issuer and serial number of interest.
pKey	On return, pointer to the certificate's private key.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

pkcs7.h

PKCS7_ValidateRootCertificate

typedef MSTATUS(* PKCS7_ValidateRootCertificate) (const void *arg, CStream cs, struct ASN1_ITEM *pCertificate, sbyte4 chainLength)

This callback function validates the certificates in a PKCS #7 message.

Which validity checks to perform depends on your application and environment. Typical checks are:

• Validity dates.
• Walking a certificate chain to ensure that each certificate was issued by the next certificate in the chain.
• Ensuring that the last certificate in a chain is trusted.
• For incomplete certificate chains, searching a private store for certificates that could complete the chain.
• Business logic indicating whether access is ok (regardless of the validity of the certificate itself), such as an employee's current status or whether a customer's purchase has enabled a given service/access.

If the Digicert certificate store is being used then look at CERT_STORE_PKCS7_ValidateRootCertificate in mss/src/crypto/cert_store.c on how to use the certificate store to validate a certificate.

(when is this callback invoked?) (is the "top" certificate the root or end-user?)

pkcs7.h

Parameters

arg	Data that can be passed to the callback.
cs	CStream containing the PKCS #7 message.
pCertificate	Pointer to topmost certificate in the certificate chain whether it is the root or not.
chainLength	The lenth of the certificate chain from the current to the topmost parent.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

pkcs7.h