Struct SigningKey

pub struct SigningKey<D>
where
    D: Digest,
{ /* private fields */ }

Available on crate feature rsa only.

Signing key for RSASSA-PKCS1-v1_5 signatures as described in RFC8017 § 8.2.

Implementations

impl<D> SigningKey<D>

where D: Digest + AssociatedOid,

pub fn new(key: RsaPrivateKey) -> SigningKey<D>

Create a new signing key with a prefix for the digest D.

Examples found in repository

tests/dyn-rsa-key.rs (line 31)

fn rsa_signer() -> rsa::pkcs1v15::SigningKey<Sha256> {
    rsa::pkcs1v15::SigningKey::<Sha256>::new(rsa_private())
}

examples/acme-new-account.rs (line 50)

fn main() {
    // This key is from RFC 7515, Appendix A.2. Provide your own key instead!
    // The key here is stored as a PKCS#8 PEM file, but you can leverage
    // RustCrypto to load a variety of other formats.
    let key = rsa::RsaPrivateKey::from_pkcs8_pem(include_str!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/examples/rfc7515a2.pem"
    )))
    .unwrap();

    // We will sign the JWT with the RS256 algorithm: RSA with SHA-256.
    // RsaPkcs1v15 is really an alias to the digital signature algorithm
    // implementation in the `rsa` crate, but provided in JAWS to make
    // it clear which types are compatible with JWTs.
    let alg = rsa::pkcs1v15::SigningKey::<Sha256>::new(key);

    let payload = json!({
      "termsOfServiceAgreed": true,
      "contact": [
        "mailto:cert-admin@example.org",
        "mailto:admin@example.org"
      ]
    });

    let header = json!({
        "nonce": "6S8IqOGY7eL2lsGoTZYifg",
        "url": "https://example.com/acme/new-account"
    });

    // Create a token with the default headers, and no custom headers.
    let mut token = Token::new(payload, header, Compact);
    // Request that the token header include a JWK field.
    token.header_mut().key().derived();

    // Sign the token with the algorithm and key we specified above.
    let signed = token.sign::<_, rsa::pkcs1v15::Signature>(&alg).unwrap();

    // Print the token in the ACME example format.
    println!("{}", signed.formatted());
}

examples/rfc7515a2.rs (line 47)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // This key is from RFC 7515, Appendix A.2. Provide your own key instead!
    // The key here is stored as a PKCS#8 PEM file, but you can leverage
    // RustCrypto to load a variety of other formats.
    let key = rsa::RsaPrivateKey::from_pkcs8_pem(include_str!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/examples/rfc7515a2.pem"
    )))
    .unwrap();

    // We will sign the JWT with the RS256 algorithm: RSA with SHA-256.
    let alg = rsa::pkcs1v15::SigningKey::<Sha256>::new(key);

    // Claims can combine registered and custom fields. The claims object
    // can be any type which implements [serde::Serialize].
    let claims: Claims<serde_json::Value, (), String, (), ()> = Claims {
        registered: RegisteredClaims {
            subject: "1234567890".to_string().into(),
            ..Default::default()
        },
        claims: json!({
            "name": "John Doe",
            "admin": true,
        }),
    };

    // Create a token with the default headers, and no custom headers.
    // The unit type can be used here because it implements [serde::Serialize],
    // but a custom type could be passed if we wanted to have custom header
    // fields.
    let mut token = Token::compact((), claims);

    // We can modify the headers freely before signing the JWT. In this case,
    // we provide the `typ` header, which is optional in the JWT spec.
    *token.header_mut().r#type() = Some("JWT".to_string());

    // We can also ask that some fields be derived from the signing key, for example,
    // this will derive the JWK field in the header from the signing key.
    token.header_mut().key().derived();

    println!("=== Initial JWT ===");
    // Initially the JWT has no defined signature:
    println!("{}", token.formatted());

    // Sign the token with the algorithm, and print the result.
    let signed = token.sign::<_, rsa::pkcs1v15::Signature>(&alg).unwrap();

    println!("=== Signed JWT ===");

    println!("JWT:");
    println!("{}", signed.formatted());
    println!("Token: {}", signed.rendered().unwrap());

    // We can't modify the token after signing it (that would change the signature)
    // but we can access fields and read from them:
    println!(
        "Type: {:?}, Algorithm: {:?}",
        signed.header().r#type(),
        signed.header().algorithm(),
    );

    // We can also verify tokens.
    let token: Token<Claims<serde_json::Value>, Unverified<()>, Compact> =
        signed.rendered().unwrap().parse().unwrap();

    println!("=== Parsed JWT ===");

    // Unverified tokens can be printed for debugging, but there is deliberately
    // no access to the payload, only to the header fields.
    println!("JWT:");
    println!("{}", token.formatted());

    // We can use the JWK to verify that the token is signed with the correct key.
    let hdr = token.header();
    let jwk = hdr.key().unwrap();
    let key = rsa::RsaPublicKey::from_jwk(jwk).unwrap();

    assert_eq!(&key, alg.verifying_key().as_ref());
    println!("=== Verification === ");
    let alg: rsa::pkcs1v15::VerifyingKey<Sha256> = alg.verifying_key();

    // We can't access the claims until we verify the token.
    let verified = token
        .verify::<_, jaws::algorithms::SignatureBytes>(&alg)
        .unwrap();

    println!("=== Verified JWT ===");
    println!("JWT:");
    println!("{}", verified.formatted());
    println!(
        "Payload: \n{}",
        serde_json::to_string_pretty(&verified.payload()).unwrap()
    );

    Ok(())
}

