File Coverage

blib/lib/Crypt/PK/ECC.pm

Criterion	Covered	Total	%
statement	98	146	67.1
branch	47	116	40.5
condition	11	63	17.4
subroutine	19	22	86.3
pod	6	13	46.1
total	181	360	50.2

package Crypt::PK::ECC;

use strict;
use warnings;
our $VERSION = '0.088_004';

require Exporter; our @ISA = qw(Exporter); ### use Exporter 5.57 'import';
our %EXPORT_TAGS = ( all => [qw( ecc_encrypt ecc_decrypt ecc_sign_message ecc_verify_message ecc_sign_hash ecc_verify_hash ecc_shared_secret )] );
our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
our @EXPORT = qw();

use Carp;
$Carp::Internal{(__PACKAGE__)}++;
use CryptX;
use Crypt::Digest qw(digest_data digest_data_b64u);
use Crypt::Misc qw(read_rawfile encode_b64u decode_b64u encode_b64 decode_b64 pem_to_der der_to_pem);
use Crypt::PK;

our %curve = ( # must be "our" as we use it from XS code
  # extra curves not recognized by libtomcrypt
  'wap-wsg-idm-ecid-wtls8' => {
        prime      => "FFFFFFFFFFFFFFFFFFFFFFFFFDE7",
        A          => "0000000000000000000000000000",
        B          => "0000000000000000000000000003",
        order      => "0100000000000001ECEA551AD837E9",
        Gx         => "0000000000000000000000000001",
        Gy         => "0000000000000000000000000002",
        cofactor   => 1,
        oid        => '2.23.43.1.4.8',
  },
  'wap-wsg-idm-ecid-wtls9' => {
        prime      => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC808F",
        A          => "0000000000000000000000000000000000000000",
        B          => "0000000000000000000000000000000000000003",
        order      => "0100000000000000000001CDC98AE0E2DE574ABF33",
        Gx         => "0000000000000000000000000000000000000001",
        Gy         => "0000000000000000000000000000000000000002",
        cofactor   => 1,
        oid        => '2.23.43.1.4.9',
  },
  # some unusual openssl names
  "wap-wsg-idm-ecid-wtls6"  => 'secp112r1',
  "wap-wsg-idm-ecid-wtls7"  => 'secp160r2',
  "wap-wsg-idm-ecid-wtls12" => 'secp224r1',
  # extra aliases
  'P-256K'                  => 'secp256k1',
);

our %curve_oid2name = ( # must be "our" as we use it from XS code
  # the following are used to derive curve_name from OID in key2hash()
  "1.2.840.10045.3.1.1"   => "secp192r1",
  "1.2.840.10045.3.1.2"   => "prime192v2",
  "1.2.840.10045.3.1.3"   => "prime192v3",
  "1.2.840.10045.3.1.4"   => "prime239v1",
  "1.2.840.10045.3.1.5"   => "prime239v2",
  "1.2.840.10045.3.1.6"   => "prime239v3",
  "1.2.840.10045.3.1.7"   => "secp256r1",
  "1.3.132.0.6"           => "secp112r1",
  "1.3.132.0.7"           => "secp112r2",
  "1.3.132.0.8"           => "secp160r1",
  "1.3.132.0.9"           => "secp160k1",
  "1.3.132.0.10"          => "secp256k1",
  "1.3.132.0.28"          => "secp128r1",
  "1.3.132.0.29"          => "secp128r2",
  "1.3.132.0.30"          => "secp160r2",
  "1.3.132.0.31"          => "secp192k1",
  "1.3.132.0.32"          => "secp224k1",
  "1.3.132.0.33"          => "secp224r1",
  "1.3.132.0.34"          => "secp384r1",
  "1.3.132.0.35"          => "secp521r1",
  "1.3.36.3.3.2.8.1.1.1"  => "brainpoolp160r1",
  "1.3.36.3.3.2.8.1.1.2"  => "brainpoolp160t1",
  "1.3.36.3.3.2.8.1.1.3"  => "brainpoolp192r1",
  "1.3.36.3.3.2.8.1.1.4"  => "brainpoolp192t1",
  "1.3.36.3.3.2.8.1.1.5"  => "brainpoolp224r1",
  "1.3.36.3.3.2.8.1.1.6"  => "brainpoolp224t1",
  "1.3.36.3.3.2.8.1.1.7"  => "brainpoolp256r1",
  "1.3.36.3.3.2.8.1.1.8"  => "brainpoolp256t1",
  "1.3.36.3.3.2.8.1.1.9"  => "brainpoolp320r1",
  "1.3.36.3.3.2.8.1.1.10" => "brainpoolp320t1",
  "1.3.36.3.3.2.8.1.1.11" => "brainpoolp384r1",
  "1.3.36.3.3.2.8.1.1.12" => "brainpoolp384t1",
  "1.3.36.3.3.2.8.1.1.13" => "brainpoolp512r1",
  "1.3.36.3.3.2.8.1.1.14" => "brainpoolp512t1",
);

my %curve2jwk = (
  # necessary for conversion of curve_name_or_OID >> P-NNN
  '1.2.840.10045.3.1.1' => 'P-192', # secp192r1
  '1.3.132.0.33'        => 'P-224', # secp224r1
  '1.2.840.10045.3.1.7' => 'P-256', # secp256r1
  '1.3.132.0.10'        => 'P-256K',# secp256k1
  '1.3.132.0.34'        => 'P-384', # secp384r1
  '1.3.132.0.35'        => 'P-521', # secp521r1
  'nistp192'            => 'P-192',
  'nistp224'            => 'P-224',
  'nistp256'            => 'P-256',
  'nistp384'            => 'P-384',
  'nistp521'            => 'P-521',
  'prime192v1'          => 'P-192',
  'prime256v1'          => 'P-256',
  'secp192r1'           => 'P-192',
  'secp224r1'           => 'P-224',
  'secp256r1'           => 'P-256',
  'secp256k1'           => 'P-256K',
  'secp384r1'           => 'P-384',
  'secp521r1'           => 'P-521',
);

