diff options
Diffstat (limited to 'comm/third_party/botan/doc/cli.rst')
| -rw-r--r-- | comm/third_party/botan/doc/cli.rst | 406 |
1 files changed, 406 insertions, 0 deletions
diff --git a/comm/third_party/botan/doc/cli.rst b/comm/third_party/botan/doc/cli.rst new file mode 100644 index 0000000000..98f9f06d4c --- /dev/null +++ b/comm/third_party/botan/doc/cli.rst @@ -0,0 +1,406 @@ +Command Line Interface +======================================== +.. highlight:: sh + +Outline +------------ + +The ``botan`` program is a command line tool for using a broad variety +of functions of the Botan library in the shell. + +All commands follow the syntax ``botan <command> <command-options>``. + +If ``botan`` is run with an unknown command, or without any command, or with the +``--help`` option, all available commands will be printed. If a particular +command is run with the ``--help`` option (like ``botan <command> --help``) +some information about the usage of the command is printed. + +Starting in version 2.9, commands that take a passphrase (such as +``gen_bcrypt`` or ``pkcs8``) will also accept the literal ``-`` to mean +ask for the passphrase on the terminal. If supported by the operating +system, echo will be disabled while reading the passphrase. + +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. + +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``. + +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. + +``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 +---------------- +``encryption --buf-size=4096 --decrypt --mode= --key= --iv= --ad=`` + Encrypt a given file with the specified *mode*. If ``--decrypt`` is provided + the file is decrypted instead. + +Public Key Cryptography +------------------------------------- +``keygen --algo=RSA --params= --passphrase= --pbe= --pbe-millis=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*. *pbe* is + the name of the desired encryption algorithm, which uses *pbe-millis* + milliseconds 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. + + The default *pbe* algorithm is "PBES2(AES-256/CBC,SHA-256)". + + With PBES2 scheme, you can select any CBC or GCM mode cipher which has an OID + defined (such as 3DES, Camellia, SM4, Twofish or Serpent). However most other + implementations support only AES or 3DES in CBC mode. You can also choose + Scrypt instead of PBKDF2, by using "Scrypt" instead of the name of a hash + function, for example "PBES2(AES-256/CBC,Scrypt)". Scrypt is also supported by + some other implementations including OpenSSL. + +``pkcs8 --pass-in= --pub-out --der-out --pass-out= --pbe= --pbe-millis=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 *pbe-millis* and *pbe* + work similarly to ``keygen``. + +``sign --der-format --passphrase= --hash=SHA-256 --emsa= --provider= key file`` + Sign the data in *file* using the PKCS #8 private key *key*. If *key* is + encrypted, the used passphrase must be passed as *pass-in*. *emsa* specifies + the signature scheme and *hash* the cryptographic hash function used in the + scheme. + + - For RSA signatures EMSA4 (RSA-PSS) is the default scheme. + - For ECDSA and DSA *emsa* defaults to EMSA1 (signing the hash directly) + + 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. + + The signature is formatted for your screen using base64. + +``verify --der-format --hash=SHA-256 --emsa= 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, + *emsa* specifies the signature scheme and *hash* the cryptographic hash + function used in the scheme. + +``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. + +``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 --emsa=`` + 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.*emsa* specifies the padding scheme to be used + when calculating the signature. + + - For RSA keys EMSA4 (RSA-PSS) is the default scheme. + - For ECDSA, DSA, ECGDSA, ECKCDSA and GOST-34.10 keys *emsa* defaults to EMSA1. + +``gen_self_signed key CN --country= --dns= --organization= --email= --path-limit=1 --days=365 --key-pass= --ca --hash=SHA-256 --emsa= --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. *emsa* specifies the padding scheme to be used when + calculating the signature. + + - For RSA keys EMSA4 (RSA-PSS) is the default scheme. + - For ECDSA, DSA, ECGDSA, ECKCDSA and GOST-34.10 keys *emsa* defaults to EMSA1. + +``sign_cert --ca-key-pass= --hash=SHA-256 --duration=365 --emsa= 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. *emsa* specifies the + padding scheme to be used when calculating the signature. *emsa* defaults to + the padding scheme used in the CA certificate. + +``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. + +TLS Server/Client +----------------------- + +The ``--policy=`` argument of the TLS commands specifies the TLS policy to use. +The policy can be any of the the strings "default", "suiteb_128", "suiteb_192", +"bsi", "strict", or "all" to denote built-in policies, or it can name a file +from which a policy description will be read. + +``tls_ciphers --policy=default --version=tls1.2`` + Prints the list of ciphersuites that will be offered under a particular + policy/version. + +``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`` + Implements a testing TLS client, which 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* of which the lowest specified version is automatically chosen. If + none of the TLS version flags is set, the latest supported version is + chosen. 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). + +``tls_server cert key --port=443 --type=tcp --policy=default --dump-traces= --max-clients=0 --socket-id=0`` + Implements a testing TLS server, which allows TLS clients to 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*. The server 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. + +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. + +``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. + +``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. + +``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, 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`` + Encode *file* to Base32. + +``base32_enc file`` + Decode 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`` + Encode *file* to Base64. + +``base64_enc file`` + Decode Base64 encoded *file*. + +``hex_dec file`` + Encode *file* to Hex. + +``hex_enc file`` + Decode Hex encoded *file*. + +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. + +``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, ...). + +``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. + +``compress --type=gzip --level=6 --buf-size=8192 file`` + Compress a given file. + +``decompress --buf-size=8192 file`` + Decompress a given compressed archive. |