1Crypt::KeyWrap(3)     User Contributed Perl Documentation    Crypt::KeyWrap(3)
2
3
4

NAME

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

SYNOPSIS

10          # A192KW wrapping
11          use Crypt::KeyWrap qw(aes_key_wrap);
12          my $kek     = pack("H*", "5840df6e29b02af1ab493b705bf16ea1ae8338f4dcc176a8"); # key encryption key
13          my $cek     = pack("H*", "c37b7e6492584340bed12207808941155068f738"); # content encryption key
14          my $enc_cek = aes_key_wrap($kek, $pt_data); # encrypted content encryption key
15
16          # A192KW unwrapping
17          use Crypt::KeyWrap qw(aes_key_unwrap);
18          my $kek     = pack("H*", "5840df6e29b02af1ab493b705bf16ea1ae8338f4dcc176a8");
19          my $enc_cek = pack("H*", "138bdeaa9b8fa7fc61f97742e72248ee5ae6ae5360d1ae6a5f54f373fa543b6a");
20          my $cek     = aes_key_unwrap($kek, $pt_data);
21

DESCRIPTION

23       Implements key management algorithms defined in
24       <https://tools.ietf.org/html/rfc7518>
25
26       BEWARE: experimental, interface of this module might change!
27
28       Supported algorithms (all defined in RFC7518):
29
30        A128KW                 see: aes_key_wrap() + aes_key_unwrap()
31        A192KW                 see: aes_key_wrap() + aes_key_unwrap()
32        A256KW                 see: aes_key_wrap() + aes_key_unwrap()
33        A128GCMKW              see: gcm_key_wrap() + gcm_key_unwrap()
34        A192GCMKW              see: gcm_key_wrap() + gcm_key_unwrap()
35        A256GCMKW              see: gcm_key_wrap() + gcm_key_unwrap()
36        PBES2-HS256+A128KW     see: pbes2_key_wrap() + pbes2_key_unwrap()
37        PBES2-HS384+A192KW     see: pbes2_key_wrap() + pbes2_key_unwrap()
38        PBES2-HS512+A256KW     see: pbes2_key_wrap() + pbes2_key_unwrap()
39        RSA-OAEP               see: rsa_key_wrap() + rsa_key_unwrap()
40        RSA-OAEP-256           see: rsa_key_wrap() + rsa_key_unwrap()
41        RSA1_5                 see: rsa_key_wrap() + rsa_key_unwrap()
42        ECDH-ES+A128KW         see: ecdhaes_key_wrap() + ecdhaes_key_unwrap()
43        ECDH-ES+A192KW         see: ecdhaes_key_wrap() + ecdhaes_key_unwrap()
44        ECDH-ES+A256KW         see: ecdhaes_key_wrap() + ecdhaes_key_unwrap()
45        ECDH-ES                see: ecdh_key_wrap() + ecdh_key_unwrap()
46

EXPORT

48       Nothing is exported by default.
49
50       You can export selected functions:
51
52         use Crypt::KeyWrap qw(aes_key_wrap gcm_key_wrap pbes2_key_wrap);
53
54       Or all of them at once:
55
56         use Crypt::KeyWrap ':all';
57

FUNCTIONS

