Syntax

   #include "NPKIT_Verify.h"
   
   NWRCODE NPKIT_VerifyCertChain
   (
      NPKI_CertChain            *certificates,
      nuint32                    flags,
      pnuint32                   cRLReason,
      pnuint32                   cRLHoldInstruction,
      time_t                    *cRLRevocationTime,
      time_t                    *cRLInvalidityDateTime,
      NPKI_CertChain           **revokedCertificate,
      pnuint32                   certInvalidityReason,
      NPKIT_CRLCacheContext      CRLCacheContext,
      void                      *reserved1,
      void                      *reserved2,
      void                      *reserved3,
      void                      *reserved4
   );
   

Parameters

certificates

(IN) Points to the linked list of NPKI_CertChain structures, each of which contains an X.509 DER encoded certificate which is to be verified. The linked list of certificates must be in leaf to root order and the last certificate, in the list, is assumed to be a trusted certificate. (If the last certificate has a CRL Distribution Point extension, it must be a self-signed certificate.)

flags

(IN) Specifies whether to verify the certificate, certificate revocation, both, or neither. Use one or more of the following flags:

• NPKI_VERIFY_NORMAL
• NPKI_VERIFY_DONT_CHECK_CERTIFICATE
• NPKI_VERIFY_DONT_CHECK_CRL

For more information, see Section 4.5, NPKI_VerifyCallBackStruct Flag Values.

cRLReason

(OUT) If the certificate has been revoked, specifies the reason code from the CRL (that is, private key compromised, affiliate change, superseded, etc.). This parameter is only set if the return code is PKI_E_CERT_INVALID and the certInvalidityReason is set to NPKIx509Invalid_Certificate_On_CRL. For more information, see Section 4.7, NPKIT_x509 Certificate Invalidity Reason Flags.

cRLHoldInstruction

(OUT) If the certificate has been revoked, specifies the hold instruction from the CRL. This parameter is only set if the return code is PKI_E_CERT_INVALID, the certInvalidityReason is set to NPKIx509Invalid_Certificate_On_CRL, and the cRLReason is set to PKI_CERTIFICATE_HOLD. The possible values for cRLHoldInstruction are:

• PKI_HOLD_INSTRUCTION_NONE
• PKI_HOLD_INSTRUCTION_CALL_ISSUER
• PKI_HOLD_INSTRUCTION_REJECT

For more information, see Section 4.9, NPKIT_x509 CRL Hold Types.

cRLRevocationTime

(OUT) Points to the time the certificate became invalid. This parameter only set if the return code is PKI_E_CERT_INVALID and the certInvalidityReason is set to NPKIx509Invalid_Certificate_On_CRL.

cRLInvalidityDateTime

(OUT) Points to the time the CRL becomes invalid.

revokedCertificate

(OUT) Points to the node in the linked list of NPKI_CertChain structures that contains the invalid certificate. This parameter only set if the return code is PKI_E_CERT_INVALID.

certInvalidityReason

(OUT) Reason why the certificate is invalid. This will only be set if the return code is set to PKI_E_CERT_INVALID.

CRLCacheContext

(OUT) Reserved for future use. Pass in NULL.

reserved1

(OUT) Reserved for future use. Pass in NULL.

reserved2

(OUT) Reserved for future use. Pass in NULL.

reserved3

(OUT) Reserved for future use. Pass in NULL.

reserved4

(OUT) Reserved for future use. Pass in NULL.

Return Values

Returns 0 if successful or a NICI or PKI error code if not successful. For a listing of NPKIT error codes, see Certificate Server Error Code Constants.

Remarks

The certificate chain must be in leaf to root order. The last certificate in the chain is assumed to be trusted. If any certificate is invalid (that is, revoked or expired), this function returns an error. You must allocate and deallocate all the certificate chain structures and data.

See Also

NPKIT_VerifyCertificate, NPKIT_VerifyCertChainWithCallback