blib/lib/Crypt/PK/Ed25519.pm

filter: Statementstmt 54.0% 47 / 87 Branchbran 30.0% 21 / 70 Conditioncond 18.1% 8 / 44 MC/DCmcdc 0.0% 0 / 21 Subroutinesub 66.6% 8 / 12 Podpod 100% 5 / 5 totaltotal 37.2% 89 / 239 CC 51 SCAR 53.1
CC
51
Cov
38%
import_key
330.4
import_key_raw
42.0
export_key_jwk
42.0
CRAP 202.6
« blib/lib/Crypt/PK/X448.pm ↑ Summary blib/lib/Crypt/PK/RSA.pm »
1 package Crypt::PK::Ed25519;
2  
3 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 4 our $VERSION = '0.091';
6  
7 4 require Exporter; our @ISA = qw(Exporter); ### use Exporter 5.57 'import';
8 4 our %EXPORT_TAGS = ( all => [qw( )] );
9 4 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
10 4 our @EXPORT = qw();
11  
12 4 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 4 $Carp::Internal{(__PACKAGE__)}++;
14 4 ▶use CryptX;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 4 ▶use Crypt::PK;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 4 ▶use Crypt::Misc qw(read_rawfile encode_b64u decode_b64u encode_b64 decode_b64 pem_to_der der_to_pem);
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 2 ▶sub new {
Subroutine new: called CC=2 SCAR=7.2
Pod documented
19 2 my $self = shift->_new();
20 2 ▶ return @_ > 0 ? $self->import_key(@_) : $self;
Branch: 1 branch
BranchTrueFalseTotal
@_ > 0 ? : 0 2 2
21 }
22  
23 0 ▶sub import_key_raw {
Subroutine import_key_raw: not called CC=6 SCAR=37.4
Pod documented
24 0 my ($self, $key, $type) = @_;
25 0 ▶ croak "FATAL: undefined key" unless $key;
Branch: 1 branch
BranchTrueFalseTotal
unless $key 0 0 0
26 0 ▶ croak "FATAL: invalid key" unless length($key) == 32;
Branch: 1 branch
BranchTrueFalseTotal
unless length $key == 32 0 0 0
27 0 ▶ croak "FATAL: undefined type" unless $type;
Branch: 1 branch
BranchTrueFalseTotal
unless $type 0 0 0
28 0 ▶ return $self->_import_raw($key, 1) if $type eq 'private';
Branch: 1 branch
BranchTrueFalseTotal
if $type eq "private" 0 0 0
29 0 ▶ return $self->_import_raw($key, 0) if $type eq 'public';
Branch: 1 branch
BranchTrueFalseTotal
if $type eq "public" 0 0 0
30 0 croak "FATAL: invalid key type '$type'";
31 }
32  
33 6 ▶sub import_key {
Subroutine import_key: called CC=36 SCAR=58.0
Pod documented
34 6 my ($self, $key, $password) = @_;
35 6 local $SIG{__DIE__} = \&CryptX::_croak;
36 6 ▶ croak "FATAL: undefined key" unless $key;
Branch: 1 branch
BranchTrueFalseTotal
unless $key 0 6 6
37  
38 # special case
39 6 ▶ if (ref($key) eq 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $key eq "HASH") 2 4 6
40 2 ▶ if ($key->{kty} && $key->{kty} eq "OKP" && $key->{crv} && $key->{crv} eq 'Ed25519') {
Branch: 1 branch
BranchTrueFalseTotal
if ($key->{"kty"} and $key->{"kty"} eq "OKP" and $key->{"crv"} and $key->{"crv"} eq "Ed25519") 0 2 2
Condition33%3/9
$key->{"kty"} and $key->{"kty"} eq "OKP" and $key->{"crv"} and $key->{"crv"} eq "Ed25519"
!ll&&!rl&&r
200
$key->{"kty"} and $key->{"kty"} eq "OKP" and $key->{"crv"}
!ll&&!rl&&r
200
$key->{"kty"} and $key->{"kty"} eq "OKP"
!ll&&!rl&&r
200
MC/DC0%0/4
$key->{"kty"} and $key->{"kty"} eq "OKP" and $key->{"crv"} and $key->{"crv"} eq "Ed25519"
$key->{"kty"} $key->{"kty"} eq "OKP" $key->{"crv"} $key->{"crv"} eq "Ed25519"
Truth table20%1/5
A and B and C and D
A= $key->{"kty"}B= $key->{"kty"} eq "OKP"C= $key->{"crv"}D= $key->{"crv"} eq "Ed25519"
ABCDresult
0XXX0
10XX0
110X0
11100
11111
41 # JWK-like structure e.g.
42 # {"kty":"OKP","crv":"Ed25519","d":"...","x":"..."}
43 0 ▶ return $self->_import_raw(decode_b64u($key->{d}), 1) if $key->{d}; # private
Branch: 1 branch
BranchTrueFalseTotal
if $key->{"d"} 0 0 0
44 0 ▶ return $self->_import_raw(decode_b64u($key->{x}), 0) if $key->{x}; # public
Branch: 1 branch
BranchTrueFalseTotal
if $key->{"x"} 0 0 0
45 }
46 2 ▶ if ($key->{curve} && $key->{curve} eq "ed25519" && ($key->{priv} || $key->{pub})) {
Branch: 1 branch
BranchTrueFalseTotal
if ($key->{"curve"} and $key->{"curve"} eq "ed25519" and $key->{"priv"} || $key->{"pub"}) 2 0 2
Condition44%4/9
$key->{"curve"} and $key->{"curve"} eq "ed25519" and $key->{"priv"} || $key->{"pub"}
!ll&&!rl&&r
002
$key->{"curve"} and $key->{"curve"} eq "ed25519"
!ll&&!rl&&r
002
$key->{"priv"} or $key->{"pub"}
l!l&&r!l&&!r
110
MC/DC0%0/4
$key->{"curve"} and $key->{"curve"} eq "ed25519" and $key->{"priv"} || $key->{"pub"}
$key->{"curve"} $key->{"curve"} eq "ed25519" $key->{"priv"} $key->{"pub"}
Truth table40%2/5
A and B and C or D
A= $key->{"curve"}B= $key->{"curve"} eq "ed25519"C= $key->{"priv"}D= $key->{"pub"}
ABCDresult
0XXX0
10XX0
11000
111X1
11011
47 # hash exported via key2hash
48 2 ▶ return $self->_import_raw(pack("H*", $key->{priv}), 1) if $key->{priv};
Branch: 1 branch
BranchTrueFalseTotal
if $key->{"priv"} 1 1 2
49 1 ▶ return $self->_import_raw(pack("H*", $key->{pub}), 0) if $key->{pub};
Branch: 1 branch
BranchTrueFalseTotal
if $key->{"pub"} 1 0 1
50 }
51 0 croak "FATAL: unexpected Ed25519 key hash";
52 }
53  
54 4 my $data;
55 4 ▶ if (ref($key) eq 'SCALAR') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $key eq 'SCALAR') { } 0 4 4
elsif (-f $key) { } 4 0 4
56 0 $data = $$key;
57 }
58 elsif (-f $key) {
59 4 $data = read_rawfile($key);
60 }
61 else {
62 0 croak "FATAL: non-existing file '$key'";
63 }
64 4 ▶ croak "FATAL: invalid key data" unless $data;
Branch: 1 branch
BranchTrueFalseTotal
unless $data 0 4 4
65  
66 4 ▶ if ($data =~ /-----BEGIN (PUBLIC|PRIVATE|ENCRYPTED PRIVATE) KEY-----(.+?)-----END (PUBLIC|PRIVATE|ENCRYPTED PRIVATE) KEY-----/s) {
Branch: 7 branches
BranchTrueFalseTotal
if ($data =~ /-----BEGIN (PUBLIC|PRIVATE|ENCRYPTED PRIVATE) KEY-----(.+?)-----END (PUBLIC|PRIVATE|ENCRYPTED PRIVATE) KEY-----/s) { } 0 4 4
elsif ($data =~ /-----BEGIN CERTIFICATE-----(.+?)-----END CERTIFICATE-----/s) { } 0 4 4
elsif ($data =~ /-----BEGIN OPENSSH (PUBLIC|PRIVATE) KEY-----(.+?)-----END/s) { } 2 2 4
elsif ($data =~ /---- BEGIN SSH2 PUBLIC KEY ----(.+?)---- END SSH2 PUBLIC KEY ----/s) { } 1 1 2
elsif ($data =~ /^\s*(\{.*?\})\s*$/s) { } 0 1 1
elsif ($data =~ /(ssh-ed25519)\s+(\S+)/) { } 1 0 1
elsif (length $data == 32) { } 0 0 0
67 0 return $self->_import_pem($data, $password);
68 }
69 elsif ($data =~ /-----BEGIN CERTIFICATE-----(.+?)-----END CERTIFICATE-----/s) {
70 0 return $self->_import_pem($data, undef);
71 }
72 elsif ($data =~ /-----BEGIN OPENSSH (PUBLIC|PRIVATE) KEY-----(.+?)-----END/s) {
73 2 return $self->_import_openssh($data, $password);
74 }
75 elsif ($data =~ /---- BEGIN SSH2 PUBLIC KEY ----(.+?)---- END SSH2 PUBLIC KEY ----/s) {
76 1 return $self->_import_openssh($data, undef);
77 }
78 elsif ($data =~ /^\s*(\{.*?\})\s*$/s) { # JSON
79 0 my $h = CryptX::_decode_json("$1");
80 0 ▶ if ($h->{kty} && $h->{kty} eq "OKP" && $h->{crv} && $h->{crv} eq 'Ed25519') {
Branch: 1 branch
BranchTrueFalseTotal
if ($h->{"kty"} and $h->{"kty"} eq "OKP" and $h->{"crv"} and $h->{"crv"} eq "Ed25519") 0 0 0
Condition0%0/9
$h->{"kty"} and $h->{"kty"} eq "OKP" and $h->{"crv"} and $h->{"crv"} eq "Ed25519"
!ll&&!rl&&r
000
$h->{"kty"} and $h->{"kty"} eq "OKP" and $h->{"crv"}
!ll&&!rl&&r
000
$h->{"kty"} and $h->{"kty"} eq "OKP"
!ll&&!rl&&r
000
MC/DC0%0/4
$h->{"kty"} and $h->{"kty"} eq "OKP" and $h->{"crv"} and $h->{"crv"} eq "Ed25519"
$h->{"kty"} $h->{"kty"} eq "OKP" $h->{"crv"} $h->{"crv"} eq "Ed25519"
Truth table0%0/5
A and B and C and D
A= $h->{"kty"}B= $h->{"kty"} eq "OKP"C= $h->{"crv"}D= $h->{"crv"} eq "Ed25519"
ABCDresult
0XXX0
10XX0
110X0
11100
11111
81 0 ▶ return $self->_import_raw(decode_b64u($h->{d}), 1) if $h->{d}; # private
Branch: 1 branch
BranchTrueFalseTotal
if $h->{"d"} 0 0 0
82 0 ▶ return $self->_import_raw(decode_b64u($h->{x}), 0) if $h->{x}; # public
Branch: 1 branch
BranchTrueFalseTotal
if $h->{"x"} 0 0 0
83 }
84 }
85 elsif ($data =~ /(ssh-ed25519)\s+(\S+)/) {
86 1 $data = decode_b64("$2");
87 1 my ($typ, $pubkey) = Crypt::PK::_ssh_parse($data);
88 1 ▶ return $self->_import_raw($pubkey, 0) if $typ eq 'ssh-ed25519' && length($pubkey) == 32;
Branch: 1 branch
BranchTrueFalseTotal
if $typ eq "ssh-ed25519" and length $pubkey == 32 1 0 1
Condition33%1/3
$typ eq "ssh-ed25519" and length $pubkey == 32
!ll&&!rl&&r
001
MC/DC0%0/2
$typ eq "ssh-ed25519" and length $pubkey == 32
$typ eq "ssh-ed25519" length $pubkey == 32
Truth table33%1/3
A and B
A= $typ eq "ssh-ed25519"B= length $pubkey == 32
ABresult
0X0
100
111
89 }
90 elsif (length($data) == 32) {
91 0 croak "FATAL: use import_key_raw() to load raw (32 bytes) Ed25519 key";
92 }
93 else {
94 0 my $rv = eval { $self->_import($data) } ||
95 0 eval { $self->_import_pkcs8($data, $password) } ||
96 0 ▶ eval { $self->_import_x509($data) };
Condition0%0/6
eval { do { $self->_import($data) } } || eval { do { $self->_import_pkcs8($data, $password) } } || eval { do { $self->_import_x509($data) } }
l!l&&r!l&&!r
000
eval { do { $self->_import($data) } } or eval { do { $self->_import_pkcs8($data, $password) } }
l!l&&r!l&&!r
000
MC/DC0%0/3
eval { do { $self->_import($data) } } || eval { do { $self->_import_pkcs8($data, $password) } } || eval { do { $self->_import_x509($data) } }
eval { do { $self->_import($data) } } eval { do { $self->_import_pkcs8($data, $password) } } eval { do { $self->_import_x509($data) } }
Truth table0%0/4
A or B || C
A= eval { do { $self->_import($data) } }B= eval { do { $self->_import_pkcs8($data, $password) } }C= eval { do { $self->_import_x509($data) } }
ABCresult
1XX1
01X1
0011
0000
97 0 ▶ return $rv if $rv;
Branch: 1 branch
BranchTrueFalseTotal
if $rv 0 0 0
98 }
99 0 croak "FATAL: invalid or unsupported Ed25519 key format";
100 }
101  
102 0 ▶sub export_key_pem {
Subroutine export_key_pem: not called CC=5 SCAR=34.0
Pod documented
103 0 my ($self, $type, $password, $cipher) = @_;
104 0 local $SIG{__DIE__} = \&CryptX::_croak;
105 0 ▶ my $key = $self->export_key_der($type||'');
Condition0%0/2
$type || ''
l!l
00
MC/DC0%0/1
$type || ''
$type
Truth table0%0/2
A
A= $type
Aresult
11
00
106 0 ▶ return unless $key;
Branch: 1 branch
BranchTrueFalseTotal
unless $key 0 0 0
107 0 ▶ return der_to_pem($key, "PRIVATE KEY", $password, $cipher) if $type eq 'private';
Branch: 1 branch
BranchTrueFalseTotal
if $type eq "private" 0 0 0
108 0 ▶ return der_to_pem($key, "PUBLIC KEY") if $type eq 'public';
Branch: 1 branch
BranchTrueFalseTotal
if $type eq "public" 0 0 0
109 }
110  
111 0 ▶sub export_key_jwk {
Subroutine export_key_jwk: not called CC=6 SCAR=37.4
Pod documented
112 0 my ($self, $type, $wanthash) = @_;
113 0 local $SIG{__DIE__} = \&CryptX::_croak;
114 0 my $kh = $self->key2hash;
115 0 ▶ return unless $kh;
Branch: 1 branch
BranchTrueFalseTotal
unless $kh 0 0 0
116 0 my $hash = { kty => "OKP", crv => "Ed25519" };
117 0 $hash->{x} = encode_b64u(pack("H*", $kh->{pub}));
118 0 ▶ $hash->{d} = encode_b64u(pack("H*", $kh->{priv})) if $type && $type eq 'private' && $kh->{priv};
Branch: 1 branch
BranchTrueFalseTotal
if $type and $type eq "private" and $kh->{"priv"} 0 0 0
Condition0%0/6
$type and $type eq "private" and $kh->{"priv"}
!ll&&!rl&&r
000
$type and $type eq "private"
!ll&&!rl&&r
000
MC/DC0%0/3
$type and $type eq "private" and $kh->{"priv"}
$type $type eq "private" $kh->{"priv"}
Truth table0%0/4
A and B and C
A= $typeB= $type eq "private"C= $kh->{"priv"}
ABCresult
0XX0
10X0
1100
1111
119 0 ▶ return $wanthash ? $hash : CryptX::_encode_json($hash);
Branch: 1 branch
BranchTrueFalseTotal
$wanthash ? : 0 0 0
120 }
121  
122 0 ▶sub CLONE_SKIP { 1 } # prevent cloning
Subroutine CLONE_SKIP: not called CC=1 SCAR=6.9
123  
124 4 1;
125  
126 =pod
127  
128 =head1 NAME
129  
130 Crypt::PK::Ed25519 - Digital signature based on Ed25519
131  
132 =head1 SYNOPSIS
133  
134 use Crypt::PK::Ed25519;
135  
136 my $message = 'hello world';
137 my $signer = Crypt::PK::Ed25519->new->generate_key;
138 my $signature = $signer->sign_message($message);
139  
140 my $public_der = $signer->export_key_der('public');
141 my $verifier = Crypt::PK::Ed25519->new(\$public_der);
142 $verifier->verify_message($signature, $message) or die "ERROR";
143  
144 #Load key
145 my $pk = Crypt::PK::Ed25519->new;
146 my $pk_hex = "A05D1AEA5830AC9A65CDFB384660D497E3697C46B419CF2CEC85DE8BD245459D";
147 $pk->import_key_raw(pack("H*", $pk_hex), "public");
148 my $sk = Crypt::PK::Ed25519->new;
149 my $sk_hex = "45C109BA6FD24E8B67D23EFB6B92D99CD457E2137172C0D749FE2B5A0C142DAD";
150 $sk->import_key_raw(pack("H*", $sk_hex), "private");
151  
152 #Key generation
153 my $pk = Crypt::PK::Ed25519->new->generate_key;
154 my $private_der = $pk->export_key_der('private');
155 my $public_der = $pk->export_key_der('public');
156 my $private_pem = $pk->export_key_pem('private');
157 my $public_pem = $pk->export_key_pem('public');
158 my $private_raw = $pk->export_key_raw('private');
159 my $public_raw = $pk->export_key_raw('public');
160 my $private_jwk = $pk->export_key_jwk('private');
161 my $public_jwk = $pk->export_key_jwk('public');
162  
163 =head1 DESCRIPTION
164  
165 I<Since: CryptX-0.067>
166  
167 =head1 METHODS
168  
169 =head2 new
170  
171 my $source = Crypt::PK::Ed25519->new();
172 $source->generate_key;
173  
174 my $public_der = $source->export_key_der('public');
175 my $pub = Crypt::PK::Ed25519->new(\$public_der);
176  
177 my $private_pem = $source->export_key_pem('private', 'secret', 'AES-256-CBC');
178 my $priv = Crypt::PK::Ed25519->new(\$private_pem, 'secret');
179  
180 Passing C<$filename> or C<\$buffer> to C<new> is equivalent: both forms
181 immediately import the key material into the new object.
182  
183 =head2 generate_key
184  
185 Uses the bundled C<chacha20> PRNG via C<rng_make_prng()>. The exact OS entropy
186 source is handled by the underlying LibTomCrypt RNG setup.
187 Returns the object itself (for chaining).
188  
189 $pk->generate_key;
190  
191 =head2 import_key
192  
193 Loads private or public key in DER or PEM format.
194  
195 my $source = Crypt::PK::Ed25519->new();
196 $source->generate_key;
197  
198 my $public_der = $source->export_key_der('public');
199 my $pub = Crypt::PK::Ed25519->new();
200 $pub->import_key(\$public_der);
201  
202 my $private_pem = $source->export_key_pem('private', 'secret', 'AES-256-CBC');
203 my $priv = Crypt::PK::Ed25519->new();
204 $priv->import_key(\$private_pem, 'secret');
205  
206 The same method also accepts filenames instead of buffers.
207  
208 Loading private or public keys from a Perl HASH:
209  
210 $pk->import_key($hashref);
211  
212 # the $hashref is either a key exported via key2hash
213 $pk->import_key({
214 curve => "ed25519",
215 pub => "A05D1AEA5830AC9A65CDFB384660D497E3697C46B419CF2CEC85DE8BD245459D",
216 priv => "45C109BA6FD24E8B67D23EFB6B92D99CD457E2137172C0D749FE2B5A0C142DAD",
217 });
218  
219 # or a hash with items corresponding to JWK (JSON Web Key)
220 $pk->import_key({
221 kty => "OKP",
222 crv => "Ed25519",
223 d => "RcEJum_STotn0j77a5LZnNRX4hNxcsDXSf4rWgwULa0",
224 x => "oF0a6lgwrJplzfs4RmDUl-NpfEa0Gc8s7IXei9JFRZ0",
225 });
226  
227 Supported key formats:
228  
229 # all formats can be loaded from a file
230 my $pk = Crypt::PK::Ed25519->new($filename);
231  
232 # or from a buffer containing the key
233 my $pk = Crypt::PK::Ed25519->new(\$buffer_with_key);
234  
235 =over
236  
237 =item * Ed25519 private keys in PEM format
238  
239 -----BEGIN ED25519 PRIVATE KEY-----
240 MC4CAQAwBQYDK2VwBCIEIEXBCbpv0k6LZ9I++2uS2ZzUV+ITcXLA10n+K1oMFC2t
241 -----END ED25519 PRIVATE KEY-----
242  
243 =item * Ed25519 private keys in password protected PEM format
244  
245 -----BEGIN ED25519 PRIVATE KEY-----
246 Proc-Type: 4,ENCRYPTED
247 DEK-Info: DES-CBC,6A64D756D49C1EFF
248  
249 8xQ7OyfQ10IITNEKcJGZA53Z1yk+NJQU7hrKqXwChZtgWNInhMBJRl9pozLKDSkH
250 v7u6EOve8NY=
251 -----END ED25519 PRIVATE KEY-----
252  
253 =item * PKCS#8 private keys
254  
255 -----BEGIN PRIVATE KEY-----
256 MC4CAQAwBQYDK2VwBCIEIEXBCbpv0k6LZ9I++2uS2ZzUV+ITcXLA10n+K1oMFC2t
257 -----END PRIVATE KEY-----
258  
259 =item * PKCS#8 encrypted private keys
260  
261 -----BEGIN ENCRYPTED PRIVATE KEY-----
262 MIGHMEsGCSqGSIb3DQEFDTA+MCkGCSqGSIb3DQEFDDAcBAjPx9JkdpRH2QICCAAw
263 DAYIKoZIhvcNAgkFADARBgUrDgMCBwQIWWieQojaWTcEOGj43SxqHUys4Eb2M27N
264 AkhqpmhosOxKrpGi0L3h8m8ipHE8EwI94NeOMsjfVw60aJuCrssY5vKN
265 -----END ENCRYPTED PRIVATE KEY-----
266  
267 =item * Ed25519 public keys in PEM format
268  
269 -----BEGIN PUBLIC KEY-----
270 MCowBQYDK2VwAyEAoF0a6lgwrJplzfs4RmDUl+NpfEa0Gc8s7IXei9JFRZ0=
271 -----END PUBLIC KEY-----
272  
273 =item * Ed25519 public key from X509 certificate
274  
275 -----BEGIN CERTIFICATE-----
276 MIIBODCB66ADAgECAhRWDU9FZBBUZ7KTdX8f7Bco8jsoaTAFBgMrZXAwETEPMA0G
277 A1UEAwwGQ3J5cHRYMCAXDTIwMDExOTEzMDIwMloYDzIyOTMxMTAyMTMwMjAyWjAR
278 MQ8wDQYDVQQDDAZDcnlwdFgwKjAFBgMrZXADIQCgXRrqWDCsmmXN+zhGYNSX42l8
279 RrQZzyzshd6L0kVFnaNTMFEwHQYDVR0OBBYEFHCGFtVibAxxWYyRt5wazMpqSZDV
280 MB8GA1UdIwQYMBaAFHCGFtVibAxxWYyRt5wazMpqSZDVMA8GA1UdEwEB/wQFMAMB
281 Af8wBQYDK2VwA0EAqG/+98smzqF/wmFX3zHXSaA67as202HnBJod1Tiurw1f+lr3
282 BX6OMtsDpgRq9O77IF1Qyx/MdJEwwErczOIbAA==
283 -----END CERTIFICATE-----
284  
285 =item * SSH public Ed25519 keys
286  
287 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0XsiFcRDp6Hpsoak8OdiiBMJhM2UKszNTxoGS7dJ++
288  
289 =item * SSH public Ed25519 keys (RFC-4716 format)
290  
291 ---- BEGIN SSH2 PUBLIC KEY ----
292 Comment: "256-bit ED25519, converted from OpenSSH"
293 AAAAC3NzaC1lZDI1NTE5AAAAIL0XsiFcRDp6Hpsoak8OdiiBMJhM2UKszNTxoGS7dJ++
294 ---- END SSH2 PUBLIC KEY ----
295  
296 =item * Ed25519 private keys in JSON Web Key (JWK) format
297  
298 See L<https://www.rfc-editor.org/rfc/rfc8037>
299  
300 {
301 "kty":"OKP",
302 "crv":"Ed25519",
303 "x":"oF0a6lgwrJplzfs4RmDUl-NpfEa0Gc8s7IXei9JFRZ0",
304 "d":"RcEJum_STotn0j77a5LZnNRX4hNxcsDXSf4rWgwULa0",
305 }
306  
307 B<BEWARE:> For JWK support you need to have L<JSON> module installed.
308  
309 =item * Ed25519 public keys in JSON Web Key (JWK) format
310  
311 {
312 "kty":"OKP",
313 "crv":"Ed25519",
314 "x":"oF0a6lgwrJplzfs4RmDUl-NpfEa0Gc8s7IXei9JFRZ0",
315 }
316  
317 B<BEWARE:> For JWK support you need to have L<JSON> module installed.
318  
319 =back
320  
321 =head2 import_key_raw
322  
323 Import raw public/private key - can load raw key data exported by L</export_key_raw>.
324  
325 $pk->import_key_raw($key, 'public');
326 $pk->import_key_raw($key, 'private');
327  
328 =head2 export_key_der
329  
330 Returns the key as a binary DER-encoded string.
331  
332 my $private_der = $pk->export_key_der('private');
333 #or
334 my $public_der = $pk->export_key_der('public');
335  
336 =head2 export_key_pem
337  
338 Returns the key as a PEM-encoded string (ASCII).
339  
340 my $private_pem = $pk->export_key_pem('private');
341 #or
342 my $public_pem = $pk->export_key_pem('public');
343  
344 Support for password protected PEM keys
345  
346 my $private_pem = $pk->export_key_pem('private', $password);
347 #or
348 my $private_pem = $pk->export_key_pem('private', $password, $cipher);
349  
350 # supported ciphers: 'DES-CBC'
351 # 'DES-EDE3-CBC'
352 # 'SEED-CBC'
353 # 'CAMELLIA-128-CBC'
354 # 'CAMELLIA-192-CBC'
355 # 'CAMELLIA-256-CBC'
356 # 'AES-128-CBC'
357 # 'AES-192-CBC'
358 # 'AES-256-CBC' (DEFAULT)
359  
360 =head2 export_key_jwk
361  
362 Returns a JSON string, or a hashref if the optional second argument is true.
363  
364 Exports public/private keys as a JSON Web Key (JWK).
365  
366 my $private_json_text = $pk->export_key_jwk('private');
367 #or
368 my $public_json_text = $pk->export_key_jwk('public');
369  
370 Also exports public/private keys as a Perl HASH with JWK structure.
371  
372 my $jwk_hash = $pk->export_key_jwk('private', 1);
373 #or
374 my $jwk_hash = $pk->export_key_jwk('public', 1);
375  
376 B<BEWARE:> For JWK support you need to have L<JSON> module installed.
377  
378 =head2 export_key_raw
379  
380 Returns the raw key as a binary string.
381  
382 Export raw public/private key
383  
384 my $private_bytes = $pk->export_key_raw('private');
385 #or
386 my $public_bytes = $pk->export_key_raw('public');
387  
388 =head2 sign_message
389  
390 Returns the signature as a binary string. Ed25519 uses a fixed hash internally
391 (SHA-512); unlike RSA or ECDSA there is no C<$hash_name> parameter.
392  
393 my $signature = $priv->sign_message($message);
394  
395 =head2 verify_message
396  
397 Returns C<1> if the signature is valid, C<0> otherwise.
398  
399 my $valid = $pub->verify_message($signature, $message);
400  
401 =head2 sign_message_ctx
402  
403 I<Since: CryptX-0.089>
404  
405 Signs a message using Ed25519ctx (RFC 8032 Section 5.1), which includes a
406 mandatory context string (at most 255 bytes). The context string makes the
407 signature domain-separated: the same key signing the same message with a
408 different context produces a different (and incompatible) signature.
409  
410 my $signature = $priv->sign_message_ctx($message, $context);
411  
412 =head2 verify_message_ctx
413  
414 I<Since: CryptX-0.089>
415  
416 Verifies a signature produced by L</sign_message_ctx>.
417  
418 my $valid = $pub->verify_message_ctx($signature, $message, $context);
419  
420 =head2 sign_message_ph
421  
422 I<Since: CryptX-0.089>
423  
424 Signs a message using Ed25519ph (RFC 8032 Section 5.1), the "pre-hashed"
425 variant. The message is first hashed with SHA-512 internally before signing.
426 This is useful when signing very large messages or when only a hash of the
427 message is available. An optional context string (at most 255 bytes) can be
428 provided; it defaults to the empty string if omitted.
429  
430 my $signature = $priv->sign_message_ph($message);
431 my $signature = $priv->sign_message_ph($message, $context);
432  
433 =head2 verify_message_ph
434  
435 I<Since: CryptX-0.089>
436  
437 Verifies a signature produced by L</sign_message_ph>.
438  
439 my $valid = $pub->verify_message_ph($signature, $message);
440 my $valid = $pub->verify_message_ph($signature, $message, $context);
441  
442 =head2 is_private
443  
444 my $rv = $pk->is_private;
445 # 1 .. private key loaded
446 # 0 .. public key loaded
447 # undef .. no key loaded
448  
449 =head2 key2hash
450  
451 Returns a hashref with the key components, or C<undef> if no key is loaded.
452  
453 my $hash = $pk->key2hash;
454  
455 # returns hash like this (or undef if no key loaded):
456 {
457 curve => "ed25519",
458 # raw public key as a hexadecimal string
459 pub => "A05D1AEA5830AC9A65CDFB384660D497E3697C46B419CF2CEC85DE8BD245459D",
460 # raw private key as a hexadecimal string. undef if key is public only
461 priv => "45C109BA6FD24E8B67D23EFB6B92D99CD457E2137172C0D749FE2B5A0C142DAD",
462 }
463  
464 =head1 OpenSSL interoperability
465  
466 # Generate a key with OpenSSL
467 # openssl genpkey -algorithm ed25519 -out ed25519_priv.pem
468 # openssl pkey -in ed25519_priv.pem -pubout -out ed25519_pub.pem
469  
470 # Load the OpenSSL-generated key in CryptX
471 use Crypt::PK::Ed25519;
472 my $priv = Crypt::PK::Ed25519->new("ed25519_priv.pem");
473 my $pub = Crypt::PK::Ed25519->new("ed25519_pub.pem");
474  
475 # Sign in CryptX, verify with OpenSSL
476 my $message = "hello";
477 my $signature = $priv->sign_message($message);
478  
479 # Export CryptX key for OpenSSL
480 my $pem = $priv->export_key_pem('private');
481 # then: openssl pkey -in priv.pem -text -noout
482  
483 =head1 SEE ALSO
484  
485 =over
486  
487 =item * L<https://en.wikipedia.org/wiki/EdDSA#Ed25519>
488  
489 =item * L<https://en.wikipedia.org/wiki/Curve25519>
490  
491 =item * L<https://www.rfc-editor.org/rfc/rfc8032>
492  
493 =back
494  
495 =cut
« blib/lib/Crypt/PK/X448.pm ↑ Summary blib/lib/Crypt/PK/RSA.pm »