diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/algos.txt | 7 | ||||
| -rw-r--r-- | doc/conf.py | 8 | ||||
| -rw-r--r-- | doc/examples.txt | 30 | ||||
| -rw-r--r-- | doc/examples/asn1.cpp | 6 | ||||
| -rw-r--r-- | doc/examples/dh.cpp | 4 | ||||
| -rw-r--r-- | doc/examples/dsa_sign.cpp | 1 | ||||
| -rw-r--r-- | doc/examples/tls_client.cpp | 2 | ||||
| -rw-r--r-- | doc/index.txt | 1 | ||||
| -rw-r--r-- | doc/lowlevel.txt | 94 | ||||
| -rw-r--r-- | doc/pubkey.txt | 8 |
10 files changed, 62 insertions, 99 deletions
diff --git a/doc/algos.txt b/doc/algos.txt index bf2a91b0c..3d4050c11 100644 --- a/doc/algos.txt +++ b/doc/algos.txt @@ -73,7 +73,6 @@ primitives, including: * PRFs from ANSI X9.42, SSL v3.0, TLS v1.0 - Recommended Algorithms --------------------------------- @@ -143,8 +142,8 @@ match that in SCAN, if it's defined there). **Stream Ciphers:** "ARC4", "MARK4", "Salsa20", "Turing", "WiderWake4+1-BE" -**Hash Functions:** "HAS-160", "GOST-34.11", "MD2", "MD4", "MD5", -"RIPEMD-128", "RIPEMD-160", "SHA-160", "SHA-256", "SHA-384", -"SHA-512", "Skein-512", "Tiger(OUTSZ)", "Whirlpool" +**Hash Functions:** "HAS-160", "GOST-34.11", "Keccak-1600(OUTSZ)", +"MD2", "MD4", "MD5", "RIPEMD-128", "RIPEMD-160", "SHA-160", "SHA-256", +"SHA-384", "SHA-512", "Skein-512", "Tiger(OUTSZ)", "Whirlpool" **MACs:** "HMAC(HASH)", "CMAC(BLOCK)", "X9.19-MAC" diff --git a/doc/conf.py b/doc/conf.py index e0600da81..f4884cb69 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -80,7 +80,7 @@ exclude_patterns = ['_build'] #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +add_function_parentheses = False # If true, the current module name will be prepended to all description # unit titles (such as .. function::). @@ -190,7 +190,7 @@ htmlhelp_basename = 'botandoc' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'botan.tex', u'botan Documentation', + ('index', 'botan.tex', u'botan Reference Manual', u'Jack Lloyd', 'manual'), ] @@ -203,10 +203,10 @@ latex_documents = [ #latex_use_parts = False # If true, show page references after internal links. -#latex_show_pagerefs = False +latex_show_pagerefs = True # If true, show URL addresses after external links. -#latex_show_urls = False +latex_show_urls = True # Additional stuff for the LaTeX preamble. #latex_preamble = '' diff --git a/doc/examples.txt b/doc/examples.txt index e0fd3ab40..b9296829a 100644 --- a/doc/examples.txt +++ b/doc/examples.txt @@ -2,24 +2,6 @@ Examples ======================================== -DSA Examples ----------------------------------------- - -DSA Signature Generation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Reads a DSA private key and signs the specified file using SHA-1 - -.. literalinclude:: examples/dsa_sign.cpp - -DSA Signature Verification -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Reads a DSA public key and a signature, and checks if the signature -is valid for the specified file - -..literalinclude:: examples/dsa_ver.cpp - X.509 Certificate Examples ---------------------------------------- @@ -52,18 +34,6 @@ expected in "cacert.pem", the private key is expected in .. literalinclude:: examples/ca.cpp - -Format Preserving Encryption ----------------------------------------- - -Format preserving encryption is a way of mapping data with an -arbitrarily specified format such that the ciphertext has the same -formatting. This example encrypts a credit card number with a valid -`Luhn checksum <http://en.wikipedia.org/wiki/Luhn_algorithm>`_ to -another number with the same format, including a correct checksum. - -.. literalinclude:: examples/fpe.cpp - ASN.1 Parsing ---------------------------------------- diff --git a/doc/examples/asn1.cpp b/doc/examples/asn1.cpp index bb891d746..95e5b2627 100644 --- a/doc/examples/asn1.cpp +++ b/doc/examples/asn1.cpp @@ -21,8 +21,8 @@ using namespace Botan; */ #define INITIAL_LEVEL 0 -void decode(BER_Decoder&, u32bit); -void emit(const std::string&, u32bit, u32bit, const std::string& = ""); +void decode(BER_Decoder&, size_t); +void emit(const std::string&, size_t, size_t, const std::string& = ""); std::string type_name(ASN1_Tag); int main(int argc, char* argv[]) @@ -243,7 +243,7 @@ void emit(const std::string& type, size_t level, size_t length, const size_t BIN_LIMIT = 64; int written = 0; - written += printf(" d=%2d, l=%4d: ", level, length); + written += printf(" d=%2d, l=%4d: ", (int)level, (int)length); for(size_t i = INITIAL_LEVEL; i != level; ++i) written += printf(" "); written += printf("%s ", type.c_str()); diff --git a/doc/examples/dh.cpp b/doc/examples/dh.cpp index 8489df8fe..8d163303a 100644 --- a/doc/examples/dh.cpp +++ b/doc/examples/dh.cpp @@ -33,11 +33,11 @@ int main() // Now Alice performs the key agreement operation PK_Key_Agreement ka_alice(private_a, "KDF2(SHA-256)"); - SymmetricKey alice_key = ka1.derive_key(32, public_b, session_param); + SymmetricKey alice_key = ka_alice.derive_key(32, public_b, session_param); // Bob does the same: PK_Key_Agreement ka_bob(private_b, "KDF2(SHA-256)"); - SymmetricKey bob_key = ka2.derive_key(32, public_a, session_param); + SymmetricKey bob_key = ka_bob.derive_key(32, public_a, session_param); if(alice_key == bob_key) { diff --git a/doc/examples/dsa_sign.cpp b/doc/examples/dsa_sign.cpp index 827fc7e0a..3511eacfa 100644 --- a/doc/examples/dsa_sign.cpp +++ b/doc/examples/dsa_sign.cpp @@ -7,6 +7,7 @@ #include <botan/botan.h> #include <botan/pubkey.h> #include <botan/dsa.h> +#include <botan/base64.h> using namespace Botan; const std::string SUFFIX = ".sig"; diff --git a/doc/examples/tls_client.cpp b/doc/examples/tls_client.cpp index 6c5ad7bde..eb4a98817 100644 --- a/doc/examples/tls_client.cpp +++ b/doc/examples/tls_client.cpp @@ -1,4 +1,4 @@ -#include <botan/init.h> +#include <botan/botan.h> #include <botan/tls_client.h> #include "socket.h" diff --git a/doc/index.txt b/doc/index.txt index 081f065ba..ca3795e88 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -18,6 +18,7 @@ Contents: passhash rng kdf + fpe bigint examples algos diff --git a/doc/lowlevel.txt b/doc/lowlevel.txt index 9f1c7bc42..5b3ec42b2 100644 --- a/doc/lowlevel.txt +++ b/doc/lowlevel.txt @@ -57,13 +57,13 @@ Since often it's hard to distinguish between a key and IV, many things .. cpp:function:: OctetString::OctetString(RandomNumberGenerator& rng, size_t length) - This constructor creates a new random key ``length`` bytes long - using the random number generator. + This constructor creates a new random key *length* bytes long using + the random number generator. .. cpp:function:: OctetString::OctetString(std::string str) - The argument ``str`` is assumed to be a hex string; it is converted - to binary and stored. Whitespace is ignored. + The argument *str* is assumed to be a hex string; it is converted to + binary and stored. Whitespace is ignored. .. cpp:function:: OctetString::OctetString(const byte* input, size_t length) @@ -99,8 +99,8 @@ restrictions on the size of the key: .. cpp:function:: bool SymmetricAlgorithm::valid_keylength(size_t length) const - This function returns true if and only if ``length`` is a valid keylength - for the algorithm. + This function returns true if and only if *length* is a valid + keylength for the algorithm. .. cpp:function:: size_t SymmetricAlgorithm::minimum_keylength() const @@ -122,35 +122,35 @@ Block ciphers implement the interface ``BlockCipher``, found in Returns the block size of the cipher in bytes -.. cpp:function:: void BlockCipher::encrypt_n(const byte* in, byte* out, size_t blocks) const +.. cpp:function:: void BlockCipher::encrypt_n(const byte* in, byte* out, size_t n) const - Encrypt ``blocks`` blocks of data, taking the input from ``in`` and - placing the ciphertext in ``out``. The two pointers may be + Encrypt *n* blocks of data, taking the input from the array *in* and + placing the ciphertext into *out*. The two pointers may be identical, but should not overlap ranges. .. cpp:function:: void BlockCipher::encrypt(const byte* in, byte* out) const - Encrypt a single block, taking the input from ``in`` and placing it - in ``out``. + Encrypt a single block, taking the input from *in* and placing it + in *out*. Acts like :cpp:func:`encrypt_n`\ (in, out, 1). .. cpp:function:: void BlockCipher::encrypt(byte* block) const - Identical to ``encrypt(block, block)``. + Identical to :cpp:func:`encrypt`\ (block, block) -.. cpp:function:: void BlockCipher::decrypt_n(const byte* in, byte out, size_t blocks) const +.. cpp:function:: void BlockCipher::decrypt_n(const byte* in, byte out, size_t n) const - Decrypt ``blocks`` blocks of data, taking the input from ``in`` and - placing the plaintext in ``out``. The two pointers may be identical, - but should not overlap ranges. + Decrypt *n* blocks of data, taking the input from *in* and placing + the plaintext in *out*. The two pointers may be identical, but + should not overlap ranges. .. cpp:function:: void BlockCipher::decrypt(const byte* in, byte* out) const - Decrypt a single block, taking the input from ``in`` and placing it - in ``out``. + Decrypt a single block, taking the input from *in* and placing it + in *out*. Acts like :cpp:func:`decrypt_n`\ (in, out, 1). .. cpp:function:: void BlockCipher::decrypt(byte* block) const - Identical to ``decrypt(block, block)``. + Identical to :cpp:func:`decrypt`\ (block, block) Stream Ciphers @@ -186,7 +186,7 @@ Return the size of the output of this function. .. cpp:function:: void BufferedComputation::update(const std::string& input) -Updates the hash/mac calculation with ``input``. +Updates the hash/mac calculation with *input*. .. cpp:function:: void BufferedComputation::final(byte* out) @@ -228,22 +228,6 @@ intended purpose (error checking), they perform very well. Some examples of checksums included in Botan are the Adler32 and CRC32 checksums. -Threads and Mutexes ---------------------------------- - -Botan includes a mutex system, which is used internally to lock some shared -data structures that must be kept shared for efficiency reasons (mostly, these -are in the allocation systems~--~handing out 1000 separate allocators hurts -performance and makes caching memory blocks useless). This system is supported -by the ``mux_pthr`` module, implementing the ``Mutex`` interface for -systems that have POSIX threads. - -If your application is using threads, you *must* add the option -"thread_safe" to the options string when you create the -``LibraryInitializer`` object. If you specify this option and no mutex -type is available, an exception is thrown, since otherwise you would -probably be facing a nasty crash. - Secure Memory --------------------------------- @@ -279,17 +263,18 @@ These types are not described in any great detail: for more information, consult the definitive sources~--~the header files ``secmem.h`` and ``allocate.h``. -``SecureBuffer`` is a simple array type, whose size is specified at compile -time. It will automatically convert to a pointer of the appropriate type, and -has a number of useful functions, including ``clear()``, and -``size_t`` ``size()``, which returns the length of the array. It is a -template that takes as parameters a type, and a constant integer which is how -long the array is (for example: ``SecureBuffer<byte, 8> key;``). +``SecureBuffer`` is a simple array type, whose size is specified at +compile time. It will automatically convert to a pointer of the +appropriate type, and has a number of useful functions, including +``clear()``, and ``size_t`` ``size()``, which returns the length of +the array. It is a template that takes as parameters a type, and a +constant integer which is how long the array is (for example: +``SecureBuffer<byte, 8> key;``). -``SecureVector`` is a variable length array. Its size can be increased or -decreased as need be, and it has a wide variety of functions useful for copying -data into its buffer. Like ``SecureBuffer``, it implements ``clear`` -and ``size``. +``SecureVector`` is a variable length array. Its size can be increased +or decreased as need be, and it has a wide variety of functions useful +for copying data into its buffer. Like ``SecureBuffer``, it implements +``clear`` and ``size``. Allocators ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -297,14 +282,14 @@ Allocators The containers described above get their memory from allocators. As a user of the library, you can add new allocator methods at run time for containers, including the ones used internally by the library, to -use. The interface to this is in ``allocate.h``. Code needing -to allocate or deallocate memory calls ``get_allocator``, -which returns a pointer to an allocator object. This pointer should -not be freed: the caller does not own the allocator (it is shared -among multiple allocatore users, and uses a mutex to serialize access -internally if necessary). It is possible to call -``get_allocator`` with a specific name to request a particular -type of allocator, otherwise, a default allocator type is returned. +use. The interface to this is in ``allocate.h``. Code needing to +allocate or deallocate memory calls ``get_allocator``, which returns a +pointer to an allocator object. This pointer should not be freed: the +caller does not own the allocator (it is shared among multiple +allocatore users, and uses a mutex to serialize access internally if +necessary). It is possible to call ``get_allocator`` with a specific +name to request a particular type of allocator, otherwise, a default +allocator type is returned. At start time, the only allocator known is a ``Default_Allocator``, which just allocates memory using ``malloc``, and zeroizes it when the @@ -323,4 +308,3 @@ allocator was successfully registered. If you ask it to, Finally, you can set the default allocator type that will be returned using the policy setting "default_alloc" to the name of any previously registered allocator. - diff --git a/doc/pubkey.txt b/doc/pubkey.txt index f48f28340..fe24c719b 100644 --- a/doc/pubkey.txt +++ b/doc/pubkey.txt @@ -458,6 +458,14 @@ For DSA, ECDSA, GOST-34.11, and Nyberg-Rueppel, you should use EMSA1. None of the other encoding methods are particularly useful for these algorithms. +Here is an example of DSA signature generation + +.. literalinclude:: examples/dsa_sign.cpp + +Here is an example that verifies DSA signatures + +.. literalinclude:: examples/dsa_ver.cpp + Key Agreement --------------------------------- |