examples/dyn-key.rs (line 34)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // This key is from RFC 7515, Appendix A.2. Provide your own key instead!
    // The key here is stored as a PKCS#8 PEM file, but you can leverage
    // RustCrypto to load a variety of other formats.
    let signing_key = rsa::RsaPrivateKey::from_pkcs8_pem(include_str!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/examples/rfc7515a2.pem"
    )))
    .unwrap();
    let verify_key: rsa::pkcs1v15::VerifyingKey<Sha256> =
        rsa::pkcs1v15::VerifyingKey::new(signing_key.to_public_key());

    // We will sign the JWT with a type-erased algorithm, and use a type-erased
    // verifier to verify it. This allows you to use a set of verifiers which
    // are not known at compile time.
    let dyn_signing_key: Box<dyn TokenSigner<SignatureBytes>> = Box::new(
        rsa::pkcs1v15::SigningKey::<Sha256>::new(signing_key.clone()),
    );
    let dyn_verify_key: Box<dyn TokenVerifier<SignatureBytes>> = Box::new(verify_key.clone());

    // Claims can combine registered and custom fields. The claims object
    // can be any type which implements [serde::Serialize].
    let claims: Claims<serde_json::Value, (), String, (), ()> = Claims {
        registered: RegisteredClaims {
            subject: "1234567890".to_string().into(),
            ..Default::default()
        },
        claims: json!({
            "name": "John Doe",
            "admin": true,
        }),
    };

    // Create a token with the default headers, and no custom headers.
    // The unit type can be used here because it implements [serde::Serialize],
    // but a custom type could be passed if we wanted to have custom header
    // fields.
    let mut token = Token::compact((), claims);
    // We can modify the headers freely before signing the JWT. In this case,
    // we provide the `typ` header, which is optional in the JWT spec.
    *token.header_mut().r#type() = Some("JWT".to_string());

    // We can also ask that some fields be derived from the signing key, for example,
    // this will derive the JWK field in the header from the signing key.
    token.header_mut().key().derived();

    println!("=== Initial JWT ===");

    // Initially the JWT has no defined signature:
    println!("{}", token.formatted());

    // Sign the token with the algorithm, and print the result.
    let signed = token
        .sign::<_, SignatureBytes>(dyn_signing_key.as_ref())
        .unwrap();

    let rendered = signed.rendered().unwrap();

    // We can also verify tokens.
    let token: Token<Claims<serde_json::Value>, Unverified<()>, Compact> =
        rendered.parse().unwrap();

    println!("=== Parsed JWT ===");

    // Unverified tokens can be printed for debugging, but there is deliberately
    // no access to the payload, only to the header fields.
    println!("JWT:");
    println!("{}", token.formatted());

    // We can use the JWK to verify that the token is signed with the correct key.
    let hdr = token.header();
    let jwk = hdr.key().unwrap();
    let key: rsa::pkcs1v15::VerifyingKey<Sha256> =
        rsa::pkcs1v15::VerifyingKey::new(rsa::RsaPublicKey::from_jwk(jwk).unwrap());

    println!("=== Verification === ");
    // Check it against the verified key
    token
        .clone()
        .verify::<_, rsa::pkcs1v15::Signature>(&verify_key)
        .unwrap();
    println!(
        "Verified with verify key (typed): {}",
        type_name_of_val(&verify_key)
    );

    // Check it against the verified key
    let verified = token
        .clone()
        .verify::<_, SignatureBytes>(dyn_verify_key.as_ref())
        .unwrap();
    println!(
        "Verified with dyn verify key: {}",
        type_name_of_val(&dyn_verify_key)
    );

    // Check it against its own JWT
    token
        .clone()
        .verify::<_, rsa::pkcs1v15::Signature>(&key)
        .unwrap();
    println!("Verified with JWK");

    println!("=== Verified JWT ===");
    println!("JWT:");
    println!("{}", verified.formatted());
    println!(
        "Payload: \n{}",
        serde_json::to_string_pretty(&verified.payload()).unwrap()
    );

    Ok(())
}

