Aeskeywrap NPM

aeskeywrap

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

Introduction

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

Supported key/kek lengths

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.

Use case

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).

Features

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)

Install (node.js)

npm i aeskeywrap

Import / Loading

Node.js

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

Browser

<!-- 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>

Available functions

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

Usage

Wrap key with kek

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

Unwrap key with kek

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

Conversions

Uint8Array to string

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

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

string to Uint8Array

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

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

wrap and convert to base64 string at once

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

convert from base64 string and unwrap at once

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

encodings

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

Error handling

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.