Python RSA

https://github.com/sybrenstuvel/python-rsa
Admin
Python-RSA is a pure-Python RSA implementation, supporting encryption, decryption, signing,...
Tokens:59,965
Snippets:486
Trust Score:9.4
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install from source

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/installation.rst

Installs Python-RSA from the downloaded source code by running the setup script.

```default
python setup.py install
```

--------------------------------

### Set up development environment with Poetry

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/README.md

Sets up a virtual environment, activates it, installs Poetry, and installs project dependencies. Run these commands in order from the project root.

```bash
python3 -m venv .venv
. ./.venv/bin/activate
pip install poetry
poetry install
```

--------------------------------

### Using rsa.newkeys with poolsize=4

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.parallel.md

Usage example showing how rsa.parallel is selected automatically by rsa.key.newkeys when poolsize > 1. On platforms using the spawn start method (e.g. Windows), this must be guarded by if __name__ == "__main__": because workers re-import the calling module.

```python
import rsa

# 4 processes, 2048-bit key, exactly 2048 bits in n
pub, priv = rsa.newkeys(2048, poolsize=4)
```

--------------------------------

### keygen command-line example

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Example invocation of the pyrsa-keygen command, generating a 2048-bit key pair with public key output to public.pem and private key to private.pem in PEM format.

```bash
pyrsa-keygen --pubout public.pem --out private.pem --form PEM 2048
```

--------------------------------

### Install with pip

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/installation.rst

Installs the Python-RSA library using pip. On some systems, you may need to use 'sudo pip' for system-wide installation or 'pip install --user rsa' to install in your home directory.

```default
pip install rsa
```

--------------------------------

### Install development dependencies with Pipenv

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/installation.rst

After cloning the repository, change into the directory and install the development requirements in a virtual environment using Pipenv.

```default
cd python-rsa
pipenv install --dev
```

--------------------------------

### Command-line usage of pyrsa-priv2pub

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.util.md

Example commands for using the pyrsa-priv2pub console script to convert a private key to a public key, including reading from stdin and writing to stdout.

```bash
pyrsa-priv2pub -i private.pem -o public.pem --inform PEM --outform PEM

# Read from stdin, write the public key to stdout:
cat private.pem | pyrsa-priv2pub --inform PEM --outform PEM > public.pem
```

--------------------------------

### Key save/load round-trip example

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Demonstrates saving and loading a private and public key in PEM format, verifying round-trip equality.

```python
import rsa

pub, priv = rsa.newkeys(1024)
pem = priv.save_pkcs1("PEM")
loaded = rsa.PrivateKey.load_pkcs1(pem, "PEM")
assert loaded == priv

pub_pem = pub.save_pkcs1(format="PEM")
pub_loaded = rsa.PublicKey.load_pkcs1(pub_pem, format="PEM")
assert pub_loaded == pub
```

--------------------------------

### Blinding usage example

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Example of blinding and unblinding a message using rsa.newkeys and the blind/unblind methods.

```python
import rsa

pub, priv = rsa.newkeys(256)
blinded, factor_inv = priv.blind(12345)
decrypted = priv.blinded_decrypt(blinded)
assert priv.unblind(decrypted, factor_inv) == 12345
```

--------------------------------

### Basic signing example

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.pkcs1.md

Signs a message with a 512-bit key and prints the signature length (64 bytes).

```python
import rsa

(pub, priv) = rsa.newkeys(512)
signature = rsa.sign(b"important document", priv, "SHA-512")
print(len(signature))  # 64 bytes
```

--------------------------------

### Example usage: prime-candidate drawing and blinding-factor selection

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.randnum.md

Example usage for prime-candidate drawing and blinding-factor selection. It imports rsa.randnum and rsa.prime, then loops up to 1000 times to find a random coprime blinding factor using randint and are_relatively_prime.

```python
import rsa.randnum
import rsa.prime

# Pick a random coprime blinding factor, as AbstractKey does:
for _ in range(1000):
    r = rsa.randnum.randint(2048 - 1)
    if rsa.prime.are_relatively_prime(2048, r):
        break
```

--------------------------------

### Error handling for missing PEM marker

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.pem.md

Error handling example: attempts to load a PEM with a missing start marker and prints the resulting ValueError message.

```python
import rsa.pem

try:
    rsa.pem.load_pem(b"garbage", "RSA PRIVATE KEY")
except ValueError as ex:
    print(ex)  # No PEM start marker "b'-----BEGIN RSA PRIVATE KEY-----'" found
```

--------------------------------

### Load public key with error handling

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Example showing how to load a public key from a PEM file, falling back to plain PKCS#1 on ValueError. Prints the loaded key.

```python
import rsa

with open("id_rsa.pub", "rb") as f:
    data = f.read()

try:
    pub = rsa.PublicKey.load_pkcs1_openssl_pem(data)
except ValueError:
    pub = rsa.PublicKey.load_pkcs1(data)  # fall back to plain PKCS#1
print(pub)
```

--------------------------------

### Manual conversion using rsa.key object API

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.util.md

Comparison example showing how to manually perform the same conversion using rsa.PrivateKey.load_pkcs1 and rsa.PublicKey, then save the public key.

