Crate rsa

source ·
Expand description

RSA Implementation in pure Rust.

It supports several schemes described in RFC8017:

  • OAEP encryption scheme
  • PKCS#1 v1.5 encryption scheme
  • PKCS#1 v1.5 signature scheme
  • PSS signature scheme

These schemes are described below.

Usage

PKCS#1 v1.5 encryption

use rsa::{PublicKey, RsaPrivateKey, RsaPublicKey, PaddingScheme};

let mut rng = rand::thread_rng();

let bits = 2048;
let private_key = RsaPrivateKey::new(&mut rng, bits).expect("failed to generate a key");
let public_key = RsaPublicKey::from(&private_key);

// Encrypt
let data = b"hello world";
let padding = PaddingScheme::new_pkcs1v15_encrypt();
let enc_data = public_key.encrypt(&mut rng, padding, &data[..]).expect("failed to encrypt");
assert_ne!(&data[..], &enc_data[..]);

// Decrypt
let padding = PaddingScheme::new_pkcs1v15_encrypt();
let dec_data = private_key.decrypt(padding, &enc_data).expect("failed to decrypt");
assert_eq!(&data[..], &dec_data[..]);

OAEP encryption

use rsa::{PublicKey, RsaPrivateKey, RsaPublicKey, PaddingScheme};

let mut rng = rand::thread_rng();

let bits = 2048;
let private_key = RsaPrivateKey::new(&mut rng, bits).expect("failed to generate a key");
let public_key = RsaPublicKey::from(&private_key);

// Encrypt
let data = b"hello world";
let padding = PaddingScheme::new_oaep::<sha2::Sha256>();
let enc_data = public_key.encrypt(&mut rng, padding, &data[..]).expect("failed to encrypt");
assert_ne!(&data[..], &enc_data[..]);

// Decrypt
let padding = PaddingScheme::new_oaep::<sha2::Sha256>();
let dec_data = private_key.decrypt(padding, &enc_data).expect("failed to decrypt");
assert_eq!(&data[..], &dec_data[..]);

PKCS#1 v1.5 signatures

use rsa::RsaPrivateKey;
use rsa::pkcs1v15::{SigningKey, VerifyingKey};
use rsa::signature::{RandomizedSigner, Signature, Verifier};
use sha2::{Digest, Sha256};

let mut rng = rand::thread_rng();

let bits = 2048;
let private_key = RsaPrivateKey::new(&mut rng, bits).expect("failed to generate a key");
let signing_key = SigningKey::<Sha256>::new_with_prefix(private_key);
let verifying_key: VerifyingKey<_> = (&signing_key).into();

// Sign
let data = b"hello world";
let signature = signing_key.sign_with_rng(&mut rng, data);
assert_ne!(signature.as_bytes(), data);

// Verify
verifying_key.verify(data, &signature).expect("failed to verify");

PSS signatures

use rsa::RsaPrivateKey;
use rsa::pss::{BlindedSigningKey, VerifyingKey};
use rsa::signature::{RandomizedSigner, Signature, Verifier};
use sha2::{Digest, Sha256};

let mut rng = rand::thread_rng();

let bits = 2048;
let private_key = RsaPrivateKey::new(&mut rng, bits).expect("failed to generate a key");
let signing_key = BlindedSigningKey::<Sha256>::new(private_key);
let verifying_key: VerifyingKey<_> = (&signing_key).into();

// Sign
let data = b"hello world";
let signature = signing_key.sign_with_rng(&mut rng, data);
assert_ne!(signature.as_bytes(), data);

// Verify
verifying_key.verify(data, &signature).expect("failed to verify");

PKCS#1 RSA Key Encoding

PKCS#1 supports a legacy format for encoding RSA keys as binary (DER) or text (PEM) data.

You can recognize PEM encoded PKCS#1 keys because they have “RSA * KEY” in the type label, e.g.:

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

Most modern applications use the newer PKCS#8 format instead (see below).

The following traits can be used to decode/encode RsaPrivateKey and RsaPublicKey as PKCS#1. Note that pkcs1 is re-exported from the toplevel of the rsa crate:

Example

use rsa::{RsaPublicKey, pkcs1::DecodeRsaPublicKey};

let pem = "-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEAtsQsUV8QpqrygsY+2+JCQ6Fw8/omM71IM2N/R8pPbzbgOl0p78MZ
GsgPOQ2HSznjD0FPzsH8oO2B5Uftws04LHb2HJAYlz25+lN5cqfHAfa3fgmC38Ff
wBkn7l582UtPWZ/wcBOnyCgb3yLcvJrXyrt8QxHJgvWO23ITrUVYszImbXQ67YGS
0YhMrbixRzmo2tpm3JcIBtnHrEUMsT0NfFdfsZhTT8YbxBvA8FdODgEwx7u/vf3J
9qbi4+Kv8cvqyJuleIRSjVXPsIMnoejIn04APPKIjpMyQdnWlby7rNyQtE4+CV+j
cFjqJbE/Xilcvqxt6DirjFCvYeKYl1uHLwIDAQAB
-----END RSA PUBLIC KEY-----";

let public_key = RsaPublicKey::from_pkcs1_pem(pem)?;

PKCS#8 RSA Key Encoding

PKCS#8 is a private key format with support for multiple algorithms. Like PKCS#1, it can be encoded as binary (DER) or text (PEM).

You can recognize PEM encoded PKCS#8 keys because they don’t have an algorithm name in the type label, e.g.:

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

The following traits can be used to decode/encode RsaPrivateKey and RsaPublicKey as PKCS#8. Note that pkcs8 is re-exported from the toplevel of the rsa crate:

Example

use rsa::{RsaPublicKey, pkcs8::DecodePublicKey};

let pem = "-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtsQsUV8QpqrygsY+2+JC
Q6Fw8/omM71IM2N/R8pPbzbgOl0p78MZGsgPOQ2HSznjD0FPzsH8oO2B5Uftws04
LHb2HJAYlz25+lN5cqfHAfa3fgmC38FfwBkn7l582UtPWZ/wcBOnyCgb3yLcvJrX
yrt8QxHJgvWO23ITrUVYszImbXQ67YGS0YhMrbixRzmo2tpm3JcIBtnHrEUMsT0N
fFdfsZhTT8YbxBvA8FdODgEwx7u/vf3J9qbi4+Kv8cvqyJuleIRSjVXPsIMnoejI
n04APPKIjpMyQdnWlby7rNyQtE4+CV+jcFjqJbE/Xilcvqxt6DirjFCvYeKYl1uH
LwIDAQAB
-----END PUBLIC KEY-----";

let public_key = RsaPublicKey::from_public_key_pem(pem)?;

Re-exports

pub use rand_core;
pub use signature;
pub use pkcs1;
pub use pkcs8;
pub use self::padding::PaddingScheme;

Modules

Useful algorithms related to RSA.
Error types.
internalsexpose-internals
Internal raw RSA functions.
Supported padding schemes.
PKCS#1 v1.5 support as described in RFC8017 § 8.2.
Support for the Probabilistic Signature Scheme (PSS) a.k.a. RSASSA-PSS.

Structs

A big unsigned integer type.
Represents a whole RSA key, public and private parts.
Represents the public part of an RSA key.

Traits

Generic trait for operations on a public key.
Components of an RSA public key.