Crypt::PK::ECC(3pm)

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

NAME

6       Crypt::PK::ECC - Public key cryptography based on EC
7

SYNOPSIS

9        ### OO interface
10
11        #Encryption: Alice
12        my $pub = Crypt::PK::ECC->new('Bob_pub_ecc1.der');
13        my $ct = $pub->encrypt("secret message");
14        #
15        #Encryption: Bob (received ciphertext $ct)
16        my $priv = Crypt::PK::ECC->new('Bob_priv_ecc1.der');
17        my $pt = $priv->decrypt($ct);
18
19        #Signature: Alice
20        my $priv = Crypt::PK::ECC->new('Alice_priv_ecc1.der');
21        my $sig = $priv->sign_message($message);
22        #
23        #Signature: Bob (received $message + $sig)
24        my $pub = Crypt::PK::ECC->new('Alice_pub_ecc1.der');
25        $pub->verify_message($sig, $message) or die "ERROR";
26
27        #Shared secret
28        my $priv = Crypt::PK::ECC->new('Alice_priv_ecc1.der');
29        my $pub = Crypt::PK::ECC->new('Bob_pub_ecc1.der');
30        my $shared_secret = $priv->shared_secret($pub);
31
32        #Key generation
33        my $pk = Crypt::PK::ECC->new();
34        $pk->generate_key('secp160r1');
35        my $private_der = $pk->export_key_der('private');
36        my $public_der = $pk->export_key_der('public');
37        my $private_pem = $pk->export_key_pem('private');
38        my $public_pem = $pk->export_key_pem('public');
39        my $public_raw = $pk->export_key_raw('public');
40
41        ### Functional interface
42
43        #Encryption: Alice
44        my $ct = ecc_encrypt('Bob_pub_ecc1.der', "secret message");
45        #Encryption: Bob (received ciphertext $ct)
46        my $pt = ecc_decrypt('Bob_priv_ecc1.der', $ct);
47
48        #Signature: Alice
49        my $sig = ecc_sign_message('Alice_priv_ecc1.der', $message);
50        #Signature: Bob (received $message + $sig)
51        ecc_verify_message('Alice_pub_ecc1.der', $sig, $message) or die "ERROR";
52
53        #Shared secret
54        my $shared_secret = ecc_shared_secret('Alice_priv_ecc1.der', 'Bob_pub_ecc1.der');
55

DESCRIPTION

57       The module provides a set of core ECC functions as well as
58       implementation of ECDSA and ECDH.
59
60       Supports elliptic curves "y^2 = x^3 + a*x + b" over prime fields "Fp =
61       Z/pZ" (binary fields not supported).
62

METHODS

