# 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:

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

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 `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

`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