More pubkey doc updates

68 files changed, 79 insertions, 97 deletions

diff --git a/examples/GNUmakefile b/doc/examples/GNUmakefile
index c386f4390..c386f4390 100644
--- a/examples/GNUmakefile
+++ b/doc/examples/GNUmakefile
diff --git a/examples/asn1.cpp b/doc/examples/asn1.cpp
index b0a6aa104..b0a6aa104 100644
--- a/examples/asn1.cpp
+++ b/doc/examples/asn1.cpp
diff --git a/examples/base64.cpp b/doc/examples/base64.cpp
index dbe8d19e3..dbe8d19e3 100644
--- a/examples/base64.cpp
+++ b/doc/examples/base64.cpp
diff --git a/examples/bcrypt.cpp b/doc/examples/bcrypt.cpp
index 27a98cf33..27a98cf33 100644
--- a/examples/bcrypt.cpp
+++ b/doc/examples/bcrypt.cpp
diff --git a/examples/bench.cpp b/doc/examples/bench.cpp
index 20e6ec40b..20e6ec40b 100644
--- a/examples/bench.cpp
+++ b/doc/examples/bench.cpp
diff --git a/examples/benchmark.cpp b/doc/examples/benchmark.cpp
index 7ad1775e2..7ad1775e2 100644
--- a/examples/benchmark.cpp
+++ b/doc/examples/benchmark.cpp
diff --git a/examples/bzip.cpp b/doc/examples/bzip.cpp
index 6137bb6af..6137bb6af 100644
--- a/examples/bzip.cpp
+++ b/doc/examples/bzip.cpp
diff --git a/examples/ca.cpp b/doc/examples/ca.cpp
index 8dd3e981f..8dd3e981f 100644
--- a/examples/ca.cpp
+++ b/doc/examples/ca.cpp
diff --git a/examples/cert_verify.cpp b/doc/examples/cert_verify.cpp
index 04bcbecad..04bcbecad 100644
--- a/examples/cert_verify.cpp
+++ b/doc/examples/cert_verify.cpp
diff --git a/examples/checksum.cpp b/doc/examples/checksum.cpp
index dba7a7d70..dba7a7d70 100644
--- a/examples/checksum.cpp
+++ b/doc/examples/checksum.cpp
diff --git a/examples/cms_dec.cpp b/doc/examples/cms_dec.cpp
index 84355fb4a..84355fb4a 100644
--- a/examples/cms_dec.cpp
+++ b/doc/examples/cms_dec.cpp
diff --git a/examples/cms_enc.cpp b/doc/examples/cms_enc.cpp
index 2cf813987..2cf813987 100644
--- a/examples/cms_enc.cpp
+++ b/doc/examples/cms_enc.cpp
diff --git a/examples/cpuid.cpp b/doc/examples/cpuid.cpp
index 6d4cc7593..6d4cc7593 100644
--- a/examples/cpuid.cpp
+++ b/doc/examples/cpuid.cpp
diff --git a/examples/cryptobox.cpp b/doc/examples/cryptobox.cpp
index 38d750d17..38d750d17 100644
--- a/examples/cryptobox.cpp
+++ b/doc/examples/cryptobox.cpp
diff --git a/examples/decrypt.cpp b/doc/examples/decrypt.cpp
index ea510c5e9..ea510c5e9 100644
--- a/examples/decrypt.cpp
+++ b/doc/examples/decrypt.cpp
diff --git a/examples/dh.cpp b/doc/examples/dh.cpp
index 652c7b136..8489df8fe 100644
--- a/examples/dh.cpp
+++ b/doc/examples/dh.cpp
@@ -1,9 +1,3 @@
-/*
-* (C) 2009-2010 Jack Lloyd
-*
-* Distributed under the terms of the Botan license
-*/
-
 #include <botan/botan.h>
 #include <botan/dh.h>
 #include <botan/pubkey.h>
