Crypt::KeyWrap − Key management/wrapping algorithms defined in RFC7518 (JWA)
# A192KW
wrapping
use Crypt::KeyWrap qw(aes_key_wrap);
my $kek = pack("H*",
"5840df6e29b02af1ab493b705bf16ea1ae8338f4dcc176a8");
# key encryption key
my $cek = pack("H*",
"c37b7e6492584340bed12207808941155068f738"); #
content encryption key
my $enc_cek = aes_key_wrap($kek, $pt_data); # encrypted
content encryption key
# A192KW unwrapping
use Crypt::KeyWrap qw(aes_key_unwrap);
my $kek = pack("H*",
"5840df6e29b02af1ab493b705bf16ea1ae8338f4dcc176a8");
my $enc_cek = pack("H*",
"138bdeaa9b8fa7fc61f97742e72248ee5ae6ae5360d1ae6a5f54f373fa543b6a");
my $cek = aes_key_unwrap($kek, $pt_data);
Implements key management algorithms defined in <https://tools.ietf.org/html/rfc7518>
BEWARE: experimental, interface of this module might change!
Supported algorithms (all defined in RFC7518):
A128KW see:
aes_key_wrap() + aes_key_unwrap()
A192KW see: aes_key_wrap() + aes_key_unwrap()
A256KW see: aes_key_wrap() + aes_key_unwrap()
A128GCMKW see: gcm_key_wrap() + gcm_key_unwrap()
A192GCMKW see: gcm_key_wrap() + gcm_key_unwrap()
A256GCMKW see: gcm_key_wrap() + gcm_key_unwrap()
PBES2−HS256+A128KW see: pbes2_key_wrap() +
pbes2_key_unwrap()
PBES2−HS384+A192KW see: pbes2_key_wrap() +
pbes2_key_unwrap()
PBES2−HS512+A256KW see: pbes2_key_wrap() +
pbes2_key_unwrap()
RSA−OAEP see: rsa_key_wrap() + rsa_key_unwrap()
RSA−OAEP−256 see: rsa_key_wrap() +
rsa_key_unwrap()
RSA1_5 see: rsa_key_wrap() + rsa_key_unwrap()
ECDH−ES+A128KW see: ecdhaes_key_wrap() +
ecdhaes_key_unwrap()
ECDH−ES+A192KW see: ecdhaes_key_wrap() +
ecdhaes_key_unwrap()
ECDH−ES+A256KW see: ecdhaes_key_wrap() +
ecdhaes_key_unwrap()
ECDH−ES see: ecdh_key_wrap() + ecdh_key_unwrap()
Nothing is exported by default.
You can export selected functions:
use Crypt::KeyWrap qw(aes_key_wrap gcm_key_wrap pbes2_key_wrap);
Or all of them at once:
use Crypt::KeyWrap ':all';
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.
$enc_cek =
aes_key_wrap($kek, $cek);
# or
$enc_cek = aes_key_wrap($kek, $cek, $cipher, $padding,
$inverse);
# params:
# $kek .. key encryption key (16bytes for AES128, 24 for
AES192, 32 for AES256)
# $cek .. content encryption key
# optional params:
# $cipher .. 'AES' (default) or 'DES_EDE'
# $padding .. 1 (default) or 0 handle $cek padding (relevant
for AES only)
# $inverse .. 0 (default) or 1 use cipher in inverse mode as
defined by SP.800−38F
Values $enc_cek, $cek and $kek are binary octets. If you disable padding you have to make sure that $cek length is multiply of 8 (for AES) or multiply of 4 (for DES_EDE);
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.
$cek =
aes_key_unwrap($kek, $enc_cek);
# or
$cek = aes_key_unwrap($kek, $enc_cek, $cipher, $padding,
$inverse);
# params:
# $kek .. key encryption key (16bytes for AES128, 24 for
AES192, 32 for AES256)
# $enc_cek .. encrypted content encryption key
# optional params:
# $cipher .. 'AES' (default) or 'DES_EDE'
# $padding .. 1 (default) or 0 − use $cek padding
(relevant for AES only)
# $inverse .. 0 (default) or 1 − use cipher in inverse
mode as defined by SP.800−38F
Values $enc_cek, $cek and $kek are binary octets.
AES GCM key wrap algorithm as defined in <https://tools.ietf.org/html/rfc7518#section−4.7> (implements algorithms "A128GCMKW", "A192GCMKW", "A256GCMKW").
($enc_cek, $tag,
$iv) = gcm_key_wrap($kek, $cek);
#or
($enc_cek, $tag, $iv) = gcm_key_wrap($kek, $cek, $aad);
#or
($enc_cek, $tag, $iv) = gcm_key_wrap($kek, $cek, $aad,
$cipher, $iv);
# params:
# $kek .. key encryption key (16bytes for AES128, 24 for
AES192, 32 for AES256)
# $cek .. content encryption key
# 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 $enc_cek, $cek, $aad, $iv, $tag and $kek are binary octets.
AES GCM key unwrap algorithm as defined in <https://tools.ietf.org/html/rfc7518#section−4.7> (implements algorithms "A128GCMKW", "A192GCMKW", "A256GCMKW").
$cek =
gcm_key_unwrap($kek, $enc_cek, $tag, $iv);
# or
$cek = gcm_key_unwrap($kek, $enc_cek, $tag, $iv, $aad);
# or
$cek = gcm_key_unwrap($kek, $enc_cek, $tag, $iv, $aad,
$cipher);
# params:
# $kek .. key encryption key (16bytes for AES128, 24 for
AES192, 32 for AES256)
# $enc_cek .. encrypted content encryption key
# $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 $enc_cek, $cek, $aad, $iv, $tag and $kek are binary octets.
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").
$enc_cek =
pbes2_key_wrap($kek, $cek, $alg, $salt, $iter);
# params:
# $kek .. key encryption key (arbitrary length)
# $cek .. content encryption key
# $alg .. algorithm name e.g. 'PBES2−HS256+A128KW'
(see rfc7518)
# $salt .. pbkdf2 salt
# $iter .. pbkdf2 iteration count
Values $enc_cek, $cek, $salt and $kek are binary octets.
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").
$cek =
pbes2_key_unwrap($kek, $enc_cek, $alg, $salt, $iter);
# params:
# $kek .. key encryption key (arbitrary length)
# $enc_cek .. encrypted content encryption key
# $alg .. algorithm name e.g. 'PBES2−HS256+A128KW'
(see rfc7518)
# $salt .. pbkdf2 salt
# $iter .. pbkdf2 iteration count
Values $enc_cek, $cek, $salt and $kek are binary octets.
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").
$enc_cek =
rsa_key_wrap($kek, $cek, $alg);
# params:
# $kek .. RSA public key − Crypt::PK::RSA instance
# $cek .. content encryption key
# $alg .. algorithm name e.g. 'RSA−OAEP' (see
rfc7518)
Values $enc_cek and $cek are binary octets.
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").
$cek =
rsa_key_unwrap($kek, $enc_cek, $alg);
# params:
# $kek .. RSA private key − Crypt::PK::RSA instance
# $enc_cek .. encrypted content encryption key
# $alg .. algorithm name e.g. 'RSA−OAEP' (see
rfc7518)
Values $enc_cek and $cek are binary octets.
ECDH+AESKW key agreement/wrap algorithm as defined in <https://tools.ietf.org/html/rfc7518#section−4.6> (implements algorithms "ECDH−ES+A128KW", "ECDH−ES+A192KW", "ECDH−ES+A256KW").
($enc_cek, $epk)
= ecdhaes_key_wrap($kek, $cek, $alg, $apu, $apv);
# params:
# $kek .. ECC public key − Crypt::PK::ECC|X25519
instance
# $cek .. content encryption key
# $alg .. algorithm name e.g. 'ECDH−ES+A256KW' (see
rfc7518)
# optional params:
# $apu .. Agreement PartyUInfo Header Parameter
# $apv .. Agreement PartyVInfo Header Parameter
Values $enc_cek and $cek are binary octets.
ECDH+AESKW key agreement/unwrap algorithm as defined in <https://tools.ietf.org/html/rfc7518#section−4.6> (implements algorithms "ECDH−ES+A128KW", "ECDH−ES+A192KW", "ECDH−ES+A256KW").
$cek =
ecdhaes_key_unwrap($kek, $enc_cek, $alg, $epk, $apu, $apv);
# params:
# $kek .. ECC private key − Crypt::PK::ECC|X25519
instance
# $enc_cek .. encrypted content encryption key
# $alg .. algorithm name e.g. 'ECDH−ES+A256KW' (see
rfc7518)
# $epk .. ephemeral ECC public key (JWK/JSON or
Crypt::PK::ECC|X25519)
# optional params:
# $apu .. Agreement PartyUInfo Header Parameter
# $apv .. Agreement PartyVInfo Header Parameter
Values $enc_cek and $cek are binary octets.
ECDH (Ephememeral Static) key agreement/wrap algorithm as defined in <https://tools.ietf.org/html/rfc7518#section−4.6> (implements algorithm "ECDH−ES").
($cek, $epk) =
ecdh_key_wrap($kek, $enc, $apu, $apv);
# params:
# $kek .. ECC public key − Crypt::PK::ECC|X25519
instance
# $enc .. encryption algorithm name e.g. 'A256GCM' (see
rfc7518)
# optional params:
# $apu .. Agreement PartyUInfo Header Parameter
# $apv .. Agreement PartyVInfo Header Parameter
Value $cek − binary octets, $epk JWK/JSON string with ephemeral ECC public key.
ECDH (Ephememeral Static) key agreement/unwrap algorithm as defined in <https://tools.ietf.org/html/rfc7518#section−4.6> (implements algorithm "ECDH−ES").
$cek =
ecdh_key_unwrap($kek, $enc, $epk, $apu, $apv);
# params:
# $kek .. ECC private key − Crypt::PK::ECC|X25519
instance
# $enc .. encryption algorithm name e.g. 'A256GCM' (see
rfc7518)
# $epk .. ephemeral ECC public key (JWK/JSON or
Crypt::PK::ECC|X25519)
# optional params:
# $apu .. Agreement PartyUInfo Header Parameter
# $apv .. Agreement PartyVInfo Header Parameter
Value $cek − binary octets.
Crypt::Cipher::AES, Crypt::AuthEnc::GCM, Crypt::PK::RSA, Crypt::KeyDerivation
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Copyright (c) 2015−2023 DCIT, a.s. <https://www.dcit.cz> / Karel Miko