64   new
65        my $pk = Crypt::PK::ECC->new();
66        #or
67        my $pk = Crypt::PK::ECC->new($priv_or_pub_key_filename);
68        #or
69        my $pk = Crypt::PK::ECC->new(\$buffer_containing_priv_or_pub_key);
70
71       Support for password protected PEM keys
72
73        my $pk = Crypt::PK::ECC->new($priv_pem_key_filename, $password);
74        #or
75        my $pk = Crypt::PK::ECC->new(\$buffer_containing_priv_pem_key, $password);
76
77   generate_key
78       Uses Yarrow-based cryptographically strong random number generator
79       seeded with random data taken from "/dev/random" (UNIX) or
80       "CryptGenRandom" (Win32).
81
82        $pk->generate_key($curve_name);
83        #or
84        $pk->generate_key($hashref_with_curve_params);
85
86       The following predefined $curve_name values are supported:
87
88        # curves from http://www.ecc-brainpool.org/download/Domain-parameters.pdf
89        'brainpoolp160r1'
90        'brainpoolp192r1'
91        'brainpoolp224r1'
92        'brainpoolp256r1'
93        'brainpoolp320r1'
94        'brainpoolp384r1'
95        'brainpoolp512r1'
96        # curves from http://www.secg.org/collateral/sec2_final.pdf
97        'secp112r1'
98        'secp112r2'
99        'secp128r1'
100        'secp128r2'
101        'secp160k1'
102        'secp160r1'
103        'secp160r2'
104        'secp192k1'
105        'secp192r1'   ... same as nistp192, prime192v1
106        'secp224k1'
107        'secp224r1'   ... same as nistp224
108        'secp256k1'   ... used by Bitcoin
109        'secp256r1'   ... same as nistp256, prime256v1
110        'secp384r1'   ... same as nistp384
111        'secp521r1'   ... same as nistp521
112        #curves from http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf
113        'nistp192'    ... same as secp192r1, prime192v1
114        'nistp224'    ... same as secp224r1
115        'nistp256'    ... same as secp256r1, prime256v1
116        'nistp384'    ... same as secp384r1
117        'nistp521'    ... same as secp521r1
118        # curves from ANS X9.62
119        'prime192v1'   ... same as nistp192, secp192r1
120        'prime192v2'
121        'prime192v3'
122        'prime239v1'
123        'prime239v2'
124        'prime239v3'
125        'prime256v1'   ... same as nistp256, secp256r1
126
127       Using custom curve parameters:
128
129        $pk->generate_key({ prime    => 'FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFF',
130                            A        => 'FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFC',
131                            B        => '22123DC2395A05CAA7423DAECCC94760A7D462256BD56916',
132                            Gx       => '7D29778100C65A1DA1783716588DCE2B8B4AEE8E228F1896',
133                            Gy       => '38A90F22637337334B49DCB66A6DC8F9978ACA7648A943B0',
134                            order    => 'FFFFFFFFFFFFFFFFFFFFFFFF7A62D031C83F4294F640EC13',
135                            cofactor => 1 });
136
137       See <http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf>,
138       <http://www.secg.org/collateral/sec2_final.pdf>,
139       <http://www.ecc-brainpool.org/download/Domain-parameters.pdf>
140
141   import_key
142       Loads private or public key in DER or PEM format.
143
144        $pk->import_key($filename);
145        #or
146        $pk->import_key(\$buffer_containing_key);
147
148       Support for password protected PEM keys:
149
150        $pk->import_key($filename, $password);
151        #or
152        $pk->import_key(\$buffer_containing_key, $password);
153
154       Loading private or public keys form perl hash:
155
156        $pk->import_key($hashref);
157
158        # the $hashref is either a key exported via key2hash
159        $pk->import_key({
160             curve_A        => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFC",
161             curve_B        => "1C97BEFC54BD7A8B65ACF89F81D4D4ADC565FA45",
162             curve_bits     => 160,
163             curve_bytes    => 20,
164             curve_cofactor => 1,
165             curve_Gx       => "4A96B5688EF573284664698968C38BB913CBFC82",
166             curve_Gy       => "23A628553168947D59DCC912042351377AC5FB32",
167             curve_order    => "0100000000000000000001F4C8F927AED3CA752257",
168             curve_prime    => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFF",
169             k              => "B0EE84A749FE95DF997E33B8F333E12101E824C3",
170             pub_x          => "5AE1ACE3ED0AEA9707CE5C0BCE014F6A2F15023A",
171             pub_y          => "895D57E992D0A15F88D6680B27B701F615FCDC0F",
172        });
173
174        # or with the curve defined just by name
175        $pk->import_key({
176             curve_name => "secp160r1",
177             k          => "B0EE84A749FE95DF997E33B8F333E12101E824C3",
178             pub_x      => "5AE1ACE3ED0AEA9707CE5C0BCE014F6A2F15023A",
179             pub_y      => "895D57E992D0A15F88D6680B27B701F615FCDC0F",
180        });
181
182        # or a hash with items corresponding to JWK (JSON Web Key)
183        $pk->import_key({
184              kty => "EC",
185              crv => "P-256",
186              x   => "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
187              y   => "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
188              d   => "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE",
189        });
190
191       Supported key formats:
192
193        # all formats can be loaded from a file
194        my $pk = Crypt::PK::ECC->new($filename);
195
196        # or from a buffer containing the key
197        my $pk = Crypt::PK::ECC->new(\$buffer_with_key);
198
199       •   EC private keys with with all curve parameters
200
201            -----BEGIN EC PRIVATE KEY-----
202            MIIB+gIBAQQwCKEAcA6cIt6CGfyLKm57LyXWv2PgTjydrHSbvhDJTOl+7bzUW8DS
203            rgSdtSPONPq1oIIBWzCCAVcCAQEwPAYHKoZIzj0BAQIxAP//////////////////
204            ///////////////////////+/////wAAAAAAAAAA/////zB7BDD/////////////
205            /////////////////////////////v////8AAAAAAAAAAP////wEMLMxL6fiPufk
206            mI4Fa+P4LRkYHZxu/oFBEgMUCI9QE4daxlY5jYou0Z0qhcjt0+wq7wMVAKM1kmqj
207            GaJ6HQCJamdzpIJ6zaxzBGEEqofKIr6LBTeOscce8yCtdG4dO2KLp5uYWfdB4IJU
208            KjhVAvJdv1UpbDpUXjhydgq3NhfeSpYmLG9dnpi/kpLcKfj0Hb0omhR86doxE7Xw
209            uMAKYLHOHX6BnXpDHXyQ6g5fAjEA////////////////////////////////x2NN
210            gfQ3Ld9YGg2ySLCneuzsGWrMxSlzAgEBoWQDYgAEeGyHPLmHcszPQ9MIIYnznpzi
211            QbvuJtYSjCqtIGxDfzgcLcc3nCc5tBxo+qX6OJEzcWdDAC0bwplY+9Z9jHR3ylNy
212            ovlHoK4ItdWkVO8NH89SLSRyVuOF8N5t3CHIo93B
213            -----END EC PRIVATE KEY-----
214
215       •   EC private keys with curve defined by OID (short form)
216
217            -----BEGIN EC PRIVATE KEY-----
218            MHcCAQEEIBG1c3z52T8XwMsahGVdOZWgKCQJfv+l7djuJjgetdbDoAoGCCqGSM49
219            AwEHoUQDQgAEoBUyo8CQAFPeYPvv78ylh5MwFZjTCLQeb042TjiMJxG+9DLFmRSM
220            lBQ9T/RsLLc+PmpB1+7yPAR+oR5gZn3kJQ==
221            -----END EC PRIVATE KEY-----
222
223       •   EC private keys with curve defined by OID + compressed form
224           (supported since: CryptX-0.059)
225
226            -----BEGIN EC PRIVATE KEY-----
227            MFcCAQEEIBG1c3z52T8XwMsahGVdOZWgKCQJfv+l7djuJjgetdbDoAoGCCqGSM49
228            AwEHoSQDIgADoBUyo8CQAFPeYPvv78ylh5MwFZjTCLQeb042TjiMJxE=
229            -----END EC PRIVATE KEY-----
230
231       •   EC private keys in password protected PEM format
232
233            -----BEGIN EC PRIVATE KEY-----
234            Proc-Type: 4,ENCRYPTED
235            DEK-Info: AES-128-CBC,98245C830C9282F7937E13D1D5BA11EC
236
237            0Y85oZ2+BKXYwrkBjsZdj6gnhOAfS5yDVmEsxFCDug+R3+Kw3QvyIfO4MVo9iWoA
238            D7wtoRfbt2OlBaLVl553+6QrUoa2DyKf8kLHQs1x1/J7tJOMM4SCXjlrOaToQ0dT
239            o7fOnjQjHne16pjgBVqGilY/I79Ab85AnE4uw7vgEucBEiU0d3nrhwuS2Opnhzyx
240            009q9VLDPwY2+q7tXjTqnk9mCmQgsiaDJqY09wlauSukYPgVuOJFmi1VdkRSDKYZ
241            rUUsQvz6Q6Q+QirSlfHna+NhUgQ2eyhGszwcP6NU8iqIxI+NCwfFVuAzw539yYwS
242            8SICczoC/YRlaclayXuomQ==
243            -----END EC PRIVATE KEY-----
244
245       •   EC public keys with all curve parameters
246
247            -----BEGIN PUBLIC KEY-----
248            MIH1MIGuBgcqhkjOPQIBMIGiAgEBMCwGByqGSM49AQECIQD/////////////////
249            ///////////////////+///8LzAGBAEABAEHBEEEeb5mfvncu6xVoGKVzocLBwKb
250            /NstzijZWfKBWxb4F5hIOtp3JqPEZV2k+/wOEQio/Re0SKaFVBmcR9CP+xDUuAIh
251            AP////////////////////66rtzmr0igO7/SXozQNkFBAgEBA0IABITjF/nKK3jg
252            pjmBRXKWAv7ekR1Ko/Nb5FFPHXjH0sDrpS7qRxFALwJHv7ylGnekgfKU3vzcewNs
253            lvjpBYt0Yg4=
254            -----END PUBLIC KEY-----
255
256       •   EC public keys with curve defined by OID (short form)
257
258            -----BEGIN PUBLIC KEY-----
259            MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEoBUyo8CQAFPeYPvv78ylh5MwFZjT
260            CLQeb042TjiMJxG+9DLFmRSMlBQ9T/RsLLc+PmpB1+7yPAR+oR5gZn3kJQ==
261            -----END PUBLIC KEY-----
262
263       •   EC public keys with curve defined by OID + public point in
264           compressed form (supported since: CryptX-0.059)
265
266            -----BEGIN PUBLIC KEY-----
267            MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADoBUyo8CQAFPeYPvv78ylh5MwFZjT
268            CLQeb042TjiMJxE=
269            -----END PUBLIC KEY-----
270
271       •   PKCS#8 private keys with all curve parameters
272
273            -----BEGIN PRIVATE KEY-----
274            MIIBMAIBADCB0wYHKoZIzj0CATCBxwIBATAkBgcqhkjOPQEBAhkA////////////
275            /////////v//////////MEsEGP////////////////////7//////////AQYIhI9
276            wjlaBcqnQj2uzMlHYKfUYiVr1WkWAxUAxGloRDXes3jEtlypWR4qV2MFmi4EMQR9
277            KXeBAMZaHaF4NxZYjc4ri0rujiKPGJY4qQ8iY3M3M0tJ3LZqbcj5l4rKdkipQ7AC
278            GQD///////////////96YtAxyD9ClPZA7BMCAQEEVTBTAgEBBBiKolTGIsTgOCtl
279            6dpdos0LvuaExCDFyT6hNAMyAAREwaCX0VY1LZxLW3G75tmft4p9uhc0J7/+NGaP
280            DN3Tr7SXkT9+co2a+8KPJhQy10k=
281            -----END PRIVATE KEY-----
282
283       •   PKCS#8 private keys with curve defined by OID (short form)
284
285            -----BEGIN PRIVATE KEY-----
286            MG8CAQAwEwYHKoZIzj0CAQYIKoZIzj0DAQMEVTBTAgEBBBjFP/caeQV4WO3fnWWS
287            f917PGzwtypd/t+hNAMyAATSg6pBT7RO6l/p+aKcrFsGuthUdfwJWS5V3NGcVt1b
288            lEHQYjWya2YnHaPq/iMFa7A=
289            -----END PRIVATE KEY-----
290
291       •   PKCS#8 encrypted private keys - password protected keys (supported
292           since: CryptX-0.059)
293
294            -----BEGIN ENCRYPTED PRIVATE KEY-----
295            MIGYMBwGCiqGSIb3DQEMAQMwDgQINApjTa6oFl0CAggABHi+59l4d4e6KtG9yci2
296            BSC65LEsQSnrnFAExfKptNU1zMFsDLCRvDeDQDbxc6HlfoxyqFL4SmH1g3RvC/Vv
297            NfckdL5O2L8MRnM+ljkFtV2Te4fszWcJFdd7KiNOkPpn+7sWLfzQdvhHChLKUzmz
298            4INKZyMv/G7VpZ0=
299            -----END ENCRYPTED PRIVATE KEY-----
300
301       •   EC public key from X509 certificate
302
303            -----BEGIN CERTIFICATE-----
304            MIIBdDCCARqgAwIBAgIJAL2BBClDEnnOMAoGCCqGSM49BAMEMBcxFTATBgNVBAMM
305            DFRlc3QgQ2VydCBFQzAgFw0xNzEyMzAyMDMzNDFaGA8zMDE3MDUwMjIwMzM0MVow
306            FzEVMBMGA1UEAwwMVGVzdCBDZXJ0IEVDMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE
307            KvkL2r5xZp7RzxLQJK+6tn/7lic+L70e1fmNbHOdxRaRvbK5G0AQWrdsbjJb92Ni
308            lCQk2+w/i+VuS2Q3MSR5TaNQME4wHQYDVR0OBBYEFGbJkDyKgaMcIGHS8/WuqIVw
309            +R8sMB8GA1UdIwQYMBaAFGbJkDyKgaMcIGHS8/WuqIVw+R8sMAwGA1UdEwQFMAMB
310            Af8wCgYIKoZIzj0EAwQDSAAwRQIhAJtOsmrM+gJpImoynAyqTN+7myL71uxd+YeC
311            6ze4MnzWAiBQi5/BqEr/SQ1+BC2TPtswvJPRFh2ZvT/6Km3gKoNVXQ==
312            -----END CERTIFICATE-----
313
314       •   SSH public EC keys
315
316            ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNT...T3xYfJIs=
317
318       •   SSH public EC keys (RFC-4716 format)
319
320            ---- BEGIN SSH2 PUBLIC KEY ----
321            Comment: "521-bit ECDSA, converted from OpenSSH"
322            AAAAE2VjZHNhLXNoYTItbmlzdHA1MjEAAAAIbmlzdHA1MjEAAACFBAFk35srteP9twCwYK
323            vU9ovMBi77Dd6lEBPrFaMEb0CZdZ5MC3nSqflGHRWkSbUpjdPdO7cYQNpK9YXHbNSO5hbU
324            1gFZgyiGFxwJYYz8NAjedBXMgyH4JWplK5FQm5P5cvaglItC9qkKioUXhCc67YMYBtivXl
325            Ue0PgIq6kbHTqbX6+5Nw==
326            ---- END SSH2 PUBLIC KEY ----
327
328       •   EC private keys in JSON Web Key (JWK) format
329
330           See <http://tools.ietf.org/html/draft-ietf-jose-json-web-key>
331
332            {
333             "kty":"EC",
334             "crv":"P-256",
335             "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
336             "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
337             "d":"870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE",
338            }
339
340           BEWARE: For JWK support you need to have JSON module installed.
341
342       •   EC public keys in JSON Web Key (JWK) format
343
344            {
345             "kty":"EC",
346             "crv":"P-256",
347             "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
348             "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
349            }
350
351           BEWARE: For JWK support you need to have JSON module installed.
352
353   import_key_raw
354       Import raw public/private key - can load data exported by
355       "export_key_raw".
356
357        $pk->import_key_raw($key, $curve);
358        # $key .... data exported by export_key_raw()
359        # $curve .. curve name or hashref with curve parameters - same as by generate_key()
360
361   export_key_der
362        my $private_der = $pk->export_key_der('private');
363        #or
364        my $public_der = $pk->export_key_der('public');
365
366       Since CryptX-0.36 "export_key_der" can also export keys in a format
367       that does not explicitly contain curve parameters but only curve OID.
368
369        my $private_der = $pk->export_key_der('private_short');
370        #or
371        my $public_der = $pk->export_key_der('public_short');
372
373       Since CryptX-0.59 "export_key_der" can also export keys in "compressed"
374       format that defines curve by OID + stores public point in compressed
375       form.
376
377        my $private_pem = $pk->export_key_der('private_compressed');
378        #or
379        my $public_pem = $pk->export_key_der('public_compressed');
380
381   export_key_pem
382        my $private_pem = $pk->export_key_pem('private');
383        #or
384        my $public_pem = $pk->export_key_pem('public');
385
386       Since CryptX-0.36 "export_key_pem" can also export keys in a format
387       that does not explicitly contain curve parameters but only curve OID.
388
389        my $private_pem = $pk->export_key_pem('private_short');
390        #or
391        my $public_pem = $pk->export_key_pem('public_short');
392
393       Since CryptX-0.59 "export_key_pem" can also export keys in "compressed"
394       format that defines curve by OID + stores public point in compressed
395       form.
396
397        my $private_pem = $pk->export_key_pem('private_compressed');
398        #or
399        my $public_pem = $pk->export_key_pem('public_compressed');
400
401       Support for password protected PEM keys
402
403        my $private_pem = $pk->export_key_pem('private', $password);
404        #or
405        my $private_pem = $pk->export_key_pem('private', $password, $cipher);
406
407        # supported ciphers: 'DES-CBC'
408        #                    'DES-EDE3-CBC'
409        #                    'SEED-CBC'
410        #                    'CAMELLIA-128-CBC'
411        #                    'CAMELLIA-192-CBC'
412        #                    'CAMELLIA-256-CBC'
413        #                    'AES-128-CBC'
414        #                    'AES-192-CBC'
415        #                    'AES-256-CBC' (DEFAULT)
416
417   export_key_jwk
418       Since: CryptX-0.022
419
420       Exports public/private keys as a JSON Web Key (JWK).
421
422        my $private_json_text = $pk->export_key_jwk('private');
423        #or
424        my $public_json_text = $pk->export_key_jwk('public');
425
426       Also exports public/private keys as a perl HASH with JWK structure.
427
428        my $jwk_hash = $pk->export_key_jwk('private', 1);
429        #or
430        my $jwk_hash = $pk->export_key_jwk('public', 1);
431
432       BEWARE: For JWK support you need to have JSON module installed.
433
434   export_key_jwk_thumbprint
435       Since: CryptX-0.031
436
437       Exports the key's JSON Web Key Thumbprint as a string.
438
439       If you don't know what this is, see RFC 7638
440       <https://tools.ietf.org/html/rfc7638>.
441
442        my $thumbprint = $pk->export_key_jwk_thumbprint('SHA256');
443
444   export_key_raw
445       Export raw public/private key. Public key is exported in ASN X9.62
446       format (compressed or uncompressed), private key is exported as raw
447       bytes (padded with leading zeros to have the same size as the ECC
448       curve).
449
450        my $pubkey_octets  = $pk->export_key_raw('public');
451        #or
452        my $pubckey_octets = $pk->export_key_raw('public_compressed');
453        #or
454        my $privkey_octets = $pk->export_key_raw('private');
455
456   encrypt
457        my $pk = Crypt::PK::ECC->new($pub_key_filename);
458        my $ct = $pk->encrypt($message);
459        #or
460        my $ct = $pk->encrypt($message, $hash_name);
461
462        #NOTE: $hash_name can be 'SHA1' (DEFAULT), 'SHA256' or any other hash supported by Crypt::Digest
463
464   decrypt
465        my $pk = Crypt::PK::ECC->new($priv_key_filename);
466        my $pt = $pk->decrypt($ciphertext);
467
468   sign_message
469        my $pk = Crypt::PK::ECC->new($priv_key_filename);
470        my $signature = $priv->sign_message($message);
471        #or
472        my $signature = $priv->sign_message($message, $hash_name);
473
474        #NOTE: $hash_name can be 'SHA1' (DEFAULT), 'SHA256' or any other hash supported by Crypt::Digest
475
476   sign_message_rfc7518
477       Since: CryptX-0.024
478
479       Same as sign_message only the signature format is as defined by
480       <https://tools.ietf.org/html/rfc7518> (JWA - JSON Web Algorithms).
481
482       BEWARE: This creates signatures according to the structure that RFC
483       7518 describes but does not apply the RFC logic for the hashing
484       algorithm selection. You'll still need to specify, e.g., SHA256 for a
485       P-256 key to get a fully RFC-7518-compliant signature.
486
487   verify_message
488        my $pk = Crypt::PK::ECC->new($pub_key_filename);
489        my $valid = $pub->verify_message($signature, $message)
490        #or
491        my $valid = $pub->verify_message($signature, $message, $hash_name);
492
493        #NOTE: $hash_name can be 'SHA1' (DEFAULT), 'SHA256' or any other hash supported by Crypt::Digest
494
495   verify_message_rfc7518
496       Since: CryptX-0.024
497
498       Same as verify_message only the signature format is as defined by
499       <https://tools.ietf.org/html/rfc7518> (JWA - JSON Web Algorithms).
500
501       BEWARE: This verifies signatures according to the structure that RFC
502       7518 describes but does not apply the RFC logic for the hashing
503       algorithm selection. You'll still need to specify, e.g., SHA256 for a
504       P-256 key to get a fully RFC-7518-compliant signature.
505
506   sign_hash
507        my $pk = Crypt::PK::ECC->new($priv_key_filename);
508        my $signature = $priv->sign_hash($message_hash);
509
510   sign_hash_rfc7518
511       Since: CryptX-0.059
512
513       Same as sign_hash only the signature format is as defined by
514       <https://tools.ietf.org/html/rfc7518> (JWA - JSON Web Algorithms).
515
516   verify_hash
517        my $pk = Crypt::PK::ECC->new($pub_key_filename);
518        my $valid = $pub->verify_hash($signature, $message_hash);
519
520   verify_hash_rfc7518
521       Since: CryptX-0.059
522
523       Same as verify_hash only the signature format is as defined by
524       <https://tools.ietf.org/html/rfc7518> (JWA - JSON Web Algorithms).
525
526   shared_secret
527         # Alice having her priv key $pk and Bob's public key $pkb
528         my $pk  = Crypt::PK::ECC->new($priv_key_filename);
529         my $pkb = Crypt::PK::ECC->new($pub_key_filename);
530         my $shared_secret = $pk->shared_secret($pkb);
531
532         # Bob having his priv key $pk and Alice's public key $pka
533         my $pk = Crypt::PK::ECC->new($priv_key_filename);
534         my $pka = Crypt::PK::ECC->new($pub_key_filename);
535         my $shared_secret = $pk->shared_secret($pka);  # same value as computed by Alice
536
537   is_private
538        my $rv = $pk->is_private;
539        # 1 .. private key loaded
540        # 0 .. public key loaded
541        # undef .. no key loaded
542
543   size
544        my $size = $pk->size;
545        # returns key size in bytes or undef if no key loaded
546
547   key2hash
548        my $hash = $pk->key2hash;
549
550        # returns hash like this (or undef if no key loaded):
551        {
552          size           => 20, # integer: key (curve) size in bytes
553          type           => 1,  # integer: 1 .. private, 0 .. public
554          #curve parameters
555          curve_A        => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFC",
556          curve_B        => "1C97BEFC54BD7A8B65ACF89F81D4D4ADC565FA45",
557          curve_bits     => 160,
558          curve_bytes    => 20,
559          curve_cofactor => 1,
560          curve_Gx       => "4A96B5688EF573284664698968C38BB913CBFC82",
561          curve_Gy       => "23A628553168947D59DCC912042351377AC5FB32",
562          curve_name     => "secp160r1",
563          curve_order    => "0100000000000000000001F4C8F927AED3CA752257",
564          curve_prime    => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFF",
565          #private key
566          k              => "B0EE84A749FE95DF997E33B8F333E12101E824C3",
567          #public key point coordinates
568          pub_x          => "5AE1ACE3ED0AEA9707CE5C0BCE014F6A2F15023A",
569          pub_y          => "895D57E992D0A15F88D6680B27B701F615FCDC0F",
570        }
571
572   curve2hash
573       Since: CryptX-0.024
574
575        my $crv = $pk->curve2hash;
576
577        # returns a hash that can be passed to: $pk->generate_key($crv)
578        {
579          A        => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFC",
580          B        => "1C97BEFC54BD7A8B65ACF89F81D4D4ADC565FA45",
581          cofactor => 1,
582          Gx       => "4A96B5688EF573284664698968C38BB913CBFC82",
583          Gy       => "23A628553168947D59DCC912042351377AC5FB32",
584          order    => "0100000000000000000001F4C8F927AED3CA752257",
585          prime    => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFF",
586        }
587