sub _import_hex {
  my ($self, $x, $y, $k, $crv) = @_;
  croak "FATAL: no curve" if !$crv;
  if (defined $k && length($k) > 0) {
    croak "FATAL: invalid length (k)" if length($k) % 2;
    return $self->import_key_raw(pack("H*", $k), $crv);
  }
  elsif (defined $x && defined $y) {
    croak "FATAL: invalid length (x)"   if length($x) % 2;
    croak "FATAL: invalid length (y)"   if length($y) % 2;
    croak "FATAL: invalid length (x,y)" if length($y) != length($x);
    my $pub_hex = "04" . $x . $y;
    return $self->import_key_raw(pack("H*", $pub_hex), $crv);
  }
}

sub new {
  my $self = shift->_new();
  return @_ > 0 ? $self->import_key(@_) : $self;
}

sub export_key_pem {
  my ($self, $type, $password, $cipher) = @_;
  local $SIG{__DIE__} = \&CryptX::_croak;
  my $key = $self->export_key_der($type||'');
  return unless $key;
  # private, private_short, private_compressed all use the same PEM header
  return der_to_pem($key, "EC PRIVATE KEY", $password, $cipher) if $type =~ /\Aprivate(?:_short|_compressed)?\z/;
  # public, public_short, public_compressed all use the same PEM header
  return der_to_pem($key, "PUBLIC KEY") if $type =~ /\Apublic(?:_short|_compressed)?\z/;
}

sub export_key_jwk {
  my ($self, $type, $wanthash) = @_;
  local $SIG{__DIE__} = \&CryptX::_croak;
  my $kh = $self->key2hash;
  $kh->{curve_oid}  = '' if !defined $kh->{curve_oid};
  $kh->{curve_name} = '' if !defined $kh->{curve_name};
  my $curve_jwt = $curve2jwk{$kh->{curve_oid}} || $curve2jwk{lc $kh->{curve_name}} || $kh->{curve_name};
  if ($type && $type eq 'private') {
    return unless $kh->{pub_x} && $kh->{pub_y} && $kh->{k};
    for (qw/pub_x pub_y k/) {
      $kh->{$_} = "0$kh->{$_}" if length($kh->{$_}) % 2;
    }
    # NOTE: x + y are not necessary in privkey
    # but they are used in https://www.rfc-editor.org/rfc/rfc7517#appendix-A.2
    my $hash = {
      kty => "EC", crv => $curve_jwt,
      x => encode_b64u(pack("H*", $kh->{pub_x})),
      y => encode_b64u(pack("H*", $kh->{pub_y})),
      d => encode_b64u(pack("H*", $kh->{k})),
    };
    return $wanthash ? $hash : CryptX::_encode_json($hash);
  }
  elsif ($type && $type eq 'public') {
    return unless $kh->{pub_x} && $kh->{pub_y};
    for (qw/pub_x pub_y/) {
      $kh->{$_} = "0$kh->{$_}" if length($kh->{$_}) % 2;
    }
    my $hash = {
      kty => "EC", crv => $curve_jwt,
      x => encode_b64u(pack("H*", $kh->{pub_x})),
      y => encode_b64u(pack("H*", $kh->{pub_y})),
    };
    return $wanthash ? $hash : CryptX::_encode_json($hash);
  }
}

sub export_key_jwk_thumbprint {
  my ($self, $hash_name) = @_;
  local $SIG{__DIE__} = \&CryptX::_croak;
  $hash_name ||= 'SHA256';
  my $h = $self->export_key_jwk('public', 1);
  my $json = CryptX::_encode_json({crv=>$h->{crv}, kty=>$h->{kty}, x=>$h->{x}, y=>$h->{y}});
  return digest_data_b64u($hash_name, $json);
}

sub import_key {
  my ($self, $key, $password) = @_;
  local $SIG{__DIE__} = \&CryptX::_croak;
  croak "FATAL: undefined key" unless $key;

  # special case
  if (ref($key) eq 'HASH') {
    if (($key->{pub_x} && $key->{pub_y}) || $key->{k}) {
      # hash exported via key2hash
      my $curve_name = $key->{curve_name} || $key->{curve_oid};
      return $self->_import_hex($key->{pub_x}, $key->{pub_y}, $key->{k}, $curve_name);
    }
    if ($key->{crv} && $key->{kty} && $key->{kty} eq "EC" && ($key->{d} || ($key->{x} && $key->{y}))) {
      # hash with items corresponding to JSON Web Key (JWK)
      $key = {%$key}; # make a copy as we will modify it
      for (qw/x y d/) {
        $key->{$_} = eval { unpack("H*", decode_b64u($key->{$_})) } if exists $key->{$_};
      }
      # names P-192 P-224 P-256 P-384 P-521 are recognized by libtomcrypt
      return $self->_import_hex($key->{x}, $key->{y}, $key->{d}, $key->{crv});
    }
    croak "FATAL: unexpected ECC key hash";
  }

  my $data;
  if (ref($key) eq 'SCALAR') {
    $data = $$key;
  }
  elsif (-f $key) {
    $data = read_rawfile($key);
  }
  else {
    croak "FATAL: non-existing file '$key'";
  }
  croak "FATAL: invalid key data" unless $data;

  if ($data =~ /(-----BEGIN (PUBLIC|EC PRIVATE|PRIVATE|ENCRYPTED PRIVATE) KEY-----(.+?)-----END (PUBLIC|EC PRIVATE|PRIVATE|ENCRYPTED PRIVATE) KEY-----)/s) {
    my $pem = $1;
    my $rv = eval { $self->_import_pem($pem, $password) } || eval { $self->_import_old(pem_to_der($pem, $password)) };
    return $rv if $rv;
  }
  elsif ($data =~ /-----BEGIN CERTIFICATE-----(.+?)-----END CERTIFICATE-----/s) {
    return $self->_import_pem($data, undef);
  }
  elsif ($data =~ /-----BEGIN OPENSSH PRIVATE KEY-----(.+?)-----END OPENSSH PRIVATE KEY-----/s) {
    return $self->_import_openssh($data, $password);
  }
  elsif ($data =~ /---- BEGIN SSH2 PUBLIC KEY ----(.+?)---- END SSH2 PUBLIC KEY ----/s) {
    return $self->_import_openssh($data, undef);
  }
  elsif ($data =~ /(ecdsa-\S+)\s+(\S+)/) {
    $data = decode_b64("$2");
    my ($typ, $skip, $pubkey) = Crypt::PK::_ssh_parse($data);
    return $self->import_key_raw($pubkey, "$2") if $pubkey && $typ =~ /^ecdsa-(.+?)-(.*)$/;
  }
  elsif ($data =~ /^\s*(\{.*?\})\s*$/s) {
    # JSON Web Key (JWK) - https://www.rfc-editor.org/rfc/rfc7517
    my $json = "$1";
    my $h = CryptX::_decode_json($json) || {};
    if ($h->{kty} eq "EC") {
      $h->{x} = eval { unpack("H*", decode_b64u($h->{x})) } if exists $h->{x};
      $h->{y} = eval { unpack("H*", decode_b64u($h->{y})) } if exists $h->{y};
      $h->{d} = eval { unpack("H*", decode_b64u($h->{d})) } if exists $h->{d};
      # names P-192 P-224 P-256 P-384 P-521 are recognized by libtomcrypt
      return $self->_import_hex($h->{x}, $h->{y}, $h->{d}, $h->{crv});
    }
  }
  else {
    my $rv = eval { $self->_import($data) }                  ||
             eval { $self->_import_old($data) }              ||
             eval { $self->_import_pkcs8($data, $password) } ||
             eval { $self->_import_x509($data) };
    return $rv if $rv;
  }
  croak "FATAL: invalid or unsupported EC key format";
}

