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

X.509 authentication AuthState

Introduction and overview​

The X.509 AuthState X509Login expects a client certificate sent from nevisProxy and establishes a user by setting his ID to the subject of the provided certificate (or some other data contained in the certificate). Optionally, the client certificate is validated against a certificate authority (CA) and a certificate revocation list (CRL).

If CRL checks are enabled, a CRL must be present for each CA certificate used. The signatures of CRLs are validated against the corresponding CA certificates and validity periods of CRLs (validFrom/validTo) are enforced.

Certificate validity checks are also possible using OCSP. In this case, each CA must have a configured OCSP service where revocation is checked on demand.

caution

The client is authenticated by nevisProxy, which means there is no end-to-end security between the client and nevisAuth. For details on how to enable X.509 client certificate authentication in the proxy, refer to the nevisProxy reference guide (integration chapter).

Description​

The following table and chapters describe the characteristics of the AuthState.

TopicDescription
Classch.nevis.esauth.auth.states.x509.X509Login
LoggingX509State, JNDI
Auditingnone
MarkerX509:token
Methodsauthenticate, setupup, unlock

Properties​

  • certificateStringTransformer string, -)

    A class that implements the interface ch.nevis.esauth.util.StringTransformer and is called when reading the incoming client certificate. This can be used if the client sending the certificate applies an unconventional format to the PEM string.

    An example for an implementation: ch.nevis.esauth.auth.states.x509.util. ReplaceWhitespacesInCertificateTransformer, which replaces all spaces with newline characters.

  • certVerify (boolean, true)

    Turns all certificate validation/verification on or off. This includes the following checks (see switches below):

    • checks certificate against configured trust anchor (requires cryptoMaterialSupplier for CA truststore)
    • certificate validity period
    • CRL (with cryptoMaterialSupplier supporting CRLs)
    • OCSP (requires cryptoMaterialSupplier=ocsp)

  • certificate (String, ${request:clientCertAsString})

    The source of the certificate to validate. To use the certificate from the physical SSL transport layer, use ${request.actorCertAsString}.

  • certValidityCheck (boolean, true)

    This switch allows to turn off the validity period check of the user certificate. Expired certificates are accepted.

  • caValidityCheck (boolean, true)

    This switch allows to turn off the validity period check of the CA certificate. Expired user certificates are accepted.

  • certRevocationCheck (regexp, true)

    This value can be either true or false to switch on the revocation check or disable it completely. It can further be a regular expression: The revocation check is then turned on for every certificate issuer matching the regexp.

    For example, .*O=TrustMe AG.*¦.*O=TrustMeToo AG.* will turn on CRL checking only for certificates issued by these two companies.

  • revocationCheckExpirationTolerance (Integer [sec], 0)

    Period in seconds to still use expired CRLs or outdated revocation lists. If the value is < 0, the expiration timestamp of the certificate revocation list is not checked.

  • issuerFilter (regexp)

    This property is used to configure a regular expression, against which the client certificate's issuer-DN is checked. If the issuer-DN does not match, processing is aborted. The default transition can be used to invoke the next AuthState. This may be used to configure multiple cascaded certificate states, where each state may handle its own certificates.

  • subjectFilter (regexp)

    This property is used to configure a regular expression, against which the client certificate's subject-DN is checked. If the subject-DN does not match, processing is aborted. The default transition can be used to invoke the next AuthState.

  • useridSource (String, "SUBJECT_DN")

    This attribute allows to configure which ASN1 element of the certificate should be used as login-ID and user-ID.

    X509Login supports the following sources:

    • SUBJECT_DN (default): The full subject-DN is used as a string as returned from Java's java.security.cert.X509Certificate.getSubjectDN() method.
    • SUBJECT_CN: The cn attribute is extracted from the subject-DN.
    • SUBJECT_UID: The uid attribute is extracted from the subject-DN.
    • SUBJECT_EMAIL: The email attribute is extracted from the subject-DN.
    • PRINCIPAL_NAME: The subject alternative name with the OID 1.3.6.1.4.1.311.20.2.3 is queried in the X.509 certificate extension structure.
    • PRINCIPAL_RFC822NAME: The first subject alternative name with type rfc822Name (=e-mail) is set as the user ID.

  • useridFormatPrincipalName (String {full,unqualified}, "unqualified")

    Defines the format of the user-ID when the useridSource is PRINCIPAL_NAME Assuming an X.509 principal name "username@REALM":

    • full user-ID="username@REALM", login-ID="username@REALM"
    • unqualified user-ID="username", login-ID="username"

  • cryptoMaterialSupplier (enum { file, ldap, ldapwithfilesystem, http, ocsp, keystore}, file)

    This property defines where to get the cryptographic material (CA certificates and CRLs). There are six possible sources:

    • file Uses truststores and CRLs from the local file system. If truststores are updated, a restart of the service is required. No restart is required if CRL files are updated - CRLs are reloaded automatically when a change is detected based on the files' last modified timestamp.
    • ldap Connects to an LDAP directory to periodically download CA certificates and CRLs. If multiple CRLs apply, the most recently issued CRL will be used.
    • ldapwithfilesystem This is a combination of file and ldap. Crypto material from the filesystem as well as the LDAP is considered.
    • http Connects to the configured locations, downloads the content (expected are DER-encoded CRLs as available from, e.g., http://swisssign.net/cgi-bin/authority/crl?ca=Personal%20Gold) and caches the crypto material in the filesystem.
    • ocsp Connects to the configured OCSP responder and verifies the certificate. The Online Certificate Status Protocol (OCSP) enables applications to determine the revocation state of an identified certificate.
    • keystore Use CertStoreManager configured in the nevisAuth engine as KeyStore and KeyStoreObject. CA certificate, CRL and OCSP checks will be performed if available.

  • caFile (file, -)

    File reference to a truststore, containing acceptable certificate authorities (CAs). The extension is used to find out which keystore provider to use to load the truststore:

    • /path/to/java/keystore/truststore.jks
    • /path/to/pkcs12/keystore/truststore.p12
    • /path/to/single/certificate/ca.der
    info

    .pem should not be used

  • caPassPhrase (String, -)

    If the configured caFile requires a passphrase to load it, the passphrase can be configured using this property.

  • crlDirectory (path, -)

    Directory containing DER-encoded CRLs to be used for CRL verification. CRLs stored here must be verifiable with the trusted certificates stored in the caFile keystore.

    Set either this attribute or crlFile.

  • crlFile (file, -)

    File reference to a CRL file in DER format. Set either this attribute or crlDirectory.

  • crlCacheAccessMax (file, -)

    The amount of seconds after which the CRL cache should be cleared.

LDAP supplier only​

  • connection1, ..., connection9 (url, -)

    See the corresponding property description in UseridPasswordAuthenticateState.

  • searchSizeLimit (int, 256)

    See the corresponding property description in UseridPasswordAuthenticateState.

  • baseDN (DN)

    This property points to an LDAP directory sub-tree containing the CA objects.

  • caObjectClassIdentifier (String, "certificationAuthority")

  • caObjectFilter (String, "(objectClass=certificationAuthority)")

  • crlObjectClassIdentifier (String, "certificationAuthority")

  • crlObjectFilter (String, "(objectClass=certificationAuthority)")

    These properties can be used to customize the LDAP query for CA certificates (LDAP attribute caCertificate) and CRLs (LDAP attribute certificateRevocationList).

    If cRLDistributionPoint is configured as caObjectClassIdentifier, CAs are not fetched from the directory. In this case, the supplier ldapwithlocalcache needs to be used to have a local trust anchor.

  • dirFetchPeriod (Integer [sec], 86400, that is, 1 day)

    Configure the polling period to look for new CA certificates and CRLs in the configured LDAP.

HTTP supplier only​

nevisAuth 4.38.x HTTP client changes

The new HTTP client shipped with nevisAuth 4.38.0.12 will likely require changes in this auth state configuration, specifically in the area of certificate configuration and handling.

Visit the migration guide for additional information.

  • connection1, ..., connection99 (url, -)

    HTTP or HTTPS URLs pointing to web locations, serving DER-encoded CRLs.

    Note that CRLs downloaded from these locations are verified against the configured truststore (See caFile and related attributes).

  • httpclient.* (String)

    Configure the outgoing HTTP communication towards the configured URLs for CRLs. For a list of valid HTTP properties, see HTTP Client.

  • crlFetchPeriod (Integer [sec], 86400)

    Download interval. The download thread sequentially downloads all the configured connection URLs.

See the crlDirectory, caFile and caPassPhrase properties in this list. The HTTP crypto material supplier uses the file-based supplier as a cache provider.

OCSP supplier only​

nevisAuth 4.38.x HTTP client changes

The new HTTP client shipped with nevisAuth 4.38.0.12 will likely require changes in this auth state configuration, specifically in the area of certificate configuration and handling.

Visit the migration guide for additional information.

  • responder (url, -)

    HTTP or HTTPS URLs pointing to web locations, serving OCSP requests. This property may either be configured as a plain value pointing to a single OCSP service to use:

    <property name="responder" value="http://ocsp.ca.com" />

    ...or as a list of properties with the name-prefix "responder:", where each property defines an OCSP service for use if the issuer of a certificate matches the regular expression that is given by the remainder of the name of the property:

    <property name="responder:^anIssuer$" value="http://ocsp.anissuer.com" />
    <property name="responder:^otherIssuer$" value="http://ocsp.otherissuer.net" />

  • httpclient.*

    Configure the outgoing HTTP communication towards the specified OCSP Responders. For a list of valid HTTP properties, see HTTP Client.

  • ocspNone (boolean, true)

    If set to false, no nonce is generated. Otherwise, a nonce is generated and and sent to the OCSP responder.

See caFile and caPassPhrase properties in this table. The OCSP material supplier uses the file-based supplier as a cache provider.

Keystore supplier only​

  • keystoreref, keyobjectref (string, -)

    References to a KeyStore (and optionally to a KeyObject therein) defined in the nevisAuth configuration. If keyobjectref is omitted, then all KeyObjects in the KeyStore are valid issuers. All KeyObjects will then be used as directly trusted or issuer certificates. See also Certificates, keys and public key infrastructure.

LDAP with filesystem supplier Only​

  • loadFileSystemFirst (boolean, false)

    When setting to true, the file system based key material is loaded first, and the LDAP based key material afterwards. This can be required if key material returned by LDAP requires key material from the filesystem to be validated.

Input​

  • connection.ClientCert (caller, required)

    Base64-encoded client certificate acquired by the caller.

Transitions​

  • ok

    Certificate was accepted.

  • nocert (optional)

    Caller (nevisProxy) did not provide a certificate. This (conditional) transition allows to differentiate between a missing and an unacceptable certificate.

  • camissing (optional)

    Failure due to missing CA trust anchor.

  • crlmissing (optional)

    Failure due to missing CRL.

  • crlexpired (optional)

    Failure due to expired CRL

  • revoked (optional)

    Certificate is revoked (according to available CRL)

  • expired (optional)

    Current system time is not in certificate validity range (from/to)

  • default

    No certificate was presented or the certificate was not accepted

Output​

none

Errors​

  • lasterror=1

    lasterrorinfo=Inacceptable certificate => the certificate does not contain a "loginidField" attribute or "issuerFilter" does not match.

  • lasterror=1

    lasterrorinfo=No certificate in request => proxy did not forward a certificate.

  • lasterror=1

    lasterrorinfo=No revocation check possible => supplier did not return a CRL or the OCSP service was not reachable. All certificates of this CA are blocked.

  • lasterror=1

    lasterrorinfo=Expired revocation check material => supplier did not return an up-to-date CRL or the OCSP service returned an outdated response. All certificates of this CA are blocked.

  • lasterror=1

    lasterrorinfo=Certificate has been revoked => certificate was revoked.

  • lasterror=1

    lasterrorinfo=No matching CA => no trust anchor provided by CA supplier, all certificates of this CA are blocked.

Notes​

none

Example​

AuthState with CRL checking from a LDAP director
<AuthState name="Certificate"
    class="ch.nevis.esauth.auth.states.x509.X509Login"
    final="false">
  <ResultCond name="ok"       next="AuthDone" authLevel="auth.strong"/>
  <ResultCond name="revoked"  next="AuthError" />
  <ResultCond name="nocert"   next="AlternateLogin" startOver="true"/>
  <ResultCond name="default"  next="AlternateLogin" />
  <Response value="AUTH_ERROR">
    <Gui name="AuthFailDialog" label="Error">
      <GuiElem name="fail" type="error" label="login.cert.fail.text"/>
    </Gui>
  </Response>
  <property name="certVerify" value="true"/>
  <property name="cryptoMaterialSupplier" value="ldap"/>
  <property name="connection1" value="ldaps://ldap.company.com:636"/>
  <property name="baseDN" value="ou=cas,o=siven,c=ch"/>
  <property name="dirFetchPeriod" value="60"/>
</AuthState>
info

The startOver flag clears errors that would otherwise be displayed to the user, for example, if a user ID / password mechanism is used as a fallback.

AuthState with CRL checking from HTTP server
<AuthState name="Certificate"
    class="ch.nevis.esauth.auth.states.x509.X509Login"
    final="false">
  <ResultCond name="ok" next="AuthDone" authLevel="auth.strong"/>
  <ResultCond name="default" next="AlternateLogin" startOver="true"/>
  <Response value="AUTH_ERROR">
    <Gui name="AuthFailDialog" label="Error">
      <GuiElem name="fail" type="error" label="login.cert.fail.text"/>
    </Gui>
  </Response>
  <property name="certVerify" value="true"/>
  <property name="caFile" value="/var/opt/keybox/client/truststore.jks"/>
  <property name="crlDirectory" value="/var/opt/nevisauth/default/cache/crl"/>
  <property name="crlDirectorySearchFileExtension" value=".der"/>
  <property name="cryptoMaterialSupplier" value="http"/>
  <property name="crlFetchPeriod" value="86400"/> <!-- sec -->
  <property name="certRevocationCheck" value="true"/>
  <property name="connection1"
            value="http://EVIntl-crl.verisign.com/EVIntl2006.crl"/>
  <property name="connection3"
            value="http://swisssign.net/cgi-bin/authority/crl?ca=Personal%20Gold"/>  
  <property name="httpclient.proxy.host" value="cache.siven.ch"/>
  <property name="httpclient.proxy.port" value="3128"/>
</AuthState>
LDAP entry
# /opt/nevisldap/bin/ldapsearch -x -LLL -H ldap://localhost:389 \
          -b 'ou=cas,o=SIVEN AG,c=ch'
dn: cn=Nevis Keybox CA: NevisBoxCA (adnws003),ou=cas,o=SIVEN AG,c=ch
cn: Nevis Keybox CA: NevisBoxCA (adnws003)
objectClass: top
objectClass: applicationProcess
objectClass: certificationAuthority
certificateRevocationList;binary:: MIIBpDCBjTANBgkqhkiG9w0BAQQFADBeMQswCQYD...
authorityRevocationList;binary:: MIIBpDCBjTANBgkqhkiG9w0BAQQFADBeMQswCQYDVQ...
cACertificate;binary:: MIIEAzCCAuugAwIBAgIJAJ9Pq3WdvWfAMA0GCSqGSIb3DQEBBQUA...
HTTP download and verify using commandline tools
# curl http://swisssign.net/cgi-bin/authority/crl?ca=Personal%20Gold ¦ \
          openssl crl -inform der -text

Certificate Revocation List (CRL):
        Version 2 (0x1)
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: /C=CH/O=SwissSign/CN=SwissSign Personal Gold CA/[email protected]
        Last Update: Jan 24 06:00:14 2010 GMT
        Next Update: Feb 3 06:00:14 2010 GMT
        CRL extensions:
                X509v3 Authority Key Identifier:

keyid:D5:BC:AC:A0:2F:AE:95:28:1A:77:21:74:E3:3F:C0:70:6F:BB:5D:0B
                X509v3 CRL Number:4300

Revoked Certificates:
        Serial Number: AC09C17739D7EC
        Revocation Date: Apr 2 05:54:52 2007 GMT