FUNCTIONS

589   ecc_encrypt
590       Elliptic Curve Diffie-Hellman (ECDH) encryption as implemented by
591       libtomcrypt. See method "encrypt" below.
592
593        my $ct = ecc_encrypt($pub_key_filename, $message);
594        #or
595        my $ct = ecc_encrypt(\$buffer_containing_pub_key, $message);
596        #or
597        my $ct = ecc_encrypt($pub_key_filename, $message, $hash_name);
598
599        #NOTE: $hash_name can be 'SHA1' (DEFAULT), 'SHA256' or any other hash supported by Crypt::Digest
600
601       ECCDH Encryption is performed by producing a random key, hashing it,
602       and XOR'ing the digest against the plaintext.
603
604   ecc_decrypt
605       Elliptic Curve Diffie-Hellman (ECDH) decryption as implemented by
606       libtomcrypt. See method "decrypt" below.
607
608        my $pt = ecc_decrypt($priv_key_filename, $ciphertext);
609        #or
610        my $pt = ecc_decrypt(\$buffer_containing_priv_key, $ciphertext);
611
612   ecc_sign_message
613       Elliptic Curve Digital Signature Algorithm (ECDSA) - signature
614       generation. See method "sign_message" below.
615
616        my $sig = ecc_sign_message($priv_key_filename, $message);
617        #or
618        my $sig = ecc_sign_message(\$buffer_containing_priv_key, $message);
619        #or
620        my $sig = ecc_sign_message($priv_key, $message, $hash_name);
621
622   ecc_verify_message
623       Elliptic Curve Digital Signature Algorithm (ECDSA) - signature
624       verification. See method "verify_message" below.
625
626        ecc_verify_message($pub_key_filename, $signature, $message) or die "ERROR";
627        #or
628        ecc_verify_message(\$buffer_containing_pub_key, $signature, $message) or die "ERROR";
629        #or
630        ecc_verify_message($pub_key, $signature, $message, $hash_name) or die "ERROR";
631
632   ecc_sign_hash
633       Elliptic Curve Digital Signature Algorithm (ECDSA) - signature
634       generation. See method "sign_hash" below.
635
636        my $sig = ecc_sign_hash($priv_key_filename, $message_hash);
637        #or
638        my $sig = ecc_sign_hash(\$buffer_containing_priv_key, $message_hash);
639
640   ecc_verify_hash
641       Elliptic Curve Digital Signature Algorithm (ECDSA) - signature
642       verification. See method "verify_hash" below.
643
644        ecc_verify_hash($pub_key_filename, $signature, $message_hash) or die "ERROR";
645        #or
646        ecc_verify_hash(\$buffer_containing_pub_key, $signature, $message_hash) or die "ERROR";
647
648   ecc_shared_secret
649       Elliptic curve Diffie-Hellman (ECDH) - construct a Diffie-Hellman
650       shared secret with a private and public ECC key. See method
651       "shared_secret" below.
652
653        #on Alice side
654        my $shared_secret = ecc_shared_secret('Alice_priv_ecc1.der', 'Bob_pub_ecc1.der');
655
656        #on Bob side
657        my $shared_secret = ecc_shared_secret('Bob_priv_ecc1.der', 'Alice_pub_ecc1.der');
658

