NPKICertificateList

Stores a certificate (such as, X.509) or set of certificates (such as, PKCS #7) to an internal structure.

Syntax

    #include "npki.h"
    
    NWRCODE NPKICertificateList(
       const NPKIContext   context, 
       const pnuint8       certificate, 
       const nuint32       certificateLen,
       const nuint32       flags,
       pnuint32            numberOfCertsInList);

Parameters

context
(IN) Specifies the NPKI context for the request.
certificate
(IN) Specifies the X.509 certificate or PKCS #7 certificate set to be acted upon.
certificateLen
(IN) Specifies the length in bytes of certificate.
flags
(IN) Specifies the task to preform on the certificate being passed in. Use one or more of the following flags:
  • PKI_ADD_CERT—Used when a certificate is being added to the certificate list. This flag can be used alone or with PKI_SORT_LIST. Using this flag with PKI_DEL_CERT causes an error.
  • PKI_DEL_CERT—Used when a certificate is removed from the certificate list. The parameter certificate must point to a valid X.509 DER-encoded certificate. This flag can be used alone or with PKI_SORT_LIST. Using this flag with PKI_ADD_CERT causes an error
  • PKI_CLEAR_CERTS—Used to delete all the certificates that have been stored with previous calls to NPKICertificateList. The certificate parameter should be NULL. This flag must be used alone.
  • PKI_SORT_LIST—Used to sort this list of certificates. PKI_E_BROKEN_CHAIN is returned if the certificates do not form a complete chain. This flag can be used with either PKI_ADD_CERT or PKI_DEL_CERT. When used alone, certificate can be NULL.
numberOfCertsInList
(OUT) Specifies the number of certificates in the list.

Return Values

Returns 0 if successful, or a PKI error code if not successful.

Remarks

Each call to NPKICertificateList can store, remove, and/or sort the internal certificate chain structure. A subsequent call to NPKIStoreServerCertificatesFromCertificateList stores the chain of certificates to a Key Material Object (KMO).

When creating a server certificate in a multi-server environment for a server that does not host the CA, calling NPKICreateServerCertificate just creates the KMO (that is, it does not store the certificate or certificate chain). After a successful call to NPKICreateServerCertificate, call NPKICertInfo to get the object certificate that was just created. Call NPKICertificateList with the flag PKI_CLEAR_CERTS to make sure the internal certificate list is cleared.

Add the object certificate to the certificate list by calling NPKICertificateList and passing in the object certificate, object certificate length, and the flag PKI_ADD_CERT. Call NPKIGetCACertificates to get the self-signed certificate. Add this to the certificate list. When all certificates have been added and a complete chain has been assembled, call NPKIStoreServerCertificatesFromCertificateList to store the certificates in the list to the KMO.

See Also