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

NAME

6       Crypt::PK::X25519 - Asymmetric cryptography based on X25519
7

SYNOPSIS

9        use Crypt::PK::X25519;
10
11        #Shared secret
12        my $priv = Crypt::PK::X25519->new('Alice_priv_x25519.der');
13        my $pub = Crypt::PK::X25519->new('Bob_pub_x25519.der');
14        my $shared_secret = $priv->shared_secret($pub);
15
16        #Load key
17        my $pk = Crypt::PK::X25519->new;
18        my $pk_hex = "EA7806F721A8570512C8F6EFB4E8D620C49A529E4DF5EAA77DEC646FB1E87E41";
19        $pk->import_key_raw(pack("H*", $pk_hex), "public");
20        my $sk = Crypt::PK::X25519->new;
21        my $sk_hex = "002F93D10BA5728D8DD8E9527721DABA3261C0BB1BEFDE7B4BBDAC631D454651";
22        $sk->import_key_raw(pack("H*", $sk_hex), "private");
23
24        #Key generation
25        my $pk = Crypt::PK::X25519->new->generate_key;
26        my $private_der = $pk->export_key_der('private');
27        my $public_der  = $pk->export_key_der('public');
28        my $private_pem = $pk->export_key_pem('private');
29        my $public_pem  = $pk->export_key_pem('public');
30        my $private_raw = $pk->export_key_raw('private');
31        my $public_raw  = $pk->export_key_raw('public');
32        my $private_jwk = $pk->export_key_jwk('private');
33        my $public_jwk  = $pk->export_key_jwk('public');
34

DESCRIPTION

36       Since: CryptX-0.067
37

METHODS

