Add keywrap documentation

3 files changed, 62 insertions, 1 deletions

diff --git a/doc/manual/contents.rst b/doc/manual/contents.rst
index f3b11f7b0..0c9ac4b7f 100644
--- a/doc/manual/contents.rst
+++ b/doc/manual/contents.rst
@@ -23,6 +23,7 @@ Contents
    lowlevel
    kdf
    pbkdf
+   keywrap
    passhash
    cryptobox
    srp
diff --git a/doc/manual/keywrap.rst b/doc/manual/keywrap.rst
new file mode 100644
index 000000000..ae1172701
--- /dev/null
+++ b/doc/manual/keywrap.rst
@@ -0,0 +1,60 @@
+AES Key Wrapping
+=================================
+
+NIST specifies two mechanisms for wrapping (encrypting) symmetric keys using
+another key. The first (and older, more widely supported) methd requres the
+input be a multiple of 8 bytes long. The other allows any length input, though
+only up to 2**32 bytes.
+
+These algorithms are described in NIST SP 800-38F, and RFCs 3394 and 5694.
+
+This API, defined in ``nist_keywrap.h``, first became available in version 2.4.0
+
+These functions take an arbitrary 128-bit block cipher object, which must
+already have been keyed with the key encryption key. NIST only allows these
+functions with AES, but any 128-bit cipher will do and some other implementations
+(such as in OpenSSL) do also allow other ciphers.  Use AES for best interop.
+
+.. cpp:function:: std::vector<uint8_t> nist_key_wrap(const uint8_t input[], \
+                  size_t input_len, const BlockCipher& bc)
+
+   This performs KW (key wrap) mode. The input must be a multiple of 8 bytes long.
+
+.. cpp:function:: secure_vector<uint8_t> nist_key_unwrap(const uint8_t input[], \
+                  size_t input_len,  const BlockCipher& bc)
+
+   This unwraps the result of nist_key_wrap, or throw Integrity_Failure on error.
+
+.. cpp:function:: std::vector<uint8_t> nist_key_wrap_padded(const uint8_t input[], \
+                  size_t input_len, const BlockCipher& bc)
+
+   This performs KWP (key wrap with padding) mode. The input can be any length.
+
+.. cpp:function:: secure_vector<uint8_t> nist_key_unwrap_padded(const uint8_t input[], \
+                  size_t input_len, const BlockCipher& bc)
+
+   This unwraps the result of nist_key_wrap_padded, or throws Integrity_Failure
+   on error.
+
+RFC 3394 Interface
+-----------------------------
+
+This is an older interface that was first available (with slight changes) in
+1.10, and available in its current form since 2.0 release. It uses a 128-bit,
+192-bit, or 256-bit key to encrypt an input key. AES is always used. The input
+must be a multiple of 8 bytes; if not an exception is thrown.
+
+This interface is defined in ``rfc3394.h``.
+
+.. cpp:function:: secure_vector<uint8_t> rfc3394_keywrap(const secure_vector<uint8_t>& key, \
+                                                         const SymmetricKey& kek)
+
+  Wrap the input key using kek (the key encryption key), and return the result. It will
+  be 8 bytes longer than the input key.
+
+.. cpp:function:: secure_vector<uint8_t> rfc3394_keyunwrap(const secure_vector<uint8_t>& key, \
+                                                           const SymmetricKey& kek)
+
+  Unwrap a key wrapped wtih rfc3394_keywrap.
+
+
diff --git a/news.rst b/news.rst
index 945556855..5bfb02428 100644
--- a/news.rst
+++ b/news.rst
@@ -14,7 +14,7 @@ Version 2.4.0, Not Yet Released
   RSA-PSS signatures (GH #1270)
 
 * Add support for AES key wrapping with padding, as specified in RFC 5649
-  and NIST SP 800-38F
+  and NIST SP 800-38F (GH #1301)
 
 * Optimize GCM mode on systems both with and without carryless
   multiply support. This includes a new base case implementation