```python
import rsa

with open("private.p
```

--------------------------------

### Generate a prime with getprime

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.prime.md

Basic example of generating a 128-bit prime and verifying its bit size.

```python
from rsa import prime, common

p = prime.getprime(128)
print(common.bit_size(p))  # 128
```

--------------------------------

### inverse usage example

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.common.md

Example of using common.inverse to compute modular inverses. Asserts that inverse(7, 4) == 3 and that (inverse(143, 4) * 143) % 4 == 1.

```python
from rsa import common

try:
    common.inverse(4, 8)  # gcd(4, 8) = 4
except common.NotRelativePrimeError as ex:
    print(ex.a, ex.b, ex.d)  # 4 8 4
```

--------------------------------

### PublicKey.load_pkcs1_openssl_pem

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Loads a SubjectPublicKeyInfo (BEGIN PUBLIC KEY) PEM file from OpenSSL. Raises ValueError if the start marker cannot be found.

```APIDOC
## PublicKey.load_pkcs1_openssl_pem

### Description
Loads a SubjectPublicKeyInfo (BEGIN PUBLIC KEY) PEM file from OpenSSL. Raises ValueError if the start marker cannot be found.

### Method
load_pkcs1_openssl_pem

### Signature
```python
@classmethod
def load_pkcs1_openssl_pem(cls, keyfile: bytes) -> "PublicKey":
```

### Parameters
- **keyfile** (bytes) - Required - The PEM file content as bytes.

### Returns
(PublicKey) The loaded public key.

### Raises
- **ValueError** - If the PEM start marker is not found.

### Example
```python
import rsa

with open("id_rsa.pub", "rb") as f:
    data = f.read()

try:
    pub = rsa.PublicKey.load_pkcs1_openssl_pem(data)
except ValueError:
    pub = rsa.PublicKey.load_pkcs1(data)  # fall back to plain PKCS#1
print(pub)
```
```

--------------------------------

### Configure ~/.pypirc for PyPI API token

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/README.md

Example ~/.pypirc configuration for publishing to PyPI using an API token. The username must be __token__ and the password must include the pypi- prefix.

```ini
[distutils]
index-servers =
    rsa

# Use `twine upload -r rsa` to upload with this token.
[rsa]
  repository = https://upload.pypi.org/legacy/
  username = __token__
  password = pypi-token
```

--------------------------------

### Module-level CLI instances in rsa/cli.py

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

These four callable instances are the console-script entry points and can also be invoked programmatically. The example shows importing the rsa.cli module and calling cli.verify(), which parses sys.argv and runs the verify program.

```python
encrypt = EncryptOperation()
decrypt = DecryptOperation()
sign = SignOperation()
verify = VerifyOperation()
```

```python
from rsa import cli

cli.verify()   # parses sys.argv and runs the verify program
```

--------------------------------

### Basic encryption example

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.pkcs1.md

Encrypts a short message with a 512-bit key and prints the ciphertext length (64 bytes).

```python
import rsa

(pub, priv) = rsa.newkeys(512)
ciphertext = rsa.encrypt(b"attack at dawn", pub)
print(len(ciphertext))  # 64 == byte_size(pub.n)
```

--------------------------------

### Verify a signature with error handling (Python)

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.pkcs1.md

Shows how to verify a signature using rsa.verify, including handling verification failure and wrong-size signatures. The example generates a key pair, signs a payload, and prints the hash name on success or catches rsa.VerificationError.

```python
import rsa

(pub, priv) = rsa.newkeys(512)
sig = rsa.sign(b"payload", priv, "SHA-256")

print(rsa.verify(b"payload", sig, pub))  # 'SHA-256'

try:
    rsa.verify(b"other payload", sig, pub)
except rsa.VerificationError:
    print("verification failed")

# Wrong-size signature also fails:
try:
    rsa.verify(b"payload", b"\x00" * 10, pub)
except rsa.VerificationError:
    print("bad signature length")
```

--------------------------------

### Round trip with save_pem and load_pem

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.pem.md

Round-trip example: saves a DER blob as PEM, prints the PEM output, and verifies that loading it back returns the original bytes.

```python
import rsa.pem

der = b"\x30\x0d\x02\x01\x00\x02\x03\x01\x00\x01\x04\x00"
pem = rsa.pem.save_pem(der, "RSA PUBLIC KEY")
print(pem.decode("ascii"))
# -----BEGIN RSA PUBLIC KEY-----
# MA0CAQMBAAEABA==
# -----END RSA PUBLIC KEY-----

assert rsa.pem.load_pem(pem, "RSA PUBLIC KEY") == der
```

--------------------------------

### Decode a DER public key example

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.asn1.md

Example of decoding a DER public key using the library's own flow. It decodes a base64-encoded DER string and prints the modulus and public exponent.

```python
import base64
from rsa.asn1 import AsnPubKey
from pyasn1.codec.der import decoder

b64der = "MAwCBQCNGmYtAgMBAAE="
der = base64.standard_b64decode(b64der)
(priv, _) = decoder.decode(der, asn1Spec=AsnPubKey())
print(int(priv["modulus"]), int(priv["publicExponent"]))  # 2367317549 65537
```