pub fn random<R>(rng: &mut R, bit_size: usize) -> Result<SigningKey<D>, Error>

where R: CryptoRngCore + ?Sized,

Generate a new signing key with a prefix for the digest D.

pub fn new_with_prefix(key: RsaPrivateKey) -> SigningKey<D>

👎Deprecated since 0.9.0: use SigningKey::new instead

Create a new signing key with a prefix for the digest D.

pub fn random_with_prefix<R>( rng: &mut R, bit_size: usize, ) -> Result<SigningKey<D>, Error>

where R: CryptoRngCore + ?Sized,

👎Deprecated since 0.9.0: use SigningKey::random instead

Generate a new signing key with a prefix for the digest D.

impl<D> SigningKey<D>

where D: Digest,

pub fn new_unprefixed(key: RsaPrivateKey) -> SigningKey<D>

Create a new signing key from the give RSA private key with an empty prefix.

Note: unprefixed signatures are uncommon

In most cases you’ll want to use SigningKey::new.

pub fn random_unprefixed<R>( rng: &mut R, bit_size: usize, ) -> Result<SigningKey<D>, Error>

where R: CryptoRngCore + ?Sized,

Generate a new signing key with an empty prefix.

Trait Implementations

impl<D> AsRef<RsaPrivateKey> for SigningKey<D>

where D: Digest,

fn as_ref(&self) -> &RsaPrivateKey

Converts this type into a shared reference of the (usually inferred) input type.

impl<D> AssociatedAlgorithmIdentifier for SigningKey<D>

where D: Digest,

const ALGORITHM_IDENTIFIER: AlgorithmIdentifier<AnyRef<'static>> = pkcs1::ALGORITHM_ID

AlgorithmIdentifier for this structure.

type Params = AnyRef<'static>

Algorithm parameters.

impl<D> Clone for SigningKey<D>

where D: Clone + Digest,

fn clone(&self) -> SigningKey<D>

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<D> Debug for SigningKey<D>

where D: Debug + Digest,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<D> DigestSigner<D, Signature> for SigningKey<D>

where D: Digest,

fn try_sign_digest(&self, digest: D) -> Result<Signature, Error>

Attempt to sign the given prehashed message Digest, returning a digital signature on success, or an error if something went wrong.

fn sign_digest(&self, digest: D) -> S

Sign the given prehashed message Digest, returning a signature.

impl<D> EncodePrivateKey for SigningKey<D>

where D: Digest,

fn to_pkcs8_der(&self) -> Result<SecretDocument, Error>

Serialize a SecretDocument containing a PKCS#8-encoded private key.

fn to_pkcs8_pem( &self, line_ending: LineEnding, ) -> Result<Zeroizing<String>, Error>

Serialize this private key as PEM-encoded PKCS#8 with the given LineEnding.

fn write_pkcs8_der_file(&self, path: impl AsRef<Path>) -> Result<(), Error>

Write ASN.1 DER-encoded PKCS#8 private key to the given path

fn write_pkcs8_pem_file( &self, path: impl AsRef<Path>, line_ending: LineEnding, ) -> Result<(), Error>

Write ASN.1 DER-encoded PKCS#8 private key to the given path

impl<D> From<RsaPrivateKey> for SigningKey<D>

where D: Digest,

fn from(key: RsaPrivateKey) -> SigningKey<D>

Converts to this type from the input type.

impl<D> JWKeyType for SigningKey<D>

where D: Digest,

const KEY_TYPE: &'static str = "RSA"

The string used to identify the JWK type in the kty field.

impl JsonWebAlgorithm for SigningKey<Sha256>

const IDENTIFIER: AlgorithmIdentifier = crate::algorithms::AlgorithmIdentifier::RS256