59   aes_key_wrap
60       AES key wrap algorithm as defined in
61       <https://tools.ietf.org/html/rfc7518#section-4.4> (implements
62       algorithms "A128KW", "A192KW", "A256KW").
63
64       Implementation follows <https://tools.ietf.org/html/rfc5649> and
65       <https://tools.ietf.org/html/rfc3394>.
66
67       The implementation is also compatible with
68       <http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf>
69       (it supports AES based KW, KWP + TDEA/DES_EDE based TKW).
70
71       AES Key Wrap algorithm.
72
73          $enc_cek = aes_key_wrap($kek, $cek);
74          # or
75          $enc_cek = aes_key_wrap($kek, $cek, $cipher, $padding, $inverse);
76
77          # params:
78          #  $kek     .. key encryption key (16bytes for AES128, 24 for AES192, 32 for AES256)
79          #  $cek     .. content encryption key
80          # optional params:
81          #  $cipher  .. 'AES' (default) or 'DES_EDE'
82          #  $padding .. 1 (default) or 0 handle $cek padding (relevant for AES only)
83          #  $inverse .. 0 (default) or 1 use cipher in inverse mode as defined by SP.800-38F
84
85       Values $enc_cek, $cek and $kek are binary octets. If you disable
86       padding you have to make sure that $cek length is multiply of 8 (for
87       AES) or multiply of 4 (for DES_EDE);
88
89   aes_key_unwrap
90       AES key unwrap algorithm as defined in
91       <https://tools.ietf.org/html/rfc7518#section-4.4> (implements
92       algorithms "A128KW", "A192KW", "A256KW").
93
94       AES Key Unwrap algorithm.
95
96          $cek = aes_key_unwrap($kek, $enc_cek);
97          # or
98          $cek = aes_key_unwrap($kek, $enc_cek, $cipher, $padding, $inverse);
99
100          # params:
101          #  $kek     .. key encryption key (16bytes for AES128, 24 for AES192, 32 for AES256)
102          #  $enc_cek .. encrypted content encryption key
103          # optional params:
104          #  $cipher  .. 'AES' (default) or 'DES_EDE'
105          #  $padding .. 1 (default) or 0 - use $cek padding (relevant for AES only)
106          #  $inverse .. 0 (default) or 1 - use cipher in inverse mode as defined by SP.800-38F
107
108       Values $enc_cek, $cek and $kek are binary octets.
109
110   gcm_key_wrap
111       AES GCM key wrap algorithm as defined in
112       <https://tools.ietf.org/html/rfc7518#section-4.7> (implements
113       algorithms "A128GCMKW", "A192GCMKW", "A256GCMKW").
114
115          ($enc_cek, $tag, $iv) = gcm_key_wrap($kek, $cek);
116          #or
117          ($enc_cek, $tag, $iv) = gcm_key_wrap($kek, $cek, $aad);
118          #or
119          ($enc_cek, $tag, $iv) = gcm_key_wrap($kek, $cek, $aad, $cipher, $iv);
120
121          # params:
122          #  $kek     .. key encryption key (16bytes for AES128, 24 for AES192, 32 for AES256)
123          #  $cek     .. content encryption key
124          # optional params:
125          #  $aad     .. additional authenticated data, DEFAULT is '' (empty string)
126          #  $cipher  .. cipher to be used by GCM, DEFAULT is 'AES'
127          #  $iv      .. initialization vector (if not defined a random IV is generated)
128
129       Values $enc_cek, $cek, $aad, $iv, $tag and $kek are binary octets.
130
131   gcm_key_unwrap
132       AES GCM key unwrap algorithm as defined in
133       <https://tools.ietf.org/html/rfc7518#section-4.7> (implements
134       algorithms "A128GCMKW", "A192GCMKW", "A256GCMKW").
135
136          $cek = gcm_key_unwrap($kek, $enc_cek, $tag, $iv);
137          # or
138          $cek = gcm_key_unwrap($kek, $enc_cek, $tag, $iv, $aad);
139          # or
140          $cek = gcm_key_unwrap($kek, $enc_cek, $tag, $iv, $aad, $cipher);
141
142          # params:
143          #  $kek     .. key encryption key (16bytes for AES128, 24 for AES192, 32 for AES256)
144          #  $enc_cek .. encrypted content encryption key
145          #  $tag     .. GCM's tag
146          #  $iv      .. initialization vector
147          # optional params:
148          #  $aad     .. additional authenticated data, DEFAULT is '' (empty string)
149          #  $cipher  .. cipher to be used by GCM, DEFAULT is 'AES'
150
151       Values $enc_cek, $cek, $aad, $iv, $tag and $kek are binary octets.
152
153   pbes2_key_wrap
154       PBES2 key wrap algorithm as defined in
155       <https://tools.ietf.org/html/rfc7518#section-4.8> (implements
156       algorithms "PBES2-HS256+A128KW", "PBES2-HS384+A192KW",
157       "PBES2-HS512+A256KW").
158
159          $enc_cek = pbes2_key_wrap($kek, $cek, $alg, $salt, $iter);
160
161          # params:
162          #  $kek     .. key encryption key (arbitrary length)
163          #  $cek     .. content encryption key
164          #  $alg     .. algorithm name e.g. 'PBES2-HS256+A128KW' (see rfc7518)
165          #  $salt    .. pbkdf2 salt
166          #  $iter    .. pbkdf2 iteration count
167
168       Values $enc_cek, $cek, $salt and $kek are binary octets.
169
170   pbes2_key_unwrap
171       PBES2 key unwrap algorithm as defined in
172       <https://tools.ietf.org/html/rfc7518#section-4.8> (implements
173       algorithms "PBES2-HS256+A128KW", "PBES2-HS384+A192KW",
174       "PBES2-HS512+A256KW").
175
176          $cek = pbes2_key_unwrap($kek, $enc_cek, $alg, $salt, $iter);
177
178          # params:
179          #  $kek     .. key encryption key (arbitrary length)
180          #  $enc_cek .. encrypted content encryption key
181          #  $alg     .. algorithm name e.g. 'PBES2-HS256+A128KW' (see rfc7518)
182          #  $salt    .. pbkdf2 salt
183          #  $iter    .. pbkdf2 iteration count
184
185       Values $enc_cek, $cek, $salt and $kek are binary octets.
186
187   rsa_key_wrap
188       PBES2 key wrap algorithm as defined in
189       <https://tools.ietf.org/html/rfc7518#section-4.2> and
190       <https://tools.ietf.org/html/rfc7518#section-4.3> (implements
191       algorithms "RSA1_5", "RSA-OAEP-256", "RSA-OAEP").
192
193          $enc_cek = rsa_key_wrap($kek, $cek, $alg);
194
195          # params:
196          #  $kek     .. RSA public key - Crypt::PK::RSA instance
197          #  $cek     .. content encryption key
198          #  $alg     .. algorithm name e.g. 'RSA-OAEP' (see rfc7518)
199
200       Values $enc_cek and $cek are binary octets.
201
202   rsa_key_unwrap
203       PBES2 key wrap algorithm as defined in
204       <https://tools.ietf.org/html/rfc7518#section-4.2> and
205       <https://tools.ietf.org/html/rfc7518#section-4.3> (implements
206       algorithms "RSA1_5", "RSA-OAEP-256", "RSA-OAEP").
207
208          $cek = rsa_key_unwrap($kek, $enc_cek, $alg);
209
210          # params:
211          #  $kek     .. RSA private key - Crypt::PK::RSA instance
212          #  $enc_cek .. encrypted content encryption key
213          #  $alg     .. algorithm name e.g. 'RSA-OAEP' (see rfc7518)
214
215       Values $enc_cek and $cek are binary octets.
216
217   ecdhaes_key_wrap
218       ECDH+AESKW key agreement/wrap algorithm as defined in
219       <https://tools.ietf.org/html/rfc7518#section-4.6> (implements
220       algorithms "ECDH-ES+A128KW", "ECDH-ES+A192KW", "ECDH-ES+A256KW").
221
222          ($enc_cek, $epk) = ecdhaes_key_wrap($kek, $cek, $alg, $apu, $apv);
223
224          # params:
225          #  $kek     .. ECC public key - Crypt::PK::ECC|X25519 instance
226          #  $cek     .. content encryption key
227          #  $alg     .. algorithm name e.g. 'ECDH-ES+A256KW' (see rfc7518)
228          # optional params:
229          #  $apu     .. Agreement PartyUInfo Header Parameter
230          #  $apv     .. Agreement PartyVInfo Header Parameter
231
232       Values $enc_cek and $cek are binary octets.
233
234   ecdhaes_key_unwrap
235       ECDH+AESKW key agreement/unwrap algorithm as defined in
236       <https://tools.ietf.org/html/rfc7518#section-4.6> (implements
237       algorithms "ECDH-ES+A128KW", "ECDH-ES+A192KW", "ECDH-ES+A256KW").
238
239          $cek = ecdhaes_key_unwrap($kek, $enc_cek, $alg, $epk, $apu, $apv);
240
241          # params:
242          #  $kek     .. ECC private key - Crypt::PK::ECC|X25519 instance
243          #  $enc_cek .. encrypted content encryption key
244          #  $alg     .. algorithm name e.g. 'ECDH-ES+A256KW' (see rfc7518)
245          #  $epk     .. ephemeral ECC public key (JWK/JSON or Crypt::PK::ECC|X25519)
246          # optional params:
247          #  $apu     .. Agreement PartyUInfo Header Parameter
248          #  $apv     .. Agreement PartyVInfo Header Parameter
249
250       Values $enc_cek and $cek are binary octets.
251
252   ecdh_key_wrap
253       ECDH (Ephememeral Static) key agreement/wrap algorithm as defined in
254       <https://tools.ietf.org/html/rfc7518#section-4.6> (implements algorithm
255       "ECDH-ES").
256
257          ($cek, $epk) = ecdh_key_wrap($kek, $enc, $apu, $apv);
258
259          # params:
260          #  $kek     .. ECC public key - Crypt::PK::ECC|X25519 instance
261          #  $enc     .. encryption algorithm name e.g. 'A256GCM' (see rfc7518)
262          # optional params:
263          #  $apu     .. Agreement PartyUInfo Header Parameter
264          #  $apv     .. Agreement PartyVInfo Header Parameter
265
266       Value $cek - binary octets, $epk JWK/JSON string with ephemeral ECC
267       public key.
268
269   ecdh_key_unwrap
270       ECDH (Ephememeral Static) key agreement/unwrap algorithm as defined in
271       <https://tools.ietf.org/html/rfc7518#section-4.6> (implements algorithm
272       "ECDH-ES").
273
274          $cek = ecdh_key_unwrap($kek, $enc, $epk, $apu, $apv);
275
276          # params:
277          #  $kek     .. ECC private key - Crypt::PK::ECC|X25519 instance
278          #  $enc     .. encryption algorithm name e.g. 'A256GCM' (see rfc7518)
279          #  $epk     .. ephemeral ECC public key (JWK/JSON or Crypt::PK::ECC|X25519)
280          # optional params:
281          #  $apu     .. Agreement PartyUInfo Header Parameter
282          #  $apv     .. Agreement PartyVInfo Header Parameter
283
284       Value $cek - binary octets.
285

SEE ALSO

287       Crypt::Cipher::AES, Crypt::AuthEnc::GCM, Crypt::PK::RSA,
288       Crypt::KeyDerivation
289

LICENSE

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

COPYRIGHT

295       Copyright (c) 2015-2023 DCIT, a.s. <https://www.dcit.cz> / Karel Miko
296
297
298
299perl v5.38.0                      2023-11-21                 Crypt::KeyWrap(3)