NAME

Crypt::KeyWrap - AES key wrap / unwrap functions

SYNOPSIS

# wrapping
use Crypt::KeyWrap qw(aes_key_wrap);
my $kek     = pack("H*", "5840df6e29b02af1ab493b705bf16ea1ae8338f4dcc176a8"); # shared secret, keep private
my $pt_data = pack("H*", "c37b7e6492584340bed12207808941155068f738");
my $ct_data = aes_key_wrap($kek, $pt_data);

# unwrapping
use Crypt::KeyWrap qw(aes_key_unwrap);
my $kek     = pack("H*", "5840df6e29b02af1ab493b705bf16ea1ae8338f4dcc176a8"); # shared secret, keep private
my $ct_data = pack("H*", "138bdeaa9b8fa7fc61f97742e72248ee5ae6ae5360d1ae6a5f54f373fa543b6a");
my $pt_data = aes_key_unwrap($kek, $pt_data);

DESCRIPTION

Implements key management algorithms defined in https://tools.ietf.org/html/rfc7518

BEWARE: experimental, interface of this module might change!

Currently supported algorithms:

A128KW
A192KW
A256KW
A128GCMKW
A192GCMKW
A256GCMKW
PBES2-HS256+A128KW
PBES2-HS384+A192KW
PBES2-HS512+A256KW
RSA-OAEP
RSA-OAEP-256
RSA1_5

Not supported yet:

ECDH-ES+A128KW
ECDH-ES+A192KW
ECDH-ES+A256KW
ECDH-ES

FUNCTIONS

aes_key_wrap

AES key wrap algorithm as defined in https://tools.ietf.org/html/rfc7518#section-4.4 (implements algorithms A128KW, A192KW, A256KW).

Implementation follows https://tools.ietf.org/html/rfc5649 and https://tools.ietf.org/html/rfc3394.

The implementation is also compatible with http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf (it supports AES based KW, KWP + TDEA/DES_EDE based TKW).

AES Key Wrap algorithm.

$ct_data = aes_key_wrap($kek, $pt_data);
# or
$ct_data = aes_key_wrap($kek, $pt_data, $cipher, $padding, $inverse);

# params:
#  $kek     .. key encryption key (16bytes for AES128, 24 for AES192, 32 for AES256)
#  $pt_data .. plaintext data
# optional params:
#  $cipher  .. 'AES' (default) or 'DES_EDE'
#  $padding .. 1 (default) or 0 handle $pt_data padding (relevant for AES only)
#  $inverse .. 0 (default) or 1 use cipher in inverse mode as defined by SP.800-38F

Values $ct_data, $pt_data and $kek are binary octets. If you disable padding you have to make sure that $pt_data length is multiply of 8 (for AES) or multiply of 4 (for DES_EDE);

aes_key_unwrap

AES key unwrap algorithm as defined in https://tools.ietf.org/html/rfc7518#section-4.4 (implements algorithms A128KW, A192KW, A256KW).

AES Key Unwrap algorithm.

$pt_data = aes_key_unwrap($kek, $ct_data);
# or
$pt_data = aes_key_unwrap($kek, $ct_data, $cipher, $padding, $inverse);

# params:
#  $kek     .. key encryption key (16bytes for AES128, 24 for AES192, 32 for AES256)
#  $ct_data .. ciphertext data
# optional params:
#  $cipher  .. 'AES' (default) or 'DES_EDE'
#  $padding .. 1 (default) or 0 - use $pt_data padding (relevant for AES only)
#  $inverse .. 0 (default) or 1 - use cipher in inverse mode as defined by SP.800-38F

Values $ct_data, $pt_data and $kek are binary octets.

gcm_key_wrap

AES GCM key wrap algorithm as defined in https://tools.ietf.org/html/rfc7518#section-4.7 (implements algorithms A128GCMKW, A192GCMKW, A256GCMKW).

($ct_data, $tag, $iv) = gcm_key_wrap($kek, $pt_data);
#or
($ct_data, $tag, $iv) = gcm_key_wrap($kek, $pt_data, $aad);
#or
($ct_data, $tag, $iv) = gcm_key_wrap($kek, $pt_data, $aad, $cipher, $iv);

