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)"
81 pkcs8 --pass-in= --pub-out --der-out --pass-out= --pbe= --pbe-mil‐
83 lis=300 key
84 Open a PKCS #8 formatted key at key. If key is encrypted, the
85 passphrase must be passed as pass-in. It is possible to
86 (re)encrypt the read key with the passphrase passed as pass-out.
87 The parameters pbe-millis and pbe work similarly to keygen.
88 sign --der-format --passphrase= --hash=SHA-256 --emsa= key file
90 Sign the data in file using the PKCS #8 private key key. If key
91 is encrypted, the used passphrase must be passed as pass-in.
92 emsa specifies the signature scheme and hash the cryptographic
93 hash function used in the scheme.
94 · For RSA signatures EMSA4 (RSA-PSS) is the default scheme.
96 · For ECDSA and DSA emsa defaults to EMSA1 (signing the hash
98 directly)
99 For ECDSA and DSA, the option --der-format outputs the signature
101 as an ASN.1 encoded blob. Some other tools (including openssl)
102 default to this format.
103 verify --der-format --hash=SHA-256 --emsa= pubkey file signature
105 Verify the authenticity of the data in file with the provided
106 signature signature and the public key pubkey. Similarly to the
107 signing process, emsa specifies the signature scheme and hash
108 the cryptographic hash function used in the scheme.
109 gen_dl_group --pbits=1024 --qbits=0 --seed= --type=subgroup
111 Generate ANSI X9.42 encoded Diffie-Hellman group parameters.
112 · If type=subgroup is passed, the size of the prime subgroup
114 q is sampled as a prime of qbits length and p is pbits
115 long. If qbits is not passed, its length is estimated from
116 pbits as described in RFC 3766.
117 · If type=strong is passed, p is sampled as a safe prime with
119 length pbits and the prime subgroup has size q with pbits-1
120 length.
121 · If type=dsa is used, p and q are generated by the algorithm
123 specified in FIPS 186-4. If the --seed parameter is used,
124 it allows to select the seed value, instead of one being
125 randomly generated. If the seed does not in fact generate a
126 valid DSA group, the command will fail.
127 dl_group_info --pem name
129 Print raw Diffie-Hellman parameters (p,g) of the standardized DH
130 group name. If pem is set, the X9.42 encoded group is printed.
131 ec_group_info --pem name
133 Print raw elliptic curve domain parameters of the standardized
134 curve name. If pem is set, the encoded domain is printed.
135 pk_encrypt --aead=AES-256/GCM rsa_pubkey datafile
137 Encrypts datafile using the specified AEAD algorithm, under a
138 key protected by the specified RSA public key.
139 pk_decrypt rsa_privkey datafile
141 Decrypts a file encrypted with pk_encrypt. If the key is
142 encrypted using a password, it will be prompted for on the ter‐
143 minal.
144
146 gen_pkcs10 key CN --country= --organization= --email= --key-pass=
147 --hash=SHA-256 --emsa=
148 Generate a PKCS #10 certificate signing request (CSR) using the
149 passed PKCS #8 private key key. If the private key is encrypted,
150 the decryption passphrase key-pass has to be passed.*emsa* spec‐
151 ifies the padding scheme to be used when calculating the signa‐
152 ture.
153 · For RSA keys EMSA4 (RSA-PSS) is the default scheme.
155 · For ECDSA, DSA, ECGDSA, ECKCDSA and GOST-34.10 keys emsa
157 defaults to EMSA1.
158 gen_self_signed key CN --country= --dns= --organization= --email=
160 --key-pass= --ca --hash=SHA-256 --emsa=
161 Generate a self signed X.509 certificate using the PKCS #8 pri‐
162 vate key key. If the private key is encrypted, the decryption
163 passphrase key-pass has to be passed. If ca is passed, the cer‐
164 tificate is marked for certificate authority (CA) usage. emsa
165 specifies the padding scheme to be used when calculating the
166 signature.
167 · For RSA keys EMSA4 (RSA-PSS) is the default scheme.
169 · For ECDSA, DSA, ECGDSA, ECKCDSA and GOST-34.10 keys emsa
171 defaults to EMSA1.
172 sign_cert --ca-key-pass= --hash=SHA-256 --duration=365 --emsa= ca_cert
174 ca_key pkcs10_req
175 Create a CA signed X.509 certificate from the information con‐
176 tained in the PKCS #10 CSR pkcs10_req. The CA certificate is
177 passed as ca_cert and the respective PKCS #8 private key as
178 ca_key. If the private key is encrypted, the decryption
179 passphrase ca-key-pass has to be passed. The created certificate
180 has a validity period of duration days. emsa specifies the pad‐
181 ding scheme to be used when calculating the signature. emsa
182 defaults to the padding scheme used in the CA certificate.
183 ocsp_check subject issuer
185 Verify an X.509 certificate against the issuers OCSP responder.
186 Pass the certificate to validate as subject and the CA certifi‐
187 cate as issuer.
188 cert_info --fingerprint --ber file
190 Parse X.509 PEM certificate and display data fields. If --fin‐
191 gerprint is used, the certificate's fingerprint is also printed.
192 cert_verify subject *ca_certs
194 Verify if the provided X.509 certificate subject can be success‐
195 fully validated. The list of trusted CA certificates is passed
196 with ca_certs, which is a list of one or more certificates.
197
199 tls_ciphers --policy=default --version=tls1.2
200 Prints the list of ciphersuites that will be offered under a
201 particular policy/version. The policy can be any of the the
202 strings "default", "suiteb_128", "suiteb_192", "strict", or
203 "all" to denote built-in policies, or it can name a file from
204 which a policy description will be read.
205 tls_client host --port=443 --print-certs --policy= --tls1.0 --tls1.1
207 --tls1.2 --session-db= --session-db-pass= --next-protocols= --type=tcp
208 Implements a testing TLS client, which connects to host via TCP
209 or UDP on port port. The TLS version can be set with the flags
210 tls1.0, tls1.1 and tls1.2 of which the lowest specified version
211 is automatically chosen. If none of the TLS version flags is
212 set, the latest supported version is chosen. The client honors
213 the TLS policy defined in the policy file and prints all cer‐
214 tificates in the chain, if print-certs is passed. next-proto‐
215 cols is a comma separated list and specifies the protocols to
216 advertise with Application-Layer Protocol Negotiation (ALPN).
217 tls_server cert key --port=443 --type=tcp --policy=
219 Implements a testing TLS server, which allows TLS clients to
220 connect. Binds to either TCP or UDP on port port. The server
221 uses the certificate cert and the respective PKCS #8 private key
222 key. The server honors the TLS policy defined in the policy
223 file.
224 tls_http_server cert key --port=443 --policy= --session-db --ses‐
226 sion-db-pass=
227 Only available if Boost.Asio support was enabled. Provides a
228 simple HTTP server which replies to all requests with an infor‐
229 mational text output. The server honors the TLS policy defined
230 in the policy file.
231 tls_proxy listen_port target_host target_port server_cert server_key
233 Only available if Boost.Asio support was enabled. Listens on a
234 port and forwards all connects to a target server specified at
235 target_host and target_port.
236
238 is_prime --prob=56 n
239 Test if the integer n is composite or prime with a Miller-Rabin
240 primality test with (prob+2)/2 iterations.
241 factor n
243 Factor the integer n using a combination of trial division by
244 small primes, and Pollard's Rho algorithm. It can in reasonable
245 time factor integers up to 110 bits or so.
246 gen_prime --count=1 bits
248 Samples count primes with a length of bits bits.
249
251 The PSK database commands are only available if sqlite3 support was
252 compiled in.
253 psk_set db db_key name psk
255 Using the PSK database named db and encrypting under the (hex)
256 key db_key, save the provided psk (also hex) under name:
257 $ botan psk_set psk.db deadba55 bunny f00fee
259 psk_get db db_key name
261 Get back a value saved with psk_set:
262 $ botan psk_get psk.db deadba55 bunny
264 f00fee
265 psk_list db db_key
267 List all values saved to the database under the given key:
268 $ botan psk_list psk.db deadba55
270 bunny
271
273 Split a file into several shares.
274 tss_split M N data_file --id= --share-prefix=share --share-suffix=tss
276 --hash=SHA-256
277 Split a file into N pieces any M of which suffices to recover
278 the original input. The ID allows specifying a unique key ID
279 which may be up to 16 bytes long, this ensures that shares can
280 be uniquely matched. If not specified a random 16 byte value is
281 used. A checksum can be appended to the data to help verify cor‐
282 rect recovery, this can be disabled using --hash=None.
283 tss_recover *shares
285 Recover some data split by tss_split. If insufficient number of
286 shares are provided an error is printed.
287
289 base64_dec file
290 Encode file to Base64.
291 base64_enc file
293 Decode Base64 encoded file.
294 hex_dec file
296 Encode file to Hex.
297 hex_enc file
299 Decode Hex encoded file.
300
302 version --full
303 Print the version number. If option --full is provided, addi‐
304 tional details are printed.
305 config info_type
307 Prints build information, useful for applications which want to
308 build against the library. The info_type argument can be any of
309 prefix, cflags, ldflags, or libs. This is similar to information
310 provided by the pkg-config tool.
311 cpuid List available processor flags (aes_ni, SIMD extensions, ...).
313 asn1print file
315 Decode and print file with ASN.1 Basic Encoding Rules (BER).
316 http_get url
318 Retrieve resource from the passed http url.
319 speed --msec=500 --provider= --buf-size=1024 algos
321 Measures the speed of the passed algos. If no algos are passed
322 all available speed tests are executed. msec (in milliseconds)
323 sets the period of measurement for each algorithm. The buf-size
324 option allows testing the same algorithm on one or more input
325 sizes, for example speed --buf-size=136,1500 AES-128/GCM tests
326 the performance of GCM for small and large packet sizes.
327 rng --system --rdrand bytes
329 Sample bytes random bytes from the specified random number gen‐
330 erator. If system is set, the system RNG is used. If system is
331 unset and rdrand is set, the hardware RDRAND instruction is used
332 if available. If both are unset, HMAC_DRBG is used.
333 cc_encrypt CC passphrase --tweak=
335 Encrypt the passed valid credit card number CC using FPE encryp‐
336 tion and the passphrase passphrase. The key is derived from the
337 passphrase using PBKDF2 with SHA256. Due to the nature of FPE,
338 the ciphertext is also a credit card number with a valid check‐
339 sum. tweak is public and parameterizes the encryption function.
340 cc_decrypt CC passphrase --tweak=
342 Decrypt the passed valid ciphertext CC using FPE decryption with
343 the passphrase passphrase and the tweak tweak.
344 BOTAN(1)