Chapter 3. Reference

3.1. key-manager attributes

You can configure a key-manager by setting its attributes.

Table 3.1. key-manager attributes

AttributeDescription

algorithm

The name of the algorithm to use to create the underlying KeyManagerFactory. This is provided by the JDK. For example, a JDK that uses SunJSSE provides the PKIX and SunX509 algorithms. For more information, see the Support Classes and Interfaces on the Oracle website.

alias-filter

A filter to apply to the aliases returned from the keystore. This can either be a comma-separated list of aliases to return or one of the following formats:

  • ALL:-alias1:-alias2
  • NONE:+alias1:+alias2

credential-reference

The credential reference to decrypt keystore item. This can be specified in clear text or as a reference to a credential stored in a credential-store. This is not a password of the keystore.

key-store

Reference to the key-store to use to initialize the underlying KeyManagerFactory.

provider-name

The name of the provider to use to create the underlying KeyManagerFactory.

providers

Reference to obtain the Provider[] to use when creating the underlying KeyManagerFactory.

3.2. key-store attributes

You can configure a key-store by setting its attributes.

Table 3.2. key-store attributes

AttributeDescription

alias-filter

A filter to apply to the aliases returned from the keystore, can either be a comma separated list of aliases to return or one of the following formats:

  • ALL:-alias1:-alias2
  • NONE:+alias1:+alias2
Note

The alias-filter attribute is case sensitive. Because the use of mixed-case or uppercase aliases, such as elytronAppServer, might not be recognized by some keystore providers, it is recommended to use lowercase aliases, such as elytronappserver.

credential-reference

The password to use to access the keystore. This can be specified in clear text or as a reference to a credential stored in a credential-store.

path

The path to the keystore file.

provider-name

The name of the provider to use to load the keystore. When you set this attribute, the search for the first provider that can create a key store of the specified type is disabled.

providers

A reference to the providers that should be used to obtain the list of provider instances to search. If not specified, the global list of providers will be used instead.

relative-to

The base path this store is relative to. This can be a full path or a predefined path such as jboss.server.config.dir.

required

If set to true, the key store file referenced must exist at the time the key store service starts. The default value is false.

type

The type of the key store, for example, JKS.

Note

The following key store types are automatically detected:

  • JKS
  • JCEKS
  • PKCS12
  • BKS
  • BCFKS
  • UBER

You must manually specify the other key store types.

A full list of key store types can be found in Java Cryptography Architecture Standard Algorithm Name Documentation for JDK 11 in the Oracle JDK documentation.

3.3. server-ssl-context attributes

You can configure the server SSL context, server-ssl-context, by setting its attributes.

Table 3.3. server-ssl-context attributes

AttributeDescription

authentication-optional

If true rejecting of the client certificate by the security domain will not prevent the connection. This allows a fall through to use other authentication mechanisms, such as form login, when the client certificate is rejected by security domain. This has an effect only when the security domain is set. This defaults to false.

cipher-suite-filter

The filter to apply to specify the enabled cipher suites. This filter takes a list of items delimited by colons, commas, or spaces. Each item may be an OpenSSL-style cipher suite name, a standard SSL/TLS cipher suite name, or a keyword such as TLSv1.2 or DES. A full list of keywords as well as additional details on creating a filter can be found in the Javadoc for the CipherSuiteSelector class. The default value is DEFAULT, which corresponds to all known cipher suites that do not have NULL encryption and excludes any cipher suites that have no authentication.

cipher-suite-names

The filter to apply to specify the enabled cipher suites for TLSv1.3.

final-principal-transformer

A final principal transformer to apply for this mechanism realm.

key-manager

Reference to the key managers to use within the SSLContext.

maximum-session-cache-size

The maximum number of SSL/TLS sessions to be cached.

need-client-auth

If set to true, a client certificate is required on SSL handshake. Connection without a trusted client certificate will be rejected. This defaults to false.

post-realm-principal-transformer

A principal transformer to apply after the realm is selected.

pre-realm-principal-transformer

A principal transformer to apply before the realm is selected.

protocols

The enabled protocols. Allowed options are

  • SSLv2
  • SSLv3
  • TLSv1
  • TLSv1.1
  • TLSv1.2
  • TLSv1.3

This defaults to enabling TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3.

Warning

