1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
7 This file is generated from xml source: DO NOT EDIT
8 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
10 <title>mod_crypto - Apache HTTP Server Version 2.5</title>
11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
19 <div id="page-header">
20 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
21 <p class="apache">Apache HTTP Server Version 2.5</p>
22 <img alt="" src="../images/feather.png" /></div>
23 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
25 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Modules</a></div>
26 <div id="page-content">
27 <div id="preamble"><h1>Apache Module mod_crypto</h1>
29 <p><span>Available Languages: </span><a href="../en/mod/mod_crypto.html" title="English"> en </a> |
30 <a href="../fr/mod/mod_crypto.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
32 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Support for symmetrical encryption and decryption</td></tr>
33 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
34 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>crypto_module</td></tr>
35 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_crypto.c</td></tr>
36 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.5 and later</td></tr></table>
39 <p>This module provides the ability to <strong>encrypt and decrypt</strong>
40 data on the input and output filter stacks.</p>
42 <p>Most specifically, it can be used to implement <strong>on-the-fly HLS
43 encryption</strong> as described by
44 <a href="http://www.ietf.org/id/draft-pantos-http-live-streaming-19.txt">
45 draft-pantos-http-live-streaming-19</a>.</p>
47 <p>Alternatively, it can be used to deliver secure data over insecure CDN
48 to suitable clients.</p>
50 <p>The crypto filter may be added to either the input or the
51 output filter stacks, as appropriate, using the
52 <code class="directive"><a href="../mod/core.html#setinputfilter">SetInputFilter</a></code>,
53 <code class="directive"><a href="../mod/core.html#setoutputfilter">SetOutputFilter</a></code>,
54 <code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code> or
55 <code class="directive"><a href="../mod/mod_filter.html#addoutputfilterbytype">AddOutputFilterByType</a></code> directives.</p>
58 <div id="quickview"><h3>Topics</h3>
60 <li><img alt="" src="../images/down.gif" /> <a href="#format">Stream Format</a></li>
61 <li><img alt="" src="../images/down.gif" /> <a href="#config">Keys and IVs</a></li>
62 <li><img alt="" src="../images/down.gif" /> <a href="#handler">Crypto Key Handler</a></li>
63 <li><img alt="" src="../images/down.gif" /> <a href="#hls">HTTP Live Streaming</a></li>
64 </ul><h3 class="directives">Directives</h3>
66 <li><img alt="" src="../images/down.gif" /> <a href="#cryptocipher">CryptoCipher</a></li>
67 <li><img alt="" src="../images/down.gif" /> <a href="#cryptodriver">CryptoDriver</a></li>
68 <li><img alt="" src="../images/down.gif" /> <a href="#cryptoiv">CryptoIV</a></li>
69 <li><img alt="" src="../images/down.gif" /> <a href="#cryptokey">CryptoKey</a></li>
70 <li><img alt="" src="../images/down.gif" /> <a href="#cryptosize">CryptoSize</a></li>
72 <h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&list_id=144532&product=Apache%20httpd-2&query_format=specific&order=changeddate%20DESC%2Cpriority%2Cbug_severity&component=mod_crypto">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&component=mod_crypto">Report a bug</a></li></ul><h3>See also</h3>
74 <li><a href="../filter.html">Filters</a></li>
75 <li><a href="#comments_section">Comments</a></li></ul></div>
76 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
78 <h2><a name="format" id="format">Stream Format</a><a title="Permanent link" href="#format" class="permalink">¶</a></h2>
81 <p>The encrypted stream consists of an optional IV block, followed by encrypted
82 blocks using the chosen cipher. The final block is padded before being written. The
83 size of the blocks is governed by the choice of cipher in use.</p>
85 <p>When the IV is specified with the <code class="directive"><a href="#cryptoiv">CryptoIV</a></code>
86 directive, that IV is used, and is not written to or read from the stream.</p>
88 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
90 <h2><a name="config" id="config">Keys and IVs</a><a title="Permanent link" href="#config" class="permalink">¶</a></h2>
95 <code class="directive"><a href="#cryptokey">CryptoKey</a></code>
97 <code class="directive"><a href="#cryptoiv">CryptoIV</a></code>
98 directives expect binary
99 values which can be specified in a number of ways as below. The most significant bits of the relevant values
100 are used, and if the values are too short, they are padded on the left
105 <dt>file:</dt><dd>Read the value directly from the given file.</dd>
106 <dt>hex:</dt><dd>Parse the expression as a hex value, which may contain colon separators.</dd>
107 <dt>decimal:</dt><dd>Parse the expression as a decimal value.</dd>
108 <dt>base64:</dt><dd>Parse the expression as a base64 value.</dd>
109 <dt>none</dt><dd>No value is specified.</dd>
112 <p>If the IV is unspecified a random IV will be generated during
113 encryption and written
114 as the first block. During decryption, the first block will be
115 interpreted as the IV.
118 <p>With the exception of file:, the <code class="directive"><a href="#cryptokey">CryptoKey</a></code>
119 and <code class="directive"><a href="#cryptoiv">CryptoIV</a></code> directives allow
120 <a href="../expr.html">expression syntax</a> to provide flexibility when setting the values.
121 This allows both keys and IVs to be salted with values available to the webserver, such
122 as REMOTE_USER, or the URL.
125 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
126 <div class="section">
127 <h2><a name="handler" id="handler">Crypto Key Handler</a><a title="Permanent link" href="#handler" class="permalink">¶</a></h2>
130 <p>For convenience, the <strong>crypto-key</strong> handler can be used to serve the key
131 to suitably authorized clients, removing the need to store the key within the directory
132 space of the webserver. This also allows the same <a href="../expr.html">expression
133 syntax</a> to be used to derive the key for both the clients and the encrypted content.</p>
135 <div class="example"><h3>Crypto Key Handler with a File</h3><p><code>
136 <Location /key><br />
137 <span class="indent">
138 SetHandler crypto-key<br />
139 CryptoCipher aes128<br />
140 CryptoKey file:/path/to/file.key<br />
144 </Location><br />
147 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
148 <div class="section">
149 <h2><a name="hls" id="hls">HTTP Live Streaming</a><a title="Permanent link" href="#hls" class="permalink">¶</a></h2>
152 <p>The HLS protocol supports encrypted streams using the AES-128 cipher and a
153 corresponding key. Access is granted to the stream by sharing the key with
154 the HLS client, typically over a secured connection.</p>
156 <p>The IV used for encrypting each media segment is specified within
157 HLS in one of two ways:</p>
161 Explicitly specified within an IV attribute inside the EXT-X-KEY
162 tag as a <strong>hexadecimal</strong> value.
165 Implicitly specified by interpreting the <strong>decimal</strong>
166 value of the EXT-X-MEDIA-SEQUENCE tag.
170 <p>The media sequence value is usually embedded within the media
171 segment filenames, and can be matched by using named regular
172 expressions as per the example below.
175 <div class="example"><h3>HLS Example - IV from media sequence</h3><p><code>
176 <LocationMatch (?<SEQUENCE>[\d]+)[^\d^/]+$><br />
177 <span class="indent">
178 SetOutputFilter ENCRYPT<br />
179 CryptoCipher aes128<br />
180 CryptoKey file:/path/to/file.key<br />
181 CryptoIV decimal:%{env:MATCH_SEQUENCE}<br />
183 </LocationMatch><br />
187 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
188 <div class="directive-section"><h2><a name="CryptoCipher" id="CryptoCipher">CryptoCipher</a> <a name="cryptocipher" id="cryptocipher">Directive</a><a title="Permanent link" href="#cryptocipher" class="permalink">¶</a></h2>
189 <table class="directive">
190 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Cipher to be used by the crypto filter</td></tr>
191 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CryptoCipher name</code></td></tr>
192 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CryptoCipher aes256</code></td></tr>
193 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
194 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
195 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_crypto</td></tr>
197 <p>The <code class="directive">CryptoCipher</code> directive allows specification of
198 the cipher to be used during encryption or decryption. If not specified, the
199 cipher defaults to <code>aes256</code>.</p>
201 <p>Possible values depend on the crypto driver in use, and could be one of:</p>
203 <ul><li>3des192</li><li>aes128</li><li>aes192</li><li>aes256</li></ul>
207 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
208 <div class="directive-section"><h2><a name="CryptoDriver" id="CryptoDriver">CryptoDriver</a> <a name="cryptodriver" id="cryptodriver">Directive</a><a title="Permanent link" href="#cryptodriver" class="permalink">¶</a></h2>
209 <table class="directive">
210 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Name of the crypto driver to use</td></tr>
211 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CryptoDriver name</code></td></tr>
212 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CryptoDriver openssl</code></td></tr>
213 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
214 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
215 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_crypto</td></tr>
217 <p>The <code class="directive"><a href="#cryptodriver">CryptoDriver</a></code>
218 directive specifies the name of the crypto driver to use. There is usually
219 a recommended default driver on each platform. Possible values include
220 <strong>openssl</strong>, <strong>commoncrypto</strong> and
221 <strong>nss</strong>.</p>
224 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
225 <div class="directive-section"><h2><a name="CryptoIV" id="CryptoIV">CryptoIV</a> <a name="cryptoiv" id="cryptoiv">Directive</a><a title="Permanent link" href="#cryptoiv" class="permalink">¶</a></h2>
226 <table class="directive">
227 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>IV (Initialisation Vector) to be used by the crypto filter</td></tr>
228 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CryptoIV value</code></td></tr>
229 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CryptoIV none</code></td></tr>
230 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
231 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
232 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_crypto</td></tr>
234 <p>The <code class="directive">CryptoIV</code> directive allows the IV (initialisation
235 vector) to be specified for the particular URL space. The IV can be read from
236 a file, or can be set based on the <a href="../expr.html">expression parser</a>,
237 allowing for flexible scenarios for the setting of keys.</p>
239 <p>Values can be specified as read from a file, or as a hexadecimal, decimal or
240 base64 value based on the following prefixes:</p>
242 <ul><li>file:</li><li>hex:</li><li>decimal:</li><li>base64:</li></ul>
244 <p>The value 'none' disables setting of the IV. In this case, during encryption
245 a random IV will be generated and inserted as the first block, and during
246 decryption the first block will interpreted as the IV.</p>
249 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
250 <div class="directive-section"><h2><a name="CryptoKey" id="CryptoKey">CryptoKey</a> <a name="cryptokey" id="cryptokey">Directive</a><a title="Permanent link" href="#cryptokey" class="permalink">¶</a></h2>
251 <table class="directive">
252 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Key to be used by the crypto filter</td></tr>
253 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CryptoKey value</code></td></tr>
254 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CryptoKey none</code></td></tr>
255 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
256 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
257 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_crypto</td></tr>
259 <p>The <code class="directive">CryptoKey</code> directive allows the encryption / decryption
260 key to be specified for the particular URL space. The key can be read from a file, or
261 can be set based on the <a href="../expr.html">expression parser</a>, allowing for
262 flexible scenarios for the setting of keys.</p>
264 <p>Values can be specified as read from a file, or as a hexadecimal, decimal or
265 base64 value based on the following prefixes:</p>
267 <ul><li>file:</li><li>hex:</li><li>decimal:</li><li>base64:</li></ul>
269 <p>The value 'none' disables the key. An attempt to serve a file through the ENCRYPT
270 or DECRYPT filters without a key will cause the request to fail.</p>
273 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
274 <div class="directive-section"><h2><a name="CryptoSize" id="CryptoSize">CryptoSize</a> <a name="cryptosize" id="cryptosize">Directive</a><a title="Permanent link" href="#cryptosize" class="permalink">¶</a></h2>
275 <table class="directive">
276 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum size in bytes to buffer by the crypto filter</td></tr>
277 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CryptoSize integer</code></td></tr>
278 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CryptoSize 131072</code></td></tr>
279 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
280 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
281 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_crypto</td></tr>
283 <p>The <code class="directive"><a href="#cryptosize">CryptoSize</a></code>
284 directive specifies the amount of data in bytes that will be
285 buffered before being encrypted or decrypted during each request.
286 The default is 128 kilobytes.</p>
290 <div class="bottomlang">
291 <p><span>Available Languages: </span><a href="../en/mod/mod_crypto.html" title="English"> en </a> |
292 <a href="../fr/mod/mod_crypto.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
293 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
294 <script type="text/javascript"><!--//--><![CDATA[//><!--
295 var comments_shortname = 'httpd';
296 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_crypto.html';
298 if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
299 d.write('<div id="comments_thread"><\/div>');
300 var s = d.createElement('script');
301 s.type = 'text/javascript';
303 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
304 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
307 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
309 })(window, document);
310 //--><!]]></script></div><div id="footer">
311 <p class="apache">Copyright 2018 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
312 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
313 if (typeof(prettyPrint) !== 'undefined') {