view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

[![testsuite](https://github.com/cpan-authors/Crypt-OpenSSL-RSA/actions/workflows/testsuite.yml/badge.svg)](https://github.com/cpan-authors/Crypt-OpenSSL-RSA/actions/workflows/testsuite.yml)

# NAME

Crypt::OpenSSL::RSA - RSA encoding and decoding, using the openSSL libraries

# SYNOPSIS

    use Crypt::OpenSSL::Random;
    use Crypt::OpenSSL::RSA;

    # not necessary if we have /dev/random:
    Crypt::OpenSSL::Random::random_seed($good_entropy);
    Crypt::OpenSSL::RSA->import_random_seed();
    $rsa_pub = Crypt::OpenSSL::RSA->new_public_key($key_string);
    $ciphertext = $rsa->encrypt($plaintext);

    $rsa_priv = Crypt::OpenSSL::RSA->new_private_key($key_string);
    $plaintext = $rsa->decrypt($ciphertext);

    $rsa = Crypt::OpenSSL::RSA->generate_key(1024); # or
    $rsa = Crypt::OpenSSL::RSA->generate_key(1024, $prime);

    print "private key is:\n", $rsa->get_private_key_string();
    print "public key (in PKCS1 format) is:\n",
          $rsa->get_public_key_string();
    print "public key (in X509 format) is:\n",
          $rsa->get_public_key_x509_string();

    $rsa_priv->use_md5_hash(); # insecure. use_sha256_hash or use_sha1_hash are the default
    $signature = $rsa_priv->sign($plaintext);
    print "Signed correctly\n" if ($rsa->verify($plaintext, $signature));

# SECURITY

Version 0.35 disabled PKCS#1 v1.5 padding entirely to mitigate the Marvin
attack.  However, the Marvin attack only affects PKCS#1 v1.5 **decryption**
(padding oracle), not **signatures**.  Version 0.38 re-enables
`use_pkcs1_padding()` for use with `sign()` and `verify()`, while keeping
it disabled for `encrypt()` and `decrypt()`.  PKCS1\_OAEP should be used
for encryption and either PKCS1\_PSS or PKCS1 can be used for signing.

# DESCRIPTION

`Crypt::OpenSSL::RSA` provides the ability to RSA encrypt strings which are
somewhat shorter than the block size of a key.  It also allows for decryption,
signatures and signature verification.

_NOTE_: Many of the methods in this package can croak, so use `eval`, or
Error.pm's try/catch mechanism to capture errors.  Also, while some
methods from earlier versions of this package return true on success,
this (never documented) behavior is no longer the case.

# Class Methods

- new\_public\_key

    Create a new `Crypt::OpenSSL::RSA` object by loading a public key in
    from a string containing either PEM or DER encoding of the PKCS#1 or
    X.509 representation of the key.

    For PEM keys, the string should include the `-----BEGIN...-----` and
    `-----END...-----` lines.  Both `BEGIN RSA PUBLIC KEY` (PKCS#1) and
    `BEGIN PUBLIC KEY` (X.509/SubjectPublicKeyInfo) formats are supported.

    DER-encoded keys (raw binary ASN.1) are also accepted and the format
    (PKCS#1 vs X.509) is auto-detected.

    The padding is set to PKCS1\_OAEP, but can be changed with the
    `use_xxx_padding` methods.

    Note, PKCS1\_OAEP can only be used for encryption.  Call
    `use_pkcs1_pss_padding` or `use_pkcs1_padding` prior to signing operations.

- new\_private\_key

    Create a new `Crypt::OpenSSL::RSA` object by loading a private key in
    from a string containing either PEM or DER encoding of the key.

    For PEM keys, the string should include the `-----BEGIN...-----` and
    `-----END...-----` lines.  The padding is set to PKCS1\_OAEP, but can
    be changed with `use_xxx_padding`.

    DER-encoded keys (raw binary ASN.1) are also accepted.

README.md  view on Meta::CPAN

- get\_public\_key\_string

    Return the Base64/DER-encoded PKCS1 representation of the public
    key.  This string has
    header and footer lines:

        -----BEGIN RSA PUBLIC KEY------
        -----END RSA PUBLIC KEY------

- get\_public\_key\_pkcs1\_string

    Alias for `get_public_key_string`.  Returns the same PKCS#1
    `RSAPublicKey` PEM format (`BEGIN RSA PUBLIC KEY`).  Provided for
    naming symmetry with the import method `new_public_key` (which
    auto-detects PKCS#1 vs X.509) and with `get_public_key_x509_string`.

- get\_public\_key\_x509\_string

    Return the Base64/DER-encoded representation of the "subject
    public key", suitable for use in X509 certificates.  This string has
    header and footer lines:

        -----BEGIN PUBLIC KEY------
        -----END PUBLIC KEY------

    and is the format that is produced by running `openssl rsa -pubout`.

- get\_private\_key\_string

    Return the Base64/DER-encoded PKCS1 representation of the private
    key.  This string has
    header and footer lines:

        -----BEGIN RSA PRIVATE KEY------
        -----END RSA PRIVATE KEY------

    2 optional parameters can be passed for passphrase protected private key
    string:

    - passphrase

        The passphrase which protects the private key.

    - cipher name

        The cipher algorithm used to protect the private key. Default to
        'des3'.

- get\_private\_key\_pkcs8\_string

    Return the Base64/DER-encoded PKCS#8 representation of the private
    key.  This string has header and footer lines:

        -----BEGIN PRIVATE KEY-----
        -----END PRIVATE KEY-----

    This is the format produced by `openssl pkey -outform PEM`, and is
    the private-key counterpart of `get_public_key_x509_string`.

    Accepts the same optional passphrase and cipher-name parameters as
    `get_private_key_string`.

- encrypt

    Encrypt a binary "string" using the public (portion of the) key.

- decrypt

    Decrypt a binary "string".  Croaks if the key is public only.

- private\_encrypt

    Encrypt a binary "string" using the private key.  Croaks if the key is
    public only.  On OpenSSL 3.x, only `use_no_padding` and
    `use_pkcs1_padding` are supported; OAEP and PSS will croak.

- public\_decrypt

    Decrypt a binary "string" using the public (portion of the) key.
    On OpenSSL 3.x, only `use_no_padding` and `use_pkcs1_padding`
    are supported; OAEP and PSS will croak.

- sign

    Sign a string using the secret (portion of the) key.

- verify

    Check the signature on a text.

# Padding Methods

**use\_pkcs1\_padding** can be used for signature operations (`sign()` and
`verify()`).  PKCS#1 v1.5 encryption is disabled due to the Marvin attack.
**use\_pkcs1\_pss\_padding** is the recommended replacement for signatures.
**use\_pkcs1\_oaep\_padding** is used for encryption operations.

On OpenSSL 3.x, the appropriate padding is set for each operation unless
**use\_no\_padding** or **use\_pkcs1\_padding** is called before the operation.

- use\_no\_padding

    Use raw RSA encryption. This mode should only be used to implement
    cryptographically sound padding modes in the application code.
    Encrypting user data directly with RSA is insecure.

- use\_pkcs1\_padding

    Use `PKCS #1 v1.5` padding for **signature operations only**.  PKCS#1 v1.5
    signatures (RSASSA-PKCS1-v1.5) are secure and widely required by protocols
    such as JWT RS256, ACME (RFC 8555), and SAML.

    **Note**: PKCS#1 v1.5 **encryption** is disabled because it is vulnerable to
    the [Marvin Attack](https://github.com/tomato42/marvin-toolkit/blob/master/README.md)
    (a timing side-channel on decryption padding validation).  Calling
    `encrypt()` or `decrypt()` with this padding will croak.  Use
    `use_pkcs1_oaep_padding()` for encryption.

- use\_pkcs1\_oaep\_padding

    Use `EME-OAEP` padding as defined in PKCS #1 v2.0 with SHA-1, MGF1 and