Use TLSv1.2, or TLSv1.3 instead of SSLv2, SSLv3, and TLSv1.0. Using SSLv2, SSLv3, or TLSv1.0 poses a security risk, therefore you must explicitly disable them.

provider-name

The name of the provider to use. If not specified, all providers from providers will be passed to the SSLContext.

providers

The name of the providers to obtain the Provider[] to use to load the SSLContext.

realm-mapper

The realm mapper to be used for SSL/TLS authentication.

security-domain

The security domain to use for authentication during SSL/TLS session establishment.

session-timeout

The timeout for SSL sessions, in seconds.

The value -1 directs Elytron to use the Java Virtual Machine (JVM) default value.

The value 0 indicates that there is timeout.

The default value is -1.

trust-manager

Reference to the trust-manager to use within the SSLContext.

use-cipher-suites-order

If set to true the cipher suites order defined on the server is used. If set to false the cipher suites order presented by the client is used. Defaults to true.

want-client-auth

If set to true a client certificate is requested, but not required, on SSL handshake. If a security domain is referenced and supports X509 evidence, want-client-auth is set to true automatically. This is ignored when need-client-auth is set. This defaults to false.

wrap

If true, the returned SSLEngine, SSLSocket, and SSLServerSocket instances are wrapped to protect against further modification. This defaults to false.

Note

The realm-mapper and principal-transformer attributes for server-ssl-context apply only for the SASL EXTERNAL mechanism, where the certificate is verified by the trust manager. HTTP CLIENT-CERT authentication settings are configured in an http-authentication-factory.

3.4. trust-manager attributes

You can configure the trust manager, trust-manager, by setting its attributes.

Table 3.4. trust-manager attributes

AttributeDescription

algorithm

The name of the algorithm to use to create the underlying TrustManagerFactory. This is provided by the JDK. For example, a JDK that uses SunJSSE provides the PKIX and SunX509 algorithms. More details on SunJSSE can be found in the Support Classes and Interfaces in Java Secure Socket Extension (JSSE) Reference Guide in Oracle documentation.

alias-filter

A filter to apply to the aliases returned from the key store. This can either be a comma-separated list of aliases to return or one of the following formats:

  • ALL:-alias1:-alias2
  • NONE:+alias1:+alias2

certificate-revocation-list

Enables certificate revocation list checks in a trust manager. You can only define a single CRL path using this attribute. To define multiple CRL paths, use certificate-revocation-lists. The attributes of certificate-revocation-list are:

  • maximum-cert-path - The maximum number of non-self-issued intermediate certificates that can exist in a certification path. The default value is 5. This attribute has been deprecated. Use maximum-cert-path in trust-manager instead.
  • path - The path to the certificate revocation list.
  • relative-to - The base path of the certificate revocation list file.

certificate-revocation-lists

Enables certificate revocation list checks in a trust manager using multiple certificate revocation lists. The attributes of certificate-revocation-list are:

  • path - The path to the certificate revocation list.
  • relative-to - The base path of the certificate revocation list file.

key-store

Reference to the key-store to use to initialize the underlying TrustManagerFactory.

maximum-cert-path

The maximum number of non-self-issued intermediate certificates that can exist in a certification path. The default value is 5.

This attribute has been moved to trust-manager from certificate-revocation-list inside trust-manager in JBoss EAP 7.3. For backward compatibility, the attribute is also present in certificate-revocation-list. Going forward, use maximum-cert-path in trust-manager.

Note

Define maximum-cert-path in either trust-manager or in certificate-revocation-list not in both.

ocsp

Enables online certificate status protocol (OCSP) checks in a trust manager. The attributes of ocsp are:

  • responder - Overrides the OCSP Responder URI resolved from the certificate.
  • responder-certificate - Alias for responder certificate located in responder-keystore or trust-manager key store if responder-keystore is not defined.
  • responder-keystore - Alternative keystore for responder certificate. responder-certificate must be defined.
  • prefer-crls - When both OCSP and CRL mechanisms are configured, OCSP mechanism is called first. When prefer-crls is set to true, the CRL mechanism is called first.

only-leaf-cert

Check revocation status of only the leaf certificate. This is an optional attribute. The default values is false.

provider-name

The name of the provider to use to create the underlying TrustManagerFactory.

providers

Reference to obtain the providers to use when creating the underlying TrustManagerFactory.