CL_CertVerify

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 1:...

API Functions

CL_CertSign

CL_CertVerifyWithKey

CL_CertVerify

Library
Description
Errors

Parameters
Return Value
See Also

NAME

CL_CertVerify: CSSM_CL_CertVerify - Verify a signed certificate (CDSA)

SYNOPSIS

# include <cssm.h>

API:
CSSM_RETURN CSSMAPI CSSM_CL_CertVerify
(CSSM_CL_HANDLE CLHandle,
CSSM_CC_HANDLE CCHandle,
const CSSM_DATA *CertToBeVerified,
const CSSM_DATA *SignerCert,
const CSSM_FIELD *VerifyScope,
uint32 ScopeSize)
SPI:
CSSM_RETURN CSSMAPI CSSM_CL_CertVerify
(CSSM_CL_HANDLE CLHandle,
CSSM_CC_HANDLE CCHandle,
const CSSM_DATA *CertToBeVerified,
const CSSM_DATA *SignerCert,
const CSSM_FIELD *VerifyScope,
uint32 ScopeSize)

LIBRARY

Common Security Services Manager library (cdsa$incssm300_shr.exe)

PARAMETERS

`CLHandle` (input)
		The handle that describes the add-in certificate library module used to perform this function.
`CCHandle` (input/optional)
		The handle that describes the context of this cryptographic operation.
`CertToBeVerified` (input)
		A pointer to the CSSM_DATA structure with a certificate containing at least one signature for verification. An unsigned certificate template cannot be verified.
`SignerCert` (input/optional)
		A pointer to the CSSM_DATA structure containing the certificate used to sign the subject certificate. This certificate provides the public key to use in the verification process and if the certificate being verified contains multiple signatures, the signer's certificate indicates which signature is to be verified.
`VerifyScope` (input/optional)
		A pointer to the CSSM_FIELD array containing the tag/value pairs of the fields to be used in verifying the signature. (This should include all fields that were used to calculate the signature.) If the verify scope is null, the certificate library module assumes that its default set of certificate fields were used to calculate the signature, and those same fields are used in the verification process.
`ScopeSize` (input)
		The number of entries in the verify scope list. If the verification scope is not specified, the input value for scope size must be zero.

DESCRIPTION

This function verifies that the signed certificate has not been altered since it was signed by the designated signer. Only one signature is verified by this function. If the certificate to be verified includes multiple signatures, this function must be applied once for each signature to be verified. This function verifies a digital signature over the certificate fields specified by VerifyScope. If the verification scope fields are not specified, the function performs verification using a preselected set of fields in the certificate.

The caller can specify a Cryptographic Service Provider (CSP) and verification algorithm that the CL can use to perform the verification. The handle for the CSP is contained in the cryptographic context identified by CCHandle.

The verification process requires that the caller must specify the necessary verification algorithm parameters. These parameter values are specified in one of two locations:

As a field value in the SignerCert parameter

As a set of algorithm parameters contained in the cryptographic context identified by CCHandle

If both of the preceding arguments are supplied, a consistency check is performed to ensure that they result in the same verification algorithm parameters. If they are not consistent, an error is returned. If only one of the above arguments is supplied, that argument is used to generate the verification algorithm parameters. If no algorithm parameters are found, the certificate cannot be verified and the operation fails.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

Errors are described in the CDSA Technical Standard.

CSSMERR_CL_INVALID_CONTEXT_HANDLE
CSSMERR_CL_INVALID_CERT_POINTER
CSSMERR_CL_UNKNOWN_FORMAT
CSSMERR_CL_INVALID_FIELD_POINTER
CSSMERR_CL_UNKNOWN_TAG
CSSMERR_CL_INVALID_SCOPE
CSSMERR_CL_INVALID_NUMBER_OF_FIELDS
CSSMERR_CL_SCOPE_NOT_SUPPORTED
CSSMERR_CL_VERIFICATION_FAILURE