--------------------------------

### Convert old dictionary-based keys to PKCS#1 key objects

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/upgrading.rst

Convert old dictionary-based public and private keys to the new PKCS#1 key objects introduced in version 3.0. The example shows both explicit constructor calls and a shorter notation using dictionary unpacking.

```python
import rsa

# Load the old key somehow.
old_pub_key = {
    'e': 65537,
    'n': 31698122414741849421263704398157795847591L
}

old_priv_key = {
    'd': 7506520894712811128876594754922157377793L,
    'p': 4169414332984308880603L,
    'q': 7602535963858869797L
}

# Create new key objects like this:
pub_key = rsa.PublicKey(n=old_pub_key['n'], e=old_pub_key['e'])

priv_key = rsa.PrivateKey(n=old_pub_key['n'], e=old_pub_key['e'],
    d=old_priv_key['d'], p=old_priv_key['p'], q=old_priv_key['q'])


# Or use this shorter notation:
pub_key = rsa.PublicKey(**old_pub_key)

old_priv_key.update(old_pub_key)
priv_key = rsa.PrivateKey(**old_priv_key)
```

--------------------------------

### Compute hash from a file-like object (Python)

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.pkcs1.md

Demonstrates using rsa.pkcs1.compute_hash with a BytesIO file-like object. The example reads data in 1024-byte blocks and prints the hex digest of the computed hash.

```python
import io
import rsa.pkcs1

handle = io.BytesIO(b"data streamed from somewhere")
digest = rsa.pkcs1.compute_hash(handle, "SHA3-256")
print(digest.hex())
```

--------------------------------

### Decryption example with error handling

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.pkcs1.md

Decrypts a ciphertext, then tampers with it to trigger DecryptionError. Demonstrates the error handling pattern.

```python
import rsa

(pub, priv) = rsa.newkeys(512)
ciphertext = rsa.encrypt(b"hello", pub)

print(rsa.decrypt(ciphertext, priv))  # b'hello'

tampered = ciphertext[:5] + b"X" + ciphertext[6:]
try:
    rsa.decrypt(tampered, priv)
ex# except rsa.DecryptionError:
#     print("decryption failed")
```

--------------------------------

### Use are_relatively_prime as a precondition guard

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.prime.md

Example showing how to use are_relatively_prime as a precondition guard, raising ValueError when the numbers are not coprime.

```python
from rsa import prime

assert prime.are_relatively_prime(2, 3)   # True
assert not prime.are_relatively_prime(2, 4)

if not prime.are_relatively_prime(a, n):
    raise ValueError("choose a coprime to n")
```

--------------------------------

### Encrypt message with public key

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/usage.rst

Alice encrypts the encoded message using Bob's public key. The import statement is repeated in the example.

```pycon
>>> import rsa
>>> crypto = rsa.encrypt(message, bob_pub)
```

--------------------------------

### Speed up key generation with poolsize parameter

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/usage.rst

Use poolsize=8 to parallelize key generation across multiple processes. The example shows generating a 512-bit key with 8 processes.

```pycon
>>> (pubkey, privkey) = rsa.newkeys(512, poolsize=8)
```

--------------------------------

### Programmatic invocation of private_to_public

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.util.md

Example of invoking private_to_public programmatically by setting sys.argv, as it reads command-line arguments.

```python
import sys
from rsa.util import private_to_public

sys.argv = ["pyrsa-priv2pub", "-i", "private.pem", "-o", "public.pem"]
private_to_public()
```

--------------------------------

### Compute hash and sign separately with rsa.compute_hash() and rsa.sign_hash()

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/usage.rst

Calculates the hash and signature in separate operations, useful for hashing on a client and signing on a remote server. Uses rsa.compute_hash() to get the hash and rsa.sign_hash() to sign it.

```pycon
>>> message = 'Go left at the blue tree'.encode()
>>> hash = rsa.compute_hash(message, 'SHA-1')
>>> signature = rsa.sign_hash(hash, privkey, 'SHA-1')
```

--------------------------------

### AbstractKey.__init__

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Initializes an AbstractKey instance with modulus and public exponent, setting up internal state for blinding and thread safety.

```APIDOC
## AbstractKey.__init__

### Description
Initializes an AbstractKey instance with the modulus and public exponent, setting up internal state for blinding and thread safety.

### Method
Constructor

### Signature
```python
def __init__(self, n: int, e: int) -> None:
```

### Parameters
- **n** (int) - Required - Modulus.
- **e** (int) - Required - Public exponent.

### Notes
Sets `blindfac = blindfac_inverse = -1` (computed lazily on first `blind()` call) and creates a `threading.Lock` in `mutex`.
```

--------------------------------

### Publish a new release with Poetry and twine

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/README.md

Builds the package with Poetry, checks the distribution files with twine, and uploads them to the rsa repository. Requires the ~/.pypirc configuration with an API token.

```bash
. ./.venv/bin/activate

poetry build
twine check dist/rsa-4.10-dev0.tar.gz dist/rsa-4.10-dev0-*.whl
twine upload -r rsa dist/rsa-4.10-dev0.tar.gz dist/rsa-4.10-dev0-*.whl
```

