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.
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 describes the characteristics of the AuthState.
| Topic | Description |
|---|---|
| Class | ch.nevis.esauth.auth.states.x509.X509Login |
| Logging | X509State, JNDI |
| Auditing | none |
| Marker | X509:token |
| Properties(general) | 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 (requirescryptoMaterialSupplierfor CA truststore) certificate validity period CRL (withcryptoMaterialSuppliersupporting 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(number, 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 fullsubject-DNis used as a string as returned from Java'sjava.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"* | |
| Properties(Provider) | 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 (http://www.ietf.org/rfc/rfc2560.txt). * keystore: Use CertStoreManager configured in the nevisAuth engine as KeyStore and KeyStoreObject. CA certificate, CRL and OCSP checks will be performed if available. |
| Properties (File and http supplier only) | 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 |
| 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 verifyable 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. | |
| Properties ". | |
| searchSizeLimit ". | |
| 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 (number, 86400, that is, 1 day)Configure the polling period to look for new CA certificates and CRLs in the configured LDAP. | |
| Properties(HTTP supplier only) | connection1, ..., connection99 (url, -)HTTP or HTTPS URLs pointing to web locations, serving DER-encoded CRLs. HTTPS support needs to be configured by setting the javax.net.ssl system properties accordingly (see /opt/nevisauth/template/conf/vmargs.conf).Note that CRLs downloaded from these locations are verified against the configured truststore (see caFile and related attributes). |
| httpclient.*The prefixhttpclient.makes it possible to specify HTTP properties for the outgoing HTTP communication with the web locations specified in theconnectionproperties.For this, you have to place the prefixhttpclient.before the relevant HTTP property. For a list of valid HTTP properties, see AuthHttpClient] ". Theconnectionproperties are described above. | |
| crlFetchPeriod (number, 86400)Download interval. The download thread sequentially downloads all the configured connection URLs. | |
| See thecrlDirectory,caFileandcaPassPhrase properties in this table. The HTTP crypto material supplier uses the file-based supplier as a cache provider. | |
| Properties(OCSPsupplieronly) | 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" />
| Topic | Description |
|---|---|
| httpclient.*The prefixhttpclient.makes it possible to specify HTTP properties for the outgoing HTTP communication with the OCSP servers specified in theresponderproperty.For this, you have to place the prefixhttpclient.before the relevant HTTP property. For a list of valid HTTP properties, see AuthHttpClient] ". Theresponderproperty is described above. | |
| ocspNone (boolean, true)If set to false, no nonce is generated. Otherwise, a nonce is generated and and sent to the OCSP responder. | |
| SeecaFileandcaPassPhraseproperties in this table. The OCSP material supplier uses the file-based supplier as a cache provider. | |
| Properties(keystore supplier only) | keystoreref, keyobjectref (string, -)References to aKeyStore(and optionally to aKeyObjecttherein) defined in the nevisAuth configuration. Ifkeyobjectrefis omitted, then allKeyObjectsin theKeyStoreare valid issuers. AllKeyObjects will then be used as directly trusted or issuer certificates. See also chapter 4.3.7 "Certificates, keys and public key infrastructure". |
| Methods | authenticatestepupunlock |
| 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 | 1: Inacceptable certificate => the certificate does not contain a "loginidField" attribute or "issuerFilter" does not match.1: No certificate in request => proxy did not forward a certificate.1: No revocation check possible => supplier did not return a CRL or the OCSP service was not reachable.All certificates of this CA are blocked.1: 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.1: Certificate has been revoked => certificate was revoked.1: No matching CA => no trust anchor provided by CA supplier, all certificates of this CA are blocked.The user should either be challenged for another certificate or just get the message that the certificate used is not acceptable. See validation properties above on how to (temporarily) disable validation policies. |
| Notes | none |
Example(AuthState with CRL checking from a LDAP directory
<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>
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.
Example(AuthState with CRL checking from HTTP servers)
<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="commConnectTimeout" value="10000"/> <!-- msec -->
<property name="commReadTimeout" value="30000"/> <!-- msec -->
<property name="proxyHost" value="cache.siven.ch"/>
<property name="proxyPort" value="3128"/>
</AuthState>
Example(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...
ExampleHTTP 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