NAME

CSSM_TP_CertRequest

SYNOPSIS

CSSM_DATA_PTR CSSMAPI CSSM_TP_CertRequest
    (CSSM_TP_HANDLE TPHandle,
    CSSM_CL_HANDLE CLHandle,
    CSSM_SUBSERVICE_UID CSPSubserviceUid,
    const CSSM_FIELD_PTR CertFields,
    uint32 NumberOfFields,
    const CSSM_FIELD_PTR PolicyIdentifier,
    uint32 NumberOfPolicyIdentifiers,
    CSSM_CA_SERVICES MoreServiceRequests,
    const CSSM_USER_AUTHENTICATION_PTR UserAuthentication,
    sint32 *EstimatedTime,
    const CSSM_DATA_PTR ReferenceIdentifier)

DESCRIPTION

If the caller is authorized to create a new certificate, this function creates a template for a new certificate and requests certificate creation from a certification authority process. The certificate template is determined by the policies defined by the policy identifiers. The template is initialized with values from the input OID/value pairs and any default values determined by the selected policies. The template is forwarded to a certification authority for processing.

The CSPSubserviceUid uniquely identifies the cryptographic service provider that must store the private key associated with the new certificate.

This function returns a ReferenceIdentifier and an EstimatedTime (specified in seconds). The estimate time defines the expected certificate creation time. This time may be substantial when certificate issuance requires offline authentication procedures by the CA process. In contrast, the estimated time can be zero, meaning the certificate can be obtained immediately. After the specified time has elapsed, the caller must use the CL module interface CSSM_CL_CertRetrieve, with the reference identifier, to obtain the signed certificate.

PARAMETERS

TPHandle (input)

The handle that describes the add-in trust policy module used to perform this function.

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

CSPSubserviceUid (input)

The persistent ID identifying the add-in CSP module where the private key is to be stored. Optionally the CL module can use this CSP to perform additional cryptographic operations or may use another default CSP for that purpose.

CertFields (input)

A pointer to an array of OID/value pairs that identify the field values as initial values in the new certificate.

NumberOfFields (input)

The number of certificate field values being input. This number specifies the number of entries in the CertFields array.

PolicyIdentifier (input/optional)

The policy identifier to be enforced when creating the Certificate template. This identifies which certificate template should be initialized and controls initialization, including the specification of required fields, and default field values. If no policy identifier is provided as input, the TP module assumes a default policy and initializes the certificate template associated with that policy.

NumberOfPolicyIdentifiers (input)

The number of policy domains in which generated certificate template should be valid. This number specifies the number of entries in the PolicyIdentifier array.

MoreServiceRequests (input/optional)

A bit mask requesting additional certificate-creation-related services from the Certificate Authority issuing the certificate. CSSM-defined bit masks allow the caller to request backup or archive of the certificate's private key, publication of the certificate in a certificate directory service, and request out-of-band notification of the need to renew this certificate.

UserAuthentication (input/optional)

A pointer to the CSSM_USER_AUTHENTICATION structure containing the authentication information to be used in association with this request. The authentication information may be a pass-phrase, a PIN, a completed registration form, a Certificate to facilitate a signing operation, and so on- depending on the context of the request. The required format for this credential is defined by the TP and recorded in the TPSubservice structure describing this module. If the information provided is insufficient, additional information can be obtained from the substructure field named MoreAuthenticationData. This field contains an immediate data value or a callback function to collect additional information from the user. If additional information is not required, this parameter must be NULL.

EstimatedTime (output)

The number of seconds estimated before the signed certificate will be ready to be retrieved. A (default) value of zero indicates that the signed certificate can be retrieved immediately via the corresponding CL_CertRetrieve function call. When the certification process cannot estimate the time required to sign the certificate, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.

ReferenceIdentifier (output)

A reference identifier which uniquely identifies this specific request. The handle persists across application executions until it is terminated by the successful or failed completion of the CSSM_TP_CertRetrieve function.

RETURN VALUE

A pointer to the CSSM_DATA structure containing the unsigned certificate template. If the return pointer is NULL, an error has occurred. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_INVALID_TP_HANDLE

Invalid Trust Policy Library Handle.

CSSM_INVALID_CL_HANDLE

Invalid Certificate Library Handle.

CSSM_TP_INVALID_FIELD_POINTER

Invalid pointer input.

CSSM_TP_INVALID_OID

Invalid attribute OID for this cert type.

CSSM_TP_MEMORY_ERROR

Not enough memory.

CSSM_TP_AUTHENTICATION_FAIL

Caller is not authorized for operation.

SEE ALSO

CSSM_TP_CertRetrieve, CSSM_CL_CertRequest,
CSSM_CL_CertRetrieve