--------------------------------

### load_pem

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.pem.md

Loads and decodes the base64 content of a PEM file between the start and end markers.

```APIDOC
## [FUNCTION] load_pem

### Description
Loads and decodes the base64 content of a PEM file between the start and end markers.

### Method
FUNCTION

### Endpoint
rsa.pem.load_pem

### Parameters
#### Function Parameters
- **contents** (FlexiText) - Required - The contents of the PEM file. `str` input is encoded as ASCII.
- **pem_marker** (FlexiText) - Required - The marker of the PEM content, e.g. `'RSA PRIVATE KEY'` when the file contains `-----BEGIN RSA PRIVATE KEY-----` / `-----END RSA PRIVATE KEY-----`.

### Returns
- **bytes** - The base64-decoded content between the start and end markers.

### Raises
- **ValueError** - If the start marker is seen twice, no start marker is found, or no end marker is found.
- **binascii.Error** - If base64 decoding fails.

### Example
```python
import rsa.pem

der = b"\x30\x0d\x02\x01\x00\x02\x03\x01\x00\x01\x04\x00"
pem = rsa.pem.save_pem(der, "RSA PUBLIC KEY")
print(pem.decode("ascii"))
# -----BEGIN RSA PUBLIC KEY-----
# MA0CAQMBAAEABA==
# -----END RSA PUBLIC KEY-----

assert rsa.pem.load_pem(pem, "RSA PUBLIC KEY") == der
```
```

--------------------------------

### AbstractKey.__init__ signature

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Constructor for AbstractKey. Initializes the modulus and public exponent, and sets up blinding factor caches and a mutex lock.

```python
def __init__(self, n: int, e: int) -> None:
```

--------------------------------

### Decryption error on altered ciphertext

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/usage.rst

Altering the encrypted data causes a rsa.pkcs1.DecryptionError. The example shows the traceback and error message.

```pycon
>>> crypto = rsa.encrypt(b'hello', bob_pub)
>>> crypto = crypto[:-1] + b'X' # change the last byte
>>> rsa.decrypt(crypto, bob_priv)
Traceback (most recent call last):
...
rsa.pkcs1.DecryptionError: Decryption failed
```

--------------------------------

### CryptoOperation.__init__

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Constructor that formats usage and help strings using the subclass's class dictionary.

```APIDOC
## `__init__`

### Description
Formats `usage`, `input_help`, and `output_help` with the subclass's class dict.

### Method
`__init__`

### Signature
```python
def __init__(self) -> None:
```

### Parameters
None

### Returns
None
```

--------------------------------

### private_to_public()

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.util.md

Reads a private key and outputs the corresponding public key. Both keys use the PKCS#1 v1.5 format. This is the entry point of the pyrsa-priv2pub console script.

```APIDOC
## [FUNCTION] private_to_public()

### Description
Reads a private key and outputs the corresponding public key. Both keys use the PKCS#1 v1.5 format. This is the entry point of the `pyrsa-priv2pub` console script.

### Method
Function call

### Endpoint
`rsa.util.private_to_public()`

### Parameters
#### Command-Line Options (parsed with `optparse.OptionParser`)
- **-i, --input** (string) - Optional - Input filename; reads from stdin if not specified (as ASCII text).
- **-o, --output** (string) - Optional - Output filename; writes to stdout if not specified.
- **--inform** (choice) - Optional - Key format of the input: `PEM` or `DER`. Default: `PEM`.
- **--outform** (choice) - Optional - Key format of the output: `PEM` or `DER`. Default: `PEM`.

### Request Example
```bash
pyrsa-priv2pub -i private.pem -o public.pem --inform PEM --outform PEM
```

### Response
#### Success Response
- Writes the public key to the specified output file or stdout.
- Progress messages go to stderr; the key itself is printed to stdout (decoded as ASCII) when no `--output` is given.

#### Response Example
```
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
```

### Error Handling
- **ValueError** - Unsupported `--inform`/`--outform` value, or malformed PEM (missing markers).
- **ValueError** - ASN.1 version field `!= 0` in a DER private key.
- **UserWarning** - Malformed keyfile with wrong stored CRT exponents (still loads).
- **pyasn1.error.PyAsn1Error** - Invalid DER data.
```

--------------------------------

### read_key method

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Reads a key file in binary mode and loads it using the key class's load_pkcs1 method. Prints progress to stderr.

```python
def read_key(self, filename: str, keyform: str) -> rsa.key.AbstractKey:

```

--------------------------------

### AbstractKey.load_pkcs1 (classmethod)

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Loads a PKCS#1 key from PEM or DER encoded bytes, dispatching to the appropriate concrete class loader.

```APIDOC
## AbstractKey.load_pkcs1 (classmethod)

### Description
Loads a PKCS#1 key from PEM or DER encoded bytes, dispatching to the appropriate concrete class loader.

### Method
Classmethod

### Signature
```python
@classmethod
def load_pkcs1(cls: typing.Type[T], keyfile: bytes, format: str = "PEM") -> T:
```

### Parameters
- **keyfile** (bytes) - Required - Contents of a PKCS#1 DER- or PEM-encoded key file.
- **format** (str) - Optional, default `"PEM"` - `"PEM"` or `"DER"`.

### Returns
A `PublicKey` or `PrivateKey` instance.
```

