1BOTAN(1)                                                              BOTAN(1)
2
3
4

NAME

6       botan - Botan command line util
7

OUTLINE

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
12       All commands follow the syntax botan <command> <command-options>.
13
14       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
19       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
24       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

HASH FUNCTION

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

PASSWORD HASH

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
41       check_argon2 password hash
42              Checks  if  the  Argon2  hash  of the passed password equals the
43              passed hash value.
44
45       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
50       check_bcrypt password hash
51              Checks if the bcrypt hash of  the  passed  password  equals  the
52              passed hash value.
53
54       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

HMAC

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

ENCRYPTION

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

PUBLIC KEY CRYPTOGRAPHY

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
82                 • For RSA params specifies the bit length of the RSA modulus.
83                   It defaults to 3072.
84
85                 • For  DH  params specifies the DH parameters. It defaults to
86                   modp/ietf/2048.
87
88                 • For DSA params specifies the DSA parameters. It defaults to
89                   dsa/botan/2048.
90
91                 • For  EC  algorithms params specifies the elliptic curve. It
92                   defaults to secp256r1.
93
94              The default pbe algorithm is "PBES2(AES-256/CBC,SHA-256)".
95
96              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
104       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
111       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
118                 • For RSA signatures EMSA4 (RSA-PSS) is the default scheme.
119
120                 • For ECDSA and DSA emsa defaults to EMSA1 (signing the  hash
121                   directly)
122
123              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
127              The signature is formatted for your screen using base64.
128
129       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
135       gen_dl_group --pbits=1024 --qbits=0 --seed= --type=subgroup
136              Generate ANSI X9.42 encoded Diffie-Hellman group parameters.
137
138                 • 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
143                 • 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
147                 • 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
153       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
157       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
161       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
165       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
170       fingerprint --no-fsname --algo=SHA-256 *keys
171              Calculate the public key fingerprint of the keys.
172
173       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

X.509

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
186                 • For RSA keys EMSA4 (RSA-PSS) is the default scheme.
187
188                 • For ECDSA, DSA, ECGDSA, ECKCDSA and  GOST-34.10  keys  emsa
189                   defaults to EMSA1.
190
191       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
200                 • For RSA keys EMSA4 (RSA-PSS) is the default scheme.
201
202                 • For  ECDSA,  DSA,  ECGDSA, ECKCDSA and GOST-34.10 keys emsa
203                   defaults to EMSA1.
204
205       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
216       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
221       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
225       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
230       trust_roots --dn --dn-only --display
231              List the certificates in the system trust store.
232

TLS SERVER/CLIENT

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
239       tls_ciphers --policy=default --version=tls1.2
240              Prints the list of ciphersuites that will  be  offered  under  a
241              particular policy/version.
242
243       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
256       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
266       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
273       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
280       tls_client_hello --hex input
281              Parse and print a TLS client hello message.
282

NUMBER THEORY

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
288       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
293       gen_prime --count=1 bits
294              Samples count primes with a length of bits bits.
295
296       mod_inverse n mod
297              Calculates a modular inverse.
298

PSK DATABASE

300       The  PSK  database  commands  are only available if sqlite3 support was
301       compiled in.
302
303       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
307                 $ botan psk_set psk.db deadba55 bunny f00fee
308
309       psk_get db db_key name
310              Get back a value saved with psk_set:
311
312                 $ botan psk_get psk.db deadba55 bunny
313                 f00fee
314
315       psk_list db db_key
316              List all values saved to the database under the given key:
317
318                 $ botan psk_list psk.db deadba55
319                 bunny
320

SECRET SHARING

322       Split a file into several shares.
323
324       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
333       tss_recover *shares
334              Recover  some data split by tss_split. If insufficient number of
335              shares are provided an error is printed.
336

DATA ENCODING/DECODING

338       base32_dec file
339              Encode file to Base32.
340
341       base32_enc file
342              Decode Base32 encoded file.
343
344       base58_enc --check file
345              Encode file to Base58. If --check  is  provided  Base58Check  is
346              used.
347
348       base58_dec --check file
349              Decode  Base58  encoded file. If --check is provided Base58Check
350              is used.
351
352       base64_dec file
353              Encode file to Base64.
354
355       base64_enc file
356              Decode Base64 encoded file.
357
358       hex_dec file
359              Encode file to Hex.
360
361       hex_enc file
362              Decode Hex encoded file.
363

MISCELLANEOUS COMMANDS

365       version --full
366              Print the version number. If option --full  is  provided,  addi‐
367              tional details are printed.
368
369       has_command cmd
370              Test if the command cmd is available.
371
372       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
378       cpuid  List available processor flags (AES-NI, SIMD extensions, ...).
379
380       cpu_clock --test-duration=500
381              Estimate the speed of the CPU cycle counter.
382
383       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
390       http_get --redirects=1 --timeout=3000 url
391              Retrieve resource from the passed http url.
392
393       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
404       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
409       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
419       entropy --truncate-at=128 source
420              Sample a raw entropy source.
421
422       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
429       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
433       roughtime_check --raw-time chain-file
434              Parse and validate a Roughtime chain file.
435
436       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
441       uuid   Generate and print a random UUID.
442
443       compress --type=gzip --level=6 --buf-size=8192 file
444              Compress a given file.
445
446       decompress --buf-size=8192 file
447              Decompress a given compressed archive.
448
449
450
451
452                                                                      BOTAN(1)
Impressum