diff options
| -rw-r--r-- | doc/manual/contents.rst | 1 | ||||
| -rw-r--r-- | doc/manual/keywrap.rst | 60 | ||||
| -rw-r--r-- | news.rst | 2 |
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. + + @@ -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 |