--------------------------------

### Load a private key from a PEM file with rsa.PrivateKey.load_pkcs1()

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/usage.rst

Reads a private key from a file in binary mode and loads it using rsa.PrivateKey.load_pkcs1(). Requires the file to be in PKCS#1 format.

```pycon
>>> import rsa
>>> with open('private.pem', mode='rb') as privatefile:
...     keydata = privatefile.read()
>>> privkey = rsa.PrivateKey.load_pkcs1(keydata)
```

--------------------------------

### AbstractKey._assert_format_exists staticmethod signature

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Static method that raises ValueError if the file format is not supported.

```python
@staticmethod
def _assert_format_exists(
    file_format: str, methods: typing.Mapping[str, typing.Callable]
) -> typing.Callable:
```

--------------------------------

### Basic usage and error handling for encrypt_int

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.core.md

Demonstrates encrypting an integer, then catching ValueError for negative messages and OverflowError for messages larger than the modulus.

```python
import rsa.core

msg = rsa.core.encrypt_int(42, 65537, 100003)
print(msg)

try:
    rsa.core.encrypt_int(-1, 65537, 100003)
except ValueError:
    print("negative message rejected")

try:
    rsa.core.encrypt_int(2**200, 65537, 100003)
except OverflowError:
    print("message larger than modulus rejected")
```

--------------------------------

### PrivateKey.__init__

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Initializes a private RSA key with the given modulus, exponents, and prime factors. It also computes derived CRT attributes.

```APIDOC
## `PrivateKey.__init__`

### Description
Initializes a private RSA key with the given modulus, exponents, and prime factors. It also computes derived CRT attributes.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    n: int,
    e: int,
    d: int,
    p: int,
    q: int,
    rs: typing.Optional[typing.List[int]] = None,
) -> None:
```

### Parameters
- **n** (int) - Required - Modulus.
- **e** (int) - Required - Public exponent.
- **d** (int) - Required - Private exponent.
- **p** (int) - Required - First prime factor.
- **q** (int) - Required - Second prime factor.
- **rs** (Optional[List[int]]) - Optional - Additional prime factors (multi-prime). Default `None` → `[]`.

### Derived Attributes
- **exp1** - `d % (p - 1)`
- **exp2** - `d % (q - 1)`
- **coef** - `inverse(q, p)`
- **ds** - `[d % (r - 1) for r in rs]`
- **ts** - `[pow(R, -1, r) ...]` per extra prime

### Response
No return value.
```

--------------------------------

### PublicKey Constructor

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Creates a new PublicKey instance with the given modulus n and public exponent e.

```APIDOC
## PublicKey Constructor

### Description
Creates a new PublicKey instance with the given modulus n and public exponent e.

### Method
Constructor

### Signature
```python
PublicKey(n: int, e: int)
```

### Parameters
- **n** (int) - Required - The modulus of the RSA key.
- **e** (int) - Required - The public exponent of the RSA key.

### Returns
A new PublicKey instance.

### Example
```python
key = rsa.PublicKey(n=3233, e=17)
```
```

--------------------------------

### Import rsa package

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.md

Import the rsa package to access its public API.

```python
import rsa
```

--------------------------------

### CryptoOperation.__call__

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Runs the program by orchestrating the CLI workflow: parse arguments, read key, read input, perform operation, and write output.

```APIDOC
## `__call__`

### Description
Runs the program: `parse_cli` → `read_key(argv[0], keyform)` → `read_infile` → `perform_operation` → `write_outfile`. Prints the operation name (`operation_progressive.title()`) to stderr.

### Method
`__call__`

### Signature
```python
def __call__(self) -> None:
```

### Parameters
None

### Returns
None
```

--------------------------------

### __call__ method

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Runs the CLI program by orchestrating parsing, key reading, input reading, operation, and output writing. Prints the operation name to stderr.

```python
def __call__(self) -> None:

```

--------------------------------

### SignOperation usage command

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Command-line usage for signing a file with a private key and hash method.

```bash
pyrsa-sign -i message.txt -o message.sig private.pem SHA-256
```

--------------------------------

### Basic usage of bytes2int and int2bytes

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.transform.md

Shows converting between bytes and integers, including the default dropping of leading zeroes and padding with fill_size.

```python
from rsa.transform import bytes2int, int2bytes

