NAME

TP_CertRequest

SYNOPSIS

CSSM_DATA_PTR CSSMTPI 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

This function determines whether or not the caller is authorized to create a new certificate. Trust is determined by the UserAuthentication information and the policy domains requested by the identifiers. If authorized the specified certificate library module should be used to create a new certificate.

The initial certificate values provided by the caller can be augmented with default values defined by the selected policy domains. The complete set of initial values must be 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). These values can be obtained from the companion function supported by the certificate library module.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 will use the reference identifier when calling CSSM_TP_CertRetrieve, to obtain the signed certificate. The reference identifier must persist across any number of application and library executions until this two step operation is completed by the CSSM_TP_CertRetrieve function. The reference identifier becomes invalid after successful completion or final failure of the CSSM_TP_CertRetrieve function. Successful completion of the CSSM_TP_CertRetrieve function returns a certificate to the caller. Failure returns a response stating that the original request can never be fulfilled.

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 CSPmodule 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. For example, the caller can 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 supplied 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. For example, a pass-phrase may be requested from the end-user in order to authenticate the request. 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 Module 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

TP_CertRetrieve, CSSM_CL_CertRequest, CSSM_CL_CertRetrieve