OpenSSL interoperability

660        ### let's have:
661        # ECC private key in PEM format - eckey.priv.pem
662        # ECC public key in PEM format  - eckey.pub.pem
663        # data file to be signed - input.data
664
665   Sign by OpenSSL, verify by Crypt::PK::ECC
666       Create signature (from commandline):
667
668        openssl dgst -sha1 -sign eckey.priv.pem -out input.sha1-ec.sig input.data
669
670       Verify signature (Perl code):
671
672        use Crypt::PK::ECC;
673        use Crypt::Digest 'digest_file';
674        use Crypt::Misc 'read_rawfile';
675
676        my $pkec = Crypt::PK::ECC->new("eckey.pub.pem");
677        my $signature = read_rawfile("input.sha1-ec.sig");
678        my $valid = $pkec->verify_hash($signature, digest_file("SHA1", "input.data"), "SHA1", "v1.5");
679        print $valid ? "SUCCESS" : "FAILURE";
680
681   Sign by Crypt::PK::ECC, verify by OpenSSL
682       Create signature (Perl code):
683
684        use Crypt::PK::ECC;
685        use Crypt::Digest 'digest_file';
686        use Crypt::Misc 'write_rawfile';
687
688        my $pkec = Crypt::PK::ECC->new("eckey.priv.pem");
689        my $signature = $pkec->sign_hash(digest_file("SHA1", "input.data"), "SHA1", "v1.5");
690        write_rawfile("input.sha1-ec.sig", $signature);
691
692       Verify signature (from commandline):
693
694        openssl dgst -sha1 -verify eckey.pub.pem -signature input.sha1-ec.sig input.data
695
696   Keys generated by Crypt::PK::ECC
697       Generate keys (Perl code):
698
699        use Crypt::PK::ECC;
700        use Crypt::Misc 'write_rawfile';
701
702        my $pkec = Crypt::PK::ECC->new;
703        $pkec->generate_key('secp160k1');
704        write_rawfile("eckey.pub.der",  $pkec->export_key_der('public'));
705        write_rawfile("eckey.priv.der", $pkec->export_key_der('private'));
706        write_rawfile("eckey.pub.pem",  $pkec->export_key_pem('public'));
707        write_rawfile("eckey.priv.pem", $pkec->export_key_pem('private'));
708        write_rawfile("eckey-passwd.priv.pem", $pkec->export_key_pem('private', 'secret'));
709
710       Use keys by OpenSSL:
711
712        openssl ec -in eckey.priv.der -text -inform der
713        openssl ec -in eckey.priv.pem -text
714        openssl ec -in eckey-passwd.priv.pem -text -inform pem -passin pass:secret
715        openssl ec -in eckey.pub.der -pubin -text -inform der
716        openssl ec -in eckey.pub.pem -pubin -text
717
718   Keys generated by OpenSSL
719       Generate keys:
720
721        openssl ecparam -param_enc explicit -name prime192v3 -genkey -out eckey.priv.pem
722        openssl ec -param_enc explicit -in eckey.priv.pem -out eckey.pub.pem -pubout
723        openssl ec -param_enc explicit -in eckey.priv.pem -out eckey.priv.der -outform der
724        openssl ec -param_enc explicit -in eckey.priv.pem -out eckey.pub.der -outform der -pubout
725        openssl ec -param_enc explicit -in eckey.priv.pem -out eckey.privc.der -outform der -conv_form compressed
726        openssl ec -param_enc explicit -in eckey.priv.pem -out eckey.pubc.der -outform der -pubout -conv_form compressed
727        openssl ec -param_enc explicit -in eckey.priv.pem -passout pass:secret -des3 -out eckey-passwd.priv.pem
728
729       Load keys (Perl code):
730
731        use Crypt::PK::ECC;
732
733        my $pkec = Crypt::PK::ECC->new;
734        $pkec->import_key("eckey.pub.der");
735        $pkec->import_key("eckey.pubc.der");
736        $pkec->import_key("eckey.priv.der");
737        $pkec->import_key("eckey.privc.der");
738        $pkec->import_key("eckey.pub.pem");
739        $pkec->import_key("eckey.priv.pem");
740        $pkec->import_key("eckey-passwd.priv.pem", "secret");
741

NAME

SYNOPSIS

DESCRIPTION

METHODS

FUNCTIONS

OpenSSL interoperability

SEE ALSO