n = bytes2int(b"\x00\x01\x02")
assert int2bytes(n) == b"\x01\x02"          # leading zero dropped by default
assert int2bytes(n, fill_size=4) == b"\x00\x00\x01\x02"
```

--------------------------------

### VerifyOperation usage command

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Command-line usage for verifying a signature with a public key and signature file.

```bash
pyrsa-verify -i message.txt public.pem message.sig
```

--------------------------------

### Verify a file-like object with rsa.verify()

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/usage.rst

Verifies a signature for a file-like object. The file is hashed in 1024-byte blocks.

```pycon
>>> with open('somefile', 'rb') as msgfile:
...     rsa.verify(msgfile, signature, pubkey)
```

--------------------------------

### EncryptOperation usage command

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Command-line usage for encrypting a file with a public key.

```bash
pyrsa-encrypt -i plaintext.txt -o ciphertext.bin public.pem
```

--------------------------------

### Generate OpenSSL RSA key and convert to Python-RSA public key

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/compatibility.rst

Generate a 512-bit RSA key with OpenSSL, then convert it to a Python-RSA-compatible public key using the pyrsa-priv2pub command. The private key must be created first before extracting the public key.

```default
openssl genrsa -out myprivatekey.pem 512
```

```default
pyrsa-priv2pub -i myprivatekey.pem -o mypublickey.pem
```

--------------------------------

### PublicKey constructor

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Constructor inherited from AbstractKey. Initializes a public key with the modulus n and public exponent e.

```python
PublicKey(n: int, e: int)
```

--------------------------------

### CryptoOperation.parse_cli

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Parses command-line options using optparse, including -i/--input, -o/--output, and --keyform. Exits with status 1 if the positional argument count is incorrect.

```APIDOC
## `parse_cli`

### Description
Parses options with `optparse`. Options: `-i/--input`, `-o/--output` (if `has_output`), and `--keyform` (choice `PEM`/`DER`, default `PEM`). Exits with status 1 (prints usage) when the positional argument count differs from `expected_cli_args`. Returns `(opts, args)`.

### Method
`parse_cli`

### Signature
```python
def parse_cli(self) -> typing.Tuple[optparse.Values, typing.List[str]]:
```

### Parameters
None

### Returns
- **typing.Tuple[optparse.Values, typing.List[str]]** - A tuple of parsed options and positional arguments.
```

--------------------------------

### Import Python-RSA version 2.0

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/upgrading.rst

Use this import to access the older, less secure version 2.0 of Python-RSA. This is intended only for gradual upgrades and will generate warnings.

```python
import rsa._version200 as rsa
```

--------------------------------

### PrivateKey._load_pkcs1_pem

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Loads a private key from PKCS#1 PEM-encoded bytes.

```APIDOC
## `PrivateKey._load_pkcs1_pem` (classmethod)

### Description
Loads a private key from PKCS#1 PEM-encoded bytes.

### Method
Classmethod

### Signature
```python
@classmethod
def _load_pkcs1_pem(cls, keyfile: bytes) -> "PrivateKey":
```

### Parameters
- **keyfile** (bytes) - Required - The PEM-encoded key data.

### Returns
- **PrivateKey** - The loaded private key.
```

--------------------------------

### Encrypt with Python-RSA and decrypt with OpenSSL

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/compatibility.rst

Demonstrates encryption and decryption interoperability between Python-RSA and OpenSSL. The output shows the decrypted message 'hello there'.

```default
$ echo hello there > testfile.txt
$ pyrsa-encrypt -i testfile.txt -o testfile.rsa publickey.pem
$ openssl rsautl -in testfile.rsa -inkey privatekey.pem -decrypt
hello there
```

--------------------------------

### Generate key pair, encrypt, and decrypt

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.md

Generate a 512-bit key pair, encrypt a message, and decrypt it back. The plaintext must be at most 53 bytes due to PKCS#1 v1.5 padding.

```python
import rsa

(pub_key, priv_key) = rsa.newkeys(512)

ciphertext = rsa.encrypt(b"secret message", pub_key)
plaintext = rsa.decrypt(ciphertext, priv_key)
assert plaintext == b"secret message"
```

--------------------------------

### Catching errors in consumer code

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/errors.md

Shows how to catch rsa.DecryptionError, rsa.VerificationError, rsa.pkcs1.CryptoError, and common.NotRelativePrimeError when using rsa.decrypt, rsa.verify, rsa.newkeys, and rsa.key.calculate_keys_custom_exponent.

```python
import rsa
from rsa import common

# Cryptographic scheme failures
try:
    rsa.decrypt(ciphertext, priv)
except rsa.DecryptionError:
    pass  # === rsa.pkcs1.DecryptionError

try:
    rsa.verify(message, sig, pub)
except rsa.VerificationError:
    pass

# Catch any pkcs1 failure at once
try:
    rsa.decrypt(ciphertext, priv)
    rsa.verify(message, sig, pub)
except rsa.pkcs1.CryptoError:
    pass

# Key-generation / modular-arithmetic failures
try:
    rsa.newkeys(1024) if False else rsa.key.calculate_keys_custom_exponent(5, 3, 9)
except common.NotRelativePrimeError as ex:
    print(ex.a, ex.b, ex.d)  # 9, phi_n, divider
except ValueError:
    pass
```

--------------------------------

### AbstractKey.load_pkcs1 classmethod signature

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Classmethod to load a PKCS#1 key from bytes. Dispatches to _load_pkcs1_pem or _load_pkcs1_der based on format.

```python
@classmethod
def load_pkcs1(cls: typing.Type[T], keyfile: bytes, format: str = "PEM") -> T:
```

--------------------------------

### Sign a file-like object with rsa.sign()

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/usage.rst

Signs a file-like object. If the object has a read(int) method, it is treated as a file and hashed in 1024-byte blocks.

```pycon
>>> with open('somefile', 'rb') as msgfile:
...     signature = rsa.sign(msgfile, privkey, 'SHA-1')
```

--------------------------------

### parse_cli method

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Parses command-line options using optparse, handling -i/--input, -o/--output, and --keyform. Exits with status 1 if the positional argument count is incorrect.

```python
def parse_cli(self) -> typing.Tuple[optparse.Values, typing.List[str]]:

