0
# CLI Tools
1

2
Command-line utilities for RSA key generation, encryption, decryption, signing, and signature verification. These tools provide direct access to RSA operations from the shell without requiring Python programming.
3

4
## Available Commands
5

6
The RSA library provides six command-line tools installed as executable scripts:
7

8
- **pyrsa-keygen** - Generate RSA key pairs
9
- **pyrsa-encrypt** - Encrypt data with public key
10
- **pyrsa-decrypt** - Decrypt data with private key
11
- **pyrsa-sign** - Sign data with private key
12
- **pyrsa-verify** - Verify signature with public key
13
- **pyrsa-priv2pub** - Convert private key to public key
14

15
## Capabilities
16

17
### Key Generation
18

19
Generate RSA key pairs and save them to files in PEM or DER format.
20

21
**Command:** `pyrsa-keygen`
22

23
**Usage:**
24
```bash
25
pyrsa-keygen [options] keysize
26

27
# Generate 2048-bit key pair to stdout (private key)
28
pyrsa-keygen 2048
29

30
# Generate keys and save to files
31
pyrsa-keygen --out private.pem --pubout public.pem 2048
32

33
# Generate in DER format
34
pyrsa-keygen --form DER --out private.der --pubout public.der 2048
35
```
36

37
**Options:**
38
- `keysize` - Key size in bits (e.g., 1024, 2048, 4096)
39
- `--out FILE` - Output filename for private key (default: stdout)
40
- `--pubout FILE` - Output filename for public key (optional)
41
- `--form FORMAT` - Key format: PEM (default) or DER
42

43
**Examples:**
44
```bash
45
# Generate 2048-bit keys with PEM format
46
pyrsa-keygen --out my_private_key.pem --pubout my_public_key.pem 2048
47

48
# Generate 4096-bit key pair in DER format
49
pyrsa-keygen --form DER --out private.der --pubout public.der 4096
50

51
# Generate key to stdout and redirect
52
pyrsa-keygen 2048 > private_key.pem
53
```
54

55
### Encryption
56

57
Encrypt data using an RSA public key, reading from stdin and writing to stdout.
58

59
**Command:** `pyrsa-encrypt`
60

61
**Usage:**
62
```bash
63
pyrsa-encrypt [options]
64

65
# Encrypt data from stdin
66
echo "secret message" | pyrsa-encrypt --key public.pem
67

68
# Encrypt a file
69
pyrsa-encrypt --key public.pem < message.txt > encrypted.bin
70

71
# Specify input/output files
72
pyrsa-encrypt --key public.pem --input message.txt --output encrypted.bin
73
```
74

75
**Options:**
76
- `--key FILE` - Public key file (PEM or DER format)
77
- `--input FILE` - Input file (default: stdin)
78
- `--output FILE` - Output file (default: stdout)
79
- `--form FORMAT` - Key format: PEM (default) or DER
80

81
**Examples:**
82
```bash
83
# Encrypt a message from command line
84
echo "Hello World" | pyrsa-encrypt --key public_key.pem > encrypted.bin
85

86
# Encrypt a file
87
pyrsa-encrypt --key public_key.pem --input document.txt --output document.encrypted
88
```
89

90
### Decryption
91

92
Decrypt data using an RSA private key, reading encrypted data from stdin and writing decrypted data to stdout.
93

94
**Command:** `pyrsa-decrypt`
95

96
**Usage:**
97
```bash
98
pyrsa-decrypt [options]
99

100
# Decrypt data from stdin
101
pyrsa-decrypt --key private.pem < encrypted.bin
102

103
# Decrypt with file specification  
104
pyrsa-decrypt --key private.pem --input encrypted.bin --output decrypted.txt
105
```
106

107
**Options:**
108
- `--key FILE` - Private key file (PEM or DER format)
109
- `--input FILE` - Input file (default: stdin)
110
- `--output FILE` - Output file (default: stdout)
111
- `--form FORMAT` - Key format: PEM (default) or DER
112

113
**Examples:**
114
```bash
115
# Decrypt and display message
116
pyrsa-decrypt --key private_key.pem < encrypted.bin
117

118
# Decrypt file to file
119
pyrsa-decrypt --key private_key.pem --input encrypted.bin --output message.txt
120
```
121

122
### Message Signing
123

124
Create digital signatures for data using an RSA private key with specified hash algorithms.
125

126
**Command:** `pyrsa-sign`
127

128
**Usage:**
129
```bash
130
pyrsa-sign [options]
131

132
# Sign data from stdin with SHA-256
133
echo "document content" | pyrsa-sign --key private.pem --hash SHA-256
134

135
# Sign a file
136
pyrsa-sign --key private.pem --hash SHA-256 --input document.txt --output signature.bin
137
```
138

139
**Options:**
140
- `--key FILE` - Private key file (PEM or DER format)
141
- `--hash ALGORITHM` - Hash algorithm: SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, MD5
142
- `--input FILE` - Input file (default: stdin)
143
- `--output FILE` - Output file (default: stdout)
144
- `--form FORMAT` - Key format: PEM (default) or DER
145

146
**Examples:**
147
```bash
148
# Sign a document with SHA-256
149
pyrsa-sign --key private_key.pem --hash SHA-256 --input contract.txt --output contract.sig
150

151
# Sign message from stdin
152
echo "Important message" | pyrsa-sign --key private_key.pem --hash SHA-256 > message.sig
153
```
154

155
### Signature Verification
156

157
Verify digital signatures to ensure data authenticity and integrity.
158

