NAME

CSSM_CL_CertRequest

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_CL_CertRequest
    (CSSM_CL_HANDLE CLHandle,
    CSSM_SUBSERVICE_UID CSPSubserviceUid, /* a unique id for the 
                                        CSP subservice */
    const uint32 SubServiceId, /* sub service Id for the CSP */
    const CSSM_FIELD_PTR SubjectCertTemplate,
    uint32 NumberOfFields,
    const CSSM_DATA_PTR CACert,
    const CSSM_FIELD_PTR SignScope,
    uint32 ScopeSize,
    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. The CA process is identified by the SignerCert. The caller can obtain the certificate for all of the certification authorities supported by the CL by querying the CSSM registry for the CL's CA information.The CA process may be local or remote. The certificate fields provides 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 may specify the CSP to 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 so on. 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.

SubServiceId (input/optional)

The sub-service number identifying the CSP sub-service to use when storing the private key associate with the certificate in the local CSP. If the CSP supports only one sub-service or the CL module assumes a default sub-service of a CSP, then the sub-service identifier can be omitted.

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 CACert input parameter or can assume a default CA process location. If a CACert 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 archive 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, and so on.

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 named MoreAuthenticationData. This field contains an immediate data value or a callback function to collect additional information from the user. If other 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_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

CSSM_CL_CertRetrieve, CSSM_CL_CertVerify