diff options
Diffstat (limited to 'src/third_party/wiredtiger/src/docs/encryption.dox')
-rw-r--r-- | src/third_party/wiredtiger/src/docs/encryption.dox | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/src/third_party/wiredtiger/src/docs/encryption.dox b/src/third_party/wiredtiger/src/docs/encryption.dox new file mode 100644 index 00000000000..e3051cf25e9 --- /dev/null +++ b/src/third_party/wiredtiger/src/docs/encryption.dox @@ -0,0 +1,124 @@ +/*! @m_page{{c,java},encryption,Encryptors} + +@section encryption_overview Overview of Encryption in WiredTiger +@ref encryption_custom "Custom encryption engines" may be used to +extend WiredTiger. WiredTiger does not currently offer builtin +support for any particular encryption algorithm. +@ref encryption_examples "Example encryption code" is provided +to demonstrate how encryption extensions are created. + +\warning 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 or \em swap devices must be +considered when planning the security of a system. + +The encryption extension must be loaded in the ::wiredtiger_open call. +See @subpage_single extensions for details on how extensions are loaded. +Also, encryption is specified using \c encryption= in the configuration +for the ::wiredtiger_open 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. + +It is also possible to use different encryption options when individual +data files are first created, using the \c encryption= configuration in +the WT_SESSION::create call. Such options override the default +(<em>system</em>) encryption that was indicated in the ::wiredtiger_open +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 \c keyid. + +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. + +It is an error to specify encryption in a WT_SESSION::create call when it +was not specified in the ::wiredtiger_open call. This prevents accidental +exposure of the file's data in log files, which would be written in the +clear in such a scenario. + +\warning When using separate keys for individual data files or tables, the +key used for the \em system encryption continues to have fundamental +importance. The database log, protected by the \em system encryption, +contains a shared stream of changes to all data files. Thus, if the \em +system 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. + +@section encryption_parameters Encryption keyid and secretkey + +Two parameters, \c keyid and \c secretkey, may be specified +when configuring encryption for ::wiredtiger_open to allow the possibility +of varying the algorithm according to different keys. + +The configuration parameter <code>encryption=(keyid=<em>identifier</em>)</code> +may be used in ::wiredtiger_open or WT_SESSION::create calls. This is intended +to reference a key stored using a Key Management Solution (KMS). +The \c keyid given to ::wiredtiger_open is stored in the clear in +WiredTiger configuration files; it should never contain sensitive +information. As an example, with a \c keyid of \c "customerABC", +the encryptor would consult the KMS to return a key previously stored +for \c "customerABC". The encryptor will use the returned key when +applying the encryption. To effectively use the \c keyid, a custom +encryptor must implement the WT_ENCRYPTOR::customize callback. +It is during \c customize that the encryptor has an opportunity to use +the \c keyid to fetch the actual key. The \c customize function is +called on the first use of a \c keyid, and the same \em customized encryptor +will be used with each use of the same \c keyid. + +The configuration parameter <code>encryption=(secretkey)</code> is used +only in the ::wiredtiger_open 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 ::wiredtiger_open call). +The secretkey is available to the encryptor during the +WT_ENCRYPTOR::customize callback, during which the encryptor may +be \em customized to keep the secretkey or a transformation of it +for use during the WT_ENCRYPTOR::encrypt and WT_ENCRYPTOR::decrypt callbacks. + +If a \c secretkey is used, it must be provided using the \c -E option +when using the \c wt utility. Specifying \c keyid is not needed with the \c wt +utility, as the \c keyid is stored in the clear on disk by WiredTiger. +Any additional \c keyid values needed to decrypt data files +are stored in WiredTiger metadata using the system encryptor. + +@section encryption_custom Custom encryption engines + +WiredTiger may be extended by adding custom encryption engines +that we call \em encryptors. Custom encryptors must be coded in the C language. +Once packaged, they can be used in any language. + +See @subpage_single extensions for general details on extending WiredTiger, +and see WT_ENCRYPTOR for the encryptor interface. + +Custom encryptors are registered by calling WT_CONNECTION::add_encryptor, +this creates an encryptor name that may be referenced using the +<code>encryption=(name=...</code> configuration string in the ::wiredtiger_open +or WT_SESSION::create call. + +@section encryption_examples Encryption examples + +There are two kinds of example code with overlapping functionality. +A simple, self contained encryption example is in @ex_ref{ex_encrypt.c}. +This example includes a small encryptor that rotates letters in the +alphabet by a fixed amount, based on the value of \c keyid. This example +also shows how encryption is configured within an application. +The second set of examples are in \c ext/encryptors. These are +encryptors only (no application level code), showing how encryptors +might be packaged in a loadable shared library. +@ex_ref{nop_encrypt.c} merely copies its input to its output. +@ex_ref{rotn_encrypt.c} is an extended version of the example that +rotates the alphabet. It adds a twist in that a \c secretkey can +be specified, changing the rotation per letter. The Python test suite +uses the rotn encryptor to help test the encryption framework. + +Please note that these samples are for demonstration use only. +They do not provide any security. + */ |