1BOTAN(1) BOTAN(1)
2
6 botan - Botan command line util
7
9 The botan program is a command line tool for using a broad variety of
10 functions of the Botan library in the shell.
11 All commands follow the syntax botan <command> <command-options>.
13 If botan is run with an unknown command, or without any command, or
15 with the --help option, all available commands will be printed. If a
16 particular command is run with the --help option (like botan <command>
17 --help) some information about the usage of the command is printed.
18 Starting in version 2.9, commands that take a passphrase (such as
20 gen_bcrypt or pkcs8) will also accept the literal - to mean ask for the
21 passphrase on the terminal. If supported by the operating system, echo
22 will be disabled while reading the passphrase.
23 Most arguments that take a path to a file will also accept the literal
25 - to mean the file content should be read from STDIN instead.
26
28 hash --algo=SHA-256 --buf-size=4096 --no-fsname --format=hex *files
29 Compute the algo digest over the data in any number of files. If
30 no files are listed on the command line, the input source de‐
31 faults to standard input. Unless the --no-fsname option is
32 given, the filename is printed alongside the hash, in the style
33 of tools such as sha256sum.
34
36 gen_argon2 --mem=65536 --p=1 --t=1 password
37 Calculate the Argon2 password digest of password. mem is the
38 amount of memory to use in Kb, p the parallelization parameter
39 and t the number of iterations to use.
40 check_argon2 password hash
42 Checks if the Argon2 hash of the passed password equals the
43 passed hash value.
44 gen_bcrypt --work-factor=12 password
46 Calculate the bcrypt password digest of password. work-factor is
47 an integer between 4 and 18. A higher work-factor value results
48 in a more expensive hash calculation.
49 check_bcrypt password hash
51 Checks if the bcrypt hash of the passed password equals the
52 passed hash value.
53 pbkdf_tune --algo=Scrypt --max-mem=256 --output-len=32 --check *times
55 Tunes the PBKDF algorithm specified with --algo= for the given
56 times.
57
59 hmac --hash=SHA-256 --buf-size=4096 --no-fsname key files
60 Compute the HMAC tag with the cryptographic hash function hash
61 using the key in file key over the data in files. files defaults
62 to STDIN. Unless the --no-fsname option is given, the filename
63 is printed alongside the HMAC value.
64
66 encryption --buf-size=4096 --decrypt --mode= --key= --iv= --ad=
67 Encrypt a given file with the specified mode. If --decrypt is
68 provided the file is decrypted instead.
69
71 keygen --algo=RSA --params= --passphrase= --pbe= --pbe-millis=300
72 --provider= --der-out
73 Generate a PKCS #8 algo private key. If der-out is passed, the
74 pair is BER encoded. Otherwise, PEM encoding is used. To pro‐
75 tect the PKCS #8 formatted key, it is recommended to encrypt it
76 with a provided passphrase. pbe is the name of the desired en‐
77 cryption algorithm, which uses pbe-millis milliseconds to derive
78 the encryption key from the passed passphrase. Algorithm spe‐
79 cific parameters, as the desired bit length of an RSA key, can
80 be passed with params.
81 • For RSA params specifies the bit length of the RSA modulus.
83 It defaults to 3072.
84 • For DH params specifies the DH parameters. It defaults to
86 modp/ietf/2048.
87 • For DSA params specifies the DSA parameters. It defaults to
89 dsa/botan/2048.
90 • For EC algorithms params specifies the elliptic curve. It
92 defaults to secp256r1.
93 The default pbe algorithm is "PBES2(AES-256/CBC,SHA-256)".
95 With PBES2 scheme, you can select any CBC or GCM mode cipher
97 which has an OID defined (such as 3DES, Camellia, SM4, Twofish
98 or Serpent). However most other implementations support only AES
99 or 3DES in CBC mode. You can also choose Scrypt instead of
100 PBKDF2, by using "Scrypt" instead of the name of a hash func‐
101 tion, for example "PBES2(AES-256/CBC,Scrypt)". Scrypt is also
102 supported by some other implementations including OpenSSL.
103 pkcs8 --pass-in= --pub-out --der-out --pass-out= --pbe= --pbe-mil‐
105 lis=300 key
106 Open a PKCS #8 formatted key at key. If key is encrypted, the
107 passphrase must be passed as pass-in. It is possible to (re)en‐
108 crypt the read key with the passphrase passed as pass-out. The
109 parameters pbe-millis and pbe work similarly to keygen.
110 sign --der-format --passphrase= --hash=SHA-256 --emsa= --provider= key
112 file
113 Sign the data in file using the PKCS #8 private key key. If key
114 is encrypted, the used passphrase must be passed as pass-in.
115 emsa specifies the signature scheme and hash the cryptographic
116 hash function used in the scheme.
117 • For RSA signatures EMSA4 (RSA-PSS) is the default scheme.
119 • For ECDSA and DSA emsa defaults to EMSA1 (signing the hash
121 directly)
122 For ECDSA and DSA, the option --der-format outputs the signature
124 as an ASN.1 encoded blob. Some other tools (including openssl)
125 default to this format.
126 The signature is formatted for your screen using base64.
128 verify --der-format --hash=SHA-256 --emsa= pubkey file signature
130 Verify the authenticity of the data in file with the provided
131 signature signature and the public key pubkey. Similarly to the
132 signing process, emsa specifies the signature scheme and hash
133 the cryptographic hash function used in the scheme.
134 gen_dl_group --pbits=1024 --qbits=0 --seed= --type=subgroup
136 Generate ANSI X9.42 encoded Diffie-Hellman group parameters.
137 • If type=subgroup is passed, the size of the prime subgroup
139 q is sampled as a prime of qbits length and p is pbits
140 long. If qbits is not passed, its length is estimated from
141 pbits as described in RFC 3766.
142 • If type=strong is passed, p is sampled as a safe prime with
144 length pbits and the prime subgroup has size q with pbits-1
145 length.
146 • If type=dsa is used, p and q are generated by the algorithm
148 specified in FIPS 186-4. If the --seed parameter is used,
149 it allows to select the seed value, instead of one being
150 randomly generated. If the seed does not in fact generate a
151 valid DSA group, the command will fail.
152 dl_group_info --pem name
154 Print raw Diffie-Hellman parameters (p,g) of the standardized DH
155 group name. If pem is set, the X9.42 encoded group is printed.
156 ec_group_info --pem name
158 Print raw elliptic curve domain parameters of the standardized
159 curve name. If pem is set, the encoded domain is printed.
160 pk_encrypt --aead=AES-256/GCM rsa_pubkey datafile
162 Encrypts datafile using the specified AEAD algorithm, under a
163 key protected by the specified RSA public key.
164 pk_decrypt rsa_privkey datafile
166 Decrypts a file encrypted with pk_encrypt. If the key is en‐
167 crypted using a password, it will be prompted for on the termi‐
168 nal.
169 fingerprint --no-fsname --algo=SHA-256 *keys
171 Calculate the public key fingerprint of the keys.
172 pk_workfactor --type=rsa bits
174 Provide an estimate of the strength of a public key based on
175 it's size. --type= can be "rsa", "dl" or "dl_exp".
176
178 gen_pkcs10 key CN --country= --organization= --ca --path-limit=1
179 --email= --dns= --ext-ku= --key-pass= --hash=SHA-256 --emsa=
180 Generate a PKCS #10 certificate signing request (CSR) using the
181 passed PKCS #8 private key key. If the private key is encrypted,
182 the decryption passphrase key-pass has to be passed.*emsa* spec‐
183 ifies the padding scheme to be used when calculating the signa‐
184 ture.
185 • For RSA keys EMSA4 (RSA-PSS) is the default scheme.
187 • For ECDSA, DSA, ECGDSA, ECKCDSA and GOST-34.10 keys emsa
189 defaults to EMSA1.
190 gen_self_signed key CN --country= --dns= --organization= --email=
192 --path-limit=1 --days=365 --key-pass= --ca --hash=SHA-256 --emsa= --der
193 Generate a self signed X.509 certificate using the PKCS #8 pri‐
194 vate key key. If the private key is encrypted, the decryption
195 passphrase key-pass has to be passed. If ca is passed, the cer‐
196 tificate is marked for certificate authority (CA) usage. emsa
197 specifies the padding scheme to be used when calculating the
198 signature.
199 • For RSA keys EMSA4 (RSA-PSS) is the default scheme.
201 • For ECDSA, DSA, ECGDSA, ECKCDSA and GOST-34.10 keys emsa
203 defaults to EMSA1.
204 sign_cert --ca-key-pass= --hash=SHA-256 --duration=365 --emsa= ca_cert
206 ca_key pkcs10_req
207 Create a CA signed X.509 certificate from the information con‐
208 tained in the PKCS #10 CSR pkcs10_req. The CA certificate is
209 passed as ca_cert and the respective PKCS #8 private key as
210 ca_key. If the private key is encrypted, the decryption
211 passphrase ca-key-pass has to be passed. The created certificate
212 has a validity period of duration days. emsa specifies the pad‐
213 ding scheme to be used when calculating the signature. emsa de‐
214 faults to the padding scheme used in the CA certificate.
215 ocsp_check --timeout=3000 subject issuer
217 Verify an X.509 certificate against the issuers OCSP responder.
218 Pass the certificate to validate as subject and the CA certifi‐
219 cate as issuer.
220 cert_info --fingerprint file
222 Parse X.509 PEM certificate and display data fields. If --fin‐
223 gerprint is used, the certificate's fingerprint is also printed.
224 cert_verify subject *ca_certs
226 Verify if the provided X.509 certificate subject can be success‐
227 fully validated. The list of trusted CA certificates is passed
228 with ca_certs, which is a list of one or more certificates.
229 trust_roots --dn --dn-only --display
231 List the certificates in the system trust store.
232
234 The --policy= argument of the TLS commands specifies the TLS policy to
235 use. The policy can be any of the the strings "default", "suiteb_128",
236 "suiteb_192", "bsi", "strict", or "all" to denote built-in policies, or
237 it can name a file from which a policy description will be read.
238 tls_ciphers --policy=default --version=tls1.2
240 Prints the list of ciphersuites that will be offered under a
241 particular policy/version.
242 tls_client host --port=443 --print-certs --policy=default --tls1.0
244 --tls1.1 --tls1.2 --skip-system-cert-store --trusted-cas= --session-db=
245 --session-db-pass= --next-protocols= --type=tcp
246 Implements a testing TLS client, which connects to host via TCP
247 or UDP on port port. The TLS version can be set with the flags
248 tls1.0, tls1.1 and tls1.2 of which the lowest specified version
249 is automatically chosen. If none of the TLS version flags is
250 set, the latest supported version is chosen. The client honors
251 the TLS policy specified with policy and prints all certificates
252 in the chain, if print-certs is passed. next-protocols is a
253 comma separated list and specifies the protocols to advertise
254 with Application-Layer Protocol Negotiation (ALPN).
255 tls_server cert key --port=443 --type=tcp --policy=default
257 --dump-traces= --max-clients=0 --socket-id=0
258 Implements a testing TLS server, which allows TLS clients to
259 connect and which echos any data that is sent to it. Binds to
260 either TCP or UDP on port port. The server uses the certificate
261 cert and the respective PKCS #8 private key key. The server hon‐
262 ors the TLS policy specified with policy. socket-id is only
263 available on FreeBSD and sets the so_user_cookie value of the
264 used socket.
265 tls_http_server cert key --port=443 --policy=default --threads=0
267 --max-clients=0 --session-db --session-db-pass=
268 Only available if Boost.Asio support was enabled. Provides a
269 simple HTTP server which replies to all requests with an infor‐
270 mational text output. The server honors the TLS policy specified
271 with policy.
272 tls_proxy listen_port target_host target_port server_cert
274 server_key--policy=default --threads=0 --max-clients=0 --session-db=
275 --session-db-pass=
276 Only available if Boost.Asio support was enabled. Listens on a
277 port and forwards all connects to a target server specified at
278 target_host and target_port.
279 tls_client_hello --hex input
281 Parse and print a TLS client hello message.
282
284 is_prime --prob=56 n
285 Test if the integer n is composite or prime with a Miller-Rabin
286 primality test with (prob+2)/2 iterations.
287 factor n
289 Factor the integer n using a combination of trial division by
290 small primes, and Pollard's Rho algorithm. It can in reasonable
291 time factor integers up to 110 bits or so.
292 gen_prime --count=1 bits
294 Samples count primes with a length of bits bits.
295 mod_inverse n mod
297 Calculates a modular inverse.
298
300 The PSK database commands are only available if sqlite3 support was
301 compiled in.
302 psk_set db db_key name psk
304 Using the PSK database named db and encrypting under the (hex)
305 key db_key, save the provided psk (also hex) under name:
306 $ botan psk_set psk.db deadba55 bunny f00fee
308 psk_get db db_key name
310 Get back a value saved with psk_set:
311 $ botan psk_get psk.db deadba55 bunny
313 f00fee
314 psk_list db db_key
316 List all values saved to the database under the given key:
317 $ botan psk_list psk.db deadba55
319 bunny
320
322 Split a file into several shares.
323 tss_split M N data_file --id= --share-prefix=share --share-suffix=tss
325 --hash=SHA-256
326 Split a file into N pieces any M of which suffices to recover
327 the original input. The ID allows specifying a unique key ID
328 which may be up to 16 bytes long, this ensures that shares can
329 be uniquely matched. If not specified a random 16 byte value is
330 used. A checksum can be appended to the data to help verify cor‐
331 rect recovery, this can be disabled using --hash=None.
332 tss_recover *shares
334 Recover some data split by tss_split. If insufficient number of
335 shares are provided an error is printed.
336
338 base32_dec file
339 Encode file to Base32.
340 base32_enc file
342 Decode Base32 encoded file.
343 base58_enc --check file
345 Encode file to Base58. If --check is provided Base58Check is
346 used.
347 base58_dec --check file
349 Decode Base58 encoded file. If --check is provided Base58Check
350 is used.
351 base64_dec file
353 Encode file to Base64.
354 base64_enc file
356 Decode Base64 encoded file.
357 hex_dec file
359 Encode file to Hex.
360 hex_enc file
362 Decode Hex encoded file.
363
365 version --full
366 Print the version number. If option --full is provided, addi‐
367 tional details are printed.
368 has_command cmd
370 Test if the command cmd is available.
371 config info_type
373 Prints build information, useful for applications which want to
374 build against the library. The info_type argument can be any of
375 prefix, cflags, ldflags, or libs. This is similar to information
376 provided by the pkg-config tool.
377 cpuid List available processor flags (AES-NI, SIMD extensions, ...).
379 cpu_clock --test-duration=500
381 Estimate the speed of the CPU cycle counter.
382 asn1print --skip-context-specific --print-limit=4096 --bin-limit=2048
384 --max-depth=64 --pem file`
385 Decode and print file with ASN.1 Basic Encoding Rules (BER). If
386 flag --pem is used, or the filename ends in .pem, then PEM en‐
387 coding is assumed. Otherwise the input is assumed to be binary
388 DER/BER.
389 http_get --redirects=1 --timeout=3000 url
391 Retrieve resource from the passed http url.
392 speed --msec=500 --format=default --ecc-groups= --provider=
394 --buf-size=1024 --clear-cpuid= --cpu-clock-speed=0 --cpu-clock-ra‐
395 tio=1.0 *algos
396 Measures the speed of the passed algos. If no algos are passed
397 all available speed tests are executed. msec (in milliseconds)
398 sets the period of measurement for each algorithm. The buf-size
399 option allows testing the same algorithm on one or more input
400 sizes, for example speed --buf-size=136,1500 AES-128/GCM tests
401 the performance of GCM for small and large packet sizes. format
402 can be "default", "table" or "json".
403 timing_test test_type --test-data-file=
405 --test-data-dir=src/tests/data/timing --warmup-runs=1000 --measure‐
406 ment-runs=10000
407 Run various timing side channel tests.
408 rng --format=hex --system --rdrand --auto --entropy --drbg --drbg-seed=
410 *bytes
411 Sample bytes random bytes from the specified random number gen‐
412 erator. If system is set, the system RNG is used. If rdrand is
413 set, the hardware RDRAND instruction is used. If auto is set,
414 AutoSeeded_RNG is used, seeded with the system RNG if available
415 or the global entropy source otherwise. If entropy is set, Au‐
416 toSeeded_RNG is used, seeded with the global entropy source. If
417 drbg is set, HMAC_DRBG is used seeded with drbg-seed.
418 entropy --truncate-at=128 source
420 Sample a raw entropy source.
421 cc_encrypt CC passphrase --tweak=
423 Encrypt the passed valid credit card number CC using FPE encryp‐
424 tion and the passphrase passphrase. The key is derived from the
425 passphrase using PBKDF2 with SHA256. Due to the nature of FPE,
426 the ciphertext is also a credit card number with a valid check‐
427 sum. tweak is public and parameterizes the encryption function.
428 cc_decrypt CC passphrase --tweak=
430 Decrypt the passed valid ciphertext CC using FPE decryption with
431 the passphrase passphrase and the tweak tweak.
432 roughtime_check --raw-time chain-file
434 Parse and validate a Roughtime chain file.
435 roughtime --raw-time --chain-file=roughtime-chain --max-chain-size=128
437 --check-local-clock=60 --host= --pubkey= --servers-file=
438 Retrieve time from a Roughtime server and store it in a chain
439 file.
440 uuid Generate and print a random UUID.
442 compress --type=gzip --level=6 --buf-size=8192 file
444 Compress a given file.
445 decompress --buf-size=8192 file
447 Decompress a given compressed archive.
448 BOTAN(1)