```

--------------------------------

### Import Python-RSA version 1.3.3

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/upgrading.rst

Use this import to access the older, less secure version 1.3.3 of Python-RSA. This is intended only for gradual upgrades and will generate warnings.

```python
import rsa._version133 as rsa
```

--------------------------------

### PublicKey.__getstate__

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Provides pickling support by returning the key's state as a tuple of (n, e).

```APIDOC
## PublicKey.__getstate__

### Description
Provides pickling support by returning the key's state as a tuple of (n, e).

### Method
__getstate__

### Signature
```python
def __getstate__(self) -> typing.Tuple[int, int]:
```

### Returns
(tuple) A tuple containing (n, e).

### Example
```python
import pickle
key = rsa.PublicKey(n=3233, e=17)
state = key.__getstate__()
print(state)  # (3233, 17)
```
```

--------------------------------

### PrivateKey.__getstate__

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Returns the state of the key for pickling. Returns an 8-tuple for standard keys or an 11-tuple for multi-prime keys.

```APIDOC
## `PrivateKey.__getstate__`

### Description
Returns the state of the key for pickling. Returns an 8-tuple for standard keys or an 11-tuple for multi-prime keys.

### Method
Method

### Signature
```python
def __getstate__(self) -> typing.Tuple:
```

### Returns
- **typing.Tuple** - The state tuple.
```

--------------------------------

### PrivateKey._load_pkcs1_der

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Loads a private key from PKCS#1 DER-encoded bytes.

```APIDOC
## `PrivateKey._load_pkcs1_der` (classmethod)

### Description
Loads a private key from PKCS#1 DER-encoded bytes.

### Method
Classmethod

### Signature
```python
@classmethod
def _load_pkcs1_der(cls, keyfile: bytes) -> "PrivateKey":
```

### Parameters
- **keyfile** (bytes) - Required - The DER-encoded key data.

### Returns
- **PrivateKey** - The loaded private key.

### Errors
- Raises `ValueError` if the ASN.1 version field is not 0.
- Warns (`UserWarning`) if the stored CRT values disagree with recomputed ones.
```

--------------------------------

### Clone repository with Git

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/installation.rst

Clones the Python-RSA source code from GitHub for development.

```default
git clone https://github.com/sybrenstuvel/python-rsa.git
```

--------------------------------

### CryptoOperation constructor

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Initializes the operation by formatting usage and help strings with the subclass's class attributes.

```python
def __init__(self) -> None:

```

--------------------------------

### perform_operation abstract method

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Abstract method that subclasses must implement to perform the actual encryption, decryption, signing, or verification. Returns the data to write to the output.

```python
@abc.abstractmethod
def perform_operation(
    self, indata: bytes, key: rsa.key.AbstractKey, cli_args: Indexable
) -> typing.Any:

```

--------------------------------

### Verify a valid signature with rsa.verify()

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/usage.rst

Verifies a signature using rsa.verify(). On success, returns the hash algorithm used as a string.

```pycon
>>> message = 'Go left at the blue tree'.encode()
>>> rsa.verify(message, signature, pubkey)
'SHA-1'
```

--------------------------------

### Error handling for int2bytes

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.transform.md

Demonstrates ValueError for negative numbers and OverflowError when fill_size is too small.

```python
from rsa.transform import int2bytes

try:
    int2bytes(-5)
except ValueError as ex:
    print(ex)

try:
    int2bytes(2**32, fill_size=4)  # needs 5 bytes
except OverflowError as ex:
    print(ex)
```

--------------------------------

### Use old and new versions together for decryption and re-encryption

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/upgrading.rst

Import both version 2.0 and the current version (3.0) to decrypt old messages with the old version and re-encrypt them with the new version. This will generate warnings because the old code is less secure.

```python
import rsa._version200 as rsa200
import rsa                        # this imports version 3.0

decrypted = rsa200.decrypt(old_crypto, version_200_private_key)
new_crypto = rsa.encrypt(decrypted, version_3_public_key)
```

--------------------------------

### PrivateKey constructor signature

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Constructor for rsa.PrivateKey. Takes n, e, d, p, q, and optional rs for multi-prime keys. Derives exp1, exp2, coef, ds, and ts attributes.

```python
def __init__(
    self,
    n: int,
    e: int,
    d: int,
    p: int,
    q: int,
    rs: typing.Optional[typing.List[int]] = None,
) -> None:
```

--------------------------------

### Calling decrypt_int_fast from PrivateKey.blinded_decrypt

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.core.md

Shows the exact call to rsa.core.decrypt_int_fast as used in rsa.key.PrivateKey.blinded_decrypt, passing the blinded value and the CRT coefficient lists.

```python
rsa.core.decrypt_int_fast(
    blinded,
    [self.p, self.q] + self.rs,
    [self.exp1, self.exp2] + self.ds,
    [self.coef] + self.ts,
)
```

--------------------------------

### AbstractKey.save_pkcs1

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Serializes the key to bytes in PEM or DER format.

```APIDOC
## AbstractKey.save_pkcs1

