[[authentication-client]]
= <authentication-client /> - WildFly Elytron

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

The _<authentication-client/>_ element can be added to the wildfly-config.xml configuration to define configuration in relation to authentication configuration for outbound connections and SSL configuration for outbound connections e.g.

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
       ...
    </authentication-client>
</configuration>
----

_Note: A single wildfly-config.xml could be used by multiple projects using multiple versions of WildFly Elytron, newer versions of WildFly Elytron will introduce new configuration using later namespace versions however they will still continue to support the previously released schemas until advertised otherwise.  For the configuration to be compatible with this either use a schema and namespace compatible with all the versions in use, or multiple authentication-client elements can be added, these should be added ordered by namespace youngest to oldest.  If a configuration with a later namespace is discovered by a newer WildFly Elytron client it will be used and parsing will not look for an older version as well._

The _<authentication-client />_ configuration can contain the following sections: -

 <credential-stores />:: Definitions of credential stores to be referenced from elsewhere in the configuration.
 <key-stores />:: Definitions of KeyStores to be referenced elsewhere in the configuration.
 <authentication-rules />:: Rules to be applied for outbound connections to match against an appropriate authentication configuration.
 <authentication-configurations />:: The individual authentication configurations that will be matched by the authentication rules.
 <net-authenticator />:: Flag to enable integration with the [java.net.Authenticator|https://docs.oracle.com/javase/8/docs/api/java/net/Authenticator.html].
 <ssl-context-rules />:: Rules to be applied for outbound connections to match against an appropriate SSL context configuration.
 <ssl-contexts />:: Individual SSL context definitions that will be matched by the ssl context rules.
 <providers/>:: Definition of how [java.security.Provider|https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html] instances will be discovered.

== <credential-stores />

The <credential-stores />  element can be used to define individual named credential stores that can subsequently be used elsewhere in the configuration to reference stored credentials as an alternative to the credentials being embedded in the configuration.

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <credential-stores>
            <credential-store name="..." type="..." provider="..." >
                <attributes>
                    <attribute name="..." value="..." />
                </attributes>
                <protection-parameter-credentials>...</protection-parameter-credentials>
            </credential-store>
        </credential-stores>
    </authentication-client>
</configuration>
----

In addition to the name an individual <credential-store /> definition can contain the following optional attributes: -

type:: The type of the credential store, e.g.KeyStoreCredentialStore.
provider:: The name of the [java.security.Provider|https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html] to use to load the credential store.

The following child elements can also be added to configure the credential store.

 <attributes .>:: Definition of configuration attributes used to initialise the credential store.

e.g.

[source,xml,options="nowrap"]
----
<attributes>
    <attribute name="..." value="..." />
</attributes>
----

The <attribute/> element can be repeated as many times as is required for the configuration.

[[client-credentials-type]]
 <protection-parameter-credentials />:: One or more credentials to be assembled into a protection parameter when initialising the credential store.

The <protection-paramter-credentials /> element can contain one more more child elements, which of these are actually supported will depend on the credential store implementation: -

[source,xml,options="nowrap"]
----
<protection-parameter-credentials>
    <key-store-reference>...</key-store-reference>
    <credential-store-reference store="..." alias="..." clear-text="..." />
    <clear-password password="..." />
    <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
    <key-pair>
        <public-key-pem>...</public-key-pem>
        <private-key-pem>...</public-key-pem>
        <openssh-private-key pem="...">
            <credential-store-reference store="..." alias="..." clear-text="..." />
            <clear-password password="..." />
            <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
        </openssh-private-key>
    </key-pair>
    <certificate private-key-pem="..." pem="..." />
    <public-key-pem>...</public-key-pem>
    <bearer-token value="..." />
    <oauth2-bearer-token token-endpoint-uri="...">...</oauth2-bearer-token>
</protection-parameter-credentials>
----

The potential child elements of <protection-parameter-credentials /> are: -

 <key-store-reference>:: Defines a reference to an entry within a KeyStore for an entry to use.

The overall structure of this element is: -

[source,xml,options="nowrap"]
----
<key-store-reference key-store-name="..." alias="...">
   <key-store-clear-password password="..." />
   <key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
   <credential-store-reference store="..." alias="..." clear-text="..." />
   <key-store-credential>...</key-store-credential>
</key-store-reference>
----

This structure is identical to the structure use in [<key-store-credential />|#key-store-credential].

 <credential-store-reference store="..." alias="..." clear-text="..." />:: Reference to a credential stored in a credential store.

 <clear-password password="..." />:: A password specified in the clear.

 <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />:: A masked password.

 <key-pair public-key-pem="..." private-key-pem="..." />:: A public and private key pair.

* <certificate private-key-pem="..." pem="..." />:: A pem encoded private key and corresponding certificate.

 <public-key-pem>...</public-key-pem>:: A pem encoded public key.

* <bearer-token value="..." />:: A bearer token

 <oauth2-bearer-token>...</oauth2-bearer-token>:: An oath2 bearer token.

The full structure of this element is: -

[source,xml,options="nowrap"]
----
<oauth2-bearer-token token-endpoint-uri="...">
    <client-credentials client-id="..." client-secret="..." />
    <masked-client-credentials client-id="...">
        <masked-client-secret algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
    </masked-client-credentials>
    <resource-owner-credentials name="..." password="..." />
    <masked-resource-owner-credentials name="...">
            <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
    </masked-resource-owner-credentials >
</oauth2-bearer-token>
----


== <key-stores />

The <key-stores /> element can be used to define individual key-store definitions that can subsequently be referenced from alternative locations within the configuration.

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <key-stores>
            <key-store name="...">
               <!-- One of the following to specify where to load the KeyStore from. -->
               <file-name name="..." />
               <load-from uri-"..." />
               <resource name="..." />
               <!-- One of the following to specify the protection parameter to unlock the KeyStore. -->
               <key-store-clear-password password="..." />
               <key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
               <key-store-credential>...</key-store-credential>
            </key-store>
        </key-stores>
       ...
    </authentication-client>
</configuration>
----

An individual <key-store /> definition must contain exactly one of the following elements to define where to load the store from.

 <file name="..." />*:: Load from file where 'name' is the name of the file.
 <load-from uri="..." />:: Load the file from the URI specified.
 <resource name="..." />:: Load as a resource from the Thread context classloader where 'name' is the name of the resource to load.

Exactly one of the following elements must also be present to specify the protection parameter for initialisation of the KeyStore.

<key-store-clear-password password="..." />:: A password specified in the clear.
<key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />:: A masked password.
<key-store-credential>...</key-store-credential>:: A reference to another KeyStore to obtain an Entry to use as the protection parameter to access this KeyStore.

[[key-store-credential]]
The structure of the <key-store-credential /> element is:

[source,xml,options="nowrap"]
----
<key-store-credential key-store-name="..." alias="...">
   <key-store-clear-password password="..." />
   <key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
   <credential-store-reference store="..." alias="..." clear-text="..." />
   <key-store-credential>...</key-store-credential>
</key-store-credential>
----

This element contains two attributes: -

 key-store-name:: _(Mandatory)_ - Name of the KeyStore being referenced to load the entry from.
 alias:: _(Optional)_ - The alias of the entry to load from the referenced KeyStore, this can only be omitted for KeyStores that contain only a single entry.

Java KeyStores also make use of a protection parameter when accessing a single entry in addition to the protection parameter to load the KeyStore, exactly one of the following elements must be present to specify the protection parameter of the entry being loaded.

 <key-store-clear-password password="..." />:: A password specified in the clear.
 <key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />:: A masked password.
 <credential-store-reference store="..." alias="..." clear-text="..." />:: Reference to a credential stored in a credential store.
 <key-store-credential>...</key-store-credential>:: A reference to another KeyStore to obtain an Entry to use as the protection parameter to access the alias.

The <key-store-credential /> is exactly the same, this means theoretically a chain of references could be used to lead to the unlocking of the required alias.

[[Rules]]
== <authentication-rules /> and <ssl-context-rules />

When either an authentication-configuration or an ssl-context is required the URI of the resources being accessed as well as an optional abstract type and abstract type authority and matched against the rules defined in the configuration to identify which authentication-configuration or ssl-context should be used.

The rules to match <authentication-configuration /> instances are defined within the <authentication-rules /> element.

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <authentication-rules>
            <rule use-configuration="...">
                ...
            </rule>
        </authentication-rules>
       ...
    </authentication-client>
</configuration>
----

The rules to match against the <ssl-context /> definitions are contains within the <ssl-context-rules /> element.

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <ssl-context-rules>
            <rule use-ssl-context="...">
                ...
            </rule>
        </ssl-context-rules>
       ...
    </authentication-client>
</configuration>
----

Overall this means that authentication configuration matching is independent of SSLContext matching.  By separating the rules from the configurations is means multiple rules can be defined that match against the same configuration.

The rules applied so first match wins and not most specific match wins, to achieve a most specific match wins configuration place the most specific rules at the beginning leaving the more general matches towards the end.

For both the <authentication-rules />  and the <ssl-context-rules /> the structure of the rules is identical other than one references an authentication configuration and the other references an SSLContext.

[source,xml,options="nowrap"]
----
<rule use-configuration|use-ssl-context="...">
    <!-- At most one of the following two can be defined. -->
    <match-no-user />
    <match-user name="..." />
    <!-- Each of the following can be defined at most once. -->
    <match-protocol name="..." />
    <match-host name="..." />
    <match-path name="..." />
    <match-port number="..." />
    <match-urn name="..." />
    <match-domain name="..." />
    <match-abstract-type name="..." authority="..." />
</rule>
----

Where multiple matches are defined within a rule they must all match for the rule to apply.  If a rule is defined with no match elements then it becomes a match all rule and will match anything, these can be useful at the end of the configuration to ensure something matches.

The individual match elements are: -

 <match-no-user />:: user-info can be embedded within a URI, this rule matches when there is no user-info.
 <match-user name="..." /> - Matches when the user-info embedded in the URI matches the name specified within this element.
 <match-protocol name="..." /> - Matches the protocol within the URI against the name specified in this match element.
 <match-host-name name="..." /> - Matches the host name from within the URI against the name specified in this match element.
 <match-path name="..." /> - Matches the path from the URI against the name specified in this match element.
 <match-port number="..." /> - Matches the port number specified within the URI against the number in this match element.  This only matches against the number specified within the URI and not against any default derrived from the protocol.
 <match-urn name="..." />" - Matches the scheme specific part of the URI against the name specified within this element.
* <match-domain-name name="..."/>:: Matches where the protocol of the URI is 'domain' and the scheme specific part of the URI is the name specified within this match element.
 <match-abstract-type name="..." authority="..." />:: Matches the abstract type and/or authority against the values specified within this match element.

=== Elytron client default SSL context security provider

Elytron client provides a java security provider which can be used to register a JVM wide default `SSLContext`. The provider can instantiate an `SSLContext` from an Elytron client configuration file. This `SSLContext` will then be the one returned when `SSLContext.getDefault()` is called. When this provider is registered then all client libraries that use `SSLContext.getDefault()` will use the Elytron client configuration without having to use Elytron client APIs in their code.

To register this `org.wildfly.security.auth.client.WildFlyElytronClientDefaultSSLContextProvider` provider, a runtime dependency on `wildfly-elytron-client` and `wildfly-client-config` is needed. Then it can be registered the usual way, either statically or dynamically.

The provider loads the SSL context from either the current authentication context obtained from the classpath, or from the authentication context obtained from the file whose path is passed into the security provider either programmatically or as an argument in the `java.security` file. Any arguments passed to the provider directly have precedence over the authentication context from the classpath.

As an example, the SSL context configured to match all rules is the one that will be initialized and returned by this provider:

[source,xml,options="nowrap"]
----
<rule use-ssl-context="ssl-context-for-client-provider" />
----

Or:

----
myAuthenticationContext.withSsl(MatchRule.ALL, myDefaultSslContext);
----

To register the provider programmatically and specify the path to an Elytron client configuration file, the following code can be used:

[source,java,options="nowrap"]
----
Security.insertProviderAt(new WildFlyElytronClientDefaultSSLContextProvider(CONFIG_FILE_PATH), 1);
----

Alternatively, the provider can be registered in the `java.security` file and the path to an Elytron client configuration file can be optionally specified as shown below:

[source,bash,options="nowrap"]
----
security.provider.1=org.wildfly.security.auth.client.WildFlyElytronClientDefaultSSLContextProvider CONFIG_FILE_PATH
----

When you have a default SSL context configured and you register this provider with high enough priority, you can make use of it by calling:

```
SSLContext.getDefault();
```

If no default SSL context is configured or there is no configuration present, the provider will be ignored.

== <authentication-configurations />

The <authentication-configurations /> element contains named configurations that can then be matched from the <authentication-rules />

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <authentication-configurations>
            <configuration name="...">
                <!-- Destination Overrides. -->
                <set-host name="..." />
                <set-port number="..." />
                <set-protocol name="..." />
                <!-- At most one of the following two elements. -->
                <set-user-name name="..." />
                <set-anonymous />
                <set-mechanism-realm name="..." />
                <rewrite-user-name-regex pattern="..." replacement="..." />
                <sasl-mechanism-selector selector="..." />
                <set-mechanism-properties>
                   <property key="..." value="..." />
                </set-mechanism-properties>
                <credentials>...</credentials>
                <set-authorization-name name="..." />
                <providers>...</providers>
                <!-- At most one of the following two elements. -->
                <use-provider-sasl-factory />
                <use-service-loader-sasl-factory module-name="..." />
            </configuration>
        </authentication-configurations>
    </authentication-client>
</configuration>
----

The elements within the <configuration /> element provide the following features: -

The first three elements override the destination.

 <set-host-name name="..." />:: Override the host name for the authenticated call.
 <set-port-number number="..." />:: Override the port number for the authenticated call.
 <set-protocol name="..."/>:: Override the protocol for the authenticated call.

The next two are mutually exclusive and can be used to set the name for authentication or switch to anonymous authentication.

 <set-user-name name="..."/>:: Set the user name to use for authentication.
 <set-anonymous />:: Switch to anonymous authentication.

 <set-mechanism-realm-name name="..." />:: Specify the name of the realm that will be selected by the SASL mechanism if required.
 <rewrite-user-name-regex pattern="..." replacement="..." />:: A regular expression pattern and replacement to re-write the user name used for authentication.
 <sasl-mechanism-selector selector="..." />:: A SASL mechanism selector using the syntax from [org.wildfly.security.sasl.SaslMechanismSelector,fromString()|https://github.com/wildfly-security/wildfly-elytron/blob/1.1.4.Final/src/main/java/org/wildfly/security/sasl/SaslMechanismSelector.java#L544]
 <set-mechanism-properties>...</set-mechanism-properties>:: One or more properties defined as <property key="..." value="..." /> to be passed to the authentication mechanisms.

 <credentials>...</credentials>:: One or more credentials available for use during authentication.

The content of this element is the same as documented for [<protection-parameter-credentials />|#client-credentials-type]

[source,xml,options="nowrap"]
----
<credentials>
    <key-store-reference>...</key-store-reference>
    <credential-store-reference store="..." alias="..." clear-text="..." />
    <clear-password password="..." />
    <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
    <key-pair>
        <public-key-pem>...</public-key-pem>
        <private-key-pem>...</public-key-pem>
        <openssh-private-key pem="...">
            <credential-store-reference store="..." alias="..." clear-text="..." />
            <clear-password password="..." />
            <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
        </openssh-private-key>
    </key-pair>
    <ssh-credential ssh-directory="..." private-key-file="..." known-hosts-file="...">
        <credential-store-reference store="..." alias="..." clear-text="..." />
        <clear-password password="..." />
        <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
    </ssh-credential>
    <certificate private-key-pem="..." pem="..." />
    <public-key-pem>...</public-key-pem>
    <bearer-token value="..." />
    <oauth2-bearer-token token-endpoint-uri="...">...</oauth2-bearer-token>
</credentials>
----

 <set-authorization-name name="..." />:: Specify the name that should be used for authorization if different from the authentication identity.
 <providers/>:: This element is described in more detail within [<providers />|#Providers] and overrides the default or inherited provider discovery with a definition specific to this authentication configuration definition.

The final two elements are mutually exclusive and define how the SASL mechanism factories will be discovered for authentication.

 <use-provider-sasl-factory />:: The [java.security.Provider|https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html] instances either inherited or defined in this configuration will be used to locate the available SASL client factories.
 <use-service-loader-sasl-factory module-name="..." />:: SASL client factories will be discovered using service loader discovery on the specified module or if not specified using the ClassLoader loading the configuration.

== <net-authenticator />

This element contains no specific configuration, however if present the [org.wildfly.security.auth.util.ElytronAuthenticator|https://wildfly-security.github.io/wildfly-elytron/documentation/api/upstream/org/wildfly/security/auth/util/ElytronAuthenticator.html] will be registered with [java.net.Authenticator.setDefault(Authenticator)|https://docs.oracle.com/javase/8/docs/api/java/net/Authenticator.html#setDefault-java.net.Authenticator-] meaning that the WildFly Elytron authentication client configuration can be used for authentication where the JDK APIs are used for HTTP calls which require authentication.

There are some limitations within this integration as the JDK will cache the authentication JVM wide from the first call so is better used in stand alone processes that don't require different credentials for different calls to the same URI,

[[SSLContexts]]
== <ssl-contexts />

The <ssl-contexts /> element holds individual names SSLContext definitions that can subsequently be matched by the  [<ssl-context-rules />|#Rules].

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.4">
        <ssl-contexts>
            <default-ssl-context name="..."/>
            <ssl-context name="...">
                <key-store-ssl-certificate>...</key-store-ssl-certificate>
                <trust-store key-store-name="..." />
                <cipher-suite selector="..." names="..." />
                <protocol names="... ..." />
                <provider-name name="..." />
                <providers>...</providers>
                <certificate-revocation-list path="..." maximum-cert-path="..." />
            </ssl-context>
        </ssl-contexts>
    </authentication-client>
</configuration>
----

The element <default-ssl-context name="..." /> simply takes the SSLContext obtainable from [javax.net.ssl.SSLContext.getDefault()|https://docs.oracle.com/javase/8/docs/api/javax/net/ssl/SSLContext.html#getDefault--] and assigns it a name so it can referenced from the [<ssl-context-rules />|#Rules].  This element can be repeated meaning the default SSLContext can be referenced using different names.

The element <ssl-context /> is used to define a named configured SSLContext, each of the child elements is optional and can be specified at most once to build up the configuration of the SSLContext.

 <key-store-ssl-certificate>:: Defines a reference to an entry within a KeyStore for the key and certificate to use in this SSLContext.

The overall structure of this element is: -

[source,xml,options="nowrap"]
----
<key-store-ssl-certificate key-store-name="..." alias="..." provider-name="..." algorithm="...">
   <key-store-clear-password password="..." />
   <key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
   <credential-store-reference store="..." alias="..." clear-text="..." />
   <key-store-credential>...</key-store-credential>
</key-store-ssl-certificate>
----

This structure is identical to the structure use in [<key-store-credential />|#key-store-credential], but it is to obtain the entry for the key and certificate. The nested elements however remain the protection parameter to unlock the entry. In comparison with the key-store-credential the key-store-ssl-certificate allows to configure also the TrustManager: -

 provider-name:: - Name of the provider used to obtain the KeyManagerFactory.
 algorithm:: - The algorithm name of the KeyManagerFactory to obtain.

 <trust-store-key-store-name />:: A reference to a KeyStore that will be used to initialise the TrustManager.

 <cipher-suite selector="..." names="..." />:: Configuration to filter the enabled cipher suites. This element must contain at least one of the following two attributes: -

 selector:: _(Optional)_ Used to configure the enabled cipher suites for TLSv1.2 and below. The format of the `selector` attribute is described in detail
 in https://wildfly-security.github.io/wildfly-elytron/documentation/api/next/org/wildfly/security/ssl/CipherSuiteSelector.html#fromString(java.lang.String)[org.wildfly.security.ssl.CipherSuiteSelector.fromString(selector)].
 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.

 names:: _(Optional)_ Used to configure the enabled cipher suites for TLSv1.3. The format of the `names` attribute is a simple colon (":")
 separated list of TLSv1.3 cipher suite names (e.g., `TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256`).
 This attribute must be specified in order for TLSv1.3 to be enabled.

The following example configuration specifies that the default filtering should be used for TLSv1.2 and below and specifies that the
`TLS_AES_128_CCM_8_SHA256` and `TLS_AES_256_GCM_SHA384` cipher suites should be used for TLSv1.3.

[source,xml,options="nowrap"]
----
<cipher-suite selector="DEFAULT" names="TLS_AES_128_CCM_8_SHA256:TLS_AES_256_GCM_SHA384"/>
----

 <protocol names="..."/>:: Used to define a space separated list of the protocols to be supported. The default value is `TLSv1 TLSv1.1 TLSv1.2 TLSv1.3`. Note that the TLSv1.3 protocol will only be usable when running against JDK 11 or higher.

 <provider-name />:: Once the available providers have been identified only the provider with the name defined on this element will be used.

 <providers/>:: This element is described in more detail within [<providers />|#Providers] and overrides the default or inherited provider discovery with a definition specific to this SSLContext definition.

 <certificate-revocation-list />:: The presence of this element enabled checking the peer's certificate against a certificate revocation list, this element defines both a path to the certificate revocation list and also specifies the maximum number of non-self-issued intermediate certificates that may exist in a certification path

 <certificate-revocation-lists />:: This element enables checking the peer's certificate against multiple certificate revocation lists. This element defines a list of certificate revocation list objects which define a path to the certificate revocation list,
 and also the base path of the certificate revocation list file.

NOTE: The certificate-revocation-list element can be substituted by a certificate-revocation-lists element which in turn allows the
configuration of multiple certificate revocation lists as follows.

[source,xml,options="nowrap"]
----
<configuration>
    <authentication-client xmlns="urn:elytron:1.4">
        <ssl-contexts>
            <default-ssl-context name="..."/>
            <ssl-context name="...">
                ...
                <certificate-revocation-lists>
                    <certificate-revocation-list path="..." relative-to="..." />
                    <certificate-revocation-list path="..." relative-to="..." />
                </certificate-revocation-lists>
            </ssl-context>
        </ssl-contexts>
    </authentication-client>
</configuration>
----

=== Configuring SSLv2Hello

Older JDK versions use ``SSLv2Hello`` during the initial SSL handshake message
where the SSL/TLS version that will be used for the rest of the communication is
negotiated.

Using ``SSLv2Hello`` is discouraged, therefore newer JDK versions disable this protocol
on the client by default. However, they do provide the ability to re-enable it if necessary.

``SSLv2Hello`` can be configured as a supported protocol for the SSL context as follows:

[source,options="nowrap"]
----
<protocol names="SSLv2Hello TLSv1">
----

=== WARNING:

* The use of ``SSLv2Hello`` is strongly discouraged.

* ``SSLv2Hello`` cannot be configured by itself, as its purpose is to determine
which encryption protocols are supported by the server it connects to. It always
needs to be configured along side another encryption protocol.

* Additionally, IBM JDK does not support specifying ``SSLv2Hello`` in its client, although a
server side connection always accepts this protocol.

[[Providers]]
== <providers />

The _<providers />_ element is used to define how [java.security.Provider|https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html] instances are located when required.  The other configuration sections of _<authentication-client />_ are independent of each other, the _<providers />_ configuration however applies to the current element and it's children unless overridden, this configuration can be specified in the following locations.


[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <providers />
        ...
        <credential-stores>
            <credential-store name="..">
                ...
                <providers />
            </credential-store>
        <credential-stores>
        ...
        <authentication-configurations>
            <authentication-configuration name="...">
                ...
                <providers />
            </authentication-configuration>
        </authentication-configurations>
        ...
        <ssl-contexts>
            <ssl-context name="...">
                ...
                <providers />
            </ssl-context>
        </ssl-contexts>
    </authentication-client>
</configuration>
----

If an individual <credential-store />, <authentication-configuration />, or <ssl-context /> contains a <providers /> definition that that definition will apply specifically to that instance.  If a configured item does not contain a <providers /> definition but a top level <providers /> is defined within <authentication-configuration /> then that will be used instead.

The <providers /> element can be defined as: -

[source,xml,options="nowrap"]
----
<providers>
    <global />
    <use-service-loader module-name="..." />
</providers>
----

Both the child elements are optional, can appear in any order and can be repeated although repeating <global /> would not really be beneficial.

 <global />:: The providers from [java.security.Security.getProviders()|https://docs.oracle.com/javase/8/docs/api/java/security/Security.html#getProviders--]
 <credential-stores />:: Providers loaded using service loader discovery from the module specified, if no module is specified the ClassLoader which loaded the authentication client is used.

Where no <provider /> configuration exists the default behaviour is the equivalent of: -

[source,xml,options="nowrap"]
----
<providers>
    <use-service-loader />
    <global />
</providers>
----

This gives the WildFly Elytron Provider priority over any globally registered Providers but also allows for the globally registered providers to be used.

[[MaskedPasswords]]
== Masked Password Types
The authentication client supports the following masked password types:
[source,xml,options="nowrap"]
----
<masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
<key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />

<!--In oauth2-bearer-token!-->
<masked-resource-owner-credentials name="...">
        <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
</masked-resource-owner-credentials >
<masked-client-credentials client-id="...">
    <masked-client-secret algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
</masked-client-credentials>

----

The following attributes are used to define the masked password:

`algorithm`:: The algorithm that was used to encrypt the password. If this attribute is not specified, the default value is "masked-MD5-DES".
A list of the supported algorithm types can be found in
link:https://github.com/wildfly/wildfly/blob/main/docs/src/main/asciidoc/_elytron/Passwords.adoc#masked-password-types[Masked Password Type]
`key-material`:: The initial key material that was used to encrypt the password. If this attribute is not specified, the default value is "somearbitrarycrazystringthatdoesnotmatter".
`iteration-count`:: The iteration count that was used to encrypt the password. This attribute is required.
`salt`:: The salt that was used to encrypt the password. This attribute is required.
`masked-password`:: The base64 encrypted password (without the "MASK-" prefix). This attribute is required.
`initialization-vector`:: The initialization vector that was used to encrypt the password. This attribute is optional.
