--- name: "Crypt::KeyWrap" section: "3pm" platform: "linux" package: "libcrypt-jwt-perl" version: "0.037-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Crypt::KeyWrap" --- # Crypt::KeyWrap(3pm) Key management/wrapping algorithms defined in RFC7518 (JWA) ## 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 \ 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 \ (implements algorithms `"A128KW"`, `"A192KW"`, `"A256KW"`). Implementation follows \ and \. The implementation is also compatible with \ (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 \ (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 \ (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 \ (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 \ (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 \ (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 \ and \ (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 PBES2 key wrap algorithm as defined in \ and \ (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. ### ecdhaes\_key\_wrap ECDH+AESKW key agreement/wrap algorithm as defined in \ (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. ### ecdhaes\_key\_unwrap ECDH+AESKW key agreement/unwrap algorithm as defined in \ (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\_key\_wrap ECDH (Ephememeral Static) key agreement/wrap algorithm as defined in \ (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\_key\_unwrap ECDH (Ephememeral Static) key agreement/unwrap algorithm as defined in \ (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. ## SEE ALSO Crypt::Cipher::AES, Crypt::AuthEnc::GCM, Crypt::PK::RSA, Crypt::KeyDerivation ## LICENSE This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ## COPYRIGHT Copyright (c) 2015-2025 DCIT, a.s. \ / Karel Miko