Skip to main content
Version: 7.2405.x.x LTS

Certificate validation

For AuthStates or services that require certificate validation, e.g., whenever a signed token is validated or a client tries to log in via its client certificate, the incoming certificates or certificate chains are verified using the nevisAuth PKI service. In the following chapters, the concepts of certificate validation are explained in detail. Following that, the configuration of the signer material and trusted certificate stores is described.

Certificate path​

The certificate path is a list of certificates that is built by starting at the leaf certificate and finding its way up towards a root certificate. The chain is built based on the issuer of each certificate. For example, if certificate A was issued by certificate B, which itself was issued by the certificate C, then the chain would look as follows: A → B → C. The leaf certificate is a leaf certificate because no other certificate is referencing it in the certificate path. The root certificate is the last in line. It does not have any issuer certificates to reference.

nevisAuth expects that, if multiple certificates are incoming, the incoming certificates can all be mapped into one certificate path. If this is not the case, the PKI mechanism will fail to validate the certificates.

The method for how the certificates are extracted from the request is specific to the AuthState or service using the certificate validation functionality.

Trust anchors​

The certificates configured in the nevisAuth configuration are used as so-called trust anchors for the certificate chain. When a certificate path is validated, nevisAuth checks whether it is linked to any of the configured trust anchors. The trust anchors can therefore be compared to the list of root certificates in a browser.

In comparison to the cert path, the trust anchors are not checked for expiration or revoking. It is therefore possible to have a revoked intermediate certificate configured as a trust anchor in nevisAuth.

Multiple mechanisms for fetching trusted certificates are available. nevisAuth allows to fetch trust anchors from LDAP or HTTP back ends or from the file system. Details about how to configure the specific types can be retrieved from the list further below.

Certificate expiration​

X.509 certificates define a time range during which they are valid. The PKI mechanism of nevisAuth checks the expiration time of the incoming certificates. If a certificate is expired, the validate method will fail and notify the caller about the expiration.

Certificate revocation​

Whenever a certificate is compromised, e.g., the private key got lost or stolen by an attacker, the certificate should be marked as invalid. This mechanism is called certificate revocation. The issuer of the certificate holds the information about revoked certificates. Requests to check the revocation status must therefore be directed at the certificate issuer.

There are two specifications for marking a certificate invalid and checking the revocation status of a certificate: Certificate Revocation Lists (CRL) and revocation check with the Online Certificate Status Protocol (OCSP).

Revocation is not a substitute for expiration. While every expired certificate should be regarded as invalid, not all non-expired certificates should be regarded as valid.

Certificate revocation lists​

The certificate revocation list (CRL) is maintained by the issuer. It holds a list of serial numbers for certificates that have been revoked. The CRL is downloaded from the issuer and has a short validity period. Therefore, a new version (or update) of the revocation list must be downloaded regularly. nevisAuth allows to configure the scheduler.interval for fetching the CRL periodically. Details can be found in the list further below.

If one of the incoming certificates is listed in the CRL, the trust validation fails.

Online certificate status protocol​

As an alternative to CRLs, the online certificate status protocol (OCSP) allows, as the name suggests, an online verification of the certificate. Thus, no revocation list must be downloaded. Instead, we can instantly see if a certificate has been revoked.

In comparison to CRLs, OCSPs have a better performance because an OCSP response contains information about one specific certificate only rather than information about all certificates issued by an issuer. Thus, there is a lesser burden on the client and network resources.

The nevisAuth PKI system allows to configure the URL of the OCSP responder per issuer. The response contains information about whether the certificate is still considered good, expired or whether the status is unknown (which is the case if the OCSP responder is not responsible for this issuer). The table Generic key material - Configuration attributes further below contains detailed information on how to configure the location of the OCSP responder.

The list below also lists the generic key material configuration attributes which are used e.g., by the token assembler and various AuthState plug-ins (e.g., X509 authentication plug-ins). For more information, see Token assemblers and keystores and X.509 authentication AuthState, respectively.

info

Certificate roll-over happens automatically. See Common aspects of SAML 2.0 AuthStates for an explanation on how to configure certificate roll-over in nevisAuth.