### Description
Serializes the key to bytes in PEM or DER format.

### Method
Method

### Signature
```python
def save_pkcs1(self, format: str = "PEM") -> bytes:
```

### Parameters
- **format** (str) - Optional, default `"PEM"` - Format to use: `"PEM"` or `"DER"`.

### Returns
The key serialized as `bytes` in PEM (default) or DER.
```

--------------------------------

### HASH_ASN1 dictionary in rsa.pkcs1

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/types.md

Maps hash names to ASN.1 DER DigestInfo algorithm-identifier prefixes. Used by rsa.pkcs1.sign_hash (prepends), rsa.pkcs1._find_method_hash (searches asn1code in clearsig), and thus rsa.pkcs1.verify and rsa.pkcs1.find_signature_hash.

```python
HASH_ASN1 = {
    "MD5": b"\x30\x20\x30\x0c\x06\x08\x2a\x86\x48\x86\xf7\x0d\x02\x05\x05\x00\x04\x10",
    "SHA-1": b"\x30\x21\x30\x09\x06\x05\x2b\x0e\x03\x02\x1a\x05\x00\x04\x14",
    "SHA-224": b"\x30\x2d\x30\x0d\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x04\x05\x00\x04\x1c",
    "SHA-256": b"\x30\x31\x30\x0d\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x01\x05\x00\x04\x20",
    "SHA-384": b"\x30\x41\x30\x0d\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x02\x05\x00\x04\x30",
    "SHA-512": b"\x30\x51\x30\x0d\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x03\x05\x00\x04\x40",
    "SHA3-256": b"\x30\x31\x30\x0d\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x08\x05\x00\x04\x20",
    "SHA3-384": b"\x30\x41\x30\x0d\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x09\x05\x00\x04\x30",
    "SHA3-512": b"\x30\x51\x30\x0d\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x0a\x05\x00\x04\x40",
}
```

--------------------------------

### newkeys and gen_keys return tuple signatures

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/types.md

Signatures of newkeys and gen_keys. newkeys returns (PublicKey, PrivateKey). gen_keys returns (p, q, e, d) for two-prime keys, or (p, q, e, d, rs) for multi-prime keys.

```python
def newkeys(...) -> typing.Tuple[PublicKey, PrivateKey]:
def gen_keys(...) -> typing.Tuple:
```

--------------------------------

### Sign, verify, and handle failed verification

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.md

Sign a payload with SHA-256, verify it, and catch a VerificationError when the payload is tampered with.

```python
import rsa

(pub_key, priv_key) = rsa.newkeys(512)

signature = rsa.sign(b"payload", priv_key, "SHA-256")
hash_name = rsa.verify(b"payload", signature, pub_key)
print("verified with", hash_name)  # 'SHA-256'

try:
    rsa.verify(b"tampered payload", signature, pub_key)
except rsa.VerificationError:
    print("signature does not match")
```

--------------------------------

### CryptoOperation.read_key

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Reads a key file in binary mode and loads it using the key class's load_pkcs1 method.

```APIDOC
## `read_key`

### Description
Reads the key file in binary mode and loads it with `self.key_class.load_pkcs1(keydata, keyform)`. Prints progress to stderr.

### Method
`read_key`

### Signature
```python
def read_key(self, filename: str, keyform: str) -> rsa.key.AbstractKey:
```

### Parameters
- **filename** (str) - Required - Path to the key file.
- **keyform** (str) - Required - Format of the key (`PEM` or `DER`).

### Returns
- **rsa.key.AbstractKey** - The loaded key object.
```

--------------------------------

### PrivateKey.__getitem__

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.key.md

Provides dictionary-like access to key attributes.

```APIDOC
## `PrivateKey.__getitem__`

### Description
Provides dictionary-like access to key attributes.

### Method
Method

### Signature
```python
def __getitem__(self, key: str) -> int:
```

### Parameters
- **key** (str) - Required - The attribute name to retrieve.

### Returns
- **int** - The value of the attribute.
```

--------------------------------

### write_outfile method

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Writes the given data to the named file in binary mode, or to sys.stdout.buffer if no filename is provided.

```python
def write_outfile(self, outdata: bytes, outname: str) -> None:

```

--------------------------------

### Generate an RSA key pair with rsa.newkeys()

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/doc/usage.rst

Use rsa.newkeys(512) to generate a public and private key pair. The function returns a tuple of (pubkey, privkey).

```pycon
>>> import rsa
>>> (pubkey, privkey) = rsa.newkeys(512)
```

--------------------------------

### DecryptOperation usage command

Source: https://github.com/sybrenstuvel/python-rsa/blob/main/_autodocs/api-reference/rsa.cli.md

Command-line usage for decrypting a file with a private key.

```bash
pyrsa-decrypt -i ciphertext.bin -o plaintext.txt private.pem
```
Tokens:
Raw