Crypt::KeyWrap(3pm)

User Contributed Perl Documentation

Crypt::KeyWrap(3pm)

NAME¶

Crypt::KeyWrap - Key management/wrapping algorithms defined in RFC7518 (JWA)

SYNOPSIS¶

   # 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);

DESCRIPTION¶

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

EXPORT¶

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';

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.

   $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¶

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.

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

   ($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.

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

   $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¶

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¶

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.

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

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

rsa_key_unwrap¶

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

ecdhaes_key_wrap¶

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

ecdhaes_key_unwrap¶

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 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)
   # optional params:
   #  $apu     .. Agreement PartyUInfo Header Parameter
   #  $apv     .. Agreement PartyVInfo Header Parameter

Values $enc_cek and $cek are binary octets.

ecdh_key_wrap¶

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 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_key_unwrap¶

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 instance
   #  $enc     .. encryption algorithm name e.g. 'A256GCM' (see rfc7518)
   #  $epk     .. ephemeral ECC public key (JWK/JSON or Crypt::PK::ECC)
   # optional params:
   #  $apu     .. Agreement PartyUInfo Header Parameter
   #  $apv     .. Agreement PartyVInfo Header Parameter

Value $cek - binary octets.

LICENSE¶

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

COPYRIGHT¶

2018-09-12

perl v5.26.2

Source file:	Crypt::KeyWrap.3pm.en.gz (from libcrypt-jwt-perl 0.023-1)
Source last updated:	2018-09-12T07:46:22Z
Converted to HTML:	2021-03-20T09:13:26Z

NAME¶

SYNOPSIS¶

DESCRIPTION¶

EXPORT¶

FUNCTIONS¶

aes_key_wrap¶

aes_key_unwrap¶

gcm_key_wrap¶

gcm_key_unwrap¶

pbes2_key_wrap¶

pbes2_key_unwrap¶

rsa_key_wrap¶

rsa_key_unwrap¶

ecdhaes_key_wrap¶

ecdhaes_key_unwrap¶

ecdh_key_wrap¶

ecdh_key_unwrap¶

SEE ALSO¶

LICENSE¶

COPYRIGHT¶