159
**Command:** `pyrsa-verify`
160

161
**Usage:**
162
```bash
163
pyrsa-verify [options]
164

165
# Verify signature (reads original data from stdin, signature from file)
166
pyrsa-verify --key public.pem --signature signature.bin < original_data.txt
167

168
# Verify with explicit files
169
pyrsa-verify --key public.pem --signature signature.bin --input original_data.txt
170
```
171

172
**Options:**
173
- `--key FILE` - Public key file (PEM or DER format)
174
- `--signature FILE` - Signature file to verify
175
- `--input FILE` - Original data file (default: stdin)
176
- `--form FORMAT` - Key format: PEM (default) or DER
177

178
**Examples:**
179
```bash
180
# Verify a document signature
181
pyrsa-verify --key public_key.pem --signature contract.sig --input contract.txt
182

183
# Verify with data from stdin
184
echo "Important message" | pyrsa-verify --key public_key.pem --signature message.sig
185
```
186

187
### Private to Public Key Conversion
188

189
Extract the public key from a private key file.
190

191
**Command:** `pyrsa-priv2pub`
192

193
**Usage:**
194
```bash
195
pyrsa-priv2pub [options]
196

197
# Convert private key to public key
198
pyrsa-priv2pub --input private.pem --output public.pem
199

200
# Convert from stdin to stdout
201
pyrsa-priv2pub < private_key.pem > public_key.pem
202
```
203

204
**Options:**
205
- `--input FILE` - Private key input file (default: stdin)
206
- `--output FILE` - Public key output file (default: stdout)
207
- `--form FORMAT` - Key format: PEM (default) or DER
208

209
**Examples:**
210
```bash
211
# Extract public key from private key
212
pyrsa-priv2pub --input my_private_key.pem --output my_public_key.pem
213

214
# Convert DER format keys
215
pyrsa-priv2pub --form DER --input private.der --output public.der
216
```
217

218
## Common Workflows
219

220
### Complete Key Generation and Usage Workflow
221

222
```bash
223
# 1. Generate key pair
224
pyrsa-keygen --out private_key.pem --pubout public_key.pem 2048
225

226
# 2. Encrypt a message
227
echo "Secret message" | pyrsa-encrypt --key public_key.pem > encrypted.bin
228

229
# 3. Decrypt the message
230
pyrsa-decrypt --key private_key.pem < encrypted.bin
231

232
# 4. Sign a document
233
pyrsa-sign --key private_key.pem --hash SHA-256 --input document.txt --output document.sig
234

235
# 5. Verify the signature
236
pyrsa-verify --key public_key.pem --signature document.sig --input document.txt
237
```
238

239
### File Encryption/Decryption
240

241
```bash
242
# Encrypt a file
243
pyrsa-encrypt --key recipient_public.pem --input secret_file.txt --output secret_file.encrypted
244

245
# Send encrypted file to recipient...
246

247
# Recipient decrypts the file
248
pyrsa-decrypt --key recipient_private.pem --input secret_file.encrypted --output decrypted_file.txt
249
```
250

251
### Document Signing and Verification
252

253
```bash
254
# Sign an important document
255
pyrsa-sign --key signer_private.pem --hash SHA-256 --input contract.pdf --output contract.sig
256

257
# Verify the signature
258
pyrsa-verify --key signer_public.pem --signature contract.sig --input contract.pdf
259
```
260

261
## CLI Implementation Details
262

263
The CLI tools are implemented as Python functions that handle:
264

265
- **Argument parsing** with `optparse` module
266
- **File I/O operations** for reading keys and data
267
- **Error handling** with informative error messages
268
- **Format detection** for PEM/DER key formats
269
- **Stream processing** for stdin/stdout operations
270

271
### CLI Functions
272

273
The CLI tools are implemented as Python functions that are registered as console script entry points:
274

275
```python { .api }
276
def keygen() -> None:
277
    """CLI key generation function (entry point for pyrsa-keygen)."""
278

279
def encrypt() -> None:
280
    """CLI encryption function (entry point for pyrsa-encrypt)."""
281

282
def decrypt() -> None:
283
    """CLI decryption function (entry point for pyrsa-decrypt)."""
284

285
def sign() -> None:
286
    """CLI signing function (entry point for pyrsa-sign)."""
287

288
def verify() -> None:
289
    """CLI verification function (entry point for pyrsa-verify)."""
290

291
def private_to_public() -> None:
292
    """CLI private to public key conversion (entry point for pyrsa-priv2pub)."""
293
```
294

295
## Error Handling
296

297
CLI tools provide clear error messages for common issues:
298

299
- **Invalid key files** - Format errors, file not found, permissions
300
- **Wrong key types** - Using private key where public key expected, etc.
301
- **Encryption/decryption failures** - Wrong keys, corrupted data
302
- **Signature verification failures** - Invalid signatures, key mismatches
303
- **File I/O errors** - Missing files, permission denied, disk full
304

305
## Security Considerations
306

307
### Key File Security
308
- Store private keys with restricted file permissions (`chmod 600`)
309
- Never transmit private keys over insecure channels
310
- Use secure key generation environments
311

312
### Data Processing
313
- CLI tools process data through stdin/stdout for security (no temporary files)
314
- Large files are processed in memory (consider available RAM)
315
- Original data is not modified during signing/verification
316

317
### Hash Algorithm Selection
318
- Use SHA-256 or stronger for new signatures
319
- Avoid MD5 and SHA-1 for new applications
320
- Consider algorithm compatibility with verification systems