Using SSL

Logback Classic supports the use of the Secure Sockets Layer (SSL) when delivering log events to a remote log server using SSLSocketAppender. This appender acts as a secure network client, connecting to an SSL-enabled log server and delivering serialized logging events over a secure channel. It supports all of the same logging features as the plain old SocketAppender while offering secure transport for logging events over the network.

Logback Classic supports two SSL-enabled logging servers.

SSL and X.509 Certificates

In order to use SSL-enabled Logback components, you will need an X.509 credential (a private key, corresponding certificate, and CA certification chain) to identify your Logback server. If you wish to use mutual authentication, you will also need credentials for your Logback clients (such as SSLSocketAppender).

You can use almost any valid X.509 credential for your Logback server. While you can use a credential issued by a commercial certification authority (CA), you can also use a certificate issued from your own internal CA or even a self-signed certificate. The following is all that is required:

  1. The server must be configured with a key store containing the server's private key, corresponding certificate, and CA certification chain (if not using a self-signed certificate).
  2. The client must be configured with a trust store containing the trusted root CA certificate(s) or the server's signed root certificate.

TODO: provide some examples of creating key stores and trust stores using self-signed certificates. Meanwhile there are lots of examples to be found out there on the web...

Configuring Logback Components for SSL

The Java Secure Sockets Extension (JSSE) and Java Cryptography Architecture (JCA) which is used to implement Logback's SSL support has many configurable options, and a pluggable provider framework that allows the built-in SSL and cryptographic capabilities of the platform to be replaced or augmented. SSL-enabled Logback components such as SSLSocketAppender and SSLSocketServer provide the ability to fully specify all of the configurable aspects of the SSL engine and cryptographic providers, to meet your unique security needs.

Basic SSL Configuration using JSSE System Properties

Fortunately, nearly all of the configurable SSL properties for SSL-enabled Logback components have reasonable defaults. In most cases all that is needed to use SSL-enabled Logback components is the configuration of some JSSE system properties.

The remainder of this section describes the specific JSSE properties that are needed in most environments. See Customizing JSSE in the JSSE Reference Guide for more information on setting JSSE system properties to customize JSSE.

If you're using either the SSLSocketServer component in your application's logback configuration or using the SimpleSSLSocketServer as a standalone application to receive logging events, you'll need to configure JSSE system properties that provide the location, type, and password of the key store containing the private key and certificate for your logging server.

System Properties for Server Key Store Configuration

Property Name Description
javax.net.ssl.keyStore Specifies a filesystem path to the file containing your logging server's private key and certificate.
javax.net.ssl.keyStoreType Specifies the key store type. If this property is not specified, the platform's default type (JKS) is assumed.
javax.net.ssl.keyStorePassword Specifies the password needed to access the key store.

See Examples below for examples of setting these system properties when starting a server application via a command-line interface.

If your logging server is using a certificate that was signed by a commercial certification authority (CA), you probably don't need to provide any SSL configuration in your applications that use SSLSocketAppender. When using a commercially-signed logging server certificate, simply setting the key store system properties in the server is usually all that is needed.

If are using either a self-signed logging server certificate or your logging server's certificate was signed by a certification authority (CA) that is not among those whose root certificates are in the Java platform's default trust store (e.g. when your organization has its own internal certification authority), you will need to configure the JSSE system properties that provide the location, type, and password of the trust store containing your server's certificate or trusted root certificates for the certification authority (CA) that signed your server's certificate. These properties will need to be set in the application that utilizes SSLSocketAppender.

System Properties for Client Trust Store Configuration

Property Name Description
javax.net.ssl.trustStore Specifies a filesystem path to the file containing your logging server's certificate or trusted root certificate(s) for the certification authority (CA) that signed.
javax.net.ssl.trustStoreType Specifies the trust store type. If this property is not specified, the platform's default type (JKS) is assumed.
javax.net.ssl.trustStorePassword Specifies the password needed to access the trust store.

See Examples below for examples of setting these system properties when starting a client application via a command-line interface.

Advanced SSL Configuration

In certain situations, the basic SSL configuration using JSSE system properties is not adequate. For example, if you are using the SSLSocketServer component in a web application, you may wish to use a different credential to identify your logging server for your remote logging clients than the credential that your web server uses to identify itself to web clients. You might wish to use SSL client authentication on your logging server to ensure that only authentic and authorized remote loggers can connect. Or perhaps your organization has strict policies regarding the SSL protocols and cipher suites that may be utilized on the organization's network. For any of these needs, you will need to make use of Logback's advanced configuration options for SSL.