Generic key material configuration attributes​

  • <KeyStore> Element

    The <KeyStore> elements are used to group key material. They contain <KeyObject> elements as described next.

  • <KeyObject> Element

    • certificate (string, -)

      The next options are supported to configure a X509 certificate (required for signature verification):

      • Keystore (FS): Specifies a file, containing X509 certificates in a keystore format, supported by an available JCE provider. JavaSE supports JKS and PKCS12. If the keystore contains multiple certificates/keys, an alias can be specified. If no alias is given and the keystore contains multiple certificates, one certificate is chosen arbitrarily for signing. This is not recommended. If the field is used for storing trustStores, however, an alias is not necessary. All certificates will be used for validating trust in that case.

        /var/opt/keybox/nevis/authSigner_keystore.jks?alias=authSigner
        /var/opt/keybox/nevis/authSigner_keystore.p12

      • Keystore (HSM): For HSM support, a PKCS#11 enabled JCE provider must be enabled (see the esauth4.security and pkcs11.cfg files for details). Example URLs to address key objects:

        • Sun JavaSE 1.5 PKCS#11 provider (SunPKCS11 is the name of the provider; HsmName is the name of the configuration section in pkcs11.cfg. The Sun provider does not support slot names; slots must be addressed via the slot number): PKCS11:?alias=authSigner?provider=SunPKCS11-HsmName

        • IBM PKCS#11 provider (The PKCS11IMPLKS may need to be used due to incompatibilities with the vendor's PKCS#11 driver library. In this case, the library is defined in pkcs11.cfg):

          PKCS11:/usr/lib/libCryptoki2.so:1?alias=authSigner
          PKCS11IMPLKS:?alias=authSigner

      • File (FS): Specifies a file, containing a PEM- or DER-encoded X509 certificate.

        /var/opt/keybox/nevis/authSigner_certificate.pem
        /var/opt/keybox/nevis/authSigner_certificate.der

        Multiple files can be configured, separated by a comma. If multiple certificates were loaded, the certificate used for signing is not guaranteed to be the first one.

      • LDAP: Specifies the URL to the LDAP server. As a property, the baseDN must be specified. Example: ldaps://mykeydirectory:658/

      • HTTP: Specifies the URL(s) to the http server. Many URLs can be listed in a comma-separated list. Certificates will be loaded from all URLs. Example: https://mywebserver:443/ca_cert1.pem,https://mywebserver:443/ca_cert2.der

    • privateKey (string, -)

      Required for signing, optional otherwise.

      The next options are supported to configure an RSA private key (required for signature generation):

      • Keystore (FS): Specifies a file, containing RSA private keys. See certificate option above for further details.
      • Keystore (HSM): See certificate option above for further details.
      • File (FS): Specifies a file, containing a DER-encoded RSA key. Example: /var/opt/keybox/nevis/authSigner_key.der
      • File (FS): Specifies a file, containing a DER-encoded encrypted RSA private key (PKCS8, requires enabled ADN JCE provider). Example: /var/opt/keybox/nevis/authSigner_pkcs8.der|

    • passPhrase (string, -)

      Required for encrypted private key access on keystores (HSM, file-based, PKCS#8).

      This attribute is used to configure a passphrase getter to obtain the secret to login to the keystore or decrypt an encrypted private key. See Passwords in the configuration for details about how to restrict disclosure of passwords in the configuration.

    • revocation (string, -)

      The path or URL to the certificate revocation list or the URL to the OCSP service.

      • File (FS): Specifies a file, containing a PEM- or DER-encoded X509 CRL.

        /var/opt/keybox/nevis/authSigner_certificate.pem
        /var/opt/keybox/nevis/authSigner_certificate.crl

        Multiple files can be configured, separated by a comma.

      • LDAP: Specifies the URL to the LDAP server. As a property, the baseDN must be specified. Example: ldaps://mykeydirectory:658/

      • HTTP: Specifies the URL to the HTTP server. Many URLs can be listed in a comma-separated list. CRLs will be loaded from all URLs. Example: https://mywebserver:443/crl.pem, https://mywebserver:443/ca_cert.crl

      • OCSP: Specifies the responder URL and issuer filter for the OCSP service. OCSP stands for online certificate status protocol. It is often used as an alternative to certificate revocation lists. Multiple responders can be configured, separated by a comma. An example for an OCSP responder: ocsp://^IssuerA$: http://ocsp.issuerA.com or multiple OCSP responders: ocsp://^IssuerA$: http://ocsp.issuerA.com , ocsp://^IssuerB$: http://ocsp.issuerB.com

  • CertStoreParameters Properties

    • disablePeriodicUpdates (boolean, false)

      If disabled, certificates and CRLs will only be fetched once.

    • scheduler.interval (int, 600)

      The update interval in seconds.

    • ommitKeyUsageCheck (boolean, false)

      Disables the verification of KeyUsage flags in loaded certificates. This property can be used to allow trusting of a certificate that has not been issued with the appropriate KeyUsage flags.

    • keyPurposeSet (string, -)

      Defines OIDs (comma-separated) that will be used during the validation check to verify the extended key usage of a certificate.

    • revocation.ocsp.[1-n].nonce (boolean, true)

      Defines if OCSP requests are sent to the OCSP responder with or without a nonce. This parameter can be individually set for each OCSP responder listed in the revocation attribute. [1-n] corresponds to the order in which responders are defined in the revocation property. For example: revocation.ocsp.1.nonce, revocation.ocsp.2.nonce,...

  • FSCertStoreParameters Properties

    • certPassPhrase (string, -)

      The password for the keystore/certificate.

    • certFileExtension (list, {"der","pem","jks","pkcs12", "p12", "pfx", "crt"})

      A list of extensions that are checked when fetching certificates. A warning is printed if a file has another extension.

    • certFileExtension (list, {"crl","pem"})

      A list of extensions that are checked when fetching CRLs. A warning is printed if a file has another extension.

    • directorySearchDepth (int, 1)

      If a directory is given as a resource of certificates or CRLs, the directory will be searched for certificates or CRLs up until the configured directorySearchDepth. By default, only the contents of the directory but no subdirectories are searched.

  • LdapCertStoreParameters Properties

    • baseDN (string, -)

      This property points to an LDAP directory subtree containing the certificates or CRLs.

    • caObjectClass (string, "certificationAuthority")

      The objectclass used by the filter to search the LDAP directory for CA certificates.

    • crlObjectClass (string, "certificationAuthority")

      The objectclass used by the filter to search the LDAP directory for certificate revocation lists.

    • caObjectFilter (string, -)

      Overrides the caObjectClass filter with a configured filter string.

    • crlObjectFilter (string, -)

      Overrides the crlObjectClass filter with a configured filter string.

    • searchSizeLimit (int, 256)

      This property limits the number of results returned by an LDAP search. This way, you can control resources such as memory and network bandwidth.

  • AuthState Properties (indirect use)

    • keystoreref (string, -)

      Reference to a <KeyStore> configuration section (e.g., DefaultKeyStore), containing the key material to use.

    • keyobjectref (string, -)

      Reference to the key object in the <KeyStore>, referenced by keystoreref (e.g., DefaultSigner)

  • AuthState Properties (JCE keystore direct use)

    • keystorefile (file, -)

      Specifies a keystore file, as supported by one of the available JCE providers. Types JKS and PKCS11 are supported by JavaSE.

    • keystoretype (string, JKS)

      Keystore type of the provided keystore file.

    • keystorealias (string, -)

      If the keystore contains multiple keys, it specifies the alias of the key to use.

    • keystorepassword (string, -)

      To access private keys in the keystore, a login to the keystore is required. This property is used to configure a password getter, as described in the KeyObject> element above.

  • AuthState Properties (JCE file/URL direct use)

    • certfile (string, -)

      Specifies a file containing a PEM- or DER-encoded X509 certificate

    • keyfile (string, -)

      Specifies either:

      • a file, containing a DER-encoded RSA private key
      • a file, containing a DER-encoded encrypted RSA private key (PKCS8, requires enabled ADN JCE provider)

    • keyfilepassword (string, -)

      Passphrase to decrypt the encrypted private key or login to the HSM.

Example​

<KeyStore name="TestCAs">
    <KeyObject name="TestCAfile"
        certificate="etc/keybox/NevisPKI/ca_cert.pem,etc/keybox/NevisPKI/ca_cert.pem"
        revocation="etc/keybox/NevisPKI/crl.pem" />
    <KeyObject name="TestCAldap" certificate="ldap://localhost:9876"
        revocation="ldap://localhost:9876">
      <property name="baseDN" value="cn=certAuth,ou=esauth4,o=siven" />
    </KeyObject>
    <KeyObject name="TestCApool"
        certificate="pool://myHttpResourcePool"/>
    <KeyObject name="TestCAhttp"
        certificate="https://ca.cern.ch/ca/CRL/CERN%20Root%20CA.crt"
        revocation="https://ca.cern.ch/ca/CRL/CERN%20Root%20CA.crl">
      <property name="proxyHost" value="proxy.siven.ch" />
      <property name="proxyPort" value="3128" />
      <property name="truststore"
            value="etc/keybox/default/cacern_truststore.jks" />
      <property name="truststorePasswd" value="password" />
      <property name="truststoreType" value="JKS" />
    </KeyObject>
</KeyStore>
info

See the nevisKeybox reference guide, chapter "Integration", for more details on passphrase handling, configuration references, and how to write passphrase getters.