Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
BOTAN(1)		    General Commands Manual		      BOTAN(1)

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 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  de-
	      faults  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  pro-
	      tect  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  de-
	      sired  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 al-
	      lows use of ciphers such as AES, Twofish,	Serpent, and SM4.  Ci-
	      phers  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  crypto-
	  graphic  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 en-
	      crypted using a password,	it will	be prompted for	on the	termi-
	      nal.

       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* spec-
	      ifies  the padding scheme	to be used when	calculating the	signa-
	      ture.

		  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 pri-
	      vate key key. If the private key is  encrypted,  the  decryption
	      passphrase  key-pass has to be passed. If	ca is passed, the cer-
	      tificate 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 con-
	      tained 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  certifi-
	      cate as issuer.

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

       cert_verify subject *ca_certs
	      Verify if	the provided X.509 certificate subject can be success-
	      fully 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 pri-
	      vate 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 hon-
	      ors  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	infor-
	      mational 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 cor-
	      rect 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 re-
	      quired to	recreate the original file. The	output shares a	 writ-
	      ten  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	direc-
	      tory 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, addi-
	      tional 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  en-
	      coding  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-ra-
       tio=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	--measure-
       ment-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 gen-
	      erator. 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, Au-
	      toSeeded_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 encryp-
	      tion  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	check-
	      sum. 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.

								      BOTAN(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=botan3&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help