diff options
| -rwxr-xr-x | configure.py | 28 | ||||
| -rw-r--r-- | doc/manual/cli.rst | 216 | ||||
| -rwxr-xr-x | src/scripts/build_docs.py | 7 | ||||
| -rwxr-xr-x | src/scripts/install.py | 7 |
4 files changed, 171 insertions, 87 deletions
diff --git a/configure.py b/configure.py index 7237cb9b0..ae23aed1e 100755 --- a/configure.py +++ b/configure.py @@ -378,7 +378,7 @@ def process_command_line(args): # pylint: disable=too-many-locals help='disable all optimizations (for debugging)') build_group.add_option('--debug-mode', action='store_true', default=False, dest='debug_mode', - help='enable debug info and disable optimizations') + help='enable debug info, disable optimizations') build_group.add_option('--gen-amalgamation', dest='gen_amalgamation', default=False, action='store_true', @@ -390,7 +390,7 @@ def process_command_line(args): # pylint: disable=too-many-locals build_group.add_option('--amalgamation', dest='amalgamation', default=False, action='store_true', - help='generate amalgamation files and build via amalgamation') + help='use amalgamation to build') build_group.add_option('--single-amalgamation-file', default=False, action='store_true', @@ -443,11 +443,11 @@ def process_command_line(args): # pylint: disable=too-many-locals build_group.add_option('--unsafe-fuzzer-mode', action='store_true', default=False, help='Disable essential checks for testing') - build_group.add_option('--build-fuzzers=', dest='build_fuzzers', + build_group.add_option('--build-fuzzers', dest='build_fuzzers', metavar='TYPE', default=None, help='Build fuzzers (afl, libfuzzer, klee, test)') - build_group.add_option('--with-fuzzer-lib=', metavar='LIB', default=None, dest='fuzzer_lib', + build_group.add_option('--with-fuzzer-lib', metavar='LIB', default=None, dest='fuzzer_lib', help='additionally link in LIB') docs_group = optparse.OptionGroup(parser, 'Documentation Options') @@ -471,6 +471,12 @@ def process_command_line(args): # pylint: disable=too-many-locals docs_group.add_option('--without-pdf', action='store_false', dest='with_pdf', help=optparse.SUPPRESS_HELP) + docs_group.add_option('--with-rst2man', action='store_true', + default=None, help='Use rst2man to generate man page') + + docs_group.add_option('--without-rst2man', action='store_false', + dest='with_rst2man', help=optparse.SUPPRESS_HELP) + docs_group.add_option('--with-doxygen', action='store_true', default=False, help='Use Doxygen') @@ -532,6 +538,8 @@ def process_command_line(args): # pylint: disable=too-many-locals help='set the binary install dir') install_group.add_option('--libdir', metavar='DIR', help='set the library install dir') + install_group.add_option('--mandir', metavar='DIR', + help='set the install dir for man pages') install_group.add_option('--includedir', metavar='DIR', help='set the include file install dir') @@ -558,7 +566,6 @@ def process_command_line(args): # pylint: disable=too-many-locals 'libexecdir', 'localedir', 'localstatedir', - 'mandir', 'oldincludedir', 'pdfdir', 'psdir', @@ -1273,6 +1280,7 @@ class OsInfo(InfoObject): # pylint: disable=too-many-instance-attributes 'bin_dir': 'bin', 'lib_dir': 'lib', 'doc_dir': 'share/doc', + 'man_dir': 'share/man', 'building_shared_supported': 'yes', 'so_post_link_command': '', 'cli_exe_name': 'botan', @@ -1318,6 +1326,7 @@ class OsInfo(InfoObject): # pylint: disable=too-many-instance-attributes self.lib_dir = lex.lib_dir self.lib_prefix = lex.lib_prefix self.library_name = lex.library_name + self.man_dir = lex.man_dir self.obj_suffix = lex.obj_suffix self.os_type = lex.os_type self.program_suffix = lex.program_suffix @@ -1769,12 +1778,14 @@ def create_template_vars(source_paths, build_config, options, modules, cc, arch, 'prefix': options.prefix or osinfo.install_root, 'bindir': options.bindir or osinfo.bin_dir, 'libdir': options.libdir or osinfo.lib_dir, + 'mandir': options.mandir or osinfo.man_dir, 'includedir': options.includedir or osinfo.header_dir, 'docdir': options.docdir or osinfo.doc_dir, 'with_documentation': options.with_documentation, 'with_sphinx': options.with_sphinx, 'with_pdf': options.with_pdf, + 'with_rst2man': options.with_rst2man, 'sphinx_config_dir': source_paths.sphinx_config_dir, 'with_doxygen': options.with_doxygen, @@ -2718,10 +2729,13 @@ def set_defaults_for_unset_options(options, info_arch, info_cc): # pylint: disab logging.info('Guessing target processor is a %s/%s (use --cpu to set)' % ( options.arch, options.cpu)) - if options.with_sphinx is None and options.with_documentation is True: - if have_program('sphinx-build'): + if options.with_documentation is True: + if options.with_sphinx is None and have_program('sphinx-build'): logging.info('Found sphinx-build (use --without-sphinx to disable)') options.with_sphinx = True + if options.with_rst2man is None and have_program('rst2man'): + logging.info('Found rst2man (use --without-rst2man to disable)') + options.with_rst2man = True # Mutates `options` diff --git a/doc/manual/cli.rst b/doc/manual/cli.rst index 72e3d3b31..85b93d5e1 100644 --- a/doc/manual/cli.rst +++ b/doc/manual/cli.rst @@ -1,55 +1,54 @@ -The Command Line Interface +botan ======================================== -The botan program is a command line tool for using a broad variety of functions of the Botan library in the shell. -The CLI offers access to the following functionalities: -- Data en- and decoding -- Creation and administration of public key parameters and keypairs -- Calculation of message digests -- Calculation and verification of public key signatures -- Access to random number generators -- Creation of X.509 certificates and certificate signing requests -- OCSP certificate checking -- Performance measurements of implemented algorithms -- TLS server/client -- Primality testing, prime factorization and prime sampling +:Subtitle: Botan command line util +:Manual section: 1 -.. highlight:: sh +Outline +------------ -General Command Usage ---------------------------------- -All commands follow the predefined syntax:: +The ``botan`` program is a command line tool for using a broad variety +of functions of the Botan library in the shell. - $ botan <command> <command-options> +All commands follow the syntax ``botan <command> <command-options>``. -and are listed with their available arguments when ``botan`` is called -with an unknown command, or without any command, or with ``--help``. +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 +Hash Function ---------------- ``hash --algo=SHA-256 --buf-size=4096 files`` - Compute the *algo* digest over the data in *files*. *files* defaults to STDIN. - + 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 *file*. *work-factor* is an integer between 1 and 18. - A higher *work-factor* value results in a more expensive hash calculation. + 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. + 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*. + 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. @@ -57,66 +56,110 @@ Public Key Cryptography - 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``. + 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. + 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. + - 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. + 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. + - 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. + 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. + 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`` - 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. + 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. ``gen_self_signed key CN --country= --dns= --organization= --email= --key-pass= --ca --hash=SHA-256`` - 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. + 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. ``sign_cert --ca-key-pass= --hash=SHA-256 --duration=365 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. + 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. ``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*. + 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 --ber file`` - Parse X.509 PEM certificate and display data fields. +``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 passed X.509 certificate *subject* passes the path validation. The list of trusted CA certificates is passed with *ca_certs* +``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). + 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. + 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 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 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 ----------------------- @@ -135,34 +178,47 @@ 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 version. Pass --full for additional details. + Print the version number. If option ``-full`` is provided additional details are printed. ``config info_type`` - Print the used prefix, cflags, ldflags or libs. + 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, ...). @@ -170,27 +226,27 @@ Miscellaneous Commands ``asn1print file`` Decode and print *file* with ASN.1 Basic Encoding Rules (BER). -``base64_dec file`` - Encode *file* to Base64. - -``base64_enc file`` - Decode Base64 encoded *file*. - ``http_get url`` Retrieve ressource from the passed http/https *url*. -``speed --msec=300 --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. +``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. + 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. + 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*. + Decrypt the passed valid ciphertext *CC* using FPE decryption with + the passphrase *passphrase* and the tweak *tweak*. diff --git a/src/scripts/build_docs.py b/src/scripts/build_docs.py index 94c61afdf..ca055ac05 100755 --- a/src/scripts/build_docs.py +++ b/src/scripts/build_docs.py @@ -105,6 +105,8 @@ def parse_options(args): def main(args=None): + # pylint: disable=too-many-branches,too-many-locals + if args is None: args = sys.argv @@ -122,6 +124,7 @@ def main(args=None): with_docs = bool(cfg['with_documentation']) with_sphinx = bool(cfg['with_sphinx']) with_pdf = bool(cfg['with_pdf']) + with_rst2man = bool(cfg['with_rst2man']) with_doxygen = bool(cfg['with_doxygen']) doc_stamp_file = cfg['doc_stamp_file'] @@ -154,6 +157,10 @@ def main(args=None): # otherwise just copy it cmds.append(['cp', manual_src, manual_output]) + if with_rst2man: + cmds.append(['rst2man', os.path.join(manual_src, 'cli.rst'), + os.path.join(cfg['build_dir'], 'botan.1')]) + cmds.append(['touch', doc_stamp_file]) for cmd in cmds: diff --git a/src/scripts/install.py b/src/scripts/install.py index d30493ebe..243d58eda 100755 --- a/src/scripts/install.py +++ b/src/scripts/install.py @@ -253,6 +253,13 @@ def main(args): for f in [f for f in os.listdir(cfg['doc_dir']) if f.endswith('.txt')]: copy_file(os.path.join(cfg['doc_dir'], f), prepend_destdir(os.path.join(target_doc_dir, f))) + if cfg['with_rst2man']: + man1_dir = prepend_destdir(os.path.join(options.prefix, os.path.join(cfg['mandir'], 'man1'))) + makedirs(man1_dir) + + copy_file(os.path.join(cfg['build_dir'], 'botan.1'), + os.path.join(man1_dir, 'botan.1')) + logging.info('Botan %s installation complete', cfg['version']) return 0 |