Apache HTTP Server Version 2.5

Apache > HTTP Server > Documentation > Version 2.5 > Modules

# Apache Module mod_session_crypto

Description: | Session encryption support
Status: | Experimental
Module Identifier: | session_crypto_module
Source File: | mod_session_crypto.c
Compatibility: | Available in Apache 2.3 and later

### Summary

### Warning

The session modules make use of HTTP cookies, and as such can fall victim to Cross Site Scripting attacks, or expose potentially private information to clients. Please ensure that the relevant risks have been taken into account before enabling the session functionality on your server.

This submodule of `mod_session` provides support for the encryption of user sessions before being written to a local database, or written to a remote browser via an HTTP cookie.

This can help provide privacy to user sessions where the contents of the session should be kept private from the user, or where protection is needed against the effects of cross site scripting attacks.

For more details on the session interface, see the documentation for the `mod_session` module.

### Topics

- Basic Usage

### Directives

### Bugfix checklist

- httpd changelog
- Known issues
- Report a bug

### See also

- `mod_session`
- `mod_session_cookie`
- `mod_session_dbd`

## Basic Usage ¶

To create a simple encrypted session and store it in a cookie called session, configure the session as follows:

### Browser based encrypted session

    Session On
    SessionCookieName session path=/
    SessionCryptoPassphrase secret

The session will be encrypted with the given key. Different servers can be configured to share sessions by ensuring the same encryption key is used on each server.

If the encryption key is changed, sessions will be invalidated automatically.

For documentation on how the session can be used to store username and password details, see the `mod_auth_form` module.

## SessionCryptoCipher Directive ¶

Description: | The crypto cipher to be used to encrypt the session
Syntax: | `SessionCryptoCipher name`
Default: | `SessionCryptoCipher aes256`
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_session_crypto
Compatibility: | Available in Apache 2.3.0 and later

The `SessionCryptoCipher` directive allows the cipher to be used during encryption. If not specified, the cipher defaults to `aes256`.

Possible values depend on the crypto driver in use, and could be one of:

- 3des192
- aes128
- aes192
- aes256

## SessionCryptoDriver Directive ¶

Description: | The crypto driver to be used to encrypt the session
Syntax: | `SessionCryptoDriver name [param[=value]]`
Default: | `none`
Context: | server config
Status: | Experimental
Module: | mod_session_crypto
Compatibility: | Available in Apache 2.3.0 and later

The `SessionCryptoDriver` directive specifies the name of the crypto driver to be used for encryption. If not specified, the driver defaults to the recommended driver compiled into APR-util.

The NSS crypto driver requires some parameters for configuration, which are specified as parameters with optional values after the driver name.

### NSS without a certificate database

    SessionCryptoDriver nss

### NSS with certificate database

    SessionCryptoDriver nss dir=certs

### NSS with certificate database and parameters

    SessionCryptoDriver nss dir=certs key3=key3.db cert7=cert7.db secmod=secmod

### NSS with paths containing spaces

    SessionCryptoDriver nss "dir=My Certs" key3=key3.db cert7=cert7.db secmod=secmod

The NSS crypto driver might have already been configured by another part of the server, for example from `mod_nss` or `mod_ldap`. If found to have already been configured, a warning will be logged, and the existing configuration will have taken affect. To avoid this warning, use the noinit parameter as follows.

### NSS with certificate database

    SessionCryptoDriver nss noinit

To prevent confusion, ensure that all modules requiring NSS are configured with identical parameters.

The openssl crypto driver supports an optional parameter to specify the engine to be used for encryption.

### OpenSSL with engine support

    SessionCryptoDriver openssl engine=name

## SessionCryptoPassphrase Directive ¶

Description: | The key used to encrypt the session
Syntax: | `SessionCryptoPassphrase secret [ secret ... ]`
Default: | `none`
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_session_crypto
Compatibility: | Available in Apache 2.3.0 and later

The `SessionCryptoPassphrase` directive specifies the keys to be used to enable symmetrical encryption on the contents of the session before writing the session, or decrypting the contents of the session after reading the session.

Keys are more secure when they are long, and consist of truly random characters. Changing the key on a server has the effect of invalidating all existing sessions.

Multiple keys can be specified in order to support key rotation. The first key listed will be used for encryption, while all keys listed will be attempted for decryption. To rotate keys across multiple servers over a period of time, add a new secret to the end of the list, and once rolled out completely to all servers, remove the first key from the start of the list.

As of version 2.4.7 if the value begins with exec: the resulting command will be executed and the first line returned to standard output by the program will be used as the key.

    #key used as-is
    SessionCryptoPassphrase secret

    #Run /path/to/program to get key
    SessionCryptoPassphrase exec:/path/to/program

    #Run /path/to/otherProgram and provide arguments
    SessionCryptoPassphrase "exec:/path/to/otherProgram argument1"

## SessionCryptoPassphraseFile Directive ¶

Description: | File containing keys used to encrypt the session
Syntax: | `SessionCryptoPassphraseFile filename`
Default: | `none`
Context: | server config, virtual host, directory
Status: | Experimental
Module: | mod_session_crypto
Compatibility: | Available in Apache 2.3.0 and later

The `SessionCryptoPassphraseFile` directive specifies the name of a configuration file containing the keys to use for encrypting or decrypting the session, specified one per line. The file is read on server start, and a graceful restart will be necessary for httpd to pick up changes to the keys.

Unlike the `SessionCryptoPassphrase` directive, the keys are not exposed within the httpd configuration and can be hidden by protecting the file appropriately.

Multiple keys can be specified in order to support key rotation. The first key listed will be used for encryption, while all keys listed will be attempted for decryption. To rotate keys across multiple servers over a period of time, add a new secret to the end of the list, and once rolled out completely to all servers, remove the first key from the start of the list.