Provided by: botan_2.6.0-3build1_amd64 bug

NAME

       botan - Botan command line util

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 with their options will be printed.

HASH FUNCTION

       hash --algo=SHA-256 --buf-size=4096 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.

PASSWORD HASH

       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.

HMAC

       hmac --hash=SHA-256 --buf-size=4096 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.

PUBLIC KEY CRYPTOGRAPHY

       keygen --algo=RSA --params= --passphrase= --pbe= --pbe-millis=300 --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 bitlength 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= --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 --passphrase= --hash=SHA-256 --emsa= 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)

       verify --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 --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.

       dl_group_info --pem name
              Print raw Diffie-Hellman parameters (p,g) of the standarized 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 standarized curve name. If pem is
              set, the encoded domain is printed.

X.509

       gen_pkcs10 key CN --country= --organization= --email= --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=  --key-pass=  --ca
       --hash=SHA-256 --emsa=
              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 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 --ber 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 sucessfully validated.  The
              list  of trusted CA certificates is passed with ca_certs, which is a list of one or
              more certificates.

TLS SERVER/CLIENT

       tls_ciphers --policy=default --version=tls1.2
              Prints  the  list  of  ciphersuites  that  will  be  offered  under  a   particular
              policy/version.  The  policy  can  be  any  of the the strings "default", "suiteb",
              "strict", or "all" to denote built-in policies, or it can name a file from which  a
              policy description will be read.

       tls_client   host   --port=443   --print-certs   --policy=   --tls1.0   --tls1.1  --tls1.2
       --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 defined in the policy file and prints all  certificates  in  the  chain,  if
              print-certs  is passed.  next-protocols is a comma seperated list and specifies the
              protocols to advertise with Application-Layer Protocol Negotiation (ALPN).

       tls_server cert key --port=443 --type=tcp --policy=
              Implements a testing TLS server, which allows TLS  clients  to  connect.  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 defined in the
              policy file.

       tls_http_server cert key --port=443 --policy= --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 defined in the policy file.

       tls_proxy listen_port target_host target_port server_cert server_key
              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.

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.

       gen_prime --count=1 bits
              Samples count primes with a length of bits bits.

PSK DATABASE

       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

DATA ENCODING/DECODING

       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.

       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.

       cpuid  List available processor flags (aes_ni, SIMD extensions, ...).

       asn1print file
              Decode and print file with ASN.1 Basic Encoding Rules (BER).

       http_get url
              Retrieve ressource from the passed http/https url.

       speed --msec=100 --provider= --buf-size=4096 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.

       rng --system --rdrand bytes
              Sample  bytes random bytes from the specified random number generator. If system is
              set, the Botan System_RNG is used. If system  is  unset  and  rdrand  is  set,  the
              hardware  rng  RDRAND_RNG  is used.  If both are unset, the Botan AutoSeeded_RNG is
              used.

       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.

                                                                                         BOTAN(1)