Using SSL
Logback supports the use of the Secure Sockets Layer (SSL) when
delivering log events to a remote log server using
SSLSocketAppender
. 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. Logback components such as SSLSocketAppender
provide the ability to fully specify all of the configurable
aspects of the SSL engine and cryptographic providers, to meet your
unique security needs.
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:
- 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).
- 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
Logback components such as
SSLSocketAppender
support a large number of SSL
configuration properties. Fortunately, nearly all of the configurable
properties have reasonable defaults. In most cases all that is needed
for an SSL client (such as SSLSocketAppender
) is the
configuration for the trustStore property,
which specifies the location, passphrase, and type of the key store
containing your trusted CA certificate(s).
The remainder of this section describes all of the configuration properties that are available, for those situations in which the defaults are not adequate.
SSL Configuration
When configuring a Logback component that supports SSL, you specify
the SSL configuration using the ssl
property. This
configuration element corresponds to the
SSLConfiguration
class, which supports several
configurable properties as shown in the table below.
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
When configuring an SSL client (e.g. When configuring an SSL server (e.g. 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
The trust store specified by this property overrides any trust
store specified by the JSSE's |
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 | 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. |
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