When configuring a Logback component that supports SSL, you specify the SSL configuration using the ssl property in the configuration of the component.

For example, if you wish to use SSLSocketServer and configure the key store properties for your logging server's credential, you could use a configuration such as the following.

View as .groovy
<configuration>
  <server class="ch.qos.logback.classic.net.server.SSLSocketServer">
    <ssl>
      <keyStore>
        <location>classpath:/logging-server-keystore.jks</location>
        <passphrase>changeit</passphrase>
      </keyStore>
    </ssl>
  </server> 

  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n
    </encoder>
  </appender>
  
  <root level="debug">
    <appender-ref ref="CONSOLE" />
  </root>

</configuration>

This configuration specifies the location of the key store as logging-server-keystore.jks at the root of the application's classpath. You could alternatively specify a file: URL to identify the location of the key store.

If you wanted to use SSLSocketAppender in your application's logback configuration, but did not want to change the application's default trust store using the JSSE javax.net.ssl.trustStore property, you could configure the appender as follows.

View as .groovy
<configuration>
  <appender name="SOCKET" class="ch.qos.logback.classic.net.SSLSocketAppender">
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n
    </encoder>
    <ssl>
      <trustStore>
        <location>classpath:/logging-server-truststore.jks</location>
      </trustStore>
    </ssl>
  </appender>
  
  <root level="debug">
    <appender-ref ref="CONSOLE" />
  </root>

</configuration>

This configuration specifies the location of the trust store as logging-server-truststore.jks at the root of the application's classpath. You could alternatively specify a file: URL to identify the location of the trust store.

SSL Configuration Properties

JSSE exposes a large number of configurable options, and Logback's SSL support makes nearly all of them available for you to specify in your server or appender configuration. When using XML configuration, SSL properties are introduced to these components by nesting an < element in the appender or server configuration. This configuration element corresponds to the SSLConfiguration class.

When configuring SSL for your server or appender components you need only configure those SSL properties for which the defaults are not adequate. Overspecifying the SSL configuration is often those cause of difficult-to-diagnose problems.

The following table describes the top-level SSL configuration properties. Many of these properties introduce additional subproperties, which are described in tables that follow after the top-level properties are described.

Property Name Type Description
keyManagerFactory KeyManagerFactoryFactoryBean Specifies the configuration used to create a KeyManagerFactory. The Java platform's default factory will be used if this property is not configured. See Key Manager Factory Configuration below.

keyStore KeyStoreFactoryBean

Specifies the configuration used to create a KeyStore. The KeyStore created by this property should contain a single X.509 credential (consisting of a private key, corresponding certificate, and CA certificate chain). This credential is presented by the local SSL peer to the remote SSL peer.

When configuring an SSL client (e.g. SSLSocketAppender), the keyStore property is needed only if the remote peer is configured to require client authentication.

When configuring an SSL server (e.g. SimpleSSLSocketServer) the keyStore property specifies the key store containing the server's credential. If this property is not configured, the JSSE's javax.net.ssl.keyStore system property must be configured to provide the location of the server's key store. See Customizing JSSE in the JSSE Reference Guide for more information on setting JSSE system properties.

See Key Store Configuration below.

parameters SSLParametersConfiguration Specifies various parameters used in SSL session negotiation. See SSL Parameters Configuration below.
protocol String Specifies the SSL protocol that will be used to create an SSLContext. See the Standard Names specification in the JSSE Reference Guide. The Java platform's default protocol will be used if this property is not configured.

provider String Specifies the name of the JSSE provider that will be used to create an SSLContext. The Java platform's default JSSE provider will be used if this property is not configured.

secureRandom SecureRandomFactoryBean Specifies the configuration used to create a SecureRandom — a secure random number generator. The Java platform's default generator will be used if this property is not configured. See Secure Random Generator Configuration below.

trustManagerFactory TrustManagerFactoryFactoryBean Specifies the configuration used to create a TrustManagerFactory. The Java platform's default factory will be used if this property is not configured. See Trust Manager Factory below.

trustStore KeyStoreFactoryBean

Specifies the configuration used to create a KeyStore used for validating identity of the remote SSL peer. The KeyStore created by this property should contain one or more trust anchors — self-signed certificates marked as "trusted" in the keystore. Typically, the trust store contains self-signed CA certificates.

The trust store specified by this property overrides any trust store specified by the JSSE's javax.net.ssl.trustStore system property and the platform's default trust store.See Customizing JSSE in the JSSE Reference Guide for more information on setting JSSE system properties.

Key Store Configuration