@@ -14,41 +8,36 @@ using namespace Botan;
 
 int main()
    {
-   Botan::LibraryInitializer init;
-
    try
       {
+      LibraryInitializer init;
+
       AutoSeeded_RNG rng;
 
       // Alice and Bob agree on a DH domain to use
-      DL_Group shared_domain("modp/ietf/1024");
+      DL_Group shared_domain("modp/ietf/2048");
 
-      // Alice creates a DH key and sends (the public part) to Bob
+      // Alice creates a DH key
       DH_PrivateKey private_a(rng, shared_domain);
 
-      // Alice sends to Bob her public key:
-      MemoryVector<byte> public_a = private_a.public_value();
-
       // Bob creates a key with a matching group
       DH_PrivateKey private_b(rng, shared_domain);
 
+      // Alice sends to Bob her public key and a session parameter
+      MemoryVector<byte> public_a = private_a.public_value();
+      const std::string session_param =
+         "Alice and Bob's shared session parameter";
+
       // Bob sends his public key to Alice
       MemoryVector<byte> public_b = private_b.public_value();
 
-      PK_Key_Agreement ka1(private_a, "KDF2(SHA-1)");
-      PK_Key_Agreement ka2(private_b, "KDF2(SHA-1)");
-
-      /*
-      * Preferably, include some salt or parameter that binds this key
-      * generation to the current session (for instance a session
-      * identifier, if guaranteed unique, would be a good choice).  Or
-      * anything else that both sides can agree on that will never
-      * repeat.
-      */
-      const std::string ka_salt = "alice and bob agree on a key";
+      // 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 = ka1.derive_key(32, public_b, ka_salt);
-      SymmetricKey bob_key = ka2.derive_key(32, public_a, ka_salt);
+      // 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);
 
       if(alice_key == bob_key)
          {
diff --git a/examples/dsa_kgen.cpp b/doc/examples/dsa_kgen.cpp
index fe3157370..fe3157370 100644
--- a/examples/dsa_kgen.cpp
+++ b/doc/examples/dsa_kgen.cpp
diff --git a/examples/dsa_sign.cpp b/doc/examples/dsa_sign.cpp
index 5f02c0dc1..5f02c0dc1 100644
--- a/examples/dsa_sign.cpp
+++ b/doc/examples/dsa_sign.cpp
diff --git a/examples/dsa_ver.cpp b/doc/examples/dsa_ver.cpp
index a666259c1..a666259c1 100644
--- a/examples/dsa_ver.cpp
+++ b/doc/examples/dsa_ver.cpp
diff --git a/examples/eax_test.cpp b/doc/examples/eax_test.cpp
index 32311800d..32311800d 100644
--- a/examples/eax_test.cpp
+++ b/doc/examples/eax_test.cpp
diff --git a/examples/eax_tv.txt b/doc/examples/eax_tv.txt
index 95cd7c1ab..95cd7c1ab 100644
--- a/examples/eax_tv.txt
+++ b/doc/examples/eax_tv.txt
diff --git a/examples/ecdsa.cpp b/doc/examples/ecdsa.cpp
index df1e1b93a..df1e1b93a 100644
--- a/examples/ecdsa.cpp
+++ b/doc/examples/ecdsa.cpp
diff --git a/examples/encrypt.cpp b/doc/examples/encrypt.cpp
index 28017d875..28017d875 100644
--- a/examples/encrypt.cpp
+++ b/doc/examples/encrypt.cpp
diff --git a/examples/encrypt2.cpp b/doc/examples/encrypt2.cpp
index 41f4fb478..41f4fb478 100644
--- a/examples/encrypt2.cpp
+++ b/doc/examples/encrypt2.cpp
diff --git a/examples/factor.cpp b/doc/examples/factor.cpp
index 58b12d9a5..58b12d9a5 100644
--- a/examples/factor.cpp
+++ b/doc/examples/factor.cpp
diff --git a/examples/fpe.cpp b/doc/examples/fpe.cpp
index 9b18d4879..9b18d4879 100644
--- a/examples/fpe.cpp
+++ b/doc/examples/fpe.cpp
diff --git a/examples/gen_certs.cpp b/doc/examples/gen_certs.cpp
index f8c9fe124..f8c9fe124 100644
--- a/examples/gen_certs.cpp
+++ b/doc/examples/gen_certs.cpp
diff --git a/examples/gtk/Makefile b/doc/examples/gtk/Makefile
index 10e069bb3..10e069bb3 100644
--- a/examples/gtk/Makefile
+++ b/doc/examples/gtk/Makefile
diff --git a/examples/gtk/dsa.cpp b/doc/examples/gtk/dsa.cpp
index 2cd91b0e8..2cd91b0e8 100644
--- a/examples/gtk/dsa.cpp
+++ b/doc/examples/gtk/dsa.cpp
diff --git a/examples/gtk/gtk_ui.cpp b/doc/examples/gtk/gtk_ui.cpp
index d4e9cd238..d4e9cd238 100644
--- a/examples/gtk/gtk_ui.cpp
+++ b/doc/examples/gtk/gtk_ui.cpp
diff --git a/examples/gtk/gtk_ui.h b/doc/examples/gtk/gtk_ui.h
index 065a4f76b..065a4f76b 100644
--- a/examples/gtk/gtk_ui.h
+++ b/doc/examples/gtk/gtk_ui.h
diff --git a/examples/gtk/readme.txt b/doc/examples/gtk/readme.txt
index 4f3691166..4f3691166 100644
--- a/examples/gtk/readme.txt
+++ b/doc/examples/gtk/readme.txt
diff --git a/examples/hash.cpp b/doc/examples/hash.cpp
index 1a4ca1b64..1a4ca1b64 100644
--- a/examples/hash.cpp
+++ b/doc/examples/hash.cpp
diff --git a/examples/hash_fd.cpp b/doc/examples/hash_fd.cpp
index 32acdbec3..32acdbec3 100644
--- a/examples/hash_fd.cpp
+++ b/doc/examples/hash_fd.cpp
diff --git a/examples/hash_quickly.cpp b/doc/examples/hash_quickly.cpp
index 005a6d719..005a6d719 100644
--- a/examples/hash_quickly.cpp
+++ b/doc/examples/hash_quickly.cpp
diff --git a/examples/hasher.cpp b/doc/examples/hasher.cpp
index e5c52ba55..e5c52ba55 100644
--- a/examples/hasher.cpp
+++ b/doc/examples/hasher.cpp
diff --git a/examples/hasher2.cpp b/doc/examples/hasher2.cpp
index b6303b644..b6303b644 100644
--- a/examples/hasher2.cpp
+++ b/doc/examples/hasher2.cpp
diff --git a/examples/keywrap.cpp b/doc/examples/keywrap.cpp
index 730bcb6c9..730bcb6c9 100644
--- a/examples/keywrap.cpp
+++ b/doc/examples/keywrap.cpp
diff --git a/examples/make_prime.cpp b/doc/examples/make_prime.cpp
index acaaac698..acaaac698 100644
--- a/examples/make_prime.cpp
+++ b/doc/examples/make_prime.cpp
diff --git a/examples/new_engine.cpp b/doc/examples/new_engine.cpp
index 42e5dbe33..42e5dbe33 100644
--- a/examples/new_engine.cpp
+++ b/doc/examples/new_engine.cpp
diff --git a/examples/package.cpp b/doc/examples/package.cpp
index 02cf52816..02cf52816 100644
--- a/examples/package.cpp
+++ b/doc/examples/package.cpp
diff --git a/examples/passhash.cpp b/doc/examples/passhash.cpp
index 586c28c3f..586c28c3f 100644
--- a/examples/passhash.cpp
+++ b/doc/examples/passhash.cpp
diff --git a/examples/pkcs10.cpp b/doc/examples/pkcs10.cpp
index 3f5ec8e05..3f5ec8e05 100644
--- a/examples/pkcs10.cpp
+++ b/doc/examples/pkcs10.cpp
diff --git a/examples/pqg_gen.cpp b/doc/examples/pqg_gen.cpp
index c033dac3b..c033dac3b 100644
--- a/examples/pqg_gen.cpp
+++ b/doc/examples/pqg_gen.cpp
diff --git a/examples/python/cipher.py b/doc/examples/python/cipher.py
index 1be2759ae..1be2759ae 100755
--- a/examples/python/cipher.py
+++ b/doc/examples/python/cipher.py
diff --git a/examples/python/cryptobox.py b/doc/examples/python/cryptobox.py
index f76ed6bc3..f76ed6bc3 100755
--- a/examples/python/cryptobox.py
+++ b/doc/examples/python/cryptobox.py
diff --git a/examples/python/nisttest.py b/doc/examples/python/nisttest.py
index 3ea8fda0f..3ea8fda0f 100755
--- a/examples/python/nisttest.py
+++ b/doc/examples/python/nisttest.py
diff --git a/examples/python/results.txt b/doc/examples/python/results.txt
index 7a3824001..7a3824001 100644
--- a/examples/python/results.txt
+++ b/doc/examples/python/results.txt
diff --git a/examples/python/rng_test.py b/doc/examples/python/rng_test.py
index 06c79b84e..06c79b84e 100755
--- a/examples/python/rng_test.py
+++ b/doc/examples/python/rng_test.py
diff --git a/examples/python/rsa.py b/doc/examples/python/rsa.py
index 8ca95ff8b..8ca95ff8b 100755
--- a/examples/python/rsa.py
+++ b/doc/examples/python/rsa.py
diff --git a/examples/read_ssh.cpp b/doc/examples/read_ssh.cpp
index f6299a29d..f6299a29d 100644
--- a/examples/read_ssh.cpp
+++ b/doc/examples/read_ssh.cpp
diff --git a/examples/readme.txt b/doc/examples/readme.txt
index fb6a03ddf..fb6a03ddf 100644
--- a/examples/readme.txt
+++ b/doc/examples/readme.txt
diff --git a/examples/rng_test.cpp b/doc/examples/rng_test.cpp
index c0d24fd80..c0d24fd80 100644
--- a/examples/rng_test.cpp
+++ b/doc/examples/rng_test.cpp
diff --git a/examples/row_encryptor.cpp b/doc/examples/row_encryptor.cpp
index 685850945..685850945 100644
--- a/examples/row_encryptor.cpp
+++ b/doc/examples/row_encryptor.cpp
diff --git a/examples/rsa_dec.cpp b/doc/examples/rsa_dec.cpp
index 81592328c..81592328c 100644
--- a/examples/rsa_dec.cpp
+++ b/doc/examples/rsa_dec.cpp
diff --git a/examples/rsa_enc.cpp b/doc/examples/rsa_enc.cpp
index ac609c4b3..ac609c4b3 100644
--- a/examples/rsa_enc.cpp
+++ b/doc/examples/rsa_enc.cpp
diff --git a/examples/rsa_kgen.cpp b/doc/examples/rsa_kgen.cpp
index f4566263b..f4566263b 100644
--- a/examples/rsa_kgen.cpp
+++ b/doc/examples/rsa_kgen.cpp
diff --git a/examples/rsa_manykey.cpp b/doc/examples/rsa_manykey.cpp
index e6a511753..e6a511753 100644
--- a/examples/rsa_manykey.cpp
+++ b/doc/examples/rsa_manykey.cpp
diff --git a/examples/self_sig.cpp b/doc/examples/self_sig.cpp
index 6710cfb51..6710cfb51 100644
--- a/examples/self_sig.cpp
+++ b/doc/examples/self_sig.cpp
diff --git a/examples/sig_gen.cpp b/doc/examples/sig_gen.cpp
index cf273216a..cf273216a 100644
--- a/examples/sig_gen.cpp
+++ b/doc/examples/sig_gen.cpp
diff --git a/examples/socket.h b/doc/examples/socket.h
index c4fa46600..c4fa46600 100644
--- a/examples/socket.h
+++ b/doc/examples/socket.h
diff --git a/examples/stack.cpp b/doc/examples/stack.cpp
index 0c00ed183..0c00ed183 100644
--- a/examples/stack.cpp
+++ b/doc/examples/stack.cpp
diff --git a/examples/tls_client.cpp b/doc/examples/tls_client.cpp
index 9f6f6229a..9f6f6229a 100644
--- a/examples/tls_client.cpp
+++ b/doc/examples/tls_client.cpp
diff --git a/examples/tls_server.cpp b/doc/examples/tls_server.cpp
index 087ba86fa..087ba86fa 100644
--- a/examples/tls_server.cpp
+++ b/doc/examples/tls_server.cpp
diff --git a/examples/toolbox.cpp b/doc/examples/toolbox.cpp
index 622a1f56f..622a1f56f 100644
--- a/examples/toolbox.cpp
+++ b/doc/examples/toolbox.cpp
diff --git a/examples/tss.cpp b/doc/examples/tss.cpp
index 03d7699bf..03d7699bf 100644
--- a/examples/tss.cpp
+++ b/doc/examples/tss.cpp
diff --git a/examples/x509info.cpp b/doc/examples/x509info.cpp
index b22b4ebd8..b22b4ebd8 100644
--- a/examples/x509info.cpp
+++ b/doc/examples/x509info.cpp
diff --git a/doc/pubkey.txt b/doc/pubkey.txt
index 1be471e1b..254880f65 100644
--- a/doc/pubkey.txt
+++ b/doc/pubkey.txt
@@ -99,8 +99,9 @@ predefined ``BigInt`` private key value is different:
   constructors described above, to match the integer modulo prime
   versions. Only use them if you really need them.
 
+.. _serializing_private_keys:
 
-Serializing Private Keys
+Serializing Private Keys Using PKCS #8
 ----------------------------------------
 
 The standard format for serializing a private key is PKCS #8, the
@@ -157,7 +158,16 @@ decrypt, if necessary) a PKCS #8 private key:
 
 .. cpp:function:: Private_Key* PKCS8::load_key(const std::string& filename, RandomNumberGenerator& rng, const std::string& passphrase = "")
 
-The result is an object allocated using ``new``.
+These functions will return an object allocated key object based on
+the data from whatever source it is using (assuming, of course, the
+source is in fact storing a representation of a private key, and the
+decryption was sucessful). The encoding used (PEM or BER) need not be
+specified; the format will be detected automatically. The key is
+allocated with ``new``, and should be released with ``delete`` when
+you are done with it. The first takes a generic ``DataSource`` that
+you have to create - the other is a simple wrapper functions that take
+either a filename or a memory buffer and create the appropriate
+``DataSource``.
 
 The versions that pass the passphrase as a ``std::string`` are
 primarily for compatibility, but they are useful in limited
@@ -179,6 +189,25 @@ passphrase passed in first, and then it cancels.
   In a future version, it is likely that ``User_Interface`` will be
   replaced by a simple callback using ``std::function``.
 
+Serializing Public Keys
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To import and export public keys, use:
+
+.. cpp:function:: MemoryVector<byte> X509::BER_encode(const Public_Key& key)
+
+.. cpp:function:: std::string X509::PEM_encode(const Public_Key& key)
+
+.. cpp:function:: Public_Key* X509::load_key(DataSource& in)
+
+.. cpp:function:: Public_Key* X509::load_key(const SecureVector<byte>& buffer)
+
+.. cpp:function:: Public_Key* X509::load_key(const std::string& filename)
+
+  These functions operate in the same way as the ones described in
+  :ref:`serializing_private_keys`, except that no encryption option is
+  availabe.
+
 .. _dl_group:
 
 DL_Group
@@ -224,7 +253,7 @@ You can generate a new random group using
   bits. If the *type* is ``Prime_Subgroup`` or ``DSA_Kosherizer``,
   then *qbits* specifies the size of the subgroup.
 
-You can export a ``DL_Group`` using
+You can serialize a ``DL_Group`` using
 
 .. cpp:function:: SecureVector<byte> DL_Group::DER_Encode(Format format)
 
@@ -232,13 +261,28 @@ or
 
 .. cpp:function:: std::string DL_Group::PEM_encode(Format format)
 
-where *format* is any of 
+where *format* is any of
+
+* ``ANSI_X9_42`` (or ``DH_PARAMETERS``) for modp groups
+* ``ANSI_X9_57`` (or ``DSA_PARAMETERS``) for DSA-style groups
+* ``PKCS_3`` is an older format for modp groups; it should only
+  be used for backwards compatability.
+
+You can reload a serialized group using
+
+.. cpp:function:: void DL_Group::BER_decode(DataSource& source, Format format)
+
+.. cpp:function:: void DL_Group::PEM_decode(DataSource& source)
 
 .. _ec_dompar:
 
 EC_Domain_Params
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+An ``EC_Domain_Params`` is initialized by passing the name of the
+group to be used to the constructor. These groups have
+semi-standardized names like "secp256r1" and "brainpool512r1".
+
 Key Checking
 ---------------------------------
 
@@ -246,22 +290,20 @@ Most public key algorithms have limitations or restrictions on their
 parameters. For example RSA requires an odd exponent, and algorithms
 based on the discrete logarithm problem need a generator $> 1$.
 
-Each low-level public key type has a function named ``check_key`` that
-takes a ``bool``. This function returns a Boolean value that declares
-whether or not the key is valid (from an algorithmic standpoint). For
-example, it will check to make sure that the prime parameters of a DSA
-key are, in fact, prime. It does not have anything to do with the
-validity of the key for any particular use, nor does it have anything
-to do with certificates that link a key (which, after all, is just
-some numbers) with a user or other entity. If ``check_key``'s argument
-is ``true``, then it does "strong" checking, which includes expensive
-operations like primality checking.
-
-Keys are always checked when they are loaded or generated, so typically there
-is no reason to use this function directly. However, you can disable or reduce
-the checks for particular cases (public keys, loaded private keys, generated
-private keys) by setting the right config toggle (see the section on the
-configuration subsystem for details).
+Each public key type has a function
+
+.. cpp:function:: bool Public_Key::check_key(RandomNumberGenerator& rng, bool strong)
+
+  This function performs a number of algorithm-specific tests that the
+  key seems to be mathematically valid and consistent, and returns
+  true if all of the tests pass.
+
+  It does not have anything to do with the validity of the key for any
+  particular use, nor does it have anything to do with certificates
+  that link a key (which, after all, is just some numbers) with a user
+  or other entity. If *strong* is ``true``, then it does "strong"
+  checking, which includes expensive operations like primality
+  checking.
 
 Getting a PK algorithm object
 ---------------------------------
@@ -423,55 +465,6 @@ in new applications. The X9.42 algorithm may be useful in some
 circumstances, but unless you need X9.42 compatibility, KDF2 is easier
 to use.
 
-There is a Diffie-Hellman example included in the distribution, which you may
-want to examine.
-
-.. _pk_import_export:
-
-Importing and Exporting Keys
----------------------------------
-
-There are many, many different (often conflicting) standards
-surrounding public key cryptography. There is, thankfully, only two
-major standards surrounding the representation of a public or private
-key: the X.509 subject public key info format (for public keys), and
-PKCS #8 (for private keys). Other crypto libraries, such as Crypto++
-and OpenSSL, also support these formats, so you can easily exchange
-keys with software that doesn't use Botan.
-
-In addition to "plain" public keys, Botan also supports X.509
-certificates.  These are documented in :ref:`x509_certificates`.
-
-.. _import_export_public_keys:
-
-Importing/Exporting Public Keys
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To import and export public keys, use:
-
-.. cpp:function:: MemoryVector<byte> X509::BER_encode(const Public_Key& key)
-
-
-.. cpp:function:: std::string X509::PEM_encode(const Public_Key& key)
-
-
-.. cpp:function:: Public_Key* X509::load_key(DataSource& in)
-
-.. cpp:function:: Public_Key* X509::load_key(const SecureVector<byte>& buffer)
-
-.. cpp:function:: Public_Key* X509::load_key(const std::string& filename)
-
-  For loading a public key, use one of the variants of ``load_key``.
-  This function will return a newly allocated key based on the data
-  from whatever source it is using (assuming, of course, the source is
-  in fact storing a representation of a public key). The encoding used
-  (PEM or BER) need not be specified; the format will be detected
-  automatically. The key is allocated with ``new``, and should be
-  released with ``delete`` when you are done with it. The first takes
-  a generic ``DataSource`` that you have to create - the other is a
-  simple wrapper functions that take either a filename or a memory
-  buffer and create the appropriate ``DataSource``.
-
-Importing/Exporting Private Keys
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+An example of using Diffie-Hellman:
 
+.. literalinclude:: examples/dh.cpp