NAME

CL_CertGroupFromVerifiedBundle

SYNOPSIS

CSSM_BOOL CSSMCLI CL_CertGroupFromVerifiedBundle
    (CSSM_CL_HANDLE CLHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CERT_BUNDLE_PTR CertBundle,
    const CSSM_DATA_PTR SignerCert,
    CSSM_CERTGROUP_PTR *CertGroup);

DESCRIPTION

This function accepts as input a certificate bundle (a codified and signed aggregation of the certificates in the group), verifies the signature of the bundle (if a signature is present) and returns a certificate group (as an array of individual certificates) including every certificate contained in the bundle. The signature on the certificate aggregate is verified using the cryptographic context and possibly using the input signer certificate. The CL module embeds the knowledge of the verification scope for the bundle types that it supports. A CL module's supported bundle types and encodings are available to applications by querying the CSSM registry. The type and encoding of the certificate bundle must be specified with the input bundle. If signature verification is successful, the certificate aggregate will be parsed into a certificate group whose order corresponds to the certificate aggregate ordering. This certificate group will then be returned to the calling application.

PARAMETERS

CLHandle (input)

The handle of the add-in module to perform this operation.

CCHandle (input)

The handle of the cryptographic context to control the verification operation.

CertBundle (input)

A structure containing a reference to a signed, encoded bundle of certificates, and to descriptors of the type and encoding of the bundle. The bundled certificates are to be separated into a certificate group (list of individual encoded certificates). If the bundle type and bundle encoding are not specified, the add-in module may either attempt to decode the bundle assuming a default type and encoding or may immediately fail.

SignerCert (input/optional)

The certificate to be used to verify the signature on the certificate bundle. If the bundle is signed but this field is not specified, then the module will assume a default certificate for verification.

CertGroup (output)

A pointer to the certificate group, represented as an array of individual, encoded certificates. The group contains all of the certificates contained in the certificate bundle.

RETURN VALUE

A CSSM_BOOL value corresponding to the result of the verification process. If a signature is required for this type of bundle and signature verification fails, the function returns CSSM_FALSE. If signature verification is required and succeeds, the function returns CSSM_TRUE and attempts to create a certificate group containing all certificates in the bundle. If the group cannot be created, the CertGroup is set to NULL and an error code is set. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_CL_INVALID_CL_HANDLE

Invalid Certificate Library Handle

CSSM_CL_INVALID_CC_HANDLE

Invalid context handle

CSSM_CL_INVALID_BUNDLE_INFO

Unknown bundle type or encoding

CSSM_CL_INVALID_SIGNER_CERTIFICATE

Revoked or expired signer certificate

CSSM_CL_INVALID_DATA_POINTER

Invalid pointer input

CSSM_CL_MEMORY_ERROR

Error allocating memory

CSSM_CL_CERGROUPFROMBUNDLE_FAIL

Unable to create the cert group

SEE ALSO

CL_CertGroupToSignedBundle