From abc85f2515b2fc2b847c4d6e9c2c3717f2391d3a Mon Sep 17 00:00:00 2001 From: Jack Lloyd Date: Sun, 19 Nov 2017 21:57:41 -0500 Subject: Add keywrap documentation --- doc/manual/keywrap.rst | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 doc/manual/keywrap.rst (limited to 'doc/manual/keywrap.rst') 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 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 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 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 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 rfc3394_keywrap(const secure_vector& 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 rfc3394_keyunwrap(const secure_vector& key, \ + const SymmetricKey& kek) + + Unwrap a key wrapped wtih rfc3394_keywrap. + + -- cgit v1.2.3