442 lines
19 KiB
ReStructuredText
442 lines
19 KiB
ReStructuredText
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.
|
|
|
|
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.
|
|
|
|
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
|
|
----------------
|
|
``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.
|
|
|
|
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*.
|
|
|
|
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.
|
|
|
|
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``.
|
|
|
|
``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.
|
|
|
|
``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 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 --client-cert= --client-cert-key=``
|
|
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).
|
|
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``
|
|
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``
|
|
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.
|
|
|
|
``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.
|