| 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; |