-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathencryption_lang_java.html
108 lines (108 loc) · 11.7 KB
/
encryption_lang_java.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>WiredTiger: Encryptors in Java</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="wiredtiger.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><a href="http://wiredtiger.com/"><img alt="Logo" src="LogoFinal-header.png" alt="WiredTiger" /></a></td>
<td style="padding-left: 0.5em;">
<div id="projectname">
 <span id="projectnumber">Version 2.9.2</span>
</div>
<div id="projectbrief"><!-- 2.9.2 --></div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="banner">
<a href="https://github.com/wiredtiger/wiredtiger">Fork me on GitHub</a>
<a class="last" href="http://groups.google.com/group/wiredtiger-users">Join my user group</a>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.10 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
<li><a href="community.html"><span>Community</span></a></li>
<li><a href="license.html"><span>License</span></a></li>
</ul>
</div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('encryption_lang_java.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Encryptors in Java </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="encryption_overview_lang_java"></a>
Overview of Encryption in WiredTiger</h1>
<p><a class="el" href="encryption_lang_java.html#encryption_custom_lang_java">Custom encryption engines</a> may be used to extend WiredTiger. WiredTiger does not currently offer builtin support for any particular encryption algorithm. <a class="el" href="encryption_lang_java.html#encryption_examples_lang_java">Example encryption code</a> is provided to demonstrate how encryption extensions are created.</p>
<dl class="section warning"><dt>Warning</dt><dd>The encryption infrastructure included in WiredTiger, when used with a strong encryption algorithm, is intended to protect data stored in files (that is, <em>encryption at rest</em>). The table content (keys, values), the metadata pertaining to data (table, index, column names, and other configuration information) as well as the database log files are encrypted on disk. Decryption occurs when the data is read into memory; thus an attacker having the ability to directly read system memory will have access to unencrypted data. Many systems may also page memory to a backing disk under load. Access to any such <em>paging</em> or <em>swap</em> devices must be considered when planning the security of a system.</dd></dl>
<p>The encryption extension must be loaded in the <code>wiredtiger.open</code> call. See <a class="el" href="extensions.html">Extending WiredTiger</a> for details on how extensions are loaded. Also, encryption is specified using <code>encryption=</code> in the configuration for the <code>wiredtiger.open</code> call. This configuration establishes the encryption algorithm and keys to be used for database log files and a subset of the WiredTiger metadata files. By default, this same encryption is also used for all data files. We call this the <em>system</em> encryption.</p>
<p>It is also possible to use different encryption options when individual data files are first created, using the <code>encryption=</code> configuration in the Session.create call. Such options override the default (<em>system</em>) encryption that was indicated in the <code>wiredtiger.open</code> call for the individual data file. It is possible to turn encryption off for individual files, to use a different encryptor, or to specify a different <code>keyid</code>.</p>
<p>Overriding the system encryption for a table does not override the system encryption for indices on that table, nor does it override the system encryption for column groups specified on that table. Encryption for column groups and indices must specified when they are created, if they are to be different than the system encryption.</p>
<p>It is an error to specify encryption in a Session.create call when it was not specified in the <code>wiredtiger.open</code> call. This prevents accidental exposure of the file's data in log files, which would be written in the clear in such a scenario.</p>
<dl class="section warning"><dt>Warning</dt><dd>When using separate keys for individual data files or tables, the key used for the <em>system</em> encryption continues to have fundamental importance. The database log, protected by the <em>system</em> encryption, contains a shared stream of changes to all data files. Thus, if the <em>system</em> key is exposed, even when per-file keys are not exposed, an attacker can read database log files, and hence has access to data in individual files.</dd></dl>
<h1><a class="anchor" id="encryption_parameters_lang_java"></a>
Encryption keyid and secretkey</h1>
<p>Two parameters, <code>keyid</code> and <code>secretkey</code>, may be specified when configuring encryption for <code>wiredtiger.open</code> to allow the possibility of varying the algorithm according to different keys.</p>
<p>The configuration parameter <code>encryption=(keyid=<em>identifier</em>)</code> may be used in <code>wiredtiger.open</code> or Session.create calls. This is intended to reference a key stored using a Key Management Solution (KMS). The <code>keyid</code> given to <code>wiredtiger.open</code> is stored in the clear in WiredTiger configuration files; it should never contain sensitive information. As an example, with a <code>keyid</code> of <code>"customerABC"</code>, the encryptor would consult the KMS to return a key previously stored for <code>"customerABC"</code>. The encryptor will use the returned key when applying the encryption. To effectively use the <code>keyid</code>, a custom encryptor must implement the <a class="el" href="struct_w_t___e_n_c_r_y_p_t_o_r.html#a947e253ec628a29b62e4b6656eb7b92a" title="If non-NULL, this callback is called to customize the encryptor. ">WT_ENCRYPTOR::customize</a> callback. It is during <code>customize</code> that the encryptor has an opportunity to use the <code>keyid</code> to fetch the actual key. The <code>customize</code> function is called on the first use of a <code>keyid</code>, and the same <em>customized</em> encryptor will be used with each use of the same <code>keyid</code>.</p>
<p>The configuration parameter <code>encryption=(secretkey)</code> is used only in the <code>wiredtiger.open</code> call. The value of the secretkey is never stored on disk in any form, so it must always be provided when WiredTiger is reopened (again, with the <code>wiredtiger.open</code> call). The secretkey is available to the encryptor during the <a class="el" href="struct_w_t___e_n_c_r_y_p_t_o_r.html#a947e253ec628a29b62e4b6656eb7b92a" title="If non-NULL, this callback is called to customize the encryptor. ">WT_ENCRYPTOR::customize</a> callback, during which the encryptor may be <em>customized</em> to keep the secretkey or a transformation of it for use during the <a class="el" href="struct_w_t___e_n_c_r_y_p_t_o_r.html#a0f0f363b689363d36ffce7fdf8a337ac" title="Callback to encrypt a chunk of data. ">WT_ENCRYPTOR::encrypt</a> and <a class="el" href="struct_w_t___e_n_c_r_y_p_t_o_r.html#abad5447ebeb99d06b9024df435cffc26" title="Callback to decrypt a chunk of data. ">WT_ENCRYPTOR::decrypt</a> callbacks.</p>
<p>If a <code>secretkey</code> is used, it must be provided using the <code>-E</code> option when using the <code>wt</code> utility. Specifying <code>keyid</code> is not needed with the <code>wt</code> utility, as the <code>keyid</code> is stored in the clear on disk by WiredTiger. Any additional <code>keyid</code> values needed to decrypt data files are stored in WiredTiger metadata using the system encryptor.</p>
<h1><a class="anchor" id="encryption_custom_lang_java"></a>
Custom encryption engines</h1>
<p>WiredTiger may be extended by adding custom encryption engines that we call <em>encryptors</em>. Custom encryptors must be coded in the C language. Once packaged, they can be used in any language.</p>
<p>See <a class="el" href="extensions.html">Extending WiredTiger</a> for general details on extending WiredTiger, and see <a class="el" href="struct_w_t___e_n_c_r_y_p_t_o_r.html" title="The interface implemented by applications to provide custom encryption. ">WT_ENCRYPTOR</a> for the encryptor interface.</p>
<p>Custom encryptors are registered by calling Connection.add_encryptor, this creates an encryptor name that may be referenced using the <code>encryption=(name=...</code> configuration string in the <code>wiredtiger.open</code> or Session.create call.</p>
<h1><a class="anchor" id="encryption_examples_lang_java"></a>
Encryption examples</h1>
<p>There are two kinds of example code with overlapping functionality. A simple, self contained encryption example is in ex_encrypt.java. This example includes a small encryptor that rotates letters in the alphabet by a fixed amount, based on the value of <code>keyid</code>. This example also shows how encryption is configured within an application. The second set of examples are in <code>ext/encryptors</code>. These are encryptors only (no application level code), showing how encryptors might be packaged in a loadable shared library. <a class="el" href="nop_encrypt_8c-example.html">nop_encrypt.c</a> merely copies its input to its output. <a class="el" href="rotn_encrypt_8c-example.html">rotn_encrypt.c</a> is an extended version of the example that rotates the alphabet. It adds a twist in that a <code>secretkey</code> can be specified, changing the rotation per letter. The Python test suite uses the rotn encryptor to help test the encryption framework.</p>
<p>Please note that these samples are for demonstration use only. They do not provide any security. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">Reference Guide</a></li><li class="navelem"><a class="el" href="programming_lang_java.html">Writing WiredTiger applications in Java</a></li>
<li class="footer">Copyright (c) 2008-2016 MongoDB, Inc. All rights reserved. Contact <a href="mailto:[email protected]">[email protected]</a> for more information.</li>
</ul>
</div>
</body>
</html>