diff options
| -rw-r--r-- | doc/manual/cipher_modes.rst | 13 | ||||
| -rw-r--r-- | doc/manual/cli.rst | 65 | ||||
| -rw-r--r-- | doc/manual/hash.rst | 17 | ||||
| -rw-r--r-- | doc/manual/index.rst | 16 |
4 files changed, 76 insertions, 35 deletions
diff --git a/doc/manual/cipher_modes.rst b/doc/manual/cipher_modes.rst index e1ffe5dfd..2bf2c23ad 100644 --- a/doc/manual/cipher_modes.rst +++ b/doc/manual/cipher_modes.rst @@ -102,10 +102,13 @@ with PKCS#7 padding. std::unique_ptr<Botan::Cipher_Mode> enc = Botan::Cipher_Mode::create("AES-128/CBC/PKCS7", Botan::ENCRYPTION); enc->set_key(key); + //generate fresh nonce (IV) + Botan::secure_vector<uint8_t> iv = rng.random_vec(enc->default_nonce_length()); + + // Copy input data to a buffer that will be encrypted Botan::secure_vector<uint8_t> pt(plaintext.data(), plaintext.data()+plaintext.length()); - //generate fresh nonce (IV) - enc->start(rng.random_vec(enc->default_nonce_length())); + enc->start(iv); enc->finish(pt); std::cout << enc->name() << " with iv " << Botan::hex_encode(iv) << " " << Botan::hex_encode(pt) << "\n"; @@ -140,7 +143,7 @@ CFB Available if ``BOTAN_HAS_MODE_CFB`` is defined. -CFB uses a block cipher to create a self-syncronizing stream cipher. It is used +CFB uses a block cipher to create a self-syncronizing stream cipher. It is used for example in the OpenPGP protocol. There is no reason to prefer it. XTS @@ -301,8 +304,8 @@ Available if ``BOTAN_HAS_AEAD_SIV`` is defined. Requires a 128-bit block cipher. Unlike other AEADs, SIV is "misuse resistent"; if a nonce is repeated, SIV retains security, with the exception that if the same nonce is used to encrypt the same message multiple times, an attacker can -detect the duplicated message (this is because for identical plaintexts SIV -will output the same ciphertext each time, in the case the nonce is repeated.) +detect the fact that the message was duplicated (this is simply because if both +the nonce and the message are reused, SIV will output identical ciphertexts). CCM ~~~~~ diff --git a/doc/manual/cli.rst b/doc/manual/cli.rst index 592aeafbc..c88e1ee90 100644 --- a/doc/manual/cli.rst +++ b/doc/manual/cli.rst @@ -11,14 +11,18 @@ 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. +``--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. Hash Function ---------------- -``hash --algo=SHA-256 --buf-size=4096 files`` +``hash --algo=SHA-256 --buf-size=4096 --no-fsname 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. + 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 ---------------- @@ -32,10 +36,11 @@ Password Hash HMAC ---------------- -``hmac --hash=SHA-256 --buf-size=4096 key files`` +``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. + defaults to STDIN. Unless the ``--no-fsname`` option is given, the + filename is printed alongside the HMAC value. Public Key Cryptography ------------------------------------- @@ -53,13 +58,21 @@ Public Key Cryptography - 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 "PBE-PKCS5v20(AES-256/CBC,SHA-256)". + + With PBE-PKCS5v20 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 "PBE-PKCS5v20(AES-256/CBC,Scrypt)" + ``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 --der-format --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 @@ -68,13 +81,17 @@ Public Key Cryptography - 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`` + 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. + +``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 --type=subgroup`` +``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 @@ -82,6 +99,10 @@ Public Key Cryptography 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 standarized DH group @@ -185,6 +206,7 @@ Number Theory ``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 150 bits or so. ``gen_prime --count=1 bits`` Samples *count* primes with a length of *bits* bits. @@ -192,7 +214,7 @@ Number Theory PSK Database -------------------- -Only available if sqlite3 support was compiled in. +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``, @@ -230,12 +252,14 @@ Data Encoding/Decoding Miscellaneous Commands ------------------------------------- ``version --full`` - Print the version number. If option ``-full`` is provided additional details are printed. + 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``. + ``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, ...). @@ -244,18 +268,21 @@ Miscellaneous Commands Decode and print *file* with ASN.1 Basic Encoding Rules (BER). ``http_get url`` - Retrieve ressource from the passed http/https *url*. + Retrieve ressource from the passed http *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. +``speed --msec=500 --provider= --buf-size=1024 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. ``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. + *system* is set, the system RNG is used. If *system* is unset and *rdrand* is + set, the hardware RDRAND instruction is used if available. If both are unset, + HMAC_DRBG is used. ``cc_encrypt CC passphrase --tweak=`` Encrypt the passed valid credit card number *CC* using FPE encryption and the diff --git a/doc/manual/hash.rst b/doc/manual/hash.rst index f76f6363c..9dadb4336 100644 --- a/doc/manual/hash.rst +++ b/doc/manual/hash.rst @@ -65,7 +65,7 @@ internal state is reset to begin hashing a new message. Code Example ------------ -Assume we want to calculate the SHA-1, Whirlpool and SHA-3 hash digests of the STDIN stream using the Botan library. +Assume we want to calculate the SHA-256, SHA-384, and SHA-3 hash digests of the STDIN stream using the Botan library. .. code-block:: cpp @@ -74,8 +74,8 @@ Assume we want to calculate the SHA-1, Whirlpool and SHA-3 hash digests of the S #include <iostream> int main () { - std::unique_ptr<Botan::HashFunction> hash1(Botan::HashFunction::create("SHA-1")); - std::unique_ptr<Botan::HashFunction> hash2(Botan::HashFunction::create("Whirlpool")); + std::unique_ptr<Botan::HashFunction> hash1(Botan::HashFunction::create("SHA-256")); + std::unique_ptr<Botan::HashFunction> hash2(Botan::HashFunction::create("SHA-384")); std::unique_ptr<Botan::HashFunction> hash3(Botan::HashFunction::create("SHA-3")); std::vector<uint8_t> buf(2048); @@ -89,8 +89,8 @@ Assume we want to calculate the SHA-1, Whirlpool and SHA-3 hash digests of the S hash2->update(buf.data(),readcount); hash3->update(buf.data(),readcount); } - std::cout << "SHA-1: " << Botan::hex_encode(hash1->final()) << std::endl; - std::cout << "Whirlpool: " << Botan::hex_encode(hash2->final()) << std::endl; + std::cout << "SHA-256: " << Botan::hex_encode(hash1->final()) << std::endl; + std::cout << "SHA-384: " << Botan::hex_encode(hash2->final()) << std::endl; std::cout << "SHA-3: " << Botan::hex_encode(hash3->final()) << std::endl; return 0; } @@ -222,8 +222,9 @@ Tiger Available if ``BOTAN_HAS_TIGER`` is defined. -An older 192-bit hash function, optimized for 64-bit systems. Seemingly secure -but not widely used. Prefer Skein-512 or BLAKE2b in new code. +An older 192-bit hash function, optimized for 64-bit systems. Possibly +vulnerable to side channels due to its use of table lookups. Prefer Skein-512 or +BLAKE2b in new code. Whirlpool ^^^^^^^^^^^^^^^ @@ -246,7 +247,7 @@ Parallel Available if ``BOTAN_HAS_PARALLEL_HASH`` is defined. -Parallel simply concatenated multiple hash functions. For example +Parallel simply concatenates multiple hash functions. For example "Parallel(SHA-256,SHA-512)" outputs a 256+512 bit hash created by hashing the input with both SHA-256 and SHA-512 and concatenating the outputs. diff --git a/doc/manual/index.rst b/doc/manual/index.rst index e094967d2..d61d508e4 100644 --- a/doc/manual/index.rst +++ b/doc/manual/index.rst @@ -14,6 +14,14 @@ source may not be required on your system. You can also download this manual as a `PDF <https://botan.randombit.net/manual/botan.pdf>`_. +Examples +---------- + +Some examples of usage are included in this documentation. However a better +source for example code is in the implementation of the +`command line interface <https://github.com/randombit/botan/tree/master/src/cli>`_, +which was intentionally written to act as practical examples of usage. + Books and other references ---------------------------- @@ -36,11 +44,13 @@ Especially recommended are: by Alfred J. Menezes, Paul C. Van Oorschot, and Scott A. Vanstone If you're doing something non-trivial or unique, you might want to at -the very least ask for review/input on a mailing list such as the +the very least ask for review/input at a place such as the `metzdowd <http://www.metzdowd.com/mailman/listinfo/cryptography>`_ or `randombit <https://lists.randombit.net/mailman/listinfo/cryptography>`_ -crypto lists. And (if possible) pay a professional cryptographer or -security company to review your design and code. +mailing lists or the +`cryptography stack exchange <https://crypto.stackexchange.com/>`_. +And (if possible) pay a professional cryptographer or security company +to review your design and code. .. toctree:: |