blib/lib/Crypt/Perl/ECDSA.pm untested

filter: Statementstmt 0.0% 0 / 6 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 2 Podpod n/a totaltotal 0.0% 0 / 8 CC 1 SCAR 6.9
CC
1
Cov
0%
BEGIN
2.0
BEGIN
2.0
CRAP 2.0
1 package Crypt::Perl::ECDSA;
2  
3 use strict;
4 use warnings;
5  
6 =encoding utf-8
7  
8 =head1 NAME
9  
10 Crypt::Perl::ECDSA - Elliptic curve cryptography in pure Perl
11  
12 =head1 SYNOPSIS
13  
14 my $pub_key1 = Crypt::Perl::ECDSA::Parse::public($pem_or_der);
15 my $prv_key1 = Crypt::Perl::ECDSA::Parse::private($pem_or_der);
16  
17 #----------------------------------------------------------------------
18  
19 my $prkey_by_name = Crypt::Perl::ECDSA::Generate::by_curve_name('secp521r1');
20  
21 #Probably only useful for trying out a custom curve?
22 my $prkey_by_curve = Crypt::Perl::ECDSA::Generate::by_explicit_curve(
23 {
24 p => ..., #isa Crypt::Perl::BigInt
25 a => ..., #isa Crypt::Perl::BigInt
26 b => ..., #isa Crypt::Perl::BigInt
27 n => ..., #isa Crypt::Perl::BigInt
28  
29 #Supposedly this can be deduced from the above, but I don’t
30 #see the math for this around. It’s not in libtomcryt, AFAICT.
31 #It may have to do with Schoof’s Algorithm?
32 h => ..., #isa Crypt::Perl::BigInt
33  
34 gx => ..., #isa Crypt::Perl::BigInt
35 gy => ..., #isa Crypt::Perl::BigInt
36 },
37 );
38  
39 #----------------------------------------------------------------------
40  
41 my $msg = 'My message';
42  
43 my $hash = Digest::SHA::sha256($msg);
44  
45 my $sig = $private->sign($hash);
46  
47 die 'Wut' if !$private->verify($hash, $sig);
48  
49 die 'Wut' if !$public->verify($hash, $sig);
50  
51 #----------------------------------------------------------------------
52  
53 $key->to_der_with_curve_name();
54 $key->to_der_with_curve_name( compressed => 1 );
55 $key->to_pem_with_curve_name();
56 $key->to_pem_with_curve_name( compressed => 1 );
57  
58 $key->to_der_with_explicit_curve();
59 $key->to_der_with_explicit_curve( seed => 1 );
60 $key->to_der_with_explicit_curve( compressed => 1 );
61 $key->to_der_with_explicit_curve( seed => 1, compressed => 1 );
62 $key->to_pem_with_explicit_curve();
63 $key->to_pem_with_explicit_curve( seed => 1 );
64 $key->to_pem_with_explicit_curve( compressed => 1 );
65 $key->to_pem_with_explicit_curve( seed => 1, compressed => 1 );
66  
67 =head1 DISCUSSION
68  
69 See the documentation for L<Crypt::Perl::ECDSA::PublicKey> and
70 L<Crypt::Perl::ECDSA::PrivateKey> for discussions of what these interfaces
71 can do.
72  
73 =head1 SECURITY
74  
75 The security advantages of elliptic-curve cryptography (ECC) are a matter of
76 some controversy. While the math itself is apparently bulletproof, there are
77 varying opinions about the integrity of the various curves that are recommended
78 for ECC. Some believe that some curves contain backdoors that would allow
79 L<NIST|https://www.nist.gov> to sniff a transmission. For more information,
80 look at L<http://safecurves.cr.yp.to>.
81  
82 That said, RSA will eventually no longer be viable: as RSA keys get bigger, the
83 security advantage of increasing their size diminishes.
84  
85 C<Crypt::Perl> “has no opinion” regarding which curves you use; it ships all
86 of the prime-field curves that (L<OpenSSL|http://openssl.org>) includes and
87 works with any of them. You can try out custom curves as well.
88  
89 =head1 FORMATS SUPPORTED
90  
91 Elliptic-curve keys can be in a variety of formats. This library supports
92 almost all of them:
93  
94 =over
95  
96 =item Parse and export of named curves and explicit curves. (See below
97 about explicit curve parameters.)
98  
99 =item Parse and export of curve points in compressed or uncompressed form,
100 and parse of points in hybrid form.
101 (NB: L<RFC 5480|https://www.rfc-editor.org/rfc/rfc5480.txt>
102 prohibits use of the hybrid form.)
103  
104 =back
105  
106 Explicit curves (i.e., giving the curve by full parameters rather than by
107 name reference) may be a known curve or an arbitrary curve.
108 Explicit curves may include or omit the seed value. It is omitted in output
109 by default. Explicit curves may also include or
110 omit the cofactor, but if the curve is unknown the cofactor is required.
111 This is because this library’s export of explicit curves always includes the
112 cofactor. While it’s not required for ECDSA, it’s recommended, and it’s
113 required for ECDH. Moreover, unlike the seed (which nither ECDSA nor ECDH
114 requires), the cofactor is small enough that its inclusion only enlarges the
115 key by a few bytes.
116  
117 I believe the cofactor can be deduced from the other curve parameters,
118 but I’ve not had time to learn how.
119  
120 Generator/base points will be exported as compressed or uncompressed
121 according to the public point. If for some reason you really need a
122 compressed base point but an uncompressed public point or vice-versa,
123 and you need this library to do it for you,
124 please explain your need for such a thing in your pull request. :-)
125  
126 =head1 TODO
127  
128 Functionality can be augmented as feature requests come in.
129 Patches are welcome—particularly with tests!
130  
131 In particular, it would be great to support characteristic-two curves, though
132 almost everything seems to expect the prime-field variety.
133 (OpenSSL is the only implementation I know of that
134 supports characteristic-two.)
135  
136 It would also be nice to have logic that deduces the cofactor from the
137 other curve parameters.
138  
139 =head1 ACKNOWLEDGEMENTS
140  
141 Most of the ECDSA logic here is ported from Kenji Urushima’s
142 L<jsrsasign|http://kjur.github.io/jsrsasign/>.
143  
144 Curve data is copied from OpenSSL. (See the script included in the
145 distribution.)
146  
147 The point decompression logic is ported from L<LibTomCrypt|http://libtom.net>.
148  
149 =cut
150  
151 1;