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
25 hash --algo=SHA-256 --buf-size=4096 --no-fsname files
26 Compute the algo digest over the data in any number of files. If
27 no files are listed on the command line, the input source
28 defaults to standard input. Unless the --no-fsname option is
29 given, the filename is printed alongside the hash, in the style
30 of tools such as sha256sum.
31
33 gen_bcrypt --work-factor=12 password
34 Calculate the bcrypt password digest of password. work-factor is
35 an integer between 4 and 18. A higher work-factor value results
36 in a more expensive hash calculation.
37 check_bcrypt password hash
39 Checks if the bcrypt hash of the passed password equals the
40 passed hash value.
41
43 hmac --hash=SHA-256 --buf-size=4096 --no-fsname key files
44 Compute the HMAC tag with the cryptographic hash function hash
45 using the key in file key over the data in files. files defaults
46 to STDIN. Unless the --no-fsname option is given, the filename
47 is printed alongside the HMAC value.
48
50 keygen --algo=RSA --params= --passphrase= --pbe= --pbe-millis=300
51 --der-out
52 Generate a PKCS #8 algo private key. If der-out is passed, the
53 pair is BER encoded. Otherwise, PEM encoding is used. To pro‐
54 tect the PKCS #8 formatted key, it is recommended to encrypt it
55 with a provided passphrase. pbe is the name of the desired
56 encryption algorithm, which uses pbe-millis milliseconds to
57 derive the encryption key from the passed passphrase. Algorithm
58 specific parameters, as the desired bit length of an RSA key,
59 can be passed with params.
60 · For RSA params specifies the bit length of the RSA modulus.
62 It defaults to 3072.
63 · For DH params specifies the DH parameters. It defaults to
65 modp/ietf/2048.
66 · For DSA params specifies the DSA parameters. It defaults to
68 dsa/botan/2048.
69 · For EC algorithms params specifies the elliptic curve. It
71 defaults to secp256r1.
72 The default pbe algorithm is "PBES2(AES-256/CBC,SHA-256)".
74 With PBES2 scheme, you can select any CBC or GCM mode cipher
76 which has an OID defined (such as 3DES, Camellia, SM4, Twofish
77 or Serpent). However most other implementations support only AES
78 or 3DES in CBC mode. You can also choose Scrypt instead of
79 PBKDF2, by using "Scrypt" instead of the name of a hash func‐
80 tion, for example "PBES2(AES-256/CBC,Scrypt)". Scrypt is also
81 supported by some other implementations including OpenSSL.
82 pkcs8 --pass-in= --pub-out --der-out --pass-out= --pbe= --pbe-mil‐
84 lis=300 key
85 Open a PKCS #8 formatted key at key. If key is encrypted, the
86 passphrase must be passed as pass-in. It is possible to
87 (re)encrypt the read key with the passphrase passed as pass-out.
88 The parameters pbe-millis and pbe work similarly to keygen.
89 sign --der-format --passphrase= --hash=SHA-256 --emsa= key file
91 Sign the data in file using the PKCS #8 private key key. If key
92 is encrypted, the used passphrase must be passed as pass-in.
93 emsa specifies the signature scheme and hash the cryptographic
94 hash function used in the scheme.
95 · For RSA signatures EMSA4 (RSA-PSS) is the default scheme.
97 · For ECDSA and DSA emsa defaults to EMSA1 (signing the hash
99 directly)
100 For ECDSA and DSA, the option --der-format outputs the signature
102 as an ASN.1 encoded blob. Some other tools (including openssl)
103 default to this format.
104 The signature is formatted for your screen using base64.
106 verify --der-format --hash=SHA-256 --emsa= pubkey file signature
108 Verify the authenticity of the data in file with the provided
109 signature signature and the public key pubkey. Similarly to the
110 signing process, emsa specifies the signature scheme and hash
111 the cryptographic hash function used in the scheme.
112 gen_dl_group --pbits=1024 --qbits=0 --seed= --type=subgroup
114 Generate ANSI X9.42 encoded Diffie-Hellman group parameters.
115 · If type=subgroup is passed, the size of the prime subgroup
117 q is sampled as a prime of qbits length and p is pbits
118 long. If qbits is not passed, its length is estimated from
119 pbits as described in RFC 3766.
120 · If type=strong is passed, p is sampled as a safe prime with
122 length pbits and the prime subgroup has size q with pbits-1
123 length.
124 · If type=dsa is used, p and q are generated by the algorithm
126 specified in FIPS 186-4. If the --seed parameter is used,
127 it allows to select the seed value, instead of one being
128 randomly generated. If the seed does not in fact generate a
129 valid DSA group, the command will fail.
130 dl_group_info --pem name
132 Print raw Diffie-Hellman parameters (p,g) of the standardized DH
133 group name. If pem is set, the X9.42 encoded group is printed.
134 ec_group_info --pem name
136 Print raw elliptic curve domain parameters of the standardized
137 curve name. If pem is set, the encoded domain is printed.
138 pk_encrypt --aead=AES-256/GCM rsa_pubkey datafile
140 Encrypts datafile using the specified AEAD algorithm, under a
141 key protected by the specified RSA public key.
142 pk_decrypt rsa_privkey datafile
144 Decrypts a file encrypted with pk_encrypt. If the key is
145 encrypted using a password, it will be prompted for on the ter‐
146 minal.
147
149 gen_pkcs10 key CN --country= --organization= --email= --key-pass=
150 --hash=SHA-256 --emsa=
151 Generate a PKCS #10 certificate signing request (CSR) using the
152 passed PKCS #8 private key key. If the private key is encrypted,
153 the decryption passphrase key-pass has to be passed.*emsa* spec‐
154 ifies the padding scheme to be used when calculating the signa‐
155 ture.
156 · For RSA keys EMSA4 (RSA-PSS) is the default scheme.
158 · For ECDSA, DSA, ECGDSA, ECKCDSA and GOST-34.10 keys emsa
160 defaults to EMSA1.
161 gen_self_signed key CN --country= --dns= --organization= --email=
163 --key-pass= --ca --hash=SHA-256 --emsa=
164 Generate a self signed X.509 certificate using the PKCS #8 pri‐
165 vate key key. If the private key is encrypted, the decryption
166 passphrase key-pass has to be passed. If ca is passed, the cer‐
167 tificate is marked for certificate authority (CA) usage. emsa
168 specifies the padding scheme to be used when calculating the
169 signature.
170 · For RSA keys EMSA4 (RSA-PSS) is the default scheme.
172 · For ECDSA, DSA, ECGDSA, ECKCDSA and GOST-34.10 keys emsa
174 defaults to EMSA1.
175 sign_cert --ca-key-pass= --hash=SHA-256 --duration=365 --emsa= ca_cert
177 ca_key pkcs10_req
178 Create a CA signed X.509 certificate from the information con‐
179 tained in the PKCS #10 CSR pkcs10_req. The CA certificate is
180 passed as ca_cert and the respective PKCS #8 private key as
181 ca_key. If the private key is encrypted, the decryption
182 passphrase ca-key-pass has to be passed. The created certificate
183 has a validity period of duration days. emsa specifies the pad‐
184 ding scheme to be used when calculating the signature. emsa
185 defaults to the padding scheme used in the CA certificate.
186 ocsp_check subject issuer
188 Verify an X.509 certificate against the issuers OCSP responder.
189 Pass the certificate to validate as subject and the CA certifi‐
190 cate as issuer.
191 cert_info --fingerprint --ber file
193 Parse X.509 PEM certificate and display data fields. If --fin‐
194 gerprint is used, the certificate's fingerprint is also printed.
195 cert_verify subject *ca_certs
197 Verify if the provided X.509 certificate subject can be success‐
198 fully validated. The list of trusted CA certificates is passed
199 with ca_certs, which is a list of one or more certificates.
200
202 tls_ciphers --policy=default --version=tls1.2
203 Prints the list of ciphersuites that will be offered under a
204 particular policy/version. The policy can be any of the the
205 strings "default", "suiteb_128", "suiteb_192", "strict", or
206 "all" to denote built-in policies, or it can name a file from
207 which a policy description will be read.
208 tls_client host --port=443 --print-certs --policy= --tls1.0 --tls1.1
210 --tls1.2 --session-db= --session-db-pass= --next-protocols= --type=tcp
211 Implements a testing TLS client, which connects to host via TCP
212 or UDP on port port. The TLS version can be set with the flags
213 tls1.0, tls1.1 and tls1.2 of which the lowest specified version
214 is automatically chosen. If none of the TLS version flags is
215 set, the latest supported version is chosen. The client honors
216 the TLS policy defined in the policy file and prints all cer‐
217 tificates in the chain, if print-certs is passed. next-proto‐
218 cols is a comma separated list and specifies the protocols to
219 advertise with Application-Layer Protocol Negotiation (ALPN).
220 tls_server cert key --port=443 --type=tcp --policy=
222 Implements a testing TLS server, which allows TLS clients to
223 connect and which echos any data that is sent to it. Binds to
224 either TCP or UDP on port port. The server uses the certificate
225 cert and the respective PKCS #8 private key key. The server hon‐
226 ors the TLS policy defined in the policy file.
227 tls_http_server cert key --port=443 --policy= --session-db --ses‐
229 sion-db-pass=
230 Only available if Boost.Asio support was enabled. Provides a
231 simple HTTP server which replies to all requests with an infor‐
232 mational text output. The server honors the TLS policy defined
233 in the policy file.
234 tls_proxy listen_port target_host target_port server_cert server_key
236 Only available if Boost.Asio support was enabled. Listens on a
237 port and forwards all connects to a target server specified at
238 target_host and target_port.
239
241 is_prime --prob=56 n
242 Test if the integer n is composite or prime with a Miller-Rabin
243 primality test with (prob+2)/2 iterations.
244 factor n
246 Factor the integer n using a combination of trial division by
247 small primes, and Pollard's Rho algorithm. It can in reasonable
248 time factor integers up to 110 bits or so.
249 gen_prime --count=1 bits
251 Samples count primes with a length of bits bits.
252
254 The PSK database commands are only available if sqlite3 support was
255 compiled in.
256 psk_set db db_key name psk
258 Using the PSK database named db and encrypting under the (hex)
259 key db_key, save the provided psk (also hex) under name:
260 $ botan psk_set psk.db deadba55 bunny f00fee
262 psk_get db db_key name
264 Get back a value saved with psk_set:
265 $ botan psk_get psk.db deadba55 bunny
267 f00fee
268 psk_list db db_key
270 List all values saved to the database under the given key:
271 $ botan psk_list psk.db deadba55
273 bunny
274
276 Split a file into several shares.
277 tss_split M N data_file --id= --share-prefix=share --share-suffix=tss
279 --hash=SHA-256
280 Split a file into N pieces any M of which suffices to recover
281 the original input. The ID allows specifying a unique key ID
282 which may be up to 16 bytes long, this ensures that shares can
283 be uniquely matched. If not specified a random 16 byte value is
284 used. A checksum can be appended to the data to help verify cor‐
285 rect recovery, this can be disabled using --hash=None.
286 tss_recover *shares
288 Recover some data split by tss_split. If insufficient number of
289 shares are provided an error is printed.
290
292 base64_dec file
293 Encode file to Base64.
294 base64_enc file
296 Decode Base64 encoded file.
297 hex_dec file
299 Encode file to Hex.
300 hex_enc file
302 Decode Hex encoded file.
303
305 version --full
306 Print the version number. If option --full is provided, addi‐
307 tional details are printed.
308 config info_type
310 Prints build information, useful for applications which want to
311 build against the library. The info_type argument can be any of
312 prefix, cflags, ldflags, or libs. This is similar to information
313 provided by the pkg-config tool.
314 cpuid List available processor flags (AES-NI, SIMD extensions, ...).
316 asn1print --pem file
318 Decode and print file with ASN.1 Basic Encoding Rules (BER). If
319 flag --pem is used, or the filename ends in .pem, then PEM
320 encoding is assumed. Otherwise the input is assumed to be binary
321 DER/BER.
322 http_get url
324 Retrieve resource from the passed http url.
325 speed --msec=500 --provider= --buf-size=1024 algos
327 Measures the speed of the passed algos. If no algos are passed
328 all available speed tests are executed. msec (in milliseconds)
329 sets the period of measurement for each algorithm. The buf-size
330 option allows testing the same algorithm on one or more input
331 sizes, for example speed --buf-size=136,1500 AES-128/GCM tests
332 the performance of GCM for small and large packet sizes.
333 rng --system --rdrand bytes
335 Sample bytes random bytes from the specified random number gen‐
336 erator. If system is set, the system RNG is used. If system is
337 unset and rdrand is set, the hardware RDRAND instruction is used
338 if available. If both are unset, HMAC_DRBG is used.
339 cc_encrypt CC passphrase --tweak=
341 Encrypt the passed valid credit card number CC using FPE encryp‐
342 tion and the passphrase passphrase. The key is derived from the
343 passphrase using PBKDF2 with SHA256. Due to the nature of FPE,
344 the ciphertext is also a credit card number with a valid check‐
345 sum. tweak is public and parameterizes the encryption function.
346 cc_decrypt CC passphrase --tweak=
348 Decrypt the passed valid ciphertext CC using FPE decryption with
349 the passphrase passphrase and the tweak tweak.
350 BOTAN(1)