Apache HTTP Server Version 2.5

Apache > HTTP Server > Documentation > Version 2.5 > Modules

# Apache Module mod_crypto

Description: | Support for symmetrical encryption and decryption
Status: | Extension
Module Identifier: | crypto_module
Source File: | mod_crypto.c
Compatibility: | Available in Apache 2.5 and later

### Summary

This module provides the ability to encrypt and decrypt data on the input and output filter stacks.

Most specifically, it can be used to implement on-the-fly HLS encryption as described by draft-pantos-http-live-streaming-19.

Alternatively, it can be used to deliver secure data over insecure CDN to suitable clients.

The crypto filter may be added to either the input or the output filter stacks, as appropriate, using the `SetInputFilter`, `SetOutputFilter`, `AddOutputFilter` or `AddOutputFilterByType` directives.

### Topics

- Stream Format
- Keys and IVs
- Crypto Key Handler
- HTTP Live Streaming

### Directives

### Bugfix checklist

- httpd changelog
- Known issues
- Report a bug

### See also

- Filters

## Stream Format ¶

The encrypted stream consists of an optional IV block, followed by encrypted blocks using the chosen cipher. The final block is padded before being written. The size of the blocks is governed by the choice of cipher in use.

When the IV is specified with the `CryptoIV` directive, that IV is used, and is not written to or read from the stream.

## Keys and IVs ¶

The `CryptoKey` and `CryptoIV` directives expect binary values which can be specified in a number of ways as below. The most significant bits of the relevant values are used, and if the values are too short, they are padded on the left with zero bits.

file:
  Read the value directly from the given file.
hex:
  Parse the expression as a hex value, which may contain colon separators.
decimal:
  Parse the expression as a decimal value.
base64:
  Parse the expression as a base64 value.
none
  No value is specified.

If the IV is unspecified a random IV will be generated during encryption and written as the first block. During decryption, the first block will be interpreted as the IV.

With the exception of file:, the `CryptoKey` and `CryptoIV` directives allow expression syntax to provide flexibility when setting the values. This allows both keys and IVs to be salted with values available to the webserver, such as REMOTE_USER, or the URL.

## Crypto Key Handler ¶

For convenience, the crypto-key handler can be used to serve the key to suitably authorized clients, removing the need to store the key within the directory space of the webserver. This also allows the same expression syntax to be used to derive the key for both the clients and the encrypted content.

### Crypto Key Handler with a File

`<Location /key>
SetHandler crypto-key
CryptoCipher aes128
CryptoKey file:/path/to/file.key
AuthType basic
...
</Location>
`

## HTTP Live Streaming ¶

The HLS protocol supports encrypted streams using the AES-128 cipher and a corresponding key. Access is granted to the stream by sharing the key with the HLS client, typically over a secured connection.

The IV used for encrypting each media segment is specified within HLS in one of two ways:

- Explicitly specified within an IV attribute inside the EXT-X-KEY tag as a hexadecimal value.
- Implicitly specified by interpreting the decimal value of the EXT-X-MEDIA-SEQUENCE tag.

The media sequence value is usually embedded within the media segment filenames, and can be matched by using named regular expressions as per the example below.

### HLS Example - IV from media sequence

`<LocationMatch (?<SEQUENCE>[\d]+)[^\d^/]+$>
SetOutputFilter ENCRYPT
CryptoCipher aes128
CryptoKey file:/path/to/file.key
CryptoIV decimal:%{env:MATCH_SEQUENCE}
</LocationMatch>
`

## CryptoCipher Directive ¶

Description: | Cipher to be used by the crypto filter
Syntax: | `CryptoCipher name`
Default: | `CryptoCipher aes256`
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_crypto

The `CryptoCipher` directive allows specification of the cipher to be used during encryption or decryption. 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

## CryptoDriver Directive ¶

Description: | Name of the crypto driver to use
Syntax: | `CryptoDriver name`
Default: | `CryptoDriver openssl`
Context: | server config
Status: | Extension
Module: | mod_crypto

The `CryptoDriver` directive specifies the name of the crypto driver to use. There is usually a recommended default driver on each platform. Possible values include openssl, commoncrypto and nss.

## CryptoIV Directive ¶

Description: | IV (Initialisation Vector) to be used by the crypto filter
Syntax: | `CryptoIV value`
Default: | `CryptoIV none`
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_crypto

The `CryptoIV` directive allows the IV (initialisation vector) to be specified for the particular URL space. The IV can be read from a file, or can be set based on the expression parser, allowing for flexible scenarios for the setting of keys.

Values can be specified as read from a file, or as a hexadecimal, decimal or base64 value based on the following prefixes:

- file:
- hex:
- decimal:
- base64:

The value 'none' disables setting of the IV. In this case, during encryption a random IV will be generated and inserted as the first block, and during decryption the first block will interpreted as the IV.

## CryptoKey Directive ¶

Description: | Key to be used by the crypto filter
Syntax: | `CryptoKey value`
Default: | `CryptoKey none`
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_crypto

The `CryptoKey` directive allows the encryption / decryption key to be specified for the particular URL space. The key can be read from a file, or can be set based on the expression parser, allowing for flexible scenarios for the setting of keys.

Values can be specified as read from a file, or as a hexadecimal, decimal or base64 value based on the following prefixes:

- file:
- hex:
- decimal:
- base64:

The value 'none' disables the key. An attempt to serve a file through the ENCRYPT or DECRYPT filters without a key will cause the request to fail.

## CryptoSize Directive ¶

Description: | Maximum size in bytes to buffer by the crypto filter
Syntax: | `CryptoSize integer`
Default: | `CryptoSize 131072`
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_crypto

The `CryptoSize` directive specifies the amount of data in bytes that will be buffered before being encrypted or decrypted during each request. The default is 128 kilobytes.