silk.crypto.rsa.

When to use#

Use RsaPublicKey.verifyPss to verify an RSA-PSS signature, for example a JSON Web Token with PS256. Use RsaPublicKey.verifyCertificate to verify the signature of an X.509 certificate. This module cannot sign, encrypt, or decrypt.

Details#

A key has a modulus of 2048 to 4096 bits and the public exponent 65537. Make one from its parts with RsaPublicKey.fromComponents, or from a certificate with RsaPublicKey.fromCertificateKey. The PSS profile is SHA-256, MGF1 with SHA-256, a 32-byte salt, and the trailer 0xbc. A signature has the same length in bytes as the modulus. The functions hash the message, so give the message, not its digest.

Errors#

• RsaError for a key, a parameter, or a signature that is not valid or does not match.

Gotchas#

A valid signature proves only that the holder of the private key signed the message. It does not prove that you can trust the key. To check a certificate chain, use the silk.tls.trust_* modules. Keys with an exponent other than 65537, or shorter than 2048 bits, are rejected.

Examples#

Reject a key outside the profile#

import silk.core.result { Result }
import silk.crypto.rsa { RsaError, RsaPublicKey }

pub fn main() -> i32 {
  // A 2048-bit odd modulus: 0xc0, then 254 bytes of 0x00, then 0x01.
  let mut modulus: [u8; 256] = [0; 256]
  modulus[0] = 0xc0
  modulus[255] = 0x01

  // The exponent 3 is not accepted, only 65537 (01 00 01).
  match RsaPublicKey.fromComponents(&modulus, b"\x03") {
    Result<RsaPublicKey, RsaError>.Failure { error: RsaError.InvalidKey } => {}
    _ => {
      return 1
    }
  }
  return match RsaPublicKey.fromComponents(&modulus, b"\x01\x00\x01") {
    Result<RsaPublicKey, RsaError>.Success { value: _ } => 0
    Result<RsaPublicKey, RsaError>.Failure { error: _ } => 1
  }
}

Import as RsaPublicKey with import silk.crypto.rsa { RsaPublicKey }.

Public declarations: 2.

RsaError#

pub enum RsaError

The reason that an RSA key or signature was rejected.

InvalidKey#

InvalidKey

The modulus is not odd, has a leading zero byte, or is not 2048 to 4096 bits, or the exponent is not 65537.

InvalidEncoding#

InvalidEncoding

A DER value is not valid, not minimal, or has bytes after it.

InvalidParameters#

InvalidParameters

An algorithm identifier or its parameters are not in the supported profile.

InvalidLength#

InvalidLength

The signature length is not the modulus length, or a BIT STRING has unused bits.

MessageTooLong#

MessageTooLong

The message is longer than SHA-256 allows.

InvalidSignature#

InvalidSignature

The signature does not match the message and the key.

Implementation Debug for RsaError#

impl Debug for RsaError

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant, such as InvalidKey.

RsaPublicKey#

pub struct RsaPublicKey

An RSA public key with a 2048 to 4096-bit modulus and the exponent 65537. It owns a copy of the modulus.

When to use#

Use RsaPublicKey.verifyPss to verify an RSA-PSS signature, for example a JSON Web Token with PS256. Use RsaPublicKey.verifyCertificate to verify the signature of an X.509 certificate. It cannot sign, encrypt, or decrypt.

Details#

Make one from its parts with RsaPublicKey.fromComponents, or from a certificate with RsaPublicKey.fromCertificateKey. The functions hash the message, so give the message, not its digest.

Gotchas#

A valid signature proves only that the holder of the private key signed the message. It does not prove that you can trust the key. To check a certificate chain, use the silk.tls.trust_* modules.

Implementation RsaPublicKey#

impl RsaPublicKey

Associated function fromComponents#

pub fn fromComponents(modulus: &[u8], exponent: &[u8]) -> Result<RsaPublicKey, RsaError>

Returns the key for the big-endian modulus and exponent bytes.

The modulus must be odd, have no leading zero byte, and have 2048 to 4096 significant bits. The exponent must be the three bytes 01 00 01 (65537).

Errors#

• InvalidKey if a value is not in this profile.

Method verifyPss#

pub fn verifyPss(self: &RsaPublicKey, message: &[u8], signature: &[u8]) -> Result<(), RsaError>

Checks that signature is a valid RSASSA-PSS signature of message with this key.

The profile is SHA-256, MGF1 with SHA-256, a 32-byte salt, and the trailer 0xbc. signature must have the same length in bytes as the modulus.

Errors#

• InvalidLength if signature has the wrong length.

• MessageTooLong if message is too long for SHA-256.

• InvalidSignature if the signature does not match.

Implementation RsaPublicKey#

impl RsaPublicKey

Associated function fromCertificateKey#

pub fn fromCertificateKey(algorithmDer: &[u8], keyDer: &[u8], unusedBits: u8) -> Result<
    RsaPublicKey,
    RsaError,
  >

Returns the key in the subjectPublicKeyInfo of a certificate.

Pass the algorithm DER, the BIT STRING bytes, and the unused-bit count from silk.tls.certificate as they are. The algorithm must be rsaEncryption with no parameters or NULL. The key must pass the same checks as RsaPublicKey.fromComponents.

Errors#

• InvalidEncoding if the DER is not valid.

• InvalidParameters if the algorithm is wrong.

• InvalidLength if unusedBits is not 0.

• InvalidKey if the key is not in the profile.

Method verifyCertificate#

pub fn verifyCertificate(
    self: &RsaPublicKey,
    message: &[u8],
    algorithmDer: &[u8],
    signature: &[u8],
    unusedBits: u8,
  ) -> Result<(), RsaError>

Verifies a certificate signature with this key.

message is the signed part of the certificate (the TBSCertificate DER), algorithmDer is its signature AlgorithmIdentifier, and signature and unusedBits come from its signature BIT STRING. It accepts sha256WithRSAEncryption (PKCS #1 v1.5) and RSASSA-PSS with the profile of RsaPublicKey.verifyPss.

Errors#

• InvalidLength if unusedBits is not 0.

• InvalidParameters if the algorithm or its parameters are not supported.

• InvalidLength if signature does not have the length of the modulus.

• MessageTooLong if message is too long for SHA-256.

• InvalidSignature if the signature does not match.

Gotchas#

It checks only this one signature. It does not check the chain, the dates, or the names.

Category: Cryptography.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.