NAME

Crypt::MagicSignatures::Key - MagicKeys for the Salmon Protocol

SYNOPSIS

  use Crypt::MagicSignatures::Key;

  my $mkey = Crypt::MagicSignatures::Key->new('RSA.mVgY...');

  my $sig = $mkey->sign('This is a message');

  if ($mkey->verify('This is a message', $sig) {
    print "The signature is valid for ' . $mkey->to_string;
  };

DESCRIPTION

Crypt::MagicSignatures::Key implements MagicKeys as described in the MagicSignatures Specification to sign messages of the Salmon Protocol. MagicSignatures is a "robust mechanism for digitally signing nearly arbitrary messages". See Crypt::MagicSignatures::Envelope for using MagicKeys to sign MagicEnvelopes.

This module is an early release! There may be significant changes in the future.

ATTRIBUTES

n

  print $mkey->n;
  $mkey->n('456789...');

The MagicKey modulus.

e

  print $mkey->e;
  $mkey->e(3);

The MagicKey public exponent. Defaults to 65537.

d

  print $mkey->d;
  $mkey->d('234567...');

The MagicKey private exponent.

size

  print $mkey->size;

The MagicKey keysize in bits.

METHODS

new

  my $mkey = Crypt::MagicSignatures::Key->new(<<'MKEY');
    RSA.
    mVgY8RN6URBTstndvmUUPb4UZTdwvw
    mddSKE5z_jvKUEK6yk1u3rrC9yN8k6
    FilGj9K0eeUPe2hf4Pj-5CmHww==.
    AQAB.
    Lgy_yL3hsLBngkFdDw1Jy9TmSRMiH6
    yihYetQ8jy-jZXdsZXd8V5ub3kuBHH
    k4M39i3TduIkcrjcsiWQb77D8Q==
  MKEY

  $mkey = Crypt::MagicSignatures::Key->new(
    n => '13145688881420345...',
    d => '87637925876135637...',
    e => 3
  );

  $mkey = Crypt::MagicSignatures::Key->new(size => 1024);

The Constructor accepts MagicKeys in compact notation as described in the MagicSignatures Specification or by attributes.

If no n attribute is given and Math::Prime::Util and Math::Random::Secure are installed, a new key will be generated. In case no size attribute is given, the default key size for generation is 512 bits.

sign

  my $sig = $mkey->sign('This is a message');

Signs a message and returns the signature. The key needs to be a private key. The signature algorithm is based on RFC3447.

verify

  my $sig = $priv_key->sign('This is a message');

  # Successfully verify signature
  if ($pub_key->verify('This is a message', $sig) {
    print "The signature is okay.";
  }

  # Fail to verify signature
  else {
    print "The signature is wrong!";
  };

Verifies a signature of a message based on the public component of the key. Returns a true value on success and false otherwise.

to_string

  my $pub_key = $mkey->to_string;
  my $priv_key = $mkey->to_string(1);

Returns the public key as a string in compact notation as described in the MagicSignatures Specification.

If a true value is passed to the method, the full key (including the private exponent if existing) is returned.

FUNCTIONS

b64url_encode

  use Crypt::MagicSignatures::Key qw/b64url_encode/;

  print b64url_encode('This is a message');
  print b64url_encode('This is a message', 0);

Encodes a string as base-64 with URL safe characters. A second parameter indicates, if trailing equal signs are wanted. The default is true. This differs from encode_base64 in MIME::Base64. The function can be exported.

b64url_decode

  use Crypt::MagicSignatures::Key qw/b64url_decode/;

  print b64url_decode('VGhpcyBpcyBhIG1lc3NhZ2U=');

Decodes a base-64 string with URL safe characters. The function can be exported.

DEPENDENCIES

Core modules: Carp, Digest::SHA, Exporter, Math::BigInt, MIME::Base64.

Math::Prime::Util and Math::Random::Secure are necessary for key generation only.

Either Math::BigInt::GMP (preferred) or Math::BigInt::Pari are recommended for speed, as well as Math::Random::ISAAC::XS.

KNOWN BUGS AND LIMITATIONS

The signing and verifification is not guaranteed to be compatible with other implementations!

SEE ALSO

Crypt::MagicSignatures::Envelope, Crypt::RSA::DataFormat, https://github.com/sivy/Salmon.

AVAILABILITY

  https://github.com/Akron/Crypt-MagicSignatures-Key

COPYRIGHT AND LICENSE

Copyright (C) 2012-2013, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the same terms as Perl.

cpanm Crypt::MagicSignatures::Key

perl -MCPAN -e shell
install Crypt::MagicSignatures::Key