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