39   new
40        my $pk = Crypt::PK::X25519->new();
41        #or
42        my $pk = Crypt::PK::X25519->new($priv_or_pub_key_filename);
43        #or
44        my $pk = Crypt::PK::X25519->new(\$buffer_containing_priv_or_pub_key);
45
46       Support for password protected PEM keys
47
48        my $pk = Crypt::PK::X25519->new($priv_pem_key_filename, $password);
49        #or
50        my $pk = Crypt::PK::X25519->new(\$buffer_containing_priv_pem_key, $password);
51
52   generate_key
53       Uses Yarrow-based cryptographically strong random number generator
54       seeded with random data taken from "/dev/random" (UNIX) or
55       "CryptGenRandom" (Win32).
56
57        $pk->generate_key;
58
59   import_key
60       Loads private or public key in DER or PEM format.
61
62        $pk->import_key($filename);
63        #or
64        $pk->import_key(\$buffer_containing_key);
65
66       Support for password protected PEM keys:
67
68        $pk->import_key($filename, $password);
69        #or
70        $pk->import_key(\$buffer_containing_key, $password);
71
72       Loading private or public keys form perl hash:
73
74        $pk->import_key($hashref);
75
76        # the $hashref is either a key exported via key2hash
77        $pk->import_key({
78             curve => "x25519",
79             pub   => "EA7806F721A8570512C8F6EFB4E8D620C49A529E4DF5EAA77DEC646FB1E87E41",
80             priv  => "002F93D10BA5728D8DD8E9527721DABA3261C0BB1BEFDE7B4BBDAC631D454651",
81        });
82
83        # or a hash with items corresponding to JWK (JSON Web Key)
84        $pk->import_key({
85              kty => "OKP",
86              crv => "X25519",
87              d   => "AC-T0Qulco2N2OlSdyHaujJhwLsb7957S72sYx1FRlE",
88              x   => "6ngG9yGoVwUSyPbvtOjWIMSaUp5N9eqnfexkb7HofkE",
89        });
90
91       Supported key formats:
92
93        # all formats can be loaded from a file
94        my $pk = Crypt::PK::X25519->new($filename);
95
96        # or from a buffer containing the key
97        my $pk = Crypt::PK::X25519->new(\$buffer_with_key);
98
99       •   X25519 private keys in PEM format
100
101            -----BEGIN X25519 PRIVATE KEY-----
102            MC4CAQAwBQYDK2VuBCIEIAAvk9ELpXKNjdjpUnch2royYcC7G+/ee0u9rGMdRUZR
103            -----END X25519 PRIVATE KEY-----
104
105       •   X25519 private keys in password protected PEM format
106
107            -----BEGIN X25519 PRIVATE KEY-----
108            Proc-Type: 4,ENCRYPTED
109            DEK-Info: DES-CBC,DEEFD3D6B714E75A
110
111            dfFWP5bKn49aZ993NVAhQQPdFWgsTb4j8CWhRjGBVTPl6ITstAL17deBIRBwZb7h
112            pAyIka81Kfs=
113            -----END X25519 PRIVATE KEY-----
114
115       •   X25519 public keys in PEM format
116
117            -----BEGIN PUBLIC KEY-----
118            MCowBQYDK2VuAyEA6ngG9yGoVwUSyPbvtOjWIMSaUp5N9eqnfexkb7HofkE=
119            -----END PUBLIC KEY-----
120
121       •   PKCS#8 private keys
122
123            -----BEGIN PRIVATE KEY-----
124            MC4CAQAwBQYDK2VuBCIEIAAvk9ELpXKNjdjpUnch2royYcC7G+/ee0u9rGMdRUZR
125            -----END PRIVATE KEY-----
126
127       •   PKCS#8 encrypted private keys
128
129            -----BEGIN ENCRYPTED PRIVATE KEY-----
130            MIGHMEsGCSqGSIb3DQEFDTA+MCkGCSqGSIb3DQEFDDAcBAiS0NOFZmjJswICCAAw
131            DAYIKoZIhvcNAgkFADARBgUrDgMCBwQIGd40Hdso8Y4EONSRCTrqvftl9hl3zbH9
132            2QmHF1KJ4HDMdLDRxD7EynonCw2SV7BO+XNRHzw2yONqiTybfte7nk9t
133            -----END ENCRYPTED PRIVATE KEY-----
134
135       •   X25519 private keys in JSON Web Key (JWK) format
136
137           See <https://tools.ietf.org/html/rfc8037>
138
139            {
140             "kty":"OKP",
141             "crv":"X25519",
142             "x":"6ngG9yGoVwUSyPbvtOjWIMSaUp5N9eqnfexkb7HofkE",
143             "d":"AC-T0Qulco2N2OlSdyHaujJhwLsb7957S72sYx1FRlE",
144            }
145
146           BEWARE: For JWK support you need to have JSON module installed.
147
148       •   X25519 public keys in JSON Web Key (JWK) format
149
150            {
151             "kty":"OKP",
152             "crv":"X25519",
153             "x":"6ngG9yGoVwUSyPbvtOjWIMSaUp5N9eqnfexkb7HofkE",
154            }
155
156           BEWARE: For JWK support you need to have JSON module installed.
157
158   import_key_raw
159       Import raw public/private key - can load raw key data exported by
160       "export_key_raw".
161
162        $pk->import_key_raw($key, 'public');
163        $pk->import_key_raw($key, 'private');
164
165   export_key_der
166        my $private_der = $pk->export_key_der('private');
167        #or
168        my $public_der = $pk->export_key_der('public');
169
170   export_key_pem
171        my $private_pem = $pk->export_key_pem('private');
172        #or
173        my $public_pem = $pk->export_key_pem('public');
174
175       Support for password protected PEM keys
176
177        my $private_pem = $pk->export_key_pem('private', $password);
178        #or
179        my $private_pem = $pk->export_key_pem('private', $password, $cipher);
180
181        # supported ciphers: 'DES-CBC'
182        #                    'DES-EDE3-CBC'
183        #                    'SEED-CBC'
184        #                    'CAMELLIA-128-CBC'
185        #                    'CAMELLIA-192-CBC'
186        #                    'CAMELLIA-256-CBC'
187        #                    'AES-128-CBC'
188        #                    'AES-192-CBC'
189        #                    'AES-256-CBC' (DEFAULT)
190
191   export_key_jwk
192       Exports public/private keys as a JSON Web Key (JWK).
193
194        my $private_json_text = $pk->export_key_jwk('private');
195        #or
196        my $public_json_text = $pk->export_key_jwk('public');
197
198       Also exports public/private keys as a perl HASH with JWK structure.
199
200        my $jwk_hash = $pk->export_key_jwk('private', 1);
201        #or
202        my $jwk_hash = $pk->export_key_jwk('public', 1);
203
204       BEWARE: For JWK support you need to have JSON module installed.
205
206   export_key_raw
207       Export raw public/private key
208
209        my $private_bytes = $pk->export_key_raw('private');
210        #or
211        my $public_bytes = $pk->export_key_raw('public');
212
213   shared_secret
214         # Alice having her priv key $pk and Bob's public key $pkb
215         my $pk  = Crypt::PK::X25519->new($priv_key_filename);
216         my $pkb = Crypt::PK::X25519->new($pub_key_filename);
217         my $shared_secret = $pk->shared_secret($pkb);
218
219         # Bob having his priv key $pk and Alice's public key $pka
220         my $pk = Crypt::PK::X25519->new($priv_key_filename);
221         my $pka = Crypt::PK::X25519->new($pub_key_filename);
222         my $shared_secret = $pk->shared_secret($pka);  # same value as computed by Alice
223
224   is_private
225        my $rv = $pk->is_private;
226        # 1 .. private key loaded
227        # 0 .. public key loaded
228        # undef .. no key loaded
229
230   key2hash
231        my $hash = $pk->key2hash;
232
233        # returns hash like this (or undef if no key loaded):
234        {
235          curve => "x25519",
236          # raw public key as a hexadecimal string
237          pub   => "EA7806F721A8570512C8F6EFB4E8D620C49A529E4DF5EAA77DEC646FB1E87E41",
238          # raw private key as a hexadecimal string. undef if key is public only
239          priv  => "002F93D10BA5728D8DD8E9527721DABA3261C0BB1BEFDE7B4BBDAC631D454651",
240        }
241

SEE ALSO

243       •   <https://en.wikipedia.org/wiki/Curve25519>
244
245       •   <https://tools.ietf.org/html/rfc7748>
246
247
248
249perl v5.34.0                      2022-02-14              Crypt::PK::X25519(3)
Impressum