sub curve2hash {
  my $self = shift;
  my $kh = $self->key2hash;
  return {
     prime    => $kh->{curve_prime},
     A        => $kh->{curve_A},
     B        => $kh->{curve_B},
     Gx       => $kh->{curve_Gx},
     Gy       => $kh->{curve_Gy},
     cofactor => $kh->{curve_cofactor},
     order    => $kh->{curve_order},
     oid      => $kh->{curve_oid},
  };
}

### FUNCTIONS

sub ecc_encrypt { # legacy/obsolete
  my $key = shift;
  local $SIG{__DIE__} = \&CryptX::_croak;
  $key = __PACKAGE__->new($key) unless ref $key;
  croak "FATAL: invalid 'key' param" unless ref($key) eq __PACKAGE__;
  return $key->encrypt(@_);
}

sub ecc_decrypt { # legacy/obsolete
  my $key = shift;
  local $SIG{__DIE__} = \&CryptX::_croak;
  $key = __PACKAGE__->new($key) unless ref $key;
  croak "FATAL: invalid 'key' param" unless ref($key) eq __PACKAGE__;
  return $key->decrypt(@_);
}

sub ecc_sign_message { # legacy/obsolete
  my $key = shift;
  local $SIG{__DIE__} = \&CryptX::_croak;
  $key = __PACKAGE__->new($key) unless ref $key;
  croak "FATAL: invalid 'key' param" unless ref($key) eq __PACKAGE__;
  return $key->sign_message(@_);
}

sub ecc_verify_message { # legacy/obsolete
  my $key = shift;
  local $SIG{__DIE__} = \&CryptX::_croak;
  $key = __PACKAGE__->new($key) unless ref $key;
  croak "FATAL: invalid 'key' param" unless ref($key) eq __PACKAGE__;
  return $key->verify_message(@_);
}

sub ecc_sign_hash { # legacy/obsolete
  my $key = shift;
  local $SIG{__DIE__} = \&CryptX::_croak;
  $key = __PACKAGE__->new($key) unless ref $key;
  croak "FATAL: invalid 'key' param" unless ref($key) eq __PACKAGE__;
  return $key->sign_hash(@_);
}

sub ecc_verify_hash { # legacy/obsolete
  my $key = shift;
  local $SIG{__DIE__} = \&CryptX::_croak;
  $key = __PACKAGE__->new($key) unless ref $key;
  croak "FATAL: invalid 'key' param" unless ref($key) eq __PACKAGE__;
  return $key->verify_hash(@_);
}

sub ecc_shared_secret { # legacy/obsolete
  my ($privkey, $pubkey) = @_;
  local $SIG{__DIE__} = \&CryptX::_croak;
  $privkey = __PACKAGE__->new($privkey) unless ref $privkey;
  $pubkey  = __PACKAGE__->new($pubkey)  unless ref $pubkey;
  croak "FATAL: invalid 'privkey' param" unless ref($privkey) eq __PACKAGE__ && $privkey->is_private;
  croak "FATAL: invalid 'pubkey' param"  unless ref($pubkey)  eq __PACKAGE__;
  return $privkey->shared_secret($pubkey);
}

sub CLONE_SKIP { 1 } # prevent cloning

1;

=pod

=head1 NAME

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

=head1 SYNOPSIS

 ### OO interface

 my $message = 'hello world';
 my $alice = Crypt::PK::ECC->new();
 $alice->generate_key('secp256r1');
 my $alice_public_der = $alice->export_key_der('public');
 my $alice_public = Crypt::PK::ECC->new(\$alice_public_der);

 my $ciphertext = $alice_public->encrypt($message);
 my $plaintext = $alice->decrypt($ciphertext);

 my $signature = $alice->sign_message($message);
 $alice_public->verify_message($signature, $message) or die "ERROR";

 my $bob = Crypt::PK::ECC->new();
 $bob->generate_key('secp256r1');
 my $bob_public_der = $bob->export_key_der('public');
 my $bob_public = Crypt::PK::ECC->new(\$bob_public_der);

 my $alice_secret = $alice->shared_secret($bob_public);
 my $bob_secret = $bob->shared_secret($alice_public);

 my $private_der = $alice->export_key_der('private');
 my $public_pem = $alice_public->export_key_pem('public');
 my $public_raw = $alice_public->export_key_raw('public');

=head1 DESCRIPTION

The module provides a set of core ECC functions as well as implementation of ECDSA and ECDH.

Supports elliptic curves C over prime fields C (binary fields not supported).

Legacy function-style wrappers still exist in code for backwards compatibility,
but they are intentionally undocumented.