# params:
#  $kek     .. key encryption key (16bytes for AES128, 24 for AES192, 32 for AES256)
#  $pt_data .. plaintext data
# optional params:
#  $aad     .. additional authenticated data, DEFAULT is '' (empty string)
#  $cipher  .. cipher to be used by GCM, DEFAULT is 'AES'
#  $iv      .. initialization vector (if not defined a random IV is generated)

Values $ct_data, $pt_data, $aad, $iv, $tag and $kek are binary octets.

gcm_key_unwrap

AES GCM key unwrap algorithm as defined in https://tools.ietf.org/html/rfc7518#section-4.7 (implements algorithms A128GCMKW, A192GCMKW, A256GCMKW).

$pt_data = gcm_key_unwrap($kek, $ct_data, $tag, $iv);
# or
$pt_data = gcm_key_unwrap($kek, $ct_data, $tag, $iv, $aad);
# or
$pt_data = gcm_key_unwrap($kek, $ct_data, $tag, $iv, $aad, $cipher);

# params:
#  $kek     .. key encryption key (16bytes for AES128, 24 for AES192, 32 for AES256)
#  $ct_data .. ciphertext data
#  $tag     .. GCM's tag
#  $iv      .. initialization vector
# optional params:
#  $aad     .. additional authenticated data, DEFAULT is '' (empty string)
#  $cipher  .. cipher to be used by GCM, DEFAULT is 'AES'

Values $ct_data, $pt_data, $aad, $iv, $tag and $kek are binary octets.

pbes2_key_wrap

PBES2 key wrap algorithm as defined in https://tools.ietf.org/html/rfc7518#section-4.8 (implements algorithms PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW).

$ct_data = pbes2_key_wrap($kek, $pt_data, $alg, $salt, $iter) = @_;

# params:
#  $kek     .. key encryption key (arbitrary length)
#  $pt_data .. plaintext data
#  $alg     .. algorithm name e.g. 'PBES2-HS256+A128KW' (see rfc7518)
#  $salt    .. pbkdf2 salt
#  $iter    .. pbkdf2 iteration count

Values $ct_data, $pt_data, $salt and $kek are binary octets.

pbes2_key_unwrap

PBES2 key unwrap algorithm as defined in https://tools.ietf.org/html/rfc7518#section-4.8 (implements algorithms PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW).

$pt_data = pbes2_key_unwrap($kek, $ct_data, $alg, $salt, $iter) = @_;

# params:
#  $kek     .. key encryption key (arbitrary length)
#  $ct_data .. ciphertext data
#  $alg     .. algorithm name e.g. 'PBES2-HS256+A128KW' (see rfc7518)
#  $salt    .. pbkdf2 salt
#  $iter    .. pbkdf2 iteration count

Values $ct_data, $pt_data, $salt and $kek are binary octets.

rsa_key_wrap

PBES2 key wrap algorithm as defined in https://tools.ietf.org/html/rfc7518#section-4.2 and https://tools.ietf.org/html/rfc7518#section-4.3 (implements algorithms RSA1_5, RSA-OAEP-256, RSA-OAEP).

$ct_data = rsa_key_wrap($kek, $pt_data, $alg) = @_;

# params:
#  $kek     .. RSA public key
#  $pt_data .. plaintext data
#  $alg     .. algorithm name e.g. 'RSA-OAEP' (see rfc7518)

Values $ct_data and $pt_data are binary octets.

Parameter $kek can be Crypt::PK::RSA or Crypt::OpenSSL::RSA instance, reference to JWK/JSON string or JWK perl hash, reference to a string with PEM or DER encoded key.

rsa_key_unwrap

$pt_data = rsa_key_unwrap($kek, $ct_data, $alg) = @_;

# params:
#  $kek     .. RSA private key
#  $ct_data .. ciphertext data
#  $alg     .. algorithm name e.g. 'RSA-OAEP' (see rfc7518)