botan(1)

📦
version 3.12.0 · 11 versions
, in nixos 26.05, ubuntu stonking

✨ NAME ✨

botan — the Botan command line util, aka your new bestie for doing cryptography in the shell 🫶

It's a General Commands Manual situation, this is botan(1), and we're about to have a whole moment.

🌸 OUTLINE 🌸

okay so here's the tea ☕ — botan is a command line tool that lets you use a huge variety of functions from the Botan library, straight from your shell. no cap.

Every single command follows this syntax:

botan <command> <command-options>

If you run botan with a command nobody recognizes, or with no command at all, or with the --help option, it will print all the available commands for you. and if you run a specific command with --help (like botan <command> --help) it prints some info about how to use that one command. slay.

Starting in version 2.9, commands that take a passphrase (like gen_bcrypt or pkcs8) will also accept the literal - to mean "ask for the passphrase on the terminal". And if your operating system supports it, echo will be disabled while reading the passphrase. (so nobody's reading over your shoulder, we love privacy 💅)

Most arguments that take a path to a file will also accept the literal - to mean the file content should be read from STDIN instead. iconic.

All options for the command line are displayed in the summary line, and in the help output. All options are — as the name suggests — optional, and the default values are shown. For example, hash file prints the SHA-256 of the file encoded as hex, while hash --format=base64 --algo=SHA-384 file prints the base64 encoded SHA-384 hash of the same file. same file, different vibe ✨

🔥 HASH FUNCTION 🔥

hash --algo=SHA-256 --buf-size=4096 --no-fsname --format=hex *files

Compute the algo digest over the data in any number of files. If no files are listed on the command line, the input source defaults to standard input. Unless the --no-fsname option is given, the filename is printed alongside the hash, in the style of tools such as sha256sum. yes bestie, it's giving sha256sum but make it Botan 💖

🎀 PASSWORD HASH 🎀

gen_argon2 --mem=65536 --p=1 --t=1 password

Calculate the Argon2 password digest of password. mem is the amount of memory to use in Kb, p the parallelization parameter, and t the number of iterations to use.

check_argon2 password hash

Checks if the Argon2 hash of the passed password equals the passed hash value.

gen_bcrypt --work-factor=12 password

Calculate the bcrypt password digest of password. work-factor is an integer between 4 and 18. A higher work-factor value results in a more expensive hash calculation. (expensive = slow = harder to brute force, that's the whole point, iykyk 😌)

check_bcrypt password hash

Checks if the bcrypt hash of the passed password equals the passed hash value.

pbkdf_tune --algo=Scrypt --max-mem=256 --output-len=32 --check *times

Tunes the PBKDF algorithm specified with --algo= for the given times.

💜 HMAC 💜

hmac --hash=SHA-256 --buf-size=4096 --no-fsname key files

Compute the HMAC tag with the cryptographic hash function hash using the key in file key over the data in files. files defaults to STDIN. Unless the --no-fsname option is given, the filename is printed alongside the HMAC value.

🔒 ENCRYPTION 🔒

cipher --buf-size=4096 --decrypt --cipher= --key= --nonce= --ad=

Encrypt a given file with the specified cipher, eg "AES-256/GCM". If --decrypt is provided the file is decrypted instead. (choose your fighter: lock it or unlock it 🔐)

👑 PUBLIC KEY CRYPTOGRAPHY 👑

keygen --algo=RSA --params= --passphrase= --cipher= --pbkdf=
--pbkdf-ms=300 --provider= --der-out

Generate a PKCS #8 algo private key. If der-out is passed, the pair is BER encoded. Otherwise, PEM encoding is used. To protect the PKCS #8 formatted key, it is recommended to encrypt it with a provided passphrase. (fr fr, please do this one, don't leave your keys out here naked 🙈)

If a passphrase is used, cipher specifies the name of the desired encryption algorithm (such as "AES-256/CBC", or leave empty to use a default), and pbkdf can be used to specify the password hashing mechanism (either a hash such as "SHA-256" to select PBKDF2, or "Scrypt").

The cipher mode must have an object identifier defined — this allows use of ciphers such as AES, Twofish, Serpent, and SM4. Ciphers in CBC, GCM, and SIV modes are supported. However most other implementations support only AES or 3DES in CBC mode. (so like, read the room, other tools are picky 💀)

If encryption is used, the parameter pbkdf-ms controls how long the password hashing function will run to derive the encryption key from the passed passphrase.

Algorithm specific parameters — as the desired bit length of an RSA key — can be passed with params.

  • For RSA params specifies the bit length of the RSA modulus. It defaults to 3072.
  • For DH params specifies the DH parameters. It defaults to modp/ietf/2048.
  • For DSA params specifies the DSA parameters. It defaults to dsa/botan/2048.
  • For EC algorithms params specifies the elliptic curve. It defaults to secp256r1.
pkcs8 --pass-in= --pub-out --der-out --pass-out= --cipher= --pbkdf=
--pbkdf-ms=300 key

Open a PKCS #8 formatted key at key. If key is encrypted, the passphrase must be passed as pass-in. It is possible to (re)encrypt the read key with the passphrase passed as pass-out. The parameters cipher, pbkdf, and pbkdf-ms work similarly to keygen. (glow up your key's encryption, we love a rebrand ✨)

sign --der-format --passphrase= --hash=SHA-256 --padding= --provider=
key file

Sign the data in file using the PKCS #8 private key key and cryptographic hash hash. If key is encrypted, the used passphrase must be passed as pass-in.

The padding option can be used to control padding for algorithms that have divergent methods; this mostly applies to RSA. For RSA, if the option is not specified PSS signatures are used. You can select generating a PKCS #1 v1.5 formatted signature instead by providing --padding=PKCS1v15.

For ECDSA and DSA, the option --der-format outputs the signature as an ASN.1 encoded blob. Some other tools (including openssl) default to this format. This option does not make sense for other algorithms such as RSA.

The signature is formatted for your screen using base64.

verify --der-format --hash=SHA-256 --padding= pubkey file signature

Verify the authenticity of the data in file with the provided signature signature and the public key pubkey. Similarly to the signing process, padding specifies the padding scheme and hash the cryptographic hash function to use.

gen_dl_group --pbits=1024 --qbits=0 --seed= --type=subgroup

Generate ANSI X9.42 encoded Diffie-Hellman group parameters.

  • If type=subgroup is passed, the size of the prime subgroup q is sampled as a prime of qbits length and p is pbits long. If qbits is not passed, its length is estimated from pbits as described in RFC 3766.
  • If type=strong is passed, p is sampled as a safe prime with length pbits and the prime subgroup has size q with pbits-1 length.
  • If type=dsa is used, p and q are generated by the algorithm specified in FIPS 186-4. If the --seed parameter is used, it allows to select the seed value, instead of one being randomly generated. If the seed does not in fact generate a valid DSA group, the command will fail. (no seed, no group, that's the rule 🍓)
dl_group_info --pem name

Print raw Diffie-Hellman parameters (p,g) of the standardized DH group name. If pem is set, the X9.42 encoded group is printed.

ec_group_info --pem name

Print raw elliptic curve domain parameters of the standardized curve name. If pem is set, the encoded domain is printed.

pk_encrypt --aead=AES-256/GCM rsa_pubkey datafile

Encrypts datafile using the specified AEAD algorithm, under a key protected by the specified RSA public key.

pk_decrypt rsa_privkey datafile

Decrypts a file encrypted with pk_encrypt. If the key is encrypted using a password, it will be prompted for on the terminal.

fingerprint --no-fsname --algo=SHA-256 *keys

Calculate the public key fingerprint of the keys.

pk_workfactor --type=rsa bits

Provide an estimate of the strength of a public key based on it's size. --type= can be "rsa", "dl" or "dl_exp".

🌈 X.509 🌈

gen_pkcs10 key CN --country= --organization= --ca --path-limit=1
--email= --dns= --ext-ku= --key-pass= --hash=SHA-256 --padding=

Generate a PKCS #10 certificate signing request (CSR) using the passed PKCS #8 private key key. If the private key is encrypted, the decryption passphrase key-pass has to be passed.

The padding option specifies the padding scheme to be used when calculating the signature. This is only used for RSA; for such keys PSS is used by default.

gen_self_signed key CN --country= --dns= --organization= --email=
--path-limit=1 --days=365 --key-pass= --ca --hash=SHA-256 --padding=
--der

Generate a self signed X.509 certificate using the PKCS #8 private key key. If the private key is encrypted, the decryption passphrase key-pass has to be passed. If ca is passed, the certificate is marked for certificate authority (CA) usage.

The padding option specifies the padding scheme to be used when calculating the signature. This is only used for RSA; for such keys PSS is used by default.

sign_cert --ca-key-pass= --hash=SHA-256 --duration=365 --padding=
ca_cert ca_key pkcs10_req

Create a CA signed X.509 certificate from the information contained in the PKCS #10 CSR pkcs10_req. The CA certificate is passed as ca_cert and the respective PKCS #8 private key as ca_key. If the private key is encrypted, the decryption passphrase ca-key-pass has to be passed. The created certificate has a validity period of duration days.

The padding argument specifies the padding scheme to be used when calculating the signature; this is only used for RSA. If not set then it will defaults to the padding scheme used in the CA certificate, or otherwise some suitable default.

ocsp_check --timeout=3000 subject issuer

Verify an X.509 certificate against the issuers OCSP responder. Pass the certificate to validate as subject and the CA certificate as issuer.

cert_info --fingerprint file

Parse X.509 PEM certificate and display data fields. If --fingerprint is used, the certificate's fingerprint is also printed.

cert_verify subject *ca_certs

Verify if the provided X.509 certificate subject can be successfully validated. The list of trusted CA certificates is passed with ca_certs, which is a list of one or more certificates.

trust_roots --dn --dn-only --display

List the certificates in the system trust store. (yes queen, show us the whole root situation 👑)

✨ TLS Server/Client ✨

okay so the TLS commands all take a --policy= argument and that's literally the vibe-setter for which TLS policy gets used 💅 it can be any of the strings "default", "suiteb_128", "suiteb_192", "bsi", "strict", or "all" — those are the built-in policies — or it can name a file from which a policy description will be read. iykyk 📁

  • tls_ciphers --policy=default --version=tls1.2 — prints the list of ciphersuites that will be offered under a particular policy/version. it's giving "show me the menu" 🍽️
  • 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 --client-cert= --client-cert-key= — bestie this is a testing TLS client, it connects to host via TCP or UDP on port port 🫶 the TLS version can be set with the flags tls1.0, tls1.1 and tls1.2, and of those the lowest specified version gets automatically chosen. if none of the TLS version flags is set, the latest supported version is chosen (main character default energy ✨). the client honors the TLS policy specified with policy, and prints all certificates in the chain if print-certs is passed 🎀 next-protocols is a comma separated list and specifies the protocols to advertise with Application-Layer Protocol Negotiation (ALPN). pass a path to a client certificate PEM and unencrypted PKCS8 encoded private key if client authentication is required 🔑
  • tls_server cert key --port=443 --type=tcp --policy=default --dump-traces= --max-clients=0 --socket-id=0 — a testing TLS server, which lets TLS clients connect and which echos any data that is sent to it 🔁 binds to either TCP or UDP on port port. the server uses the certificate cert and the respective PKCS #8 private key key. it honors the TLS policy specified with policy. socket-id is only available on FreeBSD and sets the so_user_cookie value of the used socket 👀
  • tls_http_server cert key --port=443 --policy=default --threads=0 --max-clients=0 --session-db --session-db-pass= — only available if Boost.Asio support was enabled 🚨 provides a simple HTTP server which replies to all requests with an informational text output. the server honors the TLS policy specified with policy.
  • tls_proxy listen_port target_host target_port server_cert server_key --policy=default --threads=0 --max-clients=0 --session-db= --session-db-pass= — only available if Boost.Asio support was enabled 🚨 listens on a port and forwards all connects to a target server specified at target_host and target_port.
  • tls_client_hello --hex input — parse and print a TLS client hello message. lil decoder ring moment 🔍

🔢 Number Theory 🔢

  • is_prime --prob=56 n — test if the integer n is composite or prime with a Miller-Rabin primality test with (prob+2)/2 iterations. math is mathing 🧮
  • factor n — factor the integer n using a combination of trial division by small primes, and Pollard's Rho algorithm. it can in reasonable time factor integers up to 110 bits or so 🎯
  • gen_prime --count=1 bits — samples count primes with a length of bits bits. fresh primes, hot off the press 🔥
  • mod_inverse n mod — calculates a modular inverse.

🔐 PSK Database 🔐

the PSK database commands are only available if sqlite3 support was compiled in 🫣

  • psk_set db db_key name psk — using the PSK database named db and encrypting under the (hex) key db_key, save the provided psk (also hex) under name:
$ botan psk_set psk.db deadba55 bunny f00fee
  • psk_get db db_key name — get back a value saved with psk_set:
$ botan psk_get psk.db deadba55 bunny
f00fee
  • psk_list db db_key — list all values saved to the database under the given key:
$ botan psk_list psk.db deadba55
bunny

🧩 Secret Sharing 🧩

split a file into several shares, no biggie ✂️

  • tss_split M N data_file --id= --share-prefix=share --share-suffix=tss --hash=SHA-256 — split a file into N pieces any M of which suffices to recover the original input 🫶 the ID allows specifying a unique key ID which may be up to 16 bytes long, this ensures that shares can be uniquely matched. if not specified a random 16 byte value is used 🎲 a checksum can be appended to the data to help verify correct recovery, and this can be disabled using --hash=None 🚫
  • tss_recover *shares — recover some data split by tss_split. if insufficient number of shares are provided an error is printed 😭

🎀 Data Encoding/Decoding 🎀

  • base32_dec file — decode file to Base32.
  • base32_enc file — encode Base32 encoded file.
  • base58_enc --check file — encode file to Base58. if --check is provided Base58Check is used ✅
  • base58_dec --check file — decode Base58 encoded file. if --check is provided Base58Check is used ✅
  • base64_dec file — decode file to Base64.
  • base64_enc file — encode Base64 encoded file.
  • hex_dec file — decode file to Hex.
  • hex_enc file — encode Hex encoded file.

🌈 Forward Error Correction 🌈

  • fec_encode --suffix=fec --prefix= --output-dir= k n input — split a given input file into n shares where k shares are required to recreate the original file 🧚 the output shares a written to files with the file extension specified in --suffix and either the original file name or the one specified in --prefix. the output directory is either equal to the input file's directory or the one specified in --output-dir 📂
  • fec_decode *shares — if given enough shares, this will output the original input file's content to stdout. otherwise an error is printed on stderr 💀
  • fec_info share — given a single share this will print information about the share. for instance: FEC share 4/4 with 3 needed for recovery 🧾

💜 Miscellaneous Commands 💜

  • version --full — print the version number. if option --full is provided, additional details are printed ✨
  • has_command cmd — test if the command cmd is available. vibe check on a command fr fr ✅
  • config info_type — prints build information, useful for applications which want to build against the library. the info_type argument can be any of prefix, cflags, ldflags, or libs. this is similar to information provided by the pkg-config tool 🛠️
  • cpuid — list available processor flags (AES-NI, SIMD extensions, ...). hardware flex 💪
  • cpu_clock --test-duration=500 — estimate the speed of the CPU cycle counter ⏱️
  • asn1print --skip-context-specific --print-limit=4096 --bin-limit=2048 --max-depth=64 --pem file — decode and print file with ASN.1 Basic Encoding Rules (BER). if flag --pem is used, or the filename ends in .pem, then PEM encoding is assumed. otherwise the input is assumed to be binary DER/BER 🧐
  • http_get --redirects=1 --timeout=3000 url — retrieve resource from the passed http url 🌐
  • speed --msec=500 --format=default --ecc-groups= --provider= --buf-size=1024 --clear-cpuid= --cpu-clock-speed=0 --cpu-clock-ratio=1.0 *algos — measures the speed of the passed algos 🏎️ if no algos are passed all available speed tests are executed. msec (in milliseconds) sets the period of measurement for each algorithm. the buf-size option allows testing the same algorithm on one or more input sizes, for example speed --buf-size=136,1500 AES-128/GCM tests the performance of GCM for small and large packet sizes 📦 format can be "default", "table" or "json".
  • timing_test test_type --test-data-file= --test-data-dir=src/tests/data/timing --warmup-runs=1000 --measurement-runs=10000 — run various timing side channel tests 🕵️♀️
  • rng --format=hex --system --rdrand --auto --entropy --drbg --drbg-seed= *bytes — sample bytes random bytes from the specified random number generator 🎲 if system is set, the system RNG is used. if rdrand is set, the hardware RDRAND instruction is used. if auto is set, AutoSeeded_RNG is used, seeded with the system RNG if available or the global entropy source otherwise. if entropy is set, AutoSeeded_RNG is used, seeded with the global entropy source. if drbg is set, HMAC_DRBG is used seeded with drbg-seed 🔮
  • entropy --truncate-at=128 source — sample a raw entropy source 🌀
  • cc_encrypt CC passphrase --tweak= — encrypt the passed valid credit card number CC using FPE encryption and the passphrase passphrase 💳 the key is derived from the passphrase using PBKDF2 with SHA256. due to the nature of FPE, the ciphertext is also a credit card number with a valid checksum 😳 tweak is public and parameterizes the encryption function.
  • cc_decrypt CC passphrase --tweak= — decrypt the passed valid ciphertext CC using FPE decryption with the passphrase passphrase and the tweak tweak 🔓
  • roughtime_check --raw-time chain-file — parse and validate a Roughtime chain file ⏰
  • roughtime --raw-time --chain-file=roughtime-chain --max-chain-size=128 --check-local-clock=60 --host= --pubkey= --servers-file= — retrieve time from a Roughtime server and store it in a chain file 🕰️
  • uuid — generate and print a random UUID. iconic unique-identifier behavior 👑
  • compress --type=gzip --level=6 --buf-size=8192 file — compress a given file 🗜️
  • decompress --buf-size=8192 file — decompress a given compressed archive 📂

and that's the whole page bestie, you made it to the end 🎉 this one's from the botan man page, source/version 2.19.5 (that's the release, date 2024-06-20) — slay, go forth and encrypt responsibly 💖🌸✨🦋🎀

📦 where this page comes from