NAME

CL_CertRequest

SYNOPSIS

CSSM_RETURN CSSMCLI CL_CertRequest
    (CSSM_CL_HANDLE CLHandle,
    CSSM_SUBSERVICE_UID CSPSubserviceUid,
    const CSSM_FIELD_PTRSubjectCertTemplate,
    uint32 NumberOfFields,
    const CSSM_DATA_PTR CACert,
    const CSSM_FIELD_PTR SignScope,
    uint32 ScopeSize,
    const CSSM_NET_ADDRESS_PTR CALocation,
    CSSM_CA_SERVICES MoreServiceRequests,
    const CSSM_USER_AUTHENTICATION_PTR UserAuthentication,
    sint32 *EstimatedTime,
    const CSSM_DATA_PTR ReferenceIdentifier)

DESCRIPTION

This function submits a certificate creation request to a Certificate Authority (CA) process identified by the SignerCert. The CA process may be local or remote. The CL module incorporates knowledge of the name, location, and interface protocol for communicating with the CA. The certificate fields provide the initial values for the certificate. The CA can add other default values known only to the CA.

As the certificate issuer, the CA process signs the new certificate. If the signer's certificate is not specified in this function, the CA assumes a default signing certificate it uses to issue certificates. The SignScope defines the set of certificate fields to be included in the signing process. The signing operation may be performed locally or remotely. The caller specifies the CSP to be used for storing the private key. This same CSP may optionally be used for cryptographic operations. The CL module is responsible for creating and destroying all cryptographic contexts required to perform these operations.

The caller can request additional certificate-creation-related services from the CA. These requests are designated by the MoreServiceRequests bit mask. CSSM-defined bit masks allow the caller to request certificate and key archival, certificate registration with a directory service, certificate renewal notification, and other services. CAs are not required to provide such services. The CL module works with the CA process to provide the requested services.

The caller is required to provide authentication information so the CA process can determine whether the caller is authorized to request a certificate. The specific format of the credential is specified by the CL module. The caller can query the CL Module Info structure to obtain this information.

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

CLHandle (input)

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

CSPSubserviceUid (input)

The identifier which uniquely describes the add-in CSP module subservice 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.

SubjectCertTemplate (input)

A pointer to an array of OID/Value pairs providing the initial values for the certificate.

NumberOfFields (input)

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

CACert (input/optional)

A pointer to the CSSM_DATA structure containing the desired Certification Authority's signing certificate. If the CACert is NULL, the CL module or the CA process can provide a default signing certificate.

SignScope (input/optional)

A pointer to the CSSM_FIELD array containing the OID/value pairs specifying the certificate fields to be signed. When the input value is NULL, the CL assumes and includes a default set of certificate fields in the signing process.

ScopeSize (input)

The number of entries in the sign scope list. If no signing scope is specified, then the scope size must be zero.

CALocation (input/optional)

A pointer to a network address directly or indirectly identifying the location of the CA process. If the input is NULL, the module can determine a CA process and its location based on the SignerCert input parameter or can assume a default CA process location. If SignerCert is not specified and a default cannot be assumed, the request cannot be initiated and the operation fails.

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 archival of the certificate's private key, publication of the certificate in a certificate directory service, request out-of-band notification of the need to renew this certificate, or request other services.

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 CL and recorded in the CLSubservice structure describing this module. If the supplied information is insufficient, additional information can be provided by the substructure field MoreAuthenticationData. This field contains an immediate data value or a callback function to collect additional information from the user. If authentication 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.

ReferenceHandle (output)

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

RETURN VALUE

A CSSM_OK return value signifies the requested operation has proceeded and that CL_CertRetrieve should be called (after the specified amount of time) in order to retrieve the results. If CSSM_FAIL is returned, an error has occurred. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_CL_INVALID_CL_HANDLE

Invalid Certificate Library Handle.

CSSM_CL_INVALID_CSP_HANDLE

Invalid CSP Handle.

CSSM_CL_INVALID_DATA_POINTER

Invalid pointer input.

CSSM_CL_UNKNOWN_FORMAT

Unrecognized certificate format.

CSSM_CL_INVALID_SIGNER_CERTIFICATE

Revoked or expired signer certificate.

CSSM_CL_INVALID_SCOPE

Invalid scope.

CSSM_AUTHENTICATION_FAIL

Invalid/unauthorized credential.

CSSM_CL_MEMORY_ERROR

Not enough memory.

CSSM_CL_CERT_REQUEST_FAIL

Unable to submit certificate creation request.

SEE ALSO

CL_CertRetrieve, CL_CertVerify