mirror of
https://github.com/apache/httpd.git
synced 2025-08-10 02:56:11 +00:00
a00902189d
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1752104 13f79535-47bb-0310-9956-ffa450edef68
279 lines
10 KiB
XML
279 lines
10 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_crypto.xml.meta">
|
|
|
|
<name>mod_crypto</name>
|
|
<description>Support for symmetrical encryption and decryption</description>
|
|
<status>Extension</status>
|
|
<sourcefile>mod_crypto.c</sourcefile>
|
|
<identifier>crypto_module</identifier>
|
|
<compatibility>Available in Apache 2.5 and later</compatibility>
|
|
|
|
<summary>
|
|
<p>This module provides the ability to <strong>encrypt and decrypt</strong>
|
|
data on the input and output filter stacks.</p>
|
|
|
|
<p>Most specifically, it can be used to implement <strong>on-the-fly HLS
|
|
encryption</strong> as described by
|
|
<a href="http://www.ietf.org/id/draft-pantos-http-live-streaming-19.txt">
|
|
draft-pantos-http-live-streaming-19</a>.</p>
|
|
|
|
<p>Alternatively, it can be used to deliver secure data over insecure CDN
|
|
to suitable clients.</p>
|
|
|
|
<p>The crypto filter may be added to either the input or the
|
|
output filter stacks, as appropriate, using the
|
|
<directive module="core">SetInputFilter</directive>,
|
|
<directive module="core">SetOutputFilter</directive>,
|
|
<directive module="mod_mime">AddOutputFilter</directive> or
|
|
<directive module="mod_filter">AddOutputFilterByType</directive> directives.</p>
|
|
|
|
</summary>
|
|
<seealso><a href="../filter.html">Filters</a></seealso>
|
|
|
|
<section id="format">
|
|
<title>Stream Format</title>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>When the IV is specified with the <directive module="mod_crypto">CryptoIV</directive>
|
|
directive, that IV is used, and is not written to or read from the stream.</p>
|
|
|
|
</section>
|
|
|
|
<section id="config">
|
|
<title>Keys and IVs</title>
|
|
|
|
<p>
|
|
The
|
|
<directive module="mod_crypto">CryptoKey</directive>
|
|
and
|
|
<directive module="mod_crypto">CryptoIV</directive>
|
|
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.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt>file:</dt><dd>Read the value directly from the given file.</dd>
|
|
<dt>hex:</dt><dd>Parse the expression as a hex value, which may contain colon separators.</dd>
|
|
<dt>decimal:</dt><dd>Parse the expression as a decimal value.</dd>
|
|
<dt>base64:</dt><dd>Parse the expression as a base64 value.</dd>
|
|
<dt>none</dt><dd>No value is specified.</dd>
|
|
</dl>
|
|
|
|
<p>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.
|
|
</p>
|
|
|
|
<p>With the exception of file:, the <directive module="mod_crypto">CryptoKey</directive>
|
|
and <directive module="mod_crypto">CryptoIV</directive> directives allow
|
|
<a href="../expr.html">expression syntax</a> 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.
|
|
</p>
|
|
|
|
</section>
|
|
|
|
<section id="handler">
|
|
<title>Crypto Key Handler</title>
|
|
|
|
<p>For convenience, the <strong>crypto-key</strong> 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 <a href="../expr.html">expression
|
|
syntax</a> to be used to derive the key for both the clients and the encrypted content.</p>
|
|
|
|
<example><title>Crypto Key Handler with a File</title>
|
|
<Location /key><br />
|
|
<indent>
|
|
SetHandler crypto-key<br />
|
|
CryptoCipher aes128<br />
|
|
CryptoKey file:/path/to/file.key<br />
|
|
AuthType basic<br />
|
|
...<br />
|
|
</indent>
|
|
</Location><br />
|
|
</example>
|
|
|
|
</section>
|
|
|
|
<section id="hls">
|
|
<title>HTTP Live Streaming</title>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The IV used for encrypting each media segment is specified within
|
|
HLS in one of two ways:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
Explicitly specified within an IV attribute inside the EXT-X-KEY
|
|
tag as a <strong>hexadecimal</strong> value.
|
|
</li>
|
|
<li>
|
|
Implicitly specified by interpreting the <strong>decimal</strong>
|
|
value of the EXT-X-MEDIA-SEQUENCE tag.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>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.
|
|
</p>
|
|
|
|
<example><title>HLS Example - IV from media sequence</title>
|
|
<LocationMatch (?<SEQUENCE>[\d]+)[^\d^/]+$><br />
|
|
<indent>
|
|
SetOutputFilter ENCRYPT<br />
|
|
CryptoCipher aes128<br />
|
|
CryptoKey file:/path/to/file.key<br />
|
|
CryptoIV decimal:%{env:MATCH_SEQUENCE}<br />
|
|
</indent>
|
|
</LocationMatch><br />
|
|
</example>
|
|
|
|
</section>
|
|
|
|
<directivesynopsis>
|
|
<name>CryptoDriver</name>
|
|
<description>Name of the crypto driver to use</description>
|
|
<syntax>CryptoDriver name</syntax>
|
|
<default>CryptoDriver openssl</default>
|
|
<contextlist><context>server config</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive module="mod_crypto">CryptoDriver</directive>
|
|
directive specifies the name of the crypto driver to use. There is usually
|
|
a recommended default driver on each platform. Possible values include
|
|
<strong>openssl</strong>, <strong>commoncrypto</strong> and
|
|
<strong>nss</strong>.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>CryptoCipher</name>
|
|
<description>Cipher to be used by the crypto filter</description>
|
|
<syntax>CryptoCipher name</syntax>
|
|
<default>CryptoCipher aes256</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
<context>.htaccess</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>CryptoCipher</directive> directive allows specification of
|
|
the cipher to be used during encryption or decryption. If not specified, the
|
|
cipher defaults to <code>aes256</code>.</p>
|
|
|
|
<p>Possible values depend on the crypto driver in use, and could be one of:</p>
|
|
|
|
<ul><li>3des192</li><li>aes128</li><li>aes192</li><li>aes256</li></ul>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>CryptoIV</name>
|
|
<description>IV (Initialisation Vector) to be used by the crypto filter</description>
|
|
<syntax>CryptoIV value</syntax>
|
|
<default>CryptoIV none</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
<context>.htaccess</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>CryptoIV</directive> 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 <a href="../expr.html">expression parser</a>,
|
|
allowing for flexible scenarios for the setting of keys.</p>
|
|
|
|
<p>Values can be specified as read from a file, or as a hexadecimal, decimal or
|
|
base64 value based on the following prefixes:</p>
|
|
|
|
<ul><li>file:</li><li>hex:</li><li>decimal:</li><li>base64:</li></ul>
|
|
|
|
<p>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.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>CryptoKey</name>
|
|
<description>Key to be used by the crypto filter</description>
|
|
<syntax>CryptoKey value</syntax>
|
|
<default>CryptoKey none</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
<context>.htaccess</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>CryptoKey</directive> 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 <a href="../expr.html">expression parser</a>, allowing for
|
|
flexible scenarios for the setting of keys.</p>
|
|
|
|
<p>Values can be specified as read from a file, or as a hexadecimal, decimal or
|
|
base64 value based on the following prefixes:</p>
|
|
|
|
<ul><li>file:</li><li>hex:</li><li>decimal:</li><li>base64:</li></ul>
|
|
|
|
<p>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.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>CryptoSize</name>
|
|
<description>Maximum size in bytes to buffer by the crypto filter</description>
|
|
<syntax>CryptoSize integer</syntax>
|
|
<default>CryptoSize 131072</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
<context>.htaccess</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive module="mod_crypto">CryptoSize</directive>
|
|
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.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
</modulesynopsis>
|