=head1 METHODS

=head2 new

 my $pk = Crypt::PK::ECC->new();
 #or
 my $source = Crypt::PK::ECC->new();
 $source->generate_key('secp256r1');

 my $public_der = $source->export_key_der('public');
 my $pub = Crypt::PK::ECC->new(\$public_der);

 my $private_pem = $source->export_key_pem('private', 'secret', 'AES-256-CBC');
 my $priv = Crypt::PK::ECC->new(\$private_pem, 'secret');

Passing C<$filename> or C<\$buffer> to C is equivalent: both forms
immediately import the key material into the new object.

=head2 generate_key

Uses Yarrow-based cryptographically strong random number generator seeded with
random data taken from C (UNIX) or C (Win32).
Returns the object itself (for chaining).

 $pk->generate_key($curve_name);
 #or
 $pk->generate_key($hashref_with_curve_params);

The following predefined C<$curve_name> values are supported:

 # curves from https://www.rfc-editor.org/rfc/rfc5639
 'brainpoolp160r1'
 'brainpoolp192r1'
 'brainpoolp224r1'
 'brainpoolp256r1'
 'brainpoolp320r1'
 'brainpoolp384r1'
 'brainpoolp512r1'
 # curves from https://www.secg.org/sec2-v2.pdf
 'secp112r1'
 'secp112r2'
 'secp128r1'
 'secp128r2'
 'secp160k1'
 'secp160r1'
 'secp160r2'
 'secp192k1'
 'secp192r1'   ... same as nistp192, prime192v1
 'secp224k1'
 'secp224r1'   ... same as nistp224
 'secp256k1'   ... used by Bitcoin
 'secp256r1'   ... same as nistp256, prime256v1
 'secp384r1'   ... same as nistp384
 'secp521r1'   ... same as nistp521
 #curves from https://csrc.nist.gov/pubs/fips/186-4/final
 'nistp192'    ... same as secp192r1, prime192v1
 'nistp224'    ... same as secp224r1
 'nistp256'    ... same as secp256r1, prime256v1
 'nistp384'    ... same as secp384r1
 'nistp521'    ... same as secp521r1
 # curves from ANS X9.62
 'prime192v1'   ... same as nistp192, secp192r1
 'prime192v2'
 'prime192v3'
 'prime239v1'
 'prime239v2'
 'prime239v3'
 'prime256v1'   ... same as nistp256, secp256r1

Using custom curve parameters:

 $pk->generate_key({ prime    => 'FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFF',
                     A        => 'FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFC',
                     B        => '22123DC2395A05CAA7423DAECCC94760A7D462256BD56916',
                     Gx       => '7D29778100C65A1DA1783716588DCE2B8B4AEE8E228F1896',
                     Gy       => '38A90F22637337334B49DCB66A6DC8F9978ACA7648A943B0',
                     order    => 'FFFFFFFFFFFFFFFFFFFFFFFF7A62D031C83F4294F640EC13',
                     cofactor => 1 });

See L,
L,
L

=head2 import_key

Loads private or public key in DER or PEM format.

 my $source = Crypt::PK::ECC->new();
 $source->generate_key('secp256r1');

 my $public_der = $source->export_key_der('public');
 my $pub = Crypt::PK::ECC->new();
 $pub->import_key(\$public_der);

 my $private_pem = $source->export_key_pem('private', 'secret', 'AES-256-CBC');
 my $priv = Crypt::PK::ECC->new();
 $priv->import_key(\$private_pem, 'secret');

The same method also accepts filenames instead of buffers.

Loading private or public keys form perl hash:

 $pk->import_key($hashref);

 # the $hashref is either a key exported via key2hash
 $pk->import_key({
      curve_A        => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFC",
      curve_B        => "1C97BEFC54BD7A8B65ACF89F81D4D4ADC565FA45",
      curve_bits     => 160,
      curve_bytes    => 20,
      curve_cofactor => 1,
      curve_Gx       => "4A96B5688EF573284664698968C38BB913CBFC82",
      curve_Gy       => "23A628553168947D59DCC912042351377AC5FB32",
      curve_order    => "0100000000000000000001F4C8F927AED3CA752257",
      curve_prime    => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFF",
      k              => "B0EE84A749FE95DF997E33B8F333E12101E824C3",
      pub_x          => "5AE1ACE3ED0AEA9707CE5C0BCE014F6A2F15023A",
      pub_y          => "895D57E992D0A15F88D6680B27B701F615FCDC0F",
 });

 # or with the curve defined just by name
 $pk->import_key({
      curve_name => "secp160r1",
      k          => "B0EE84A749FE95DF997E33B8F333E12101E824C3",
      pub_x      => "5AE1ACE3ED0AEA9707CE5C0BCE014F6A2F15023A",
      pub_y      => "895D57E992D0A15F88D6680B27B701F615FCDC0F",
 });

 # or a hash with items corresponding to JWK (JSON Web Key)
 $pk->import_key({
       kty => "EC",
       crv => "P-256",
       x   => "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
       y   => "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
       d   => "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE",
 });

Supported key formats:

 # all formats can be loaded from a file
 my $pk = Crypt::PK::ECC->new($filename);

 # or from a buffer containing the key
 my $pk = Crypt::PK::ECC->new(\$buffer_with_key);

=over

=item * EC private keys with with all curve parameters

 -----BEGIN EC PRIVATE KEY-----
 MIIB+gIBAQQwCKEAcA6cIt6CGfyLKm57LyXWv2PgTjydrHSbvhDJTOl+7bzUW8DS
 rgSdtSPONPq1oIIBWzCCAVcCAQEwPAYHKoZIzj0BAQIxAP//////////////////
 ///////////////////////+/////wAAAAAAAAAA/////zB7BDD/////////////
 /////////////////////////////v////8AAAAAAAAAAP////wEMLMxL6fiPufk
 mI4Fa+P4LRkYHZxu/oFBEgMUCI9QE4daxlY5jYou0Z0qhcjt0+wq7wMVAKM1kmqj
 GaJ6HQCJamdzpIJ6zaxzBGEEqofKIr6LBTeOscce8yCtdG4dO2KLp5uYWfdB4IJU
 KjhVAvJdv1UpbDpUXjhydgq3NhfeSpYmLG9dnpi/kpLcKfj0Hb0omhR86doxE7Xw
 uMAKYLHOHX6BnXpDHXyQ6g5fAjEA////////////////////////////////x2NN
 gfQ3Ld9YGg2ySLCneuzsGWrMxSlzAgEBoWQDYgAEeGyHPLmHcszPQ9MIIYnznpzi
 QbvuJtYSjCqtIGxDfzgcLcc3nCc5tBxo+qX6OJEzcWdDAC0bwplY+9Z9jHR3ylNy
 ovlHoK4ItdWkVO8NH89SLSRyVuOF8N5t3CHIo93B
 -----END EC PRIVATE KEY-----

