Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages
OpenXPKI::Server::API2::Plugin::Cert::validate_certificate(3) User Contributed Perl Documentation OpenXPKI::Server::API2::Plugin::Cert::validate_certificate(3)


Validate a certificate by creating the chain, extra certificates passed via chain or in a pkcs7 container are used together with the certificates held in the database.

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.


  • "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".

Do not perform a CRL check, this is the default.
Tries to find a valid CRL for the leaf certificate but will silently skip the revocation check if no CRL is found.
Tries to find a valid CRL for the leaf certificate, will throw an exception if there is no fresh CRL information.
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.

2022-05-14 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.