NAME

CL_CertMultiSignRequest

SYNOPSIS

CSSM_RETURN CSSMCLI CL_CertMultiSignRequest
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA_PTR SubjectCert,
    const CSSM_DATA_PTR CACert,
    uint32 NumberOfCACerts,
    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 request to a Certificate Authority (CA) process to add one or more signatures to an existing certificate. This could be a notary public service or a simple multiple signature facility. 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 CA process performs the signaturing operation once for each specified signer certificate. The signing operation may be performed locally or remotely. The CA must have access to the private keys associated with the signer certificates. If no signer's certificate is specified, the CA can assume one or more default signing certificates it uses for a multi-signing service. If no defaults are defined, the CA can reject the request.

The CL module selects and uses a default CSP to perform any required cryptographic operations. The CL module is responsible for creating and destroying all cryptographic contexts required to perform these operations.

The SignScope defines the set of certificate fields in the Subject Cert that are to be included in the signing process.

The caller can request additional signing-related services from the CA. These requests are designated by the MoreServiceRequests bit mask. CSSM-defined bit masks allow the caller to request full notary public services, and re-publishing of the new multiply-signed certificate with all directory services holding a copy of the old certificate. CAs are not required to provide such services. The CL module works with the CA process to provide the requested services.

This function returns a ReferenceIdentifier and an EstimatedTime (specified in seconds). The estimate time defines the expected signing time. This time may be substantial when the multiple signature model requires off-line procedures (such as a notary public). In contrast, the estimated time can be zero, meaning the multiply-signed certificate can be obtained immediately. After the specified time has elapsed, the caller must use the CL module interface CSSM_CL_CertMultiSignRetrieve, with the reference identifier, to obtain the multiply-signed certificate.

PARAMETERS

CLHandle (input)

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

SubjectCert (input)

A pointer to the CSSM_DATA structure containing the certificate to be signed multiple times.

CACerts (input/optional)

A pointer to an array of one or more CSSM_DATA structures containing the signing certificates of the desired Certification Authorities. If CACerts is NULL, the CL module or the CA process can provide a default set of signing certificates.

NumberOfCACerts (input)

The number of CA signing certificates presented in the CACerts array. If no CA certificates are specified, the value of this parameter must be zero.

SignScope (input/optional)

A pointer to the CSSM_FIELD array containing the OID/value pairs specifying the certificate fields to be included in the signature calculation. 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 signing-related services from the Certificate Authority performing this function.

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, an 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 multiply-signed certificate will be ready to be retrieved. A (default) value of zero indicates that the certificate can be retrieved immediately via the corresponding CL_CertRetrieve function call. When the signing authority 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 successful or failed completion of the CSSM_CL_MultiSignRetrieve function.

RETURN VALUE

A CSSM_OK return value signifies the requested operation has proceeded and that CL_CertMultiSignRetrieve 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_CL_MEMORY_ERROR

Not enough memory.

CSSM_CL_SIGN_REQUEST_FAIL

Unable to submit certificate signing request.

SEE ALSO

CL_CertMultiSignRetrieve