=item * EC private keys with curve defined by OID (short form)

 -----BEGIN EC PRIVATE KEY-----
 MHcCAQEEIBG1c3z52T8XwMsahGVdOZWgKCQJfv+l7djuJjgetdbDoAoGCCqGSM49
 AwEHoUQDQgAEoBUyo8CQAFPeYPvv78ylh5MwFZjTCLQeb042TjiMJxG+9DLFmRSM
 lBQ9T/RsLLc+PmpB1+7yPAR+oR5gZn3kJQ==
 -----END EC PRIVATE KEY-----

=item * EC private keys with curve defined by OID + compressed form (supported since: CryptX-0.059)

 -----BEGIN EC PRIVATE KEY-----
 MFcCAQEEIBG1c3z52T8XwMsahGVdOZWgKCQJfv+l7djuJjgetdbDoAoGCCqGSM49
 AwEHoSQDIgADoBUyo8CQAFPeYPvv78ylh5MwFZjTCLQeb042TjiMJxE=
 -----END EC PRIVATE KEY-----

=item * EC private keys in password protected PEM format

 -----BEGIN EC PRIVATE KEY-----
 Proc-Type: 4,ENCRYPTED
 DEK-Info: AES-128-CBC,98245C830C9282F7937E13D1D5BA11EC

 0Y85oZ2+BKXYwrkBjsZdj6gnhOAfS5yDVmEsxFCDug+R3+Kw3QvyIfO4MVo9iWoA
 D7wtoRfbt2OlBaLVl553+6QrUoa2DyKf8kLHQs1x1/J7tJOMM4SCXjlrOaToQ0dT
 o7fOnjQjHne16pjgBVqGilY/I79Ab85AnE4uw7vgEucBEiU0d3nrhwuS2Opnhzyx
 009q9VLDPwY2+q7tXjTqnk9mCmQgsiaDJqY09wlauSukYPgVuOJFmi1VdkRSDKYZ
 rUUsQvz6Q6Q+QirSlfHna+NhUgQ2eyhGszwcP6NU8iqIxI+NCwfFVuAzw539yYwS
 8SICczoC/YRlaclayXuomQ==
 -----END EC PRIVATE KEY-----

=item * EC public keys with all curve parameters

 -----BEGIN PUBLIC KEY-----
 MIH1MIGuBgcqhkjOPQIBMIGiAgEBMCwGByqGSM49AQECIQD/////////////////
 ///////////////////+///8LzAGBAEABAEHBEEEeb5mfvncu6xVoGKVzocLBwKb
 /NstzijZWfKBWxb4F5hIOtp3JqPEZV2k+/wOEQio/Re0SKaFVBmcR9CP+xDUuAIh
 AP////////////////////66rtzmr0igO7/SXozQNkFBAgEBA0IABITjF/nKK3jg
 pjmBRXKWAv7ekR1Ko/Nb5FFPHXjH0sDrpS7qRxFALwJHv7ylGnekgfKU3vzcewNs
 lvjpBYt0Yg4=
 -----END PUBLIC KEY-----

=item * EC public keys with curve defined by OID (short form)

 -----BEGIN PUBLIC KEY-----
 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEoBUyo8CQAFPeYPvv78ylh5MwFZjT
 CLQeb042TjiMJxG+9DLFmRSMlBQ9T/RsLLc+PmpB1+7yPAR+oR5gZn3kJQ==
 -----END PUBLIC KEY-----

=item * EC public keys with curve defined by OID + public point in compressed form (supported since: CryptX-0.059)

 -----BEGIN PUBLIC KEY-----
 MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADoBUyo8CQAFPeYPvv78ylh5MwFZjT
 CLQeb042TjiMJxE=
 -----END PUBLIC KEY-----

=item * PKCS#8 private keys with all curve parameters

 -----BEGIN PRIVATE KEY-----
 MIIBMAIBADCB0wYHKoZIzj0CATCBxwIBATAkBgcqhkjOPQEBAhkA////////////
 /////////v//////////MEsEGP////////////////////7//////////AQYIhI9
 wjlaBcqnQj2uzMlHYKfUYiVr1WkWAxUAxGloRDXes3jEtlypWR4qV2MFmi4EMQR9
 KXeBAMZaHaF4NxZYjc4ri0rujiKPGJY4qQ8iY3M3M0tJ3LZqbcj5l4rKdkipQ7AC
 GQD///////////////96YtAxyD9ClPZA7BMCAQEEVTBTAgEBBBiKolTGIsTgOCtl
 6dpdos0LvuaExCDFyT6hNAMyAAREwaCX0VY1LZxLW3G75tmft4p9uhc0J7/+NGaP
 DN3Tr7SXkT9+co2a+8KPJhQy10k=
 -----END PRIVATE KEY-----

=item * PKCS#8 private keys with curve defined by OID (short form)

 -----BEGIN PRIVATE KEY-----
 MG8CAQAwEwYHKoZIzj0CAQYIKoZIzj0DAQMEVTBTAgEBBBjFP/caeQV4WO3fnWWS
 f917PGzwtypd/t+hNAMyAATSg6pBT7RO6l/p+aKcrFsGuthUdfwJWS5V3NGcVt1b
 lEHQYjWya2YnHaPq/iMFa7A=
 -----END PRIVATE KEY-----