The identifier for this algorithm when used in a JWT registered header.

impl JsonWebAlgorithm for SigningKey<Sha512>

const IDENTIFIER: AlgorithmIdentifier = crate::algorithms::AlgorithmIdentifier::RS512

The identifier for this algorithm when used in a JWT registered header.

impl JsonWebAlgorithm for SigningKey<Sha384>

const IDENTIFIER: AlgorithmIdentifier = crate::algorithms::AlgorithmIdentifier::RS384

The identifier for this algorithm when used in a JWT registered header.

impl JsonWebAlgorithmDigest for SigningKey<Sha256>

type Digest = CoreWrapper<CtVariableCoreWrapper<Sha256VarCore, UInt<UInt<UInt<UInt<UInt<UInt<UTerm, B1>, B0>, B0>, B0>, B0>, B0>, OidSha256>>

The digest algorithm used by this signature.

impl JsonWebAlgorithmDigest for SigningKey<Sha512>

type Digest = CoreWrapper<CtVariableCoreWrapper<Sha512VarCore, UInt<UInt<UInt<UInt<UInt<UInt<UInt<UTerm, B1>, B0>, B0>, B0>, B0>, B0>, B0>, OidSha512>>

The digest algorithm used by this signature.

impl JsonWebAlgorithmDigest for SigningKey<Sha384>

type Digest = CoreWrapper<CtVariableCoreWrapper<Sha512VarCore, UInt<UInt<UInt<UInt<UInt<UInt<UTerm, B1>, B1>, B0>, B0>, B0>, B0>, OidSha384>>

The digest algorithm used by this signature.

impl<D> Keypair for SigningKey<D>

where D: Digest,

type VerifyingKey = VerifyingKey<D>

Verifying key type for this keypair.

fn verifying_key(&self) -> <SigningKey<D> as Keypair>::VerifyingKey

Get the verifying key which can verify signatures produced by the signing key portion of this keypair.

impl<D> PrehashSigner<Signature> for SigningKey<D>

where D: Digest,

fn sign_prehash(&self, prehash: &[u8]) -> Result<Signature, Error>

Attempt to sign the given message digest, returning a digital signature on success, or an error if something went wrong.

impl<D> RandomizedDigestSigner<D, Signature> for SigningKey<D>

where D: Digest,

fn try_sign_digest_with_rng( &self, rng: &mut impl CryptoRngCore, digest: D, ) -> Result<Signature, Error>

Attempt to sign the given prehashed message Digest, returning a digital signature on success, or an error if something went wrong.

fn sign_digest_with_rng(&self, rng: &mut impl CryptoRngCore, digest: D) -> S

Sign the given prehashed message Digest, returning a signature.

impl<D> RandomizedSigner<Signature> for SigningKey<D>

where D: Digest,

fn try_sign_with_rng( &self, rng: &mut impl CryptoRngCore, msg: &[u8], ) -> Result<Signature, Error>

Attempt to sign the given message, returning a digital signature on success, or an error if something went wrong.

fn sign_with_rng(&self, rng: &mut impl CryptoRngCore, msg: &[u8]) -> S

Sign the given message and return a digital signature

impl<D> SerializeJWK for SigningKey<D>

where D: Digest,

fn parameters(&self) -> Vec<(String, Value)>

Return a list of parameters to be serialized in the JWK.

impl<D> SignatureAlgorithmIdentifier for SigningKey<D>

where D: Digest + RsaSignatureAssociatedOid,

const SIGNATURE_ALGORITHM_IDENTIFIER: AlgorithmIdentifier<AnyRef<'static>>

AlgorithmIdentifier for the corresponding singature system.

type Params = AnyRef<'static>

Algorithm parameters.

impl<D> Signer<Signature> for SigningKey<D>

where D: Digest,

fn try_sign(&self, msg: &[u8]) -> Result<Signature, Error>

Attempt to sign the given message, returning a digital signature on success, or an error if something went wrong.

fn sign(&self, msg: &[u8]) -> S

Sign the given message and return a digital signature

impl<D> TryFrom<PrivateKeyInfo<'_>> for SigningKey<D>

where D: Digest + AssociatedOid,

type Error = Error

The type returned in the event of a conversion error.

fn try_from( private_key_info: PrivateKeyInfo<'_>, ) -> Result<SigningKey<D>, Error>

Performs the conversion.

impl<D> ZeroizeOnDrop for SigningKey<D>

where D: Digest,