.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Crypt::KeyWrap 3pm" .TH Crypt::KeyWrap 3pm "2021-03-20" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Crypt::KeyWrap \- Key management/wrapping algorithms defined in RFC7518 (JWA) .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 5 \& # 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); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Implements key management algorithms defined in .PP \&\s-1BEWARE:\s0 experimental, interface of this module might change! .PP Supported algorithms (all defined in \s-1RFC7518\s0): .PP .Vb 10 \& 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() .Ve .SH "EXPORT" .IX Header "EXPORT" Nothing is exported by default. .PP You can export selected functions: .PP .Vb 1 \& use Crypt::KeyWrap qw(aes_key_wrap gcm_key_wrap pbes2_key_wrap); .Ve .PP Or all of them at once: .PP .Vb 1 \& use Crypt::KeyWrap \*(Aq:all\*(Aq; .Ve .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "aes_key_wrap" .IX Subsection "aes_key_wrap" \&\s-1AES\s0 key wrap algorithm as defined in (implements algorithms \f(CW\*(C`A128KW\*(C'\fR, \f(CW\*(C`A192KW\*(C'\fR, \f(CW\*(C`A256KW\*(C'\fR). .PP Implementation follows and . .PP The implementation is also compatible with (it supports \s-1AES\s0 based \s-1KW, KWP + TDEA/DES_EDE\s0 based \s-1TKW\s0). .PP \&\s-1AES\s0 Key Wrap algorithm. .PP .Vb 3 \& $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 .. \*(AqAES\*(Aq (default) or \*(AqDES_EDE\*(Aq \& # $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 .Ve .PP Values \f(CW$enc_cek\fR, \f(CW$cek\fR and \f(CW$kek\fR are binary octets. If you disable padding you have to make sure that \&\f(CW$cek\fR length is multiply of 8 (for \s-1AES\s0) or multiply of 4 (for \s-1DES_EDE\s0); .SS "aes_key_unwrap" .IX Subsection "aes_key_unwrap" \&\s-1AES\s0 key unwrap algorithm as defined in (implements algorithms \f(CW\*(C`A128KW\*(C'\fR, \f(CW\*(C`A192KW\*(C'\fR, \f(CW\*(C`A256KW\*(C'\fR). .PP \&\s-1AES\s0 Key Unwrap algorithm. .PP .Vb 3 \& $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 .. \*(AqAES\*(Aq (default) or \*(AqDES_EDE\*(Aq \& # $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 .Ve .PP Values \f(CW$enc_cek\fR, \f(CW$cek\fR and \f(CW$kek\fR are binary octets. .SS "gcm_key_wrap" .IX Subsection "gcm_key_wrap" \&\s-1AES GCM\s0 key wrap algorithm as defined in (implements algorithms \f(CW\*(C`A128GCMKW\*(C'\fR, \f(CW\*(C`A192GCMKW\*(C'\fR, \f(CW\*(C`A256GCMKW\*(C'\fR). .PP .Vb 5 \& ($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 \*(Aq\*(Aq (empty string) \& # $cipher .. cipher to be used by GCM, DEFAULT is \*(AqAES\*(Aq \& # $iv .. initialization vector (if not defined a random IV is generated) .Ve .PP Values \f(CW$enc_cek\fR, \f(CW$cek\fR, \f(CW$aad\fR, \f(CW$iv\fR, \f(CW$tag\fR and \f(CW$kek\fR are binary octets. .SS "gcm_key_unwrap" .IX Subsection "gcm_key_unwrap" \&\s-1AES GCM\s0 key unwrap algorithm as defined in (implements algorithms \f(CW\*(C`A128GCMKW\*(C'\fR, \f(CW\*(C`A192GCMKW\*(C'\fR, \f(CW\*(C`A256GCMKW\*(C'\fR). .PP .Vb 5 \& $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\*(Aqs tag \& # $iv .. initialization vector \& # optional params: \& # $aad .. additional authenticated data, DEFAULT is \*(Aq\*(Aq (empty string) \& # $cipher .. cipher to be used by GCM, DEFAULT is \*(AqAES\*(Aq .Ve .PP Values \f(CW$enc_cek\fR, \f(CW$cek\fR, \f(CW$aad\fR, \f(CW$iv\fR, \f(CW$tag\fR and \f(CW$kek\fR are binary octets. .SS "pbes2_key_wrap" .IX Subsection "pbes2_key_wrap" \&\s-1PBES2\s0 key wrap algorithm as defined in (implements algorithms \f(CW\*(C`PBES2\-HS256+A128KW\*(C'\fR, \f(CW\*(C`PBES2\-HS384+A192KW\*(C'\fR, \f(CW\*(C`PBES2\-HS512+A256KW\*(C'\fR). .PP .Vb 1 \& $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. \*(AqPBES2\-HS256+A128KW\*(Aq (see rfc7518) \& # $salt .. pbkdf2 salt \& # $iter .. pbkdf2 iteration count .Ve .PP Values \f(CW$enc_cek\fR, \f(CW$cek\fR, \f(CW$salt\fR and \f(CW$kek\fR are binary octets. .SS "pbes2_key_unwrap" .IX Subsection "pbes2_key_unwrap" \&\s-1PBES2\s0 key unwrap algorithm as defined in (implements algorithms \f(CW\*(C`PBES2\-HS256+A128KW\*(C'\fR, \f(CW\*(C`PBES2\-HS384+A192KW\*(C'\fR, \f(CW\*(C`PBES2\-HS512+A256KW\*(C'\fR). .PP .Vb 1 \& $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. \*(AqPBES2\-HS256+A128KW\*(Aq (see rfc7518) \& # $salt .. pbkdf2 salt \& # $iter .. pbkdf2 iteration count .Ve .PP Values \f(CW$enc_cek\fR, \f(CW$cek\fR, \f(CW$salt\fR and \f(CW$kek\fR are binary octets. .SS "rsa_key_wrap" .IX Subsection "rsa_key_wrap" \&\s-1PBES2\s0 key wrap algorithm as defined in and (implements algorithms \f(CW\*(C`RSA1_5\*(C'\fR, \f(CW\*(C`RSA\-OAEP\-256\*(C'\fR, \f(CW\*(C`RSA\-OAEP\*(C'\fR). .PP .Vb 1 \& $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. \*(AqRSA\-OAEP\*(Aq (see rfc7518) .Ve .PP Values \f(CW$enc_cek\fR and \f(CW$cek\fR are binary octets. .SS "rsa_key_unwrap" .IX Subsection "rsa_key_unwrap" \&\s-1PBES2\s0 key wrap algorithm as defined in and (implements algorithms \f(CW\*(C`RSA1_5\*(C'\fR, \f(CW\*(C`RSA\-OAEP\-256\*(C'\fR, \f(CW\*(C`RSA\-OAEP\*(C'\fR). .PP .Vb 1 \& $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. \*(AqRSA\-OAEP\*(Aq (see rfc7518) .Ve .PP Values \f(CW$enc_cek\fR and \f(CW$cek\fR are binary octets. .SS "ecdhaes_key_wrap" .IX Subsection "ecdhaes_key_wrap" \&\s-1ECDH+AESKW\s0 key agreement/wrap algorithm as defined in (implements algorithms \f(CW\*(C`ECDH\-ES+A128KW\*(C'\fR, \f(CW\*(C`ECDH\-ES+A192KW\*(C'\fR, \f(CW\*(C`ECDH\-ES+A256KW\*(C'\fR). .PP .Vb 1 \& ($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. \*(AqECDH\-ES+A256KW\*(Aq (see rfc7518) \& # optional params: \& # $apu .. Agreement PartyUInfo Header Parameter \& # $apv .. Agreement PartyVInfo Header Parameter .Ve .PP Values \f(CW$enc_cek\fR and \f(CW$cek\fR are binary octets. .SS "ecdhaes_key_unwrap" .IX Subsection "ecdhaes_key_unwrap" \&\s-1ECDH+AESKW\s0 key agreement/unwrap algorithm as defined in (implements algorithms \f(CW\*(C`ECDH\-ES+A128KW\*(C'\fR, \f(CW\*(C`ECDH\-ES+A192KW\*(C'\fR, \f(CW\*(C`ECDH\-ES+A256KW\*(C'\fR). .PP .Vb 1 \& $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. \*(AqECDH\-ES+A256KW\*(Aq (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 .Ve .PP Values \f(CW$enc_cek\fR and \f(CW$cek\fR are binary octets. .SS "ecdh_key_wrap" .IX Subsection "ecdh_key_wrap" \&\s-1ECDH\s0 (Ephememeral Static) key agreement/wrap algorithm as defined in (implements algorithm \f(CW\*(C`ECDH\-ES\*(C'\fR). .PP .Vb 1 \& ($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. \*(AqA256GCM\*(Aq (see rfc7518) \& # optional params: \& # $apu .. Agreement PartyUInfo Header Parameter \& # $apv .. Agreement PartyVInfo Header Parameter .Ve .PP Value \f(CW$cek\fR \- binary octets, \f(CW$epk\fR \s-1JWK/JSON\s0 string with ephemeral \s-1ECC\s0 public key. .SS "ecdh_key_unwrap" .IX Subsection "ecdh_key_unwrap" \&\s-1ECDH\s0 (Ephememeral Static) key agreement/unwrap algorithm as defined in (implements algorithm \f(CW\*(C`ECDH\-ES\*(C'\fR). .PP .Vb 1 \& $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. \*(AqA256GCM\*(Aq (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 .Ve .PP Value \f(CW$cek\fR \- binary octets. .SH "SEE ALSO" .IX Header "SEE ALSO" Crypt::Cipher::AES, Crypt::AuthEnc::GCM, Crypt::PK::RSA, Crypt::KeyDerivation .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2015\-2021 \s-1DCIT,\s0 a.s. / Karel Miko