Chapter 3. Configuring HTTPS
Abstract
This chapter describes how to configure HTTPS endpoints.
3.1. Authentication Alternatives
3.1.1. Target-Only Authentication
Overview
When an application is configured for target-only authentication, the target authenticates itself to the client but the client is not authentic to the target object, as shown in Figure 3.1, “Target Authentication Only”.
Figure 3.1. Target Authentication Only
Security handshake
Prior to running the application, the client and server should be set up as follows:
- A certificate chain is associated with the server. The certificate chain is provided in the form of a Java keystore (ee Section 3.3, “Specifying an Application's Own Certificate”).
- One or more lists of trusted certification authorities (CA) are made available to the client. (see Section 3.2, “Specifying Trusted CA Certificates”).
During the security handshake, the server sends its certificate chain to the client (see Figure 3.1, “Target Authentication Only”). The client then searches its trusted CA lists to find a CA certificate that matches one of the CA certificates in the server's certificate chain.
HTTPS example
On the client side, there are no policy settings required for target-only authentication. Simply configure your client without associating an X.509 certificate with the HTTPS port. You must provide the client with a list of trusted CA certificates, however (see Section 3.2, “Specifying Trusted CA Certificates”).
On the server side, in the server's XML configuration file, make sure that the
sec:clientAuthentication element does not require client authentication. This element can be omitted, in which case the default policy is to not require client authentication. However, if the sec:clientAuthentication element is present, it should be configured as follows:
<http:destination id="{Namespace}PortName.http-destination">
<http:tlsServerParameters secureSocketProtocol="TLSv1">
...
<sec:clientAuthentication want="false" required="false"/>
</http:tlsServerParameters>
</http:destination>Important
You must set
secureSocketProtocol to TLSv1 on the server side, in order to protect against the Poodle vulnerability (CVE-2014-3566)
Where the
want attribute is set to false (the default), specifying that the server does not request an X.509 certificate from the client during a TLS handshake. The required attribute is also set to false (the default), specifying that the absence of a client certificate does not trigger an exception during the TLS handshake.
Note
The
want attribute can be set either to true or to false. If set to true, the want setting causes the server to request a client certificate during the TLS handshake, but no exception is raised for clients lacking a certificate, so long as the required attribute is set to false.
It is also necessary to associate an X.509 certificate with the server's HTTPS port (see Section 3.3, “Specifying an Application's Own Certificate” ) and to provide the server with a list of trusted CA certificates (see Section 3.2, “Specifying Trusted CA Certificates” ).
Note
The choice of cipher suite can potentially affect whether or not target-only authentication is supported (see Chapter 4, Configuring HTTPS Cipher Suites).
3.1.2. Mutual Authentication
Overview
When an application is configured for mutual authentication, the target authenticates itself to the client and the client authenticates itself to the target. This scenario is illustrated in Figure 3.2, “Mutual Authentication” . In this case, the server and the client each require an X.509 certificate for the security handshake.
Figure 3.2. Mutual Authentication
Security handshake
Prior to running the application, the client and server must be set up as follows:
- Both client and server have an associated certificate chain (see Section 3.3, “Specifying an Application's Own Certificate”).
- Both client and server are configured with lists of trusted certification authorities (CA) (see Section 3.2, “Specifying Trusted CA Certificates”).
During the TLS handshake, the server sends its certificate chain to the client, and the client sends its certificate chain to the server—see Figure 3.1, “Target Authentication Only” .
HTTPS example
On the client side, there are no policy settings required for mutual authentication. Simply associate an X.509 certificate with the client’s HTTPS port (see Section 3.3, “Specifying an Application's Own Certificate”). You also need to provide the client with a list of trusted CA certificates (see Section 3.2, “Specifying Trusted CA Certificates”).
On the server side, in the server’s XML configuration file, make sure that the
sec:clientAuthentication element is configured to require client authentication. For example:
<http:destination id="{Namespace}PortName.http-destination">
<http:tlsServerParameters secureSocketProtocol="TLSv1">
...
<sec:clientAuthentication want="true" required="true"/>
</http:tlsServerParameters>
</http:destination>Important
You must set
secureSocketProtocol to TLSv1 on the server side, in order to protect against the Poodle vulnerability (CVE-2014-3566)
Where the
want attribute is set to true, specifying that the server requests an X.509 certificate from the client during a TLS handshake. The required attribute is also set to true, specifying that the absence of a client certificate triggers an exception during the TLS handshake.
It is also necessary to associate an X.509 certificate with the server’s HTTPS port (see Section 3.3, “Specifying an Application's Own Certificate”) and to provide the server with a list of trusted CA certificates (see Section 3.2, “Specifying Trusted CA Certificates”).
Note
The choice of cipher suite can potentially affect whether or not mutual authentication is supported (see Chapter 4, Configuring HTTPS Cipher Suites).
