0
# RSA
1

2
A pure-Python implementation of the RSA cryptographic algorithm supporting encryption, decryption, digital signing, and signature verification according to PKCS#1 version 1.5 standards. This library provides both a Python API for programmatic use and command-line tools for direct RSA operations.
3

4
## Package Information
5

6
- **Package Name**: rsa
7
- **Language**: Python
8
- **Installation**: `pip install rsa`
9
- **Dependencies**: pyasn1 (>=0.1.3)
10

11
## Core Imports
12

13
```python
14
import rsa
15
```
16

17
Import specific functions:
18

19
```python
20
from rsa import newkeys, encrypt, decrypt, sign, verify
21
from rsa import PublicKey, PrivateKey
22
```
23

24
## Basic Usage
25

26
```python
27
import rsa
28

29
# Generate a key pair
30
(public_key, private_key) = rsa.newkeys(512)
31

32
# Encrypt a message
33
message = b'hello world'
34
encrypted = rsa.encrypt(message, public_key)
35

36
# Decrypt the message
37
decrypted = rsa.decrypt(encrypted, private_key)
38
print(decrypted.decode())  # outputs: hello world
39

40
# Sign a message
41
signature = rsa.sign(message, private_key, 'SHA-256')
42

43
# Verify the signature
44
hash_method = rsa.verify(message, signature, public_key)
45
print(hash_method)  # outputs: SHA-256
46
```
47

48
## Architecture
49

50
The RSA library is organized around three main components:
51

52
- **Key Management**: Key pair generation, loading/saving keys in various formats (PEM, DER)
53
- **Cryptographic Operations**: PKCS#1 v1.5 encryption/decryption and signing/verification
54
- **CLI Tools**: Command-line utilities for key generation and cryptographic operations
55

56
The library implements pure-Python RSA operations without external cryptographic dependencies, making it suitable for educational purposes and environments requiring minimal dependencies.
57

58
## Capabilities
59

60
### Key Management
61

62
RSA key pair generation and key object management including loading/saving keys in PKCS#1 PEM/DER formats and OpenSSL compatibility.
63

64
```python { .api }
65
def newkeys(nbits: int, accurate: bool = True, poolsize: int = 1, exponent: int = 65537) -> Tuple[PublicKey, PrivateKey]: ...
66

67
class PublicKey:
68
    def __init__(self, n: int, e: int): ...
69
    def save_pkcs1_pem(self) -> bytes: ...
70
    def save_pkcs1_der(self) -> bytes: ...
71

72
class PrivateKey:
73
    def __init__(self, n: int, e: int, d: int, p: int, q: int): ...
74
    def save_pkcs1_pem(self) -> bytes: ...
75
    def save_pkcs1_der(self) -> bytes: ...
76
```
77

78
[Key Management](./key-management.md)
79

80
### Cryptographic Operations
81

82
PKCS#1 v1.5 encryption, decryption, signing, and signature verification with support for multiple hash algorithms.
83

84
```python { .api }
85
def encrypt(message: bytes, pub_key: PublicKey) -> bytes: ...
86
def decrypt(crypto: bytes, priv_key: PrivateKey) -> bytes: ...
87
def sign(message: bytes, priv_key: PrivateKey, hash_method: str) -> bytes: ...
88
def verify(message: bytes, signature: bytes, pub_key: PublicKey) -> str: ...
89
def sign_hash(hash_value: bytes, priv_key: PrivateKey, hash_method: str) -> bytes: ...
90
def find_signature_hash(signature: bytes, pub_key: PublicKey) -> str: ...
91
def compute_hash(message: Union[bytes, BinaryIO], method_name: str) -> bytes: ...
92
```
93

94
[Cryptographic Operations](./crypto-operations.md)
95

96
### CLI Tools
97

98
Command-line utilities for key generation, encryption, decryption, signing, and signature verification.
99

100
```python { .api }
101
# CLI entry points available as shell commands:
102
# pyrsa-keygen - Generate RSA key pairs
103
# pyrsa-encrypt - Encrypt data with public key
104
# pyrsa-decrypt - Decrypt data with private key  
105
# pyrsa-sign - Sign data with private key
106
# pyrsa-verify - Verify signature with public key
107
# pyrsa-priv2pub - Convert private key to public key
108
```
109

110
[CLI Tools](./cli-tools.md)
111

112
## Exception Types
113

114
```python { .api }
115
class CryptoError(Exception):
116
    """Base class for all cryptographic exceptions"""
117

118
class DecryptionError(CryptoError):
119
    """Raised when decryption fails"""
120

121
class VerificationError(CryptoError):
122
    """Raised when signature verification fails"""
123
```
124

125
## Type References
126

127
```python { .api }
128
from typing import Tuple, Union, BinaryIO, Iterator, Callable
129
```
130

131
## Supported Hash Methods
132

133
- **SHA-1** - Secure Hash Algorithm 1
134
- **SHA-224** - SHA-2 224-bit
135
- **SHA-256** - SHA-2 256-bit (recommended)
136
- **SHA-384** - SHA-2 384-bit
137
- **SHA-512** - SHA-2 512-bit
138
- **MD5** - Message Digest 5 (deprecated, not recommended)
139

140
## Key Formats
141

142
- **PKCS#1 PEM** - ASCII-armored format with BEGIN/END RSA KEY headers
143
- **PKCS#1 DER** - Binary ASN.1 DER encoding
144
- **OpenSSL PEM** - OpenSSL-compatible PEM format
145
- **Pickle** - Python pickle format (with security warnings)