=item * PKCS#8 encrypted private keys - password protected keys (supported since: CryptX-0.059)

 -----BEGIN ENCRYPTED PRIVATE KEY-----
 MIGYMBwGCiqGSIb3DQEMAQMwDgQINApjTa6oFl0CAggABHi+59l4d4e6KtG9yci2
 BSC65LEsQSnrnFAExfKptNU1zMFsDLCRvDeDQDbxc6HlfoxyqFL4SmH1g3RvC/Vv
 NfckdL5O2L8MRnM+ljkFtV2Te4fszWcJFdd7KiNOkPpn+7sWLfzQdvhHChLKUzmz
 4INKZyMv/G7VpZ0=
 -----END ENCRYPTED PRIVATE KEY-----

=item * EC public key from X509 certificate

 -----BEGIN CERTIFICATE-----
 MIIBdDCCARqgAwIBAgIJAL2BBClDEnnOMAoGCCqGSM49BAMEMBcxFTATBgNVBAMM
 DFRlc3QgQ2VydCBFQzAgFw0xNzEyMzAyMDMzNDFaGA8zMDE3MDUwMjIwMzM0MVow
 FzEVMBMGA1UEAwwMVGVzdCBDZXJ0IEVDMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE
 KvkL2r5xZp7RzxLQJK+6tn/7lic+L70e1fmNbHOdxRaRvbK5G0AQWrdsbjJb92Ni
 lCQk2+w/i+VuS2Q3MSR5TaNQME4wHQYDVR0OBBYEFGbJkDyKgaMcIGHS8/WuqIVw
 +R8sMB8GA1UdIwQYMBaAFGbJkDyKgaMcIGHS8/WuqIVw+R8sMAwGA1UdEwQFMAMB
 Af8wCgYIKoZIzj0EAwQDSAAwRQIhAJtOsmrM+gJpImoynAyqTN+7myL71uxd+YeC
 6ze4MnzWAiBQi5/BqEr/SQ1+BC2TPtswvJPRFh2ZvT/6Km3gKoNVXQ==
 -----END CERTIFICATE-----

=item * SSH public EC keys

 ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNT...T3xYfJIs=

=item * SSH public EC keys (RFC-4716 format)

 ---- BEGIN SSH2 PUBLIC KEY ----
 Comment: "521-bit ECDSA, converted from OpenSSH"
 AAAAE2VjZHNhLXNoYTItbmlzdHA1MjEAAAAIbmlzdHA1MjEAAACFBAFk35srteP9twCwYK
 vU9ovMBi77Dd6lEBPrFaMEb0CZdZ5MC3nSqflGHRWkSbUpjdPdO7cYQNpK9YXHbNSO5hbU
 1gFZgyiGFxwJYYz8NAjedBXMgyH4JWplK5FQm5P5cvaglItC9qkKioUXhCc67YMYBtivXl
 Ue0PgIq6kbHTqbX6+5Nw==
 ---- END SSH2 PUBLIC KEY ----

=item * EC private keys in JSON Web Key (JWK) format

See L

 {
  "kty":"EC",
  "crv":"P-256",
  "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
  "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
  "d":"870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE",
 }

B For JWK support you need to have L module installed.

=item * EC public keys in JSON Web Key (JWK) format

 {
  "kty":"EC",
  "crv":"P-256",
  "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
  "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
 }

B For JWK support you need to have L module installed.

=back

=head2 import_key_raw

Import raw public/private key - can load data exported by L.

 $pk->import_key_raw($key, $curve);
 # $key .... [binary string] data exported by export_key_raw()
 # $curve .. [string | hashref] curve name or hashref with curve parameters - same as by generate_key()

=head2 export_key_der

Returns the key as a binary DER-encoded string.

 my $private_der = $pk->export_key_der('private');
 #or
 my $public_der = $pk->export_key_der('public');

Since CryptX-0.36 C can also export keys in a format
that does not explicitly contain curve parameters but only curve OID.

 my $private_der = $pk->export_key_der('private_short');
 #or
 my $public_der = $pk->export_key_der('public_short');

Since CryptX-0.59 C can also export keys in "compressed" format
that defines curve by OID + stores public point in compressed form.

 my $private_pem = $pk->export_key_der('private_compressed');
 #or
 my $public_pem = $pk->export_key_der('public_compressed');

=head2 export_key_pem

Returns the key as a PEM-encoded string (ASCII).

 my $private_pem = $pk->export_key_pem('private');
 #or
 my $public_pem = $pk->export_key_pem('public');

Since CryptX-0.36 C can also export keys in a format
that does not explicitly contain curve parameters but only curve OID.

 my $private_pem = $pk->export_key_pem('private_short');
 #or
 my $public_pem = $pk->export_key_pem('public_short');

Since CryptX-0.59 C can also export keys in "compressed" format
that defines curve by OID + stores public point in compressed form.

 my $private_pem = $pk->export_key_pem('private_compressed');
 #or
 my $public_pem = $pk->export_key_pem('public_compressed');

Support for password protected PEM keys

 my $private_pem = $pk->export_key_pem('private', $password);
 #or
 my $private_pem = $pk->export_key_pem('private', $password, $cipher);

 # supported ciphers: 'DES-CBC'
 #                    'DES-EDE3-CBC'
 #                    'SEED-CBC'
 #                    'CAMELLIA-128-CBC'
 #                    'CAMELLIA-192-CBC'
 #                    'CAMELLIA-256-CBC'
 #                    'AES-128-CBC'
 #                    'AES-192-CBC'
 #                    'AES-256-CBC' (DEFAULT)

=head2 export_key_jwk

I

Returns a JSON string, or a hashref if the optional second argument is true.

Exports public/private keys as a JSON Web Key (JWK).

 my $private_json_text = $pk->export_key_jwk('private');
 #or
 my $public_json_text = $pk->export_key_jwk('public');

Also exports public/private keys as a perl HASH with JWK structure.

 my $jwk_hash = $pk->export_key_jwk('private', 1);
 #or
 my $jwk_hash = $pk->export_key_jwk('public', 1);

B For JWK support you need to have L module installed.

=head2 export_key_jwk_thumbprint

I

Exports the key's JSON Web Key Thumbprint as a string.

