This package provides the RFC 3394 key wrapping (also known as aes-key-wrap).
It's written in TypeScrypt.

This package implements the aes-key-wrap (key wrapping and unwrapping), following this heise article, based on the specification by nist.

Following key/kek lengths are supported:

• 128-bit key with 128-bit kek
• 192-bit key with 192-bit kek
• 256-bit key with 256-bit kek

Mixed lengths (128-bit key with 256-bit kek, for example) are not supported, currently, but they don't make any sense either, since a chain with a weaker link does not become stronger by adding a stronger link.

With aes-key-wrap you can wrap (encrypt) a key, used to encrypt data, using a so-called kek (usally a key, derived from a password).

• Wrap a key with a KEK*, using aes-key-wrap
• Unwrap a key with a KEK*, using aes-key-wrap
• Uint8Array <=> string conversion

*KEK = Key encryption key (key, used to encrypt another key)

npm i aeskeywrap

// Replace ... with a comma-separated list of the functions, you need
import { ... } from 'aeskeywrap';

<!-- Load the file from jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/aeskeywrap@1.2.2/dist/aeskeywrap.js"></script>

<!-- or load the file from unpkg -->
<script src="https://unpkg.com/aeskeywrap@1.2.2/dist/aeskeywrap.js"></script>

<!-- or download the file and host it yourself -->
<script src="/js/aeskeywrap.js"></script>

<script>
  // Replace ... with a comma-separated list of the functions, you need
  const { ... } = aeskeywrap;
</script>

• keyWrap: wraps a key with a kek
• unwrapKey: unwraps a wrapped key with a kek
• toString: encodes an Uint8Array to a string
• fromString: decodes a string to an Uint8Array
• wrapKeyToString: wraps a key with a kek and encodes it
• unwrapKeyFromString: decodes a wrappedKey and unwraps it

// key, kek and wrappedKey are Unit8Arrays
const wrappedKey = wrapKey(key, kek);

// key, kek and wrappedKey are Unit8Arrays
const key = unwrapKey(wrappedKey, kek);

// convert Uint8Array to base64 string
const wrappedKeyBase64 = toString(wrappedKey, 'base64')

// convert Uint8Array to hex string
const wrappedKeyHex = toString(wrappedKey, 'hex')

// convert Uint8Array to base64 string
const wrappedKey = fromString(wrappedKeyBase64, 'base64')

// convert Uint8Array to hex string
const wrappedKey_ = fromString(wrappedKeyhex, 'hex')

const wrappedKey = wrapKeyToString(key, kek, 'base64');

const key = unwrapKeyFromString(wrappedKeyBase64, kek, 'base64');

You can use all encodings, available at buffer.toString() function.
Currently this includes:

• ascii
• utf8
• utf-8
• utf16le
• ucs2
• ucs-2
• base64
• base64url
• latin1
• binary
• hex

There are 3 possible errors.
Each error only contains a message, specifying the error type.

These are the 3 different messages (they are very self-explanatory):

• Unauthentic data. Wrong kek?
• Invalid data length(s). kek must be 16, 24 or 32 bytes, key must be same length.
• Invalid data length(s). kek must be 16, 24 or 32 bytes, wrappedKey must be 8 bytes longer

There are 2 different reasons for unauthentic data:

• The wrapped key has been tampered with
• The kek is wrong (e.g. due to an wrong password), which is the most common case

The message Unauthentic data. Wrong kek? will never change (design decision). Therefore, it can be reliably used to determine whether the process failed due to unauthentic data.

• crypto-js by evanvosberg,
  used for AES single block encryption and decryption

Unit Tests based on official test vectors

• for 128-bit key
• for 192-bit key
• for 256-bit key

Changelog

This project is licensed under the MIT License