The KeyStoreFactoryBean specifies the configuration needed to create a KeyStore containing X.509 credentials. The properties of this factory bean can be used in the keyStore and trustStore properties of the SSL Configuration.

Property Name Type Description
location String A URL that specifies the location of the key store. Use a file: URL to specify the location of the keystore on a filesystem. Use a classpath: URL to specify a keystore than can be found on the classpath. If the URL doesn't specify a scheme, classpath: is assumed.
passphrase String Specifies the passphrase needed to access the key store.
provider String Specifies the name of the JCA provider that will be used to create a KeyStore. The Java platform's default key store provider will be used if this property is not configured.
type String Specifies the KeyStore type. See the Standard Names specification in the Java Cryptography Architecture specification. The Java platform's default key store type will be used if this property is not configured.

Key Manager Factory Configuration

The KeyManagerFactoryFactoryBean specifies the configuration needed to create a KeyManagerFactory. Generally, it isn't necessary to explicitly configure the key manager factory, as the platform's default factory is adequate for most needs.

Property Name Type Description
algorithm String Specifies the KeyManagerFactory algorithm name. See the Standard Names specification in the JSSE Reference Guide. The Java platform's default key manager algorithm will be used if this property is not configured.
provider String Specifies the name of the JCA provider that will be used to create a SecureRandom generator. The Java platform's default JSSE provider will be used if this property is not configured.

Secure Random Generator Configuration

The SecureRandomFactoryBean specifies the configuration needed to create a SecureRandom generator. Generally, it isn't necessary to explicitly configure the secure random generator, as the platform's default generator is adequate for most needs.

Property Name Type Description
algorithm String Specifies the SecureRandom algorithm name. See the Standard Names specification in the Java Cryptography Architecture specification. The Java platform's default random number generation algorithm will be used if this property is not configured.
provider String Specifies the name of the JCA provider that will be used to create a SecureRandom generator. The Java platform's default JSSE provider will be used if this property is not configured.

SSL Parameters Configuration

The SSLParametersConfiguration allows the customization of allowed SSL protocols, cipher suites, and client authentication options.

Property Name Type Description
excludedCipherSpecs String

Specifies a comma-separated list of SSL cipher spec names or patterns to disable during session negotation. This property is used to filter the cipher suites supported by the SSL engine, such that any cipher spec matched by this property is disabled.

Each field in the comma-separated list specified for this property may be a simple string or a regular expression.

See the Standard Names specification in the JSSE Reference Guide for a list of cipher spec names.

includedCipherSpecs String

Specifies a comma-separated list of SSL cipher spec names or patterns to enable during session negotation. This property is used to filter the cipher suites supported by the SSL engine, such that only those cipher suites matched by this property are enabled.

Each field in the comma-separated list specified for this property may be a simple string or a regular expression.

See the Standard Names specification in the JSSE Reference Guide for a list of cipher spec names.

excludedProtocols String

Specifies a comma-separated list of SSL protocol names or patterns to disable during session negotation. This property is used to filter the protocols supported by the SSL engine, such that any protocol matched by this property is disabled.

Each field in the comma-separated list specified for this property may be a simple string or a regular expression.

See the Standard Names specification in the JSSE Reference Guide for a list of protocol names.

includedProtocols String

Specifies a comma-separated list of SSL protocol names or patterns to enable during session negotation. This property is used to filter the protocols supported by the SSL engine, such that only those protocols matched by this property are enabled.

Each field in the comma-separated list specified for this property may be a simple string or a regular expression.

See the Standard Names specification in the JSSE Reference Guide for a list of protocol names.

needClientAuth boolean Set this property to the value true to configure a server to require a valid client certificate. This property is ignored when configured for a client SSLSocketAppender.
wantClientAuth boolean Set this property to the value true to configure the server to request a client certificate. This property is ignored when configured for a client SSLSocketAppender.

Trust Manager Factory Configuration

The TrustManagerFactoryFactoryBean specifies the configuration needed to create a TrustManagerFactory. Generally, it isn't necessary to explicitly configure the trust manager factory, as the platform's default factory is adequate for most needs.

Property Name Type Description
algorithm String Specifies the TrustManagerFactory algorithm name. See the Standard Names specification in the JSSE Reference Guide. The Java platform's default key manager algorithm will be used if this property is not configured.
provider String Specifies the name of the JCA provider that will be used to create a SecureRandom generator. The Java platform's default JSSE provider will be used if this property is not configured.

Examples

TODO

Resolving SSL Exceptions

When using SSLSocketAppender, the appender acts as a client, connecting to an SSL-enabled logging server. If SSL is misconfigured, it generally results in the client and server being unable to negotiate an agreeable session. This problem usually manifests itself as exceptions being thrown by both parties when the client attempts to connect to the server.