If you don't know what this is, see RFC 7638 L.

 my $thumbprint = $pk->export_key_jwk_thumbprint('SHA256');

=head2 export_key_raw

Returns the raw key as a binary string.

Export raw public/private key. Public key is exported in ASN X9.62 format (compressed or uncompressed),
private key is exported as raw bytes (padded with leading zeros to have the same size as the ECC curve).

 my $pubkey_octets  = $pk->export_key_raw('public');
 #or
 my $pubckey_octets = $pk->export_key_raw('public_compressed');
 #or
 my $privkey_octets = $pk->export_key_raw('private');

=head2 encrypt

Returns the ciphertext as a binary string.

 my $pk = Crypt::PK::ECC->new($pub_key_filename);
 my $ct = $pk->encrypt($message);
 #or
 my $ct = $pk->encrypt($message, $hash_name);

 # $hash_name .. [string] 'SHA1' (DEFAULT), 'SHA256' or any other hash supported by Crypt::Digest

=head2 decrypt

Returns the plaintext as a binary string.

 my $pk = Crypt::PK::ECC->new($priv_key_filename);
 my $pt = $pk->decrypt($ciphertext);

=head2 sign_message

Returns the signature as a binary string.

 my $pk = Crypt::PK::ECC->new($priv_key_filename);
 my $signature = $pk->sign_message($message);
 #or
 my $signature = $pk->sign_message($message, $hash_name);

 # $hash_name .. [string] 'SHA1' (DEFAULT), 'SHA256' or any other hash supported by Crypt::Digest

=head2 sign_message_rfc7518

I

Same as L only the signature format is as defined by L
(JWA - JSON Web Algorithms).

B This creates signatures according to the structure that RFC 7518 describes but does not apply
the RFC logic for the hashing algorithm selection. You'll still need to specify, e.g., SHA256 for a P-256 key
to get a fully RFC-7518-compliant signature.

=head2 verify_message

Returns C<1> if the signature is valid, C<0> otherwise.

 my $pk = Crypt::PK::ECC->new($pub_key_filename);
 my $valid = $pk->verify_message($signature, $message);
 #or
 my $valid = $pk->verify_message($signature, $message, $hash_name);

 # $hash_name .. [string] 'SHA1' (DEFAULT), 'SHA256' or any other hash supported by Crypt::Digest

=head2 verify_message_rfc7518

I

Same as L only the signature format is as defined by L
(JWA - JSON Web Algorithms).

B This verifies signatures according to the structure that RFC 7518 describes but does not apply
the RFC logic for the hashing algorithm selection. You'll still need to specify, e.g., SHA256 for a P-256 key
to get a fully RFC-7518-compliant signature.

=head2 sign_hash

Returns the signature as a binary string.

 my $pk = Crypt::PK::ECC->new($priv_key_filename);
 my $signature = $pk->sign_hash($message_hash, $deterministic_hash_name);

 # $deterministic_hash_name .. [string] 'SHA1', 'SHA256' or any other hash supported by Crypt::Digest
 #      in most cases it will be the same as used to create $message_hash, if not provided non-deterministic
 #      signature will be created

I

=head2 sign_hash_eth

Same as L but returns the signature in Ethereum format:
32-byte C value, 32-byte C value, 1-byte recovery ID (27 or 28). Total
output is always exactly 65 bytes.

=head2 sign_hash_rfc7518

I

Same as L only the signature format is as defined by L
(JWA - JSON Web Algorithms).

=head2 verify_hash

Returns C<1> if the signature is valid, C<0> otherwise.

 my $pk = Crypt::PK::ECC->new($pub_key_filename);
 my $valid = $pk->verify_hash($signature, $message_hash);

=head2 verify_hash_rfc7518

I

Same as L only the signature format is as defined by L
(JWA - JSON Web Algorithms).

=head2 verify_hash_eth

Returns C<1> if the signature is valid, C<0> otherwise.
Same as L but expects the signature in Ethereum format
(65 bytes: r || s || recovery_id).
Compatible with signatures generated by L.

=head2 recovery_pub_eth

Alternative method to verify a signature with recovery of the public key.
Mainly used in Ethereum-like blockchain networks.
This method will recover public key from ECDSA signature in Ethereum format
(see L).

 my $pk = Crypt::PK::ECC->new($priv_key_filename);
 my $signature = $pk->sign_hash_eth($message_hash);
 my $pub_key = $pk->recovery_pub_eth($signature, $message_hash);

=head2 recovery_pub

Recovers the public key from an ECDSA signature produced by L.
Returns a new L object containing the recovered public key.

Unlike L, the standard DER-encoded signature does not embed
the recovery identifier, so C<$recid> must be supplied explicitly.

 my $pk = Crypt::PK::ECC->new($priv_key_filename);
 my $signature = $pk->sign_hash($message_hash);
 my $pub_key = $pk->recovery_pub($signature, $message_hash, $recid);

 # $signature .... [binary string] binary DER-encoded ECDSA signature (from sign_hash)
 # $message_hash . [binary string] the hash that was signed
 # $recid ........ [integer] recovery identifier, 0 or 1 (selects which of the
 #                 two possible public keys corresponds to the signature)

=head2 recovery_pub_rfc7518

I

Same logic as recovery_pub_eth except, but compatible with L
signature. The main difference that B<$recid> is required, because rfc7518 signature
doesn't contain parity bit, so you need to specify it explicitly.

 my $pk = Crypt::PK::ECC->new($priv_key_filename);
 my $signature = $pk->sign_hash_rfc7518($message_hash);
 my $pub_key = $pk->recovery_pub_rfc7518($signature, $message_hash, $recid);

=head2 shared_secret

Returns the shared secret as a binary string (raw bytes).

  # Alice having her priv key $pk and Bob's public key $pkb
  my $pk  = Crypt::PK::ECC->new($priv_key_filename);
  my $pkb = Crypt::PK::ECC->new($pub_key_filename);
  my $shared_secret = $pk->shared_secret($pkb);

  # Bob having his priv key $pk and Alice's public key $pka
  my $pk = Crypt::PK::ECC->new($priv_key_filename);
  my $pka = Crypt::PK::ECC->new($pub_key_filename);
  my $shared_secret = $pk->shared_secret($pka);  # same value as computed by Alice

