diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/building.rst | 4 | ||||
| -rw-r--r-- | doc/deprecated.rst | 294 | ||||
| -rw-r--r-- | doc/dev_ref/todo.rst | 18 | ||||
| -rw-r--r-- | doc/side_channels.rst | 10 |
4 files changed, 228 insertions, 98 deletions
diff --git a/doc/building.rst b/doc/building.rst index 0c7608341..9227c8a6e 100644 --- a/doc/building.rst +++ b/doc/building.rst @@ -434,8 +434,8 @@ not exist until after you run the script for the first time). Also included in ``build/build.h`` are macros which let applications check which features are included in the current version of the library. All of them begin with ``BOTAN_HAS_``. For example, if -``BOTAN_HAS_BLOWFISH`` is defined, then an application can include -``<botan/blowfish.h>`` and use the Blowfish class. +``BOTAN_HAS_RSA`` is defined, then an application knows that this +version of the library has RSA available. ``BOTAN_MP_WORD_BITS``: This macro controls the size of the words used for calculations with the MPI implementation in Botan. It must be set to either 32 diff --git a/doc/deprecated.rst b/doc/deprecated.rst index 57fa9957c..8f81bd719 100644 --- a/doc/deprecated.rst +++ b/doc/deprecated.rst @@ -1,74 +1,61 @@ Deprecated Features ======================== -The following functionality is currently deprecated, and will likely -be removed in a future release. If you think you have a good reason to -be using one of the following, contact the developers to explain your -use case if you want to make sure your code continues to work. +Certain functionality is deprecated and is likely to be removed in +a future major release. -This is in addition to specific API calls marked with BOTAN_DEPRECATED -in the source. +To help warn users, macros are used to annotate deprecated functions +and headers. These warnings are enabled by default, but can be +disabled by defining the macro ``BOTAN_NO_DEPRECATED_WARNINGS`` prior +to including any Botan headers. -- Configuring a build (with ``configure.py``) using Python2. In a future - major release, Python3 will be required. +.. warning:: + Not all of the functionality which is currently deprecated has an + associated warning. -- Using the Python wrapper with Python2. - -- Directly using an algorithm class like ``AES_128`` or ``SHA_256``. Instead - create the objects via a ``T::create`` call. A future major release may - make such declarations private. - -- Directly accessing the member variables of types calendar_point, ASN1_Attribute, - AlgorithmIdentifier, and BER_Object - -- The following headers are currently public, but will be completely - removed in a future major release: ``botan.h``, ``init.h``, - ``lookup.h``, ``threefish.h``, ``sm2_enc.h``, ``datastor.h``, - ``basefilt.h``, ``hex_filt.h``, ``b64_filt.h``, ``comp_filter.h``, - ``key_filt.h``, ``buf_filt.h``, ``cipher_filter.h``, - ``tls_blocking.h``, ``pbkdf1.h``, ``xmss_key_pair.h``, - -- The following headers are currently public, but will be made - internal in a future major release, and no longer usable by - applications: ``rotate.h``, ``loadstor.h``, ``mul128.h``, - ``dyn_load.h``, ``atomic.h``, ``blinding.h``, ``gf2m_small_m.h``, - ``locking_allocator.h``, ``polyn_gf2m.h`,, ``parsing.h``, - ``rfc6979.h``, ``divide.h``, ``charset.h``, ``secqueue.h``, - ``keypair.h``, ``http_util.h``, ``scan_name.h``, ``ghash.h``, - ``tls_extensions.h``, ``tls_messages.h``, ``tls_algos.h``, - ``tls_magic.h``, ``oids.h``, ``stl_compatability.h``, ``bswap.h``, - ``calendar.h``, ``curve_nistp.h``, ``curve_gfp.h``, ``eme.h``, - ``eme_pkcs.h``, ``eme_raw.h``, ``oaep.h``, ``emsa1.h``, ``emsa.h``, - ``emsa_pkcs1.h``, ``emsa_raw.h``, ``emsa_x931.h``, ``hash_id.h``, - ``iso9796.h``, ``pssr.h``, ``kdf1.h``, ``kdf1_iso18033.h``, - ``kdf2.h``, ``sp800_108.h``, ``sp800_56a.h``, ``sp800_56c.h``, - ``prf_tls.h``, ``prf_x942.h``, ``mode_pad.h``, ``monty.h``, - ``mul128.h``, ``pbes2.h``, ``pbkdf2.h``, ``pk_ops.h``, - ``pow_mod.h``, ``reducer.h``, ``stream_mode.h``, ``workfactor.h``, - ``xmss_common_ops.h``, ``xmss_tools.h``, ``xmss_hash.h``, - ``xmss_tools.h``, +If you are using something which is currently deprecated and there +doesn't seem to be an obvious alternative, contact the developers to +explain your use case if you want to make sure your code continues to +work. -- Using a default output length for "SHAKE-128" and "SHAKE-256". Instead, - always specify the desired output length. +TLS Protocol Deprecations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- All or nothing package transform (``package.h``) +The following TLS protocol features are deprecated and will be removed +in a future major release: -- The TLS constructors taking `std::function` for callbacks. Instead - use the TLS::Callbacks interface. +- Support for TLSv1.0/v1.1 and DTLS v1.0 -- Using ``X509_Certificate::subject_info`` and ``issuer_info`` to access any - information that is not included in the DN or subject alternative name. Prefer - using the specific assessor functions for other data, eg instead of - ``cert.subject_info("X509.Certificate.serial")`` use ``cert.serial_number()``. +- All support for DSA ciphersuites/certificates -- The Buffered_Computation base class. In a future release the class will be - removed, and all of member functions instead declared directly on - MessageAuthenticationCode and HashFunction. So this only affects you if you - are directly referencing `Botan::Buffered_Computation` in some way. +- Support for point compression in TLS. This is supported in v1.2 but + removed in v1.3. For simplicity it will be removed in v1.2 also. -- Platform support for Google Native Client +- Support for using SHA-1 to sign TLS v1.2 ServerKeyExchange. -- Support for PathScale and HP compilers +- All CBC mode ciphersuites. This includes all available 3DES and SEED + ciphersuites. This implies also removing Encrypt-then-MAC extension. + +- All ciphersuites using DH key exchange (DHE-DSS, DHE-RSA, DHE-PSK, anon DH) + +- All ciphersuites using static RSA key exchange + +- All anonymous (DH/ECDH) ciphersuites. This does not include PSK and + ECDHE-PSK, which will be retained. + +- SRP ciphersuites. This is implied by the removal of CBC mode, since + all available SRP ciphersuites use CBC. To avoid use of obsolete + ciphers, it would be better to instead perform a standard TLS + negotiation, then a PAKE authentication within (and bound to) the + TLS channel. + +- OCB ciphersuites using 128-bit keys + +Deprecated Functionality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This section lists cryptographic functionality which will be removed +in a future major release. - Block ciphers CAST-256, Kasumi, MISTY1, and DESX. @@ -89,35 +76,184 @@ in the source. - All pre-created DSA groups -TLS Protocol Deprecations ---------------------------- +- All or nothing package transform (``package.h``) -The following TLS protocol features are deprecated and will be removed -in a future major release: -- Support for TLSv1.0/v1.1 and DTLS v1.0 +Deprecated Headers +^^^^^^^^^^^^^^^^^^^^^^ + +* The following headers and all functionality contained within them + are outright deprecated, and will be removed entirely in a future + major release. Most are either simply forwarding includes to another + (still public) header, or contain functionality which is entirely + deprecated. Consult the relevent file for more information. + ``basefilt.h``, ``botan.h``, ``buf_filt.h``, ``cipher_filter.h``, ``comp_filter.h``, + ``compiler.h``, ``init.h``, ``key_filt.h``, ``lookup.h``, ``sm2_enc.h``, ``threefish.h``, + ``xmss_key_pair.h`` + +* The following headers have useful functionality but which we wish to + hide from applications to allow easier library evolution. They will + be made internal in a future major release, and will only be + available to the library itself. In most cases, there is an + alternative available. For example instead of using algorithm + specific interfaces, use X::create to create the object dynamically. + ``adler32.h``, + ``aes.h``, + ``aria.h``, + ``atomic.h``, + ``bcrypt_pbkdf.h``, + ``blake2b.h``, + ``blinding.h``, + ``blowfish.h``, + ``bswap.h``, + ``camellia.h``, + ``cascade.h``, + ``cast128.h``, + ``cast256.h``, + ``cbc.h``, + ``cbc_mac.h``, + ``ccm.h``, + ``cfb.h``, + ``chacha20poly1305.h``, + ``chacha.h``, + ``charset.h``, + ``cmac.h``, + ``comb4p.h``, + ``compiler.h``, + ``cpuid.h``, + ``crc24.h``, + ``crc32.h``, + ``ctr.h``, + ``curve_gfp.h``, + ``curve_nistp.h``, + ``datastor.h``, + ``des.h``, + ``desx.h``, + ``divide.h``, + ``eax.h``, + ``eme.h``, + ``eme_pkcs.h``, + ``eme_raw.h``, + ``emsa1.h``, + ``emsa.h``, + ``emsa_pkcs1.h``, + ``emsa_raw.h``, + ``emsa_x931.h``, + ``gcm.h``, + ``gf2m_small_m.h``, + ``ghash.h``, + ``gmac.h``, + ``gost_28147.h``, + ``gost_3411.h``, + ``hash_id.h``, + ``hkdf.h``, + ``hmac.h``, + ``http_util.h``, + ``idea.h``, + ``iso9796.h``, + ``kasumi.h``, + ``kdf1.h``, + ``kdf1_iso18033.h``, + ``kdf2.h``, + ``keccak.h``, + ``keypair.h``, + ``lion.h``, + ``loadstor.h``, + ``locking_allocator.h``, + ``md4.h``, + ``md5.h``, + ``mdx_hash.h``, + ``misty1.h``, + ``mode_pad.h``, + ``mul128.h``, + ``noekeon.h``, + ``oaep.h``, + ``ocb.h``, + ``ofb.h``, + ``par_hash.h``, + ``parsing.h``, + ``pbes2.h``, + ``pbkdf1.h``, + ``pbkdf2.h``, + ``pgp_s2k.h``, + ``poly1305.h``, + ``polyn_gf2m.h``, + ``pow_mod.h``, + ``prf_tls.h``, + ``prf_x942.h``, + ``pssr.h``, + ``rc4.h``, + ``rfc6979.h``, + ``rmd160.h``, + ``rotate.h``, + ``salsa20.h``, + ``scan_name.h``, + ``scrypt.h``, + ``secqueue.h``, + ``seed.h``, + ``serpent.h``, + ``sha160.h``, + ``sha2_32.h``, + ``sha2_64.h``, + ``sha3.h``, + ``shacal2.h``, + ``shake_cipher.h``, + ``shake.h``, + ``siphash.h``, + ``siv.h``, + ``skein_512.h``, + ``sm3.h``, + ``sm4.h``, + ``sp800_108.h``, + ``sp800_56a.h``, + ``sp800_56c.h``, + ``stl_compatibility.h``, + ``stream_mode.h``, + ``streebog.h``, + ``threefish_512.h``, + ``tiger.h``, + ``tls_algos.h``, + ``tls_magic.h``, + ``twofish.h``, + ``uuid.h``, + ``whrlpool.h``, + ``x919_mac.h``, + ``xmss_common_ops.h``, + ``xmss_hash.h``, + ``xmss_index_registry.h``, + ``xmss_tools.h``, + ``xtea.h``, + ``xts.h``, -- All support for DSA ciphersuites/certificates +Other API deprecations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- Support for point compression in TLS. This is supported in v1.2 but - removed in v1.3. For simplicity it will be removed in v1.2 also. +- Directly accessing the member variables of types ``calendar_point``, + ``ASN1_Attribute``, ``AlgorithmIdentifier``, and ``BER_Object`` -- Support for using SHA-1 to sign TLS v1.2 ServerKeyExchange. +- Using a default output length for "SHAKE-128" and "SHAKE-256". Instead, + always specify the desired output length. -- All CBC mode ciphersuites. This includes all available 3DES and SEED - ciphersuites. This implies also removing Encrypt-then-MAC extension. +- The TLS constructors taking ``std::function`` for callbacks. Instead + use the ``TLS::Callbacks`` interface. -- All ciphersuites using DH key exchange (DHE-DSS, DHE-RSA, DHE-PSK, anon DH) +- Using ``X509_Certificate::subject_info`` and ``issuer_info`` to access any + information that is not included in the DN or subject alternative name. Prefer + using the specific assessor functions for other data, eg instead of + ``cert.subject_info("X509.Certificate.serial")`` use ``cert.serial_number()``. -- All ciphersuites using static RSA key exchange +- The ``Buffered_Computation`` base class. In a future release the + class will be removed, and all of member functions instead declared + directly on ``MessageAuthenticationCode`` and ``HashFunction``. So + this only affects you if you are directly referencing + ``Botan::Buffered_Computation`` in some way. -- All anonymous (DH/ECDH) ciphersuites. This does not include PSK and - ECDHE-PSK, which will be retained. +Deprecated Build Targets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- SRP ciphersuites. This is implied by the removal of CBC mode, since - all available SRP ciphersuites use CBC. To avoid use of obsolete - ciphers, it would be better to instead perform a standard TLS - negotiation, then a PAKE authentication within (and bound to) the - TLS channel. +- Configuring a build (with ``configure.py``) using Python2. In a future + major release, Python3 will be required. -- OCB ciphersuites using 128-bit keys +- Platform support for Google Native Client + +- Support for PathScale and HP compilers diff --git a/doc/dev_ref/todo.rst b/doc/dev_ref/todo.rst index 714722f30..6c1dadf8f 100644 --- a/doc/dev_ref/todo.rst +++ b/doc/dev_ref/todo.rst @@ -12,8 +12,7 @@ Ciphers, Hashes, PBKDF * Stiched AES-NI GCM mode * Bitsliced AES or Camellia -* Compressed tables for AES -* AES using vector permutes for NEON +* Vector permute AES only supports little-endian systems; fix for big-endian * Camellia using AES-NI * Poly1305 using AVX2 * ASCON 1.2 (CAESAR) @@ -39,7 +38,7 @@ Public Key Crypto, Math * Abstract representation of ECC point elements to allow specific implementations of the field arithmetic depending upon the curve. * Use NAF (joint sparse form) for ECC multi-exponentiation -* Curves for pairings (BN-256 is widely implemented) +* Curves for pairings (BN-256, BLS12-381) * Identity based encryption * BBS group signatures * Paillier homomorphic cryptosystem @@ -60,6 +59,9 @@ Utility Functions * Add a memory span type * Make Memory_Pool more concurrent (currently uses a global lock) +* Guarded integer type to prevent overflow bugs +* Add logging callbacks +* Add latency tracing framework Multiparty Protocols ---------------------- @@ -77,9 +79,7 @@ External Providers, Hardware Support * Extend Apple CommonCrypto provider (HMAC, CMAC, RSA, ECDSA, ECDH) * Support iOS keychain access * POWER8 crypto extensions (SHA-2, GCM) -* POWER9 on-chip RNG (DARN) * Better TPM support: NVRAM, PCR measurements, sealing -* Intel SGX support * Support Intel QuickAssist accelerator cards TLS @@ -163,13 +163,6 @@ Python * Write a CLI or HTTPS client in Python -Library Infrastructure ----------------------------------------- - -* Guarded integer type to prevent overflow bugs -* Add logging callbacks -* Add latency tracing framework - Build/Test ---------------------------------------- @@ -188,6 +181,7 @@ Build/Test * Add support for vxWorks * Add support for Fuschia OS * Add support for CloudABI +* Add support for SGX FIPS 140 Build --------------------------------------- diff --git a/doc/side_channels.rst b/doc/side_channels.rst index 5fe660171..3880b9c75 100644 --- a/doc/side_channels.rst +++ b/doc/side_channels.rst @@ -245,10 +245,9 @@ are fast and are thought to be side channel silent. These instructions are used when available. On CPUs which do not have hardware AES instructions but do support SIMD vectors -with a byte shuffle (including x86's SSSE3 and ARM's NEON), a version of AES is -implemented which is side channel silent. This version is based on code by Mike -Hamburg [VectorAes], see aes_vperm.cpp. This same technique could be applied -with AltiVec, and the paper suggests some optimizations for the AltiVec shuffle. +with a byte shuffle (including x86's SSSE3, ARM's NEON and PowerPC AltiVec), a +version of AES is implemented which is side channel silent. This implementation +is based on code by Mike Hamburg [VectorAes], see aes_vperm.cpp. On all other processors, a table lookup version (T-tables) is used. This approach is relatively fast, but known to be very vulnerable to side @@ -333,7 +332,8 @@ Hash Functions Most hash functions included in Botan such as MD5, SHA-1, SHA-2, SHA-3, Skein, and BLAKE2 do not require any input-dependent memory lookups, and so seem to not be -affected by common CPU side channels. +affected by common CPU side channels. However the implementations of Whirlpool +and Streebog use table lookups and probably can be attacked by side channels. Memory comparisons ---------------------- |