validate_certificate

If a PKCS7 container is provided, pem and chain are ignored.

If chain is given but pem is not, the first item of the given array is taken as entity, the remaining certificates are used to build the chain. The recommended use is to pass the entity via pem and any extra chain certificates via chain, where chain can be omitted if the required chain certificates are all in the database.

If anchor is set, the resulting chain is tested against the list. If any of the given certificates is found in the chain, the result is TRUSTED. Otherwise it is UNTRUSTED.

The return value is a HashRef:

    {
        status => '...',    # validation result
        chain => [ ... ],   # full certificate chain starting with the entity
    }

"status" can be one of:

• VALID - only if "anchor" is NOT given: certificate chain can be build and ends with a root certificate held inside the database.
• BROKEN - broken certificate chain (e.g. expired certificates)
• REVOKED - chain contains a revoked certificate (revocation status is considered for certificates in local database only!)
• NOROOT - root certificate not found
• UNTRUSTED - chain can be build but root certificate is not in local database, if "anchor" is given: chain does not match trust list
• TRUSTED - only if "anchor" is given: chain is valid and matches trust list.

Parameters

• "pem" Str - PEM encoded certificate (Str)
• "chain" ArrayRef - full certificate chain (list of PEM encoded certificates)
• "pkcs7" Str - PEM encoded PKCS7 container
• "anchor" ArrayRef - list of trust anchors (certificate identifiers).
• "novalidity" Bool - treat expired certificates as good
• "crl_check" Str - one of none, soft, leaf, all

CRL Check

For certificates that are managed by this PKI instance, the revocation status is ALWAYS checked based in the information in the database.

If you want to validate externally issued certificates, you can pass the crl_check parameter with one of the following values (default is none). There is currently no special return value for CRL checks, failure to validate will just return the status "BROKEN".

none

Do not perform a CRL check, this is the default.

soft

Tries to find a valid CRL for the leaf certificate but will silently skip the revocation check if no CRL is found.

leaf

Tries to find a valid CRL for the leaf certificate, will throw an exception if there is no fresh CRL information.

all

Tries to find a valid CRL for all certifiates in the chain, will throw an exception if there is no fresh CRL information for any element.

Changes compared to API v1:

The new parameter "chain" is used to specify a chain (instead of passing an ArrayRef to "PEM"):

    CTX('api')->validate_certificate(PEM   => [ .. ]); # old
    CTX('api2')->validate_certificate(chain => [ .. ]); # new

The previously unused parameter "NOCRL" was removed.