The content of the exception messages varies depending on whether you are looking at the client's log or the server's log. This is mostly due to inherent protocol limitations in error reporting during session negotiation. As a consequence of this fact, in order to troubleshoot session negotiation problems, you will usually want to look at the logs of both the appender client and the logging server.

Server's Certificate is Not Available

When starting the logging server, you see the following exception in the log:

javax.net.ssl.SSLException: No available certificate or key corresponds to the SSL cipher suites which are enabled

In most cases this means that you have not configured the location of the key store containing the server's private key and corresponding certificate.

Solution

Using either the Key Store system properties or the keyStore property of the server component's ssl property, you must specify the location and passphrase for the key store containing the server's private key and certificate.

Client Does Not Trust the Server

When the appender client attempts to connect to the logging server, you see the following exception in the log:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed

This problem is the result of the server presenting a certificate the client does not trust. The most common cause is that you are using a self-signed server certificate (or a server certificate that was signed by your organization's internal certification authority) and you have not provided a trust store containing the server's self-signed certificate (or the trusted root certificate(s) for the CA that signed your server certificate).

This problem can also occur if your server certificate has expired or has been revoked. If you have access to the server log you will likely see the following exception logged each time the client attempts to connect:

javax.net.ssl.SSLHandshakeException: Received fatal alert: ...

The remainder of the exception message will usually provide a code that indicates why the client rejected the server's certificate.

Code Description
certificate_unknown Usually indicates that the client's trust store has not been properly configured.
certificate_expired Indicates that the server's certificate has expired and needs to be replaced.
certificate_revoked Indicates that the issuing certification authority (CA) has revoked the server's certificate and the certificate needs to be replaced.

Solutions

If the server's log message is reporting certificate_unknown then using either the Trust Store system properties or the trustStore property of the appender component's ssl property, you must specify the location and passphrase for the trust store containing the server's self-signed certificate or the issuing certificate authority's root certificate.

If the server's log message is reporting certificate_expired or certificate_revoked the server needs a new certificate. The new certificate and associated private key needs to be placed in the key store specified in the logging server's configuration. And, if using a self-signed server certificate, the server's certificate also needs to be placed in the trust store specified in the appender client's configuration.

Server Does Not Trust the Client

NOTE: This problem can occur only if you have explicitly configured the server to request a client certificate (using either the needClientAuth or wantClientAuth property).

When the appender client attempts to connect to the logging server, you see the following exception in the client's log:

javax.net.ssl.SSLHandshakeException: Received fatal alert: ...

The remainder of the exception message will usually provide a code that indicates why the server rejected the client's certificate.

Code Description
certificate_unknown Usually indicates that the server's trust store has not been properly configured.
certificate_expired Indicates that the client's certificate has expired and needs to be replaced.
certificate_revoked Indicates that the issuing certification authority (CA) has revoked the client's certificate and the certificate needs to be replaced.

Solutions

If the client's log message is reporting bad_certificate then using either the Trust Store system properties or the trustStore property of the server component's ssl property, you must specify the location and passphrase for the trust store containing the client's self-signed certificate or the issuing certificate authority's root certificate.

If the server's log message is reporting certificate_expired or certificate_revoked the client needs a new certificate. The new certificate and associated private key needs to be placed in the key store specified in the appender client's configuration. And, if using a self-signed client certificate, the client's certificate also needs to be placed in the trust store specified in the logging servers's configuration.

Client and Server Cannot Agree on a Protocol

NOTE: This problem usually occurs only when you are explicitly excluding or including SSL protocols in your configuration.

When the appender client attempts to connect to the logging server, you see the following exception in the log:

javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure

The server's log message is usually more descriptive. For example:

javax.net.ssl.SSLHandshakeException: SSLv2Hello is disabled

Generally, this means that you have excluded a protocol from one of the peers and not the other.

Solution

Check the values specified for the excludedProtocols and includedProtocols properties on both the logging server and appender client.

Client and Server Cannot Agree on a Cipher Suite

NOTE: This problem usually occurs only when you are explicitly excluding or including SSL cipher suites in your configuration.

When the appender client attempts to connect to the logging server, you see the following exception in the log:

javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure

The server's log message is usually more descriptive:

javax.net.ssl.SSLHandshakeException: no cipher suites in common

This means that you have configured the cipher suites on the logging server and appender client such that the intersection of their respective sets of enabled cipher suites is empty.

Solution

Check the values specified for the excludedCipherSuites and includedCipherSuites properties on both the server and client.