=head2 is_private

 my $rv = $pk->is_private;
 # 1 .. private key loaded
 # 0 .. public key loaded
 # undef .. no key loaded

=head2 size

 my $size = $pk->size;
 # returns key size in bytes or undef if no key loaded

=head2 key2hash

Returns a hashref with the key components, or C if no key is loaded.

 my $hash = $pk->key2hash;

 # returns hash like this (or undef if no key loaded):
 {
   size           => 20, # integer: key (curve) size in bytes
   type           => 1,  # integer: 1 .. private, 0 .. public
   #curve parameters
   curve_A        => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFC",
   curve_B        => "1C97BEFC54BD7A8B65ACF89F81D4D4ADC565FA45",
   curve_bits     => 160,
   curve_bytes    => 20,
   curve_cofactor => 1,
   curve_Gx       => "4A96B5688EF573284664698968C38BB913CBFC82",
   curve_Gy       => "23A628553168947D59DCC912042351377AC5FB32",
   curve_name     => "secp160r1",
   curve_order    => "0100000000000000000001F4C8F927AED3CA752257",
   curve_prime    => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFF",
   #private key
   k              => "B0EE84A749FE95DF997E33B8F333E12101E824C3",
   #public key point coordinates
   pub_x          => "5AE1ACE3ED0AEA9707CE5C0BCE014F6A2F15023A",
   pub_y          => "895D57E992D0A15F88D6680B27B701F615FCDC0F",
 }

=head2 curve2hash

I

 my $crv = $pk->curve2hash;

 # returns a hash that can be passed to: $pk->generate_key($crv)
 {
   A        => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFC",
   B        => "1C97BEFC54BD7A8B65ACF89F81D4D4ADC565FA45",
   cofactor => 1,
   Gx       => "4A96B5688EF573284664698968C38BB913CBFC82",
   Gy       => "23A628553168947D59DCC912042351377AC5FB32",
   order    => "0100000000000000000001F4C8F927AED3CA752257",
   prime    => "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFF",
 }

=head1 OpenSSL interoperability

 ### let's have:
 # ECC private key in PEM format - eckey.priv.pem
 # ECC public key in PEM format  - eckey.pub.pem
 # data file to be signed - input.data

=head2 Sign by OpenSSL, verify by Crypt::PK::ECC

Create signature (from commandline):

 openssl dgst -sha1 -sign eckey.priv.pem -out input.sha1-ec.sig input.data

Verify signature (Perl code):

 use Crypt::PK::ECC;
 use Crypt::Digest 'digest_file';
 use Crypt::Misc 'read_rawfile';

 my $pkec = Crypt::PK::ECC->new("eckey.pub.pem");
 my $signature = read_rawfile("input.sha1-ec.sig");
 my $valid = $pkec->verify_hash($signature, digest_file("SHA1", "input.data"));
 print $valid ? "SUCCESS" : "FAILURE";

=head2 Sign by Crypt::PK::ECC, verify by OpenSSL

Create signature (Perl code):

 use Crypt::PK::ECC;
 use Crypt::Digest 'digest_file';
 use Crypt::Misc 'write_rawfile';

 my $pkec = Crypt::PK::ECC->new("eckey.priv.pem");
 my $signature = $pkec->sign_hash(digest_file("SHA1", "input.data"));
 write_rawfile("input.sha1-ec.sig", $signature);

Verify signature (from commandline):

 openssl dgst -sha1 -verify eckey.pub.pem -signature input.sha1-ec.sig input.data

=head2 Keys generated by Crypt::PK::ECC

Generate keys (Perl code):

 use Crypt::PK::ECC;
 use Crypt::Misc 'write_rawfile';

 my $pkec = Crypt::PK::ECC->new;
 $pkec->generate_key('secp160k1');
 write_rawfile("eckey.pub.der",  $pkec->export_key_der('public'));
 write_rawfile("eckey.priv.der", $pkec->export_key_der('private'));
 write_rawfile("eckey.pub.pem",  $pkec->export_key_pem('public'));
 write_rawfile("eckey.priv.pem", $pkec->export_key_pem('private'));
 write_rawfile("eckey-passwd.priv.pem", $pkec->export_key_pem('private', 'secret'));

Use keys by OpenSSL:

 openssl ec -in eckey.priv.der -text -inform der
 openssl ec -in eckey.priv.pem -text
 openssl ec -in eckey-passwd.priv.pem -text -inform pem -passin pass:secret
 openssl ec -in eckey.pub.der -pubin -text -inform der
 openssl ec -in eckey.pub.pem -pubin -text

=head2 Keys generated by OpenSSL

Generate keys:

 openssl ecparam -param_enc explicit -name prime192v3 -genkey -out eckey.priv.pem
 openssl ec -param_enc explicit -in eckey.priv.pem -out eckey.pub.pem -pubout
 openssl ec -param_enc explicit -in eckey.priv.pem -out eckey.priv.der -outform der
 openssl ec -param_enc explicit -in eckey.priv.pem -out eckey.pub.der -outform der -pubout
 openssl ec -param_enc explicit -in eckey.priv.pem -out eckey.privc.der -outform der -conv_form compressed
 openssl ec -param_enc explicit -in eckey.priv.pem -out eckey.pubc.der -outform der -pubout -conv_form compressed
 openssl ec -param_enc explicit -in eckey.priv.pem -passout pass:secret -des3 -out eckey-passwd.priv.pem

Load keys (Perl code):

 use Crypt::PK::ECC;

 my $pkec = Crypt::PK::ECC->new;
 $pkec->import_key("eckey.pub.der");
 $pkec->import_key("eckey.pubc.der");
 $pkec->import_key("eckey.priv.der");
 $pkec->import_key("eckey.privc.der");
 $pkec->import_key("eckey.pub.pem");
 $pkec->import_key("eckey.priv.pem");
 $pkec->import_key("eckey-passwd.priv.pem", "secret");

=head1 SEE ALSO

=over

=item * L

=item * L

=item * L

=back

=cut