aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorSimon L. B. Nielsen <simon@FreeBSD.org>2008-08-23 10:51:00 +0000
committerSimon L. B. Nielsen <simon@FreeBSD.org>2008-08-23 10:51:00 +0000
commitc4a78426bef17a0a7c81195c2b2399e7441f14ad (patch)
tree596c39f00d5968b1519e8cd7f0546412b14c20f0 /doc
parenta0ddfe4e7233d81e88a86217b7653708db2720fa (diff)
downloadsrc-c4a78426bef17a0a7c81195c2b2399e7441f14ad.tar.gz
src-c4a78426bef17a0a7c81195c2b2399e7441f14ad.zip
Flatten OpenSSL vendor tree.
Notes
Notes: svn path=/vendor-crypto/openssl/dist/; revision=182044
Diffstat (limited to 'doc')
-rw-r--r--doc/HOWTO/certificates.txt105
-rw-r--r--doc/HOWTO/keys.txt73
-rw-r--r--doc/HOWTO/proxy_certificates.txt322
-rw-r--r--doc/README12
-rw-r--r--doc/apps/CA.pl.pod179
-rw-r--r--doc/apps/asn1parse.pod171
-rw-r--r--doc/apps/ca.pod671
-rw-r--r--doc/apps/ciphers.pod418
-rw-r--r--doc/apps/config.pod279
-rw-r--r--doc/apps/crl.pod117
-rw-r--r--doc/apps/crl2pkcs7.pod91
-rw-r--r--doc/apps/dgst.pod110
-rw-r--r--doc/apps/dhparam.pod141
-rw-r--r--doc/apps/dsa.pod158
-rw-r--r--doc/apps/dsaparam.pod110
-rw-r--r--doc/apps/ec.pod190
-rw-r--r--doc/apps/ecparam.pod179
-rw-r--r--doc/apps/enc.pod271
-rw-r--r--doc/apps/errstr.pod39
-rw-r--r--doc/apps/gendsa.pod66
-rw-r--r--doc/apps/genrsa.pod96
-rw-r--r--doc/apps/nseq.pod70
-rw-r--r--doc/apps/ocsp.pod365
-rw-r--r--doc/apps/openssl.pod345
-rw-r--r--doc/apps/passwd.pod82
-rw-r--r--doc/apps/pkcs12.pod330
-rw-r--r--doc/apps/pkcs7.pod105
-rw-r--r--doc/apps/pkcs8.pod243
-rw-r--r--doc/apps/rand.pod50
-rw-r--r--doc/apps/req.pod611
-rw-r--r--doc/apps/rsa.pod189
-rw-r--r--doc/apps/rsautl.pod183
-rw-r--r--doc/apps/s_client.pod266
-rw-r--r--doc/apps/s_server.pod327
-rw-r--r--doc/apps/s_time.pod173
-rw-r--r--doc/apps/sess_id.pod151
-rw-r--r--doc/apps/smime.pod385
-rw-r--r--doc/apps/speed.pod59
-rw-r--r--doc/apps/spkac.pod133
-rw-r--r--doc/apps/verify.pod328
-rw-r--r--doc/apps/version.pod64
-rw-r--r--doc/apps/x509.pod832
-rw-r--r--doc/apps/x509v3_config.pod456
-rw-r--r--doc/c-indentation.el44
-rw-r--r--doc/crypto/ASN1_OBJECT_new.pod43
-rw-r--r--doc/crypto/ASN1_STRING_length.pod81
-rw-r--r--doc/crypto/ASN1_STRING_new.pod44
-rw-r--r--doc/crypto/ASN1_STRING_print_ex.pod96
-rw-r--r--doc/crypto/ASN1_generate_nconf.pod253
-rw-r--r--doc/crypto/BIO_ctrl.pod128
-rw-r--r--doc/crypto/BIO_f_base64.pod81
-rw-r--r--doc/crypto/BIO_f_buffer.pod69
-rw-r--r--doc/crypto/BIO_f_cipher.pod76
-rw-r--r--doc/crypto/BIO_f_md.pod138
-rw-r--r--doc/crypto/BIO_f_null.pod32
-rw-r--r--doc/crypto/BIO_f_ssl.pod313
-rw-r--r--doc/crypto/BIO_find_type.pod98
-rw-r--r--doc/crypto/BIO_new.pod65
-rw-r--r--doc/crypto/BIO_push.pod69
-rw-r--r--doc/crypto/BIO_read.pod66
-rw-r--r--doc/crypto/BIO_s_accept.pod195
-rw-r--r--doc/crypto/BIO_s_bio.pod182
-rw-r--r--doc/crypto/BIO_s_connect.pod192
-rw-r--r--doc/crypto/BIO_s_fd.pod89
-rw-r--r--doc/crypto/BIO_s_file.pod144
-rw-r--r--doc/crypto/BIO_s_mem.pod115
-rw-r--r--doc/crypto/BIO_s_null.pod37
-rw-r--r--doc/crypto/BIO_s_socket.pod63
-rw-r--r--doc/crypto/BIO_set_callback.pod108
-rw-r--r--doc/crypto/BIO_should_retry.pod114
-rw-r--r--doc/crypto/BN_BLINDING_new.pod109
-rw-r--r--doc/crypto/BN_CTX_new.pod53
-rw-r--r--doc/crypto/BN_CTX_start.pod52
-rw-r--r--doc/crypto/BN_add.pod126
-rw-r--r--doc/crypto/BN_add_word.pod61
-rw-r--r--doc/crypto/BN_bn2bin.pod95
-rw-r--r--doc/crypto/BN_cmp.pod48
-rw-r--r--doc/crypto/BN_copy.pod34
-rw-r--r--doc/crypto/BN_generate_prime.pod102
-rw-r--r--doc/crypto/BN_mod_inverse.pod36
-rw-r--r--doc/crypto/BN_mod_mul_montgomery.pod101
-rw-r--r--doc/crypto/BN_mod_mul_reciprocal.pod81
-rw-r--r--doc/crypto/BN_new.pod53
-rw-r--r--doc/crypto/BN_num_bytes.pod57
-rw-r--r--doc/crypto/BN_rand.pod58
-rw-r--r--doc/crypto/BN_set_bit.pod66
-rw-r--r--doc/crypto/BN_swap.pod23
-rw-r--r--doc/crypto/BN_zero.pod59
-rw-r--r--doc/crypto/CONF_modules_free.pod47
-rw-r--r--doc/crypto/CONF_modules_load_file.pod60
-rw-r--r--doc/crypto/CRYPTO_set_ex_data.pod51
-rw-r--r--doc/crypto/DH_generate_key.pod50
-rw-r--r--doc/crypto/DH_generate_parameters.pod73
-rw-r--r--doc/crypto/DH_get_ex_new_index.pod36
-rw-r--r--doc/crypto/DH_new.pod40
-rw-r--r--doc/crypto/DH_set_method.pod129
-rw-r--r--doc/crypto/DH_size.pod33
-rw-r--r--doc/crypto/DSA_SIG_new.pod40
-rw-r--r--doc/crypto/DSA_do_sign.pod47
-rw-r--r--doc/crypto/DSA_dup_DH.pod36
-rw-r--r--doc/crypto/DSA_generate_key.pod34
-rw-r--r--doc/crypto/DSA_generate_parameters.pod105
-rw-r--r--doc/crypto/DSA_get_ex_new_index.pod36
-rw-r--r--doc/crypto/DSA_new.pod42
-rw-r--r--doc/crypto/DSA_set_method.pod143
-rw-r--r--doc/crypto/DSA_sign.pod66
-rw-r--r--doc/crypto/DSA_size.pod33
-rw-r--r--doc/crypto/ERR_GET_LIB.pod51
-rw-r--r--doc/crypto/ERR_clear_error.pod29
-rw-r--r--doc/crypto/ERR_error_string.pod73
-rw-r--r--doc/crypto/ERR_get_error.pod76
-rw-r--r--doc/crypto/ERR_load_crypto_strings.pod46
-rw-r--r--doc/crypto/ERR_load_strings.pod54
-rw-r--r--doc/crypto/ERR_print_errors.pod51
-rw-r--r--doc/crypto/ERR_put_error.pod44
-rw-r--r--doc/crypto/ERR_remove_state.pod34
-rw-r--r--doc/crypto/ERR_set_mark.pod38
-rw-r--r--doc/crypto/EVP_BytesToKey.pod67
-rw-r--r--doc/crypto/EVP_DigestInit.pod256
-rw-r--r--doc/crypto/EVP_EncryptInit.pod511
-rw-r--r--doc/crypto/EVP_OpenInit.pod63
-rw-r--r--doc/crypto/EVP_PKEY_new.pod47
-rw-r--r--doc/crypto/EVP_PKEY_set1_RSA.pod80
-rw-r--r--doc/crypto/EVP_SealInit.pod85
-rw-r--r--doc/crypto/EVP_SignInit.pod95
-rw-r--r--doc/crypto/EVP_VerifyInit.pod86
-rw-r--r--doc/crypto/OBJ_nid2obj.pod149
-rw-r--r--doc/crypto/OPENSSL_Applink.pod21
-rw-r--r--doc/crypto/OPENSSL_VERSION_NUMBER.pod101
-rw-r--r--doc/crypto/OPENSSL_config.pod82
-rw-r--r--doc/crypto/OPENSSL_ia32cap.pod35
-rw-r--r--doc/crypto/OPENSSL_load_builtin_modules.pod51
-rw-r--r--doc/crypto/OpenSSL_add_all_algorithms.pod66
-rw-r--r--doc/crypto/PKCS12_create.pod75
-rw-r--r--doc/crypto/PKCS12_parse.pod50
-rw-r--r--doc/crypto/PKCS7_decrypt.pod53
-rw-r--r--doc/crypto/PKCS7_encrypt.pod65
-rw-r--r--doc/crypto/PKCS7_sign.pod101
-rw-r--r--doc/crypto/PKCS7_verify.pod116
-rw-r--r--doc/crypto/RAND_add.pod77
-rw-r--r--doc/crypto/RAND_bytes.pod47
-rw-r--r--doc/crypto/RAND_cleanup.pod29
-rw-r--r--doc/crypto/RAND_egd.pod85
-rw-r--r--doc/crypto/RAND_load_file.pod53
-rw-r--r--doc/crypto/RAND_set_rand_method.pod83
-rw-r--r--doc/crypto/RSA_blinding_on.pod43
-rw-r--r--doc/crypto/RSA_check_key.pod67
-rw-r--r--doc/crypto/RSA_generate_key.pod69
-rw-r--r--doc/crypto/RSA_get_ex_new_index.pod120
-rw-r--r--doc/crypto/RSA_new.pod41
-rw-r--r--doc/crypto/RSA_padding_add_PKCS1_type_1.pod124
-rw-r--r--doc/crypto/RSA_print.pod49
-rw-r--r--doc/crypto/RSA_private_encrypt.pod70
-rw-r--r--doc/crypto/RSA_public_encrypt.pod84
-rw-r--r--doc/crypto/RSA_set_method.pod202
-rw-r--r--doc/crypto/RSA_sign.pod62
-rw-r--r--doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod59
-rw-r--r--doc/crypto/RSA_size.pod33
-rw-r--r--doc/crypto/SMIME_read_PKCS7.pod71
-rw-r--r--doc/crypto/SMIME_write_PKCS7.pod61
-rw-r--r--doc/crypto/X509_NAME_ENTRY_get_object.pod72
-rw-r--r--doc/crypto/X509_NAME_add_entry_by_txt.pod114
-rw-r--r--doc/crypto/X509_NAME_get_index_by_NID.pod106
-rw-r--r--doc/crypto/X509_NAME_print_ex.pod105
-rw-r--r--doc/crypto/X509_new.pod37
-rw-r--r--doc/crypto/bio.pod54
-rw-r--r--doc/crypto/blowfish.pod112
-rw-r--r--doc/crypto/bn.pod181
-rw-r--r--doc/crypto/bn_internal.pod226
-rw-r--r--doc/crypto/buffer.pod73
-rw-r--r--doc/crypto/crypto.pod85
-rw-r--r--doc/crypto/d2i_ASN1_OBJECT.pod29
-rw-r--r--doc/crypto/d2i_DHparams.pod30
-rw-r--r--doc/crypto/d2i_DSAPublicKey.pod83
-rw-r--r--doc/crypto/d2i_PKCS8PrivateKey.pod56
-rw-r--r--doc/crypto/d2i_RSAPublicKey.pod67
-rw-r--r--doc/crypto/d2i_X509.pod231
-rw-r--r--doc/crypto/d2i_X509_ALGOR.pod30
-rw-r--r--doc/crypto/d2i_X509_CRL.pod37
-rw-r--r--doc/crypto/d2i_X509_NAME.pod31
-rw-r--r--doc/crypto/d2i_X509_REQ.pod36
-rw-r--r--doc/crypto/d2i_X509_SIG.pod30
-rw-r--r--doc/crypto/des.pod358
-rw-r--r--doc/crypto/des_modes.pod255
-rw-r--r--doc/crypto/dh.pod78
-rw-r--r--doc/crypto/dsa.pod114
-rw-r--r--doc/crypto/ecdsa.pod210
-rw-r--r--doc/crypto/engine.pod599
-rw-r--r--doc/crypto/err.pod187
-rw-r--r--doc/crypto/evp.pod45
-rw-r--r--doc/crypto/hmac.pod102
-rw-r--r--doc/crypto/lh_stats.pod60
-rw-r--r--doc/crypto/lhash.pod294
-rw-r--r--doc/crypto/md5.pod101
-rw-r--r--doc/crypto/mdc2.pod64
-rw-r--r--doc/crypto/pem.pod476
-rw-r--r--doc/crypto/rand.pod175
-rw-r--r--doc/crypto/rc4.pod62
-rw-r--r--doc/crypto/ripemd.pod66
-rw-r--r--doc/crypto/rsa.pod123
-rw-r--r--doc/crypto/sha.pod70
-rw-r--r--doc/crypto/threads.pod175
-rw-r--r--doc/crypto/ui.pod194
-rw-r--r--doc/crypto/ui_compat.pod55
-rw-r--r--doc/crypto/x509.pod64
-rw-r--r--doc/fingerprints.txt57
-rw-r--r--doc/openssl-shared.txt32
-rw-r--r--doc/openssl.txt1254
-rw-r--r--doc/openssl_button.gifbin0 -> 2063 bytes
-rw-r--r--doc/openssl_button.html7
-rw-r--r--doc/ssl/SSL_CIPHER_get_name.pod112
-rw-r--r--doc/ssl/SSL_COMP_add_compression_method.pod70
-rw-r--r--doc/ssl/SSL_CTX_add_extra_chain_cert.pod39
-rw-r--r--doc/ssl/SSL_CTX_add_session.pod73
-rw-r--r--doc/ssl/SSL_CTX_ctrl.pod34
-rw-r--r--doc/ssl/SSL_CTX_flush_sessions.pod49
-rw-r--r--doc/ssl/SSL_CTX_free.pod41
-rw-r--r--doc/ssl/SSL_CTX_get_ex_new_index.pod53
-rw-r--r--doc/ssl/SSL_CTX_get_verify_mode.pod50
-rw-r--r--doc/ssl/SSL_CTX_load_verify_locations.pod124
-rw-r--r--doc/ssl/SSL_CTX_new.pod94
-rw-r--r--doc/ssl/SSL_CTX_sess_number.pod76
-rw-r--r--doc/ssl/SSL_CTX_sess_set_cache_size.pod51
-rw-r--r--doc/ssl/SSL_CTX_sess_set_get_cb.pod87
-rw-r--r--doc/ssl/SSL_CTX_sessions.pod34
-rw-r--r--doc/ssl/SSL_CTX_set_cert_store.pod57
-rw-r--r--doc/ssl/SSL_CTX_set_cert_verify_callback.pod75
-rw-r--r--doc/ssl/SSL_CTX_set_cipher_list.pod70
-rw-r--r--doc/ssl/SSL_CTX_set_client_CA_list.pod94
-rw-r--r--doc/ssl/SSL_CTX_set_client_cert_cb.pod94
-rw-r--r--doc/ssl/SSL_CTX_set_default_passwd_cb.pod76
-rw-r--r--doc/ssl/SSL_CTX_set_generate_session_id.pod150
-rw-r--r--doc/ssl/SSL_CTX_set_info_callback.pod153
-rw-r--r--doc/ssl/SSL_CTX_set_max_cert_list.pod77
-rw-r--r--doc/ssl/SSL_CTX_set_mode.pod81
-rw-r--r--doc/ssl/SSL_CTX_set_msg_callback.pod99
-rw-r--r--doc/ssl/SSL_CTX_set_options.pod235
-rw-r--r--doc/ssl/SSL_CTX_set_quiet_shutdown.pod63
-rw-r--r--doc/ssl/SSL_CTX_set_session_cache_mode.pod137
-rw-r--r--doc/ssl/SSL_CTX_set_session_id_context.pod83
-rw-r--r--doc/ssl/SSL_CTX_set_ssl_version.pod61
-rw-r--r--doc/ssl/SSL_CTX_set_timeout.pod59
-rw-r--r--doc/ssl/SSL_CTX_set_tmp_dh_callback.pod170
-rw-r--r--doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod166
-rw-r--r--doc/ssl/SSL_CTX_set_verify.pod294
-rw-r--r--doc/ssl/SSL_CTX_use_certificate.pod169
-rw-r--r--doc/ssl/SSL_SESSION_free.pod55
-rw-r--r--doc/ssl/SSL_SESSION_get_ex_new_index.pod61
-rw-r--r--doc/ssl/SSL_SESSION_get_time.pod64
-rw-r--r--doc/ssl/SSL_accept.pod76
-rw-r--r--doc/ssl/SSL_alert_type_string.pod228
-rw-r--r--doc/ssl/SSL_clear.pod69
-rw-r--r--doc/ssl/SSL_connect.pod73
-rw-r--r--doc/ssl/SSL_do_handshake.pod75
-rw-r--r--doc/ssl/SSL_free.pod44
-rw-r--r--doc/ssl/SSL_get_SSL_CTX.pod26
-rw-r--r--doc/ssl/SSL_get_ciphers.pod42
-rw-r--r--doc/ssl/SSL_get_client_CA_list.pod53
-rw-r--r--doc/ssl/SSL_get_current_cipher.pod43
-rw-r--r--doc/ssl/SSL_get_default_timeout.pod41
-rw-r--r--doc/ssl/SSL_get_error.pod114
-rw-r--r--doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod61
-rw-r--r--doc/ssl/SSL_get_ex_new_index.pod59
-rw-r--r--doc/ssl/SSL_get_fd.pod44
-rw-r--r--doc/ssl/SSL_get_peer_cert_chain.pod52
-rw-r--r--doc/ssl/SSL_get_peer_certificate.pod55
-rw-r--r--doc/ssl/SSL_get_rbio.pod40
-rw-r--r--doc/ssl/SSL_get_session.pod73
-rw-r--r--doc/ssl/SSL_get_verify_result.pod57
-rw-r--r--doc/ssl/SSL_get_version.pod46
-rw-r--r--doc/ssl/SSL_library_init.pod52
-rw-r--r--doc/ssl/SSL_load_client_CA_file.pod62
-rw-r--r--doc/ssl/SSL_new.pod44
-rw-r--r--doc/ssl/SSL_pending.pod43
-rw-r--r--doc/ssl/SSL_read.pod118
-rw-r--r--doc/ssl/SSL_rstate_string.pod59
-rw-r--r--doc/ssl/SSL_session_reused.pod45
-rw-r--r--doc/ssl/SSL_set_bio.pod34
-rw-r--r--doc/ssl/SSL_set_connect_state.pod55
-rw-r--r--doc/ssl/SSL_set_fd.pod54
-rw-r--r--doc/ssl/SSL_set_session.pod57
-rw-r--r--doc/ssl/SSL_set_shutdown.pod72
-rw-r--r--doc/ssl/SSL_set_verify_result.pod38
-rw-r--r--doc/ssl/SSL_shutdown.pod125
-rw-r--r--doc/ssl/SSL_state_string.pod45
-rw-r--r--doc/ssl/SSL_want.pod77
-rw-r--r--doc/ssl/SSL_write.pod109
-rw-r--r--doc/ssl/d2i_SSL_SESSION.pod66
-rw-r--r--doc/ssl/ssl.pod736
-rw-r--r--doc/ssleay.txt7030
-rw-r--r--doc/standards.txt272
291 files changed, 40371 insertions, 0 deletions
diff --git a/doc/HOWTO/certificates.txt b/doc/HOWTO/certificates.txt
new file mode 100644
index 000000000000..a8a34c7abc51
--- /dev/null
+++ b/doc/HOWTO/certificates.txt
@@ -0,0 +1,105 @@
+<DRAFT!>
+ HOWTO certificates
+
+1. Introduction
+
+How you handle certificates depend a great deal on what your role is.
+Your role can be one or several of:
+
+ - User of some client software
+ - User of some server software
+ - Certificate authority
+
+This file is for users who wish to get a certificate of their own.
+Certificate authorities should read ca.txt.
+
+In all the cases shown below, the standard configuration file, as
+compiled into openssl, will be used. You may find it in /etc/,
+/usr/local/ssl/ or somewhere else. The name is openssl.cnf, and
+is better described in another HOWTO <config.txt?>. If you want to
+use a different configuration file, use the argument '-config {file}'
+with the command shown below.
+
+
+2. Relationship with keys
+
+Certificates are related to public key cryptography by containing a
+public key. To be useful, there must be a corresponding private key
+somewhere. With OpenSSL, public keys are easily derived from private
+keys, so before you create a certificate or a certificate request, you
+need to create a private key.
+
+Private keys are generated with 'openssl genrsa' if you want a RSA
+private key, or 'openssl gendsa' if you want a DSA private key.
+Further information on how to create private keys can be found in
+another HOWTO <keys.txt?>. The rest of this text assumes you have
+a private key in the file privkey.pem.
+
+
+3. Creating a certificate request
+
+To create a certificate, you need to start with a certificate
+request (or, as some certificate authorities like to put
+it, "certificate signing request", since that's exactly what they do,
+they sign it and give you the result back, thus making it authentic
+according to their policies). A certificate request can then be sent
+to a certificate authority to get it signed into a certificate, or if
+you have your own certificate authority, you may sign it yourself, or
+if you need a self-signed certificate (because you just want a test
+certificate or because you are setting up your own CA).
+
+The certificate request is created like this:
+
+ openssl req -new -key privkey.pem -out cert.csr
+
+Now, cert.csr can be sent to the certificate authority, if they can
+handle files in PEM format. If not, use the extra argument '-outform'
+followed by the keyword for the format to use (see another HOWTO
+<formats.txt?>). In some cases, that isn't sufficient and you will
+have to be more creative.
+
+When the certificate authority has then done the checks the need to
+do (and probably gotten payment from you), they will hand over your
+new certificate to you.
+
+Section 5 will tell you more on how to handle the certificate you
+received.
+
+
+4. Creating a self-signed test certificate
+
+If you don't want to deal with another certificate authority, or just
+want to create a test certificate for yourself. This is similar to
+creating a certificate request, but creates a certificate instead of
+a certificate request. This is NOT the recommended way to create a
+CA certificate, see ca.txt.
+
+ openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095
+
+
+5. What to do with the certificate
+
+If you created everything yourself, or if the certificate authority
+was kind enough, your certificate is a raw DER thing in PEM format.
+Your key most definitely is if you have followed the examples above.
+However, some (most?) certificate authorities will encode them with
+things like PKCS7 or PKCS12, or something else. Depending on your
+applications, this may be perfectly OK, it all depends on what they
+know how to decode. If not, There are a number of OpenSSL tools to
+convert between some (most?) formats.
+
+So, depending on your application, you may have to convert your
+certificate and your key to various formats, most often also putting
+them together into one file. The ways to do this is described in
+another HOWTO <formats.txt?>, I will just mention the simplest case.
+In the case of a raw DER thing in PEM format, and assuming that's all
+right for yor applications, simply concatenating the certificate and
+the key into a new file and using that one should be enough. With
+some applications, you don't even have to do that.
+
+
+By now, you have your cetificate and your private key and can start
+using the software that depend on it.
+
+--
+Richard Levitte
diff --git a/doc/HOWTO/keys.txt b/doc/HOWTO/keys.txt
new file mode 100644
index 000000000000..7ae2a3a11833
--- /dev/null
+++ b/doc/HOWTO/keys.txt
@@ -0,0 +1,73 @@
+<DRAFT!>
+ HOWTO keys
+
+1. Introduction
+
+Keys are the basis of public key algorithms and PKI. Keys usually
+come in pairs, with one half being the public key and the other half
+being the private key. With OpenSSL, the private key contains the
+public key information as well, so a public key doesn't need to be
+generated separately.
+
+Public keys come in several flavors, using different cryptographic
+algorithms. The most popular ones associated with certificates are
+RSA and DSA, and this HOWTO will show how to generate each of them.
+
+
+2. To generate a RSA key
+
+A RSA key can be used both for encryption and for signing.
+
+Generating a key for the RSA algorithm is quite easy, all you have to
+do is the following:
+
+ openssl genrsa -des3 -out privkey.pem 2048
+
+With this variant, you will be prompted for a protecting password. If
+you don't want your key to be protected by a password, remove the flag
+'-des3' from the command line above.
+
+ NOTE: if you intend to use the key together with a server
+ certificate, it may be a good thing to avoid protecting it
+ with a password, since that would mean someone would have to
+ type in the password every time the server needs to access
+ the key.
+
+The number 2048 is the size of the key, in bits. Today, 2048 or
+higher is recommended for RSA keys, as fewer amount of bits is
+consider insecure or to be insecure pretty soon.
+
+
+3. To generate a DSA key
+
+A DSA key can be used for signing only. This is important to keep
+in mind to know what kind of purposes a certificate request with a
+DSA key can really be used for.
+
+Generating a key for the DSA algorithm is a two-step process. First,
+you have to generate parameters from which to generate the key:
+
+ openssl dsaparam -out dsaparam.pem 2048
+
+The number 2048 is the size of the key, in bits. Today, 2048 or
+higher is recommended for DSA keys, as fewer amount of bits is
+consider insecure or to be insecure pretty soon.
+
+When that is done, you can generate a key using the parameters in
+question (actually, several keys can be generated from the same
+parameters):
+
+ openssl gendsa -des3 -out privkey.pem dsaparam.pem
+
+With this variant, you will be prompted for a protecting password. If
+you don't want your key to be protected by a password, remove the flag
+'-des3' from the command line above.
+
+ NOTE: if you intend to use the key together with a server
+ certificate, it may be a good thing to avoid protecting it
+ with a password, since that would mean someone would have to
+ type in the password every time the server needs to access
+ the key.
+
+--
+Richard Levitte
diff --git a/doc/HOWTO/proxy_certificates.txt b/doc/HOWTO/proxy_certificates.txt
new file mode 100644
index 000000000000..3d36b02f6b31
--- /dev/null
+++ b/doc/HOWTO/proxy_certificates.txt
@@ -0,0 +1,322 @@
+<DRAFT!>
+ HOWTO proxy certificates
+
+0. WARNING
+
+NONE OF THE CODE PRESENTED HERE HAVE BEEN CHECKED! They are just an
+example to show you how things can be done. There may be typos or
+type conflicts, and you will have to resolve them.
+
+1. Introduction
+
+Proxy certificates are defined in RFC 3820. They are really usual
+certificates with the mandatory extension proxyCertInfo.
+
+Proxy certificates are issued by an End Entity (typically a user),
+either directly with the EE certificate as issuing certificate, or by
+extension through an already issued proxy certificate.. They are used
+to extend rights to some other entity (a computer process, typically,
+or sometimes to the user itself), so it can perform operations in the
+name of the owner of the EE certificate.
+
+See http://www.ietf.org/rfc/rfc3820.txt for more information.
+
+
+2. A warning about proxy certificates
+
+Noone seems to have tested proxy certificates with security in mind.
+Basically, to this date, it seems that proxy certificates have only
+been used in a world that's highly aware of them. What would happen
+if an unsuspecting application is to validate a chain of certificates
+that contains proxy certificates? It would usually consider the leaf
+to be the certificate to check for authorisation data, and since proxy
+certificates are controlled by the EE certificate owner alone, it's
+would be normal to consider what the EE certificate owner could do
+with them.
+
+subjectAltName and issuerAltName are forbidden in proxy certificates,
+and this is enforced in OpenSSL. The subject must be the same as the
+issuer, with one commonName added on.
+
+Possible threats are, as far as has been imagined so far:
+
+ - impersonation through commonName (think server certificates).
+ - use of additional extensions, possibly non-standard ones used in
+ certain environments, that would grant extra or different
+ authorisation rights.
+
+For this reason, OpenSSL requires that the use of proxy certificates
+be explicitely allowed. Currently, this can be done using the
+following methods:
+
+ - if the application calls X509_verify_cert() itself, it can do the
+ following prior to that call (ctx is the pointer passed in the call
+ to X509_verify_cert()):
+
+ X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
+
+ - in all other cases, proxy certificate validation can be enabled
+ before starting the application by setting the envirnoment variable
+ OPENSSL_ALLOW_PROXY with some non-empty value.
+
+There are thoughts to allow proxy certificates with a line in the
+default openssl.cnf, but that's still in the future.
+
+
+3. How to create proxy cerificates
+
+It's quite easy to create proxy certificates, by taking advantage of
+the lack of checks of the 'openssl x509' application (*ahem*). But
+first, you need to create a configuration section that contains a
+definition of the proxyCertInfo extension, a little like this:
+
+ [ v3_proxy ]
+ # A proxy certificate MUST NEVER be a CA certificate.
+ basicConstraints=CA:FALSE
+
+ # Usual authority key ID
+ authorityKeyIdentifier=keyid,issuer:always
+
+ # Now, for the extension that marks this certificate as a proxy one
+ proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB
+
+It's also possible to give the proxy extension in a separate section:
+
+ proxyCertInfo=critical,@proxy_ext
+
+ [ proxy_ext ]
+ language=id-ppl-anyLanguage
+ pathlen=0
+ policy=text:BC
+
+The policy value has a specific syntax, {syntag}:{string}, where the
+syntag determines what will be done with the string. The recognised
+syntags are as follows:
+
+ text indicates that the string is simply the bytes, not
+ encoded in any kind of way:
+
+ policy=text:rksmrgs
+
+ Previous versions of this design had a specific tag
+ for UTF-8 text. However, since the bytes are copied
+ as-is anyway, there's no need for it. Instead, use
+ the text: tag, like this:
+
+ policy=text:räksmörgås
+
+ hex indicates the string is encoded in hex, with colons
+ between each byte (every second hex digit):
+
+ policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73
+
+ Previous versions of this design had a tag to insert a
+ complete DER blob. However, the only legal use for
+ this would be to surround the bytes that would go with
+ the hex: tag with what's needed to construct a correct
+ OCTET STRING. Since hex: does that, the DER tag felt
+ superfluous, and was therefore removed.
+
+ file indicates that the text of the policy should really be
+ taken from a file. The string is then really a file
+ name. This is useful for policies that are large
+ (more than a few of lines) XML documents, for example.
+
+The 'policy' setting can be split up in multiple lines like this:
+
+ 0.policy=This is
+ 1.polisy= a multi-
+ 2.policy=line policy.
+
+NOTE: the proxy policy value is the part that determines the rights
+granted to the process using the proxy certificate. The value is
+completely dependent on the application reading and interpretting it!
+
+Now that you have created an extension section for your proxy
+certificate, you can now easily create a proxy certificate like this:
+
+ openssl req -new -config openssl.cnf \
+ -out proxy.req -keyout proxy.key
+ openssl x509 -req -CAcreateserial -in proxy.req -days 7 \
+ -out proxy.crt -CA user.crt -CAkey user.key \
+ -extfile openssl.cnf -extensions v3_proxy
+
+It's just as easy to create a proxy certificate using another proxy
+certificate as issuer (note that I'm using a different configuration
+section for it):
+
+ openssl req -new -config openssl.cnf \
+ -out proxy2.req -keyout proxy2.key
+ openssl x509 -req -CAcreateserial -in proxy2.req -days 7 \
+ -out proxy2.crt -CA proxy.crt -CAkey proxy.key \
+ -extfile openssl.cnf -extensions v3_proxy2
+
+
+4. How to have your application interpret the policy?
+
+The basic way to interpret proxy policies is to prepare some default
+rights, then do a check of the proxy certificate against the a chain
+of proxy certificates, user certificate and CA certificates, and see
+what rights came out by the end. Sounds easy, huh? It almost is.
+
+The slightly complicated part is how to pass data between your
+application and the certificate validation procedure.
+
+You need the following ingredients:
+
+ - a callback routing that will be called for every certificate that's
+ validated. It will be called several times for each certificates,
+ so you must be attentive to when it's a good time to do the proxy
+ policy interpretation and check, as well as to fill in the defaults
+ when the EE certificate is checked.
+
+ - a structure of data that's shared between your application code and
+ the callback.
+
+ - a wrapper function that sets it all up.
+
+ - an ex_data index function that creates an index into the generic
+ ex_data store that's attached to an X509 validation context.
+
+This is some cookbook code for you to fill in:
+
+ /* In this example, I will use a view of granted rights as a bit
+ array, one bit for each possible right. */
+ typedef struct your_rights {
+ unsigned char rights[total_rights / 8];
+ } YOUR_RIGHTS;
+
+ /* The following procedure will create an index for the ex_data
+ store in the X509 validation context the first time it's called.
+ Subsequent calls will return the same index. */
+ static int get_proxy_auth_ex_data_idx(void)
+ {
+ static volatile int idx = -1;
+ if (idx < 0)
+ {
+ CRYPTO_w_lock(CRYPTO_LOCK_X509_STORE);
+ if (idx < 0)
+ {
+ idx = X509_STORE_CTX_get_ex_new_index(0,
+ "for verify callback",
+ NULL,NULL,NULL);
+ }
+ CRYPTO_w_unlock(CRYPTO_LOCK_X509_STORE);
+ }
+ return idx;
+ }
+
+ /* Callback to be given to the X509 validation procedure. */
+ static int verify_callback(int ok, X509_STORE_CTX *ctx)
+ {
+ if (ok == 1) /* It's REALLY important you keep the proxy policy
+ check within this secion. It's important to know
+ that when ok is 1, the certificates are checked
+ from top to bottom. You get the CA root first,
+ followed by the possible chain of intermediate
+ CAs, followed by the EE certificate, followed by
+ the possible proxy certificates. */
+ {
+ X509 *xs = ctx->current_cert;
+
+ if (xs->ex_flags & EXFLAG_PROXY)
+ {
+ YOUR_RIGHTS *rights =
+ (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
+ get_proxy_auth_ex_data_idx());
+ PROXY_CERT_INFO_EXTENSION *pci =
+ X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL);
+
+ switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage))
+ {
+ case NID_Independent:
+ /* Do whatever you need to grant explicit rights to
+ this particular proxy certificate, usually by
+ pulling them from some database. If there are none
+ to be found, clear all rights (making this and any
+ subsequent proxy certificate void of any rights).
+ */
+ memset(rights->rights, 0, sizeof(rights->rights));
+ break;
+ case NID_id_ppl_inheritAll:
+ /* This is basically a NOP, we simply let the current
+ rights stand as they are. */
+ break;
+ default:
+ /* This is usually the most complex section of code.
+ You really do whatever you want as long as you
+ follow RFC 3820. In the example we use here, the
+ simplest thing to do is to build another, temporary
+ bit array and fill it with the rights granted by
+ the current proxy certificate, then use it as a
+ mask on the accumulated rights bit array, and
+ voil, you now have a new accumulated rights bit
+ array. */
+ {
+ int i;
+ YOUR_RIGHTS tmp_rights;
+ memset(tmp_rights.rights, 0, sizeof(tmp_rights.rights));
+
+ /* process_rights() is supposed to be a procedure
+ that takes a string and it's length, interprets
+ it and sets the bits in the YOUR_RIGHTS pointed
+ at by the third argument. */
+ process_rights((char *) pci->proxyPolicy->policy->data,
+ pci->proxyPolicy->policy->length,
+ &tmp_rights);
+
+ for(i = 0; i < total_rights / 8; i++)
+ rights->rights[i] &= tmp_rights.rights[i];
+ }
+ break;
+ }
+ PROXY_CERT_INFO_EXTENSION_free(pci);
+ }
+ else if (!(xs->ex_flags & EXFLAG_CA))
+ {
+ /* We have a EE certificate, let's use it to set default!
+ */
+ YOUR_RIGHTS *rights =
+ (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
+ get_proxy_auth_ex_data_idx());
+
+ /* The following procedure finds out what rights the owner
+ of the current certificate has, and sets them in the
+ YOUR_RIGHTS structure pointed at by the second
+ argument. */
+ set_default_rights(xs, rights);
+ }
+ }
+ return ok;
+ }
+
+ static int my_X509_verify_cert(X509_STORE_CTX *ctx,
+ YOUR_RIGHTS *needed_rights)
+ {
+ int i;
+ int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) = ctx->verify_cb;
+ YOUR_RIGHTS rights;
+
+ X509_STORE_CTX_set_verify_cb(ctx, verify_callback);
+ X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(), &rights);
+ X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
+ ok = X509_verify_cert(ctx);
+
+ if (ok == 1)
+ {
+ ok = check_needed_rights(rights, needed_rights);
+ }
+
+ X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb);
+
+ return ok;
+ }
+
+If you use SSL or TLS, you can easily set up a callback to have the
+certificates checked properly, using the code above:
+
+ SSL_CTX_set_cert_verify_callback(s_ctx, my_X509_verify_cert, &needed_rights);
+
+
+--
+Richard Levitte
diff --git a/doc/README b/doc/README
new file mode 100644
index 000000000000..6ecc14d99457
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,12 @@
+
+ apps/openssl.pod .... Documentation of OpenSSL `openssl' command
+ crypto/crypto.pod ... Documentation of OpenSSL crypto.h+libcrypto.a
+ ssl/ssl.pod ......... Documentation of OpenSSL ssl.h+libssl.a
+ openssl.txt ......... Assembled documentation files for OpenSSL [not final]
+ ssleay.txt .......... Assembled documentation of ancestor SSLeay [obsolete]
+ standards.txt ....... Assembled pointers to standards, RFCs or internet drafts
+ that are related to OpenSSL.
+
+ An archive of HTML documents for the SSLeay library is available from
+ http://www.columbia.edu/~ariel/ssleay/
+
diff --git a/doc/apps/CA.pl.pod b/doc/apps/CA.pl.pod
new file mode 100644
index 000000000000..ed69952f3799
--- /dev/null
+++ b/doc/apps/CA.pl.pod
@@ -0,0 +1,179 @@
+
+=pod
+
+=head1 NAME
+
+CA.pl - friendlier interface for OpenSSL certificate programs
+
+=head1 SYNOPSIS
+
+B<CA.pl>
+[B<-?>]
+[B<-h>]
+[B<-help>]
+[B<-newcert>]
+[B<-newreq>]
+[B<-newreq-nodes>]
+[B<-newca>]
+[B<-xsign>]
+[B<-sign>]
+[B<-signreq>]
+[B<-signcert>]
+[B<-verify>]
+[B<files>]
+
+=head1 DESCRIPTION
+
+The B<CA.pl> script is a perl script that supplies the relevant command line
+arguments to the B<openssl> command for some common certificate operations.
+It is intended to simplify the process of certificate creation and management
+by the use of some simple options.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<?>, B<-h>, B<-help>
+
+prints a usage message.
+
+=item B<-newcert>
+
+creates a new self signed certificate. The private key and certificate are
+written to the file "newreq.pem".
+
+=item B<-newreq>
+
+creates a new certificate request. The private key and request are
+written to the file "newreq.pem".
+
+=item B<-newreq-nodes>
+
+is like B<-newreq> except that the private key will not be encrypted.
+
+=item B<-newca>
+
+creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert>
+and B<-xsign> options). The user is prompted to enter the filename of the CA
+certificates (which should also contain the private key) or by hitting ENTER
+details of the CA will be prompted for. The relevant files and directories
+are created in a directory called "demoCA" in the current directory.
+
+=item B<-pkcs12>
+
+create a PKCS#12 file containing the user certificate, private key and CA
+certificate. It expects the user certificate and private key to be in the
+file "newcert.pem" and the CA certificate to be in the file demoCA/cacert.pem,
+it creates a file "newcert.p12". This command can thus be called after the
+B<-sign> option. The PKCS#12 file can be imported directly into a browser.
+If there is an additional argument on the command line it will be used as the
+"friendly name" for the certificate (which is typically displayed in the browser
+list box), otherwise the name "My Certificate" is used.
+
+=item B<-sign>, B<-signreq>, B<-xsign>
+
+calls the B<ca> program to sign a certificate request. It expects the request
+to be in the file "newreq.pem". The new certificate is written to the file
+"newcert.pem" except in the case of the B<-xsign> option when it is written
+to standard output.
+
+
+=item B<-signCA>
+
+this option is the same as the B<-signreq> option except it uses the configuration
+file section B<v3_ca> and so makes the signed request a valid CA certificate. This
+is useful when creating intermediate CA from a root CA.
+
+=item B<-signcert>
+
+this option is the same as B<-sign> except it expects a self signed certificate
+to be present in the file "newreq.pem".
+
+=item B<-verify>
+
+verifies certificates against the CA certificate for "demoCA". If no certificates
+are specified on the command line it tries to verify the file "newcert.pem".
+
+=item B<files>
+
+one or more optional certificate file names for use with the B<-verify> command.
+
+=back
+
+=head1 EXAMPLES
+
+Create a CA hierarchy:
+
+ CA.pl -newca
+
+Complete certificate creation example: create a CA, create a request, sign
+the request and finally create a PKCS#12 file containing it.
+
+ CA.pl -newca
+ CA.pl -newreq
+ CA.pl -signreq
+ CA.pl -pkcs12 "My Test Certificate"
+
+=head1 DSA CERTIFICATES
+
+Although the B<CA.pl> creates RSA CAs and requests it is still possible to
+use it with DSA certificates and requests using the L<req(1)|req(1)> command
+directly. The following example shows the steps that would typically be taken.
+
+Create some DSA parameters:
+
+ openssl dsaparam -out dsap.pem 1024
+
+Create a DSA CA certificate and private key:
+
+ openssl req -x509 -newkey dsa:dsap.pem -keyout cacert.pem -out cacert.pem
+
+Create the CA directories and files:
+
+ CA.pl -newca
+
+enter cacert.pem when prompted for the CA file name.
+
+Create a DSA certificate request and private key (a different set of parameters
+can optionally be created first):
+
+ openssl req -out newreq.pem -newkey dsa:dsap.pem
+
+Sign the request:
+
+ CA.pl -signreq
+
+=head1 NOTES
+
+Most of the filenames mentioned can be modified by editing the B<CA.pl> script.
+
+If the demoCA directory already exists then the B<-newca> command will not
+overwrite it and will do nothing. This can happen if a previous call using
+the B<-newca> option terminated abnormally. To get the correct behaviour
+delete the demoCA directory if it already exists.
+
+Under some environments it may not be possible to run the B<CA.pl> script
+directly (for example Win32) and the default configuration file location may
+be wrong. In this case the command:
+
+ perl -S CA.pl
+
+can be used and the B<OPENSSL_CONF> environment variable changed to point to
+the correct path of the configuration file "openssl.cnf".
+
+The script is intended as a simple front end for the B<openssl> program for use
+by a beginner. Its behaviour isn't always what is wanted. For more control over the
+behaviour of the certificate commands call the B<openssl> command directly.
+
+=head1 ENVIRONMENT VARIABLES
+
+The variable B<OPENSSL_CONF> if defined allows an alternative configuration
+file location to be specified, it should contain the full path to the
+configuration file, not just its directory.
+
+=head1 SEE ALSO
+
+L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<req(1)|req(1)>, L<pkcs12(1)|pkcs12(1)>,
+L<config(5)|config(5)>
+
+=cut
diff --git a/doc/apps/asn1parse.pod b/doc/apps/asn1parse.pod
new file mode 100644
index 000000000000..542d96906626
--- /dev/null
+++ b/doc/apps/asn1parse.pod
@@ -0,0 +1,171 @@
+=pod
+
+=head1 NAME
+
+asn1parse - ASN.1 parsing tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<asn1parse>
+[B<-inform PEM|DER>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-offset number>]
+[B<-length number>]
+[B<-i>]
+[B<-oid filename>]
+[B<-strparse offset>]
+[B<-genstr string>]
+[B<-genconf file>]
+
+=head1 DESCRIPTION
+
+The B<asn1parse> command is a diagnostic utility that can parse ASN.1
+structures. It can also be used to extract data from ASN.1 formatted data.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-inform> B<DER|PEM>
+
+the input format. B<DER> is binary format and B<PEM> (the default) is base64
+encoded.
+
+=item B<-in filename>
+
+the input file, default is standard input
+
+=item B<-out filename>
+
+output file to place the DER encoded data into. If this
+option is not present then no data will be output. This is most useful when
+combined with the B<-strparse> option.
+
+=item B<-noout>
+
+don't output the parsed version of the input file.
+
+=item B<-offset number>
+
+starting offset to begin parsing, default is start of file.
+
+=item B<-length number>
+
+number of bytes to parse, default is until end of file.
+
+=item B<-i>
+
+indents the output according to the "depth" of the structures.
+
+=item B<-oid filename>
+
+a file containing additional OBJECT IDENTIFIERs (OIDs). The format of this
+file is described in the NOTES section below.
+
+=item B<-strparse offset>
+
+parse the contents octets of the ASN.1 object starting at B<offset>. This
+option can be used multiple times to "drill down" into a nested structure.
+
+=item B<-genstr string>, B<-genconf file>
+
+generate encoded data based on B<string>, B<file> or both using
+ASN1_generate_nconf() format. If B<file> only is present then the string
+is obtained from the default section using the name B<asn1>. The encoded
+data is passed through the ASN1 parser and printed out as though it came
+from a file, the contents can thus be examined and written to a file
+using the B<out> option.
+
+=back
+
+=head2 OUTPUT
+
+The output will typically contain lines like this:
+
+ 0:d=0 hl=4 l= 681 cons: SEQUENCE
+
+.....
+
+ 229:d=3 hl=3 l= 141 prim: BIT STRING
+ 373:d=2 hl=3 l= 162 cons: cont [ 3 ]
+ 376:d=3 hl=3 l= 159 cons: SEQUENCE
+ 379:d=4 hl=2 l= 29 cons: SEQUENCE
+ 381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier
+ 386:d=5 hl=2 l= 22 prim: OCTET STRING
+ 410:d=4 hl=2 l= 112 cons: SEQUENCE
+ 412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier
+ 417:d=5 hl=2 l= 105 prim: OCTET STRING
+ 524:d=4 hl=2 l= 12 cons: SEQUENCE
+
+.....
+
+This example is part of a self signed certificate. Each line starts with the
+offset in decimal. B<d=XX> specifies the current depth. The depth is increased
+within the scope of any SET or SEQUENCE. B<hl=XX> gives the header length
+(tag and length octets) of the current type. B<l=XX> gives the length of
+the contents octets.
+
+The B<-i> option can be used to make the output more readable.
+
+Some knowledge of the ASN.1 structure is needed to interpret the output.
+
+In this example the BIT STRING at offset 229 is the certificate public key.
+The contents octets of this will contain the public key information. This can
+be examined using the option B<-strparse 229> to yield:
+
+ 0:d=0 hl=3 l= 137 cons: SEQUENCE
+ 3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897
+ 135:d=1 hl=2 l= 3 prim: INTEGER :010001
+
+=head1 NOTES
+
+If an OID is not part of OpenSSL's internal table it will be represented in
+numerical form (for example 1.2.3.4). The file passed to the B<-oid> option
+allows additional OIDs to be included. Each line consists of three columns,
+the first column is the OID in numerical format and should be followed by white
+space. The second column is the "short name" which is a single word followed
+by white space. The final column is the rest of the line and is the
+"long name". B<asn1parse> displays the long name. Example:
+
+C<1.2.3.4 shortName A long name>
+
+=head1 EXAMPLES
+
+Parse a file:
+
+ openssl asn1parse -in file.pem
+
+Parse a DER file:
+
+ openssl asn1parse -inform DER -in file.der
+
+Generate a simple UTF8String:
+
+ openssl asn1parse -genstr 'UTF8:Hello World'
+
+Generate and write out a UTF8String, don't print parsed output:
+
+ openssl asn1parse -genstr 'UTF8:Hello World' -noout -out utf8.der
+
+Generate using a config file:
+
+ openssl asn1parse -genconf asn1.cnf -noout -out asn1.der
+
+Example config file:
+
+ asn1=SEQUENCE:seq_sect
+
+ [seq_sect]
+
+ field1=BOOL:TRUE
+ field2=EXP:0, UTF8:some random string
+
+
+=head1 BUGS
+
+There should be options to change the format of output lines. The output of some
+ASN.1 types is not well handled (if at all).
+
+=cut
diff --git a/doc/apps/ca.pod b/doc/apps/ca.pod
new file mode 100644
index 000000000000..5618c2dc9d2e
--- /dev/null
+++ b/doc/apps/ca.pod
@@ -0,0 +1,671 @@
+
+=pod
+
+=head1 NAME
+
+ca - sample minimal CA application
+
+=head1 SYNOPSIS
+
+B<openssl> B<ca>
+[B<-verbose>]
+[B<-config filename>]
+[B<-name section>]
+[B<-gencrl>]
+[B<-revoke file>]
+[B<-crl_reason reason>]
+[B<-crl_hold instruction>]
+[B<-crl_compromise time>]
+[B<-crl_CA_compromise time>]
+[B<-crldays days>]
+[B<-crlhours hours>]
+[B<-crlexts section>]
+[B<-startdate date>]
+[B<-enddate date>]
+[B<-days arg>]
+[B<-md arg>]
+[B<-policy arg>]
+[B<-keyfile arg>]
+[B<-key arg>]
+[B<-passin arg>]
+[B<-cert file>]
+[B<-selfsign>]
+[B<-in file>]
+[B<-out file>]
+[B<-notext>]
+[B<-outdir dir>]
+[B<-infiles>]
+[B<-spkac file>]
+[B<-ss_cert file>]
+[B<-preserveDN>]
+[B<-noemailDN>]
+[B<-batch>]
+[B<-msie_hack>]
+[B<-extensions section>]
+[B<-extfile section>]
+[B<-engine id>]
+[B<-subj arg>]
+[B<-utf8>]
+[B<-multivalue-rdn>]
+
+=head1 DESCRIPTION
+
+The B<ca> command is a minimal CA application. It can be used
+to sign certificate requests in a variety of forms and generate
+CRLs it also maintains a text database of issued certificates
+and their status.
+
+The options descriptions will be divided into each purpose.
+
+=head1 CA OPTIONS
+
+=over 4
+
+=item B<-config filename>
+
+specifies the configuration file to use.
+
+=item B<-name section>
+
+specifies the configuration file section to use (overrides
+B<default_ca> in the B<ca> section).
+
+=item B<-in filename>
+
+an input filename containing a single certificate request to be
+signed by the CA.
+
+=item B<-ss_cert filename>
+
+a single self signed certificate to be signed by the CA.
+
+=item B<-spkac filename>
+
+a file containing a single Netscape signed public key and challenge
+and additional field values to be signed by the CA. See the B<SPKAC FORMAT>
+section for information on the required format.
+
+=item B<-infiles>
+
+if present this should be the last option, all subsequent arguments
+are assumed to the the names of files containing certificate requests.
+
+=item B<-out filename>
+
+the output file to output certificates to. The default is standard
+output. The certificate details will also be printed out to this
+file.
+
+=item B<-outdir directory>
+
+the directory to output certificates to. The certificate will be
+written to a filename consisting of the serial number in hex with
+".pem" appended.
+
+=item B<-cert>
+
+the CA certificate file.
+
+=item B<-keyfile filename>
+
+the private key to sign requests with.
+
+=item B<-key password>
+
+the password used to encrypt the private key. Since on some
+systems the command line arguments are visible (e.g. Unix with
+the 'ps' utility) this option should be used with caution.
+
+=item B<-selfsign>
+
+indicates the issued certificates are to be signed with the key
+the certificate requests were signed with (given with B<-keyfile>).
+Cerificate requests signed with a different key are ignored. If
+B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is
+ignored.
+
+A consequence of using B<-selfsign> is that the self-signed
+certificate appears among the entries in the certificate database
+(see the configuration option B<database>), and uses the same
+serial number counter as all other certificates sign with the
+self-signed certificate.
+
+=item B<-passin arg>
+
+the key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-verbose>
+
+this prints extra details about the operations being performed.
+
+=item B<-notext>
+
+don't output the text form of a certificate to the output file.
+
+=item B<-startdate date>
+
+this allows the start date to be explicitly set. The format of the
+date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
+
+=item B<-enddate date>
+
+this allows the expiry date to be explicitly set. The format of the
+date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
+
+=item B<-days arg>
+
+the number of days to certify the certificate for.
+
+=item B<-md alg>
+
+the message digest to use. Possible values include md5, sha1 and mdc2.
+This option also applies to CRLs.
+
+=item B<-policy arg>
+
+this option defines the CA "policy" to use. This is a section in
+the configuration file which decides which fields should be mandatory
+or match the CA certificate. Check out the B<POLICY FORMAT> section
+for more information.
+
+=item B<-msie_hack>
+
+this is a legacy option to make B<ca> work with very old versions of
+the IE certificate enrollment control "certenr3". It used UniversalStrings
+for almost everything. Since the old control has various security bugs
+its use is strongly discouraged. The newer control "Xenroll" does not
+need this option.
+
+=item B<-preserveDN>
+
+Normally the DN order of a certificate is the same as the order of the
+fields in the relevant policy section. When this option is set the order
+is the same as the request. This is largely for compatibility with the
+older IE enrollment control which would only accept certificates if their
+DNs match the order of the request. This is not needed for Xenroll.
+
+=item B<-noemailDN>
+
+The DN of a certificate can contain the EMAIL field if present in the
+request DN, however it is good policy just having the e-mail set into
+the altName extension of the certificate. When this option is set the
+EMAIL field is removed from the certificate' subject and set only in
+the, eventually present, extensions. The B<email_in_dn> keyword can be
+used in the configuration file to enable this behaviour.
+
+=item B<-batch>
+
+this sets the batch mode. In this mode no questions will be asked
+and all certificates will be certified automatically.
+
+=item B<-extensions section>
+
+the section of the configuration file containing certificate extensions
+to be added when a certificate is issued (defaults to B<x509_extensions>
+unless the B<-extfile> option is used). If no extension section is
+present then, a V1 certificate is created. If the extension section
+is present (even if it is empty), then a V3 certificate is created.
+
+=item B<-extfile file>
+
+an additional configuration file to read certificate extensions from
+(using the default section unless the B<-extensions> option is also
+used).
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-subj arg>
+
+supersedes subject name given in the request.
+The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
+characters may be escaped by \ (backslash), no spaces are skipped.
+
+=item B<-utf8>
+
+this option causes field values to be interpreted as UTF8 strings, by
+default they are interpreted as ASCII. This means that the field
+values, whether prompted from a terminal or obtained from a
+configuration file, must be valid UTF8 strings.
+
+=item B<-multivalue-rdn>
+
+this option causes the -subj argument to be interpretedt with full
+support for multivalued RDNs. Example:
+
+I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
+
+If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
+
+=back
+
+=head1 CRL OPTIONS
+
+=over 4
+
+=item B<-gencrl>
+
+this option generates a CRL based on information in the index file.
+
+=item B<-crldays num>
+
+the number of days before the next CRL is due. That is the days from
+now to place in the CRL nextUpdate field.
+
+=item B<-crlhours num>
+
+the number of hours before the next CRL is due.
+
+=item B<-revoke filename>
+
+a filename containing a certificate to revoke.
+
+=item B<-crl_reason reason>
+
+revocation reason, where B<reason> is one of: B<unspecified>, B<keyCompromise>,
+B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>,
+B<certificateHold> or B<removeFromCRL>. The matching of B<reason> is case
+insensitive. Setting any revocation reason will make the CRL v2.
+
+In practive B<removeFromCRL> is not particularly useful because it is only used
+in delta CRLs which are not currently implemented.
+
+=item B<-crl_hold instruction>
+
+This sets the CRL revocation reason code to B<certificateHold> and the hold
+instruction to B<instruction> which must be an OID. Although any OID can be
+used only B<holdInstructionNone> (the use of which is discouraged by RFC2459)
+B<holdInstructionCallIssuer> or B<holdInstructionReject> will normally be used.
+
+=item B<-crl_compromise time>
+
+This sets the revocation reason to B<keyCompromise> and the compromise time to
+B<time>. B<time> should be in GeneralizedTime format that is B<YYYYMMDDHHMMSSZ>.
+
+=item B<-crl_CA_compromise time>
+
+This is the same as B<crl_compromise> except the revocation reason is set to
+B<CACompromise>.
+
+=item B<-crlexts section>
+
+the section of the configuration file containing CRL extensions to
+include. If no CRL extension section is present then a V1 CRL is
+created, if the CRL extension section is present (even if it is
+empty) then a V2 CRL is created. The CRL extensions specified are
+CRL extensions and B<not> CRL entry extensions. It should be noted
+that some software (for example Netscape) can't handle V2 CRLs.
+
+=back
+
+=head1 CONFIGURATION FILE OPTIONS
+
+The section of the configuration file containing options for B<ca>
+is found as follows: If the B<-name> command line option is used,
+then it names the section to be used. Otherwise the section to
+be used must be named in the B<default_ca> option of the B<ca> section
+of the configuration file (or in the default section of the
+configuration file). Besides B<default_ca>, the following options are
+read directly from the B<ca> section:
+ RANDFILE
+ preserve
+ msie_hack
+With the exception of B<RANDFILE>, this is probably a bug and may
+change in future releases.
+
+Many of the configuration file options are identical to command line
+options. Where the option is present in the configuration file
+and the command line the command line value is used. Where an
+option is described as mandatory then it must be present in
+the configuration file or the command line equivalent (if
+any) used.
+
+=over 4
+
+=item B<oid_file>
+
+This specifies a file containing additional B<OBJECT IDENTIFIERS>.
+Each line of the file should consist of the numerical form of the
+object identifier followed by white space then the short name followed
+by white space and finally the long name.
+
+=item B<oid_section>
+
+This specifies a section in the configuration file containing extra
+object identifiers. Each line should consist of the short name of the
+object identifier followed by B<=> and the numerical form. The short
+and long names are the same when this option is used.
+
+=item B<new_certs_dir>
+
+the same as the B<-outdir> command line option. It specifies
+the directory where new certificates will be placed. Mandatory.
+
+=item B<certificate>
+
+the same as B<-cert>. It gives the file containing the CA
+certificate. Mandatory.
+
+=item B<private_key>
+
+same as the B<-keyfile> option. The file containing the
+CA private key. Mandatory.
+
+=item B<RANDFILE>
+
+a file used to read and write random number seed information, or
+an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+
+=item B<default_days>
+
+the same as the B<-days> option. The number of days to certify
+a certificate for.
+
+=item B<default_startdate>
+
+the same as the B<-startdate> option. The start date to certify
+a certificate for. If not set the current time is used.
+
+=item B<default_enddate>
+
+the same as the B<-enddate> option. Either this option or
+B<default_days> (or the command line equivalents) must be
+present.
+
+=item B<default_crl_hours default_crl_days>
+
+the same as the B<-crlhours> and the B<-crldays> options. These
+will only be used if neither command line option is present. At
+least one of these must be present to generate a CRL.
+
+=item B<default_md>
+
+the same as the B<-md> option. The message digest to use. Mandatory.
+
+=item B<database>
+
+the text database file to use. Mandatory. This file must be present
+though initially it will be empty.
+
+=item B<unique_subject>
+
+if the value B<yes> is given, the valid certificate entries in the
+database must have unique subjects. if the value B<no> is given,
+several valid certificate entries may have the exact same subject.
+The default value is B<yes>, to be compatible with older (pre 0.9.8)
+versions of OpenSSL. However, to make CA certificate roll-over easier,
+it's recommended to use the value B<no>, especially if combined with
+the B<-selfsign> command line option.
+
+=item B<serial>
+
+a text file containing the next serial number to use in hex. Mandatory.
+This file must be present and contain a valid serial number.
+
+=item B<crlnumber>
+
+a text file containing the next CRL number to use in hex. The crl number
+will be inserted in the CRLs only if this file exists. If this file is
+present, it must contain a valid CRL number.
+
+=item B<x509_extensions>
+
+the same as B<-extensions>.
+
+=item B<crl_extensions>
+
+the same as B<-crlexts>.
+
+=item B<preserve>
+
+the same as B<-preserveDN>
+
+=item B<email_in_dn>
+
+the same as B<-noemailDN>. If you want the EMAIL field to be removed
+from the DN of the certificate simply set this to 'no'. If not present
+the default is to allow for the EMAIL filed in the certificate's DN.
+
+=item B<msie_hack>
+
+the same as B<-msie_hack>
+
+=item B<policy>
+
+the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
+for more information.
+
+=item B<name_opt>, B<cert_opt>
+
+these options allow the format used to display the certificate details
+when asking the user to confirm signing. All the options supported by
+the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used
+here, except the B<no_signame> and B<no_sigdump> are permanently set
+and cannot be disabled (this is because the certificate signature cannot
+be displayed because the certificate has not been signed at this point).
+
+For convenience the values B<ca_default> are accepted by both to produce
+a reasonable output.
+
+If neither option is present the format used in earlier versions of
+OpenSSL is used. Use of the old format is B<strongly> discouraged because
+it only displays fields mentioned in the B<policy> section, mishandles
+multicharacter string types and does not display extensions.
+
+=item B<copy_extensions>
+
+determines how extensions in certificate requests should be handled.
+If set to B<none> or this option is not present then extensions are
+ignored and not copied to the certificate. If set to B<copy> then any
+extensions present in the request that are not already present are copied
+to the certificate. If set to B<copyall> then all extensions in the
+request are copied to the certificate: if the extension is already present
+in the certificate it is deleted first. See the B<WARNINGS> section before
+using this option.
+
+The main use of this option is to allow a certificate request to supply
+values for certain extensions such as subjectAltName.
+
+=back
+
+=head1 POLICY FORMAT
+
+The policy section consists of a set of variables corresponding to
+certificate DN fields. If the value is "match" then the field value
+must match the same field in the CA certificate. If the value is
+"supplied" then it must be present. If the value is "optional" then
+it may be present. Any fields not mentioned in the policy section
+are silently deleted, unless the B<-preserveDN> option is set but
+this can be regarded more of a quirk than intended behaviour.
+
+=head1 SPKAC FORMAT
+
+The input to the B<-spkac> command line option is a Netscape
+signed public key and challenge. This will usually come from
+the B<KEYGEN> tag in an HTML form to create a new private key.
+It is however possible to create SPKACs using the B<spkac> utility.
+
+The file should contain the variable SPKAC set to the value of
+the SPKAC and also the required DN components as name value pairs.
+If you need to include the same component twice then it can be
+preceded by a number and a '.'.
+
+=head1 EXAMPLES
+
+Note: these examples assume that the B<ca> directory structure is
+already set up and the relevant files already exist. This usually
+involves creating a CA certificate and private key with B<req>, a
+serial number file and an empty index file and placing them in
+the relevant directories.
+
+To use the sample configuration file below the directories demoCA,
+demoCA/private and demoCA/newcerts would be created. The CA
+certificate would be copied to demoCA/cacert.pem and its private
+key to demoCA/private/cakey.pem. A file demoCA/serial would be
+created containing for example "01" and the empty index file
+demoCA/index.txt.
+
+
+Sign a certificate request:
+
+ openssl ca -in req.pem -out newcert.pem
+
+Sign a certificate request, using CA extensions:
+
+ openssl ca -in req.pem -extensions v3_ca -out newcert.pem
+
+Generate a CRL
+
+ openssl ca -gencrl -out crl.pem
+
+Sign several requests:
+
+ openssl ca -infiles req1.pem req2.pem req3.pem
+
+Certify a Netscape SPKAC:
+
+ openssl ca -spkac spkac.txt
+
+A sample SPKAC file (the SPKAC line has been truncated for clarity):
+
+ SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
+ CN=Steve Test
+ emailAddress=steve@openssl.org
+ 0.OU=OpenSSL Group
+ 1.OU=Another Group
+
+A sample configuration file with the relevant sections for B<ca>:
+
+ [ ca ]
+ default_ca = CA_default # The default ca section
+
+ [ CA_default ]
+
+ dir = ./demoCA # top dir
+ database = $dir/index.txt # index file.
+ new_certs_dir = $dir/newcerts # new certs dir
+
+ certificate = $dir/cacert.pem # The CA cert
+ serial = $dir/serial # serial no file
+ private_key = $dir/private/cakey.pem# CA private key
+ RANDFILE = $dir/private/.rand # random number file
+
+ default_days = 365 # how long to certify for
+ default_crl_days= 30 # how long before next CRL
+ default_md = md5 # md to use
+
+ policy = policy_any # default policy
+ email_in_dn = no # Don't add the email into cert DN
+
+ name_opt = ca_default # Subject name display option
+ cert_opt = ca_default # Certificate display option
+ copy_extensions = none # Don't copy extensions from request
+
+ [ policy_any ]
+ countryName = supplied
+ stateOrProvinceName = optional
+ organizationName = optional
+ organizationalUnitName = optional
+ commonName = supplied
+ emailAddress = optional
+
+=head1 FILES
+
+Note: the location of all files can change either by compile time options,
+configuration file entries, environment variables or command line options.
+The values below reflect the default values.
+
+ /usr/local/ssl/lib/openssl.cnf - master configuration file
+ ./demoCA - main CA directory
+ ./demoCA/cacert.pem - CA certificate
+ ./demoCA/private/cakey.pem - CA private key
+ ./demoCA/serial - CA serial number file
+ ./demoCA/serial.old - CA serial number backup file
+ ./demoCA/index.txt - CA text database file
+ ./demoCA/index.txt.old - CA text database backup file
+ ./demoCA/certs - certificate output file
+ ./demoCA/.rnd - CA random seed information
+
+=head1 ENVIRONMENT VARIABLES
+
+B<OPENSSL_CONF> reflects the location of master configuration file it can
+be overridden by the B<-config> command line option.
+
+=head1 RESTRICTIONS
+
+The text database index file is a critical part of the process and
+if corrupted it can be difficult to fix. It is theoretically possible
+to rebuild the index file from all the issued certificates and a current
+CRL: however there is no option to do this.
+
+V2 CRL features like delta CRLs are not currently supported.
+
+Although several requests can be input and handled at once it is only
+possible to include one SPKAC or self signed certificate.
+
+=head1 BUGS
+
+The use of an in memory text database can cause problems when large
+numbers of certificates are present because, as the name implies
+the database has to be kept in memory.
+
+The B<ca> command really needs rewriting or the required functionality
+exposed at either a command or interface level so a more friendly utility
+(perl script or GUI) can handle things properly. The scripts B<CA.sh> and
+B<CA.pl> help a little but not very much.
+
+Any fields in a request that are not present in a policy are silently
+deleted. This does not happen if the B<-preserveDN> option is used. To
+enforce the absence of the EMAIL field within the DN, as suggested by
+RFCs, regardless the contents of the request' subject the B<-noemailDN>
+option can be used. The behaviour should be more friendly and
+configurable.
+
+Cancelling some commands by refusing to certify a certificate can
+create an empty file.
+
+=head1 WARNINGS
+
+The B<ca> command is quirky and at times downright unfriendly.
+
+The B<ca> utility was originally meant as an example of how to do things
+in a CA. It was not supposed to be used as a full blown CA itself:
+nevertheless some people are using it for this purpose.
+
+The B<ca> command is effectively a single user command: no locking is
+done on the various files and attempts to run more than one B<ca> command
+on the same database can have unpredictable results.
+
+The B<copy_extensions> option should be used with caution. If care is
+not taken then it can be a security risk. For example if a certificate
+request contains a basicConstraints extension with CA:TRUE and the
+B<copy_extensions> value is set to B<copyall> and the user does not spot
+this when the certificate is displayed then this will hand the requestor
+a valid CA certificate.
+
+This situation can be avoided by setting B<copy_extensions> to B<copy>
+and including basicConstraints with CA:FALSE in the configuration file.
+Then if the request contains a basicConstraints extension it will be
+ignored.
+
+It is advisable to also include values for other extensions such
+as B<keyUsage> to prevent a request supplying its own values.
+
+Additional restrictions can be placed on the CA certificate itself.
+For example if the CA certificate has:
+
+ basicConstraints = CA:TRUE, pathlen:0
+
+then even if a certificate is issued with CA:TRUE it will not be valid.
+
+=head1 SEE ALSO
+
+L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>,
+L<config(5)|config(5)>
+
+=cut
diff --git a/doc/apps/ciphers.pod b/doc/apps/ciphers.pod
new file mode 100644
index 000000000000..e16eadef21ee
--- /dev/null
+++ b/doc/apps/ciphers.pod
@@ -0,0 +1,418 @@
+=pod
+
+=head1 NAME
+
+ciphers - SSL cipher display and cipher list tool.
+
+=head1 SYNOPSIS
+
+B<openssl> B<ciphers>
+[B<-v>]
+[B<-ssl2>]
+[B<-ssl3>]
+[B<-tls1>]
+[B<cipherlist>]
+
+=head1 DESCRIPTION
+
+The B<cipherlist> command converts OpenSSL cipher lists into ordered
+SSL cipher preference lists. It can be used as a test tool to determine
+the appropriate cipherlist.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-v>
+
+verbose option. List ciphers with a complete description of
+protocol version (SSLv2 or SSLv3; the latter includes TLS), key exchange,
+authentication, encryption and mac algorithms used along with any key size
+restrictions and whether the algorithm is classed as an "export" cipher.
+Note that without the B<-v> option, ciphers may seem to appear twice
+in a cipher list; this is when similar ciphers are available for
+SSL v2 and for SSL v3/TLS v1.
+
+=item B<-ssl3>
+
+only include SSL v3 ciphers.
+
+=item B<-ssl2>
+
+only include SSL v2 ciphers.
+
+=item B<-tls1>
+
+only include TLS v1 ciphers.
+
+=item B<-h>, B<-?>
+
+print a brief usage message.
+
+=item B<cipherlist>
+
+a cipher list to convert to a cipher preference list. If it is not included
+then the default cipher list will be used. The format is described below.
+
+=back
+
+=head1 CIPHER LIST FORMAT
+
+The cipher list consists of one or more I<cipher strings> separated by colons.
+Commas or spaces are also acceptable separators but colons are normally used.
+
+The actual cipher string can take several different forms.
+
+It can consist of a single cipher suite such as B<RC4-SHA>.
+
+It can represent a list of cipher suites containing a certain algorithm, or
+cipher suites of a certain type. For example B<SHA1> represents all ciphers
+suites using the digest algorithm SHA1 and B<SSLv3> represents all SSL v3
+algorithms.
+
+Lists of cipher suites can be combined in a single cipher string using the
+B<+> character. This is used as a logical B<and> operation. For example
+B<SHA1+DES> represents all cipher suites containing the SHA1 B<and> the DES
+algorithms.
+
+Each cipher string can be optionally preceded by the characters B<!>,
+B<-> or B<+>.
+
+If B<!> is used then the ciphers are permanently deleted from the list.
+The ciphers deleted can never reappear in the list even if they are
+explicitly stated.
+
+If B<-> is used then the ciphers are deleted from the list, but some or
+all of the ciphers can be added again by later options.
+
+If B<+> is used then the ciphers are moved to the end of the list. This
+option doesn't add any new ciphers it just moves matching existing ones.
+
+If none of these characters is present then the string is just interpreted
+as a list of ciphers to be appended to the current preference list. If the
+list includes any ciphers already present they will be ignored: that is they
+will not moved to the end of the list.
+
+Additionally the cipher string B<@STRENGTH> can be used at any point to sort
+the current cipher list in order of encryption algorithm key length.
+
+=head1 CIPHER STRINGS
+
+The following is a list of all permitted cipher strings and their meanings.
+
+=over 4
+
+=item B<DEFAULT>
+
+the default cipher list. This is determined at compile time and is normally
+B<ALL:!ADH:RC4+RSA:+SSLv2:@STRENGTH>. This must be the first cipher string
+specified.
+
+=item B<COMPLEMENTOFDEFAULT>
+
+the ciphers included in B<ALL>, but not enabled by default. Currently
+this is B<ADH>. Note that this rule does not cover B<eNULL>, which is
+not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary).
+
+=item B<ALL>
+
+all ciphers suites except the B<eNULL> ciphers which must be explicitly enabled.
+
+=item B<COMPLEMENTOFALL>
+
+the cipher suites not enabled by B<ALL>, currently being B<eNULL>.
+
+=item B<HIGH>
+
+"high" encryption cipher suites. This currently means those with key lengths larger
+than 128 bits, and some cipher suites with 128-bit keys.
+
+=item B<MEDIUM>
+
+"medium" encryption cipher suites, currently some of those using 128 bit encryption.
+
+=item B<LOW>
+
+"low" encryption cipher suites, currently those using 64 or 56 bit encryption algorithms
+but excluding export cipher suites.
+
+=item B<EXP>, B<EXPORT>
+
+export encryption algorithms. Including 40 and 56 bits algorithms.
+
+=item B<EXPORT40>
+
+40 bit export encryption algorithms
+
+=item B<EXPORT56>
+
+56 bit export encryption algorithms. In OpenSSL 0.9.8c and later the set of
+56 bit export ciphers is empty unless OpenSSL has been explicitly configured
+with support for experimental ciphers.
+
+=item B<eNULL>, B<NULL>
+
+the "NULL" ciphers that is those offering no encryption. Because these offer no
+encryption at all and are a security risk they are disabled unless explicitly
+included.
+
+=item B<aNULL>
+
+the cipher suites offering no authentication. This is currently the anonymous
+DH algorithms. These cipher suites are vulnerable to a "man in the middle"
+attack and so their use is normally discouraged.
+
+=item B<kRSA>, B<RSA>
+
+cipher suites using RSA key exchange.
+
+=item B<kEDH>
+
+cipher suites using ephemeral DH key agreement.
+
+=item B<kDHr>, B<kDHd>
+
+cipher suites using DH key agreement and DH certificates signed by CAs with RSA
+and DSS keys respectively. Not implemented.
+
+=item B<aRSA>
+
+cipher suites using RSA authentication, i.e. the certificates carry RSA keys.
+
+=item B<aDSS>, B<DSS>
+
+cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
+
+=item B<aDH>
+
+cipher suites effectively using DH authentication, i.e. the certificates carry
+DH keys. Not implemented.
+
+=item B<kFZA>, B<aFZA>, B<eFZA>, B<FZA>
+
+ciphers suites using FORTEZZA key exchange, authentication, encryption or all
+FORTEZZA algorithms. Not implemented.
+
+=item B<TLSv1>, B<SSLv3>, B<SSLv2>
+
+TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively.
+
+=item B<DH>
+
+cipher suites using DH, including anonymous DH.
+
+=item B<ADH>
+
+anonymous DH cipher suites.
+
+=item B<AES>
+
+cipher suites using AES.
+
+=item B<3DES>
+
+cipher suites using triple DES.
+
+=item B<DES>
+
+cipher suites using DES (not triple DES).
+
+=item B<RC4>
+
+cipher suites using RC4.
+
+=item B<RC2>
+
+cipher suites using RC2.
+
+=item B<IDEA>
+
+cipher suites using IDEA.
+
+=item B<MD5>
+
+cipher suites using MD5.
+
+=item B<SHA1>, B<SHA>
+
+cipher suites using SHA1.
+
+=item B<Camellia>
+
+cipher suites using Camellia.
+
+=back
+
+=head1 CIPHER SUITE NAMES
+
+The following lists give the SSL or TLS cipher suites names from the
+relevant specification and their OpenSSL equivalents. It should be noted,
+that several cipher suite names do not include the authentication used,
+e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
+
+=head2 SSL v3.0 cipher suites.
+
+ SSL_RSA_WITH_NULL_MD5 NULL-MD5
+ SSL_RSA_WITH_NULL_SHA NULL-SHA
+ SSL_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5
+ SSL_RSA_WITH_RC4_128_MD5 RC4-MD5
+ SSL_RSA_WITH_RC4_128_SHA RC4-SHA
+ SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5
+ SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
+ SSL_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA
+ SSL_RSA_WITH_DES_CBC_SHA DES-CBC-SHA
+ SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
+
+ SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA Not implemented.
+ SSL_DH_DSS_WITH_DES_CBC_SHA Not implemented.
+ SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented.
+ SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA Not implemented.
+ SSL_DH_RSA_WITH_DES_CBC_SHA Not implemented.
+ SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented.
+ SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA
+ SSL_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA
+ SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA
+ SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA
+ SSL_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA
+ SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA
+
+ SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5
+ SSL_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5
+ SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA
+ SSL_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA
+ SSL_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA
+
+ SSL_FORTEZZA_KEA_WITH_NULL_SHA Not implemented.
+ SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA Not implemented.
+ SSL_FORTEZZA_KEA_WITH_RC4_128_SHA Not implemented.
+
+=head2 TLS v1.0 cipher suites.
+
+ TLS_RSA_WITH_NULL_MD5 NULL-MD5
+ TLS_RSA_WITH_NULL_SHA NULL-SHA
+ TLS_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5
+ TLS_RSA_WITH_RC4_128_MD5 RC4-MD5
+ TLS_RSA_WITH_RC4_128_SHA RC4-SHA
+ TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5
+ TLS_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
+ TLS_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA
+ TLS_RSA_WITH_DES_CBC_SHA DES-CBC-SHA
+ TLS_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
+
+ TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA Not implemented.
+ TLS_DH_DSS_WITH_DES_CBC_SHA Not implemented.
+ TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented.
+ TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA Not implemented.
+ TLS_DH_RSA_WITH_DES_CBC_SHA Not implemented.
+ TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented.
+ TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA
+ TLS_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA
+ TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA
+ TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA
+ TLS_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA
+ TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA
+
+ TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5
+ TLS_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5
+ TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA
+ TLS_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA
+ TLS_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA
+
+=head2 AES ciphersuites from RFC3268, extending TLS v1.0
+
+ TLS_RSA_WITH_AES_128_CBC_SHA AES128-SHA
+ TLS_RSA_WITH_AES_256_CBC_SHA AES256-SHA
+
+ TLS_DH_DSS_WITH_AES_128_CBC_SHA DH-DSS-AES128-SHA
+ TLS_DH_DSS_WITH_AES_256_CBC_SHA DH-DSS-AES256-SHA
+ TLS_DH_RSA_WITH_AES_128_CBC_SHA DH-RSA-AES128-SHA
+ TLS_DH_RSA_WITH_AES_256_CBC_SHA DH-RSA-AES256-SHA
+
+ TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE-DSS-AES128-SHA
+ TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-DSS-AES256-SHA
+ TLS_DHE_RSA_WITH_AES_128_CBC_SHA DHE-RSA-AES128-SHA
+ TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA
+
+ TLS_DH_anon_WITH_AES_128_CBC_SHA ADH-AES128-SHA
+ TLS_DH_anon_WITH_AES_256_CBC_SHA ADH-AES256-SHA
+
+=head2 Camellia ciphersuites from RFC4132, extending TLS v1.0
+
+ TLS_RSA_WITH_CAMELLIA_128_CBC_SHA CAMELLIA128-SHA
+ TLS_RSA_WITH_CAMELLIA_256_CBC_SHA CAMELLIA256-SHA
+
+ TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA Not implemented.
+ TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA Not implemented.
+ TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA Not implemented.
+ TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA Not implemented.
+
+ TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA DHE-DSS-CAMELLIA128-SHA
+ TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA DHE-DSS-CAMELLIA256-SHA
+ TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA DHE-RSA-CAMELLIA128-SHA
+ TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA DHE-RSA-CAMELLIA256-SHA
+
+ TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA ADH-CAMELLIA128-SHA
+ TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA ADH-CAMELLIA256-SHA
+
+=head2 Additional Export 1024 and other cipher suites
+
+Note: these ciphers can also be used in SSL v3.
+
+ TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DES-CBC-SHA
+ TLS_RSA_EXPORT1024_WITH_RC4_56_SHA EXP1024-RC4-SHA
+ TLS_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DHE-DSS-DES-CBC-SHA
+ TLS_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA EXP1024-DHE-DSS-RC4-SHA
+ TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA
+
+=head2 SSL v2.0 cipher suites.
+
+ SSL_CK_RC4_128_WITH_MD5 RC4-MD5
+ SSL_CK_RC4_128_EXPORT40_WITH_MD5 EXP-RC4-MD5
+ SSL_CK_RC2_128_CBC_WITH_MD5 RC2-MD5
+ SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 EXP-RC2-MD5
+ SSL_CK_IDEA_128_CBC_WITH_MD5 IDEA-CBC-MD5
+ SSL_CK_DES_64_CBC_WITH_MD5 DES-CBC-MD5
+ SSL_CK_DES_192_EDE3_CBC_WITH_MD5 DES-CBC3-MD5
+
+=head1 NOTES
+
+The non-ephemeral DH modes are currently unimplemented in OpenSSL
+because there is no support for DH certificates.
+
+Some compiled versions of OpenSSL may not include all the ciphers
+listed here because some ciphers were excluded at compile time.
+
+=head1 EXAMPLES
+
+Verbose listing of all OpenSSL ciphers including NULL ciphers:
+
+ openssl ciphers -v 'ALL:eNULL'
+
+Include all ciphers except NULL and anonymous DH then sort by
+strength:
+
+ openssl ciphers -v 'ALL:!ADH:@STRENGTH'
+
+Include only 3DES ciphers and then place RSA ciphers last:
+
+ openssl ciphers -v '3DES:+RSA'
+
+Include all RC4 ciphers but leave out those without authentication:
+
+ openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT'
+
+Include all chiphers with RSA authentication but leave out ciphers without
+encryption.
+
+ openssl ciphers -v 'RSA:!COMPLEMENTOFALL'
+
+=head1 SEE ALSO
+
+L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ssl(3)|ssl(3)>
+
+=head1 HISTORY
+
+The B<COMPLENTOFALL> and B<COMPLEMENTOFDEFAULT> selection options were
+added in version 0.9.7.
+
+=cut
diff --git a/doc/apps/config.pod b/doc/apps/config.pod
new file mode 100644
index 000000000000..ace34b62bd2e
--- /dev/null
+++ b/doc/apps/config.pod
@@ -0,0 +1,279 @@
+
+=pod
+
+=for comment openssl_manual_section:5
+
+=head1 NAME
+
+config - OpenSSL CONF library configuration files
+
+=head1 DESCRIPTION
+
+The OpenSSL CONF library can be used to read configuration files.
+It is used for the OpenSSL master configuration file B<openssl.cnf>
+and in a few other places like B<SPKAC> files and certificate extension
+files for the B<x509> utility. OpenSSL applications can also use the
+CONF library for their own purposes.
+
+A configuration file is divided into a number of sections. Each section
+starts with a line B<[ section_name ]> and ends when a new section is
+started or end of file is reached. A section name can consist of
+alphanumeric characters and underscores.
+
+The first section of a configuration file is special and is referred
+to as the B<default> section this is usually unnamed and is from the
+start of file until the first named section. When a name is being looked up
+it is first looked up in a named section (if any) and then the
+default section.
+
+The environment is mapped onto a section called B<ENV>.
+
+Comments can be included by preceding them with the B<#> character
+
+Each section in a configuration file consists of a number of name and
+value pairs of the form B<name=value>
+
+The B<name> string can contain any alphanumeric characters as well as
+a few punctuation symbols such as B<.> B<,> B<;> and B<_>.
+
+The B<value> string consists of the string following the B<=> character
+until end of line with any leading and trailing white space removed.
+
+The value string undergoes variable expansion. This can be done by
+including the form B<$var> or B<${var}>: this will substitute the value
+of the named variable in the current section. It is also possible to
+substitute a value from another section using the syntax B<$section::name>
+or B<${section::name}>. By using the form B<$ENV::name> environment
+variables can be substituted. It is also possible to assign values to
+environment variables by using the name B<ENV::name>, this will work
+if the program looks up environment variables using the B<CONF> library
+instead of calling B<getenv()> directly.
+
+It is possible to escape certain characters by using any kind of quote
+or the B<\> character. By making the last character of a line a B<\>
+a B<value> string can be spread across multiple lines. In addition
+the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
+
+=head1 OPENSSL LIBRARY CONFIGURATION
+
+In OpenSSL 0.9.7 and later applications can automatically configure certain
+aspects of OpenSSL using the master OpenSSL configuration file, or optionally
+an alternative configuration file. The B<openssl> utility includes this
+functionality: any sub command uses the master OpenSSL configuration file
+unless an option is used in the sub command to use an alternative configuration
+file.
+
+To enable library configuration the default section needs to contain an
+appropriate line which points to the main configuration section. The default
+name is B<openssl_conf> which is used by the B<openssl> utility. Other
+applications may use an alternative name such as B<myapplicaton_conf>.
+
+The configuration section should consist of a set of name value pairs which
+contain specific module configuration information. The B<name> represents
+the name of the I<configuration module> the meaning of the B<value> is
+module specific: it may, for example, represent a further configuration
+section containing configuration module specific information. E.g.
+
+ openssl_conf = openssl_init
+
+ [openssl_init]
+
+ oid_section = new_oids
+ engines = engine_section
+
+ [new_oids]
+
+ ... new oids here ...
+
+ [engine_section]
+
+ ... engine stuff here ...
+
+Currently there are two configuration modules. One for ASN1 objects another
+for ENGINE configuration.
+
+=head2 ASN1 OBJECT CONFIGURATION MODULE
+
+This module has the name B<oid_section>. The value of this variable points
+to a section containing name value pairs of OIDs: the name is the OID short
+and long name, the value is the numerical form of the OID. Although some of
+the B<openssl> utility sub commands already have their own ASN1 OBJECT section
+functionality not all do. By using the ASN1 OBJECT configuration module
+B<all> the B<openssl> utility sub commands can see the new objects as well
+as any compliant applications. For example:
+
+ [new_oids]
+
+ some_new_oid = 1.2.3.4
+ some_other_oid = 1.2.3.5
+
+In OpenSSL 0.9.8 it is also possible to set the value to the long name followed
+by a comma and the numerical OID form. For example:
+
+ shortName = some object long name, 1.2.3.4
+
+=head2 ENGINE CONFIGURATION MODULE
+
+This ENGINE configuration module has the name B<engines>. The value of this
+variable points to a section containing further ENGINE configuration
+information.
+
+The section pointed to by B<engines> is a table of engine names (though see
+B<engine_id> below) and further sections containing configuration informations
+specific to each ENGINE.
+
+Each ENGINE specific section is used to set default algorithms, load
+dynamic, perform initialization and send ctrls. The actual operation performed
+depends on the I<command> name which is the name of the name value pair. The
+currently supported commands are listed below.
+
+For example:
+
+ [engine_section]
+
+ # Configure ENGINE named "foo"
+ foo = foo_section
+ # Configure ENGINE named "bar"
+ bar = bar_section
+
+ [foo_section]
+ ... foo ENGINE specific commands ...
+
+ [bar_section]
+ ... "bar" ENGINE specific commands ...
+
+The command B<engine_id> is used to give the ENGINE name. If used this
+command must be first. For example:
+
+ [engine_section]
+ # This would normally handle an ENGINE named "foo"
+ foo = foo_section
+
+ [foo_section]
+ # Override default name and use "myfoo" instead.
+ engine_id = myfoo
+
+The command B<dynamic_path> loads and adds an ENGINE from the given path. It
+is equivalent to sending the ctrls B<SO_PATH> with the path argument followed
+by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is
+not the required behaviour then alternative ctrls can be sent directly
+to the dynamic ENGINE using ctrl commands.
+
+The command B<init> determines whether to initialize the ENGINE. If the value
+is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to
+initialized the ENGINE immediately. If the B<init> command is not present
+then an attempt will be made to initialize the ENGINE after all commands in
+its section have been processed.
+
+The command B<default_algorithms> sets the default algorithms an ENGINE will
+supply using the functions B<ENGINE_set_default_string()>
+
+If the name matches none of the above command names it is assumed to be a
+ctrl command which is sent to the ENGINE. The value of the command is the
+argument to the ctrl command. If the value is the string B<EMPTY> then no
+value is sent to the command.
+
+For example:
+
+
+ [engine_section]
+
+ # Configure ENGINE named "foo"
+ foo = foo_section
+
+ [foo_section]
+ # Load engine from DSO
+ dynamic_path = /some/path/fooengine.so
+ # A foo specific ctrl.
+ some_ctrl = some_value
+ # Another ctrl that doesn't take a value.
+ other_ctrl = EMPTY
+ # Supply all default algorithms
+ default_algorithms = ALL
+
+=head1 NOTES
+
+If a configuration file attempts to expand a variable that doesn't exist
+then an error is flagged and the file will not load. This can happen
+if an attempt is made to expand an environment variable that doesn't
+exist. For example in a previous version of OpenSSL the default OpenSSL
+master configuration file used the value of B<HOME> which may not be
+defined on non Unix systems and would cause an error.
+
+This can be worked around by including a B<default> section to provide
+a default value: then if the environment lookup fails the default value
+will be used instead. For this to work properly the default value must
+be defined earlier in the configuration file than the expansion. See
+the B<EXAMPLES> section for an example of how to do this.
+
+If the same variable exists in the same section then all but the last
+value will be silently ignored. In certain circumstances such as with
+DNs the same field may occur multiple times. This is usually worked
+around by ignoring any characters before an initial B<.> e.g.
+
+ 1.OU="My first OU"
+ 2.OU="My Second OU"
+
+=head1 EXAMPLES
+
+Here is a sample configuration file using some of the features
+mentioned above.
+
+ # This is the default section.
+
+ HOME=/temp
+ RANDFILE= ${ENV::HOME}/.rnd
+ configdir=$ENV::HOME/config
+
+ [ section_one ]
+
+ # We are now in section one.
+
+ # Quotes permit leading and trailing whitespace
+ any = " any variable name "
+
+ other = A string that can \
+ cover several lines \
+ by including \\ characters
+
+ message = Hello World\n
+
+ [ section_two ]
+
+ greeting = $section_one::message
+
+This next example shows how to expand environment variables safely.
+
+Suppose you want a variable called B<tmpfile> to refer to a
+temporary filename. The directory it is placed in can determined by
+the the B<TEMP> or B<TMP> environment variables but they may not be
+set to any value at all. If you just include the environment variable
+names and the variable doesn't exist then this will cause an error when
+an attempt is made to load the configuration file. By making use of the
+default section both values can be looked up with B<TEMP> taking
+priority and B</tmp> used if neither is defined:
+
+ TMP=/tmp
+ # The above value is used if TMP isn't in the environment
+ TEMP=$ENV::TMP
+ # The above value is used if TEMP isn't in the environment
+ tmpfile=${ENV::TEMP}/tmp.filename
+
+=head1 BUGS
+
+Currently there is no way to include characters using the octal B<\nnn>
+form. Strings are all null terminated so nulls cannot form part of
+the value.
+
+The escaping isn't quite right: if you want to use sequences like B<\n>
+you can't use any quote escaping on the same line.
+
+Files are loaded in a single pass. This means that an variable expansion
+will only work if the variables referenced are defined earlier in the
+file.
+
+=head1 SEE ALSO
+
+L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)>
+
+=cut
diff --git a/doc/apps/crl.pod b/doc/apps/crl.pod
new file mode 100644
index 000000000000..a40c873b9568
--- /dev/null
+++ b/doc/apps/crl.pod
@@ -0,0 +1,117 @@
+=pod
+
+=head1 NAME
+
+crl - CRL utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<crl>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-text>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-hash>]
+[B<-issuer>]
+[B<-lastupdate>]
+[B<-nextupdate>]
+[B<-CAfile file>]
+[B<-CApath dir>]
+
+=head1 DESCRIPTION
+
+The B<crl> command processes CRL files in DER or PEM format.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. B<DER> format is DER encoded CRL
+structure. B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read from or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-text>
+
+print out the CRL in text form.
+
+=item B<-noout>
+
+don't output the encoded version of the CRL.
+
+=item B<-hash>
+
+output a hash of the issuer name. This can be use to lookup CRLs in
+a directory by issuer name.
+
+=item B<-issuer>
+
+output the issuer name.
+
+=item B<-lastupdate>
+
+output the lastUpdate field.
+
+=item B<-nextupdate>
+
+output the nextUpdate field.
+
+=item B<-CAfile file>
+
+verify the signature on a CRL by looking up the issuing certificate in
+B<file>
+
+=item B<-CApath dir>
+
+verify the signature on a CRL by looking up the issuing certificate in
+B<dir>. This directory must be a standard certificate directory: that
+is a hash of each subject name (using B<x509 -hash>) should be linked
+to each certificate.
+
+=back
+
+=head1 NOTES
+
+The PEM CRL format uses the header and footer lines:
+
+ -----BEGIN X509 CRL-----
+ -----END X509 CRL-----
+
+=head1 EXAMPLES
+
+Convert a CRL file from PEM to DER:
+
+ openssl crl -in crl.pem -outform DER -out crl.der
+
+Output the text form of a DER encoded certificate:
+
+ openssl crl -in crl.der -text -noout
+
+=head1 BUGS
+
+Ideally it should be possible to create a CRL using appropriate options
+and files too.
+
+=head1 SEE ALSO
+
+L<crl2pkcs7(1)|crl2pkcs7(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>
+
+=cut
diff --git a/doc/apps/crl2pkcs7.pod b/doc/apps/crl2pkcs7.pod
new file mode 100644
index 000000000000..3797bc0df4ef
--- /dev/null
+++ b/doc/apps/crl2pkcs7.pod
@@ -0,0 +1,91 @@
+=pod
+
+=head1 NAME
+
+crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates.
+
+=head1 SYNOPSIS
+
+B<openssl> B<crl2pkcs7>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-certfile filename>]
+[B<-nocrl>]
+
+=head1 DESCRIPTION
+
+The B<crl2pkcs7> command takes an optional CRL and one or more
+certificates and converts them into a PKCS#7 degenerate "certificates
+only" structure.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the CRL input format. B<DER> format is DER encoded CRL
+structure.B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the PKCS#7 structure output format. B<DER> format is DER
+encoded PKCS#7 structure.B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-in filename>
+
+This specifies the input filename to read a CRL from or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write the PKCS#7 structure to or standard
+output by default.
+
+=item B<-certfile filename>
+
+specifies a filename containing one or more certificates in B<PEM> format.
+All certificates in the file will be added to the PKCS#7 structure. This
+option can be used more than once to read certificates form multiple
+files.
+
+=item B<-nocrl>
+
+normally a CRL is included in the output file. With this option no CRL is
+included in the output file and a CRL is not read from the input file.
+
+=back
+
+=head1 EXAMPLES
+
+Create a PKCS#7 structure from a certificate and CRL:
+
+ openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem
+
+Creates a PKCS#7 structure in DER format with no CRL from several
+different certificates:
+
+ openssl crl2pkcs7 -nocrl -certfile newcert.pem
+ -certfile demoCA/cacert.pem -outform DER -out p7.der
+
+=head1 NOTES
+
+The output file is a PKCS#7 signed data structure containing no signers and
+just certificates and an optional CRL.
+
+This utility can be used to send certificates and CAs to Netscape as part of
+the certificate enrollment process. This involves sending the DER encoded output
+as MIME type application/x-x509-user-cert.
+
+The B<PEM> encoded form with the header and footer lines removed can be used to
+install user certificates and CAs in MSIE using the Xenroll control.
+
+=head1 SEE ALSO
+
+L<pkcs7(1)|pkcs7(1)>
+
+=cut
diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod
new file mode 100644
index 000000000000..b0d198724c6b
--- /dev/null
+++ b/doc/apps/dgst.pod
@@ -0,0 +1,110 @@
+=pod
+
+=head1 NAME
+
+dgst, md5, md4, md2, sha1, sha, mdc2, ripemd160 - message digests
+
+=head1 SYNOPSIS
+
+B<openssl> B<dgst>
+[B<-md5|-md4|-md2|-sha1|-sha|-mdc2|-ripemd160|-dss1>]
+[B<-c>]
+[B<-d>]
+[B<-hex>]
+[B<-binary>]
+[B<-out filename>]
+[B<-sign filename>]
+[B<-passin arg>]
+[B<-verify filename>]
+[B<-prverify filename>]
+[B<-signature filename>]
+[B<file...>]
+
+[B<md5|md4|md2|sha1|sha|mdc2|ripemd160>]
+[B<-c>]
+[B<-d>]
+[B<file...>]
+
+=head1 DESCRIPTION
+
+The digest functions output the message digest of a supplied file or files
+in hexadecimal form. They can also be used for digital signing and verification.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-c>
+
+print out the digest in two digit groups separated by colons, only relevant if
+B<hex> format output is used.
+
+=item B<-d>
+
+print out BIO debugging information.
+
+=item B<-hex>
+
+digest is to be output as a hex dump. This is the default case for a "normal"
+digest as opposed to a digital signature.
+
+=item B<-binary>
+
+output the digest or signature in binary form.
+
+=item B<-out filename>
+
+filename to output to, or standard output by default.
+
+=item B<-sign filename>
+
+digitally sign the digest using the private key in "filename".
+
+=item B<-passin arg>
+
+the private key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-verify filename>
+
+verify the signature using the the public key in "filename".
+The output is either "Verification OK" or "Verification Failure".
+
+=item B<-prverify filename>
+
+verify the signature using the the private key in "filename".
+
+=item B<-signature filename>
+
+the actual signature to verify.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<file...>
+
+file or files to digest. If no files are specified then standard input is
+used.
+
+=back
+
+=head1 NOTES
+
+The digest of choice for all new applications is SHA1. Other digests are
+however still widely used.
+
+If you wish to sign or verify data using the DSA algorithm then the dss1
+digest must be used.
+
+A source of random numbers is required for certain signing algorithms, in
+particular DSA.
+
+The signing and verify options should only be used if a single file is
+being signed or verified.
+
+=cut
diff --git a/doc/apps/dhparam.pod b/doc/apps/dhparam.pod
new file mode 100644
index 000000000000..c31db95a4732
--- /dev/null
+++ b/doc/apps/dhparam.pod
@@ -0,0 +1,141 @@
+=pod
+
+=head1 NAME
+
+dhparam - DH parameter manipulation and generation
+
+=head1 SYNOPSIS
+
+B<openssl dhparam>
+[B<-inform DER|PEM>]
+[B<-outform DER|PEM>]
+[B<-in> I<filename>]
+[B<-out> I<filename>]
+[B<-dsaparam>]
+[B<-noout>]
+[B<-text>]
+[B<-C>]
+[B<-2>]
+[B<-5>]
+[B<-rand> I<file(s)>]
+[B<-engine id>]
+[I<numbits>]
+
+=head1 DESCRIPTION
+
+This command is used to manipulate DH parameter files.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with the PKCS#3 DHparameter structure. The PEM form is the
+default format: it consists of the B<DER> format base64 encoded with
+additional header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in> I<filename>
+
+This specifies the input filename to read parameters from or standard input if
+this option is not specified.
+
+=item B<-out> I<filename>
+
+This specifies the output filename parameters to. Standard output is used
+if this option is not present. The output filename should B<not> be the same
+as the input filename.
+
+=item B<-dsaparam>
+
+If this option is used, DSA rather than DH parameters are read or created;
+they are converted to DH format. Otherwise, "strong" primes (such
+that (p-1)/2 is also prime) will be used for DH parameter generation.
+
+DH parameter generation with the B<-dsaparam> option is much faster,
+and the recommended exponent length is shorter, which makes DH key
+exchange more efficient. Beware that with such DSA-style DH
+parameters, a fresh DH key should be created for each use to
+avoid small-subgroup attacks that may be possible otherwise.
+
+=item B<-2>, B<-5>
+
+The generator to use, either 2 or 5. 2 is the default. If present then the
+input file is ignored and parameters are generated instead.
+
+=item B<-rand> I<file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item I<numbits>
+
+this option specifies that a parameter set should be generated of size
+I<numbits>. It must be the last option. If not present then a value of 512
+is used. If this option is present then the input file is ignored and
+parameters are generated instead.
+
+=item B<-noout>
+
+this option inhibits the output of the encoded version of the parameters.
+
+=item B<-text>
+
+this option prints out the DH parameters in human readable form.
+
+=item B<-C>
+
+this option converts the parameters into C code. The parameters can then
+be loaded by calling the B<get_dh>I<numbits>B<()> function.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 WARNINGS
+
+The program B<dhparam> combines the functionality of the programs B<dh> and
+B<gendh> in previous versions of OpenSSL and SSLeay. The B<dh> and B<gendh>
+programs are retained for now but may have different purposes in future
+versions of OpenSSL.
+
+=head1 NOTES
+
+PEM format DH parameters use the header and footer lines:
+
+ -----BEGIN DH PARAMETERS-----
+ -----END DH PARAMETERS-----
+
+OpenSSL currently only supports the older PKCS#3 DH, not the newer X9.42
+DH.
+
+This program manipulates DH parameters not keys.
+
+=head1 BUGS
+
+There should be a way to generate and manipulate DH keys.
+
+=head1 SEE ALSO
+
+L<dsaparam(1)|dsaparam(1)>
+
+=head1 HISTORY
+
+The B<dhparam> command was added in OpenSSL 0.9.5.
+The B<-dsaparam> option was added in OpenSSL 0.9.6.
+
+=cut
diff --git a/doc/apps/dsa.pod b/doc/apps/dsa.pod
new file mode 100644
index 000000000000..ed06b8806d8c
--- /dev/null
+++ b/doc/apps/dsa.pod
@@ -0,0 +1,158 @@
+=pod
+
+=head1 NAME
+
+dsa - DSA key processing
+
+=head1 SYNOPSIS
+
+B<openssl> B<dsa>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin arg>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-text>]
+[B<-noout>]
+[B<-modulus>]
+[B<-pubin>]
+[B<-pubout>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<dsa> command processes DSA keys. They can be converted between various
+forms and their components printed out. B<Note> This command uses the
+traditional SSLeay compatible format for private key encryption: newer
+applications should use the more secure PKCS#8 format using the B<pkcs8>
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option with a private key uses
+an ASN1 DER encoded form of an ASN.1 SEQUENCE consisting of the values of
+version (currently zero), p, q, g, the public and private key components
+respectively as ASN.1 INTEGERs. When used with a public key it uses a
+SubjectPublicKeyInfo structure: it is an error if the key is not DSA.
+
+The B<PEM> form is the default format: it consists of the B<DER> format base64
+encoded with additional header and footer lines. In the case of a private key
+PKCS#8 format is also accepted.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin arg>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output by
+is not specified. If any encryption options are set then a pass phrase will be
+prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout arg>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-des|-des3|-idea>
+
+These options encrypt the private key with the DES, triple DES, or the
+IDEA ciphers respectively before outputting it. A pass phrase is prompted for.
+If none of these options is specified the key is written in plain text. This
+means that using the B<dsa> utility to read in an encrypted key with no
+encryption option can be used to remove the pass phrase from a key, or by
+setting the encryption options it can be use to add or change the pass phrase.
+These options can only be used with PEM format output files.
+
+=item B<-text>
+
+prints out the public, private key components and parameters.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the key.
+
+=item B<-modulus>
+
+this option prints out the value of the public key component of the key.
+
+=item B<-pubin>
+
+by default a private key is read from the input file: with this option a
+public key is read instead.
+
+=item B<-pubout>
+
+by default a private key is output. With this option a public
+key will be output instead. This option is automatically set if the input is
+a public key.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 NOTES
+
+The PEM private key format uses the header and footer lines:
+
+ -----BEGIN DSA PRIVATE KEY-----
+ -----END DSA PRIVATE KEY-----
+
+The PEM public key format uses the header and footer lines:
+
+ -----BEGIN PUBLIC KEY-----
+ -----END PUBLIC KEY-----
+
+=head1 EXAMPLES
+
+To remove the pass phrase on a DSA private key:
+
+ openssl dsa -in key.pem -out keyout.pem
+
+To encrypt a private key using triple DES:
+
+ openssl dsa -in key.pem -des3 -out keyout.pem
+
+To convert a private key from PEM to DER format:
+
+ openssl dsa -in key.pem -outform DER -out keyout.der
+
+To print out the components of a private key to standard output:
+
+ openssl dsa -in key.pem -text -noout
+
+To just output the public part of a private key:
+
+ openssl dsa -in key.pem -pubout -out pubkey.pem
+
+=head1 SEE ALSO
+
+L<dsaparam(1)|dsaparam(1)>, L<gendsa(1)|gendsa(1)>, L<rsa(1)|rsa(1)>,
+L<genrsa(1)|genrsa(1)>
+
+=cut
diff --git a/doc/apps/dsaparam.pod b/doc/apps/dsaparam.pod
new file mode 100644
index 000000000000..b9b1b93b42ec
--- /dev/null
+++ b/doc/apps/dsaparam.pod
@@ -0,0 +1,110 @@
+=pod
+
+=head1 NAME
+
+dsaparam - DSA parameter manipulation and generation
+
+=head1 SYNOPSIS
+
+B<openssl dsaparam>
+[B<-inform DER|PEM>]
+[B<-outform DER|PEM>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-text>]
+[B<-C>]
+[B<-rand file(s)>]
+[B<-genkey>]
+[B<-engine id>]
+[B<numbits>]
+
+=head1 DESCRIPTION
+
+This command is used to manipulate or generate DSA parameter files.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with RFC2459 (PKIX) DSS-Parms that is a SEQUENCE consisting
+of p, q and g respectively. The PEM form is the default format: it consists
+of the B<DER> format base64 encoded with additional header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read parameters from or standard input if
+this option is not specified. If the B<numbits> parameter is included then
+this option will be ignored.
+
+=item B<-out filename>
+
+This specifies the output filename parameters to. Standard output is used
+if this option is not present. The output filename should B<not> be the same
+as the input filename.
+
+=item B<-noout>
+
+this option inhibits the output of the encoded version of the parameters.
+
+=item B<-text>
+
+this option prints out the DSA parameters in human readable form.
+
+=item B<-C>
+
+this option converts the parameters into C code. The parameters can then
+be loaded by calling the B<get_dsaXXX()> function.
+
+=item B<-genkey>
+
+this option will generate a DSA either using the specified or generated
+parameters.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<numbits>
+
+this option specifies that a parameter set should be generated of size
+B<numbits>. It must be the last option. If this option is included then
+the input file (if any) is ignored.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 NOTES
+
+PEM format DSA parameters use the header and footer lines:
+
+ -----BEGIN DSA PARAMETERS-----
+ -----END DSA PARAMETERS-----
+
+DSA parameter generation is a slow process and as a result the same set of
+DSA parameters is often used to generate several distinct keys.
+
+=head1 SEE ALSO
+
+L<gendsa(1)|gendsa(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>,
+L<rsa(1)|rsa(1)>
+
+=cut
diff --git a/doc/apps/ec.pod b/doc/apps/ec.pod
new file mode 100644
index 000000000000..1d4a36dbf403
--- /dev/null
+++ b/doc/apps/ec.pod
@@ -0,0 +1,190 @@
+=pod
+
+=head1 NAME
+
+ec - EC key processing
+
+=head1 SYNOPSIS
+
+B<openssl> B<ec>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin arg>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-text>]
+[B<-noout>]
+[B<-param_out>]
+[B<-pubin>]
+[B<-pubout>]
+[B<-conv_form arg>]
+[B<-param_enc arg>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<ec> command processes EC keys. They can be converted between various
+forms and their components printed out. B<Note> OpenSSL uses the
+private key format specified in 'SEC 1: Elliptic Curve Cryptography'
+(http://www.secg.org/). To convert a OpenSSL EC private key into the
+PKCS#8 private key format use the B<pkcs8> command.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option with a private key uses
+an ASN.1 DER encoded SEC1 private key. When used with a public key it
+uses the SubjectPublicKeyInfo structur as specified in RFC 3280.
+The B<PEM> form is the default format: it consists of the B<DER> format base64
+encoded with additional header and footer lines. In the case of a private key
+PKCS#8 format is also accepted.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin arg>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output by
+is not specified. If any encryption options are set then a pass phrase will be
+prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout arg>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-des|-des3|-idea>
+
+These options encrypt the private key with the DES, triple DES, IDEA or
+any other cipher supported by OpenSSL before outputting it. A pass phrase is
+prompted for.
+If none of these options is specified the key is written in plain text. This
+means that using the B<ec> utility to read in an encrypted key with no
+encryption option can be used to remove the pass phrase from a key, or by
+setting the encryption options it can be use to add or change the pass phrase.
+These options can only be used with PEM format output files.
+
+=item B<-text>
+
+prints out the public, private key components and parameters.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the key.
+
+=item B<-modulus>
+
+this option prints out the value of the public key component of the key.
+
+=item B<-pubin>
+
+by default a private key is read from the input file: with this option a
+public key is read instead.
+
+=item B<-pubout>
+
+by default a private key is output. With this option a public
+key will be output instead. This option is automatically set if the input is
+a public key.
+
+=item B<-conv_form>
+
+This specifies how the points on the elliptic curve are converted
+into octet strings. Possible values are: B<compressed> (the default
+value), B<uncompressed> and B<hybrid>. For more information regarding
+the point conversion forms please read the X9.62 standard.
+B<Note> Due to patent issues the B<compressed> option is disabled
+by default for binary curves and can be enabled by defining
+the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
+
+=item B<-param_enc arg>
+
+This specifies how the elliptic curve parameters are encoded.
+Possible value are: B<named_curve>, i.e. the ec parameters are
+specified by a OID, or B<explicit> where the ec parameters are
+explicitly given (see RFC 3279 for the definition of the
+EC parameters structures). The default value is B<named_curve>.
+B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279,
+is currently not implemented in OpenSSL.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 NOTES
+
+The PEM private key format uses the header and footer lines:
+
+ -----BEGIN EC PRIVATE KEY-----
+ -----END EC PRIVATE KEY-----
+
+The PEM public key format uses the header and footer lines:
+
+ -----BEGIN PUBLIC KEY-----
+ -----END PUBLIC KEY-----
+
+=head1 EXAMPLES
+
+To encrypt a private key using triple DES:
+
+ openssl ec -in key.pem -des3 -out keyout.pem
+
+To convert a private key from PEM to DER format:
+
+ openssl ec -in key.pem -outform DER -out keyout.der
+
+To print out the components of a private key to standard output:
+
+ openssl ec -in key.pem -text -noout
+
+To just output the public part of a private key:
+
+ openssl ec -in key.pem -pubout -out pubkey.pem
+
+To change the parameters encoding to B<explicit>:
+
+ openssl ec -in key.pem -param_enc explicit -out keyout.pem
+
+To change the point conversion form to B<compressed>:
+
+ openssl ec -in key.pem -conv_form compressed -out keyout.pem
+
+=head1 SEE ALSO
+
+L<ecparam(1)|ecparam(1)>, L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>
+
+=head1 HISTORY
+
+The ec command was first introduced in OpenSSL 0.9.8.
+
+=head1 AUTHOR
+
+Nils Larsch for the OpenSSL project (http://www.openssl.org).
+
+=cut
diff --git a/doc/apps/ecparam.pod b/doc/apps/ecparam.pod
new file mode 100644
index 000000000000..1a12105da733
--- /dev/null
+++ b/doc/apps/ecparam.pod
@@ -0,0 +1,179 @@
+=pod
+
+=head1 NAME
+
+ecparam - EC parameter manipulation and generation
+
+=head1 SYNOPSIS
+
+B<openssl ecparam>
+[B<-inform DER|PEM>]
+[B<-outform DER|PEM>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-text>]
+[B<-C>]
+[B<-check>]
+[B<-name arg>]
+[B<-list_curve>]
+[B<-conv_form arg>]
+[B<-param_enc arg>]
+[B<-no_seed>]
+[B<-rand file(s)>]
+[B<-genkey>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+This command is used to manipulate or generate EC parameter files.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN.1 DER encoded
+form compatible with RFC 3279 EcpkParameters. The PEM form is the default
+format: it consists of the B<DER> format base64 encoded with additional
+header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read parameters from or standard input if
+this option is not specified.
+
+=item B<-out filename>
+
+This specifies the output filename parameters to. Standard output is used
+if this option is not present. The output filename should B<not> be the same
+as the input filename.
+
+=item B<-noout>
+
+This option inhibits the output of the encoded version of the parameters.
+
+=item B<-text>
+
+This option prints out the EC parameters in human readable form.
+
+=item B<-C>
+
+This option converts the EC parameters into C code. The parameters can then
+be loaded by calling the B<get_ec_group_XXX()> function.
+
+=item B<-check>
+
+Validate the elliptic curve parameters.
+
+=item B<-name arg>
+
+Use the EC parameters with the specified 'short' name. Use B<-list_curves>
+to get a list of all currently implemented EC parameters.
+
+=item B<-list_curves>
+
+If this options is specified B<ecparam> will print out a list of all
+currently implemented EC parameters names and exit.
+
+=item B<-conv_form>
+
+This specifies how the points on the elliptic curve are converted
+into octet strings. Possible values are: B<compressed> (the default
+value), B<uncompressed> and B<hybrid>. For more information regarding
+the point conversion forms please read the X9.62 standard.
+B<Note> Due to patent issues the B<compressed> option is disabled
+by default for binary curves and can be enabled by defining
+the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
+
+=item B<-param_enc arg>
+
+This specifies how the elliptic curve parameters are encoded.
+Possible value are: B<named_curve>, i.e. the ec parameters are
+specified by a OID, or B<explicit> where the ec parameters are
+explicitly given (see RFC 3279 for the definition of the
+EC parameters structures). The default value is B<named_curve>.
+B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279,
+is currently not implemented in OpenSSL.
+
+=item B<-no_seed>
+
+This option inhibits that the 'seed' for the parameter generation
+is included in the ECParameters structure (see RFC 3279).
+
+=item B<-genkey>
+
+This option will generate a EC private key using the specified parameters.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 NOTES
+
+PEM format EC parameters use the header and footer lines:
+
+ -----BEGIN EC PARAMETERS-----
+ -----END EC PARAMETERS-----
+
+OpenSSL is currently not able to generate new groups and therefore
+B<ecparam> can only create EC parameters from known (named) curves.
+
+=head1 EXAMPLES
+
+To create EC parameters with the group 'prime192v1':
+
+ openssl ecparam -out ec_param.pem -name prime192v1
+
+To create EC parameters with explicit parameters:
+
+ openssl ecparam -out ec_param.pem -name prime192v1 -param_enc explicit
+
+To validate given EC parameters:
+
+ openssl ecparam -in ec_param.pem -check
+
+To create EC parameters and a private key:
+
+ openssl ecparam -out ec_key.pem -name prime192v1 -genkey
+
+To change the point encoding to 'compressed':
+
+ openssl ecparam -in ec_in.pem -out ec_out.pem -conv_form compressed
+
+To print out the EC parameters to standard output:
+
+ openssl ecparam -in ec_param.pem -noout -text
+
+=head1 SEE ALSO
+
+L<ec(1)|ec(1)>, L<dsaparam(1)|dsaparam(1)>
+
+=head1 HISTORY
+
+The ecparam command was first introduced in OpenSSL 0.9.8.
+
+=head1 AUTHOR
+
+Nils Larsch for the OpenSSL project (http://www.openssl.org)
+
+=cut
diff --git a/doc/apps/enc.pod b/doc/apps/enc.pod
new file mode 100644
index 000000000000..c43da5b3f1ee
--- /dev/null
+++ b/doc/apps/enc.pod
@@ -0,0 +1,271 @@
+=pod
+
+=head1 NAME
+
+enc - symmetric cipher routines
+
+=head1 SYNOPSIS
+
+B<openssl enc -ciphername>
+[B<-in filename>]
+[B<-out filename>]
+[B<-pass arg>]
+[B<-e>]
+[B<-d>]
+[B<-a>]
+[B<-A>]
+[B<-k password>]
+[B<-kfile filename>]
+[B<-K key>]
+[B<-iv IV>]
+[B<-p>]
+[B<-P>]
+[B<-bufsize number>]
+[B<-nopad>]
+[B<-debug>]
+
+=head1 DESCRIPTION
+
+The symmetric cipher commands allow data to be encrypted or decrypted
+using various block and stream ciphers using keys based on passwords
+or explicitly provided. Base64 encoding or decoding can also be performed
+either by itself or in addition to the encryption or decryption.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-in filename>
+
+the input filename, standard input by default.
+
+=item B<-out filename>
+
+the output filename, standard output by default.
+
+=item B<-pass arg>
+
+the password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-salt>
+
+use a salt in the key derivation routines. This option should B<ALWAYS>
+be used unless compatibility with previous versions of OpenSSL or SSLeay
+is required. This option is only present on OpenSSL versions 0.9.5 or
+above.
+
+=item B<-nosalt>
+
+don't use a salt in the key derivation routines. This is the default for
+compatibility with previous versions of OpenSSL and SSLeay.
+
+=item B<-e>
+
+encrypt the input data: this is the default.
+
+=item B<-d>
+
+decrypt the input data.
+
+=item B<-a>
+
+base64 process the data. This means that if encryption is taking place
+the data is base64 encoded after encryption. If decryption is set then
+the input data is base64 decoded before being decrypted.
+
+=item B<-A>
+
+if the B<-a> option is set then base64 process the data on one line.
+
+=item B<-k password>
+
+the password to derive the key from. This is for compatibility with previous
+versions of OpenSSL. Superseded by the B<-pass> argument.
+
+=item B<-kfile filename>
+
+read the password to derive the key from the first line of B<filename>.
+This is for compatibility with previous versions of OpenSSL. Superseded by
+the B<-pass> argument.
+
+=item B<-S salt>
+
+the actual salt to use: this must be represented as a string comprised only
+of hex digits.
+
+=item B<-K key>
+
+the actual key to use: this must be represented as a string comprised only
+of hex digits. If only the key is specified, the IV must additionally specified
+using the B<-iv> option. When both a key and a password are specified, the
+key given with the B<-K> option will be used and the IV generated from the
+password will be taken. It probably does not make much sense to specify
+both key and password.
+
+=item B<-iv IV>
+
+the actual IV to use: this must be represented as a string comprised only
+of hex digits. When only the key is specified using the B<-K> option, the
+IV must explicitly be defined. When a password is being specified using
+one of the other options, the IV is generated from this password.
+
+=item B<-p>
+
+print out the key and IV used.
+
+=item B<-P>
+
+print out the key and IV used then immediately exit: don't do any encryption
+or decryption.
+
+=item B<-bufsize number>
+
+set the buffer size for I/O
+
+=item B<-nopad>
+
+disable standard block padding
+
+=item B<-debug>
+
+debug the BIOs used for I/O.
+
+=back
+
+=head1 NOTES
+
+The program can be called either as B<openssl ciphername> or
+B<openssl enc -ciphername>.
+
+A password will be prompted for to derive the key and IV if necessary.
+
+The B<-salt> option should B<ALWAYS> be used if the key is being derived
+from a password unless you want compatibility with previous versions of
+OpenSSL and SSLeay.
+
+Without the B<-salt> option it is possible to perform efficient dictionary
+attacks on the password and to attack stream cipher encrypted data. The reason
+for this is that without the salt the same password always generates the same
+encryption key. When the salt is being used the first eight bytes of the
+encrypted data are reserved for the salt: it is generated at random when
+encrypting a file and read from the encrypted file when it is decrypted.
+
+Some of the ciphers do not have large keys and others have security
+implications if not used correctly. A beginner is advised to just use
+a strong block cipher in CBC mode such as bf or des3.
+
+All the block ciphers normally use PKCS#5 padding also known as standard block
+padding: this allows a rudimentary integrity or password check to be
+performed. However since the chance of random data passing the test is
+better than 1 in 256 it isn't a very good test.
+
+If padding is disabled then the input data must be a multiple of the cipher
+block length.
+
+All RC2 ciphers have the same key and effective key length.
+
+Blowfish and RC5 algorithms use a 128 bit key.
+
+=head1 SUPPORTED CIPHERS
+
+ base64 Base 64
+
+ bf-cbc Blowfish in CBC mode
+ bf Alias for bf-cbc
+ bf-cfb Blowfish in CFB mode
+ bf-ecb Blowfish in ECB mode
+ bf-ofb Blowfish in OFB mode
+
+ cast-cbc CAST in CBC mode
+ cast Alias for cast-cbc
+ cast5-cbc CAST5 in CBC mode
+ cast5-cfb CAST5 in CFB mode
+ cast5-ecb CAST5 in ECB mode
+ cast5-ofb CAST5 in OFB mode
+
+ des-cbc DES in CBC mode
+ des Alias for des-cbc
+ des-cfb DES in CBC mode
+ des-ofb DES in OFB mode
+ des-ecb DES in ECB mode
+
+ des-ede-cbc Two key triple DES EDE in CBC mode
+ des-ede Two key triple DES EDE in ECB mode
+ des-ede-cfb Two key triple DES EDE in CFB mode
+ des-ede-ofb Two key triple DES EDE in OFB mode
+
+ des-ede3-cbc Three key triple DES EDE in CBC mode
+ des-ede3 Three key triple DES EDE in ECB mode
+ des3 Alias for des-ede3-cbc
+ des-ede3-cfb Three key triple DES EDE CFB mode
+ des-ede3-ofb Three key triple DES EDE in OFB mode
+
+ desx DESX algorithm.
+
+ idea-cbc IDEA algorithm in CBC mode
+ idea same as idea-cbc
+ idea-cfb IDEA in CFB mode
+ idea-ecb IDEA in ECB mode
+ idea-ofb IDEA in OFB mode
+
+ rc2-cbc 128 bit RC2 in CBC mode
+ rc2 Alias for rc2-cbc
+ rc2-cfb 128 bit RC2 in CFB mode
+ rc2-ecb 128 bit RC2 in ECB mode
+ rc2-ofb 128 bit RC2 in OFB mode
+ rc2-64-cbc 64 bit RC2 in CBC mode
+ rc2-40-cbc 40 bit RC2 in CBC mode
+
+ rc4 128 bit RC4
+ rc4-64 64 bit RC4
+ rc4-40 40 bit RC4
+
+ rc5-cbc RC5 cipher in CBC mode
+ rc5 Alias for rc5-cbc
+ rc5-cfb RC5 cipher in CFB mode
+ rc5-ecb RC5 cipher in ECB mode
+ rc5-ofb RC5 cipher in OFB mode
+
+=head1 EXAMPLES
+
+Just base64 encode a binary file:
+
+ openssl base64 -in file.bin -out file.b64
+
+Decode the same file
+
+ openssl base64 -d -in file.b64 -out file.bin
+
+Encrypt a file using triple DES in CBC mode using a prompted password:
+
+ openssl des3 -salt -in file.txt -out file.des3
+
+Decrypt a file using a supplied password:
+
+ openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword
+
+Encrypt a file then base64 encode it (so it can be sent via mail for example)
+using Blowfish in CBC mode:
+
+ openssl bf -a -salt -in file.txt -out file.bf
+
+Base64 decode a file then decrypt it:
+
+ openssl bf -d -salt -a -in file.bf -out file.txt
+
+Decrypt some data using a supplied 40 bit RC4 key:
+
+ openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405
+
+=head1 BUGS
+
+The B<-A> option when used with large files doesn't work properly.
+
+There should be an option to allow an iteration count to be included.
+
+The B<enc> program only supports a fixed number of algorithms with
+certain parameters. So if, for example, you want to use RC2 with a
+76 bit key or RC4 with an 84 bit key you can't use this program.
+
+=cut
diff --git a/doc/apps/errstr.pod b/doc/apps/errstr.pod
new file mode 100644
index 000000000000..b3c6ccfc9cbd
--- /dev/null
+++ b/doc/apps/errstr.pod
@@ -0,0 +1,39 @@
+=pod
+
+=head1 NAME
+
+errstr - lookup error codes
+
+=head1 SYNOPSIS
+
+B<openssl errstr error_code>
+
+=head1 DESCRIPTION
+
+Sometimes an application will not load error message and only
+numerical forms will be available. The B<errstr> utility can be used to
+display the meaning of the hex code. The hex code is the hex digits after the
+second colon.
+
+=head1 EXAMPLE
+
+The error code:
+
+ 27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107:
+
+can be displayed with:
+
+ openssl errstr 2006D080
+
+to produce the error message:
+
+ error:2006D080:BIO routines:BIO_new_file:no such file
+
+=head1 SEE ALSO
+
+L<err(3)|err(3)>,
+L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
+L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
+
+
+=cut
diff --git a/doc/apps/gendsa.pod b/doc/apps/gendsa.pod
new file mode 100644
index 000000000000..2c56cc788897
--- /dev/null
+++ b/doc/apps/gendsa.pod
@@ -0,0 +1,66 @@
+=pod
+
+=head1 NAME
+
+gendsa - generate a DSA private key from a set of parameters
+
+=head1 SYNOPSIS
+
+B<openssl> B<gendsa>
+[B<-out filename>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-rand file(s)>]
+[B<-engine id>]
+[B<paramfile>]
+
+=head1 DESCRIPTION
+
+The B<gendsa> command generates a DSA private key from a DSA parameter file
+(which will be typically generated by the B<openssl dsaparam> command).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-des|-des3|-idea>
+
+These options encrypt the private key with the DES, triple DES, or the
+IDEA ciphers respectively before outputting it. A pass phrase is prompted for.
+If none of these options is specified no encryption is used.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<paramfile>
+
+This option specifies the DSA parameter file to use. The parameters in this
+file determine the size of the private key. DSA parameters can be generated
+and examined using the B<openssl dsaparam> command.
+
+=back
+
+=head1 NOTES
+
+DSA key generation is little more than random number generation so it is
+much quicker that RSA key generation for example.
+
+=head1 SEE ALSO
+
+L<dsaparam(1)|dsaparam(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>,
+L<rsa(1)|rsa(1)>
+
+=cut
diff --git a/doc/apps/genrsa.pod b/doc/apps/genrsa.pod
new file mode 100644
index 000000000000..25af4d1475cd
--- /dev/null
+++ b/doc/apps/genrsa.pod
@@ -0,0 +1,96 @@
+=pod
+
+=head1 NAME
+
+genrsa - generate an RSA private key
+
+=head1 SYNOPSIS
+
+B<openssl> B<genrsa>
+[B<-out filename>]
+[B<-passout arg>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-f4>]
+[B<-3>]
+[B<-rand file(s)>]
+[B<-engine id>]
+[B<numbits>]
+
+=head1 DESCRIPTION
+
+The B<genrsa> command generates an RSA private key.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-out filename>
+
+the output filename. If this argument is not specified then standard output is
+used.
+
+=item B<-passout arg>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-des|-des3|-idea>
+
+These options encrypt the private key with the DES, triple DES, or the
+IDEA ciphers respectively before outputting it. If none of these options is
+specified no encryption is used. If encryption is used a pass phrase is prompted
+for if it is not supplied via the B<-passout> argument.
+
+=item B<-F4|-3>
+
+the public exponent to use, either 65537 or 3. The default is 65537.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<numbits>
+
+the size of the private key to generate in bits. This must be the last option
+specified. The default is 512.
+
+=back
+
+=head1 NOTES
+
+RSA private key generation essentially involves the generation of two prime
+numbers. When generating a private key various symbols will be output to
+indicate the progress of the generation. A B<.> represents each number which
+has passed an initial sieve test, B<+> means a number has passed a single
+round of the Miller-Rabin primality test. A newline means that the number has
+passed all the prime tests (the actual number depends on the key size).
+
+Because key generation is a random process the time taken to generate a key
+may vary somewhat.
+
+=head1 BUGS
+
+A quirk of the prime generation algorithm is that it cannot generate small
+primes. Therefore the number of bits should not be less that 64. For typical
+private keys this will not matter because for security reasons they will
+be much larger (typically 1024 bits).
+
+=head1 SEE ALSO
+
+L<gendsa(1)|gendsa(1)>
+
+=cut
+
diff --git a/doc/apps/nseq.pod b/doc/apps/nseq.pod
new file mode 100644
index 000000000000..989c3108fb83
--- /dev/null
+++ b/doc/apps/nseq.pod
@@ -0,0 +1,70 @@
+=pod
+
+=head1 NAME
+
+nseq - create or examine a netscape certificate sequence
+
+=head1 SYNOPSIS
+
+B<openssl> B<nseq>
+[B<-in filename>]
+[B<-out filename>]
+[B<-toseq>]
+
+=head1 DESCRIPTION
+
+The B<nseq> command takes a file containing a Netscape certificate
+sequence and prints out the certificates contained in it or takes a
+file of certificates and converts it into a Netscape certificate
+sequence.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-in filename>
+
+This specifies the input filename to read or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename or standard output by default.
+
+=item B<-toseq>
+
+normally a Netscape certificate sequence will be input and the output
+is the certificates contained in it. With the B<-toseq> option the
+situation is reversed: a Netscape certificate sequence is created from
+a file of certificates.
+
+=back
+
+=head1 EXAMPLES
+
+Output the certificates in a Netscape certificate sequence
+
+ openssl nseq -in nseq.pem -out certs.pem
+
+Create a Netscape certificate sequence
+
+ openssl nseq -in certs.pem -toseq -out nseq.pem
+
+=head1 NOTES
+
+The B<PEM> encoded form uses the same headers and footers as a certificate:
+
+ -----BEGIN CERTIFICATE-----
+ -----END CERTIFICATE-----
+
+A Netscape certificate sequence is a Netscape specific form that can be sent
+to browsers as an alternative to the standard PKCS#7 format when several
+certificates are sent to the browser: for example during certificate enrollment.
+It is used by Netscape certificate server for example.
+
+=head1 BUGS
+
+This program needs a few more options: like allowing DER or PEM input and
+output files and allowing multiple certificate files to be used.
+
+=cut
diff --git a/doc/apps/ocsp.pod b/doc/apps/ocsp.pod
new file mode 100644
index 000000000000..4f266058e536
--- /dev/null
+++ b/doc/apps/ocsp.pod
@@ -0,0 +1,365 @@
+=pod
+
+=head1 NAME
+
+ocsp - Online Certificate Status Protocol utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<ocsp>
+[B<-out file>]
+[B<-issuer file>]
+[B<-cert file>]
+[B<-serial n>]
+[B<-signer file>]
+[B<-signkey file>]
+[B<-sign_other file>]
+[B<-no_certs>]
+[B<-req_text>]
+[B<-resp_text>]
+[B<-text>]
+[B<-reqout file>]
+[B<-respout file>]
+[B<-reqin file>]
+[B<-respin file>]
+[B<-nonce>]
+[B<-no_nonce>]
+[B<-url URL>]
+[B<-host host:n>]
+[B<-path>]
+[B<-CApath dir>]
+[B<-CAfile file>]
+[B<-VAfile file>]
+[B<-validity_period n>]
+[B<-status_age n>]
+[B<-noverify>]
+[B<-verify_other file>]
+[B<-trust_other>]
+[B<-no_intern>]
+[B<-no_signature_verify>]
+[B<-no_cert_verify>]
+[B<-no_chain>]
+[B<-no_cert_checks>]
+[B<-port num>]
+[B<-index file>]
+[B<-CA file>]
+[B<-rsigner file>]
+[B<-rkey file>]
+[B<-rother file>]
+[B<-resp_no_certs>]
+[B<-nmin n>]
+[B<-ndays n>]
+[B<-resp_key_id>]
+[B<-nrequest n>]
+
+=head1 DESCRIPTION
+
+The Online Certificate Status Protocol (OCSP) enables applications to
+determine the (revocation) state of an identified certificate (RFC 2560).
+
+The B<ocsp> command performs many common OCSP tasks. It can be used
+to print out requests and responses, create requests and send queries
+to an OCSP responder and behave like a mini OCSP server itself.
+
+=head1 OCSP CLIENT OPTIONS
+
+=over 4
+
+=item B<-out filename>
+
+specify output filename, default is standard output.
+
+=item B<-issuer filename>
+
+This specifies the current issuer certificate. This option can be used
+multiple times. The certificate specified in B<filename> must be in
+PEM format.
+
+=item B<-cert filename>
+
+Add the certificate B<filename> to the request. The issuer certificate
+is taken from the previous B<issuer> option, or an error occurs if no
+issuer certificate is specified.
+
+=item B<-serial num>
+
+Same as the B<cert> option except the certificate with serial number
+B<num> is added to the request. The serial number is interpreted as a
+decimal integer unless preceded by B<0x>. Negative integers can also
+be specified by preceding the value by a B<-> sign.
+
+=item B<-signer filename>, B<-signkey filename>
+
+Sign the OCSP request using the certificate specified in the B<signer>
+option and the private key specified by the B<signkey> option. If
+the B<signkey> option is not present then the private key is read
+from the same file as the certificate. If neither option is specified then
+the OCSP request is not signed.
+
+=item B<-sign_other filename>
+
+Additional certificates to include in the signed request.
+
+=item B<-nonce>, B<-no_nonce>
+
+Add an OCSP nonce extension to a request or disable OCSP nonce addition.
+Normally if an OCSP request is input using the B<respin> option no
+nonce is added: using the B<nonce> option will force addition of a nonce.
+If an OCSP request is being created (using B<cert> and B<serial> options)
+a nonce is automatically added specifying B<no_nonce> overrides this.
+
+=item B<-req_text>, B<-resp_text>, B<-text>
+
+print out the text form of the OCSP request, response or both respectively.
+
+=item B<-reqout file>, B<-respout file>
+
+write out the DER encoded certificate request or response to B<file>.
+
+=item B<-reqin file>, B<-respin file>
+
+read OCSP request or response file from B<file>. These option are ignored
+if OCSP request or response creation is implied by other options (for example
+with B<serial>, B<cert> and B<host> options).
+
+=item B<-url responder_url>
+
+specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
+
+=item B<-host hostname:port>, B<-path pathname>
+
+if the B<host> option is present then the OCSP request is sent to the host
+B<hostname> on port B<port>. B<path> specifies the HTTP path name to use
+or "/" by default.
+
+=item B<-CAfile file>, B<-CApath pathname>
+
+file or pathname containing trusted CA certificates. These are used to verify
+the signature on the OCSP response.
+
+=item B<-verify_other file>
+
+file containing additional certificates to search when attempting to locate
+the OCSP response signing certificate. Some responders omit the actual signer's
+certificate from the response: this option can be used to supply the necessary
+certificate in such cases.
+
+=item B<-trust_other>
+
+the certificates specified by the B<-verify_certs> option should be explicitly
+trusted and no additional checks will be performed on them. This is useful
+when the complete responder certificate chain is not available or trusting a
+root CA is not appropriate.
+
+=item B<-VAfile file>
+
+file containing explicitly trusted responder certificates. Equivalent to the
+B<-verify_certs> and B<-trust_other> options.
+
+=item B<-noverify>
+
+don't attempt to verify the OCSP response signature or the nonce values. This
+option will normally only be used for debugging since it disables all verification
+of the responders certificate.
+
+=item B<-no_intern>
+
+ignore certificates contained in the OCSP response when searching for the
+signers certificate. With this option the signers certificate must be specified
+with either the B<-verify_certs> or B<-VAfile> options.
+
+=item B<-no_signature_verify>
+
+don't check the signature on the OCSP response. Since this option tolerates invalid
+signatures on OCSP responses it will normally only be used for testing purposes.
+
+=item B<-no_cert_verify>
+
+don't verify the OCSP response signers certificate at all. Since this option allows
+the OCSP response to be signed by any certificate it should only be used for
+testing purposes.
+
+=item B<-no_chain>
+
+do not use certificates in the response as additional untrusted CA
+certificates.
+
+=item B<-no_cert_checks>
+
+don't perform any additional checks on the OCSP response signers certificate.
+That is do not make any checks to see if the signers certificate is authorised
+to provide the necessary status information: as a result this option should
+only be used for testing purposes.
+
+=item B<-validity_period nsec>, B<-status_age age>
+
+these options specify the range of times, in seconds, which will be tolerated
+in an OCSP response. Each certificate status response includes a B<notBefore> time and
+an optional B<notAfter> time. The current time should fall between these two values, but
+the interval between the two times may be only a few seconds. In practice the OCSP
+responder and clients clocks may not be precisely synchronised and so such a check
+may fail. To avoid this the B<-validity_period> option can be used to specify an
+acceptable error range in seconds, the default value is 5 minutes.
+
+If the B<notAfter> time is omitted from a response then this means that new status
+information is immediately available. In this case the age of the B<notBefore> field
+is checked to see it is not older than B<age> seconds old. By default this additional
+check is not performed.
+
+=back
+
+=head1 OCSP SERVER OPTIONS
+
+=over 4
+
+=item B<-index indexfile>
+
+B<indexfile> is a text index file in B<ca> format containing certificate revocation
+information.
+
+If the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise
+it is in client mode. The request(s) the responder processes can be either specified on
+the command line (using B<issuer> and B<serial> options), supplied in a file (using the
+B<respin> option) or via external OCSP clients (if B<port> or B<url> is specified).
+
+If the B<index> option is present then the B<CA> and B<rsigner> options must also be
+present.
+
+=item B<-CA file>
+
+CA certificate corresponding to the revocation information in B<indexfile>.
+
+=item B<-rsigner file>
+
+The certificate to sign OCSP responses with.
+
+=item B<-rother file>
+
+Additional certificates to include in the OCSP response.
+
+=item B<-resp_no_certs>
+
+Don't include any certificates in the OCSP response.
+
+=item B<-resp_key_id>
+
+Identify the signer certificate using the key ID, default is to use the subject name.
+
+=item B<-rkey file>
+
+The private key to sign OCSP responses with: if not present the file specified in the
+B<rsigner> option is used.
+
+=item B<-port portnum>
+
+Port to listen for OCSP requests on. The port may also be specified using the B<url>
+option.
+
+=item B<-nrequest number>
+
+The OCSP server will exit after receiving B<number> requests, default unlimited.
+
+=item B<-nmin minutes>, B<-ndays days>
+
+Number of minutes or days when fresh revocation information is available: used in the
+B<nextUpdate> field. If neither option is present then the B<nextUpdate> field is
+omitted meaning fresh revocation information is immediately available.
+
+=back
+
+=head1 OCSP Response verification.
+
+OCSP Response follows the rules specified in RFC2560.
+
+Initially the OCSP responder certificate is located and the signature on
+the OCSP request checked using the responder certificate's public key.
+
+Then a normal certificate verify is performed on the OCSP responder certificate
+building up a certificate chain in the process. The locations of the trusted
+certificates used to build the chain can be specified by the B<CAfile>
+and B<CApath> options or they will be looked for in the standard OpenSSL
+certificates directory.
+
+If the initial verify fails then the OCSP verify process halts with an
+error.
+
+Otherwise the issuing CA certificate in the request is compared to the OCSP
+responder certificate: if there is a match then the OCSP verify succeeds.
+
+Otherwise the OCSP responder certificate's CA is checked against the issuing
+CA certificate in the request. If there is a match and the OCSPSigning
+extended key usage is present in the OCSP responder certificate then the
+OCSP verify succeeds.
+
+Otherwise the root CA of the OCSP responders CA is checked to see if it
+is trusted for OCSP signing. If it is the OCSP verify succeeds.
+
+If none of these checks is successful then the OCSP verify fails.
+
+What this effectively means if that if the OCSP responder certificate is
+authorised directly by the CA it is issuing revocation information about
+(and it is correctly configured) then verification will succeed.
+
+If the OCSP responder is a "global responder" which can give details about
+multiple CAs and has its own separate certificate chain then its root
+CA can be trusted for OCSP signing. For example:
+
+ openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem
+
+Alternatively the responder certificate itself can be explicitly trusted
+with the B<-VAfile> option.
+
+=head1 NOTES
+
+As noted, most of the verify options are for testing or debugging purposes.
+Normally only the B<-CApath>, B<-CAfile> and (if the responder is a 'global
+VA') B<-VAfile> options need to be used.
+
+The OCSP server is only useful for test and demonstration purposes: it is
+not really usable as a full OCSP responder. It contains only a very
+simple HTTP request handling and can only handle the POST form of OCSP
+queries. It also handles requests serially meaning it cannot respond to
+new requests until it has processed the current one. The text index file
+format of revocation is also inefficient for large quantities of revocation
+data.
+
+It is possible to run the B<ocsp> application in responder mode via a CGI
+script using the B<respin> and B<respout> options.
+
+=head1 EXAMPLES
+
+Create an OCSP request and write it to a file:
+
+ openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der
+
+Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the
+response to a file and print it out in text form
+
+ openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \
+ -url http://ocsp.myhost.com/ -resp_text -respout resp.der
+
+Read in an OCSP response and print out text form:
+
+ openssl ocsp -respin resp.der -text
+
+OCSP server on port 8888 using a standard B<ca> configuration, and a separate
+responder certificate. All requests and responses are printed to a file.
+
+ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
+ -text -out log.txt
+
+As above but exit after processing one request:
+
+ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
+ -nrequest 1
+
+Query status information using internally generated request:
+
+ openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
+ -issuer demoCA/cacert.pem -serial 1
+
+Query status information using request read from a file, write response to a
+second file.
+
+ openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
+ -reqin req.der -respout resp.der
diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod
new file mode 100644
index 000000000000..dc0f49ddca63
--- /dev/null
+++ b/doc/apps/openssl.pod
@@ -0,0 +1,345 @@
+
+=pod
+
+=head1 NAME
+
+openssl - OpenSSL command line tool
+
+=head1 SYNOPSIS
+
+B<openssl>
+I<command>
+[ I<command_opts> ]
+[ I<command_args> ]
+
+B<openssl> [ B<list-standard-commands> | B<list-message-digest-commands> | B<list-cipher-commands> ]
+
+B<openssl> B<no->I<XXX> [ I<arbitrary options> ]
+
+=head1 DESCRIPTION
+
+OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL
+v2/v3) and Transport Layer Security (TLS v1) network protocols and related
+cryptography standards required by them.
+
+The B<openssl> program is a command line tool for using the various
+cryptography functions of OpenSSL's B<crypto> library from the shell.
+It can be used for
+
+ o Creation of RSA, DH and DSA key parameters
+ o Creation of X.509 certificates, CSRs and CRLs
+ o Calculation of Message Digests
+ o Encryption and Decryption with Ciphers
+ o SSL/TLS Client and Server Tests
+ o Handling of S/MIME signed or encrypted mail
+
+=head1 COMMAND SUMMARY
+
+The B<openssl> program provides a rich variety of commands (I<command> in the
+SYNOPSIS above), each of which often has a wealth of options and arguments
+(I<command_opts> and I<command_args> in the SYNOPSIS).
+
+The pseudo-commands B<list-standard-commands>, B<list-message-digest-commands>,
+and B<list-cipher-commands> output a list (one entry per line) of the names
+of all standard commands, message digest commands, or cipher commands,
+respectively, that are available in the present B<openssl> utility.
+
+The pseudo-command B<no->I<XXX> tests whether a command of the
+specified name is available. If no command named I<XXX> exists, it
+returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1
+and prints I<XXX>. In both cases, the output goes to B<stdout> and
+nothing is printed to B<stderr>. Additional command line arguments
+are always ignored. Since for each cipher there is a command of the
+same name, this provides an easy way for shell scripts to test for the
+availability of ciphers in the B<openssl> program. (B<no->I<XXX> is
+not able to detect pseudo-commands such as B<quit>,
+B<list->I<...>B<-commands>, or B<no->I<XXX> itself.)
+
+=head2 STANDARD COMMANDS
+
+=over 10
+
+=item L<B<asn1parse>|asn1parse(1)>
+
+Parse an ASN.1 sequence.
+
+=item L<B<ca>|ca(1)>
+
+Certificate Authority (CA) Management.
+
+=item L<B<ciphers>|ciphers(1)>
+
+Cipher Suite Description Determination.
+
+=item L<B<crl>|crl(1)>
+
+Certificate Revocation List (CRL) Management.
+
+=item L<B<crl2pkcs7>|crl2pkcs7(1)>
+
+CRL to PKCS#7 Conversion.
+
+=item L<B<dgst>|dgst(1)>
+
+Message Digest Calculation.
+
+=item B<dh>
+
+Diffie-Hellman Parameter Management.
+Obsoleted by L<B<dhparam>|dhparam(1)>.
+
+=item L<B<dsa>|dsa(1)>
+
+DSA Data Management.
+
+=item L<B<dsaparam>|dsaparam(1)>
+
+DSA Parameter Generation.
+
+=item L<B<enc>|enc(1)>
+
+Encoding with Ciphers.
+
+=item L<B<errstr>|errstr(1)>
+
+Error Number to Error String Conversion.
+
+=item L<B<dhparam>|dhparam(1)>
+
+Generation and Management of Diffie-Hellman Parameters.
+
+=item B<gendh>
+
+Generation of Diffie-Hellman Parameters.
+Obsoleted by L<B<dhparam>|dhparam(1)>.
+
+=item L<B<gendsa>|gendsa(1)>
+
+Generation of DSA Parameters.
+
+=item L<B<genrsa>|genrsa(1)>
+
+Generation of RSA Parameters.
+
+=item L<B<ocsp>|ocsp(1)>
+
+Online Certificate Status Protocol utility.
+
+=item L<B<passwd>|passwd(1)>
+
+Generation of hashed passwords.
+
+=item L<B<pkcs12>|pkcs12(1)>
+
+PKCS#12 Data Management.
+
+=item L<B<pkcs7>|pkcs7(1)>
+
+PKCS#7 Data Management.
+
+=item L<B<rand>|rand(1)>
+
+Generate pseudo-random bytes.
+
+=item L<B<req>|req(1)>
+
+X.509 Certificate Signing Request (CSR) Management.
+
+=item L<B<rsa>|rsa(1)>
+
+RSA Data Management.
+
+=item L<B<rsautl>|rsautl(1)>
+
+RSA utility for signing, verification, encryption, and decryption.
+
+=item L<B<s_client>|s_client(1)>
+
+This implements a generic SSL/TLS client which can establish a transparent
+connection to a remote server speaking SSL/TLS. It's intended for testing
+purposes only and provides only rudimentary interface functionality but
+internally uses mostly all functionality of the OpenSSL B<ssl> library.
+
+=item L<B<s_server>|s_server(1)>
+
+This implements a generic SSL/TLS server which accepts connections from remote
+clients speaking SSL/TLS. It's intended for testing purposes only and provides
+only rudimentary interface functionality but internally uses mostly all
+functionality of the OpenSSL B<ssl> library. It provides both an own command
+line oriented protocol for testing SSL functions and a simple HTTP response
+facility to emulate an SSL/TLS-aware webserver.
+
+=item L<B<s_time>|s_time(1)>
+
+SSL Connection Timer.
+
+=item L<B<sess_id>|sess_id(1)>
+
+SSL Session Data Management.
+
+=item L<B<smime>|smime(1)>
+
+S/MIME mail processing.
+
+=item L<B<speed>|speed(1)>
+
+Algorithm Speed Measurement.
+
+=item L<B<verify>|verify(1)>
+
+X.509 Certificate Verification.
+
+=item L<B<version>|version(1)>
+
+OpenSSL Version Information.
+
+=item L<B<x509>|x509(1)>
+
+X.509 Certificate Data Management.
+
+=back
+
+=head2 MESSAGE DIGEST COMMANDS
+
+=over 10
+
+=item B<md2>
+
+MD2 Digest
+
+=item B<md5>
+
+MD5 Digest
+
+=item B<mdc2>
+
+MDC2 Digest
+
+=item B<rmd160>
+
+RMD-160 Digest
+
+=item B<sha>
+
+SHA Digest
+
+=item B<sha1>
+
+SHA-1 Digest
+
+=back
+
+=head2 ENCODING AND CIPHER COMMANDS
+
+=over 10
+
+=item B<base64>
+
+Base64 Encoding
+
+=item B<bf bf-cbc bf-cfb bf-ecb bf-ofb>
+
+Blowfish Cipher
+
+=item B<cast cast-cbc>
+
+CAST Cipher
+
+=item B<cast5-cbc cast5-cfb cast5-ecb cast5-ofb>
+
+CAST5 Cipher
+
+=item B<des des-cbc des-cfb des-ecb des-ede des-ede-cbc des-ede-cfb des-ede-ofb des-ofb>
+
+DES Cipher
+
+=item B<des3 desx des-ede3 des-ede3-cbc des-ede3-cfb des-ede3-ofb>
+
+Triple-DES Cipher
+
+=item B<idea idea-cbc idea-cfb idea-ecb idea-ofb>
+
+IDEA Cipher
+
+=item B<rc2 rc2-cbc rc2-cfb rc2-ecb rc2-ofb>
+
+RC2 Cipher
+
+=item B<rc4>
+
+RC4 Cipher
+
+=item B<rc5 rc5-cbc rc5-cfb rc5-ecb rc5-ofb>
+
+RC5 Cipher
+
+=back
+
+=head1 PASS PHRASE ARGUMENTS
+
+Several commands accept password arguments, typically using B<-passin>
+and B<-passout> for input and output passwords respectively. These allow
+the password to be obtained from a variety of sources. Both of these
+options take a single argument whose format is described below. If no
+password argument is given and a password is required then the user is
+prompted to enter one: this will typically be read from the current
+terminal with echoing turned off.
+
+=over 10
+
+=item B<pass:password>
+
+the actual password is B<password>. Since the password is visible
+to utilities (like 'ps' under Unix) this form should only be used
+where security is not important.
+
+=item B<env:var>
+
+obtain the password from the environment variable B<var>. Since
+the environment of other processes is visible on certain platforms
+(e.g. ps under certain Unix OSes) this option should be used with caution.
+
+=item B<file:pathname>
+
+the first line of B<pathname> is the password. If the same B<pathname>
+argument is supplied to B<-passin> and B<-passout> arguments then the first
+line will be used for the input password and the next line for the output
+password. B<pathname> need not refer to a regular file: it could for example
+refer to a device or named pipe.
+
+=item B<fd:number>
+
+read the password from the file descriptor B<number>. This can be used to
+send the data via a pipe for example.
+
+=item B<stdin>
+
+read the password from standard input.
+
+=back
+
+=head1 SEE ALSO
+
+L<asn1parse(1)|asn1parse(1)>, L<ca(1)|ca(1)>, L<config(5)|config(5)>,
+L<crl(1)|crl(1)>, L<crl2pkcs7(1)|crl2pkcs7(1)>, L<dgst(1)|dgst(1)>,
+L<dhparam(1)|dhparam(1)>, L<dsa(1)|dsa(1)>, L<dsaparam(1)|dsaparam(1)>,
+L<enc(1)|enc(1)>, L<gendsa(1)|gendsa(1)>,
+L<genrsa(1)|genrsa(1)>, L<nseq(1)|nseq(1)>, L<openssl(1)|openssl(1)>,
+L<passwd(1)|passwd(1)>,
+L<pkcs12(1)|pkcs12(1)>, L<pkcs7(1)|pkcs7(1)>, L<pkcs8(1)|pkcs8(1)>,
+L<rand(1)|rand(1)>, L<req(1)|req(1)>, L<rsa(1)|rsa(1)>,
+L<rsautl(1)|rsautl(1)>, L<s_client(1)|s_client(1)>,
+L<s_server(1)|s_server(1)>, L<s_time(1)|s_time(1)>,
+L<smime(1)|smime(1)>, L<spkac(1)|spkac(1)>,
+L<verify(1)|verify(1)>, L<version(1)|version(1)>, L<x509(1)|x509(1)>,
+L<crypto(3)|crypto(3)>, L<ssl(3)|ssl(3)>
+
+=head1 HISTORY
+
+The openssl(1) document appeared in OpenSSL 0.9.2.
+The B<list->I<XXX>B<-commands> pseudo-commands were added in OpenSSL 0.9.3;
+the B<no->I<XXX> pseudo-commands were added in OpenSSL 0.9.5a.
+For notes on the availability of other commands, see their individual
+manual pages.
+
+=cut
diff --git a/doc/apps/passwd.pod b/doc/apps/passwd.pod
new file mode 100644
index 000000000000..f44982549bf1
--- /dev/null
+++ b/doc/apps/passwd.pod
@@ -0,0 +1,82 @@
+=pod
+
+=head1 NAME
+
+passwd - compute password hashes
+
+=head1 SYNOPSIS
+
+B<openssl passwd>
+[B<-crypt>]
+[B<-1>]
+[B<-apr1>]
+[B<-salt> I<string>]
+[B<-in> I<file>]
+[B<-stdin>]
+[B<-noverify>]
+[B<-quiet>]
+[B<-table>]
+{I<password>}
+
+=head1 DESCRIPTION
+
+The B<passwd> command computes the hash of a password typed at
+run-time or the hash of each password in a list. The password list is
+taken from the named file for option B<-in file>, from stdin for
+option B<-stdin>, or from the command line, or from the terminal otherwise.
+The Unix standard algorithm B<crypt> and the MD5-based BSD password
+algorithm B<1> and its Apache variant B<apr1> are available.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-crypt>
+
+Use the B<crypt> algorithm (default).
+
+=item B<-1>
+
+Use the MD5 based BSD password algorithm B<1>.
+
+=item B<-apr1>
+
+Use the B<apr1> algorithm (Apache variant of the BSD algorithm).
+
+=item B<-salt> I<string>
+
+Use the specified salt.
+When reading a password from the terminal, this implies B<-noverify>.
+
+=item B<-in> I<file>
+
+Read passwords from I<file>.
+
+=item B<-stdin>
+
+Read passwords from B<stdin>.
+
+=item B<-noverify>
+
+Don't verify when reading a password from the terminal.
+
+=item B<-quiet>
+
+Don't output warnings when passwords given at the command line are truncated.
+
+=item B<-table>
+
+In the output list, prepend the cleartext password and a TAB character
+to each password hash.
+
+=back
+
+=head1 EXAMPLES
+
+B<openssl passwd -crypt -salt xx password> prints B<xxj31ZMTZzkVA>.
+
+B<openssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a.>.
+
+B<openssl passwd -apr1 -salt xxxxxxxx password> prints B<$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0>.
+
+=cut
diff --git a/doc/apps/pkcs12.pod b/doc/apps/pkcs12.pod
new file mode 100644
index 000000000000..7d84146293d2
--- /dev/null
+++ b/doc/apps/pkcs12.pod
@@ -0,0 +1,330 @@
+
+=pod
+
+=head1 NAME
+
+pkcs12 - PKCS#12 file utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkcs12>
+[B<-export>]
+[B<-chain>]
+[B<-inkey filename>]
+[B<-certfile filename>]
+[B<-name name>]
+[B<-caname name>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-nomacver>]
+[B<-nocerts>]
+[B<-clcerts>]
+[B<-cacerts>]
+[B<-nokeys>]
+[B<-info>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-nodes>]
+[B<-noiter>]
+[B<-maciter>]
+[B<-twopass>]
+[B<-descert>]
+[B<-certpbe>]
+[B<-keypbe>]
+[B<-keyex>]
+[B<-keysig>]
+[B<-password arg>]
+[B<-passin arg>]
+[B<-passout arg>]
+[B<-rand file(s)>]
+
+=head1 DESCRIPTION
+
+The B<pkcs12> command allows PKCS#12 files (sometimes referred to as
+PFX files) to be created and parsed. PKCS#12 files are used by several
+programs including Netscape, MSIE and MS Outlook.
+
+=head1 COMMAND OPTIONS
+
+There are a lot of options the meaning of some depends of whether a PKCS#12 file
+is being created or parsed. By default a PKCS#12 file is parsed a PKCS#12
+file can be created by using the B<-export> option (see below).
+
+=head1 PARSING OPTIONS
+
+=over 4
+
+=item B<-in filename>
+
+This specifies filename of the PKCS#12 file to be parsed. Standard input is used
+by default.
+
+=item B<-out filename>
+
+The filename to write certificates and private keys to, standard output by default.
+They are all written in PEM format.
+
+=item B<-pass arg>, B<-passin arg>
+
+the PKCS#12 file (i.e. input file) password source. For more information about the
+format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
+L<openssl(1)|openssl(1)>.
+
+=item B<-passout arg>
+
+pass phrase source to encrypt any outputed private keys with. For more information
+about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
+L<openssl(1)|openssl(1)>.
+
+=item B<-noout>
+
+this option inhibits output of the keys and certificates to the output file version
+of the PKCS#12 file.
+
+=item B<-clcerts>
+
+only output client certificates (not CA certificates).
+
+=item B<-cacerts>
+
+only output CA certificates (not client certificates).
+
+=item B<-nocerts>
+
+no certificates at all will be output.
+
+=item B<-nokeys>
+
+no private keys will be output.
+
+=item B<-info>
+
+output additional information about the PKCS#12 file structure, algorithms used and
+iteration counts.
+
+=item B<-des>
+
+use DES to encrypt private keys before outputting.
+
+=item B<-des3>
+
+use triple DES to encrypt private keys before outputting, this is the default.
+
+=item B<-idea>
+
+use IDEA to encrypt private keys before outputting.
+
+=item B<-nodes>
+
+don't encrypt the private keys at all.
+
+=item B<-nomacver>
+
+don't attempt to verify the integrity MAC before reading the file.
+
+=item B<-twopass>
+
+prompt for separate integrity and encryption passwords: most software
+always assumes these are the same so this option will render such
+PKCS#12 files unreadable.
+
+=back
+
+=head1 FILE CREATION OPTIONS
+
+=over 4
+
+=item B<-export>
+
+This option specifies that a PKCS#12 file will be created rather than
+parsed.
+
+=item B<-out filename>
+
+This specifies filename to write the PKCS#12 file to. Standard output is used
+by default.
+
+=item B<-in filename>
+
+The filename to read certificates and private keys from, standard input by default.
+They must all be in PEM format. The order doesn't matter but one private key and
+its corresponding certificate should be present. If additional certificates are
+present they will also be included in the PKCS#12 file.
+
+=item B<-inkey filename>
+
+file to read private key from. If not present then a private key must be present
+in the input file.
+
+=item B<-name friendlyname>
+
+This specifies the "friendly name" for the certificate and private key. This name
+is typically displayed in list boxes by software importing the file.
+
+=item B<-certfile filename>
+
+A filename to read additional certificates from.
+
+=item B<-caname friendlyname>
+
+This specifies the "friendly name" for other certificates. This option may be
+used multiple times to specify names for all certificates in the order they
+appear. Netscape ignores friendly names on other certificates whereas MSIE
+displays them.
+
+=item B<-pass arg>, B<-passout arg>
+
+the PKCS#12 file (i.e. output file) password source. For more information about
+the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
+L<openssl(1)|openssl(1)>.
+
+=item B<-passin password>
+
+pass phrase source to decrypt any input private keys with. For more information
+about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
+L<openssl(1)|openssl(1)>.
+
+=item B<-chain>
+
+if this option is present then an attempt is made to include the entire
+certificate chain of the user certificate. The standard CA store is used
+for this search. If the search fails it is considered a fatal error.
+
+=item B<-descert>
+
+encrypt the certificate using triple DES, this may render the PKCS#12
+file unreadable by some "export grade" software. By default the private
+key is encrypted using triple DES and the certificate using 40 bit RC2.
+
+=item B<-keypbe alg>, B<-certpbe alg>
+
+these options allow the algorithm used to encrypt the private key and
+certificates to be selected. Although any PKCS#5 v1.5 or PKCS#12 algorithms
+can be selected it is advisable only to use PKCS#12 algorithms. See the list
+in the B<NOTES> section for more information.
+
+=item B<-keyex|-keysig>
+
+specifies that the private key is to be used for key exchange or just signing.
+This option is only interpreted by MSIE and similar MS software. Normally
+"export grade" software will only allow 512 bit RSA keys to be used for
+encryption purposes but arbitrary length keys for signing. The B<-keysig>
+option marks the key for signing only. Signing only keys can be used for
+S/MIME signing, authenticode (ActiveX control signing) and SSL client
+authentication, however due to a bug only MSIE 5.0 and later support
+the use of signing only keys for SSL client authentication.
+
+=item B<-nomaciter>, B<-noiter>
+
+these options affect the iteration counts on the MAC and key algorithms.
+Unless you wish to produce files compatible with MSIE 4.0 you should leave
+these options alone.
+
+To discourage attacks by using large dictionaries of common passwords the
+algorithm that derives keys from passwords can have an iteration count applied
+to it: this causes a certain part of the algorithm to be repeated and slows it
+down. The MAC is used to check the file integrity but since it will normally
+have the same password as the keys and certificates it could also be attacked.
+By default both MAC and encryption iteration counts are set to 2048, using
+these options the MAC and encryption iteration counts can be set to 1, since
+this reduces the file security you should not use these options unless you
+really have to. Most software supports both MAC and key iteration counts.
+MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter>
+option.
+
+=item B<-maciter>
+
+This option is included for compatibility with previous versions, it used
+to be needed to use MAC iterations counts but they are now used by default.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=back
+
+=head1 NOTES
+
+Although there are a large number of options most of them are very rarely
+used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used
+for PKCS#12 file creation B<-export> and B<-name> are also used.
+
+If none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present
+then all certificates will be output in the order they appear in the input
+PKCS#12 files. There is no guarantee that the first certificate present is
+the one corresponding to the private key. Certain software which requires
+a private key and certificate and assumes the first certificate in the
+file is the one corresponding to the private key: this may not always
+be the case. Using the B<-clcerts> option will solve this problem by only
+outputting the certificate corresponding to the private key. If the CA
+certificates are required then they can be output to a separate file using
+the B<-nokeys -cacerts> options to just output CA certificates.
+
+The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption
+algorithms for private keys and certificates to be specified. Normally
+the defaults are fine but occasionally software can't handle triple DES
+encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can
+be used to reduce the private key encryption to 40 bit RC2. A complete
+description of all algorithms is contained in the B<pkcs8> manual page.
+
+=head1 EXAMPLES
+
+Parse a PKCS#12 file and output it to a file:
+
+ openssl pkcs12 -in file.p12 -out file.pem
+
+Output only client certificates to a file:
+
+ openssl pkcs12 -in file.p12 -clcerts -out file.pem
+
+Don't encrypt the private key:
+
+ openssl pkcs12 -in file.p12 -out file.pem -nodes
+
+Print some info about a PKCS#12 file:
+
+ openssl pkcs12 -in file.p12 -info -noout
+
+Create a PKCS#12 file:
+
+ openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate"
+
+Include some extra certificates:
+
+ openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \
+ -certfile othercerts.pem
+
+=head1 BUGS
+
+Some would argue that the PKCS#12 standard is one big bug :-)
+
+Versions of OpenSSL before 0.9.6a had a bug in the PKCS#12 key generation
+routines. Under rare circumstances this could produce a PKCS#12 file encrypted
+with an invalid key. As a result some PKCS#12 files which triggered this bug
+from other implementations (MSIE or Netscape) could not be decrypted
+by OpenSSL and similarly OpenSSL could produce PKCS#12 files which could
+not be decrypted by other implementations. The chances of producing such
+a file are relatively small: less than 1 in 256.
+
+A side effect of fixing this bug is that any old invalidly encrypted PKCS#12
+files cannot no longer be parsed by the fixed version. Under such circumstances
+the B<pkcs12> utility will report that the MAC is OK but fail with a decryption
+error when extracting private keys.
+
+This problem can be resolved by extracting the private keys and certificates
+from the PKCS#12 file using an older version of OpenSSL and recreating the PKCS#12
+file from the keys and certificates using a newer version of OpenSSL. For example:
+
+ old-openssl -in bad.p12 -out keycerts.pem
+ openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12
+
+=head1 SEE ALSO
+
+L<pkcs8(1)|pkcs8(1)>
+
diff --git a/doc/apps/pkcs7.pod b/doc/apps/pkcs7.pod
new file mode 100644
index 000000000000..a0a636328b59
--- /dev/null
+++ b/doc/apps/pkcs7.pod
@@ -0,0 +1,105 @@
+=pod
+
+=head1 NAME
+
+pkcs7 - PKCS#7 utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkcs7>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-print_certs>]
+[B<-text>]
+[B<-noout>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<pkcs7> command processes PKCS#7 files in DER or PEM format.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. B<DER> format is DER encoded PKCS#7
+v1.5 structure.B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read from or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-print_certs>
+
+prints out any certificates or CRLs contained in the file. They are
+preceded by their subject and issuer names in one line format.
+
+=item B<-text>
+
+prints out certificates details in full rather than just subject and
+issuer names.
+
+=item B<-noout>
+
+don't output the encoded version of the PKCS#7 structure (or certificates
+is B<-print_certs> is set).
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 EXAMPLES
+
+Convert a PKCS#7 file from PEM to DER:
+
+ openssl pkcs7 -in file.pem -outform DER -out file.der
+
+Output all certificates in a file:
+
+ openssl pkcs7 -in file.pem -print_certs -out certs.pem
+
+=head1 NOTES
+
+The PEM PKCS#7 format uses the header and footer lines:
+
+ -----BEGIN PKCS7-----
+ -----END PKCS7-----
+
+For compatibility with some CAs it will also accept:
+
+ -----BEGIN CERTIFICATE-----
+ -----END CERTIFICATE-----
+
+=head1 RESTRICTIONS
+
+There is no option to print out all the fields of a PKCS#7 file.
+
+This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they
+cannot currently parse, for example, the new CMS as described in RFC2630.
+
+=head1 SEE ALSO
+
+L<crl2pkcs7(1)|crl2pkcs7(1)>
+
+=cut
diff --git a/doc/apps/pkcs8.pod b/doc/apps/pkcs8.pod
new file mode 100644
index 000000000000..68ecd65b1019
--- /dev/null
+++ b/doc/apps/pkcs8.pod
@@ -0,0 +1,243 @@
+=pod
+
+=head1 NAME
+
+pkcs8 - PKCS#8 format private key conversion tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkcs8>
+[B<-topk8>]
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin arg>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-noiter>]
+[B<-nocrypt>]
+[B<-nooct>]
+[B<-embed>]
+[B<-nsdb>]
+[B<-v2 alg>]
+[B<-v1 alg>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<pkcs8> command processes private keys in PKCS#8 format. It can handle
+both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
+format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-topk8>
+
+Normally a PKCS#8 private key is expected on input and a traditional format
+private key will be written. With the B<-topk8> option the situation is
+reversed: it reads a traditional format private key and writes a PKCS#8
+format key.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. If a PKCS#8 format key is expected on input
+then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be
+expected. Otherwise the B<DER> or B<PEM> format of the traditional format
+private key is used.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin arg>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output by
+default. If any encryption options are set then a pass phrase will be
+prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout arg>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-nocrypt>
+
+PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
+structures using an appropriate password based encryption algorithm. With
+this option an unencrypted PrivateKeyInfo structure is expected or output.
+This option does not encrypt private keys at all and should only be used
+when absolutely necessary. Certain software such as some versions of Java
+code signing software used unencrypted private keys.
+
+=item B<-nooct>
+
+This option generates RSA private keys in a broken format that some software
+uses. Specifically the private key should be enclosed in a OCTET STRING
+but some software just includes the structure itself without the
+surrounding OCTET STRING.
+
+=item B<-embed>
+
+This option generates DSA keys in a broken format. The DSA parameters are
+embedded inside the PrivateKey structure. In this form the OCTET STRING
+contains an ASN1 SEQUENCE consisting of two structures: a SEQUENCE containing
+the parameters and an ASN1 INTEGER containing the private key.
+
+=item B<-nsdb>
+
+This option generates DSA keys in a broken format compatible with Netscape
+private key databases. The PrivateKey contains a SEQUENCE consisting of
+the public and private keys respectively.
+
+=item B<-v2 alg>
+
+This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8
+private keys are encrypted with the password based encryption algorithm
+called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it
+was the strongest encryption algorithm supported in PKCS#5 v1.5. Using
+the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any
+encryption algorithm such as 168 bit triple DES or 128 bit RC2 however
+not many implementations support PKCS#5 v2.0 yet. If you are just using
+private keys with OpenSSL then this doesn't matter.
+
+The B<alg> argument is the encryption algorithm to use, valid values include
+B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used.
+
+=item B<-v1 alg>
+
+This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
+list of possible algorithms is included below.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 NOTES
+
+The encrypted form of a PEM encode PKCS#8 files uses the following
+headers and footers:
+
+ -----BEGIN ENCRYPTED PRIVATE KEY-----
+ -----END ENCRYPTED PRIVATE KEY-----
+
+The unencrypted form uses:
+
+ -----BEGIN PRIVATE KEY-----
+ -----END PRIVATE KEY-----
+
+Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
+counts are more secure that those encrypted using the traditional
+SSLeay compatible formats. So if additional security is considered
+important the keys should be converted.
+
+The default encryption is only 56 bits because this is the encryption
+that most current implementations of PKCS#8 will support.
+
+Some software may use PKCS#12 password based encryption algorithms
+with PKCS#8 format private keys: these are handled automatically
+but there is no option to produce them.
+
+It is possible to write out DER encoded encrypted private keys in
+PKCS#8 format because the encryption details are included at an ASN1
+level whereas the traditional format includes them at a PEM level.
+
+=head1 PKCS#5 v1.5 and PKCS#12 algorithms.
+
+Various algorithms can be used with the B<-v1> command line option,
+including PKCS#5 v1.5 and PKCS#12. These are described in more detail
+below.
+
+=over 4
+
+=item B<PBE-MD2-DES PBE-MD5-DES>
+
+These algorithms were included in the original PKCS#5 v1.5 specification.
+They only offer 56 bits of protection since they both use DES.
+
+=item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES>
+
+These algorithms are not mentioned in the original PKCS#5 v1.5 specification
+but they use the same key derivation algorithm and are supported by some
+software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or
+56 bit DES.
+
+=item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40>
+
+These algorithms use the PKCS#12 password based encryption algorithm and
+allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
+
+=back
+
+=head1 EXAMPLES
+
+Convert a private from traditional to PKCS#5 v2.0 format using triple
+DES:
+
+ openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
+
+Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
+(DES):
+
+ openssl pkcs8 -in key.pem -topk8 -out enckey.pem
+
+Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
+(3DES):
+
+ openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
+
+Read a DER unencrypted PKCS#8 format private key:
+
+ openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
+
+Convert a private key from any PKCS#8 format to traditional format:
+
+ openssl pkcs8 -in pk8.pem -out key.pem
+
+=head1 STANDARDS
+
+Test vectors from this PKCS#5 v2.0 implementation were posted to the
+pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
+counts, several people confirmed that they could decrypt the private
+keys produced and Therefore it can be assumed that the PKCS#5 v2.0
+implementation is reasonably accurate at least as far as these
+algorithms are concerned.
+
+The format of PKCS#8 DSA (and other) private keys is not well documented:
+it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
+PKCS#8 private key format complies with this standard.
+
+=head1 BUGS
+
+There should be an option that prints out the encryption algorithm
+in use and other details such as the iteration count.
+
+PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
+key format for OpenSSL: for compatibility several of the utilities use
+the old format at present.
+
+=head1 SEE ALSO
+
+L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>,
+L<gendsa(1)|gendsa(1)>
+
+=cut
diff --git a/doc/apps/rand.pod b/doc/apps/rand.pod
new file mode 100644
index 000000000000..75745ca0023c
--- /dev/null
+++ b/doc/apps/rand.pod
@@ -0,0 +1,50 @@
+=pod
+
+=head1 NAME
+
+rand - generate pseudo-random bytes
+
+=head1 SYNOPSIS
+
+B<openssl rand>
+[B<-out> I<file>]
+[B<-rand> I<file(s)>]
+[B<-base64>]
+I<num>
+
+=head1 DESCRIPTION
+
+The B<rand> command outputs I<num> pseudo-random bytes after seeding
+the random number generator once. As in other B<openssl> command
+line tools, PRNG seeding uses the file I<$HOME/>B<.rnd> or B<.rnd>
+in addition to the files given in the B<-rand> option. A new
+I<$HOME>/B<.rnd> or B<.rnd> file will be written back if enough
+seeding was obtained from these sources.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-out> I<file>
+
+Write to I<file> instead of standard output.
+
+=item B<-rand> I<file(s)>
+
+Use specified file or files or EGD socket (see L<RAND_egd(3)|RAND_egd(3)>)
+for seeding the random number generator.
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-base64>
+
+Perform base64 encoding on the output.
+
+=back
+
+=head1 SEE ALSO
+
+L<RAND_bytes(3)|RAND_bytes(3)>
+
+=cut
diff --git a/doc/apps/req.pod b/doc/apps/req.pod
new file mode 100644
index 000000000000..82b565c9d4f3
--- /dev/null
+++ b/doc/apps/req.pod
@@ -0,0 +1,611 @@
+
+=pod
+
+=head1 NAME
+
+req - PKCS#10 certificate request and certificate generating utility.
+
+=head1 SYNOPSIS
+
+B<openssl> B<req>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin arg>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-text>]
+[B<-pubkey>]
+[B<-noout>]
+[B<-verify>]
+[B<-modulus>]
+[B<-new>]
+[B<-rand file(s)>]
+[B<-newkey rsa:bits>]
+[B<-newkey dsa:file>]
+[B<-nodes>]
+[B<-key filename>]
+[B<-keyform PEM|DER>]
+[B<-keyout filename>]
+[B<-[md5|sha1|md2|mdc2]>]
+[B<-config filename>]
+[B<-subj arg>]
+[B<-multivalue-rdn>]
+[B<-x509>]
+[B<-days n>]
+[B<-set_serial n>]
+[B<-asn1-kludge>]
+[B<-newhdr>]
+[B<-extensions section>]
+[B<-reqexts section>]
+[B<-utf8>]
+[B<-nameopt>]
+[B<-batch>]
+[B<-verbose>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<req> command primarily creates and processes certificate requests
+in PKCS#10 format. It can additionally create self signed certificates
+for use as root CAs for example.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with the PKCS#10. The B<PEM> form is the default format: it
+consists of the B<DER> format base64 encoded with additional header and
+footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a request from or standard input
+if this option is not specified. A request is only read if the creation
+options (B<-new> and B<-newkey>) are not specified.
+
+=item B<-passin arg>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-out filename>
+
+This specifies the output filename to write to or standard output by
+default.
+
+=item B<-passout arg>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-text>
+
+prints out the certificate request in text form.
+
+=item B<-pubkey>
+
+outputs the public key.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the request.
+
+=item B<-modulus>
+
+this option prints out the value of the modulus of the public key
+contained in the request.
+
+=item B<-verify>
+
+verifies the signature on the request.
+
+=item B<-new>
+
+this option generates a new certificate request. It will prompt
+the user for the relevant field values. The actual fields
+prompted for and their maximum and minimum sizes are specified
+in the configuration file and any requested extensions.
+
+If the B<-key> option is not used it will generate a new RSA private
+key using information specified in the configuration file.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-newkey arg>
+
+this option creates a new certificate request and a new private
+key. The argument takes one of two forms. B<rsa:nbits>, where
+B<nbits> is the number of bits, generates an RSA key B<nbits>
+in size. B<dsa:filename> generates a DSA key using the parameters
+in the file B<filename>.
+
+=item B<-key filename>
+
+This specifies the file to read the private key from. It also
+accepts PKCS#8 format private keys for PEM format files.
+
+=item B<-keyform PEM|DER>
+
+the format of the private key file specified in the B<-key>
+argument. PEM is the default.
+
+=item B<-keyout filename>
+
+this gives the filename to write the newly created private key to.
+If this option is not specified then the filename present in the
+configuration file is used.
+
+=item B<-nodes>
+
+if this option is specified then if a private key is created it
+will not be encrypted.
+
+=item B<-[md5|sha1|md2|mdc2]>
+
+this specifies the message digest to sign the request with. This
+overrides the digest algorithm specified in the configuration file.
+This option is ignored for DSA requests: they always use SHA1.
+
+=item B<-config filename>
+
+this allows an alternative configuration file to be specified,
+this overrides the compile time filename or any specified in
+the B<OPENSSL_CONF> environment variable.
+
+=item B<-subj arg>
+
+sets subject name for new request or supersedes the subject name
+when processing a request.
+The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
+characters may be escaped by \ (backslash), no spaces are skipped.
+
+=item B<-multivalue-rdn>
+
+this option causes the -subj argument to be interpreted with full
+support for multivalued RDNs. Example:
+
+I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
+
+If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
+
+=item B<-x509>
+
+this option outputs a self signed certificate instead of a certificate
+request. This is typically used to generate a test certificate or
+a self signed root CA. The extensions added to the certificate
+(if any) are specified in the configuration file. Unless specified
+using the B<set_serial> option B<0> will be used for the serial
+number.
+
+=item B<-days n>
+
+when the B<-x509> option is being used this specifies the number of
+days to certify the certificate for. The default is 30 days.
+
+=item B<-set_serial n>
+
+serial number to use when outputting a self signed certificate. This
+may be specified as a decimal value or a hex value if preceded by B<0x>.
+It is possible to use negative serial numbers but this is not recommended.
+
+=item B<-extensions section>
+
+=item B<-reqexts section>
+
+these options specify alternative sections to include certificate
+extensions (if the B<-x509> option is present) or certificate
+request extensions. This allows several different sections to
+be used in the same configuration file to specify requests for
+a variety of purposes.
+
+=item B<-utf8>
+
+this option causes field values to be interpreted as UTF8 strings, by
+default they are interpreted as ASCII. This means that the field
+values, whether prompted from a terminal or obtained from a
+configuration file, must be valid UTF8 strings.
+
+=item B<-nameopt option>
+
+option which determines how the subject or issuer names are displayed. The
+B<option> argument can be a single option or multiple options separated by
+commas. Alternatively the B<-nameopt> switch may be used more than once to
+set multiple options. See the L<x509(1)|x509(1)> manual page for details.
+
+=item B<-asn1-kludge>
+
+by default the B<req> command outputs certificate requests containing
+no attributes in the correct PKCS#10 format. However certain CAs will only
+accept requests containing no attributes in an invalid form: this
+option produces this invalid format.
+
+More precisely the B<Attributes> in a PKCS#10 certificate request
+are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so
+if no attributes are present then they should be encoded as an
+empty B<SET OF>. The invalid form does not include the empty
+B<SET OF> whereas the correct form does.
+
+It should be noted that very few CAs still require the use of this option.
+
+=item B<-newhdr>
+
+Adds the word B<NEW> to the PEM file header and footer lines on the outputed
+request. Some software (Netscape certificate server) and some CAs need this.
+
+=item B<-batch>
+
+non-interactive mode.
+
+=item B<-verbose>
+
+print extra details about the operations being performed.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 CONFIGURATION FILE FORMAT
+
+The configuration options are specified in the B<req> section of
+the configuration file. As with all configuration files if no
+value is specified in the specific section (i.e. B<req>) then
+the initial unnamed or B<default> section is searched too.
+
+The options available are described in detail below.
+
+=over 4
+
+=item B<input_password output_password>
+
+The passwords for the input private key file (if present) and
+the output private key file (if one will be created). The
+command line options B<passin> and B<passout> override the
+configuration file values.
+
+=item B<default_bits>
+
+This specifies the default key size in bits. If not specified then
+512 is used. It is used if the B<-new> option is used. It can be
+overridden by using the B<-newkey> option.
+
+=item B<default_keyfile>
+
+This is the default filename to write a private key to. If not
+specified the key is written to standard output. This can be
+overridden by the B<-keyout> option.
+
+=item B<oid_file>
+
+This specifies a file containing additional B<OBJECT IDENTIFIERS>.
+Each line of the file should consist of the numerical form of the
+object identifier followed by white space then the short name followed
+by white space and finally the long name.
+
+=item B<oid_section>
+
+This specifies a section in the configuration file containing extra
+object identifiers. Each line should consist of the short name of the
+object identifier followed by B<=> and the numerical form. The short
+and long names are the same when this option is used.
+
+=item B<RANDFILE>
+
+This specifies a filename in which random number seed information is
+placed and read from, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+It is used for private key generation.
+
+=item B<encrypt_key>
+
+If this is set to B<no> then if a private key is generated it is
+B<not> encrypted. This is equivalent to the B<-nodes> command line
+option. For compatibility B<encrypt_rsa_key> is an equivalent option.
+
+=item B<default_md>
+
+This option specifies the digest algorithm to use. Possible values
+include B<md5 sha1 mdc2>. If not present then MD5 is used. This
+option can be overridden on the command line.
+
+=item B<string_mask>
+
+This option masks out the use of certain string types in certain
+fields. Most users will not need to change this option.
+
+It can be set to several values B<default> which is also the default
+option uses PrintableStrings, T61Strings and BMPStrings if the
+B<pkix> value is used then only PrintableStrings and BMPStrings will
+be used. This follows the PKIX recommendation in RFC2459. If the
+B<utf8only> option is used then only UTF8Strings will be used: this
+is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
+option just uses PrintableStrings and T61Strings: certain software has
+problems with BMPStrings and UTF8Strings: in particular Netscape.
+
+=item B<req_extensions>
+
+this specifies the configuration file section containing a list of
+extensions to add to the certificate request. It can be overridden
+by the B<-reqexts> command line switch.
+
+=item B<x509_extensions>
+
+this specifies the configuration file section containing a list of
+extensions to add to certificate generated when the B<-x509> switch
+is used. It can be overridden by the B<-extensions> command line switch.
+
+=item B<prompt>
+
+if set to the value B<no> this disables prompting of certificate fields
+and just takes values from the config file directly. It also changes the
+expected format of the B<distinguished_name> and B<attributes> sections.
+
+=item B<utf8>
+
+if set to the value B<yes> then field values to be interpreted as UTF8
+strings, by default they are interpreted as ASCII. This means that
+the field values, whether prompted from a terminal or obtained from a
+configuration file, must be valid UTF8 strings.
+
+=item B<attributes>
+
+this specifies the section containing any request attributes: its format
+is the same as B<distinguished_name>. Typically these may contain the
+challengePassword or unstructuredName types. They are currently ignored
+by OpenSSL's request signing utilities but some CAs might want them.
+
+=item B<distinguished_name>
+
+This specifies the section containing the distinguished name fields to
+prompt for when generating a certificate or certificate request. The format
+is described in the next section.
+
+=back
+
+=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
+
+There are two separate formats for the distinguished name and attribute
+sections. If the B<prompt> option is set to B<no> then these sections
+just consist of field names and values: for example,
+
+ CN=My Name
+ OU=My Organization
+ emailAddress=someone@somewhere.org
+
+This allows external programs (e.g. GUI based) to generate a template file
+with all the field names and values and just pass it to B<req>. An example
+of this kind of configuration file is contained in the B<EXAMPLES> section.
+
+Alternatively if the B<prompt> option is absent or not set to B<no> then the
+file contains field prompting information. It consists of lines of the form:
+
+ fieldName="prompt"
+ fieldName_default="default field value"
+ fieldName_min= 2
+ fieldName_max= 4
+
+"fieldName" is the field name being used, for example commonName (or CN).
+The "prompt" string is used to ask the user to enter the relevant
+details. If the user enters nothing then the default value is used if no
+default value is present then the field is omitted. A field can
+still be omitted if a default value is present if the user just
+enters the '.' character.
+
+The number of characters entered must be between the fieldName_min and
+fieldName_max limits: there may be additional restrictions based
+on the field being used (for example countryName can only ever be
+two characters long and must fit in a PrintableString).
+
+Some fields (such as organizationName) can be used more than once
+in a DN. This presents a problem because configuration files will
+not recognize the same name occurring twice. To avoid this problem
+if the fieldName contains some characters followed by a full stop
+they will be ignored. So for example a second organizationName can
+be input by calling it "1.organizationName".
+
+The actual permitted field names are any object identifier short or
+long names. These are compiled into OpenSSL and include the usual
+values such as commonName, countryName, localityName, organizationName,
+organizationUnitName, stateOrProvinceName. Additionally emailAddress
+is include as well as name, surname, givenName initials and dnQualifier.
+
+Additional object identifiers can be defined with the B<oid_file> or
+B<oid_section> options in the configuration file. Any additional fields
+will be treated as though they were a DirectoryString.
+
+
+=head1 EXAMPLES
+
+Examine and verify certificate request:
+
+ openssl req -in req.pem -text -verify -noout
+
+Create a private key and then generate a certificate request from it:
+
+ openssl genrsa -out key.pem 1024
+ openssl req -new -key key.pem -out req.pem
+
+The same but just using req:
+
+ openssl req -newkey rsa:1024 -keyout key.pem -out req.pem
+
+Generate a self signed root certificate:
+
+ openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem
+
+Example of a file pointed to by the B<oid_file> option:
+
+ 1.2.3.4 shortName A longer Name
+ 1.2.3.6 otherName Other longer Name
+
+Example of a section pointed to by B<oid_section> making use of variable
+expansion:
+
+ testoid1=1.2.3.5
+ testoid2=${testoid1}.6
+
+Sample configuration file prompting for field values:
+
+ [ req ]
+ default_bits = 1024
+ default_keyfile = privkey.pem
+ distinguished_name = req_distinguished_name
+ attributes = req_attributes
+ x509_extensions = v3_ca
+
+ dirstring_type = nobmp
+
+ [ req_distinguished_name ]
+ countryName = Country Name (2 letter code)
+ countryName_default = AU
+ countryName_min = 2
+ countryName_max = 2
+
+ localityName = Locality Name (eg, city)
+
+ organizationalUnitName = Organizational Unit Name (eg, section)
+
+ commonName = Common Name (eg, YOUR name)
+ commonName_max = 64
+
+ emailAddress = Email Address
+ emailAddress_max = 40
+
+ [ req_attributes ]
+ challengePassword = A challenge password
+ challengePassword_min = 4
+ challengePassword_max = 20
+
+ [ v3_ca ]
+
+ subjectKeyIdentifier=hash
+ authorityKeyIdentifier=keyid:always,issuer:always
+ basicConstraints = CA:true
+
+Sample configuration containing all field values:
+
+
+ RANDFILE = $ENV::HOME/.rnd
+
+ [ req ]
+ default_bits = 1024
+ default_keyfile = keyfile.pem
+ distinguished_name = req_distinguished_name
+ attributes = req_attributes
+ prompt = no
+ output_password = mypass
+
+ [ req_distinguished_name ]
+ C = GB
+ ST = Test State or Province
+ L = Test Locality
+ O = Organization Name
+ OU = Organizational Unit Name
+ CN = Common Name
+ emailAddress = test@email.address
+
+ [ req_attributes ]
+ challengePassword = A challenge password
+
+
+=head1 NOTES
+
+The header and footer lines in the B<PEM> format are normally:
+
+ -----BEGIN CERTIFICATE REQUEST-----
+ -----END CERTIFICATE REQUEST-----
+
+some software (some versions of Netscape certificate server) instead needs:
+
+ -----BEGIN NEW CERTIFICATE REQUEST-----
+ -----END NEW CERTIFICATE REQUEST-----
+
+which is produced with the B<-newhdr> option but is otherwise compatible.
+Either form is accepted transparently on input.
+
+The certificate requests generated by B<Xenroll> with MSIE have extensions
+added. It includes the B<keyUsage> extension which determines the type of
+key (signature only or general purpose) and any additional OIDs entered
+by the script in an extendedKeyUsage extension.
+
+=head1 DIAGNOSTICS
+
+The following messages are frequently asked about:
+
+ Using configuration from /some/path/openssl.cnf
+ Unable to load config info
+
+This is followed some time later by...
+
+ unable to find 'distinguished_name' in config
+ problems making Certificate Request
+
+The first error message is the clue: it can't find the configuration
+file! Certain operations (like examining a certificate request) don't
+need a configuration file so its use isn't enforced. Generation of
+certificates or requests however does need a configuration file. This
+could be regarded as a bug.
+
+Another puzzling message is this:
+
+ Attributes:
+ a0:00
+
+this is displayed when no attributes are present and the request includes
+the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
+0x00). If you just see:
+
+ Attributes:
+
+then the B<SET OF> is missing and the encoding is technically invalid (but
+it is tolerated). See the description of the command line option B<-asn1-kludge>
+for more information.
+
+=head1 ENVIRONMENT VARIABLES
+
+The variable B<OPENSSL_CONF> if defined allows an alternative configuration
+file location to be specified, it will be overridden by the B<-config> command
+line switch if it is present. For compatibility reasons the B<SSLEAY_CONF>
+environment variable serves the same purpose but its use is discouraged.
+
+=head1 BUGS
+
+OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
+treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
+This can cause problems if you need characters that aren't available in
+PrintableStrings and you don't want to or can't use BMPStrings.
+
+As a consequence of the T61String handling the only correct way to represent
+accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
+currently chokes on these. If you have to use accented characters with Netscape
+and MSIE then you currently need to use the invalid T61String form.
+
+The current prompting is not very friendly. It doesn't allow you to confirm what
+you've just entered. Other things like extensions in certificate requests are
+statically defined in the configuration file. Some of these: like an email
+address in subjectAltName should be input by the user.
+
+=head1 SEE ALSO
+
+L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
+L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>
+
+=cut
diff --git a/doc/apps/rsa.pod b/doc/apps/rsa.pod
new file mode 100644
index 000000000000..4d7640995ede
--- /dev/null
+++ b/doc/apps/rsa.pod
@@ -0,0 +1,189 @@
+
+=pod
+
+=head1 NAME
+
+rsa - RSA key processing tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<rsa>
+[B<-inform PEM|NET|DER>]
+[B<-outform PEM|NET|DER>]
+[B<-in filename>]
+[B<-passin arg>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-sgckey>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-text>]
+[B<-noout>]
+[B<-modulus>]
+[B<-check>]
+[B<-pubin>]
+[B<-pubout>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<rsa> command processes RSA keys. They can be converted between various
+forms and their components printed out. B<Note> this command uses the
+traditional SSLeay compatible format for private key encryption: newer
+applications should use the more secure PKCS#8 format using the B<pkcs8>
+utility.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|NET|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format.
+The B<PEM> form is the default format: it consists of the B<DER> format base64
+encoded with additional header and footer lines. On input PKCS#8 format private
+keys are also accepted. The B<NET> form is a format is described in the B<NOTES>
+section.
+
+=item B<-outform DER|NET|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin arg>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output if this
+option is not specified. If any encryption options are set then a pass phrase
+will be prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout password>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-sgckey>
+
+use the modified NET algorithm used with some versions of Microsoft IIS and SGC
+keys.
+
+=item B<-des|-des3|-idea>
+
+These options encrypt the private key with the DES, triple DES, or the
+IDEA ciphers respectively before outputting it. A pass phrase is prompted for.
+If none of these options is specified the key is written in plain text. This
+means that using the B<rsa> utility to read in an encrypted key with no
+encryption option can be used to remove the pass phrase from a key, or by
+setting the encryption options it can be use to add or change the pass phrase.
+These options can only be used with PEM format output files.
+
+=item B<-text>
+
+prints out the various public or private key components in
+plain text in addition to the encoded version.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the key.
+
+=item B<-modulus>
+
+this option prints out the value of the modulus of the key.
+
+=item B<-check>
+
+this option checks the consistency of an RSA private key.
+
+=item B<-pubin>
+
+by default a private key is read from the input file: with this
+option a public key is read instead.
+
+=item B<-pubout>
+
+by default a private key is output: with this option a public
+key will be output instead. This option is automatically set if
+the input is a public key.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 NOTES
+
+The PEM private key format uses the header and footer lines:
+
+ -----BEGIN RSA PRIVATE KEY-----
+ -----END RSA PRIVATE KEY-----
+
+The PEM public key format uses the header and footer lines:
+
+ -----BEGIN PUBLIC KEY-----
+ -----END PUBLIC KEY-----
+
+The B<NET> form is a format compatible with older Netscape servers
+and Microsoft IIS .key files, this uses unsalted RC4 for its encryption.
+It is not very secure and so should only be used when necessary.
+
+Some newer version of IIS have additional data in the exported .key
+files. To use these with the utility, view the file with a binary editor
+and look for the string "private-key", then trace back to the byte
+sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). Copy all the data
+from this point onwards to another file and use that as the input
+to the B<rsa> utility with the B<-inform NET> option. If you get
+an error after entering the password try the B<-sgckey> option.
+
+=head1 EXAMPLES
+
+To remove the pass phrase on an RSA private key:
+
+ openssl rsa -in key.pem -out keyout.pem
+
+To encrypt a private key using triple DES:
+
+ openssl rsa -in key.pem -des3 -out keyout.pem
+
+To convert a private key from PEM to DER format:
+
+ openssl rsa -in key.pem -outform DER -out keyout.der
+
+To print out the components of a private key to standard output:
+
+ openssl rsa -in key.pem -text -noout
+
+To just output the public part of a private key:
+
+ openssl rsa -in key.pem -pubout -out pubkey.pem
+
+=head1 BUGS
+
+The command line password arguments don't currently work with
+B<NET> format.
+
+There should be an option that automatically handles .key files,
+without having to manually edit them.
+
+=head1 SEE ALSO
+
+L<pkcs8(1)|pkcs8(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>,
+L<gendsa(1)|gendsa(1)>
+
+=cut
diff --git a/doc/apps/rsautl.pod b/doc/apps/rsautl.pod
new file mode 100644
index 000000000000..a7c1681d9859
--- /dev/null
+++ b/doc/apps/rsautl.pod
@@ -0,0 +1,183 @@
+=pod
+
+=head1 NAME
+
+rsautl - RSA utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<rsautl>
+[B<-in file>]
+[B<-out file>]
+[B<-inkey file>]
+[B<-pubin>]
+[B<-certin>]
+[B<-sign>]
+[B<-verify>]
+[B<-encrypt>]
+[B<-decrypt>]
+[B<-pkcs>]
+[B<-ssl>]
+[B<-raw>]
+[B<-hexdump>]
+[B<-asn1parse>]
+
+=head1 DESCRIPTION
+
+The B<rsautl> command can be used to sign, verify, encrypt and decrypt
+data using the RSA algorithm.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-in filename>
+
+This specifies the input filename to read data from or standard input
+if this option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-inkey file>
+
+the input key file, by default it should be an RSA private key.
+
+=item B<-pubin>
+
+the input file is an RSA public key.
+
+=item B<-certin>
+
+the input is a certificate containing an RSA public key.
+
+=item B<-sign>
+
+sign the input data and output the signed result. This requires
+and RSA private key.
+
+=item B<-verify>
+
+verify the input data and output the recovered data.
+
+=item B<-encrypt>
+
+encrypt the input data using an RSA public key.
+
+=item B<-decrypt>
+
+decrypt the input data using an RSA private key.
+
+=item B<-pkcs, -oaep, -ssl, -raw>
+
+the padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP,
+special padding used in SSL v2 backwards compatible handshakes,
+or no padding, respectively.
+For signatures, only B<-pkcs> and B<-raw> can be used.
+
+=item B<-hexdump>
+
+hex dump the output data.
+
+=item B<-asn1parse>
+
+asn1parse the output data, this is useful when combined with the
+B<-verify> option.
+
+=back
+
+=head1 NOTES
+
+B<rsautl> because it uses the RSA algorithm directly can only be
+used to sign or verify small pieces of data.
+
+=head1 EXAMPLES
+
+Sign some data using a private key:
+
+ openssl rsautl -sign -in file -inkey key.pem -out sig
+
+Recover the signed data
+
+ openssl rsautl -verify -in sig -inkey key.pem
+
+Examine the raw signed data:
+
+ openssl rsautl -verify -in file -inkey key.pem -raw -hexdump
+
+ 0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world
+
+The PKCS#1 block formatting is evident from this. If this was done using
+encrypt and decrypt the block would have been of type 2 (the second byte)
+and random padding data visible instead of the 0xff bytes.
+
+It is possible to analyse the signature of certificates using this
+utility in conjunction with B<asn1parse>. Consider the self signed
+example in certs/pca-cert.pem . Running B<asn1parse> as follows yields:
+
+ openssl asn1parse -in pca-cert.pem
+
+ 0:d=0 hl=4 l= 742 cons: SEQUENCE
+ 4:d=1 hl=4 l= 591 cons: SEQUENCE
+ 8:d=2 hl=2 l= 3 cons: cont [ 0 ]
+ 10:d=3 hl=2 l= 1 prim: INTEGER :02
+ 13:d=2 hl=2 l= 1 prim: INTEGER :00
+ 16:d=2 hl=2 l= 13 cons: SEQUENCE
+ 18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
+ 29:d=3 hl=2 l= 0 prim: NULL
+ 31:d=2 hl=2 l= 92 cons: SEQUENCE
+ 33:d=3 hl=2 l= 11 cons: SET
+ 35:d=4 hl=2 l= 9 cons: SEQUENCE
+ 37:d=5 hl=2 l= 3 prim: OBJECT :countryName
+ 42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU
+ ....
+ 599:d=1 hl=2 l= 13 cons: SEQUENCE
+ 601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
+ 612:d=2 hl=2 l= 0 prim: NULL
+ 614:d=1 hl=3 l= 129 prim: BIT STRING
+
+
+The final BIT STRING contains the actual signature. It can be extracted with:
+
+ openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
+
+The certificate public key can be extracted with:
+
+ openssl x509 -in test/testx509.pem -pubout -noout >pubkey.pem
+
+The signature can be analysed with:
+
+ openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
+
+ 0:d=0 hl=2 l= 32 cons: SEQUENCE
+ 2:d=1 hl=2 l= 12 cons: SEQUENCE
+ 4:d=2 hl=2 l= 8 prim: OBJECT :md5
+ 14:d=2 hl=2 l= 0 prim: NULL
+ 16:d=1 hl=2 l= 16 prim: OCTET STRING
+ 0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%..
+
+This is the parsed version of an ASN1 DigestInfo structure. It can be seen that
+the digest used was md5. The actual part of the certificate that was signed can
+be extracted with:
+
+ openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
+
+and its digest computed with:
+
+ openssl md5 -c tbs
+ MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
+
+which it can be seen agrees with the recovered value above.
+
+=head1 SEE ALSO
+
+L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>
diff --git a/doc/apps/s_client.pod b/doc/apps/s_client.pod
new file mode 100644
index 000000000000..c17a83a22581
--- /dev/null
+++ b/doc/apps/s_client.pod
@@ -0,0 +1,266 @@
+
+=pod
+
+=head1 NAME
+
+s_client - SSL/TLS client program
+
+=head1 SYNOPSIS
+
+B<openssl> B<s_client>
+[B<-connect host:port>]
+[B<-verify depth>]
+[B<-cert filename>]
+[B<-certform DER|PEM>]
+[B<-key filename>]
+[B<-keyform DER|PEM>]
+[B<-pass arg>]
+[B<-CApath directory>]
+[B<-CAfile filename>]
+[B<-reconnect>]
+[B<-pause>]
+[B<-showcerts>]
+[B<-debug>]
+[B<-msg>]
+[B<-nbio_test>]
+[B<-state>]
+[B<-nbio>]
+[B<-crlf>]
+[B<-ign_eof>]
+[B<-quiet>]
+[B<-ssl2>]
+[B<-ssl3>]
+[B<-tls1>]
+[B<-no_ssl2>]
+[B<-no_ssl3>]
+[B<-no_tls1>]
+[B<-bugs>]
+[B<-cipher cipherlist>]
+[B<-starttls protocol>]
+[B<-engine id>]
+[B<-rand file(s)>]
+
+=head1 DESCRIPTION
+
+The B<s_client> command implements a generic SSL/TLS client which connects
+to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for
+SSL servers.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-connect host:port>
+
+This specifies the host and optional port to connect to. If not specified
+then an attempt is made to connect to the local host on port 4433.
+
+=item B<-cert certname>
+
+The certificate to use, if one is requested by the server. The default is
+not to use a certificate.
+
+=item B<-certform format>
+
+The certificate format to use: DER or PEM. PEM is the default.
+
+=item B<-key keyfile>
+
+The private key to use. If not specified then the certificate file will
+be used.
+
+=item B<-keyform format>
+
+The private format to use: DER or PEM. PEM is the default.
+
+=item B<-pass arg>
+
+the private key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-verify depth>
+
+The verify depth to use. This specifies the maximum length of the
+server certificate chain and turns on server certificate verification.
+Currently the verify operation continues after errors so all the problems
+with a certificate chain can be seen. As a side effect the connection
+will never fail due to a server certificate verify failure.
+
+=item B<-CApath directory>
+
+The directory to use for server certificate verification. This directory
+must be in "hash format", see B<verify> for more information. These are
+also used when building the client certificate chain.
+
+=item B<-CAfile file>
+
+A file containing trusted certificates to use during server authentication
+and to use when attempting to build the client certificate chain.
+
+=item B<-reconnect>
+
+reconnects to the same server 5 times using the same session ID, this can
+be used as a test that session caching is working.
+
+=item B<-pause>
+
+pauses 1 second between each read and write call.
+
+=item B<-showcerts>
+
+display the whole server certificate chain: normally only the server
+certificate itself is displayed.
+
+=item B<-prexit>
+
+print session information when the program exits. This will always attempt
+to print out information even if the connection fails. Normally information
+will only be printed out once if the connection succeeds. This option is useful
+because the cipher in use may be renegotiated or the connection may fail
+because a client certificate is required or is requested only after an
+attempt is made to access a certain URL. Note: the output produced by this
+option is not always accurate because a connection might never have been
+established.
+
+=item B<-state>
+
+prints out the SSL session states.
+
+=item B<-debug>
+
+print extensive debugging information including a hex dump of all traffic.
+
+=item B<-msg>
+
+show all protocol messages with hex dump.
+
+=item B<-nbio_test>
+
+tests non-blocking I/O
+
+=item B<-nbio>
+
+turns on non-blocking I/O
+
+=item B<-crlf>
+
+this option translated a line feed from the terminal into CR+LF as required
+by some servers.
+
+=item B<-ign_eof>
+
+inhibit shutting down the connection when end of file is reached in the
+input.
+
+=item B<-quiet>
+
+inhibit printing of session and certificate information. This implicitly
+turns on B<-ign_eof> as well.
+
+=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>
+
+these options disable the use of certain SSL or TLS protocols. By default
+the initial handshake uses a method which should be compatible with all
+servers and permit them to use SSL v3, SSL v2 or TLS as appropriate.
+
+Unfortunately there are a lot of ancient and broken servers in use which
+cannot handle this technique and will fail to connect. Some servers only
+work if TLS is turned off with the B<-no_tls> option others will only
+support SSL v2 and may need the B<-ssl2> option.
+
+=item B<-bugs>
+
+there are several known bug in SSL and TLS implementations. Adding this
+option enables various workarounds.
+
+=item B<-cipher cipherlist>
+
+this allows the cipher list sent by the client to be modified. Although
+the server determines which cipher suite is used it should take the first
+supported cipher in the list sent by the client. See the B<ciphers>
+command for more information.
+
+=item B<-starttls protocol>
+
+send the protocol-specific message(s) to switch to TLS for communication.
+B<protocol> is a keyword for the intended protocol. Currently, the only
+supported keywords are "smtp", "pop3", "imap", and "ftp".
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<s_client>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=back
+
+=head1 CONNECTED COMMANDS
+
+If a connection is established with an SSL server then any data received
+from the server is displayed and any key presses will be sent to the
+server. When used interactively (which means neither B<-quiet> nor B<-ign_eof>
+have been given), the session will be renegotiated if the line begins with an
+B<R>, and if the line begins with a B<Q> or if end of file is reached, the
+connection will be closed down.
+
+=head1 NOTES
+
+B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP
+server the command:
+
+ openssl s_client -connect servername:443
+
+would typically be used (https uses port 443). If the connection succeeds
+then an HTTP command can be given such as "GET /" to retrieve a web page.
+
+If the handshake fails then there are several possible causes, if it is
+nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>,
+B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> options can be tried
+in case it is a buggy server. In particular you should play with these
+options B<before> submitting a bug report to an OpenSSL mailing list.
+
+A frequent problem when attempting to get client certificates working
+is that a web client complains it has no certificates or gives an empty
+list to choose from. This is normally because the server is not sending
+the clients certificate authority in its "acceptable CA list" when it
+requests a certificate. By using B<s_client> the CA list can be viewed
+and checked. However some servers only request client authentication
+after a specific URL is requested. To obtain the list in this case it
+is necessary to use the B<-prexit> option and send an HTTP request
+for an appropriate page.
+
+If a certificate is specified on the command line using the B<-cert>
+option it will not be used unless the server specifically requests
+a client certificate. Therefor merely including a client certificate
+on the command line is no guarantee that the certificate works.
+
+If there are problems verifying a server certificate then the
+B<-showcerts> option can be used to show the whole chain.
+
+=head1 BUGS
+
+Because this program has a lot of options and also because some of
+the techniques used are rather old, the C source of s_client is rather
+hard to read and not a model of how things should be done. A typical
+SSL client program would be much simpler.
+
+The B<-verify> option should really exit if the server verification
+fails.
+
+The B<-prexit> option is a bit of a hack. We should really report
+information whenever a session is renegotiated.
+
+=head1 SEE ALSO
+
+L<sess_id(1)|sess_id(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
+
+=cut
diff --git a/doc/apps/s_server.pod b/doc/apps/s_server.pod
new file mode 100644
index 000000000000..7c1a9581d961
--- /dev/null
+++ b/doc/apps/s_server.pod
@@ -0,0 +1,327 @@
+
+=pod
+
+=head1 NAME
+
+s_server - SSL/TLS server program
+
+=head1 SYNOPSIS
+
+B<openssl> B<s_server>
+[B<-accept port>]
+[B<-context id>]
+[B<-verify depth>]
+[B<-Verify depth>]
+[B<-cert filename>]
+[B<-certform DER|PEM>]
+[B<-key keyfile>]
+[B<-keyform DER|PEM>]
+[B<-pass arg>]
+[B<-dcert filename>]
+[B<-dcertform DER|PEM>]
+[B<-dkey keyfile>]
+[B<-dkeyform DER|PEM>]
+[B<-dpass arg>]
+[B<-dhparam filename>]
+[B<-nbio>]
+[B<-nbio_test>]
+[B<-crlf>]
+[B<-debug>]
+[B<-msg>]
+[B<-state>]
+[B<-CApath directory>]
+[B<-CAfile filename>]
+[B<-nocert>]
+[B<-cipher cipherlist>]
+[B<-quiet>]
+[B<-no_tmp_rsa>]
+[B<-ssl2>]
+[B<-ssl3>]
+[B<-tls1>]
+[B<-no_ssl2>]
+[B<-no_ssl3>]
+[B<-no_tls1>]
+[B<-no_dhe>]
+[B<-bugs>]
+[B<-hack>]
+[B<-www>]
+[B<-WWW>]
+[B<-HTTP>]
+[B<-engine id>]
+[B<-id_prefix arg>]
+[B<-rand file(s)>]
+
+=head1 DESCRIPTION
+
+The B<s_server> command implements a generic SSL/TLS server which listens
+for connections on a given port using SSL/TLS.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-accept port>
+
+the TCP port to listen on for connections. If not specified 4433 is used.
+
+=item B<-context id>
+
+sets the SSL context id. It can be given any string value. If this option
+is not present a default value will be used.
+
+=item B<-cert certname>
+
+The certificate to use, most servers cipher suites require the use of a
+certificate and some require a certificate with a certain public key type:
+for example the DSS cipher suites require a certificate containing a DSS
+(DSA) key. If not specified then the filename "server.pem" will be used.
+
+=item B<-certform format>
+
+The certificate format to use: DER or PEM. PEM is the default.
+
+=item B<-key keyfile>
+
+The private key to use. If not specified then the certificate file will
+be used.
+
+=item B<-keyform format>
+
+The private format to use: DER or PEM. PEM is the default.
+
+=item B<-pass arg>
+
+the private key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-dcert filename>, B<-dkey keyname>
+
+specify an additional certificate and private key, these behave in the
+same manner as the B<-cert> and B<-key> options except there is no default
+if they are not specified (no additional certificate and key is used). As
+noted above some cipher suites require a certificate containing a key of
+a certain type. Some cipher suites need a certificate carrying an RSA key
+and some a DSS (DSA) key. By using RSA and DSS certificates and keys
+a server can support clients which only support RSA or DSS cipher suites
+by using an appropriate certificate.
+
+=item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg>
+
+addtional certificate and private key format and passphrase respectively.
+
+=item B<-nocert>
+
+if this option is set then no certificate is used. This restricts the
+cipher suites available to the anonymous ones (currently just anonymous
+DH).
+
+=item B<-dhparam filename>
+
+the DH parameter file to use. The ephemeral DH cipher suites generate keys
+using a set of DH parameters. If not specified then an attempt is made to
+load the parameters from the server certificate file. If this fails then
+a static set of parameters hard coded into the s_server program will be used.
+
+=item B<-no_dhe>
+
+if this option is set then no DH parameters will be loaded effectively
+disabling the ephemeral DH cipher suites.
+
+=item B<-no_tmp_rsa>
+
+certain export cipher suites sometimes use a temporary RSA key, this option
+disables temporary RSA key generation.
+
+=item B<-verify depth>, B<-Verify depth>
+
+The verify depth to use. This specifies the maximum length of the
+client certificate chain and makes the server request a certificate from
+the client. With the B<-verify> option a certificate is requested but the
+client does not have to send one, with the B<-Verify> option the client
+must supply a certificate or an error occurs.
+
+=item B<-CApath directory>
+
+The directory to use for client certificate verification. This directory
+must be in "hash format", see B<verify> for more information. These are
+also used when building the server certificate chain.
+
+=item B<-CAfile file>
+
+A file containing trusted certificates to use during client authentication
+and to use when attempting to build the server certificate chain. The list
+is also used in the list of acceptable client CAs passed to the client when
+a certificate is requested.
+
+=item B<-state>
+
+prints out the SSL session states.
+
+=item B<-debug>
+
+print extensive debugging information including a hex dump of all traffic.
+
+=item B<-msg>
+
+show all protocol messages with hex dump.
+
+=item B<-nbio_test>
+
+tests non blocking I/O
+
+=item B<-nbio>
+
+turns on non blocking I/O
+
+=item B<-crlf>
+
+this option translated a line feed from the terminal into CR+LF.
+
+=item B<-quiet>
+
+inhibit printing of session and certificate information.
+
+=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>
+
+these options disable the use of certain SSL or TLS protocols. By default
+the initial handshake uses a method which should be compatible with all
+servers and permit them to use SSL v3, SSL v2 or TLS as appropriate.
+
+=item B<-bugs>
+
+there are several known bug in SSL and TLS implementations. Adding this
+option enables various workarounds.
+
+=item B<-hack>
+
+this option enables a further workaround for some some early Netscape
+SSL code (?).
+
+=item B<-cipher cipherlist>
+
+this allows the cipher list used by the server to be modified. When
+the client sends a list of supported ciphers the first client cipher
+also included in the server list is used. Because the client specifies
+the preference order, the order of the server cipherlist irrelevant. See
+the B<ciphers> command for more information.
+
+=item B<-www>
+
+sends a status message back to the client when it connects. This includes
+lots of information about the ciphers used and various session parameters.
+The output is in HTML format so this option will normally be used with a
+web browser.
+
+=item B<-WWW>
+
+emulates a simple web server. Pages will be resolved relative to the
+current directory, for example if the URL https://myhost/page.html is
+requested the file ./page.html will be loaded.
+
+=item B<-HTTP>
+
+emulates a simple web server. Pages will be resolved relative to the
+current directory, for example if the URL https://myhost/page.html is
+requested the file ./page.html will be loaded. The files loaded are
+assumed to contain a complete and correct HTTP response (lines that
+are part of the HTTP response line and headers must end with CRLF).
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<s_server>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-id_prefix arg>
+
+generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful
+for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple
+servers, when each of which might be generating a unique range of session
+IDs (eg. with a certain prefix).
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=back
+
+=head1 CONNECTED COMMANDS
+
+If a connection request is established with an SSL client and neither the
+B<-www> nor the B<-WWW> option has been used then normally any data received
+from the client is displayed and any key presses will be sent to the client.
+
+Certain single letter commands are also recognized which perform special
+operations: these are listed below.
+
+=over 4
+
+=item B<q>
+
+end the current SSL connection but still accept new connections.
+
+=item B<Q>
+
+end the current SSL connection and exit.
+
+=item B<r>
+
+renegotiate the SSL session.
+
+=item B<R>
+
+renegotiate the SSL session and request a client certificate.
+
+=item B<P>
+
+send some plain text down the underlying TCP connection: this should
+cause the client to disconnect due to a protocol violation.
+
+=item B<S>
+
+print out some session cache status information.
+
+=back
+
+=head1 NOTES
+
+B<s_server> can be used to debug SSL clients. To accept connections from
+a web browser the command:
+
+ openssl s_server -accept 443 -www
+
+can be used for example.
+
+Most web browsers (in particular Netscape and MSIE) only support RSA cipher
+suites, so they cannot connect to servers which don't use a certificate
+carrying an RSA key or a version of OpenSSL with RSA disabled.
+
+Although specifying an empty list of CAs when requesting a client certificate
+is strictly speaking a protocol violation, some SSL clients interpret this to
+mean any CA is acceptable. This is useful for debugging purposes.
+
+The session parameters can printed out using the B<sess_id> program.
+
+=head1 BUGS
+
+Because this program has a lot of options and also because some of
+the techniques used are rather old, the C source of s_server is rather
+hard to read and not a model of how things should be done. A typical
+SSL server program would be much simpler.
+
+The output of common ciphers is wrong: it just gives the list of ciphers that
+OpenSSL recognizes and the client supports.
+
+There should be a way for the B<s_server> program to print out details of any
+unknown cipher suites a client says it supports.
+
+=head1 SEE ALSO
+
+L<sess_id(1)|sess_id(1)>, L<s_client(1)|s_client(1)>, L<ciphers(1)|ciphers(1)>
+
+=cut
diff --git a/doc/apps/s_time.pod b/doc/apps/s_time.pod
new file mode 100644
index 000000000000..5a38aa2e0394
--- /dev/null
+++ b/doc/apps/s_time.pod
@@ -0,0 +1,173 @@
+
+=pod
+
+=head1 NAME
+
+s_time - SSL/TLS performance timing program
+
+=head1 SYNOPSIS
+
+B<openssl> B<s_time>
+[B<-connect host:port>]
+[B<-www page>]
+[B<-cert filename>]
+[B<-key filename>]
+[B<-CApath directory>]
+[B<-CAfile filename>]
+[B<-reuse>]
+[B<-new>]
+[B<-verify depth>]
+[B<-nbio>]
+[B<-time seconds>]
+[B<-ssl2>]
+[B<-ssl3>]
+[B<-bugs>]
+[B<-cipher cipherlist>]
+
+=head1 DESCRIPTION
+
+The B<s_client> command implements a generic SSL/TLS client which connects to a
+remote host using SSL/TLS. It can request a page from the server and includes
+the time to transfer the payload data in its timing measurements. It measures
+the number of connections within a given timeframe, the amount of data
+transferred (if any), and calculates the average time spent for one connection.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-connect host:port>
+
+This specifies the host and optional port to connect to.
+
+=item B<-www page>
+
+This specifies the page to GET from the server. A value of '/' gets the
+index.htm[l] page. If this parameter is not specified, then B<s_time> will only
+perform the handshake to establish SSL connections but not transfer any
+payload data.
+
+=item B<-cert certname>
+
+The certificate to use, if one is requested by the server. The default is
+not to use a certificate. The file is in PEM format.
+
+=item B<-key keyfile>
+
+The private key to use. If not specified then the certificate file will
+be used. The file is in PEM format.
+
+=item B<-verify depth>
+
+The verify depth to use. This specifies the maximum length of the
+server certificate chain and turns on server certificate verification.
+Currently the verify operation continues after errors so all the problems
+with a certificate chain can be seen. As a side effect the connection
+will never fail due to a server certificate verify failure.
+
+=item B<-CApath directory>
+
+The directory to use for server certificate verification. This directory
+must be in "hash format", see B<verify> for more information. These are
+also used when building the client certificate chain.
+
+=item B<-CAfile file>
+
+A file containing trusted certificates to use during server authentication
+and to use when attempting to build the client certificate chain.
+
+=item B<-new>
+
+performs the timing test using a new session ID for each connection.
+If neither B<-new> nor B<-reuse> are specified, they are both on by default
+and executed in sequence.
+
+=item B<-reuse>
+
+performs the timing test using the same session ID; this can be used as a test
+that session caching is working. If neither B<-new> nor B<-reuse> are
+specified, they are both on by default and executed in sequence.
+
+=item B<-nbio>
+
+turns on non-blocking I/O.
+
+=item B<-ssl2>, B<-ssl3>
+
+these options disable the use of certain SSL or TLS protocols. By default
+the initial handshake uses a method which should be compatible with all
+servers and permit them to use SSL v3, SSL v2 or TLS as appropriate.
+The timing program is not as rich in options to turn protocols on and off as
+the L<s_client(1)|s_client(1)> program and may not connect to all servers.
+
+Unfortunately there are a lot of ancient and broken servers in use which
+cannot handle this technique and will fail to connect. Some servers only
+work if TLS is turned off with the B<-ssl3> option; others
+will only support SSL v2 and may need the B<-ssl2> option.
+
+=item B<-bugs>
+
+there are several known bug in SSL and TLS implementations. Adding this
+option enables various workarounds.
+
+=item B<-cipher cipherlist>
+
+this allows the cipher list sent by the client to be modified. Although
+the server determines which cipher suite is used it should take the first
+supported cipher in the list sent by the client.
+See the L<ciphers(1)|ciphers(1)> command for more information.
+
+=item B<-time length>
+
+specifies how long (in seconds) B<s_time> should establish connections and
+optionally transfer payload data from a server. Server and client performance
+and the link speed determine how many connections B<s_time> can establish.
+
+=back
+
+=head1 NOTES
+
+B<s_client> can be used to measure the performance of an SSL connection.
+To connect to an SSL HTTP server and get the default page the command
+
+ openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]
+
+would typically be used (https uses port 443). 'commoncipher' is a cipher to
+which both client and server can agree, see the L<ciphers(1)|ciphers(1)> command
+for details.
+
+If the handshake fails then there are several possible causes, if it is
+nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>,
+B<-ssl3> options can be tried
+in case it is a buggy server. In particular you should play with these
+options B<before> submitting a bug report to an OpenSSL mailing list.
+
+A frequent problem when attempting to get client certificates working
+is that a web client complains it has no certificates or gives an empty
+list to choose from. This is normally because the server is not sending
+the clients certificate authority in its "acceptable CA list" when it
+requests a certificate. By using L<s_client(1)|s_client(1)> the CA list can be
+viewed and checked. However some servers only request client authentication
+after a specific URL is requested. To obtain the list in this case it
+is necessary to use the B<-prexit> option of L<s_client(1)|s_client(1)> and
+send an HTTP request for an appropriate page.
+
+If a certificate is specified on the command line using the B<-cert>
+option it will not be used unless the server specifically requests
+a client certificate. Therefor merely including a client certificate
+on the command line is no guarantee that the certificate works.
+
+=head1 BUGS
+
+Because this program does not have all the options of the
+L<s_client(1)|s_client(1)> program to turn protocols on and off, you may not be
+able to measure the performance of all protocols with all servers.
+
+The B<-verify> option should really exit if the server verification
+fails.
+
+=head1 SEE ALSO
+
+L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
+
+=cut
diff --git a/doc/apps/sess_id.pod b/doc/apps/sess_id.pod
new file mode 100644
index 000000000000..9988d2cd3d5d
--- /dev/null
+++ b/doc/apps/sess_id.pod
@@ -0,0 +1,151 @@
+
+=pod
+
+=head1 NAME
+
+sess_id - SSL/TLS session handling utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<sess_id>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-text>]
+[B<-noout>]
+[B<-context ID>]
+
+=head1 DESCRIPTION
+
+The B<sess_id> process the encoded version of the SSL session structure
+and optionally prints out SSL session details (for example the SSL session
+master key) in human readable format. Since this is a diagnostic tool that
+needs some knowledge of the SSL protocol to use properly, most users will
+not need to use it.
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+format containing session details. The precise format can vary from one version
+to the next. The B<PEM> form is the default format: it consists of the B<DER>
+format base64 encoded with additional header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read session information from or standard
+input by default.
+
+=item B<-out filename>
+
+This specifies the output filename to write session information to or standard
+output if this option is not specified.
+
+=item B<-text>
+
+prints out the various public or private key components in
+plain text in addition to the encoded version.
+
+=item B<-cert>
+
+if a certificate is present in the session it will be output using this option,
+if the B<-text> option is also present then it will be printed out in text form.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the session.
+
+=item B<-context ID>
+
+this option can set the session id so the output session information uses the
+supplied ID. The ID can be any string of characters. This option wont normally
+be used.
+
+=back
+
+=head1 OUTPUT
+
+Typical output:
+
+ SSL-Session:
+ Protocol : TLSv1
+ Cipher : 0016
+ Session-ID: 871E62626C554CE95488823752CBD5F3673A3EF3DCE9C67BD916C809914B40ED
+ Session-ID-ctx: 01000000
+ Master-Key: A7CEFC571974BE02CAC305269DC59F76EA9F0B180CB6642697A68251F2D2BB57E51DBBB4C7885573192AE9AEE220FACD
+ Key-Arg : None
+ Start Time: 948459261
+ Timeout : 300 (sec)
+ Verify return code 0 (ok)
+
+Theses are described below in more detail.
+
+=over 4
+
+=item B<Protocol>
+
+this is the protocol in use TLSv1, SSLv3 or SSLv2.
+
+=item B<Cipher>
+
+the cipher used this is the actual raw SSL or TLS cipher code, see the SSL
+or TLS specifications for more information.
+
+=item B<Session-ID>
+
+the SSL session ID in hex format.
+
+=item B<Session-ID-ctx>
+
+the session ID context in hex format.
+
+=item B<Master-Key>
+
+this is the SSL session master key.
+
+=item B<Key-Arg>
+
+the key argument, this is only used in SSL v2.
+
+=item B<Start Time>
+
+this is the session start time represented as an integer in standard Unix format.
+
+=item B<Timeout>
+
+the timeout in seconds.
+
+=item B<Verify return code>
+
+this is the return code when an SSL client certificate is verified.
+
+=back
+
+=head1 NOTES
+
+The PEM encoded session format uses the header and footer lines:
+
+ -----BEGIN SSL SESSION PARAMETERS-----
+ -----END SSL SESSION PARAMETERS-----
+
+Since the SSL session output contains the master key it is possible to read the contents
+of an encrypted session using this information. Therefore appropriate security precautions
+should be taken if the information is being output by a "real" application. This is
+however strongly discouraged and should only be used for debugging purposes.
+
+=head1 BUGS
+
+The cipher and start time should be printed out in human readable form.
+
+=head1 SEE ALSO
+
+L<ciphers(1)|ciphers(1)>, L<s_server(1)|s_server(1)>
+
+=cut
diff --git a/doc/apps/smime.pod b/doc/apps/smime.pod
new file mode 100644
index 000000000000..caf2d2689e62
--- /dev/null
+++ b/doc/apps/smime.pod
@@ -0,0 +1,385 @@
+=pod
+
+=head1 NAME
+
+smime - S/MIME utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<smime>
+[B<-encrypt>]
+[B<-decrypt>]
+[B<-sign>]
+[B<-verify>]
+[B<-pk7out>]
+[B<-des>]
+[B<-des3>]
+[B<-rc2-40>]
+[B<-rc2-64>]
+[B<-rc2-128>]
+[B<-aes128>]
+[B<-aes192>]
+[B<-aes256>]
+[B<-camellia128>]
+[B<-camellia192>]
+[B<-camellia256>]
+[B<-in file>]
+[B<-certfile file>]
+[B<-signer file>]
+[B<-recip file>]
+[B<-inform SMIME|PEM|DER>]
+[B<-passin arg>]
+[B<-inkey file>]
+[B<-out file>]
+[B<-outform SMIME|PEM|DER>]
+[B<-content file>]
+[B<-to addr>]
+[B<-from ad>]
+[B<-subject s>]
+[B<-text>]
+[B<-rand file(s)>]
+[cert.pem]...
+
+=head1 DESCRIPTION
+
+The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
+verify S/MIME messages.
+
+=head1 COMMAND OPTIONS
+
+There are five operation options that set the type of operation to be performed.
+The meaning of the other options varies according to the operation type.
+
+=over 4
+
+=item B<-encrypt>
+
+encrypt mail for the given recipient certificates. Input file is the message
+to be encrypted. The output file is the encrypted mail in MIME format.
+
+=item B<-decrypt>
+
+decrypt mail using the supplied certificate and private key. Expects an
+encrypted mail message in MIME format for the input file. The decrypted mail
+is written to the output file.
+
+=item B<-sign>
+
+sign mail using the supplied certificate and private key. Input file is
+the message to be signed. The signed message in MIME format is written
+to the output file.
+
+=item B<-verify>
+
+verify signed mail. Expects a signed mail message on input and outputs
+the signed data. Both clear text and opaque signing is supported.
+
+=item B<-pk7out>
+
+takes an input message and writes out a PEM encoded PKCS#7 structure.
+
+=item B<-in filename>
+
+the input message to be encrypted or signed or the MIME message to
+be decrypted or verified.
+
+=item B<-inform SMIME|PEM|DER>
+
+this specifies the input format for the PKCS#7 structure. The default
+is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
+format change this to expect PEM and DER format PKCS#7 structures
+instead. This currently only affects the input format of the PKCS#7
+structure, if no PKCS#7 structure is being input (for example with
+B<-encrypt> or B<-sign>) this option has no effect.
+
+=item B<-out filename>
+
+the message text that has been decrypted or verified or the output MIME
+format message that has been signed or verified.
+
+=item B<-outform SMIME|PEM|DER>
+
+this specifies the output format for the PKCS#7 structure. The default
+is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER>
+format change this to write PEM and DER format PKCS#7 structures
+instead. This currently only affects the output format of the PKCS#7
+structure, if no PKCS#7 structure is being output (for example with
+B<-verify> or B<-decrypt>) this option has no effect.
+
+=item B<-content filename>
+
+This specifies a file containing the detached content, this is only
+useful with the B<-verify> command. This is only usable if the PKCS#7
+structure is using the detached signature form where the content is
+not included. This option will override any content if the input format
+is S/MIME and it uses the multipart/signed MIME content type.
+
+=item B<-text>
+
+this option adds plain text (text/plain) MIME headers to the supplied
+message if encrypting or signing. If decrypting or verifying it strips
+off text headers: if the decrypted or verified message is not of MIME
+type text/plain then an error occurs.
+
+=item B<-CAfile file>
+
+a file containing trusted CA certificates, only used with B<-verify>.
+
+=item B<-CApath dir>
+
+a directory containing trusted CA certificates, only used with
+B<-verify>. This directory must be a standard certificate directory: that
+is a hash of each subject name (using B<x509 -hash>) should be linked
+to each certificate.
+
+=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128 -aes128 -aes192 -aes256 -camellia128 -camellia192 -camellia256>
+
+the encryption algorithm to use. DES (56 bits), triple DES (168 bits),
+40, 64 or 128 bit RC2, 128, 192 or 256 bit AES, or 128, 192 or 256 bit Camellia respectively. If not
+specified 40 bit RC2 is used. Only used with B<-encrypt>.
+
+=item B<-nointern>
+
+when verifying a message normally certificates (if any) included in
+the message are searched for the signing certificate. With this option
+only the certificates specified in the B<-certfile> option are used.
+The supplied certificates can still be used as untrusted CAs however.
+
+=item B<-noverify>
+
+do not verify the signers certificate of a signed message.
+
+=item B<-nochain>
+
+do not do chain verification of signers certificates: that is don't
+use the certificates in the signed message as untrusted CAs.
+
+=item B<-nosigs>
+
+don't try to verify the signatures on the message.
+
+=item B<-nocerts>
+
+when signing a message the signer's certificate is normally included
+with this option it is excluded. This will reduce the size of the
+signed message but the verifier must have a copy of the signers certificate
+available locally (passed using the B<-certfile> option for example).
+
+=item B<-noattr>
+
+normally when a message is signed a set of attributes are included which
+include the signing time and supported symmetric algorithms. With this
+option they are not included.
+
+=item B<-binary>
+
+normally the input message is converted to "canonical" format which is
+effectively using CR and LF as end of line: as required by the S/MIME
+specification. When this option is present no translation occurs. This
+is useful when handling binary data which may not be in MIME format.
+
+=item B<-nodetach>
+
+when signing a message use opaque signing: this form is more resistant
+to translation by mail relays but it cannot be read by mail agents that
+do not support S/MIME. Without this option cleartext signing with
+the MIME type multipart/signed is used.
+
+=item B<-certfile file>
+
+allows additional certificates to be specified. When signing these will
+be included with the message. When verifying these will be searched for
+the signers certificates. The certificates should be in PEM format.
+
+=item B<-signer file>
+
+the signers certificate when signing a message. If a message is
+being verified then the signers certificates will be written to this
+file if the verification was successful.
+
+=item B<-recip file>
+
+the recipients certificate when decrypting a message. This certificate
+must match one of the recipients of the message or an error occurs.
+
+=item B<-inkey file>
+
+the private key to use when signing or decrypting. This must match the
+corresponding certificate. If this option is not specified then the
+private key must be included in the certificate file specified with
+the B<-recip> or B<-signer> file.
+
+=item B<-passin arg>
+
+the private key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<cert.pem...>
+
+one or more certificates of message recipients: used when encrypting
+a message.
+
+=item B<-to, -from, -subject>
+
+the relevant mail headers. These are included outside the signed
+portion of a message so they may be included manually. If signing
+then many S/MIME mail clients check the signers certificate's email
+address matches that specified in the From: address.
+
+=back
+
+=head1 NOTES
+
+The MIME message must be sent without any blank lines between the
+headers and the output. Some mail programs will automatically add
+a blank line. Piping the mail directly to sendmail is one way to
+achieve the correct format.
+
+The supplied message to be signed or encrypted must include the
+necessary MIME headers or many S/MIME clients wont display it
+properly (if at all). You can use the B<-text> option to automatically
+add plain text headers.
+
+A "signed and encrypted" message is one where a signed message is
+then encrypted. This can be produced by encrypting an already signed
+message: see the examples section.
+
+This version of the program only allows one signer per message but it
+will verify multiple signers on received messages. Some S/MIME clients
+choke if a message contains multiple signers. It is possible to sign
+messages "in parallel" by signing an already signed message.
+
+The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
+clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7
+encrypted data is used for other purposes.
+
+=head1 EXIT CODES
+
+=over 4
+
+=item 0
+
+the operation was completely successfully.
+
+=item 1
+
+an error occurred parsing the command options.
+
+=item 2
+
+one of the input files could not be read.
+
+=item 3
+
+an error occurred creating the PKCS#7 file or when reading the MIME
+message.
+
+=item 4
+
+an error occurred decrypting or verifying the message.
+
+=item 5
+
+the message was verified correctly but an error occurred writing out
+the signers certificates.
+
+=back
+
+=head1 EXAMPLES
+
+Create a cleartext signed message:
+
+ openssl smime -sign -in message.txt -text -out mail.msg \
+ -signer mycert.pem
+
+Create and opaque signed message
+
+ openssl smime -sign -in message.txt -text -out mail.msg -nodetach \
+ -signer mycert.pem
+
+Create a signed message, include some additional certificates and
+read the private key from another file:
+
+ openssl smime -sign -in in.txt -text -out mail.msg \
+ -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
+
+Send a signed message under Unix directly to sendmail, including headers:
+
+ openssl smime -sign -in in.txt -text -signer mycert.pem \
+ -from steve@openssl.org -to someone@somewhere \
+ -subject "Signed message" | sendmail someone@somewhere
+
+Verify a message and extract the signer's certificate if successful:
+
+ openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt
+
+Send encrypted mail using triple DES:
+
+ openssl smime -encrypt -in in.txt -from steve@openssl.org \
+ -to someone@somewhere -subject "Encrypted message" \
+ -des3 user.pem -out mail.msg
+
+Sign and encrypt mail:
+
+ openssl smime -sign -in ml.txt -signer my.pem -text \
+ | openssl smime -encrypt -out mail.msg \
+ -from steve@openssl.org -to someone@somewhere \
+ -subject "Signed and Encrypted message" -des3 user.pem
+
+Note: the encryption command does not include the B<-text> option because the message
+being encrypted already has MIME headers.
+
+Decrypt mail:
+
+ openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
+
+The output from Netscape form signing is a PKCS#7 structure with the
+detached signature format. You can use this program to verify the
+signature by line wrapping the base64 encoded structure and surrounding
+it with:
+
+ -----BEGIN PKCS7-----
+ -----END PKCS7-----
+
+and using the command,
+
+ openssl smime -verify -inform PEM -in signature.pem -content content.txt
+
+alternatively you can base64 decode the signature and use
+
+ openssl smime -verify -inform DER -in signature.der -content content.txt
+
+Create an encrypted message using 128 bit Camellia:
+
+ openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
+
+=head1 BUGS
+
+The MIME parser isn't very clever: it seems to handle most messages that I've thrown
+at it but it may choke on others.
+
+The code currently will only write out the signer's certificate to a file: if the
+signer has a separate encryption certificate this must be manually extracted. There
+should be some heuristic that determines the correct encryption certificate.
+
+Ideally a database should be maintained of a certificates for each email address.
+
+The code doesn't currently take note of the permitted symmetric encryption
+algorithms as supplied in the SMIMECapabilities signed attribute. this means the
+user has to manually include the correct encryption algorithm. It should store
+the list of permitted ciphers in a database and only use those.
+
+No revocation checking is done on the signer's certificate.
+
+The current code can only handle S/MIME v2 messages, the more complex S/MIME v3
+structures may cause parsing errors.
+
+=cut
diff --git a/doc/apps/speed.pod b/doc/apps/speed.pod
new file mode 100644
index 000000000000..0dcdba873e0c
--- /dev/null
+++ b/doc/apps/speed.pod
@@ -0,0 +1,59 @@
+=pod
+
+=head1 NAME
+
+speed - test library performance
+
+=head1 SYNOPSIS
+
+B<openssl speed>
+[B<-engine id>]
+[B<md2>]
+[B<mdc2>]
+[B<md5>]
+[B<hmac>]
+[B<sha1>]
+[B<rmd160>]
+[B<idea-cbc>]
+[B<rc2-cbc>]
+[B<rc5-cbc>]
+[B<bf-cbc>]
+[B<des-cbc>]
+[B<des-ede3>]
+[B<rc4>]
+[B<rsa512>]
+[B<rsa1024>]
+[B<rsa2048>]
+[B<rsa4096>]
+[B<dsa512>]
+[B<dsa1024>]
+[B<dsa2048>]
+[B<idea>]
+[B<rc2>]
+[B<des>]
+[B<rsa>]
+[B<blowfish>]
+
+=head1 DESCRIPTION
+
+This command is used to test the performance of cryptographic algorithms.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<speed>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<[zero or more test algorithms]>
+
+If any options are given, B<speed> tests those algorithms, otherwise all of
+the above are tested.
+
+=back
+
+=cut
diff --git a/doc/apps/spkac.pod b/doc/apps/spkac.pod
new file mode 100644
index 000000000000..c3f1ff9c6441
--- /dev/null
+++ b/doc/apps/spkac.pod
@@ -0,0 +1,133 @@
+=pod
+
+=head1 NAME
+
+spkac - SPKAC printing and generating utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<spkac>
+[B<-in filename>]
+[B<-out filename>]
+[B<-key keyfile>]
+[B<-passin arg>]
+[B<-challenge string>]
+[B<-pubkey>]
+[B<-spkac spkacname>]
+[B<-spksect section>]
+[B<-noout>]
+[B<-verify>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<spkac> command processes Netscape signed public key and challenge
+(SPKAC) files. It can print out their contents, verify the signature and
+produce its own SPKACs from a supplied private key.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-in filename>
+
+This specifies the input filename to read from or standard input if this
+option is not specified. Ignored if the B<-key> option is used.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-key keyfile>
+
+create an SPKAC file using the private key in B<keyfile>. The
+B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if
+present.
+
+=item B<-passin password>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
+=item B<-challenge string>
+
+specifies the challenge string if an SPKAC is being created.
+
+=item B<-spkac spkacname>
+
+allows an alternative name form the variable containing the
+SPKAC. The default is "SPKAC". This option affects both
+generated and input SPKAC files.
+
+=item B<-spksect section>
+
+allows an alternative name form the section containing the
+SPKAC. The default is the default section.
+
+=item B<-noout>
+
+don't output the text version of the SPKAC (not used if an
+SPKAC is being created).
+
+=item B<-pubkey>
+
+output the public key of an SPKAC (not used if an SPKAC is
+being created).
+
+=item B<-verify>
+
+verifies the digital signature on the supplied SPKAC.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 EXAMPLES
+
+Print out the contents of an SPKAC:
+
+ openssl spkac -in spkac.cnf
+
+Verify the signature of an SPKAC:
+
+ openssl spkac -in spkac.cnf -noout -verify
+
+Create an SPKAC using the challenge string "hello":
+
+ openssl spkac -key key.pem -challenge hello -out spkac.cnf
+
+Example of an SPKAC, (long lines split up for clarity):
+
+ SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\
+ PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\
+ PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\
+ 2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\
+ 4=
+
+=head1 NOTES
+
+A created SPKAC with suitable DN components appended can be fed into
+the B<ca> utility.
+
+SPKACs are typically generated by Netscape when a form is submitted
+containing the B<KEYGEN> tag as part of the certificate enrollment
+process.
+
+The challenge string permits a primitive form of proof of possession
+of private key. By checking the SPKAC signature and a random challenge
+string some guarantee is given that the user knows the private key
+corresponding to the public key being certified. This is important in
+some applications. Without this it is possible for a previous SPKAC
+to be used in a "replay attack".
+
+=head1 SEE ALSO
+
+L<ca(1)|ca(1)>
+
+=cut
diff --git a/doc/apps/verify.pod b/doc/apps/verify.pod
new file mode 100644
index 000000000000..ea5c29c15021
--- /dev/null
+++ b/doc/apps/verify.pod
@@ -0,0 +1,328 @@
+=pod
+
+=head1 NAME
+
+verify - Utility to verify certificates.
+
+=head1 SYNOPSIS
+
+B<openssl> B<verify>
+[B<-CApath directory>]
+[B<-CAfile file>]
+[B<-purpose purpose>]
+[B<-untrusted file>]
+[B<-help>]
+[B<-issuer_checks>]
+[B<-verbose>]
+[B<->]
+[certificates]
+
+
+=head1 DESCRIPTION
+
+The B<verify> command verifies certificate chains.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-CApath directory>
+
+A directory of trusted certificates. The certificates should have names
+of the form: hash.0 or have symbolic links to them of this
+form ("hash" is the hashed certificate subject name: see the B<-hash> option
+of the B<x509> utility). Under Unix the B<c_rehash> script will automatically
+create symbolic links to a directory of certificates.
+
+=item B<-CAfile file>
+
+A file of trusted certificates. The file should contain multiple certificates
+in PEM format concatenated together.
+
+=item B<-untrusted file>
+
+A file of untrusted certificates. The file should contain multiple certificates
+
+=item B<-purpose purpose>
+
+the intended use for the certificate. Without this option no chain verification
+will be done. Currently accepted uses are B<sslclient>, B<sslserver>,
+B<nssslserver>, B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION>
+section for more information.
+
+=item B<-help>
+
+prints out a usage message.
+
+=item B<-verbose>
+
+print extra information about the operations being performed.
+
+=item B<-issuer_checks>
+
+print out diagnostics relating to searches for the issuer certificate
+of the current certificate. This shows why each candidate issuer
+certificate was rejected. However the presence of rejection messages
+does not itself imply that anything is wrong: during the normal
+verify process several rejections may take place.
+
+=item B<->
+
+marks the last option. All arguments following this are assumed to be
+certificate files. This is useful if the first certificate filename begins
+with a B<->.
+
+=item B<certificates>
+
+one or more certificates to verify. If no certificate filenames are included
+then an attempt is made to read a certificate from standard input. They should
+all be in PEM format.
+
+
+=back
+
+=head1 VERIFY OPERATION
+
+The B<verify> program uses the same functions as the internal SSL and S/MIME
+verification, therefore this description applies to these verify operations
+too.
+
+There is one crucial difference between the verify operations performed
+by the B<verify> program: wherever possible an attempt is made to continue
+after an error whereas normally the verify operation would halt on the
+first error. This allows all the problems with a certificate chain to be
+determined.
+
+The verify operation consists of a number of separate steps.
+
+Firstly a certificate chain is built up starting from the supplied certificate
+and ending in the root CA. It is an error if the whole chain cannot be built
+up. The chain is built up by looking up the issuers certificate of the current
+certificate. If a certificate is found which is its own issuer it is assumed
+to be the root CA.
+
+The process of 'looking up the issuers certificate' itself involves a number
+of steps. In versions of OpenSSL before 0.9.5a the first certificate whose
+subject name matched the issuer of the current certificate was assumed to be
+the issuers certificate. In OpenSSL 0.9.6 and later all certificates
+whose subject name matches the issuer name of the current certificate are
+subject to further tests. The relevant authority key identifier components
+of the current certificate (if present) must match the subject key identifier
+(if present) and issuer and serial number of the candidate issuer, in addition
+the keyUsage extension of the candidate issuer (if present) must permit
+certificate signing.
+
+The lookup first looks in the list of untrusted certificates and if no match
+is found the remaining lookups are from the trusted certificates. The root CA
+is always looked up in the trusted certificate list: if the certificate to
+verify is a root certificate then an exact match must be found in the trusted
+list.
+
+The second operation is to check every untrusted certificate's extensions for
+consistency with the supplied purpose. If the B<-purpose> option is not included
+then no checks are done. The supplied or "leaf" certificate must have extensions
+compatible with the supplied purpose and all other certificates must also be valid
+CA certificates. The precise extensions required are described in more detail in
+the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility.
+
+The third operation is to check the trust settings on the root CA. The root
+CA should be trusted for the supplied purpose. For compatibility with previous
+versions of SSLeay and OpenSSL a certificate with no trust settings is considered
+to be valid for all purposes.
+
+The final operation is to check the validity of the certificate chain. The validity
+period is checked against the current system time and the notBefore and notAfter
+dates in the certificate. The certificate signatures are also checked at this
+point.
+
+If all operations complete successfully then certificate is considered valid. If
+any operation fails then the certificate is not valid.
+
+=head1 DIAGNOSTICS
+
+When a verify operation fails the output messages can be somewhat cryptic. The
+general form of the error message is:
+
+ server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)
+ error 24 at 1 depth lookup:invalid CA certificate
+
+The first line contains the name of the certificate being verified followed by
+the subject name of the certificate. The second line contains the error number
+and the depth. The depth is number of the certificate being verified when a
+problem was detected starting with zero for the certificate being verified itself
+then 1 for the CA that signed the certificate and so on. Finally a text version
+of the error number is presented.
+
+An exhaustive list of the error codes and messages is shown below, this also
+includes the name of the error code as defined in the header file x509_vfy.h
+Some of the error codes are defined but never returned: these are described
+as "unused".
+
+=over 4
+
+=item B<0 X509_V_OK: ok>
+
+the operation was successful.
+
+=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
+
+the issuer certificate could not be found: this occurs if the issuer certificate
+of an untrusted certificate cannot be found.
+
+=item B<3 X509_V_ERR_UNABLE_TO_GET_CRL unable to get certificate CRL>
+
+the CRL of a certificate could not be found. Unused.
+
+=item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
+
+the certificate signature could not be decrypted. This means that the actual signature value
+could not be determined rather than it not matching the expected value, this is only
+meaningful for RSA keys.
+
+=item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature>
+
+the CRL signature could not be decrypted: this means that the actual signature value
+could not be determined rather than it not matching the expected value. Unused.
+
+=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
+
+the public key in the certificate SubjectPublicKeyInfo could not be read.
+
+=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
+
+the signature of the certificate is invalid.
+
+=item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
+
+the signature of the certificate is invalid. Unused.
+
+=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
+
+the certificate is not yet valid: the notBefore date is after the current time.
+
+=item B<10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
+
+the certificate has expired: that is the notAfter date is before the current time.
+
+=item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
+
+the CRL is not yet valid. Unused.
+
+=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
+
+the CRL has expired. Unused.
+
+=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
+
+the certificate notBefore field contains an invalid time.
+
+=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field>
+
+the certificate notAfter field contains an invalid time.
+
+=item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
+
+the CRL lastUpdate field contains an invalid time. Unused.
+
+=item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
+
+the CRL nextUpdate field contains an invalid time. Unused.
+
+=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory>
+
+an error occurred trying to allocate memory. This should never happen.
+
+=item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate>
+
+the passed certificate is self signed and the same certificate cannot be found in the list of
+trusted certificates.
+
+=item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain>
+
+the certificate chain could be built up using the untrusted certificates but the root could not
+be found locally.
+
+=item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
+
+the issuer certificate of a locally looked up certificate could not be found. This normally means
+the list of trusted certificates is not complete.
+
+=item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
+
+no signatures could be verified because the chain contains only one certificate and it is not
+self signed.
+
+=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
+
+the certificate chain length is greater than the supplied maximum depth. Unused.
+
+=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked>
+
+the certificate has been revoked. Unused.
+
+=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate>
+
+a CA certificate is invalid. Either it is not a CA or its extensions are not consistent
+with the supplied purpose.
+
+=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
+
+the basicConstraints pathlength parameter has been exceeded.
+
+=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
+
+the supplied certificate cannot be used for the specified purpose.
+
+=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
+
+the root CA is not marked as trusted for the specified purpose.
+
+=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected>
+
+the root CA is marked to reject the specified purpose.
+
+=item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
+
+the current candidate issuer certificate was rejected because its subject name
+did not match the issuer name of the current certificate. Only displayed when
+the B<-issuer_checks> option is set.
+
+=item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
+
+the current candidate issuer certificate was rejected because its subject key
+identifier was present and did not match the authority key identifier current
+certificate. Only displayed when the B<-issuer_checks> option is set.
+
+=item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch>
+
+the current candidate issuer certificate was rejected because its issuer name
+and serial number was present and did not match the authority key identifier
+of the current certificate. Only displayed when the B<-issuer_checks> option is set.
+
+=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
+
+the current candidate issuer certificate was rejected because its keyUsage extension
+does not permit certificate signing.
+
+=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
+
+an application specific error. Unused.
+
+=back
+
+=head1 BUGS
+
+Although the issuer checks are a considerably improvement over the old technique they still
+suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that
+trusted certificates with matching subject name must either appear in a file (as specified by the
+B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only
+the certificates in the file will be recognised.
+
+Previous versions of OpenSSL assume certificates with matching subject name are identical and
+mishandled them.
+
+=head1 SEE ALSO
+
+L<x509(1)|x509(1)>
+
+=cut
diff --git a/doc/apps/version.pod b/doc/apps/version.pod
new file mode 100644
index 000000000000..e00324c446cd
--- /dev/null
+++ b/doc/apps/version.pod
@@ -0,0 +1,64 @@
+=pod
+
+=head1 NAME
+
+version - print OpenSSL version information
+
+=head1 SYNOPSIS
+
+B<openssl version>
+[B<-a>]
+[B<-v>]
+[B<-b>]
+[B<-o>]
+[B<-f>]
+[B<-p>]
+
+=head1 DESCRIPTION
+
+This command is used to print out version information about OpenSSL.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-a>
+
+all information, this is the same as setting all the other flags.
+
+=item B<-v>
+
+the current OpenSSL version.
+
+=item B<-b>
+
+the date the current version of OpenSSL was built.
+
+=item B<-o>
+
+option information: various options set when the library was built.
+
+=item B<-c>
+
+compilation flags.
+
+=item B<-p>
+
+platform setting.
+
+=item B<-d>
+
+OPENSSLDIR setting.
+
+=back
+
+=head1 NOTES
+
+The output of B<openssl version -a> would typically be used when sending
+in a bug report.
+
+=head1 HISTORY
+
+The B<-d> option was added in OpenSSL 0.9.7.
+
+=cut
diff --git a/doc/apps/x509.pod b/doc/apps/x509.pod
new file mode 100644
index 000000000000..a925da41f16a
--- /dev/null
+++ b/doc/apps/x509.pod
@@ -0,0 +1,832 @@
+
+=pod
+
+=head1 NAME
+
+x509 - Certificate display and signing utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<x509>
+[B<-inform DER|PEM|NET>]
+[B<-outform DER|PEM|NET>]
+[B<-keyform DER|PEM>]
+[B<-CAform DER|PEM>]
+[B<-CAkeyform DER|PEM>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-serial>]
+[B<-hash>]
+[B<-subject_hash>]
+[B<-issuer_hash>]
+[B<-subject>]
+[B<-issuer>]
+[B<-nameopt option>]
+[B<-email>]
+[B<-startdate>]
+[B<-enddate>]
+[B<-purpose>]
+[B<-dates>]
+[B<-modulus>]
+[B<-fingerprint>]
+[B<-alias>]
+[B<-noout>]
+[B<-trustout>]
+[B<-clrtrust>]
+[B<-clrreject>]
+[B<-addtrust arg>]
+[B<-addreject arg>]
+[B<-setalias arg>]
+[B<-days arg>]
+[B<-set_serial n>]
+[B<-signkey filename>]
+[B<-x509toreq>]
+[B<-req>]
+[B<-CA filename>]
+[B<-CAkey filename>]
+[B<-CAcreateserial>]
+[B<-CAserial filename>]
+[B<-text>]
+[B<-C>]
+[B<-md2|-md5|-sha1|-mdc2>]
+[B<-clrext>]
+[B<-extfile filename>]
+[B<-extensions section>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<x509> command is a multi purpose certificate utility. It can be
+used to display certificate information, convert certificates to
+various forms, sign certificate requests like a "mini CA" or edit
+certificate trust settings.
+
+Since there are a large number of options they will split up into
+various sections.
+
+=head1 OPTIONS
+
+=head2 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM|NET>
+
+This specifies the input format normally the command will expect an X509
+certificate but this can change if other options such as B<-req> are
+present. The DER format is the DER encoding of the certificate and PEM
+is the base64 encoding of the DER encoding with header and footer lines
+added. The NET option is an obscure Netscape server format that is now
+obsolete.
+
+=item B<-outform DER|PEM|NET>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a certificate from or standard input
+if this option is not specified.
+
+=item B<-out filename>
+
+This specifies the output filename to write to or standard output by
+default.
+
+=item B<-md2|-md5|-sha1|-mdc2>
+
+the digest to use. This affects any signing or display option that uses a message
+digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not
+specified then SHA1 is used. If the key being used to sign with is a DSA key
+then this option has no effect: SHA1 is always used with DSA keys.
+
+=item B<-engine id>
+
+specifying an engine (by it's unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head2 DISPLAY OPTIONS
+
+Note: the B<-alias> and B<-purpose> options are also display options
+but are described in the B<TRUST SETTINGS> section.
+
+=over 4
+
+=item B<-text>
+
+prints out the certificate in text form. Full details are output including the
+public key, signature algorithms, issuer and subject names, serial number
+any extensions present and any trust settings.
+
+=item B<-certopt option>
+
+customise the output format used with B<-text>. The B<option> argument can be
+a single option or multiple options separated by commas. The B<-certopt> switch
+may be also be used more than once to set multiple options. See the B<TEXT OPTIONS>
+section for more information.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the request.
+
+=item B<-modulus>
+
+this option prints out the value of the modulus of the public key
+contained in the certificate.
+
+=item B<-serial>
+
+outputs the certificate serial number.
+
+=item B<-subject_hash>
+
+outputs the "hash" of the certificate subject name. This is used in OpenSSL to
+form an index to allow certificates in a directory to be looked up by subject
+name.
+
+=item B<-issuer_hash>
+
+outputs the "hash" of the certificate issuer name.
+
+=item B<-hash>
+
+synonym for "-hash" for backward compatibility reasons.
+
+=item B<-subject>
+
+outputs the subject name.
+
+=item B<-issuer>
+
+outputs the issuer name.
+
+=item B<-nameopt option>
+
+option which determines how the subject or issuer names are displayed. The
+B<option> argument can be a single option or multiple options separated by
+commas. Alternatively the B<-nameopt> switch may be used more than once to
+set multiple options. See the B<NAME OPTIONS> section for more information.
+
+=item B<-email>
+
+outputs the email address(es) if any.
+
+=item B<-startdate>
+
+prints out the start date of the certificate, that is the notBefore date.
+
+=item B<-enddate>
+
+prints out the expiry date of the certificate, that is the notAfter date.
+
+=item B<-dates>
+
+prints out the start and expiry dates of a certificate.
+
+=item B<-fingerprint>
+
+prints out the digest of the DER encoded version of the whole certificate
+(see digest options).
+
+=item B<-C>
+
+this outputs the certificate in the form of a C source file.
+
+=back
+
+=head2 TRUST SETTINGS
+
+Please note these options are currently experimental and may well change.
+
+A B<trusted certificate> is an ordinary certificate which has several
+additional pieces of information attached to it such as the permitted
+and prohibited uses of the certificate and an "alias".
+
+Normally when a certificate is being verified at least one certificate
+must be "trusted". By default a trusted certificate must be stored
+locally and must be a root CA: any certificate chain ending in this CA
+is then usable for any purpose.
+
+Trust settings currently are only used with a root CA. They allow a finer
+control over the purposes the root CA can be used for. For example a CA
+may be trusted for SSL client but not SSL server use.
+
+See the description of the B<verify> utility for more information on the
+meaning of trust settings.
+
+Future versions of OpenSSL will recognize trust settings on any
+certificate: not just root CAs.
+
+
+=over 4
+
+=item B<-trustout>
+
+this causes B<x509> to output a B<trusted> certificate. An ordinary
+or trusted certificate can be input but by default an ordinary
+certificate is output and any trust settings are discarded. With the
+B<-trustout> option a trusted certificate is output. A trusted
+certificate is automatically output if any trust settings are modified.
+
+=item B<-setalias arg>
+
+sets the alias of the certificate. This will allow the certificate
+to be referred to using a nickname for example "Steve's Certificate".
+
+=item B<-alias>
+
+outputs the certificate alias, if any.
+
+=item B<-clrtrust>
+
+clears all the permitted or trusted uses of the certificate.
+
+=item B<-clrreject>
+
+clears all the prohibited or rejected uses of the certificate.
+
+=item B<-addtrust arg>
+
+adds a trusted certificate use. Any object name can be used here
+but currently only B<clientAuth> (SSL client use), B<serverAuth>
+(SSL server use) and B<emailProtection> (S/MIME email) are used.
+Other OpenSSL applications may define additional uses.
+
+=item B<-addreject arg>
+
+adds a prohibited use. It accepts the same values as the B<-addtrust>
+option.
+
+=item B<-purpose>
+
+this option performs tests on the certificate extensions and outputs
+the results. For a more complete description see the B<CERTIFICATE
+EXTENSIONS> section.
+
+=back
+
+=head2 SIGNING OPTIONS
+
+The B<x509> utility can be used to sign certificates and requests: it
+can thus behave like a "mini CA".
+
+=over 4
+
+=item B<-signkey filename>
+
+this option causes the input file to be self signed using the supplied
+private key.
+
+If the input file is a certificate it sets the issuer name to the
+subject name (i.e. makes it self signed) changes the public key to the
+supplied value and changes the start and end dates. The start date is
+set to the current time and the end date is set to a value determined
+by the B<-days> option. Any certificate extensions are retained unless
+the B<-clrext> option is supplied.
+
+If the input is a certificate request then a self signed certificate
+is created using the supplied private key using the subject name in
+the request.
+
+=item B<-clrext>
+
+delete any extensions from a certificate. This option is used when a
+certificate is being created from another certificate (for example with
+the B<-signkey> or the B<-CA> options). Normally all extensions are
+retained.
+
+=item B<-keyform PEM|DER>
+
+specifies the format (DER or PEM) of the private key file used in the
+B<-signkey> option.
+
+=item B<-days arg>
+
+specifies the number of days to make a certificate valid for. The default
+is 30 days.
+
+=item B<-x509toreq>
+
+converts a certificate into a certificate request. The B<-signkey> option
+is used to pass the required private key.
+
+=item B<-req>
+
+by default a certificate is expected on input. With this option a
+certificate request is expected instead.
+
+=item B<-set_serial n>
+
+specifies the serial number to use. This option can be used with either
+the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA>
+option the serial number file (as specified by the B<-CAserial> or
+B<-CAcreateserial> options) is not used.
+
+The serial number can be decimal or hex (if preceded by B<0x>). Negative
+serial numbers can also be specified but their use is not recommended.
+
+=item B<-CA filename>
+
+specifies the CA certificate to be used for signing. When this option is
+present B<x509> behaves like a "mini CA". The input file is signed by this
+CA using this option: that is its issuer name is set to the subject name
+of the CA and it is digitally signed using the CAs private key.
+
+This option is normally combined with the B<-req> option. Without the
+B<-req> option the input is a certificate which must be self signed.
+
+=item B<-CAkey filename>
+
+sets the CA private key to sign a certificate with. If this option is
+not specified then it is assumed that the CA private key is present in
+the CA certificate file.
+
+=item B<-CAserial filename>
+
+sets the CA serial number file to use.
+
+When the B<-CA> option is used to sign a certificate it uses a serial
+number specified in a file. This file consist of one line containing
+an even number of hex digits with the serial number to use. After each
+use the serial number is incremented and written out to the file again.
+
+The default filename consists of the CA certificate file base name with
+".srl" appended. For example if the CA certificate file is called
+"mycacert.pem" it expects to find a serial number file called "mycacert.srl".
+
+=item B<-CAcreateserial>
+
+with this option the CA serial number file is created if it does not exist:
+it will contain the serial number "02" and the certificate being signed will
+have the 1 as its serial number. Normally if the B<-CA> option is specified
+and the serial number file does not exist it is an error.
+
+=item B<-extfile filename>
+
+file containing certificate extensions to use. If not specified then
+no extensions are added to the certificate.
+
+=item B<-extensions section>
+
+the section to add certificate extensions from. If this option is not
+specified then the extensions should either be contained in the unnamed
+(default) section or the default section should contain a variable called
+"extensions" which contains the section to use.
+
+=back
+
+=head2 NAME OPTIONS
+
+The B<nameopt> command line switch determines how the subject and issuer
+names are displayed. If no B<nameopt> switch is present the default "oneline"
+format is used which is compatible with previous versions of OpenSSL.
+Each option is described in detail below, all options can be preceded by
+a B<-> to turn the option off. Only the first four will normally be used.
+
+=over 4
+
+=item B<compat>
+
+use the old format. This is equivalent to specifying no name options at all.
+
+=item B<RFC2253>
+
+displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>,
+B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>,
+B<sep_comma_plus>, B<dn_rev> and B<sname>.
+
+=item B<oneline>
+
+a oneline format which is more readable than RFC2253. It is equivalent to
+specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>,
+B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname>
+options.
+
+=item B<multiline>
+
+a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
+B<space_eq>, B<lname> and B<align>.
+
+=item B<esc_2253>
+
+escape the "special" characters required by RFC2253 in a field That is
+B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginning of a string
+and a space character at the beginning or end of a string.
+
+=item B<esc_ctrl>
+
+escape control characters. That is those with ASCII values less than
+0x20 (space) and the delete (0x7f) character. They are escaped using the
+RFC2253 \XX notation (where XX are two hex digits representing the
+character value).
+
+=item B<esc_msb>
+
+escape characters with the MSB set, that is with ASCII values larger than
+127.
+
+=item B<use_quote>
+
+escapes some characters by surrounding the whole string with B<"> characters,
+without the option all escaping is done with the B<\> character.
+
+=item B<utf8>
+
+convert all strings to UTF8 format first. This is required by RFC2253. If
+you are lucky enough to have a UTF8 compatible terminal then the use
+of this option (and B<not> setting B<esc_msb>) may result in the correct
+display of multibyte (international) characters. Is this option is not
+present then multibyte characters larger than 0xff will be represented
+using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits.
+Also if this option is off any UTF8Strings will be converted to their
+character form first.
+
+=item B<no_type>
+
+this option does not attempt to interpret multibyte characters in any
+way. That is their content octets are merely dumped as though one octet
+represents each character. This is useful for diagnostic purposes but
+will result in rather odd looking output.
+
+=item B<show_type>
+
+show the type of the ASN1 character string. The type precedes the
+field contents. For example "BMPSTRING: Hello World".
+
+=item B<dump_der>
+
+when this option is set any fields that need to be hexdumped will
+be dumped using the DER encoding of the field. Otherwise just the
+content octets will be displayed. Both options use the RFC2253
+B<#XXXX...> format.
+
+=item B<dump_nostr>
+
+dump non character string types (for example OCTET STRING) if this
+option is not set then non character string types will be displayed
+as though each content octet represents a single character.
+
+=item B<dump_all>
+
+dump all fields. This option when used with B<dump_der> allows the
+DER encoding of the structure to be unambiguously determined.
+
+=item B<dump_unknown>
+
+dump any field whose OID is not recognised by OpenSSL.
+
+=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>,
+B<sep_multiline>
+
+these options determine the field separators. The first character is
+between RDNs and the second between multiple AVAs (multiple AVAs are
+very rare and their use is discouraged). The options ending in
+"space" additionally place a space after the separator to make it
+more readable. The B<sep_multiline> uses a linefeed character for
+the RDN separator and a spaced B<+> for the AVA separator. It also
+indents the fields by four characters.
+
+=item B<dn_rev>
+
+reverse the fields of the DN. This is required by RFC2253. As a side
+effect this also reverses the order of multiple AVAs but this is
+permissible.
+
+=item B<nofname>, B<sname>, B<lname>, B<oid>
+
+these options alter how the field name is displayed. B<nofname> does
+not display the field at all. B<sname> uses the "short name" form
+(CN for commonName for example). B<lname> uses the long form.
+B<oid> represents the OID in numerical form and is useful for
+diagnostic purpose.
+
+=item B<align>
+
+align field values for a more readable output. Only usable with
+B<sep_multiline>.
+
+=item B<space_eq>
+
+places spaces round the B<=> character which follows the field
+name.
+
+=back
+
+=head2 TEXT OPTIONS
+
+As well as customising the name output format, it is also possible to
+customise the actual fields printed using the B<certopt> options when
+the B<text> option is present. The default behaviour is to print all fields.
+
+=over 4
+
+=item B<compatible>
+
+use the old format. This is equivalent to specifying no output options at all.
+
+=item B<no_header>
+
+don't print header information: that is the lines saying "Certificate" and "Data".
+
+=item B<no_version>
+
+don't print out the version number.
+
+=item B<no_serial>
+
+don't print out the serial number.
+
+=item B<no_signame>
+
+don't print out the signature algorithm used.
+
+=item B<no_validity>
+
+don't print the validity, that is the B<notBefore> and B<notAfter> fields.
+
+=item B<no_subject>
+
+don't print out the subject name.
+
+=item B<no_issuer>
+
+don't print out the issuer name.
+
+=item B<no_pubkey>
+
+don't print out the public key.
+
+=item B<no_sigdump>
+
+don't give a hexadecimal dump of the certificate signature.
+
+=item B<no_aux>
+
+don't print out certificate trust information.
+
+=item B<no_extensions>
+
+don't print out any X509V3 extensions.
+
+=item B<ext_default>
+
+retain default extension behaviour: attempt to print out unsupported certificate extensions.
+
+=item B<ext_error>
+
+print an error message for unsupported certificate extensions.
+
+=item B<ext_parse>
+
+ASN1 parse unsupported extensions.
+
+=item B<ext_dump>
+
+hex dump unsupported extensions.
+
+=item B<ca_default>
+
+the value used by the B<ca> utility, equivalent to B<no_issuer>, B<no_pubkey>, B<no_header>,
+B<no_version>, B<no_sigdump> and B<no_signame>.
+
+=back
+
+=head1 EXAMPLES
+
+Note: in these examples the '\' means the example should be all on one
+line.
+
+Display the contents of a certificate:
+
+ openssl x509 -in cert.pem -noout -text
+
+Display the certificate serial number:
+
+ openssl x509 -in cert.pem -noout -serial
+
+Display the certificate subject name:
+
+ openssl x509 -in cert.pem -noout -subject
+
+Display the certificate subject name in RFC2253 form:
+
+ openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
+
+Display the certificate subject name in oneline form on a terminal
+supporting UTF8:
+
+ openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
+
+Display the certificate MD5 fingerprint:
+
+ openssl x509 -in cert.pem -noout -fingerprint
+
+Display the certificate SHA1 fingerprint:
+
+ openssl x509 -sha1 -in cert.pem -noout -fingerprint
+
+Convert a certificate from PEM to DER format:
+
+ openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
+
+Convert a certificate to a certificate request:
+
+ openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
+
+Convert a certificate request into a self signed certificate using
+extensions for a CA:
+
+ openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
+ -signkey key.pem -out cacert.pem
+
+Sign a certificate request using the CA certificate above and add user
+certificate extensions:
+
+ openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
+ -CA cacert.pem -CAkey key.pem -CAcreateserial
+
+
+Set a certificate to be trusted for SSL client use and change set its alias to
+"Steve's Class 1 CA"
+
+ openssl x509 -in cert.pem -addtrust clientAuth \
+ -setalias "Steve's Class 1 CA" -out trust.pem
+
+=head1 NOTES
+
+The PEM format uses the header and footer lines:
+
+ -----BEGIN CERTIFICATE-----
+ -----END CERTIFICATE-----
+
+it will also handle files containing:
+
+ -----BEGIN X509 CERTIFICATE-----
+ -----END X509 CERTIFICATE-----
+
+Trusted certificates have the lines
+
+ -----BEGIN TRUSTED CERTIFICATE-----
+ -----END TRUSTED CERTIFICATE-----
+
+The conversion to UTF8 format used with the name options assumes that
+T61Strings use the ISO8859-1 character set. This is wrong but Netscape
+and MSIE do this as do many certificates. So although this is incorrect
+it is more likely to display the majority of certificates correctly.
+
+The B<-fingerprint> option takes the digest of the DER encoded certificate.
+This is commonly called a "fingerprint". Because of the nature of message
+digests the fingerprint of a certificate is unique to that certificate and
+two certificates with the same fingerprint can be considered to be the same.
+
+The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
+
+The B<-email> option searches the subject name and the subject alternative
+name extension. Only unique email addresses will be printed out: it will
+not print the same address more than once.
+
+=head1 CERTIFICATE EXTENSIONS
+
+The B<-purpose> option checks the certificate extensions and determines
+what the certificate can be used for. The actual checks done are rather
+complex and include various hacks and workarounds to handle broken
+certificates and software.
+
+The same code is used when verifying untrusted certificates in chains
+so this section is useful if a chain is rejected by the verify code.
+
+The basicConstraints extension CA flag is used to determine whether the
+certificate can be used as a CA. If the CA flag is true then it is a CA,
+if the CA flag is false then it is not a CA. B<All> CAs should have the
+CA flag set to true.
+
+If the basicConstraints extension is absent then the certificate is
+considered to be a "possible CA" other extensions are checked according
+to the intended use of the certificate. A warning is given in this case
+because the certificate should really not be regarded as a CA: however
+it is allowed to be a CA to work around some broken software.
+
+If the certificate is a V1 certificate (and thus has no extensions) and
+it is self signed it is also assumed to be a CA but a warning is again
+given: this is to work around the problem of Verisign roots which are V1
+self signed certificates.
+
+If the keyUsage extension is present then additional restraints are
+made on the uses of the certificate. A CA certificate B<must> have the
+keyCertSign bit set if the keyUsage extension is present.
+
+The extended key usage extension places additional restrictions on the
+certificate uses. If this extension is present (whether critical or not)
+the key can only be used for the purposes specified.
+
+A complete description of each test is given below. The comments about
+basicConstraints and keyUsage and V1 certificates above apply to B<all>
+CA certificates.
+
+
+=over 4
+
+=item B<SSL Client>
+
+The extended key usage extension must be absent or include the "web client
+authentication" OID. keyUsage must be absent or it must have the
+digitalSignature bit set. Netscape certificate type must be absent or it must
+have the SSL client bit set.
+
+=item B<SSL Client CA>
+
+The extended key usage extension must be absent or include the "web client
+authentication" OID. Netscape certificate type must be absent or it must have
+the SSL CA bit set: this is used as a work around if the basicConstraints
+extension is absent.
+
+=item B<SSL Server>
+
+The extended key usage extension must be absent or include the "web server
+authentication" and/or one of the SGC OIDs. keyUsage must be absent or it
+must have the digitalSignature, the keyEncipherment set or both bits set.
+Netscape certificate type must be absent or have the SSL server bit set.
+
+=item B<SSL Server CA>
+
+The extended key usage extension must be absent or include the "web server
+authentication" and/or one of the SGC OIDs. Netscape certificate type must
+be absent or the SSL CA bit must be set: this is used as a work around if the
+basicConstraints extension is absent.
+
+=item B<Netscape SSL Server>
+
+For Netscape SSL clients to connect to an SSL server it must have the
+keyEncipherment bit set if the keyUsage extension is present. This isn't
+always valid because some cipher suites use the key for digital signing.
+Otherwise it is the same as a normal SSL server.
+
+=item B<Common S/MIME Client Tests>
+
+The extended key usage extension must be absent or include the "email
+protection" OID. Netscape certificate type must be absent or should have the
+S/MIME bit set. If the S/MIME bit is not set in netscape certificate type
+then the SSL client bit is tolerated as an alternative but a warning is shown:
+this is because some Verisign certificates don't set the S/MIME bit.
+
+=item B<S/MIME Signing>
+
+In addition to the common S/MIME client tests the digitalSignature bit must
+be set if the keyUsage extension is present.
+
+=item B<S/MIME Encryption>
+
+In addition to the common S/MIME tests the keyEncipherment bit must be set
+if the keyUsage extension is present.
+
+=item B<S/MIME CA>
+
+The extended key usage extension must be absent or include the "email
+protection" OID. Netscape certificate type must be absent or must have the
+S/MIME CA bit set: this is used as a work around if the basicConstraints
+extension is absent.
+
+=item B<CRL Signing>
+
+The keyUsage extension must be absent or it must have the CRL signing bit
+set.
+
+=item B<CRL Signing CA>
+
+The normal CA tests apply. Except in this case the basicConstraints extension
+must be present.
+
+=back
+
+=head1 BUGS
+
+Extensions in certificates are not transferred to certificate requests and
+vice versa.
+
+It is possible to produce invalid certificates or requests by specifying the
+wrong private key or using inconsistent options in some cases: these should
+be checked.
+
+There should be options to explicitly set such things as start and end
+dates rather than an offset from the current time.
+
+The code to implement the verify behaviour described in the B<TRUST SETTINGS>
+is currently being developed. It thus describes the intended behaviour rather
+than the current behaviour. It is hoped that it will represent reality in
+OpenSSL 0.9.5 and later.
+
+=head1 SEE ALSO
+
+L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
+L<gendsa(1)|gendsa(1)>, L<verify(1)|verify(1)>
+
+=head1 HISTORY
+
+Before OpenSSL 0.9.8, the default digest for RSA keys was MD5.
+
+=cut
diff --git a/doc/apps/x509v3_config.pod b/doc/apps/x509v3_config.pod
new file mode 100644
index 000000000000..38c46e85c461
--- /dev/null
+++ b/doc/apps/x509v3_config.pod
@@ -0,0 +1,456 @@
+=pod
+
+=for comment openssl_manual_section:5
+
+=head1 NAME
+
+x509v3_config - X509 V3 certificate extension configuration format
+
+=head1 DESCRIPTION
+
+Several of the OpenSSL utilities can add extensions to a certificate or
+certificate request based on the contents of a configuration file.
+
+Typically the application will contain an option to point to an extension
+section. Each line of the extension section takes the form:
+
+ extension_name=[critical,] extension_options
+
+If B<critical> is present then the extension will be critical.
+
+The format of B<extension_options> depends on the value of B<extension_name>.
+
+There are four main types of extension: I<string> extensions, I<multi-valued>
+extensions, I<raw> and I<arbitrary> extensions.
+
+String extensions simply have a string which contains either the value itself
+or how it is obtained.
+
+For example:
+
+ nsComment="This is a Comment"
+
+Multi-valued extensions have a short form and a long form. The short form
+is a list of names and values:
+
+ basicConstraints=critical,CA:true,pathlen:1
+
+The long form allows the values to be placed in a separate section:
+
+ basicConstraints=critical,@bs_section
+
+ [bs_section]
+
+ CA=true
+ pathlen=1
+
+Both forms are equivalent.
+
+The syntax of raw extensions is governed by the extension code: it can
+for example contain data in multiple sections. The correct syntax to
+use is defined by the extension code itself: check out the certificate
+policies extension for an example.
+
+If an extension type is unsupported then the I<arbitrary> extension syntax
+must be used, see the L<ARBITRART EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details.
+
+=head1 STANDARD EXTENSIONS
+
+The following sections describe each supported extension in detail.
+
+=head2 Basic Constraints.
+
+This is a multi valued extension which indicates whether a certificate is
+a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or
+B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by an
+non-negative value can be included.
+
+For example:
+
+ basicConstraints=CA:TRUE
+
+ basicConstraints=CA:FALSE
+
+ basicConstraints=critical,CA:TRUE, pathlen:0
+
+A CA certificate B<must> include the basicConstraints value with the CA field
+set to TRUE. An end user certificate must either set CA to FALSE or exclude the
+extension entirely. Some software may require the inclusion of basicConstraints
+with CA set to FALSE for end entity certificates.
+
+The pathlen parameter indicates the maximum number of CAs that can appear
+below this one in a chain. So if you have a CA with a pathlen of zero it can
+only be used to sign end user certificates and not further CAs.
+
+
+=head2 Key Usage.
+
+Key usage is a multi valued extension consisting of a list of names of the
+permitted key usages.
+
+The supporte names are: digitalSignature, nonRepudiation, keyEncipherment,
+dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
+and decipherOnly.
+
+Examples:
+
+ keyUsage=digitalSignature, nonRepudiation
+
+ keyUsage=critical, keyCertSign
+
+
+=head2 Extended Key Usage.
+
+This extensions consists of a list of usages indicating purposes for which
+the certificate public key can be used for,
+
+These can either be object short names of the dotted numerical form of OIDs.
+While any OID can be used only certain values make sense. In particular the
+following PKIX, NS and MS values are meaningful:
+
+ Value Meaning
+ ----- -------
+ serverAuth SSL/TLS Web Server Authentication.
+ clientAuth SSL/TLS Web Client Authentication.
+ codeSigning Code signing.
+ emailProtection E-mail Protection (S/MIME).
+ timeStamping Trusted Timestamping
+ msCodeInd Microsoft Individual Code Signing (authenticode)
+ msCodeCom Microsoft Commercial Code Signing (authenticode)
+ msCTLSign Microsoft Trust List Signing
+ msSGC Microsoft Server Gated Crypto
+ msEFS Microsoft Encrypted File System
+ nsSGC Netscape Server Gated Crypto
+
+Examples:
+
+ extendedKeyUsage=critical,codeSigning,1.2.3.4
+ extendedKeyUsage=nsSGC,msSGC
+
+
+=head2 Subject Key Identifier.
+
+This is really a string extension and can take two possible values. Either
+the word B<hash> which will automatically follow the guidelines in RFC3280
+or a hex string giving the extension value to include. The use of the hex
+string is strongly discouraged.
+
+Example:
+
+ subjectKeyIdentifier=hash
+
+
+=head2 Authority Key Identifier.
+
+The authority key identifier extension permits two options. keyid and issuer:
+both can take the optional value "always".
+
+If the keyid option is present an attempt is made to copy the subject key
+identifier from the parent certificate. If the value "always" is present
+then an error is returned if the option fails.
+
+The issuer option copies the issuer and serial number from the issuer
+certificate. This will only be done if the keyid option fails or
+is not included unless the "always" flag will always include the value.
+
+Example:
+
+ authorityKeyIdentifier=keyid,issuer
+
+
+=head2 Subject Alternative Name.
+
+The subject alternative name extension allows various literal values to be
+included in the configuration file. These include B<email> (an email address)
+B<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a
+registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName>
+(a distinguished name) and otherName.
+
+The email option include a special 'copy' value. This will automatically
+include and email addresses contained in the certificate subject name in
+the extension.
+
+The IP address used in the B<IP> options can be in either IPv4 or IPv6 format.
+
+The value of B<dirName> should point to a section containing the distinguished
+name to use as a set of name value pairs. Multi values AVAs can be formed by
+preceeding the name with a B<+> character.
+
+otherName can include arbitrary data associated with an OID: the value
+should be the OID followed by a semicolon and the content in standard
+ASN1_generate_nconf() format.
+
+Examples:
+
+ subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/
+ subjectAltName=IP:192.168.7.1
+ subjectAltName=IP:13::17
+ subjectAltName=email:my@other.address,RID:1.2.3.4
+ subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
+
+ subjectAltName=dirName:dir_sect
+
+ [dir_sect]
+ C=UK
+ O=My Organization
+ OU=My Unit
+ CN=My Name
+
+
+=head2 Issuer Alternative Name.
+
+The issuer alternative name option supports all the literal options of
+subject alternative name. It does B<not> support the email:copy option because
+that would not make sense. It does support an additional issuer:copy option
+that will copy all the subject alternative name values from the issuer
+certificate (if possible).
+
+Example:
+
+ issuserAltName = issuer:copy
+
+
+=head2 Authority Info Access.
+
+The authority information access extension gives details about how to access
+certain information relating to the CA. Its syntax is accessOID;location
+where I<location> has the same syntax as subject alternative name (except
+that email:copy is not supported). accessOID can be any valid OID but only
+certain values are meaningful, for example OCSP and caIssuers.
+
+Example:
+
+ authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
+ authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
+
+
+=head2 CRL distribution points.
+
+This is a multi-valued extension that supports all the literal options of
+subject alternative name. Of the few software packages that currently interpret
+this extension most only interpret the URI option.
+
+Currently each option will set a new DistributionPoint with the fullName
+field set to the given value.
+
+Other fields like cRLissuer and reasons cannot currently be set or displayed:
+at this time no examples were available that used these fields.
+
+Examples:
+
+ crlDistributionPoints=URI:http://myhost.com/myca.crl
+ crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
+
+=head2 Certificate Policies.
+
+This is a I<raw> extension. All the fields of this extension can be set by
+using the appropriate syntax.
+
+If you follow the PKIX recommendations and just using one OID then you just
+include the value of that OID. Multiple OIDs can be set separated by commas,
+for example:
+
+ certificatePolicies= 1.2.4.5, 1.1.3.4
+
+If you wish to include qualifiers then the policy OID and qualifiers need to
+be specified in a separate section: this is done by using the @section syntax
+instead of a literal OID value.
+
+The section referred to must include the policy OID using the name
+policyIdentifier, cPSuri qualifiers can be included using the syntax:
+
+ CPS.nnn=value
+
+userNotice qualifiers can be set using the syntax:
+
+ userNotice.nnn=@notice
+
+The value of the userNotice qualifier is specified in the relevant section.
+This section can include explicitText, organization and noticeNumbers
+options. explicitText and organization are text strings, noticeNumbers is a
+comma separated list of numbers. The organization and noticeNumbers options
+(if included) must BOTH be present. If you use the userNotice option with IE5
+then you need the 'ia5org' option at the top level to modify the encoding:
+otherwise it will not be interpreted properly.
+
+Example:
+
+ certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
+
+ [polsect]
+
+ policyIdentifier = 1.3.5.8
+ CPS.1="http://my.host.name/"
+ CPS.2="http://my.your.name/"
+ userNotice.1=@notice
+
+ [notice]
+
+ explicitText="Explicit Text Here"
+ organization="Organisation Name"
+ noticeNumbers=1,2,3,4
+
+The B<ia5org> option changes the type of the I<organization> field. In RFC2459
+it can only be of type DisplayText. In RFC3280 IA5Strring is also permissible.
+Some software (for example some versions of MSIE) may require ia5org.
+
+=head2 Policy Constraints
+
+This is a multi-valued extension which consisting of the names
+B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative intger
+value. At least one component must be present.
+
+Example:
+
+ policyConstraints = requireExplicitPolicy:3
+
+
+=head2 Inhibit Any Policy
+
+This is a string extension whose value must be a non negative integer.
+
+Example:
+
+ inhibitAnyPolicy = 2
+
+
+=head2 Name Constraints
+
+The name constraints extension is a multi-valued extension. The name should
+begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
+the name and the value follows the syntax of subjectAltName except email:copy
+is not supported and the B<IP> form should consist of an IP addresses and
+subnet mask separated by a B</>.
+
+Examples:
+
+ nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
+
+ nameConstraints=permitted;email:.somedomain.com
+
+ nameConstraints=excluded;email:.com
+
+=head1 DEPRECATED EXTENSIONS
+
+The following extensions are non standard, Netscape specific and largely
+obsolete. Their use in new applications is discouraged.
+
+=head2 Netscape String extensions.
+
+Netscape Comment (B<nsComment>) is a string extension containing a comment
+which will be displayed when the certificate is viewed in some browsers.
+
+Example:
+
+ nsComment = "Some Random Comment"
+
+Other supported extensions in this category are: B<nsBaseUrl>,
+B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
+and B<nsSslServerName>.
+
+
+=head2 Netscape Certificate Type
+
+This is a multi-valued extensions which consists of a list of flags to be
+included. It was used to indicate the purposes for which a certificate could
+be used. The basicConstraints, keyUsage and extended key usage extensions are
+now used instead.
+
+Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
+B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
+
+
+=head1 ARBITRARY EXTENSIONS
+
+If an extension is not supported by the OpenSSL code then it must be encoded
+using the arbitrary extension format. It is also possible to use the arbitrary
+format for supported extensions. Extreme care should be taken to ensure that
+the data is formatted correctly for the given extension type.
+
+There are two ways to encode arbitrary extensions.
+
+The first way is to use the word ASN1 followed by the extension content
+using the same syntax as ASN1_generate_nconf(). For example:
+
+ 1.2.3.4=critical,ASN1:UTF8String:Some random data
+
+ 1.2.3.4=ASN1:SEQUENCE:seq_sect
+
+ [seq_sect]
+
+ field1 = UTF8:field1
+ field2 = UTF8:field2
+
+It is also possible to use the word DER to include the raw encoded data in any
+extension.
+
+ 1.2.3.4=critical,DER:01:02:03:04
+ 1.2.3.4=DER:01020304
+
+The value following DER is a hex dump of the DER encoding of the extension
+Any extension can be placed in this form to override the default behaviour.
+For example:
+
+ basicConstraints=critical,DER:00:01:02:03
+
+=head1 WARNING
+
+There is no guarantee that a specific implementation will process a given
+extension. It may therefore be sometimes possible to use certificates for
+purposes prohibited by their extensions because a specific application does
+not recognize or honour the values of the relevant extensions.
+
+The DER and ASN1 options should be used with caution. It is possible to create
+totally invalid extensions if they are not used carefully.
+
+
+=head1 NOTES
+
+If an extension is multi-value and a field value must contain a comma the long
+form must be used otherwise the comma would be misinterpreted as a field
+separator. For example:
+
+ subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
+
+will produce an error but the equivalent form:
+
+ subjectAltName=@subject_alt_section
+
+ [subject_alt_section]
+ subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
+
+is valid.
+
+Due to the behaviour of the OpenSSL B<conf> library the same field name
+can only occur once in a section. This means that:
+
+ subjectAltName=@alt_section
+
+ [alt_section]
+
+ email=steve@here
+ email=steve@there
+
+will only recognize the last value. This can be worked around by using the form:
+
+ [alt_section]
+
+ email.1=steve@here
+ email.2=steve@there
+
+=head1 HISTORY
+
+The X509v3 extension code was first added to OpenSSL 0.9.2.
+
+Policy mappings, inhibit any policy and name constraints support was added in
+OpenSSL 0.9.8
+
+The B<directoryName> and B<otherName> option as well as the B<ASN1> option
+for arbitrary extensions was added in OpenSSL 0.9.8
+
+=head1 SEE ALSO
+
+L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>
+
+
+=cut
diff --git a/doc/c-indentation.el b/doc/c-indentation.el
new file mode 100644
index 000000000000..cbf01cb1720a
--- /dev/null
+++ b/doc/c-indentation.el
@@ -0,0 +1,44 @@
+; This Emacs Lisp file defines a C indentation style that closely
+; follows most aspects of the one that is used throughout SSLeay,
+; and hence in OpenSSL.
+;
+; This definition is for the "CC mode" package, which is the default
+; mode for editing C source files in Emacs 20, not for the older
+; c-mode.el (which was the default in less recent releaes of Emacs 19).
+;
+; Copy the definition in your .emacs file or use M-x eval-buffer.
+; To activate this indentation style, visit a C file, type
+; M-x c-set-style <RET> (or C-c . for short), and enter "eay".
+; To toggle the auto-newline feature of CC mode, type C-c C-a.
+;
+; Apparently statement blocks that are not introduced by a statement
+; such as "if" and that are not the body of a function cannot
+; be handled too well by CC mode with this indentation style,
+; so you have to indent them manually (you can use C-q tab).
+;
+; For suggesting improvements, please send e-mail to bodo@openssl.org.
+
+(c-add-style "eay"
+ '((c-basic-offset . 8)
+ (c-comment-only-line-offset . 0)
+ (c-hanging-braces-alist)
+ (c-offsets-alist . ((defun-open . +)
+ (defun-block-intro . 0)
+ (class-open . +)
+ (class-close . +)
+ (block-open . 0)
+ (block-close . 0)
+ (substatement-open . +)
+ (statement . 0)
+ (statement-block-intro . 0)
+ (statement-case-open . +)
+ (statement-case-intro . +)
+ (case-label . -)
+ (label . -)
+ (arglist-cont-nonempty . +)
+ (topmost-intro . -)
+ (brace-list-close . 0)
+ (brace-list-intro . 0)
+ (brace-list-open . +)
+ ))))
+
diff --git a/doc/crypto/ASN1_OBJECT_new.pod b/doc/crypto/ASN1_OBJECT_new.pod
new file mode 100644
index 000000000000..51679bfcd97c
--- /dev/null
+++ b/doc/crypto/ASN1_OBJECT_new.pod
@@ -0,0 +1,43 @@
+=pod
+
+=head1 NAME
+
+ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions
+
+=head1 SYNOPSIS
+
+ ASN1_OBJECT *ASN1_OBJECT_new(void);
+ void ASN1_OBJECT_free(ASN1_OBJECT *a);
+
+=head1 DESCRIPTION
+
+The ASN1_OBJECT allocation routines, allocate and free an
+ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.
+
+ASN1_OBJECT_new() allocates and initializes a ASN1_OBJECT structure.
+
+ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.
+
+=head1 NOTES
+
+Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it
+is almost never used in applications. The ASN1 object utility functions
+such as OBJ_nid2obj() are used instead.
+
+=head1 RETURN VALUES
+
+If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error
+code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+Otherwise it returns a pointer to the newly allocated structure.
+
+ASN1_OBJECT_free() returns no value.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)|d2i_ASN1_OBJECT(3)>
+
+=head1 HISTORY
+
+ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/ASN1_STRING_length.pod b/doc/crypto/ASN1_STRING_length.pod
new file mode 100644
index 000000000000..c4ec693f17bd
--- /dev/null
+++ b/doc/crypto/ASN1_STRING_length.pod
@@ -0,0 +1,81 @@
+=pod
+
+=head1 NAME
+
+ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
+ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data -
+ASN1_STRING utility functions
+
+=head1 SYNOPSIS
+
+ int ASN1_STRING_length(ASN1_STRING *x);
+ unsigned char * ASN1_STRING_data(ASN1_STRING *x);
+
+ ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
+
+ int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
+
+ int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
+
+ int ASN1_STRING_type(ASN1_STRING *x);
+
+ int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in);
+
+=head1 DESCRIPTION
+
+These functions allow an B<ASN1_STRING> structure to be manipulated.
+
+ASN1_STRING_length() returns the length of the content of B<x>.
+
+ASN1_STRING_data() returns an internal pointer to the data of B<x>.
+Since this is an internal pointer it should B<not> be freed or
+modified in any way.
+
+ASN1_STRING_dup() returns a copy of the structure B<a>.
+
+ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two
+are identical. The string types and content are compared.
+
+ASN1_STRING_set() sets the data of string B<str> to the buffer
+B<data> or length B<len>. The supplied data is copied. If B<len>
+is -1 then the length is determined by strlen(data).
+
+ASN1_STRING_type() returns the type of B<x>, using standard constants
+such as B<V_ASN1_OCTET_STRING>.
+
+ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the
+converted data is allocated in a buffer in B<*out>. The length of
+B<out> is returned or a negative error code. The buffer B<*out>
+should be free using OPENSSL_free().
+
+=head1 NOTES
+
+Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING>
+structure. Other types such as B<ASN1_OCTET_STRING> are simply typedefed
+to B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents.
+B<ASN1_STRING> is also used for some B<CHOICE> types which consist
+entirely of primitive string types such as B<DirectoryString> and
+B<Time>.
+
+These functions should B<not> be used to examine or modify B<ASN1_INTEGER>
+or B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED>
+utility functions should be used instead.
+
+In general it cannot be assumed that the data returned by ASN1_STRING_data()
+is null terminated or does not contain embedded nulls. The actual format
+of the data will depend on the actual string type itself: for example
+for and IA5String the data will be ASCII, for a BMPString two bytes per
+character in big endian format, UTF8String will be in UTF8 format.
+
+Similar care should be take to ensure the data is in the correct format
+when calling ASN1_STRING_set().
+
+=head1 RETURN VALUES
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+=cut
diff --git a/doc/crypto/ASN1_STRING_new.pod b/doc/crypto/ASN1_STRING_new.pod
new file mode 100644
index 000000000000..5b1bbb7eb21f
--- /dev/null
+++ b/doc/crypto/ASN1_STRING_new.pod
@@ -0,0 +1,44 @@
+=pod
+
+=head1 NAME
+
+ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free -
+ASN1_STRING allocation functions
+
+=head1 SYNOPSIS
+
+ ASN1_STRING * ASN1_STRING_new(void);
+ ASN1_STRING * ASN1_STRING_type_new(int type);
+ void ASN1_STRING_free(ASN1_STRING *a);
+
+=head1 DESCRIPTION
+
+ASN1_STRING_new() returns an allocated B<ASN1_STRING> structure. Its type
+is undefined.
+
+ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of
+type B<type>.
+
+ASN1_STRING_free() frees up B<a>.
+
+=head1 NOTES
+
+Other string types call the B<ASN1_STRING> functions. For example
+ASN1_OCTET_STRING_new() calls ASN1_STRING_type(V_ASN1_OCTET_STRING).
+
+=head1 RETURN VALUES
+
+ASN1_STRING_new() and ASN1_STRING_type_new() return a valid
+ASN1_STRING structure or B<NULL> if an error occurred.
+
+ASN1_STRING_free() does not return a value.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/doc/crypto/ASN1_STRING_print_ex.pod b/doc/crypto/ASN1_STRING_print_ex.pod
new file mode 100644
index 000000000000..3891b88791dd
--- /dev/null
+++ b/doc/crypto/ASN1_STRING_print_ex.pod
@@ -0,0 +1,96 @@
+=pod
+
+=head1 NAME
+
+ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp - ASN1_STRING output routines.
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1.h>
+
+ int ASN1_STRING_print_ex(BIO *out, ASN1_STRING *str, unsigned long flags);
+ int ASN1_STRING_print_ex_fp(FILE *fp, ASN1_STRING *str, unsigned long flags);
+ int ASN1_STRING_print(BIO *out, ASN1_STRING *str);
+
+
+=head1 DESCRIPTION
+
+These functions output an B<ASN1_STRING> structure. B<ASN1_STRING> is used to
+represent all the ASN1 string types.
+
+ASN1_STRING_print_ex() outputs B<str> to B<out>, the format is determined by
+the options B<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs
+to B<fp> instead.
+
+ASN1_STRING_print() prints B<str> to B<out> but using a different format to
+ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF)
+with '.'.
+
+=head1 NOTES
+
+ASN1_STRING_print() is a legacy function which should be avoided in new applications.
+
+Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is
+suitable, or on UTF8 terminals B<ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB>.
+
+The complete set of supported options for B<flags> is listed below.
+
+Various characters can be escaped. If B<ASN1_STRFLGS_ESC_2253> is set the characters
+determined by RFC2253 are escaped. If B<ASN1_STRFLGS_ESC_CTRL> is set control
+characters are escaped. If B<ASN1_STRFLGS_ESC_MSB> is set characters with the
+MSB set are escaped: this option should B<not> be used if the terminal correctly
+interprets UTF8 sequences.
+
+Escaping takes several forms.
+
+If the character being escaped is a 16 bit character then the form "\UXXXX" is used
+using exactly four characters for the hex representation. If it is 32 bits then
+"\WXXXXXXXX" is used using eight characters of its hex representation. These forms
+will only be used if UTF8 conversion is not set (see below).
+
+Printable characters are normally escaped using the backslash '\' character. If
+B<ASN1_STRFLGS_ESC_QUOTE> is set then the whole string is instead surrounded by
+double quote characters: this is arguably more readable than the backslash
+notation. Other characters use the "\XX" using exactly two characters of the hex
+representation.
+
+If B<ASN1_STRFLGS_UTF8_CONVERT> is set then characters are converted to UTF8
+format first. If the terminal supports the display of UTF8 sequences then this
+option will correctly display multi byte characters.
+
+If B<ASN1_STRFLGS_IGNORE_TYPE> is set then the string type is not interpreted at
+all: everything is assumed to be one byte per character. This is primarily for
+debugging purposes and can result in confusing output in multi character strings.
+
+If B<ASN1_STRFLGS_SHOW_TYPE> is set then the string type itself is printed out
+before its value (for example "BMPSTRING"), this actually uses ASN1_tag2str().
+
+The content of a string instead of being interpreted can be "dumped": this just
+outputs the value of the string using the form #XXXX using hex format for each
+octet.
+
+If B<ASN1_STRFLGS_DUMP_ALL> is set then any type is dumped.
+
+Normally non character string types (such as OCTET STRING) are assumed to be
+one byte per character, if B<ASN1_STRFLGS_DUMP_UNKNOWN> is set then they will
+be dumped instead.
+
+When a type is dumped normally just the content octets are printed, if
+B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped
+instead (including tag and length octets).
+
+B<ASN1_STRFLGS_RFC2253> includes all the flags required by RFC2253. It is
+equivalent to:
+ ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB |
+ ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER
+
+=head1 SEE ALSO
+
+L<X509_NAME_print_ex(3)|X509_NAME_print_ex(3)>,
+L<ASN1_tag2str(3)|ASN1_tag2str(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/doc/crypto/ASN1_generate_nconf.pod b/doc/crypto/ASN1_generate_nconf.pod
new file mode 100644
index 000000000000..ba6e3c2e8140
--- /dev/null
+++ b/doc/crypto/ASN1_generate_nconf.pod
@@ -0,0 +1,253 @@
+=pod
+
+=head1 NAME
+
+ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
+
+=head1 SYNOPSIS
+
+ ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
+ ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
+
+=head1 DESCRIPTION
+
+These functions generate the ASN1 encoding of a string
+in an B<ASN1_TYPE> structure.
+
+B<str> contains the string to encode B<nconf> or B<cnf> contains
+the optional configuration information where additional strings
+will be read from. B<nconf> will typically come from a config
+file wherease B<cnf> is obtained from an B<X509V3_CTX> structure
+which will typically be used by X509 v3 certificate extension
+functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
+configuration will be used.
+
+=head1 GENERATION STRING FORMAT
+
+The actual data encoded is determined by the string B<str> and
+the configuration information. The general format of the string
+is:
+
+ B<[modifier,]type[:value]>
+
+That is zero or more comma separated modifiers followed by a type
+followed by an optional colon and a value. The formats of B<type>,
+B<value> and B<modifier> are explained below.
+
+=head2 SUPPORTED TYPES
+
+The supported types are listed below. Unless otherwise specified
+only the B<ASCII> format is permissible.
+
+=over 2
+
+=item B<BOOLEAN>, B<BOOL>
+
+This encodes a boolean type. The B<value> string is mandatory and
+should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
+B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no>
+are acceptable.
+
+=item B<NULL>
+
+Encode the B<NULL> type, the B<value> string must not be present.
+
+=item B<INTEGER>, B<INT>
+
+Encodes an ASN1 B<INTEGER> type. The B<value> string represents
+the value of the integer, it can be preceeded by a minus sign and
+is normally interpreted as a decimal value unless the prefix B<0x>
+is included.
+
+=item B<ENUMERATED>, B<ENUM>
+
+Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to
+B<INTEGER>.
+
+=item B<OBJECT>, B<OID>
+
+Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
+a short name, a long name or numerical format.
+
+=item B<UTCTIME>, B<UTC>
+
+Encodes an ASN1 B<UTCTime> structure, the value should be in
+the format B<YYMMDDHHMMSSZ>.
+
+=item B<GENERALIZEDTIME>, B<GENTIME>
+
+Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
+the format B<YYYYMMDDHHMMSSZ>.
+
+=item B<OCTETSTRING>, B<OCT>
+
+Emcodes an ASN1 B<OCTET STRING>. B<value> represents the contents
+of this structure, the format strings B<ASCII> and B<HEX> can be
+used to specify the format of B<value>.
+
+=item B<BITSRING>, B<BITSTR>
+
+Emcodes an ASN1 B<BIT STRING>. B<value> represents the contents
+of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
+can be used to specify the format of B<value>.
+
+If the format is anything other than B<BITLIST> the number of unused
+bits is set to zero.
+
+=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
+B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
+B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
+B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>
+
+These encode the corresponding string types. B<value> represents the
+contents of this structure. The format can be B<ASCII> or B<UTF8>.
+
+=item B<SEQUENCE>, B<SEQ>, B<SET>
+
+Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
+should be a section name which will contain the contents. The
+field names in the section are ignored and the values are in the
+generated string format. If B<value> is absent then an empty SEQUENCE
+will be encoded.
+
+=back
+
+=head2 MODIFIERS
+
+Modifiers affect the following structure, they can be used to
+add EXPLICIT or IMPLICIT tagging, add wrappers or to change
+the string format of the final type and value. The supported
+formats are documented below.
+
+=over 2
+
+=item B<EXPLICIT>, B<EXP>
+
+Add an explicit tag to the following structure. This string
+should be followed by a colon and the tag value to use as a
+decimal value.
+
+By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL,
+APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used,
+the default is CONTEXT SPECIFIC.
+
+=item B<IMPLICIT>, B<IMP>
+
+This is the same as B<EXPLICIT> except IMPLICIT tagging is used
+instead.
+
+=item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP>
+
+The following structure is surrounded by an OCTET STRING, a SEQUENCE,
+a SET or a BIT STRING respectively. For a BIT STRING the number of unused
+bits is set to zero.
+
+=item B<FORMAT>
+
+This specifies the format of the ultimate value. It should be followed
+by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>.
+
+If no format specifier is included then B<ASCII> is used. If B<UTF8> is specified
+then the value string must be a valid B<UTF8> string. For B<HEX> the output must
+be a set of hex digits. B<BITLIST> (which is only valid for a BIT STRING) is a
+comma separated list of set bits.
+
+=back
+
+=head1 EXAMPLES
+
+A simple IA5String:
+
+ IA5STRING:Hello World
+
+An IA5String explicitly tagged:
+
+ EXPLICIT:0,IA5STRING:Hello World
+
+An IA5String explicitly tagged using APPLICATION tagging:
+
+ EXPLICIT:0A,IA5STRING:Hello World
+
+A more complex example using a config file to produce a
+SEQUENCE consiting of a BOOL an OID and a UTF8String:
+
+asn1 = SEQUENCE:seq_section
+
+[seq_section]
+
+field1 = BOOLEAN:TRUE
+field2 = OID:commonName
+field3 = UTF8:Third field
+
+This example produces an RSAPrivateKey structure, this is the
+key contained in the file client.pem in all OpenSSL distributions
+(note: the field names such as 'coeff' are ignored and are present just
+for clarity):
+
+ asn1=SEQUENCE:private_key
+ [private_key]
+ version=INTEGER:0
+
+ n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
+ D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
+
+ e=INTEGER:0x010001
+
+ d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
+ F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
+
+ p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
+ D4BD57
+
+ q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
+ 46EC4F
+
+ exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
+ 9C0A39B9
+
+ exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
+ E7B2458F
+
+ coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
+ 628657053A
+
+This example is the corresponding public key in a SubjectPublicKeyInfo
+structure:
+
+ # Start with a SEQUENCE
+ asn1=SEQUENCE:pubkeyinfo
+
+ # pubkeyinfo contains an algorithm identifier and the public key wrapped
+ # in a BIT STRING
+ [pubkeyinfo]
+ algorithm=SEQUENCE:rsa_alg
+ pubkey=BITWRAP,SEQUENCE:rsapubkey
+
+ # algorithm ID for RSA is just an OID and a NULL
+ [rsa_alg]
+ algorithm=OID:rsaEncryption
+ parameter=NULL
+
+ # Actual public key: modulus and exponent
+ [rsapubkey]
+ n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
+ D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
+
+ e=INTEGER:0x010001
+
+=head1 RETURN VALUES
+
+ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
+data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
+
+The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8
+
+=cut
diff --git a/doc/crypto/BIO_ctrl.pod b/doc/crypto/BIO_ctrl.pod
new file mode 100644
index 000000000000..722e8b8f46c9
--- /dev/null
+++ b/doc/crypto/BIO_ctrl.pod
@@ -0,0 +1,128 @@
+=pod
+
+=head1 NAME
+
+BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
+BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
+BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
+BIO_get_info_callback, BIO_set_info_callback - BIO control operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg);
+ long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long));
+ char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg);
+ long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg);
+
+ int BIO_reset(BIO *b);
+ int BIO_seek(BIO *b, int ofs);
+ int BIO_tell(BIO *b);
+ int BIO_flush(BIO *b);
+ int BIO_eof(BIO *b);
+ int BIO_set_close(BIO *b,long flag);
+ int BIO_get_close(BIO *b);
+ int BIO_pending(BIO *b);
+ int BIO_wpending(BIO *b);
+ size_t BIO_ctrl_pending(BIO *b);
+ size_t BIO_ctrl_wpending(BIO *b);
+
+ int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);
+ int BIO_set_info_callback(BIO *b,bio_info_cb *cb);
+
+ typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
+
+=head1 DESCRIPTION
+
+BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl()
+are BIO "control" operations taking arguments of various types.
+These functions are not normally called directly, various macros
+are used instead. The standard macros are described below, macros
+specific to a particular type of BIO are described in the specific
+BIOs manual page as well as any special features of the standard
+calls.
+
+BIO_reset() typically resets a BIO to some initial state, in the case
+of file related BIOs for example it rewinds the file pointer to the
+start of the file.
+
+BIO_seek() resets a file related BIO's (that is file descriptor and
+FILE BIOs) file position pointer to B<ofs> bytes from start of file.
+
+BIO_tell() returns the current file position of a file related BIO.
+
+BIO_flush() normally writes out any internally buffered data, in some
+cases it is used to signal EOF and that no more data will be written.
+
+BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of
+"EOF" varies according to the BIO type.
+
+BIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can
+take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used
+in a source/sink BIO to indicate that the underlying I/O stream should
+be closed when the BIO is freed.
+
+BIO_get_close() returns the BIOs close flag.
+
+BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
+return the number of pending characters in the BIOs read and write buffers.
+Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending()
+return a size_t type and are functions, BIO_pending() and BIO_wpending() are
+macros which call BIO_ctrl().
+
+=head1 RETURN VALUES
+
+BIO_reset() normally returns 1 for success and 0 or -1 for failure. File
+BIOs are an exception, they return 0 for success and -1 for failure.
+
+BIO_seek() and BIO_tell() both return the current file position on success
+and -1 for failure, except file BIOs which for BIO_seek() always return 0
+for success and -1 for failure.
+
+BIO_flush() returns 1 for success and 0 or -1 for failure.
+
+BIO_eof() returns 1 if EOF has been reached 0 otherwise.
+
+BIO_set_close() always returns 1.
+
+BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.
+
+BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
+return the amount of pending data.
+
+=head1 NOTES
+
+BIO_flush(), because it can write data may return 0 or -1 indicating
+that the call should be retried later in a similar manner to BIO_write().
+The BIO_should_retry() call should be used and appropriate action taken
+is the call fails.
+
+The return values of BIO_pending() and BIO_wpending() may not reliably
+determine the amount of pending data in all cases. For example in the
+case of a file BIO some data may be available in the FILE structures
+internal buffers but it is not possible to determine this in a
+portably way. For other types of BIO they may not be supported.
+
+Filter BIOs if they do not internally handle a particular BIO_ctrl()
+operation usually pass the operation to the next BIO in the chain.
+This often means there is no need to locate the required BIO for
+a particular operation, it can be called on a chain and it will
+be automatically passed to the relevant BIO. However this can cause
+unexpected results: for example no current filter BIOs implement
+BIO_seek(), but this may still succeed if the chain ends in a FILE
+or file descriptor BIO.
+
+Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl()
+operation.
+
+=head1 BUGS
+
+Some of the return values are ambiguous and care should be taken. In
+particular a return value of 0 can be returned if an operation is not
+supported, if an error occurred, if EOF has not been reached and in
+the case of BIO_seek() on a file BIO for a successful operation.
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_f_base64.pod b/doc/crypto/BIO_f_base64.pod
new file mode 100644
index 000000000000..438af3b6b66c
--- /dev/null
+++ b/doc/crypto/BIO_f_base64.pod
@@ -0,0 +1,81 @@
+=pod
+
+=head1 NAME
+
+BIO_f_base64 - base64 BIO filter
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+ #include <openssl/evp.h>
+
+ BIO_METHOD * BIO_f_base64(void);
+
+=head1 DESCRIPTION
+
+BIO_f_base64() returns the base64 BIO method. This is a filter
+BIO that base64 encodes any data written through it and decodes
+any data read through it.
+
+Base64 BIOs do not support BIO_gets() or BIO_puts().
+
+BIO_flush() on a base64 BIO that is being written through is
+used to signal that no more data is to be encoded: this is used
+to flush the final block through the BIO.
+
+The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags()
+to encode the data all on one line or expect the data to be all
+on one line.
+
+=head1 NOTES
+
+Because of the format of base64 encoding the end of the encoded
+block cannot always be reliably determined.
+
+=head1 RETURN VALUES
+
+BIO_f_base64() returns the base64 BIO method.
+
+=head1 EXAMPLES
+
+Base64 encode the string "Hello World\n" and write the result
+to standard output:
+
+ BIO *bio, *b64;
+ char message[] = "Hello World \n";
+
+ b64 = BIO_new(BIO_f_base64());
+ bio = BIO_new_fp(stdout, BIO_NOCLOSE);
+ bio = BIO_push(b64, bio);
+ BIO_write(bio, message, strlen(message));
+ BIO_flush(bio);
+
+ BIO_free_all(bio);
+
+Read Base64 encoded data from standard input and write the decoded
+data to standard output:
+
+ BIO *bio, *b64, *bio_out;
+ char inbuf[512];
+ int inlen;
+
+ b64 = BIO_new(BIO_f_base64());
+ bio = BIO_new_fp(stdin, BIO_NOCLOSE);
+ bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
+ bio = BIO_push(b64, bio);
+ while((inlen = BIO_read(bio, inbuf, 512)) > 0)
+ BIO_write(bio_out, inbuf, inlen);
+
+ BIO_free_all(bio);
+
+=head1 BUGS
+
+The ambiguity of EOF in base64 encoded data can cause additional
+data following the base64 encoded block to be misinterpreted.
+
+There should be some way of specifying a test that the BIO can perform
+to reliably determine EOF (for example a MIME boundary).
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_f_buffer.pod b/doc/crypto/BIO_f_buffer.pod
new file mode 100644
index 000000000000..c9093c6a576c
--- /dev/null
+++ b/doc/crypto/BIO_f_buffer.pod
@@ -0,0 +1,69 @@
+=pod
+
+=head1 NAME
+
+BIO_f_buffer - buffering BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO_METHOD * BIO_f_buffer(void);
+
+ #define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL)
+ #define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0)
+ #define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1)
+ #define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL)
+ #define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf)
+
+=head1 DESCRIPTION
+
+BIO_f_buffer() returns the buffering BIO method.
+
+Data written to a buffering BIO is buffered and periodically written
+to the next BIO in the chain. Data read from a buffering BIO comes from
+an internal buffer which is filled from the next BIO in the chain.
+Both BIO_gets() and BIO_puts() are supported.
+
+Calling BIO_reset() on a buffering BIO clears any buffered data.
+
+BIO_get_buffer_num_lines() returns the number of lines currently buffered.
+
+BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
+set the read, write or both read and write buffer sizes to B<size>. The initial
+buffer size is DEFAULT_BUFFER_SIZE, currently 1024. Any attempt to reduce the
+buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared
+when the buffer is resized.
+
+BIO_set_buffer_read_data() clears the read buffer and fills it with B<num>
+bytes of B<buf>. If B<num> is larger than the current buffer size the buffer
+is expanded.
+
+=head1 NOTES
+
+Buffering BIOs implement BIO_gets() by using BIO_read() operations on the
+next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
+possible to provide BIO_gets() functionality if the following BIOs do not
+support it (for example SSL BIOs).
+
+Data is only written to the next BIO in the chain when the write buffer fills
+or when BIO_flush() is called. It is therefore important to call BIO_flush()
+whenever any pending data should be written such as when removing a buffering
+BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate
+source/sink BIO is non blocking.
+
+=head1 RETURN VALUES
+
+BIO_f_buffer() returns the buffering BIO method.
+
+BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0).
+
+BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
+return 1 if the buffer was successfully resized or 0 for failure.
+
+BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if
+there was an error.
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_f_cipher.pod b/doc/crypto/BIO_f_cipher.pod
new file mode 100644
index 000000000000..02439cea94a0
--- /dev/null
+++ b/doc/crypto/BIO_f_cipher.pod
@@ -0,0 +1,76 @@
+=pod
+
+=head1 NAME
+
+BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+ #include <openssl/evp.h>
+
+ BIO_METHOD * BIO_f_cipher(void);
+ void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher,
+ unsigned char *key, unsigned char *iv, int enc);
+ int BIO_get_cipher_status(BIO *b)
+ int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)
+
+=head1 DESCRIPTION
+
+BIO_f_cipher() returns the cipher BIO method. This is a filter
+BIO that encrypts any data written through it, and decrypts any data
+read from it. It is a BIO wrapper for the cipher routines
+EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().
+
+Cipher BIOs do not support BIO_gets() or BIO_puts().
+
+BIO_flush() on an encryption BIO that is being written through is
+used to signal that no more data is to be encrypted: this is used
+to flush and possibly pad the final block through the BIO.
+
+BIO_set_cipher() sets the cipher of BIO B<b> to B<cipher> using key B<key>
+and IV B<iv>. B<enc> should be set to 1 for encryption and zero for
+decryption.
+
+When reading from an encryption BIO the final block is automatically
+decrypted and checked when EOF is detected. BIO_get_cipher_status()
+is a BIO_ctrl() macro which can be called to determine whether the
+decryption operation was successful.
+
+BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal
+BIO cipher context. The retrieved context can be used in conjunction
+with the standard cipher routines to set it up. This is useful when
+BIO_set_cipher() is not flexible enough for the applications needs.
+
+=head1 NOTES
+
+When encrypting BIO_flush() B<must> be called to flush the final block
+through the BIO. If it is not then the final block will fail a subsequent
+decrypt.
+
+When decrypting an error on the final block is signalled by a zero
+return value from the read operation. A successful decrypt followed
+by EOF will also return zero for the final read. BIO_get_cipher_status()
+should be called to determine if the decrypt was successful.
+
+As always, if BIO_gets() or BIO_puts() support is needed then it can
+be achieved by preceding the cipher BIO with a buffering BIO.
+
+=head1 RETURN VALUES
+
+BIO_f_cipher() returns the cipher BIO method.
+
+BIO_set_cipher() does not return a value.
+
+BIO_get_cipher_status() returns 1 for a successful decrypt and 0
+for failure.
+
+BIO_get_cipher_ctx() currently always returns 1.
+
+=head1 EXAMPLES
+
+TBA
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_f_md.pod b/doc/crypto/BIO_f_md.pod
new file mode 100644
index 000000000000..0d24083e6db8
--- /dev/null
+++ b/doc/crypto/BIO_f_md.pod
@@ -0,0 +1,138 @@
+=pod
+
+=head1 NAME
+
+BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+ #include <openssl/evp.h>
+
+ BIO_METHOD * BIO_f_md(void);
+ int BIO_set_md(BIO *b,EVP_MD *md);
+ int BIO_get_md(BIO *b,EVP_MD **mdp);
+ int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);
+
+=head1 DESCRIPTION
+
+BIO_f_md() returns the message digest BIO method. This is a filter
+BIO that digests any data passed through it, it is a BIO wrapper
+for the digest routines EVP_DigestInit(), EVP_DigestUpdate()
+and EVP_DigestFinal().
+
+Any data written or read through a digest BIO using BIO_read() and
+BIO_write() is digested.
+
+BIO_gets(), if its B<size> parameter is large enough finishes the
+digest calculation and returns the digest value. BIO_puts() is
+not supported.
+
+BIO_reset() reinitialises a digest BIO.
+
+BIO_set_md() sets the message digest of BIO B<b> to B<md>: this
+must be called to initialize a digest BIO before any data is
+passed through it. It is a BIO_ctrl() macro.
+
+BIO_get_md() places the a pointer to the digest BIOs digest method
+in B<mdp>, it is a BIO_ctrl() macro.
+
+BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>.
+
+=head1 NOTES
+
+The context returned by BIO_get_md_ctx() can be used in calls
+to EVP_DigestFinal() and also the signature routines EVP_SignFinal()
+and EVP_VerifyFinal().
+
+The context returned by BIO_get_md_ctx() is an internal context
+structure. Changes made to this context will affect the digest
+BIO itself and the context pointer will become invalid when the digest
+BIO is freed.
+
+After the digest has been retrieved from a digest BIO it must be
+reinitialized by calling BIO_reset(), or BIO_set_md() before any more
+data is passed through it.
+
+If an application needs to call BIO_gets() or BIO_puts() through
+a chain containing digest BIOs then this can be done by prepending
+a buffering BIO.
+
+=head1 RETURN VALUES
+
+BIO_f_md() returns the digest BIO method.
+
+BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and
+0 for failure.
+
+=head1 EXAMPLES
+
+The following example creates a BIO chain containing an SHA1 and MD5
+digest BIO and passes the string "Hello World" through it. Error
+checking has been omitted for clarity.
+
+ BIO *bio, *mdtmp;
+ char message[] = "Hello World";
+ bio = BIO_new(BIO_s_null());
+ mdtmp = BIO_new(BIO_f_md());
+ BIO_set_md(mdtmp, EVP_sha1());
+ /* For BIO_push() we want to append the sink BIO and keep a note of
+ * the start of the chain.
+ */
+ bio = BIO_push(mdtmp, bio);
+ mdtmp = BIO_new(BIO_f_md());
+ BIO_set_md(mdtmp, EVP_md5());
+ bio = BIO_push(mdtmp, bio);
+ /* Note: mdtmp can now be discarded */
+ BIO_write(bio, message, strlen(message));
+
+The next example digests data by reading through a chain instead:
+
+ BIO *bio, *mdtmp;
+ char buf[1024];
+ int rdlen;
+ bio = BIO_new_file(file, "rb");
+ mdtmp = BIO_new(BIO_f_md());
+ BIO_set_md(mdtmp, EVP_sha1());
+ bio = BIO_push(mdtmp, bio);
+ mdtmp = BIO_new(BIO_f_md());
+ BIO_set_md(mdtmp, EVP_md5());
+ bio = BIO_push(mdtmp, bio);
+ do {
+ rdlen = BIO_read(bio, buf, sizeof(buf));
+ /* Might want to do something with the data here */
+ } while(rdlen > 0);
+
+This next example retrieves the message digests from a BIO chain and
+outputs them. This could be used with the examples above.
+
+ BIO *mdtmp;
+ unsigned char mdbuf[EVP_MAX_MD_SIZE];
+ int mdlen;
+ int i;
+ mdtmp = bio; /* Assume bio has previously been set up */
+ do {
+ EVP_MD *md;
+ mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
+ if(!mdtmp) break;
+ BIO_get_md(mdtmp, &md);
+ printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
+ mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
+ for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
+ printf("\n");
+ mdtmp = BIO_next(mdtmp);
+ } while(mdtmp);
+
+ BIO_free_all(bio);
+
+=head1 BUGS
+
+The lack of support for BIO_puts() and the non standard behaviour of
+BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets()
+and BIO_puts() should be passed to the next BIO in the chain and digest
+the data passed through and that digests should be retrieved using a
+separate BIO_ctrl() call.
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_f_null.pod b/doc/crypto/BIO_f_null.pod
new file mode 100644
index 000000000000..b057c1840832
--- /dev/null
+++ b/doc/crypto/BIO_f_null.pod
@@ -0,0 +1,32 @@
+=pod
+
+=head1 NAME
+
+BIO_f_null - null filter
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO_METHOD * BIO_f_null(void);
+
+=head1 DESCRIPTION
+
+BIO_f_null() returns the null filter BIO method. This is a filter BIO
+that does nothing.
+
+All requests to a null filter BIO are passed through to the next BIO in
+the chain: this means that a BIO chain containing a null filter BIO
+behaves just as though the BIO was not there.
+
+=head1 NOTES
+
+As may be apparent a null filter BIO is not particularly useful.
+
+=head1 RETURN VALUES
+
+BIO_f_null() returns the null filter BIO method.
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_f_ssl.pod b/doc/crypto/BIO_f_ssl.pod
new file mode 100644
index 000000000000..f0b731731f50
--- /dev/null
+++ b/doc/crypto/BIO_f_ssl.pod
@@ -0,0 +1,313 @@
+=pod
+
+=head1 NAME
+
+BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes,
+BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
+BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
+BIO_ssl_shutdown - SSL BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+ #include <openssl/ssl.h>
+
+ BIO_METHOD *BIO_f_ssl(void);
+
+ #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)
+ #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
+ #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
+ #define BIO_set_ssl_renegotiate_bytes(b,num) \
+ BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);
+ #define BIO_set_ssl_renegotiate_timeout(b,seconds) \
+ BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
+ #define BIO_get_num_renegotiates(b) \
+ BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);
+
+ BIO *BIO_new_ssl(SSL_CTX *ctx,int client);
+ BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
+ BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
+ int BIO_ssl_copy_session_id(BIO *to,BIO *from);
+ void BIO_ssl_shutdown(BIO *bio);
+
+ #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
+
+=head1 DESCRIPTION
+
+BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which
+is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to
+SSL I/O.
+
+I/O performed on an SSL BIO communicates using the SSL protocol with
+the SSLs read and write BIOs. If an SSL connection is not established
+then an attempt is made to establish one on the first I/O call.
+
+If a BIO is appended to an SSL BIO using BIO_push() it is automatically
+used as the SSL BIOs read and write BIOs.
+
+Calling BIO_reset() on an SSL BIO closes down any current SSL connection
+by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in
+the chain: this will typically disconnect the underlying transport.
+The SSL BIO is then reset to the initial accept or connect state.
+
+If the close flag is set when an SSL BIO is freed then the internal
+SSL structure is also freed using SSL_free().
+
+BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using
+the close flag B<c>.
+
+BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be
+manipulated using the standard SSL library functions.
+
+BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client>
+is 1 client mode is set. If B<client> is 0 server mode is set.
+
+BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count
+to B<num>. When set after every B<num> bytes of I/O (read and write)
+the SSL session is automatically renegotiated. B<num> must be at
+least 512 bytes.
+
+BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
+B<seconds>. When the renegotiate timeout elapses the session is
+automatically renegotiated.
+
+BIO_get_num_renegotiates() returns the total number of session
+renegotiations due to I/O or timeout.
+
+BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using
+client mode if B<client> is non zero.
+
+BIO_new_ssl_connect() creates a new BIO chain consisting of an
+SSL BIO (using B<ctx>) followed by a connect BIO.
+
+BIO_new_buffer_ssl_connect() creates a new BIO chain consisting
+of a buffering BIO, an SSL BIO (using B<ctx>) and a connect
+BIO.
+
+BIO_ssl_copy_session_id() copies an SSL session id between
+BIO chains B<from> and B<to>. It does this by locating the
+SSL BIOs in each chain and calling SSL_copy_session_id() on
+the internal SSL pointer.
+
+BIO_ssl_shutdown() closes down an SSL connection on BIO
+chain B<bio>. It does this by locating the SSL BIO in the
+chain and calling SSL_shutdown() on its internal SSL
+pointer.
+
+BIO_do_handshake() attempts to complete an SSL handshake on the
+supplied BIO and establish the SSL connection. It returns 1
+if the connection was established successfully. A zero or negative
+value is returned if the connection could not be established, the
+call BIO_should_retry() should be used for non blocking connect BIOs
+to determine if the call should be retried. If an SSL connection has
+already been established this call has no effect.
+
+=head1 NOTES
+
+SSL BIOs are exceptional in that if the underlying transport
+is non blocking they can still request a retry in exceptional
+circumstances. Specifically this will happen if a session
+renegotiation takes place during a BIO_read() operation, one
+case where this happens is when SGC or step up occurs.
+
+In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be
+set to disable this behaviour. That is when this flag is set
+an SSL BIO using a blocking transport will never request a
+retry.
+
+Since unknown BIO_ctrl() operations are sent through filter
+BIOs the servers name and port can be set using BIO_set_host()
+on the BIO returned by BIO_new_ssl_connect() without having
+to locate the connect BIO first.
+
+Applications do not have to call BIO_do_handshake() but may wish
+to do so to separate the handshake process from other I/O
+processing.
+
+=head1 RETURN VALUES
+
+TBA
+
+=head1 EXAMPLE
+
+This SSL/TLS client example, attempts to retrieve a page from an
+SSL/TLS web server. The I/O routines are identical to those of the
+unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>.
+
+ BIO *sbio, *out;
+ int len;
+ char tmpbuf[1024];
+ SSL_CTX *ctx;
+ SSL *ssl;
+
+ ERR_load_crypto_strings();
+ ERR_load_SSL_strings();
+ OpenSSL_add_all_algorithms();
+
+ /* We would seed the PRNG here if the platform didn't
+ * do it automatically
+ */
+
+ ctx = SSL_CTX_new(SSLv23_client_method());
+
+ /* We'd normally set some stuff like the verify paths and
+ * mode here because as things stand this will connect to
+ * any server whose certificate is signed by any CA.
+ */
+
+ sbio = BIO_new_ssl_connect(ctx);
+
+ BIO_get_ssl(sbio, &ssl);
+
+ if(!ssl) {
+ fprintf(stderr, "Can't locate SSL pointer\n");
+ /* whatever ... */
+ }
+
+ /* Don't want any retries */
+ SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
+
+ /* We might want to do other things with ssl here */
+
+ BIO_set_conn_hostname(sbio, "localhost:https");
+
+ out = BIO_new_fp(stdout, BIO_NOCLOSE);
+ if(BIO_do_connect(sbio) <= 0) {
+ fprintf(stderr, "Error connecting to server\n");
+ ERR_print_errors_fp(stderr);
+ /* whatever ... */
+ }
+
+ if(BIO_do_handshake(sbio) <= 0) {
+ fprintf(stderr, "Error establishing SSL connection\n");
+ ERR_print_errors_fp(stderr);
+ /* whatever ... */
+ }
+
+ /* Could examine ssl here to get connection info */
+
+ BIO_puts(sbio, "GET / HTTP/1.0\n\n");
+ for(;;) {
+ len = BIO_read(sbio, tmpbuf, 1024);
+ if(len <= 0) break;
+ BIO_write(out, tmpbuf, len);
+ }
+ BIO_free_all(sbio);
+ BIO_free(out);
+
+Here is a simple server example. It makes use of a buffering
+BIO to allow lines to be read from the SSL BIO using BIO_gets.
+It creates a pseudo web page containing the actual request from
+a client and also echoes the request to standard output.
+
+ BIO *sbio, *bbio, *acpt, *out;
+ int len;
+ char tmpbuf[1024];
+ SSL_CTX *ctx;
+ SSL *ssl;
+
+ ERR_load_crypto_strings();
+ ERR_load_SSL_strings();
+ OpenSSL_add_all_algorithms();
+
+ /* Might seed PRNG here */
+
+ ctx = SSL_CTX_new(SSLv23_server_method());
+
+ if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
+ || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
+ || !SSL_CTX_check_private_key(ctx)) {
+
+ fprintf(stderr, "Error setting up SSL_CTX\n");
+ ERR_print_errors_fp(stderr);
+ return 0;
+ }
+
+ /* Might do other things here like setting verify locations and
+ * DH and/or RSA temporary key callbacks
+ */
+
+ /* New SSL BIO setup as server */
+ sbio=BIO_new_ssl(ctx,0);
+
+ BIO_get_ssl(sbio, &ssl);
+
+ if(!ssl) {
+ fprintf(stderr, "Can't locate SSL pointer\n");
+ /* whatever ... */
+ }
+
+ /* Don't want any retries */
+ SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
+
+ /* Create the buffering BIO */
+
+ bbio = BIO_new(BIO_f_buffer());
+
+ /* Add to chain */
+ sbio = BIO_push(bbio, sbio);
+
+ acpt=BIO_new_accept("4433");
+
+ /* By doing this when a new connection is established
+ * we automatically have sbio inserted into it. The
+ * BIO chain is now 'swallowed' by the accept BIO and
+ * will be freed when the accept BIO is freed.
+ */
+
+ BIO_set_accept_bios(acpt,sbio);
+
+ out = BIO_new_fp(stdout, BIO_NOCLOSE);
+
+ /* Setup accept BIO */
+ if(BIO_do_accept(acpt) <= 0) {
+ fprintf(stderr, "Error setting up accept BIO\n");
+ ERR_print_errors_fp(stderr);
+ return 0;
+ }
+
+ /* Now wait for incoming connection */
+ if(BIO_do_accept(acpt) <= 0) {
+ fprintf(stderr, "Error in connection\n");
+ ERR_print_errors_fp(stderr);
+ return 0;
+ }
+
+ /* We only want one connection so remove and free
+ * accept BIO
+ */
+
+ sbio = BIO_pop(acpt);
+
+ BIO_free_all(acpt);
+
+ if(BIO_do_handshake(sbio) <= 0) {
+ fprintf(stderr, "Error in SSL handshake\n");
+ ERR_print_errors_fp(stderr);
+ return 0;
+ }
+
+ BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
+ BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
+ BIO_puts(sbio, "--------------------------------------------------\r\n");
+
+ for(;;) {
+ len = BIO_gets(sbio, tmpbuf, 1024);
+ if(len <= 0) break;
+ BIO_write(sbio, tmpbuf, len);
+ BIO_write(out, tmpbuf, len);
+ /* Look for blank line signifying end of headers*/
+ if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break;
+ }
+
+ BIO_puts(sbio, "--------------------------------------------------\r\n");
+ BIO_puts(sbio, "\r\n");
+
+ /* Since there is a buffering BIO present we had better flush it */
+ BIO_flush(sbio);
+
+ BIO_free_all(sbio);
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_find_type.pod b/doc/crypto/BIO_find_type.pod
new file mode 100644
index 000000000000..bd3b25619617
--- /dev/null
+++ b/doc/crypto/BIO_find_type.pod
@@ -0,0 +1,98 @@
+=pod
+
+=head1 NAME
+
+BIO_find_type, BIO_next - BIO chain traversal
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO * BIO_find_type(BIO *b,int bio_type);
+ BIO * BIO_next(BIO *b);
+
+ #define BIO_method_type(b) ((b)->method->type)
+
+ #define BIO_TYPE_NONE 0
+ #define BIO_TYPE_MEM (1|0x0400)
+ #define BIO_TYPE_FILE (2|0x0400)
+
+ #define BIO_TYPE_FD (4|0x0400|0x0100)
+ #define BIO_TYPE_SOCKET (5|0x0400|0x0100)
+ #define BIO_TYPE_NULL (6|0x0400)
+ #define BIO_TYPE_SSL (7|0x0200)
+ #define BIO_TYPE_MD (8|0x0200)
+ #define BIO_TYPE_BUFFER (9|0x0200)
+ #define BIO_TYPE_CIPHER (10|0x0200)
+ #define BIO_TYPE_BASE64 (11|0x0200)
+ #define BIO_TYPE_CONNECT (12|0x0400|0x0100)
+ #define BIO_TYPE_ACCEPT (13|0x0400|0x0100)
+ #define BIO_TYPE_PROXY_CLIENT (14|0x0200)
+ #define BIO_TYPE_PROXY_SERVER (15|0x0200)
+ #define BIO_TYPE_NBIO_TEST (16|0x0200)
+ #define BIO_TYPE_NULL_FILTER (17|0x0200)
+ #define BIO_TYPE_BER (18|0x0200)
+ #define BIO_TYPE_BIO (19|0x0400)
+
+ #define BIO_TYPE_DESCRIPTOR 0x0100
+ #define BIO_TYPE_FILTER 0x0200
+ #define BIO_TYPE_SOURCE_SINK 0x0400
+
+=head1 DESCRIPTION
+
+The BIO_find_type() searches for a BIO of a given type in a chain, starting
+at BIO B<b>. If B<type> is a specific type (such as BIO_TYPE_MEM) then a search
+is made for a BIO of that type. If B<type> is a general type (such as
+B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is
+searched for. BIO_find_type() returns the next matching BIO or NULL if none is
+found.
+
+Note: not all the B<BIO_TYPE_*> types above have corresponding BIO implementations.
+
+BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs
+in a chain or used in conjunction with BIO_find_type() to find all BIOs of a
+certain type.
+
+BIO_method_type() returns the type of a BIO.
+
+=head1 RETURN VALUES
+
+BIO_find_type() returns a matching BIO or NULL for no match.
+
+BIO_next() returns the next BIO in a chain.
+
+BIO_method_type() returns the type of the BIO B<b>.
+
+=head1 NOTES
+
+BIO_next() was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO
+chain or find multiple matches using BIO_find_type(). Previous versions had to
+use:
+
+ next = bio->next_bio;
+
+=head1 BUGS
+
+BIO_find_type() in OpenSSL 0.9.5a and earlier could not be safely passed a
+NULL pointer for the B<b> argument.
+
+=head1 EXAMPLE
+
+Traverse a chain looking for digest BIOs:
+
+ BIO *btmp;
+ btmp = in_bio; /* in_bio is chain to search through */
+
+ do {
+ btmp = BIO_find_type(btmp, BIO_TYPE_MD);
+ if(btmp == NULL) break; /* Not found */
+ /* btmp is a digest BIO, do something with it ...*/
+ ...
+
+ btmp = BIO_next(btmp);
+ } while(btmp);
+
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_new.pod b/doc/crypto/BIO_new.pod
new file mode 100644
index 000000000000..2a245fc8de83
--- /dev/null
+++ b/doc/crypto/BIO_new.pod
@@ -0,0 +1,65 @@
+=pod
+
+=head1 NAME
+
+BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO * BIO_new(BIO_METHOD *type);
+ int BIO_set(BIO *a,BIO_METHOD *type);
+ int BIO_free(BIO *a);
+ void BIO_vfree(BIO *a);
+ void BIO_free_all(BIO *a);
+
+=head1 DESCRIPTION
+
+The BIO_new() function returns a new BIO using method B<type>.
+
+BIO_set() sets the method of an already existing BIO.
+
+BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO
+but it does not return a value. Calling BIO_free() may also have some effect
+on the underlying I/O structure, for example it may close the file being
+referred to under certain circumstances. For more details see the individual
+BIO_METHOD descriptions.
+
+BIO_free_all() frees up an entire BIO chain, it does not halt if an error
+occurs freeing up an individual BIO in the chain.
+
+=head1 RETURN VALUES
+
+BIO_new() returns a newly created BIO or NULL if the call fails.
+
+BIO_set(), BIO_free() return 1 for success and 0 for failure.
+
+BIO_free_all() and BIO_vfree() do not return values.
+
+=head1 NOTES
+
+Some BIOs (such as memory BIOs) can be used immediately after calling
+BIO_new(). Others (such as file BIOs) need some additional initialization,
+and frequently a utility function exists to create and initialize such BIOs.
+
+If BIO_free() is called on a BIO chain it will only free one BIO resulting
+in a memory leak.
+
+Calling BIO_free_all() a single BIO has the same effect as calling BIO_free()
+on it other than the discarded return value.
+
+Normally the B<type> argument is supplied by a function which returns a
+pointer to a BIO_METHOD. There is a naming convention for such functions:
+a source/sink BIO is normally called BIO_s_*() and a filter BIO
+BIO_f_*();
+
+=head1 EXAMPLE
+
+Create a memory BIO:
+
+ BIO *mem = BIO_new(BIO_s_mem());
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_push.pod b/doc/crypto/BIO_push.pod
new file mode 100644
index 000000000000..8af1d3c09751
--- /dev/null
+++ b/doc/crypto/BIO_push.pod
@@ -0,0 +1,69 @@
+=pod
+
+=head1 NAME
+
+BIO_push, BIO_pop - add and remove BIOs from a chain.
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO * BIO_push(BIO *b,BIO *append);
+ BIO * BIO_pop(BIO *b);
+
+=head1 DESCRIPTION
+
+The BIO_push() function appends the BIO B<append> to B<b>, it returns
+B<b>.
+
+BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
+in the chain, or NULL if there is no next BIO. The removed BIO then
+becomes a single BIO with no association with the original chain,
+it can thus be freed or attached to a different chain.
+
+=head1 NOTES
+
+The names of these functions are perhaps a little misleading. BIO_push()
+joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain,
+the deleted BIO does not need to be at the end of a chain.
+
+The process of calling BIO_push() and BIO_pop() on a BIO may have additional
+consequences (a control call is made to the affected BIOs) any effects will
+be noted in the descriptions of individual BIOs.
+
+=head1 EXAMPLES
+
+For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
+a base64 BIO and B<f> is a file BIO.
+
+If the call:
+
+ BIO_push(b64, f);
+
+is made then the new chain will be B<b64-chain>. After making the calls
+
+ BIO_push(md2, b64);
+ BIO_push(md1, md2);
+
+the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
+by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
+
+It should be noted that reading causes data to pass in the reverse
+direction, that is data is read from B<f>, base64 B<decoded> and digested
+by B<md1> and B<md2>. If the call:
+
+ BIO_pop(md2);
+
+The call will return B<b64> and the new chain will be B<md1-b64-f> data can
+be written to B<md1> as before.
+
+=head1 RETURN VALUES
+
+BIO_push() returns the end of the chain, B<b>.
+
+BIO_pop() returns the next BIO in the chain, or NULL if there is no next
+BIO.
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_read.pod b/doc/crypto/BIO_read.pod
new file mode 100644
index 000000000000..b34528104ddf
--- /dev/null
+++ b/doc/crypto/BIO_read.pod
@@ -0,0 +1,66 @@
+=pod
+
+=head1 NAME
+
+BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ int BIO_read(BIO *b, void *buf, int len);
+ int BIO_gets(BIO *b,char *buf, int size);
+ int BIO_write(BIO *b, const void *buf, int len);
+ int BIO_puts(BIO *b,const char *buf);
+
+=head1 DESCRIPTION
+
+BIO_read() attempts to read B<len> bytes from BIO B<b> and places
+the data in B<buf>.
+
+BIO_gets() performs the BIOs "gets" operation and places the data
+in B<buf>. Usually this operation will attempt to read a line of data
+from the BIO of maximum length B<len>. There are exceptions to this
+however, for example BIO_gets() on a digest BIO will calculate and
+return the digest and other BIOs may not support BIO_gets() at all.
+
+BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>.
+
+BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b>
+
+=head1 RETURN VALUES
+
+All these functions return either the amount of data successfully read or
+written (if the return value is positive) or that no data was successfully
+read or written if the result is 0 or -1. If the return value is -2 then
+the operation is not implemented in the specific BIO type.
+
+=head1 NOTES
+
+A 0 or -1 return is not necessarily an indication of an error. In
+particular when the source/sink is non-blocking or of a certain type
+it may merely be an indication that no data is currently available and that
+the application should retry the operation later.
+
+One technique sometimes used with blocking sockets is to use a system call
+(such as select(), poll() or equivalent) to determine when data is available
+and then call read() to read the data. The equivalent with BIOs (that is call
+select() on the underlying I/O structure and then call BIO_read() to
+read the data) should B<not> be used because a single call to BIO_read()
+can cause several reads (and writes in the case of SSL BIOs) on the underlying
+I/O structure and may block as a result. Instead select() (or equivalent)
+should be combined with non blocking I/O so successive reads will request
+a retry instead of blocking.
+
+See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to
+determine the cause of a retry and other I/O issues.
+
+If the BIO_gets() function is not supported by a BIO then it possible to
+work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)>
+to the chain.
+
+=head1 SEE ALSO
+
+L<BIO_should_retry(3)|BIO_should_retry(3)>
+
+TBA
diff --git a/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod
new file mode 100644
index 000000000000..7b63e4621b66
--- /dev/null
+++ b/doc/crypto/BIO_s_accept.pod
@@ -0,0 +1,195 @@
+=pod
+
+=head1 NAME
+
+BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port,
+BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
+BIO_get_bind_mode, BIO_do_accept - accept BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO_METHOD *BIO_s_accept(void);
+
+ long BIO_set_accept_port(BIO *b, char *name);
+ char *BIO_get_accept_port(BIO *b);
+
+ BIO *BIO_new_accept(char *host_port);
+
+ long BIO_set_nbio_accept(BIO *b, int n);
+ long BIO_set_accept_bios(BIO *b, char *bio);
+
+ long BIO_set_bind_mode(BIO *b, long mode);
+ long BIO_get_bind_mode(BIO *b, long dummy);
+
+ #define BIO_BIND_NORMAL 0
+ #define BIO_BIND_REUSEADDR_IF_UNUSED 1
+ #define BIO_BIND_REUSEADDR 2
+
+ int BIO_do_accept(BIO *b);
+
+=head1 DESCRIPTION
+
+BIO_s_accept() returns the accept BIO method. This is a wrapper
+round the platform's TCP/IP socket accept routines.
+
+Using accept BIOs, TCP/IP connections can be accepted and data
+transferred using only BIO routines. In this way any platform
+specific operations are hidden by the BIO abstraction.
+
+Read and write operations on an accept BIO will perform I/O
+on the underlying connection. If no connection is established
+and the port (see below) is set up properly then the BIO
+waits for an incoming connection.
+
+Accept BIOs support BIO_puts() but not BIO_gets().
+
+If the close flag is set on an accept BIO then any active
+connection on that chain is shutdown and the socket closed when
+the BIO is freed.
+
+Calling BIO_reset() on a accept BIO will close any active
+connection and reset the BIO into a state where it awaits another
+incoming connection.
+
+BIO_get_fd() and BIO_set_fd() can be called to retrieve or set
+the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)>
+
+BIO_set_accept_port() uses the string B<name> to set the accept
+port. The port is represented as a string of the form "host:port",
+where "host" is the interface to use and "port" is the port.
+Either or both values can be "*" which is interpreted as meaning
+any interface or port respectively. "port" has the same syntax
+as the port specified in BIO_set_conn_port() for connect BIOs,
+that is it can be a numerical port string or a string to lookup
+using getservbyname() and a string table.
+
+BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into
+a single call: that is it creates a new accept BIO with port
+B<host_port>.
+
+BIO_set_nbio_accept() sets the accept socket to blocking mode
+(the default) if B<n> is 0 or non blocking mode if B<n> is 1.
+
+BIO_set_accept_bios() can be used to set a chain of BIOs which
+will be duplicated and prepended to the chain when an incoming
+connection is received. This is useful if, for example, a
+buffering or SSL BIO is required for each connection. The
+chain of BIOs must not be freed after this call, they will
+be automatically freed when the accept BIO is freed.
+
+BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve
+the current bind mode. If BIO_BIND_NORMAL (the default) is set
+then another socket cannot be bound to the same port. If
+BIO_BIND_REUSEADDR is set then other sockets can bind to the
+same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and
+attempt is first made to use BIO_BIN_NORMAL, if this fails
+and the port is not in use then a second attempt is made
+using BIO_BIND_REUSEADDR.
+
+BIO_do_accept() serves two functions. When it is first
+called, after the accept BIO has been setup, it will attempt
+to create the accept socket and bind an address to it. Second
+and subsequent calls to BIO_do_accept() will await an incoming
+connection, or request a retry in non blocking mode.
+
+=head1 NOTES
+
+When an accept BIO is at the end of a chain it will await an
+incoming connection before processing I/O calls. When an accept
+BIO is not at then end of a chain it passes I/O calls to the next
+BIO in the chain.
+
+When a connection is established a new socket BIO is created for
+the connection and appended to the chain. That is the chain is now
+accept->socket. This effectively means that attempting I/O on
+an initial accept socket will await an incoming connection then
+perform I/O on it.
+
+If any additional BIOs have been set using BIO_set_accept_bios()
+then they are placed between the socket and the accept BIO,
+that is the chain will be accept->otherbios->socket.
+
+If a server wishes to process multiple connections (as is normally
+the case) then the accept BIO must be made available for further
+incoming connections. This can be done by waiting for a connection and
+then calling:
+
+ connection = BIO_pop(accept);
+
+After this call B<connection> will contain a BIO for the recently
+established connection and B<accept> will now be a single BIO
+again which can be used to await further incoming connections.
+If no further connections will be accepted the B<accept> can
+be freed using BIO_free().
+
+If only a single connection will be processed it is possible to
+perform I/O using the accept BIO itself. This is often undesirable
+however because the accept BIO will still accept additional incoming
+connections. This can be resolved by using BIO_pop() (see above)
+and freeing up the accept BIO after the initial connection.
+
+If the underlying accept socket is non-blocking and BIO_do_accept() is
+called to await an incoming connection it is possible for
+BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens
+then it is an indication that an accept attempt would block: the application
+should take appropriate action to wait until the underlying socket has
+accepted a connection and retry the call.
+
+BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(),
+BIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and
+BIO_do_accept() are macros.
+
+=head1 RETURN VALUES
+
+TBA
+
+=head1 EXAMPLE
+
+This example accepts two connections on port 4444, sends messages
+down each and finally closes both down.
+
+ BIO *abio, *cbio, *cbio2;
+ ERR_load_crypto_strings();
+ abio = BIO_new_accept("4444");
+
+ /* First call to BIO_accept() sets up accept BIO */
+ if(BIO_do_accept(abio) <= 0) {
+ fprintf(stderr, "Error setting up accept\n");
+ ERR_print_errors_fp(stderr);
+ exit(0);
+ }
+
+ /* Wait for incoming connection */
+ if(BIO_do_accept(abio) <= 0) {
+ fprintf(stderr, "Error accepting connection\n");
+ ERR_print_errors_fp(stderr);
+ exit(0);
+ }
+ fprintf(stderr, "Connection 1 established\n");
+ /* Retrieve BIO for connection */
+ cbio = BIO_pop(abio);
+ BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
+ fprintf(stderr, "Sent out data on connection 1\n");
+ /* Wait for another connection */
+ if(BIO_do_accept(abio) <= 0) {
+ fprintf(stderr, "Error accepting connection\n");
+ ERR_print_errors_fp(stderr);
+ exit(0);
+ }
+ fprintf(stderr, "Connection 2 established\n");
+ /* Close accept BIO to refuse further connections */
+ cbio2 = BIO_pop(abio);
+ BIO_free(abio);
+ BIO_puts(cbio2, "Connection 2: Sending out Data on second\n");
+ fprintf(stderr, "Sent out data on connection 2\n");
+
+ BIO_puts(cbio, "Connection 1: Second connection established\n");
+ /* Close the two established connections */
+ BIO_free(cbio);
+ BIO_free(cbio2);
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod
new file mode 100644
index 000000000000..8d0a55a025c7
--- /dev/null
+++ b/doc/crypto/BIO_s_bio.pod
@@ -0,0 +1,182 @@
+=pod
+
+=head1 NAME
+
+BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
+BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair,
+BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request,
+BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO_METHOD *BIO_s_bio(void);
+
+ #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2)
+ #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL)
+
+ #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL)
+
+ #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL)
+ #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL)
+
+ int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
+
+ #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL)
+ size_t BIO_ctrl_get_write_guarantee(BIO *b);
+
+ #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL)
+ size_t BIO_ctrl_get_read_request(BIO *b);
+
+ int BIO_ctrl_reset_read_request(BIO *b);
+
+=head1 DESCRIPTION
+
+BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink
+BIOs where data written to either half of the pair is buffered and can be read from
+the other half. Both halves must usually by handled by the same application thread
+since no locking is done on the internal data structures.
+
+Since BIO chains typically end in a source/sink BIO it is possible to make this
+one half of a BIO pair and have all the data processed by the chain under application
+control.
+
+One typical use of BIO pairs is to place TLS/SSL I/O under application control, this
+can be used when the application wishes to use a non standard transport for
+TLS/SSL or the normal socket routines are inappropriate.
+
+Calls to BIO_read() will read data from the buffer or request a retry if no
+data is available.
+
+Calls to BIO_write() will place data in the buffer or request a retry if the
+buffer is full.
+
+The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to
+determine the amount of pending data in the read or write buffer.
+
+BIO_reset() clears any data in the write buffer.
+
+BIO_make_bio_pair() joins two separate BIOs into a connected pair.
+
+BIO_destroy_pair() destroys the association between two connected BIOs. Freeing
+up any half of the pair will automatically destroy the association.
+
+BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further
+writes on BIO B<b> are allowed (they will return an error). Reads on the other
+half of the pair will return any pending data or EOF when all pending data has
+been read.
+
+BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>.
+If the size is not initialized a default value is used. This is currently
+17K, sufficient for a maximum size TLS record.
+
+BIO_get_write_buf_size() returns the size of the write buffer.
+
+BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and
+BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2>
+with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is
+zero then the default size is used. BIO_new_bio_pair() does not check whether
+B<bio1> or B<bio2> do point to some other BIO, the values are overwritten,
+BIO_free() is not called.
+
+BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum
+length of data that can be currently written to the BIO. Writes larger than this
+value will return a value from BIO_write() less than the amount requested or if the
+buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function
+whereas BIO_get_write_guarantee() is a macro.
+
+BIO_get_read_request() and BIO_ctrl_get_read_request() return the
+amount of data requested, or the buffer size if it is less, if the
+last read attempt at the other half of the BIO pair failed due to an
+empty buffer. This can be used to determine how much data should be
+written to the BIO so the next read will succeed: this is most useful
+in TLS/SSL applications where the amount of data read is usually
+meaningful rather than just a buffer size. After a successful read
+this call will return zero. It also will return zero once new data
+has been written satisfying the read request or part of it.
+Note that BIO_get_read_request() never returns an amount larger
+than that returned by BIO_get_write_guarantee().
+
+BIO_ctrl_reset_read_request() can also be used to reset the value returned by
+BIO_get_read_request() to zero.
+
+=head1 NOTES
+
+Both halves of a BIO pair should be freed. That is even if one half is implicit
+freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed.
+
+When used in bidirectional applications (such as TLS/SSL) care should be taken to
+flush any data in the write buffer. This can be done by calling BIO_pending()
+on the other half of the pair and, if any data is pending, reading it and sending
+it to the underlying transport. This must be done before any normal processing
+(such as calling select() ) due to a request and BIO_should_read() being true.
+
+To see why this is important consider a case where a request is sent using
+BIO_write() and a response read with BIO_read(), this can occur during an
+TLS/SSL handshake for example. BIO_write() will succeed and place data in the write
+buffer. BIO_read() will initially fail and BIO_should_read() will be true. If
+the application then waits for data to be available on the underlying transport
+before flushing the write buffer it will never succeed because the request was
+never sent!
+
+=head1 RETURN VALUES
+
+BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
+B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the
+locations for B<bio1> and B<bio2>. Check the error stack for more information.
+
+[XXXXX: More return values need to be added here]
+
+=head1 EXAMPLE
+
+The BIO pair can be used to have full control over the network access of an
+application. The application can call select() on the socket as required
+without having to go through the SSL-interface.
+
+ BIO *internal_bio, *network_bio;
+ ...
+ BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
+ SSL_set_bio(ssl, internal_bio, internal_bio);
+ SSL_operations();
+ ...
+
+ application | TLS-engine
+ | |
+ +----------> SSL_operations()
+ | /\ ||
+ | || \/
+ | BIO-pair (internal_bio)
+ +----------< BIO-pair (network_bio)
+ | |
+ socket |
+
+ ...
+ SSL_free(ssl); /* implicitly frees internal_bio */
+ BIO_free(network_bio);
+ ...
+
+As the BIO pair will only buffer the data and never directly access the
+connection, it behaves non-blocking and will return as soon as the write
+buffer is full or the read buffer is drained. Then the application has to
+flush the write buffer and/or fill the read buffer.
+
+Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
+and must be transfered to the network. Use BIO_ctrl_get_read_request() to
+find out, how many bytes must be written into the buffer before the
+SSL_operation() can successfully be continued.
+
+=head1 WARNING
+
+As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
+condition, but there is still data in the write buffer. An application must
+not rely on the error value of SSL_operation() but must assure that the
+write buffer is always flushed first. Otherwise a deadlock may occur as
+the peer might be waiting for the data before being able to continue.
+
+=head1 SEE ALSO
+
+L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
+L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)>
+
+=cut
diff --git a/doc/crypto/BIO_s_connect.pod b/doc/crypto/BIO_s_connect.pod
new file mode 100644
index 000000000000..bcf7d8dcac7d
--- /dev/null
+++ b/doc/crypto/BIO_s_connect.pod
@@ -0,0 +1,192 @@
+=pod
+
+=head1 NAME
+
+BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port,
+BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
+BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
+BIO_set_nbio, BIO_do_connect - connect BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO_METHOD * BIO_s_connect(void);
+
+ BIO *BIO_new_connect(char *name);
+
+ long BIO_set_conn_hostname(BIO *b, char *name);
+ long BIO_set_conn_port(BIO *b, char *port);
+ long BIO_set_conn_ip(BIO *b, char *ip);
+ long BIO_set_conn_int_port(BIO *b, char *port);
+ char *BIO_get_conn_hostname(BIO *b);
+ char *BIO_get_conn_port(BIO *b);
+ char *BIO_get_conn_ip(BIO *b, dummy);
+ long BIO_get_conn_int_port(BIO *b, int port);
+
+ long BIO_set_nbio(BIO *b, long n);
+
+ int BIO_do_connect(BIO *b);
+
+=head1 DESCRIPTION
+
+BIO_s_connect() returns the connect BIO method. This is a wrapper
+round the platform's TCP/IP socket connection routines.
+
+Using connect BIOs, TCP/IP connections can be made and data
+transferred using only BIO routines. In this way any platform
+specific operations are hidden by the BIO abstraction.
+
+Read and write operations on a connect BIO will perform I/O
+on the underlying connection. If no connection is established
+and the port and hostname (see below) is set up properly then
+a connection is established first.
+
+Connect BIOs support BIO_puts() but not BIO_gets().
+
+If the close flag is set on a connect BIO then any active
+connection is shutdown and the socket closed when the BIO
+is freed.
+
+Calling BIO_reset() on a connect BIO will close any active
+connection and reset the BIO into a state where it can connect
+to the same host again.
+
+BIO_get_fd() places the underlying socket in B<c> if it is not NULL,
+it also returns the socket . If B<c> is not NULL it should be of
+type (int *).
+
+BIO_set_conn_hostname() uses the string B<name> to set the hostname.
+The hostname can be an IP address. The hostname can also include the
+port in the form hostname:port . It is also acceptable to use the
+form "hostname/any/other/path" or "hostname:port/any/other/path".
+
+BIO_set_conn_port() sets the port to B<port>. B<port> can be the
+numerical form or a string such as "http". A string will be looked
+up first using getservbyname() on the host platform but if that
+fails a standard table of port names will be used. Currently the
+list is http, telnet, socks, https, ssl, ftp, gopher and wais.
+
+BIO_set_conn_ip() sets the IP address to B<ip> using binary form,
+that is four bytes specifying the IP address in big-endian form.
+
+BIO_set_conn_int_port() sets the port using B<port>. B<port> should
+be of type (int *).
+
+BIO_get_conn_hostname() returns the hostname of the connect BIO or
+NULL if the BIO is initialized but no hostname is set.
+This return value is an internal pointer which should not be modified.
+
+BIO_get_conn_port() returns the port as a string.
+
+BIO_get_conn_ip() returns the IP address in binary form.
+
+BIO_get_conn_int_port() returns the port as an int.
+
+BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is
+zero then blocking I/O is set. If B<n> is 1 then non blocking I/O
+is set. Blocking I/O is the default. The call to BIO_set_nbio()
+should be made before the connection is established because
+non blocking I/O is set during the connect process.
+
+BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
+a single call: that is it creates a new connect BIO with B<name>.
+
+BIO_do_connect() attempts to connect the supplied BIO. It returns 1
+if the connection was established successfully. A zero or negative
+value is returned if the connection could not be established, the
+call BIO_should_retry() should be used for non blocking connect BIOs
+to determine if the call should be retried.
+
+=head1 NOTES
+
+If blocking I/O is set then a non positive return value from any
+I/O call is caused by an error condition, although a zero return
+will normally mean that the connection was closed.
+
+If the port name is supplied as part of the host name then this will
+override any value set with BIO_set_conn_port(). This may be undesirable
+if the application does not wish to allow connection to arbitrary
+ports. This can be avoided by checking for the presence of the ':'
+character in the passed hostname and either indicating an error or
+truncating the string at that point.
+
+The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(),
+BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a
+connection attempt is made. Before any connection attempt the values
+returned are those set by the application itself.
+
+Applications do not have to call BIO_do_connect() but may wish to do
+so to separate the connection process from other I/O processing.
+
+If non blocking I/O is set then retries will be requested as appropriate.
+
+It addition to BIO_should_read() and BIO_should_write() it is also
+possible for BIO_should_io_special() to be true during the initial
+connection process with the reason BIO_RR_CONNECT. If this is returned
+then this is an indication that a connection attempt would block,
+the application should then take appropriate action to wait until
+the underlying socket has connected and retry the call.
+
+BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(),
+BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(),
+BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and
+BIO_do_connect() are macros.
+
+=head1 RETURN VALUES
+
+BIO_s_connect() returns the connect BIO method.
+
+BIO_get_fd() returns the socket or -1 if the BIO has not
+been initialized.
+
+BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and
+BIO_set_conn_int_port() always return 1.
+
+BIO_get_conn_hostname() returns the connected hostname or NULL is
+none was set.
+
+BIO_get_conn_port() returns a string representing the connected
+port or NULL if not set.
+
+BIO_get_conn_ip() returns a pointer to the connected IP address in
+binary form or all zeros if not set.
+
+BIO_get_conn_int_port() returns the connected port or 0 if none was
+set.
+
+BIO_set_nbio() always returns 1.
+
+BIO_do_connect() returns 1 if the connection was successfully
+established and 0 or -1 if the connection failed.
+
+=head1 EXAMPLE
+
+This is example connects to a webserver on the local host and attempts
+to retrieve a page and copy the result to standard output.
+
+
+ BIO *cbio, *out;
+ int len;
+ char tmpbuf[1024];
+ ERR_load_crypto_strings();
+ cbio = BIO_new_connect("localhost:http");
+ out = BIO_new_fp(stdout, BIO_NOCLOSE);
+ if(BIO_do_connect(cbio) <= 0) {
+ fprintf(stderr, "Error connecting to server\n");
+ ERR_print_errors_fp(stderr);
+ /* whatever ... */
+ }
+ BIO_puts(cbio, "GET / HTTP/1.0\n\n");
+ for(;;) {
+ len = BIO_read(cbio, tmpbuf, 1024);
+ if(len <= 0) break;
+ BIO_write(out, tmpbuf, len);
+ }
+ BIO_free(cbio);
+ BIO_free(out);
+
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_s_fd.pod b/doc/crypto/BIO_s_fd.pod
new file mode 100644
index 000000000000..b1de1d101549
--- /dev/null
+++ b/doc/crypto/BIO_s_fd.pod
@@ -0,0 +1,89 @@
+=pod
+
+=head1 NAME
+
+BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO_METHOD * BIO_s_fd(void);
+
+ #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
+ #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)
+
+ BIO *BIO_new_fd(int fd, int close_flag);
+
+=head1 DESCRIPTION
+
+BIO_s_fd() returns the file descriptor BIO method. This is a wrapper
+round the platforms file descriptor routines such as read() and write().
+
+BIO_read() and BIO_write() read or write the underlying descriptor.
+BIO_puts() is supported but BIO_gets() is not.
+
+If the close flag is set then then close() is called on the underlying
+file descriptor when the BIO is freed.
+
+BIO_reset() attempts to change the file pointer to the start of file
+using lseek(fd, 0, 0).
+
+BIO_seek() sets the file pointer to position B<ofs> from start of file
+using lseek(fd, ofs, 0).
+
+BIO_tell() returns the current file position by calling lseek(fd, 0, 1).
+
+BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
+flag to B<c>.
+
+BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
+returns the file descriptor. If B<c> is not NULL it should be of type
+(int *).
+
+BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
+
+=head1 NOTES
+
+The behaviour of BIO_read() and BIO_write() depends on the behavior of the
+platforms read() and write() calls on the descriptor. If the underlying
+file descriptor is in a non blocking mode then the BIO will behave in the
+manner described in the L<BIO_read(3)|BIO_read(3)> and L<BIO_should_retry(3)|BIO_should_retry(3)>
+manual pages.
+
+File descriptor BIOs should not be used for socket I/O. Use socket BIOs
+instead.
+
+=head1 RETURN VALUES
+
+BIO_s_fd() returns the file descriptor BIO method.
+
+BIO_reset() returns zero for success and -1 if an error occurred.
+BIO_seek() and BIO_tell() return the current file position or -1
+is an error occurred. These values reflect the underlying lseek()
+behaviour.
+
+BIO_set_fd() always returns 1.
+
+BIO_get_fd() returns the file descriptor or -1 if the BIO has not
+been initialized.
+
+BIO_new_fd() returns the newly allocated BIO or NULL is an error
+occurred.
+
+=head1 EXAMPLE
+
+This is a file descriptor BIO version of "Hello World":
+
+ BIO *out;
+ out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
+ BIO_printf(out, "Hello World\n");
+ BIO_free(out);
+
+=head1 SEE ALSO
+
+L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
+L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>,
+L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
+L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
+L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>
diff --git a/doc/crypto/BIO_s_file.pod b/doc/crypto/BIO_s_file.pod
new file mode 100644
index 000000000000..b2a29263f4cd
--- /dev/null
+++ b/doc/crypto/BIO_s_file.pod
@@ -0,0 +1,144 @@
+=pod
+
+=head1 NAME
+
+BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp,
+BIO_read_filename, BIO_write_filename, BIO_append_filename,
+BIO_rw_filename - FILE bio
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO_METHOD * BIO_s_file(void);
+ BIO *BIO_new_file(const char *filename, const char *mode);
+ BIO *BIO_new_fp(FILE *stream, int flags);
+
+ BIO_set_fp(BIO *b,FILE *fp, int flags);
+ BIO_get_fp(BIO *b,FILE **fpp);
+
+ int BIO_read_filename(BIO *b, char *name)
+ int BIO_write_filename(BIO *b, char *name)
+ int BIO_append_filename(BIO *b, char *name)
+ int BIO_rw_filename(BIO *b, char *name)
+
+=head1 DESCRIPTION
+
+BIO_s_file() returns the BIO file method. As its name implies it
+is a wrapper round the stdio FILE structure and it is a
+source/sink BIO.
+
+Calls to BIO_read() and BIO_write() read and write data to the
+underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.
+
+BIO_flush() on a file BIO calls the fflush() function on the wrapped
+stream.
+
+BIO_reset() attempts to change the file pointer to the start of file
+using fseek(stream, 0, 0).
+
+BIO_seek() sets the file pointer to position B<ofs> from start of file
+using fseek(stream, ofs, 0).
+
+BIO_eof() calls feof().
+
+Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO
+is freed.
+
+BIO_new_file() creates a new file BIO with mode B<mode> the meaning
+of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE
+flag is set on the returned BIO.
+
+BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be:
+BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying
+stream to text mode, default is binary: this only has any effect under
+Win32).
+
+BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same
+meaning as in BIO_new_fp(), it is a macro.
+
+BIO_get_fp() retrieves the fp of a file BIO, it is a macro.
+
+BIO_seek() is a macro that sets the position pointer to B<offset> bytes
+from the start of file.
+
+BIO_tell() returns the value of the position pointer.
+
+BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
+BIO_rw_filename() set the file BIO B<b> to use file B<name> for
+reading, writing, append or read write respectively.
+
+=head1 NOTES
+
+When wrapping stdout, stdin or stderr the underlying stream should not
+normally be closed so the BIO_NOCLOSE flag should be set.
+
+Because the file BIO calls the underlying stdio functions any quirks
+in stdio behaviour will be mirrored by the corresponding BIO.
+
+=head1 EXAMPLES
+
+File BIO "hello world":
+
+ BIO *bio_out;
+ bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
+ BIO_printf(bio_out, "Hello World\n");
+
+Alternative technique:
+
+ BIO *bio_out;
+ bio_out = BIO_new(BIO_s_file());
+ if(bio_out == NULL) /* Error ... */
+ if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
+ BIO_printf(bio_out, "Hello World\n");
+
+Write to a file:
+
+ BIO *out;
+ out = BIO_new_file("filename.txt", "w");
+ if(!out) /* Error occurred */
+ BIO_printf(out, "Hello World\n");
+ BIO_free(out);
+
+Alternative technique:
+
+ BIO *out;
+ out = BIO_new(BIO_s_file());
+ if(out == NULL) /* Error ... */
+ if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
+ BIO_printf(out, "Hello World\n");
+ BIO_free(out);
+
+=head1 RETURN VALUES
+
+BIO_s_file() returns the file BIO method.
+
+BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
+occurred.
+
+BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
+(although the current implementation never return 0).
+
+BIO_seek() returns the same value as the underlying fseek() function:
+0 for success or -1 for failure.
+
+BIO_tell() returns the current file position.
+
+BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
+BIO_rw_filename() return 1 for success or 0 for failure.
+
+=head1 BUGS
+
+BIO_reset() and BIO_seek() are implemented using fseek() on the underlying
+stream. The return value for fseek() is 0 for success or -1 if an error
+occurred this differs from other types of BIO which will typically return
+1 for success and a non positive value if an error occurred.
+
+=head1 SEE ALSO
+
+L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
+L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>,
+L<BIO_read(3)|BIO_read(3)>,
+L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
+L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
+L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>
diff --git a/doc/crypto/BIO_s_mem.pod b/doc/crypto/BIO_s_mem.pod
new file mode 100644
index 000000000000..19648acfae0f
--- /dev/null
+++ b/doc/crypto/BIO_s_mem.pod
@@ -0,0 +1,115 @@
+=pod
+
+=head1 NAME
+
+BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
+BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO_METHOD * BIO_s_mem(void);
+
+ BIO_set_mem_eof_return(BIO *b,int v)
+ long BIO_get_mem_data(BIO *b, char **pp)
+ BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c)
+ BIO_get_mem_ptr(BIO *b,BUF_MEM **pp)
+
+ BIO *BIO_new_mem_buf(void *buf, int len);
+
+=head1 DESCRIPTION
+
+BIO_s_mem() return the memory BIO method function.
+
+A memory BIO is a source/sink BIO which uses memory for its I/O. Data
+written to a memory BIO is stored in a BUF_MEM structure which is extended
+as appropriate to accommodate the stored data.
+
+Any data written to a memory BIO can be recalled by reading from it.
+Unless the memory BIO is read only any data read from it is deleted from
+the BIO.
+
+Memory BIOs support BIO_gets() and BIO_puts().
+
+If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying
+BUF_MEM structure is also freed.
+
+Calling BIO_reset() on a read write memory BIO clears any data in it. On a
+read only BIO it restores the BIO to its original state and the read only
+data can be read again.
+
+BIO_eof() is true if no data is in the BIO.
+
+BIO_ctrl_pending() returns the number of bytes currently stored.
+
+BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is
+empty. If the B<v> is zero then an empty memory BIO will return EOF (that is
+it will return zero and BIO_should_retry(b) will be false. If B<v> is non
+zero then it will return B<v> when it is empty and it will set the read retry
+flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal
+positive return value B<v> should be set to a negative value, typically -1.
+
+BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data
+and returns the total amount of data available. It is implemented as a macro.
+
+BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the
+close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE.
+It is a macro.
+
+BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is
+a macro.
+
+BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>,
+if B<len> is -1 then the B<buf> is assumed to be null terminated and its
+length is determined by B<strlen>. The BIO is set to a read only state and
+as a result cannot be written to. This is useful when some data needs to be
+made available from a static area of memory in the form of a BIO. The
+supplied data is read directly from the supplied buffer: it is B<not> copied
+first, so the supplied area of memory must be unchanged until the BIO is freed.
+
+=head1 NOTES
+
+Writes to memory BIOs will always succeed if memory is available: that is
+their size can grow indefinitely.
+
+Every read from a read write memory BIO will remove the data just read with
+an internal copy operation, if a BIO contains a lots of data and it is
+read in small chunks the operation can be very slow. The use of a read only
+memory BIO avoids this problem. If the BIO must be read write then adding
+a buffering BIO to the chain will speed up the process.
+
+=head1 BUGS
+
+There should be an option to set the maximum size of a memory BIO.
+
+There should be a way to "rewind" a read write BIO without destroying
+its contents.
+
+The copying operation should not occur after every small read of a large BIO
+to improve efficiency.
+
+=head1 EXAMPLE
+
+Create a memory BIO and write some data to it:
+
+ BIO *mem = BIO_new(BIO_s_mem());
+ BIO_puts(mem, "Hello World\n");
+
+Create a read only memory BIO:
+
+ char data[] = "Hello World";
+ BIO *mem;
+ mem = BIO_new_mem_buf(data, -1);
+
+Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
+
+ BUF_MEM *bptr;
+ BIO_get_mem_ptr(mem, &bptr);
+ BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
+ BIO_free(mem);
+
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_s_null.pod b/doc/crypto/BIO_s_null.pod
new file mode 100644
index 000000000000..e5514f723898
--- /dev/null
+++ b/doc/crypto/BIO_s_null.pod
@@ -0,0 +1,37 @@
+=pod
+
+=head1 NAME
+
+BIO_s_null - null data sink
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO_METHOD * BIO_s_null(void);
+
+=head1 DESCRIPTION
+
+BIO_s_null() returns the null sink BIO method. Data written to
+the null sink is discarded, reads return EOF.
+
+=head1 NOTES
+
+A null sink BIO behaves in a similar manner to the Unix /dev/null
+device.
+
+A null bio can be placed on the end of a chain to discard any data
+passed through it.
+
+A null sink is useful if, for example, an application wishes to digest some
+data by writing through a digest bio but not send the digested data anywhere.
+Since a BIO chain must normally include a source/sink BIO this can be achieved
+by adding a null sink BIO to the end of the chain
+
+=head1 RETURN VALUES
+
+BIO_s_null() returns the null sink BIO method.
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_s_socket.pod b/doc/crypto/BIO_s_socket.pod
new file mode 100644
index 000000000000..1c8d3a911027
--- /dev/null
+++ b/doc/crypto/BIO_s_socket.pod
@@ -0,0 +1,63 @@
+=pod
+
+=head1 NAME
+
+BIO_s_socket, BIO_new_socket - socket BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO_METHOD *BIO_s_socket(void);
+
+ long BIO_set_fd(BIO *b, int fd, long close_flag);
+ long BIO_get_fd(BIO *b, int *c);
+
+ BIO *BIO_new_socket(int sock, int close_flag);
+
+=head1 DESCRIPTION
+
+BIO_s_socket() returns the socket BIO method. This is a wrapper
+round the platform's socket routines.
+
+BIO_read() and BIO_write() read or write the underlying socket.
+BIO_puts() is supported but BIO_gets() is not.
+
+If the close flag is set then the socket is shut down and closed
+when the BIO is freed.
+
+BIO_set_fd() sets the socket of BIO B<b> to B<fd> and the close
+flag to B<close_flag>.
+
+BIO_get_fd() places the socket in B<c> if it is not NULL, it also
+returns the socket. If B<c> is not NULL it should be of type (int *).
+
+BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>.
+
+=head1 NOTES
+
+Socket BIOs also support any relevant functionality of file descriptor
+BIOs.
+
+The reason for having separate file descriptor and socket BIOs is that on some
+platforms sockets are not file descriptors and use distinct I/O routines,
+Windows is one such platform. Any code mixing the two will not work on
+all platforms.
+
+BIO_set_fd() and BIO_get_fd() are macros.
+
+=head1 RETURN VALUES
+
+BIO_s_socket() returns the socket BIO method.
+
+BIO_set_fd() always returns 1.
+
+BIO_get_fd() returns the socket or -1 if the BIO has not been
+initialized.
+
+BIO_new_socket() returns the newly allocated BIO or NULL is an error
+occurred.
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_set_callback.pod b/doc/crypto/BIO_set_callback.pod
new file mode 100644
index 000000000000..47595562457b
--- /dev/null
+++ b/doc/crypto/BIO_set_callback.pod
@@ -0,0 +1,108 @@
+=pod
+
+=head1 NAME
+
+BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
+BIO_debug_callback - BIO callback functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ #define BIO_set_callback(b,cb) ((b)->callback=(cb))
+ #define BIO_get_callback(b) ((b)->callback)
+ #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg))
+ #define BIO_get_callback_arg(b) ((b)->cb_arg)
+
+ long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
+ long argl,long ret);
+
+ typedef long (*callback)(BIO *b, int oper, const char *argp,
+ int argi, long argl, long retvalue);
+
+=head1 DESCRIPTION
+
+BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback,
+they are both macros. The callback is called during most high level BIO
+operations. It can be used for debugging purposes to trace operations on
+a BIO or to modify its operation.
+
+BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
+used to set and retrieve an argument for use in the callback.
+
+BIO_debug_callback() is a standard debugging callback which prints
+out information relating to each BIO operation. If the callback
+argument is set if is interpreted as a BIO to send the information
+to, otherwise stderr is used.
+
+callback() is the callback function itself. The meaning of each
+argument is described below.
+
+The BIO the callback is attached to is passed in B<b>.
+
+B<oper> is set to the operation being performed. For some operations
+the callback is called twice, once before and once after the actual
+operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
+
+The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
+the value of B<oper>, that is the operation being performed.
+
+B<retvalue> is the return value that would be returned to the
+application if no callback were present. The actual value returned
+is the return value of the callback itself. In the case of callbacks
+called before the actual BIO operation 1 is placed in retvalue, if
+the return value is not positive it will be immediately returned to
+the application and the BIO operation will not be performed.
+
+The callback should normally simply return B<retvalue> when it has
+finished processing, unless if specifically wishes to modify the
+value returned to the application.
+
+=head1 CALLBACK OPERATIONS
+
+=over 4
+
+=item B<BIO_free(b)>
+
+callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the
+free operation.
+
+=item B<BIO_read(b, out, outl)>
+
+callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before
+the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
+after.
+
+=item B<BIO_write(b, in, inl)>
+
+callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before
+the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
+after.
+
+=item B<BIO_gets(b, out, outl)>
+
+callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before
+the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
+after.
+
+=item B<BIO_puts(b, in)>
+
+callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before
+the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
+after.
+
+=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
+
+callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
+callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
+
+=back
+
+=head1 EXAMPLE
+
+The BIO_debug_callback() function is a good example, its source is
+in crypto/bio/bio_cb.c
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BIO_should_retry.pod b/doc/crypto/BIO_should_retry.pod
new file mode 100644
index 000000000000..539c3912728c
--- /dev/null
+++ b/doc/crypto/BIO_should_retry.pod
@@ -0,0 +1,114 @@
+=pod
+
+=head1 NAME
+
+BIO_should_retry, BIO_should_read, BIO_should_write,
+BIO_should_io_special, BIO_retry_type, BIO_should_retry,
+BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ)
+ #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE)
+ #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL)
+ #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS)
+ #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY)
+
+ #define BIO_FLAGS_READ 0x01
+ #define BIO_FLAGS_WRITE 0x02
+ #define BIO_FLAGS_IO_SPECIAL 0x04
+ #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
+ #define BIO_FLAGS_SHOULD_RETRY 0x08
+
+ BIO * BIO_get_retry_BIO(BIO *bio, int *reason);
+ int BIO_get_retry_reason(BIO *bio);
+
+=head1 DESCRIPTION
+
+These functions determine why a BIO is not able to read or write data.
+They will typically be called after a failed BIO_read() or BIO_write()
+call.
+
+BIO_should_retry() is true if the call that produced this condition
+should then be retried at a later time.
+
+If BIO_should_retry() is false then the cause is an error condition.
+
+BIO_should_read() is true if the cause of the condition is that a BIO
+needs to read data.
+
+BIO_should_write() is true if the cause of the condition is that a BIO
+needs to read data.
+
+BIO_should_io_special() is true if some "special" condition, that is a
+reason other than reading or writing is the cause of the condition.
+
+BIO_get_retry_reason() returns a mask of the cause of a retry condition
+consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,
+B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of
+these.
+
+BIO_get_retry_BIO() determines the precise reason for the special
+condition, it returns the BIO that caused this condition and if
+B<reason> is not NULL it contains the reason code. The meaning of
+the reason code and the action that should be taken depends on
+the type of BIO that resulted in this condition.
+
+BIO_get_retry_reason() returns the reason for a special condition if
+passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
+
+=head1 NOTES
+
+If BIO_should_retry() returns false then the precise "error condition"
+depends on the BIO type that caused it and the return code of the BIO
+operation. For example if a call to BIO_read() on a socket BIO returns
+0 and BIO_should_retry() is false then the cause will be that the
+connection closed. A similar condition on a file BIO will mean that it
+has reached EOF. Some BIO types may place additional information on
+the error queue. For more details see the individual BIO type manual
+pages.
+
+If the underlying I/O structure is in a blocking mode almost all current
+BIO types will not request a retry, because the underlying I/O
+calls will not. If the application knows that the BIO type will never
+signal a retry then it need not call BIO_should_retry() after a failed
+BIO I/O call. This is typically done with file BIOs.
+
+SSL BIOs are the only current exception to this rule: they can request a
+retry even if the underlying I/O structure is blocking, if a handshake
+occurs during a call to BIO_read(). An application can retry the failed
+call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
+on the underlying SSL structure.
+
+While an application may retry a failed non blocking call immediately
+this is likely to be very inefficient because the call will fail
+repeatedly until data can be processed or is available. An application
+will normally wait until the necessary condition is satisfied. How
+this is done depends on the underlying I/O structure.
+
+For example if the cause is ultimately a socket and BIO_should_read()
+is true then a call to select() may be made to wait until data is
+available and then retry the BIO operation. By combining the retry
+conditions of several non blocking BIOs in a single select() call
+it is possible to service several BIOs in a single thread, though
+the performance may be poor if SSL BIOs are present because long delays
+can occur during the initial handshake process.
+
+It is possible for a BIO to block indefinitely if the underlying I/O
+structure cannot process or return any data. This depends on the behaviour of
+the platforms I/O functions. This is often not desirable: one solution
+is to use non blocking I/O and use a timeout on the select() (or
+equivalent) call.
+
+=head1 BUGS
+
+The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
+that is they cannot retry after a partial read or write. This is usually
+worked around by only passing the relevant data to ASN1 functions when
+the entire structure can be read or written.
+
+=head1 SEE ALSO
+
+TBA
diff --git a/doc/crypto/BN_BLINDING_new.pod b/doc/crypto/BN_BLINDING_new.pod
new file mode 100644
index 000000000000..7b087f7288f9
--- /dev/null
+++ b/doc/crypto/BN_BLINDING_new.pod
@@ -0,0 +1,109 @@
+=pod
+
+=head1 NAME
+
+BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
+BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
+BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_get_flags,
+BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM
+functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
+ BIGNUM *mod);
+ void BN_BLINDING_free(BN_BLINDING *b);
+ int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx);
+ int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
+ int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
+ int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
+ BN_CTX *ctx);
+ int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
+ BN_CTX *ctx);
+ unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *);
+ void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long);
+ unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
+ void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
+ BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
+ const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
+ int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
+ const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
+ BN_MONT_CTX *m_ctx);
+
+=head1 DESCRIPTION
+
+BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies
+the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object.
+
+BN_BLINDING_free() frees the B<BN_BLINDING> structure.
+
+BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring
+the B<A> and B<Ai> or, after specific number of uses and if the
+necessary parameters are set, by re-creating the blinding parameters.
+
+BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>.
+If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be
+returned in B<r> (this is useful if a B<RSA> object is shared amoung
+several threads). BN_BLINDING_invert_ex() multiplies B<n> with the
+inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as
+the inverse blinding.
+
+BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper
+functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex()
+with B<r> set to NULL.
+
+BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id()
+set and get the "thread id" value of the B<BN_BLINDING> structure,
+a field provided to users of B<BN_BLINDING> structure to help them
+provide proper locking if needed for multi-threaded use. The
+"thread id" of a newly allocated B<BN_BLINDING> structure is zero.
+
+BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently
+there are two supported flags: B<BN_BLINDING_NO_UPDATE> and
+B<BN_BLINDING_NO_RECREATE>. B<BN_BLINDING_NO_UPDATE> inhibits the
+automatic update of the B<BN_BLINDING> parameters after each use
+and B<BN_BLINDING_NO_RECREATE> inhibits the automatic re-creation
+of the B<BN_BLINDING> parameters after a fixed number of uses (currently
+32). In newly allocated B<BN_BLINDING> objects no flags are set.
+BN_BLINDING_set_flags() sets the B<BN_BLINDING> parameters flags.
+
+BN_BLINDING_create_param() creates new B<BN_BLINDING> parameters
+using the exponent B<e> and the modulus B<m>. B<bn_mod_exp> and
+B<m_ctx> can be used to pass special functions for exponentiation
+(normally BN_mod_exp_mont() and B<BN_MONT_CTX>).
+
+=head1 RETURN VALUES
+
+BN_BLINDING_new() returns the newly allocated B<BN_BLINDING> structure
+or NULL in case of an error.
+
+BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(),
+BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on
+success and 0 if an error occured.
+
+BN_BLINDING_get_thread_id() returns the thread id (a B<unsigned long>
+value) or 0 if not set.
+
+BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags
+(a B<unsigned long> value).
+
+BN_BLINDING_create_param() returns the newly created B<BN_BLINDING>
+parameters or NULL on error.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>
+
+=head1 HISTORY
+
+BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id,
+BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags
+and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8
+
+=head1 AUTHOR
+
+Nils Larsch for the OpenSSL project (http://www.openssl.org).
+
+=cut
diff --git a/doc/crypto/BN_CTX_new.pod b/doc/crypto/BN_CTX_new.pod
new file mode 100644
index 000000000000..ad8d07db89af
--- /dev/null
+++ b/doc/crypto/BN_CTX_new.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BN_CTX *BN_CTX_new(void);
+
+ void BN_CTX_init(BN_CTX *c);
+
+ void BN_CTX_free(BN_CTX *c);
+
+=head1 DESCRIPTION
+
+A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by
+library functions. Since dynamic memory allocation to create B<BIGNUM>s
+is rather expensive when used in conjunction with repeated subroutine
+calls, the B<BN_CTX> structure is used.
+
+BN_CTX_new() allocates and initializes a B<BN_CTX>
+structure. BN_CTX_init() initializes an existing uninitialized
+B<BN_CTX>.
+
+BN_CTX_free() frees the components of the B<BN_CTX>, and if it was
+created by BN_CTX_new(), also the structure itself.
+If L<BN_CTX_start(3)|BN_CTX_start(3)> has been used on the B<BN_CTX>,
+L<BN_CTX_end(3)|BN_CTX_end(3)> must be called before the B<BN_CTX>
+may be freed by BN_CTX_free().
+
+
+=head1 RETURN VALUES
+
+BN_CTX_new() returns a pointer to the B<BN_CTX>. If the allocation fails,
+it returns B<NULL> and sets an error code that can be obtained by
+L<ERR_get_error(3)|ERR_get_error(3)>.
+
+BN_CTX_init() and BN_CTX_free() have no return values.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
+L<BN_CTX_start(3)|BN_CTX_start(3)>
+
+=head1 HISTORY
+
+BN_CTX_new() and BN_CTX_free() are available in all versions on SSLeay
+and OpenSSL. BN_CTX_init() was added in SSLeay 0.9.1b.
+
+=cut
diff --git a/doc/crypto/BN_CTX_start.pod b/doc/crypto/BN_CTX_start.pod
new file mode 100644
index 000000000000..dfcefe1a8876
--- /dev/null
+++ b/doc/crypto/BN_CTX_start.pod
@@ -0,0 +1,52 @@
+=pod
+
+=head1 NAME
+
+BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ void BN_CTX_start(BN_CTX *ctx);
+
+ BIGNUM *BN_CTX_get(BN_CTX *ctx);
+
+ void BN_CTX_end(BN_CTX *ctx);
+
+=head1 DESCRIPTION
+
+These functions are used to obtain temporary B<BIGNUM> variables from
+a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)|BN_CTX_new(3)>)
+in order to save the overhead of repeatedly creating and
+freeing B<BIGNUM>s in functions that are called from inside a loop.
+
+A function must call BN_CTX_start() first. Then, BN_CTX_get() may be
+called repeatedly to obtain temporary B<BIGNUM>s. All BN_CTX_get()
+calls must be made before calling any other functions that use the
+B<ctx> as an argument.
+
+Finally, BN_CTX_end() must be called before returning from the function.
+When BN_CTX_end() is called, the B<BIGNUM> pointers obtained from
+BN_CTX_get() become invalid.
+
+=head1 RETURN VALUES
+
+BN_CTX_start() and BN_CTX_end() return no values.
+
+BN_CTX_get() returns a pointer to the B<BIGNUM>, or B<NULL> on error.
+Once BN_CTX_get() has failed, the subsequent calls will return B<NULL>
+as well, so it is sufficient to check the return value of the last
+BN_CTX_get() call. In case of an error, an error code is set, which
+can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+
+=head1 SEE ALSO
+
+L<BN_CTX_new(3)|BN_CTX_new(3)>
+
+=head1 HISTORY
+
+BN_CTX_start(), BN_CTX_get() and BN_CTX_end() were added in OpenSSL 0.9.5.
+
+=cut
diff --git a/doc/crypto/BN_add.pod b/doc/crypto/BN_add.pod
new file mode 100644
index 000000000000..88c7a799eea5
--- /dev/null
+++ b/doc/crypto/BN_add.pod
@@ -0,0 +1,126 @@
+=pod
+
+=head1 NAME
+
+BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add,
+BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_exp, BN_mod_exp, BN_gcd -
+arithmetic operations on BIGNUMs
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
+
+ int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
+
+ int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
+
+ int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
+
+ int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
+ BN_CTX *ctx);
+
+ int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
+
+ int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
+
+ int BN_mod_add(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+ BN_CTX *ctx);
+
+ int BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+ BN_CTX *ctx);
+
+ int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+ BN_CTX *ctx);
+
+ int BN_mod_sqr(BIGNUM *r, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
+
+ int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx);
+
+ int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
+ const BIGNUM *m, BN_CTX *ctx);
+
+ int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
+
+=head1 DESCRIPTION
+
+BN_add() adds I<a> and I<b> and places the result in I<r> (C<r=a+b>).
+I<r> may be the same B<BIGNUM> as I<a> or I<b>.
+
+BN_sub() subtracts I<b> from I<a> and places the result in I<r> (C<r=a-b>).
+
+BN_mul() multiplies I<a> and I<b> and places the result in I<r> (C<r=a*b>).
+I<r> may be the same B<BIGNUM> as I<a> or I<b>.
+For multiplication by powers of 2, use L<BN_lshift(3)|BN_lshift(3)>.
+
+BN_sqr() takes the square of I<a> and places the result in I<r>
+(C<r=a^2>). I<r> and I<a> may be the same B<BIGNUM>.
+This function is faster than BN_mul(r,a,a).
+
+BN_div() divides I<a> by I<d> and places the result in I<dv> and the
+remainder in I<rem> (C<dv=a/d, rem=a%d>). Either of I<dv> and I<rem> may
+be B<NULL>, in which case the respective value is not returned.
+The result is rounded towards zero; thus if I<a> is negative, the
+remainder will be zero or negative.
+For division by powers of 2, use BN_rshift(3).
+
+BN_mod() corresponds to BN_div() with I<dv> set to B<NULL>.
+
+BN_nnmod() reduces I<a> modulo I<m> and places the non-negative
+remainder in I<r>.
+
+BN_mod_add() adds I<a> to I<b> modulo I<m> and places the non-negative
+result in I<r>.
+
+BN_mod_sub() subtracts I<b> from I<a> modulo I<m> and places the
+non-negative result in I<r>.
+
+BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative
+remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be
+the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for
+repeated computations using the same modulus, see
+L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)> and
+L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>.
+
+BN_mod_sqr() takes the square of I<a> modulo B<m> and places the
+result in I<r>.
+
+BN_exp() raises I<a> to the I<p>-th power and places the result in I<r>
+(C<r=a^p>). This function is faster than repeated applications of
+BN_mul().
+
+BN_mod_exp() computes I<a> to the I<p>-th power modulo I<m> (C<r=a^p %
+m>). This function uses less time and space than BN_exp().
+
+BN_gcd() computes the greatest common divisor of I<a> and I<b> and
+places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or
+I<b>.
+
+For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
+temporary variables; see L<BN_CTX_new(3)|BN_CTX_new(3)>.
+
+Unless noted otherwise, the result B<BIGNUM> must be different from
+the arguments.
+
+=head1 RETURN VALUES
+
+For all functions, 1 is returned for success, 0 on error. The return
+value should always be checked (e.g., C<if (!BN_add(r,a,b)) goto err;>).
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>,
+L<BN_add_word(3)|BN_add_word(3)>, L<BN_set_bit(3)|BN_set_bit(3)>
+
+=head1 HISTORY
+
+BN_add(), BN_sub(), BN_sqr(), BN_div(), BN_mod(), BN_mod_mul(),
+BN_mod_exp() and BN_gcd() are available in all versions of SSLeay and
+OpenSSL. The I<ctx> argument to BN_mul() was added in SSLeay
+0.9.1b. BN_exp() appeared in SSLeay 0.9.0.
+BN_nnmod(), BN_mod_add(), BN_mod_sub(), and BN_mod_sqr() were added in
+OpenSSL 0.9.7.
+
+=cut
diff --git a/doc/crypto/BN_add_word.pod b/doc/crypto/BN_add_word.pod
new file mode 100644
index 000000000000..70667d289345
--- /dev/null
+++ b/doc/crypto/BN_add_word.pod
@@ -0,0 +1,61 @@
+=pod
+
+=head1 NAME
+
+BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic
+functions on BIGNUMs with integers
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_add_word(BIGNUM *a, BN_ULONG w);
+
+ int BN_sub_word(BIGNUM *a, BN_ULONG w);
+
+ int BN_mul_word(BIGNUM *a, BN_ULONG w);
+
+ BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
+
+ BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);
+
+=head1 DESCRIPTION
+
+These functions perform arithmetic operations on BIGNUMs with unsigned
+integers. They are much more efficient than the normal BIGNUM
+arithmetic operations.
+
+BN_add_word() adds B<w> to B<a> (C<a+=w>).
+
+BN_sub_word() subtracts B<w> from B<a> (C<a-=w>).
+
+BN_mul_word() multiplies B<a> and B<w> (C<a*=w>).
+
+BN_div_word() divides B<a> by B<w> (C<a/=w>) and returns the remainder.
+
+BN_mod_word() returns the remainder of B<a> divided by B<w> (C<a%w>).
+
+For BN_div_word() and BN_mod_word(), B<w> must not be 0.
+
+=head1 RETURN VALUES
+
+BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0
+on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+BN_mod_word() and BN_div_word() return B<a>%B<w> on success and
+B<(BN_ULONG)-1> if an error occurred.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>
+
+=head1 HISTORY
+
+BN_add_word() and BN_mod_word() are available in all versions of
+SSLeay and OpenSSL. BN_div_word() was added in SSLeay 0.8, and
+BN_sub_word() and BN_mul_word() in SSLeay 0.9.0.
+
+Before 0.9.8a the return value for BN_div_word() and BN_mod_word()
+in case of an error was 0.
+
+=cut
diff --git a/doc/crypto/BN_bn2bin.pod b/doc/crypto/BN_bn2bin.pod
new file mode 100644
index 000000000000..a4b17ca60a89
--- /dev/null
+++ b/doc/crypto/BN_bn2bin.pod
@@ -0,0 +1,95 @@
+=pod
+
+=head1 NAME
+
+BN_bn2bin, BN_bin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn,
+BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn - format conversions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_bn2bin(const BIGNUM *a, unsigned char *to);
+ BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
+
+ char *BN_bn2hex(const BIGNUM *a);
+ char *BN_bn2dec(const BIGNUM *a);
+ int BN_hex2bn(BIGNUM **a, const char *str);
+ int BN_dec2bn(BIGNUM **a, const char *str);
+
+ int BN_print(BIO *fp, const BIGNUM *a);
+ int BN_print_fp(FILE *fp, const BIGNUM *a);
+
+ int BN_bn2mpi(const BIGNUM *a, unsigned char *to);
+ BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);
+
+=head1 DESCRIPTION
+
+BN_bn2bin() converts the absolute value of B<a> into big-endian form
+and stores it at B<to>. B<to> must point to BN_num_bytes(B<a>) bytes of
+memory.
+
+BN_bin2bn() converts the positive integer in big-endian form of length
+B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If B<ret> is
+NULL, a new B<BIGNUM> is created.
+
+BN_bn2hex() and BN_bn2dec() return printable strings containing the
+hexadecimal and decimal encoding of B<a> respectively. For negative
+numbers, the string is prefaced with a leading '-'. The string must be
+freed later using OPENSSL_free().
+
+BN_hex2bn() converts the string B<str> containing a hexadecimal number
+to a B<BIGNUM> and stores it in **B<bn>. If *B<bn> is NULL, a new
+B<BIGNUM> is created. If B<bn> is NULL, it only computes the number's
+length in hexadecimal digits. If the string starts with '-', the
+number is negative. BN_dec2bn() is the same using the decimal system.
+
+BN_print() and BN_print_fp() write the hexadecimal encoding of B<a>,
+with a leading '-' for negative numbers, to the B<BIO> or B<FILE>
+B<fp>.
+
+BN_bn2mpi() and BN_mpi2bn() convert B<BIGNUM>s from and to a format
+that consists of the number's length in bytes represented as a 4-byte
+big-endian number, and the number itself in big-endian format, where
+the most significant bit signals a negative number (the representation
+of numbers with the MSB set is prefixed with null byte).
+
+BN_bn2mpi() stores the representation of B<a> at B<to>, where B<to>
+must be large enough to hold the result. The size can be determined by
+calling BN_bn2mpi(B<a>, NULL).
+
+BN_mpi2bn() converts the B<len> bytes long representation at B<s> to
+a B<BIGNUM> and stores it at B<ret>, or in a newly allocated B<BIGNUM>
+if B<ret> is NULL.
+
+=head1 RETURN VALUES
+
+BN_bn2bin() returns the length of the big-endian number placed at B<to>.
+BN_bin2bn() returns the B<BIGNUM>, NULL on error.
+
+BN_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL
+on error. BN_hex2bn() and BN_dec2bn() return the number's length in
+hexadecimal or decimal digits, and 0 on error.
+
+BN_print_fp() and BN_print() return 1 on success, 0 on write errors.
+
+BN_bn2mpi() returns the length of the representation. BN_mpi2bn()
+returns the B<BIGNUM>, and NULL on error.
+
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_zero(3)|BN_zero(3)>,
+L<ASN1_INTEGER_to_BN(3)|ASN1_INTEGER_to_BN(3)>,
+L<BN_num_bytes(3)|BN_num_bytes(3)>
+
+=head1 HISTORY
+
+BN_bn2bin(), BN_bin2bn(), BN_print_fp() and BN_print() are available
+in all versions of SSLeay and OpenSSL.
+
+BN_bn2hex(), BN_bn2dec(), BN_hex2bn(), BN_dec2bn(), BN_bn2mpi() and
+BN_mpi2bn() were added in SSLeay 0.9.0.
+
+=cut
diff --git a/doc/crypto/BN_cmp.pod b/doc/crypto/BN_cmp.pod
new file mode 100644
index 000000000000..23e9ed0b4f95
--- /dev/null
+++ b/doc/crypto/BN_cmp.pod
@@ -0,0 +1,48 @@
+=pod
+
+=head1 NAME
+
+BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_is_odd - BIGNUM comparison and test functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_cmp(BIGNUM *a, BIGNUM *b);
+ int BN_ucmp(BIGNUM *a, BIGNUM *b);
+
+ int BN_is_zero(BIGNUM *a);
+ int BN_is_one(BIGNUM *a);
+ int BN_is_word(BIGNUM *a, BN_ULONG w);
+ int BN_is_odd(BIGNUM *a);
+
+=head1 DESCRIPTION
+
+BN_cmp() compares the numbers B<a> and B<b>. BN_ucmp() compares their
+absolute values.
+
+BN_is_zero(), BN_is_one() and BN_is_word() test if B<a> equals 0, 1,
+or B<w> respectively. BN_is_odd() tests if a is odd.
+
+BN_is_zero(), BN_is_one(), BN_is_word() and BN_is_odd() are macros.
+
+=head1 RETURN VALUES
+
+BN_cmp() returns -1 if B<a> E<lt> B<b>, 0 if B<a> == B<b> and 1 if
+B<a> E<gt> B<b>. BN_ucmp() is the same using the absolute values
+of B<a> and B<b>.
+
+BN_is_zero(), BN_is_one() BN_is_word() and BN_is_odd() return 1 if
+the condition is true, 0 otherwise.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>
+
+=head1 HISTORY
+
+BN_cmp(), BN_ucmp(), BN_is_zero(), BN_is_one() and BN_is_word() are
+available in all versions of SSLeay and OpenSSL.
+BN_is_odd() was added in SSLeay 0.8.
+
+=cut
diff --git a/doc/crypto/BN_copy.pod b/doc/crypto/BN_copy.pod
new file mode 100644
index 000000000000..388dd7df2653
--- /dev/null
+++ b/doc/crypto/BN_copy.pod
@@ -0,0 +1,34 @@
+=pod
+
+=head1 NAME
+
+BN_copy, BN_dup - copy BIGNUMs
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from);
+
+ BIGNUM *BN_dup(const BIGNUM *from);
+
+=head1 DESCRIPTION
+
+BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM>
+containing the value B<from>.
+
+=head1 RETURN VALUES
+
+BN_copy() returns B<to> on success, NULL on error. BN_dup() returns
+the new B<BIGNUM>, and NULL on error. The error codes can be obtained
+by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+BN_copy() and BN_dup() are available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/BN_generate_prime.pod b/doc/crypto/BN_generate_prime.pod
new file mode 100644
index 000000000000..7dccacbc1e55
--- /dev/null
+++ b/doc/crypto/BN_generate_prime.pod
@@ -0,0 +1,102 @@
+=pod
+
+=head1 NAME
+
+BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
+ BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);
+
+ int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int,
+ void *), BN_CTX *ctx, void *cb_arg);
+
+ int BN_is_prime_fasttest(const BIGNUM *a, int checks,
+ void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg,
+ int do_trial_division);
+
+=head1 DESCRIPTION
+
+BN_generate_prime() generates a pseudo-random prime number of B<num>
+bits.
+If B<ret> is not B<NULL>, it will be used to store the number.
+
+If B<callback> is not B<NULL>, it is called as follows:
+
+=over 4
+
+=item *
+
+B<callback(0, i, cb_arg)> is called after generating the i-th
+potential prime number.
+
+=item *
+
+While the number is being tested for primality, B<callback(1, j,
+cb_arg)> is called as described below.
+
+=item *
+
+When a prime has been found, B<callback(2, i, cb_arg)> is called.
+
+=back
+
+The prime may have to fulfill additional requirements for use in
+Diffie-Hellman key exchange:
+
+If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add>
+== B<rem> (p % B<add> == 1 if B<rem> == B<NULL>) in order to suit a given
+generator.
+
+If B<safe> is true, it will be a safe prime (i.e. a prime p so
+that (p-1)/2 is also prime).
+
+The PRNG must be seeded prior to calling BN_generate_prime().
+The prime number generation has a negligible error probability.
+
+BN_is_prime() and BN_is_prime_fasttest() test if the number B<a> is
+prime. The following tests are performed until one of them shows that
+B<a> is composite; if B<a> passes all these tests, it is considered
+prime.
+
+BN_is_prime_fasttest(), when called with B<do_trial_division == 1>,
+first attempts trial division by a number of small primes;
+if no divisors are found by this test and B<callback> is not B<NULL>,
+B<callback(1, -1, cb_arg)> is called.
+If B<do_trial_division == 0>, this test is skipped.
+
+Both BN_is_prime() and BN_is_prime_fasttest() perform a Miller-Rabin
+probabilistic primality test with B<checks> iterations. If
+B<checks == BN_prime_checks>, a number of iterations is used that
+yields a false positive rate of at most 2^-80 for random input.
+
+If B<callback> is not B<NULL>, B<callback(1, j, cb_arg)> is called
+after the j-th iteration (j = 0, 1, ...). B<ctx> is a
+pre-allocated B<BN_CTX> (to save the overhead of allocating and
+freeing the structure in a loop), or B<NULL>.
+
+=head1 RETURN VALUES
+
+BN_generate_prime() returns the prime number on success, B<NULL> otherwise.
+
+BN_is_prime() returns 0 if the number is composite, 1 if it is
+prime with an error probability of less than 0.25^B<checks>, and
+-1 on error.
+
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>
+
+=head1 HISTORY
+
+The B<cb_arg> arguments to BN_generate_prime() and to BN_is_prime()
+were added in SSLeay 0.9.0. The B<ret> argument to BN_generate_prime()
+was added in SSLeay 0.9.1.
+BN_is_prime_fasttest() was added in OpenSSL 0.9.5.
+
+=cut
diff --git a/doc/crypto/BN_mod_inverse.pod b/doc/crypto/BN_mod_inverse.pod
new file mode 100644
index 000000000000..3ea3975c7422
--- /dev/null
+++ b/doc/crypto/BN_mod_inverse.pod
@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+BN_mod_inverse - compute inverse modulo n
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,
+ BN_CTX *ctx);
+
+=head1 DESCRIPTION
+
+BN_mod_inverse() computes the inverse of B<a> modulo B<n>
+places the result in B<r> (C<(a*r)%n==1>). If B<r> is NULL,
+a new B<BIGNUM> is created.
+
+B<ctx> is a previously allocated B<BN_CTX> used for temporary
+variables. B<r> may be the same B<BIGNUM> as B<a> or B<n>.
+
+=head1 RETURN VALUES
+
+BN_mod_inverse() returns the B<BIGNUM> containing the inverse, and
+NULL on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>
+
+=head1 HISTORY
+
+BN_mod_inverse() is available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/BN_mod_mul_montgomery.pod b/doc/crypto/BN_mod_mul_montgomery.pod
new file mode 100644
index 000000000000..6b16351b92e4
--- /dev/null
+++ b/doc/crypto/BN_mod_mul_montgomery.pod
@@ -0,0 +1,101 @@
+=pod
+
+=head1 NAME
+
+BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init,
+BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy,
+BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BN_MONT_CTX *BN_MONT_CTX_new(void);
+ void BN_MONT_CTX_init(BN_MONT_CTX *ctx);
+ void BN_MONT_CTX_free(BN_MONT_CTX *mont);
+
+ int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
+ BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
+
+ int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
+ BN_MONT_CTX *mont, BN_CTX *ctx);
+
+ int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
+ BN_CTX *ctx);
+
+ int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
+ BN_CTX *ctx);
+
+=head1 DESCRIPTION
+
+These functions implement Montgomery multiplication. They are used
+automatically when L<BN_mod_exp(3)|BN_mod_exp(3)> is called with suitable input,
+but they may be useful when several operations are to be performed
+using the same modulus.
+
+BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure.
+BN_MONT_CTX_init() initializes an existing uninitialized B<BN_MONT_CTX>.
+
+BN_MONT_CTX_set() sets up the I<mont> structure from the modulus I<m>
+by precomputing its inverse and a value R.
+
+BN_MONT_CTX_copy() copies the B<BN_MONT_CTX> I<from> to I<to>.
+
+BN_MONT_CTX_free() frees the components of the B<BN_MONT_CTX>, and, if
+it was created by BN_MONT_CTX_new(), also the structure itself.
+
+BN_mod_mul_montgomery() computes Mont(I<a>,I<b>):=I<a>*I<b>*R^-1 and places
+the result in I<r>.
+
+BN_from_montgomery() performs the Montgomery reduction I<r> = I<a>*R^-1.
+
+BN_to_montgomery() computes Mont(I<a>,R^2), i.e. I<a>*R.
+Note that I<a> must be non-negative and smaller than the modulus.
+
+For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
+temporary variables.
+
+The B<BN_MONT_CTX> structure is defined as follows:
+
+ typedef struct bn_mont_ctx_st
+ {
+ int ri; /* number of bits in R */
+ BIGNUM RR; /* R^2 (used to convert to Montgomery form) */
+ BIGNUM N; /* The modulus */
+ BIGNUM Ni; /* R*(1/R mod N) - N*Ni = 1
+ * (Ni is only stored for bignum algorithm) */
+ BN_ULONG n0; /* least significant word of Ni */
+ int flags;
+ } BN_MONT_CTX;
+
+BN_to_montgomery() is a macro.
+
+=head1 RETURN VALUES
+
+BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL
+on error.
+
+BN_MONT_CTX_init() and BN_MONT_CTX_free() have no return values.
+
+For the other functions, 1 is returned for success, 0 on error.
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 WARNING
+
+The inputs must be reduced modulo B<m>, otherwise the result will be
+outside the expected range.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
+L<BN_CTX_new(3)|BN_CTX_new(3)>
+
+=head1 HISTORY
+
+BN_MONT_CTX_new(), BN_MONT_CTX_free(), BN_MONT_CTX_set(),
+BN_mod_mul_montgomery(), BN_from_montgomery() and BN_to_montgomery()
+are available in all versions of SSLeay and OpenSSL.
+
+BN_MONT_CTX_init() and BN_MONT_CTX_copy() were added in SSLeay 0.9.1b.
+
+=cut
diff --git a/doc/crypto/BN_mod_mul_reciprocal.pod b/doc/crypto/BN_mod_mul_reciprocal.pod
new file mode 100644
index 000000000000..74a216ddc2ad
--- /dev/null
+++ b/doc/crypto/BN_mod_mul_reciprocal.pod
@@ -0,0 +1,81 @@
+=pod
+
+=head1 NAME
+
+BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init,
+BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using
+reciprocal
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BN_RECP_CTX *BN_RECP_CTX_new(void);
+ void BN_RECP_CTX_init(BN_RECP_CTX *recp);
+ void BN_RECP_CTX_free(BN_RECP_CTX *recp);
+
+ int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);
+
+ int BN_div_recp(BIGNUM *dv, BIGNUM *rem, BIGNUM *a, BN_RECP_CTX *recp,
+ BN_CTX *ctx);
+
+ int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,
+ BN_RECP_CTX *recp, BN_CTX *ctx);
+
+=head1 DESCRIPTION
+
+BN_mod_mul_reciprocal() can be used to perform an efficient
+L<BN_mod_mul(3)|BN_mod_mul(3)> operation when the operation will be performed
+repeatedly with the same modulus. It computes B<r>=(B<a>*B<b>)%B<m>
+using B<recp>=1/B<m>, which is set as described below. B<ctx> is a
+previously allocated B<BN_CTX> used for temporary variables.
+
+BN_RECP_CTX_new() allocates and initializes a B<BN_RECP> structure.
+BN_RECP_CTX_init() initializes an existing uninitialized B<BN_RECP>.
+
+BN_RECP_CTX_free() frees the components of the B<BN_RECP>, and, if it
+was created by BN_RECP_CTX_new(), also the structure itself.
+
+BN_RECP_CTX_set() stores B<m> in B<recp> and sets it up for computing
+1/B<m> and shifting it left by BN_num_bits(B<m>)+1 to make it an
+integer. The result and the number of bits it was shifted left will
+later be stored in B<recp>.
+
+BN_div_recp() divides B<a> by B<m> using B<recp>. It places the quotient
+in B<dv> and the remainder in B<rem>.
+
+The B<BN_RECP_CTX> structure is defined as follows:
+
+ typedef struct bn_recp_ctx_st
+ {
+ BIGNUM N; /* the divisor */
+ BIGNUM Nr; /* the reciprocal */
+ int num_bits;
+ int shift;
+ int flags;
+ } BN_RECP_CTX;
+
+It cannot be shared between threads.
+
+=head1 RETURN VALUES
+
+BN_RECP_CTX_new() returns the newly allocated B<BN_RECP_CTX>, and NULL
+on error.
+
+BN_RECP_CTX_init() and BN_RECP_CTX_free() have no return values.
+
+For the other functions, 1 is returned for success, 0 on error.
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
+L<BN_CTX_new(3)|BN_CTX_new(3)>
+
+=head1 HISTORY
+
+B<BN_RECP_CTX> was added in SSLeay 0.9.0. Before that, the function
+BN_reciprocal() was used instead, and the BN_mod_mul_reciprocal()
+arguments were different.
+
+=cut
diff --git a/doc/crypto/BN_new.pod b/doc/crypto/BN_new.pod
new file mode 100644
index 000000000000..ab7a105e3ad7
--- /dev/null
+++ b/doc/crypto/BN_new.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BIGNUM *BN_new(void);
+
+ void BN_init(BIGNUM *);
+
+ void BN_clear(BIGNUM *a);
+
+ void BN_free(BIGNUM *a);
+
+ void BN_clear_free(BIGNUM *a);
+
+=head1 DESCRIPTION
+
+BN_new() allocates and initializes a B<BIGNUM> structure. BN_init()
+initializes an existing uninitialized B<BIGNUM>.
+
+BN_clear() is used to destroy sensitive data such as keys when they
+are no longer needed. It erases the memory used by B<a> and sets it
+to the value 0.
+
+BN_free() frees the components of the B<BIGNUM>, and if it was created
+by BN_new(), also the structure itself. BN_clear_free() additionally
+overwrites the data before the memory is returned to the system.
+
+=head1 RETURN VALUES
+
+BN_new() returns a pointer to the B<BIGNUM>. If the allocation fails,
+it returns B<NULL> and sets an error code that can be obtained
+by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+BN_init(), BN_clear(), BN_free() and BN_clear_free() have no return
+values.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+BN_new(), BN_clear(), BN_free() and BN_clear_free() are available in
+all versions on SSLeay and OpenSSL. BN_init() was added in SSLeay
+0.9.1b.
+
+=cut
diff --git a/doc/crypto/BN_num_bytes.pod b/doc/crypto/BN_num_bytes.pod
new file mode 100644
index 000000000000..a6a2e3f81988
--- /dev/null
+++ b/doc/crypto/BN_num_bytes.pod
@@ -0,0 +1,57 @@
+=pod
+
+=head1 NAME
+
+BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_num_bytes(const BIGNUM *a);
+
+ int BN_num_bits(const BIGNUM *a);
+
+ int BN_num_bits_word(BN_ULONG w);
+
+=head1 DESCRIPTION
+
+BN_num_bytes() returns the size of a B<BIGNUM> in bytes.
+
+BN_num_bits_word() returns the number of significant bits in a word.
+If we take 0x00000432 as an example, it returns 11, not 16, not 32.
+Basically, except for a zero, it returns I<floor(log2(w))+1>.
+
+BN_num_bits() returns the number of significant bits in a B<BIGNUM>,
+following the same principle as BN_num_bits_word().
+
+BN_num_bytes() is a macro.
+
+=head1 RETURN VALUES
+
+The size.
+
+=head1 NOTES
+
+Some have tried using BN_num_bits() on individual numbers in RSA keys,
+DH keys and DSA keys, and found that they don't always come up with
+the number of bits they expected (something like 512, 1024, 2048,
+...). This is because generating a number with some specific number
+of bits doesn't always set the highest bits, thereby making the number
+of I<significant> bits a little lower. If you want to know the "key
+size" of such a key, either use functions like RSA_size(), DH_size()
+and DSA_size(), or use BN_num_bytes() and multiply with 8 (although
+there's no real guarantee that will match the "key size", just a lot
+more probability).
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<DH_size(3)|DH_size(3)>, L<DSA_size(3)|DSA_size(3)>,
+L<RSA_size(3)|RSA_size(3)>
+
+=head1 HISTORY
+
+BN_num_bytes(), BN_num_bits() and BN_num_bits_word() are available in
+all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/BN_rand.pod b/doc/crypto/BN_rand.pod
new file mode 100644
index 000000000000..81f93c2eb3a4
--- /dev/null
+++ b/doc/crypto/BN_rand.pod
@@ -0,0 +1,58 @@
+=pod
+
+=head1 NAME
+
+BN_rand, BN_pseudo_rand - generate pseudo-random number
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
+
+ int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
+
+ int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
+
+ int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);
+
+=head1 DESCRIPTION
+
+BN_rand() generates a cryptographically strong pseudo-random number of
+B<bits> bits in length and stores it in B<rnd>. If B<top> is -1, the
+most significant bit of the random number can be zero. If B<top> is 0,
+it is set to 1, and if B<top> is 1, the two most significant bits of
+the number will be set to 1, so that the product of two such random
+numbers will always have 2*B<bits> length. If B<bottom> is true, the
+number will be odd.
+
+BN_pseudo_rand() does the same, but pseudo-random numbers generated by
+this function are not necessarily unpredictable. They can be used for
+non-cryptographic purposes and for certain purposes in cryptographic
+protocols, but usually not for key generation etc.
+
+BN_rand_range() generates a cryptographically strong pseudo-random
+number B<rnd> in the range 0 <lt>= B<rnd> E<lt> B<range>.
+BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(),
+and hence numbers generated by it are not necessarily unpredictable.
+
+The PRNG must be seeded prior to calling BN_rand() or BN_rand_range().
+
+=head1 RETURN VALUES
+
+The functions return 1 on success, 0 on error.
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
+L<RAND_add(3)|RAND_add(3)>, L<RAND_bytes(3)|RAND_bytes(3)>
+
+=head1 HISTORY
+
+BN_rand() is available in all versions of SSLeay and OpenSSL.
+BN_pseudo_rand() was added in OpenSSL 0.9.5. The B<top> == -1 case
+and the function BN_rand_range() were added in OpenSSL 0.9.6a.
+BN_pseudo_rand_range() was added in OpenSSL 0.9.6c.
+
+=cut
diff --git a/doc/crypto/BN_set_bit.pod b/doc/crypto/BN_set_bit.pod
new file mode 100644
index 000000000000..b7c47b9b0158
--- /dev/null
+++ b/doc/crypto/BN_set_bit.pod
@@ -0,0 +1,66 @@
+=pod
+
+=head1 NAME
+
+BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift,
+BN_lshift1, BN_rshift, BN_rshift1 - bit operations on BIGNUMs
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_set_bit(BIGNUM *a, int n);
+ int BN_clear_bit(BIGNUM *a, int n);
+
+ int BN_is_bit_set(const BIGNUM *a, int n);
+
+ int BN_mask_bits(BIGNUM *a, int n);
+
+ int BN_lshift(BIGNUM *r, const BIGNUM *a, int n);
+ int BN_lshift1(BIGNUM *r, BIGNUM *a);
+
+ int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
+ int BN_rshift1(BIGNUM *r, BIGNUM *a);
+
+=head1 DESCRIPTION
+
+BN_set_bit() sets bit B<n> in B<a> to 1 (C<a|=(1E<lt>E<lt>n)>). The
+number is expanded if necessary.
+
+BN_clear_bit() sets bit B<n> in B<a> to 0 (C<a&=~(1E<lt>E<lt>n)>). An
+error occurs if B<a> is shorter than B<n> bits.
+
+BN_is_bit_set() tests if bit B<n> in B<a> is set.
+
+BN_mask_bits() truncates B<a> to an B<n> bit number
+(C<a&=~((~0)E<gt>E<gt>n)>). An error occurs if B<a> already is
+shorter than B<n> bits.
+
+BN_lshift() shifts B<a> left by B<n> bits and places the result in
+B<r> (C<r=a*2^n>). BN_lshift1() shifts B<a> left by one and places
+the result in B<r> (C<r=2*a>).
+
+BN_rshift() shifts B<a> right by B<n> bits and places the result in
+B<r> (C<r=a/2^n>). BN_rshift1() shifts B<a> right by one and places
+the result in B<r> (C<r=a/2>).
+
+For the shift functions, B<r> and B<a> may be the same variable.
+
+=head1 RETURN VALUES
+
+BN_is_bit_set() returns 1 if the bit is set, 0 otherwise.
+
+All other functions return 1 for success, 0 on error. The error codes
+can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, L<BN_add(3)|BN_add(3)>
+
+=head1 HISTORY
+
+BN_set_bit(), BN_clear_bit(), BN_is_bit_set(), BN_mask_bits(),
+BN_lshift(), BN_lshift1(), BN_rshift(), and BN_rshift1() are available
+in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/BN_swap.pod b/doc/crypto/BN_swap.pod
new file mode 100644
index 000000000000..79efaa144634
--- /dev/null
+++ b/doc/crypto/BN_swap.pod
@@ -0,0 +1,23 @@
+=pod
+
+=head1 NAME
+
+BN_swap - exchange BIGNUMs
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ void BN_swap(BIGNUM *a, BIGNUM *b);
+
+=head1 DESCRIPTION
+
+BN_swap() exchanges the values of I<a> and I<b>.
+
+L<bn(3)|bn(3)>
+
+=head1 HISTORY
+
+BN_swap was added in OpenSSL 0.9.7.
+
+=cut
diff --git a/doc/crypto/BN_zero.pod b/doc/crypto/BN_zero.pod
new file mode 100644
index 000000000000..b555ec398859
--- /dev/null
+++ b/doc/crypto/BN_zero.pod
@@ -0,0 +1,59 @@
+=pod
+
+=head1 NAME
+
+BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment
+operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_zero(BIGNUM *a);
+ int BN_one(BIGNUM *a);
+
+ const BIGNUM *BN_value_one(void);
+
+ int BN_set_word(BIGNUM *a, unsigned long w);
+ unsigned long BN_get_word(BIGNUM *a);
+
+=head1 DESCRIPTION
+
+BN_zero(), BN_one() and BN_set_word() set B<a> to the values 0, 1 and
+B<w> respectively. BN_zero() and BN_one() are macros.
+
+BN_value_one() returns a B<BIGNUM> constant of value 1. This constant
+is useful for use in comparisons and assignment.
+
+BN_get_word() returns B<a>, if it can be represented as an unsigned
+long.
+
+=head1 RETURN VALUES
+
+BN_get_word() returns the value B<a>, and 0xffffffffL if B<a> cannot
+be represented as an unsigned long.
+
+BN_zero(), BN_one() and BN_set_word() return 1 on success, 0 otherwise.
+BN_value_one() returns the constant.
+
+=head1 BUGS
+
+Someone might change the constant.
+
+If a B<BIGNUM> is equal to 0xffffffffL it can be represented as an
+unsigned long but this value is also returned on error.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)>
+
+=head1 HISTORY
+
+BN_zero(), BN_one() and BN_set_word() are available in all versions of
+SSLeay and OpenSSL. BN_value_one() and BN_get_word() were added in
+SSLeay 0.8.
+
+BN_value_one() was changed to return a true const BIGNUM * in OpenSSL
+0.9.7.
+
+=cut
diff --git a/doc/crypto/CONF_modules_free.pod b/doc/crypto/CONF_modules_free.pod
new file mode 100644
index 000000000000..87bc7b783c9e
--- /dev/null
+++ b/doc/crypto/CONF_modules_free.pod
@@ -0,0 +1,47 @@
+=pod
+
+=head1 NAME
+
+ CONF_modules_free, CONF_modules_finish, CONF_modules_unload -
+ OpenSSL configuration cleanup functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/conf.h>
+
+ void CONF_modules_free(void);
+ void CONF_modules_finish(void);
+ void CONF_modules_unload(int all);
+
+=head1 DESCRIPTION
+
+CONF_modules_free() closes down and frees up all memory allocated by all
+configuration modules.
+
+CONF_modules_finish() calls each configuration modules B<finish> handler
+to free up any configuration that module may have performed.
+
+CONF_modules_unload() finishes and unloads configuration modules. If
+B<all> is set to B<0> only modules loaded from DSOs will be unloads. If
+B<all> is B<1> all modules, including builtin modules will be unloaded.
+
+=head1 NOTES
+
+Normally applications will only call CONF_modules_free() at application to
+tidy up any configuration performed.
+
+=head1 RETURN VALUE
+
+None of the functions return a value.
+
+=head1 SEE ALSO
+
+L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>,
+L<CONF_modules_load_file(3), CONF_modules_load_file(3)>
+
+=head1 HISTORY
+
+CONF_modules_free(), CONF_modules_unload(), and CONF_modules_finish()
+first appeared in OpenSSL 0.9.7.
+
+=cut
diff --git a/doc/crypto/CONF_modules_load_file.pod b/doc/crypto/CONF_modules_load_file.pod
new file mode 100644
index 000000000000..9965d69bf2ec
--- /dev/null
+++ b/doc/crypto/CONF_modules_load_file.pod
@@ -0,0 +1,60 @@
+=pod
+
+=head1 NAME
+
+ CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/conf.h>
+
+ int CONF_modules_load_file(const char *filename, const char *appname,
+ unsigned long flags);
+ int CONF_modules_load(const CONF *cnf, const char *appname,
+ unsigned long flags);
+
+=head1 DESCRIPTION
+
+The function CONF_modules_load_file() configures OpenSSL using file
+B<filename> and application name B<appname>. If B<filename> is NULL
+the standard OpenSSL configuration file is used. If B<appname> is
+NULL the standard OpenSSL application name B<openssl_conf> is used.
+The behaviour can be cutomized using B<flags>.
+
+CONF_modules_load() is idential to CONF_modules_load_file() except it
+read configuration information from B<cnf>.
+
+=head1 NOTES
+
+The following B<flags> are currently recognized:
+
+B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual
+configuration modules are ignored. If not set the first module error is
+considered fatal and no further modules are loads.
+
+Normally any modules errors will add error information to the error queue. If
+B<CONF_MFLAGS_SILENT> is set no error information is added.
+
+If B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is
+disabled.
+
+B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file()
+ignore missing configuration files. Normally a missing configuration file
+return an error.
+
+=head1 RETURN VALUE
+
+These functions return 1 for success and a zero or negative value for
+failure. If module errors are not ignored the return code will reflect the
+return value of the failing module (this will always be zero or negative).
+
+=head1 SEE ALSO
+
+L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>,
+L<CONF_free(3), CONF_free(3)>, L<err(3),err(3)>
+
+=head1 HISTORY
+
+CONF_modules_load_file and CONF_modules_load first appeared in OpenSSL 0.9.7.
+
+=cut
diff --git a/doc/crypto/CRYPTO_set_ex_data.pod b/doc/crypto/CRYPTO_set_ex_data.pod
new file mode 100644
index 000000000000..1bd5bed67d70
--- /dev/null
+++ b/doc/crypto/CRYPTO_set_ex_data.pod
@@ -0,0 +1,51 @@
+=pod
+
+=head1 NAME
+
+CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data functions
+
+=head1 SYNOPSIS
+
+ int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
+
+ void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);
+
+=head1 DESCRIPTION
+
+Several OpenSSL structures can have application specific data attached to them.
+These functions are used internally by OpenSSL to manipulate application
+specific data attached to a specific structure.
+
+These functions should only be used by applications to manipulate
+B<CRYPTO_EX_DATA> structures passed to the B<new_func()>, B<free_func()> and
+B<dup_func()> callbacks: as passed to B<RSA_get_ex_new_index()> for example.
+
+B<CRYPTO_set_ex_data()> is used to set application specific data, the data is
+supplied in the B<arg> parameter and its precise meaning is up to the
+application.
+
+B<CRYPTO_get_ex_data()> is used to retrieve application specific data. The data
+is returned to the application, this will be the same value as supplied to
+a previous B<CRYPTO_set_ex_data()> call.
+
+=head1 RETURN VALUES
+
+B<CRYPTO_set_ex_data()> returns 1 on success or 0 on failure.
+
+B<CRYPTO_get_ex_data()> returns the application data or 0 on failure. 0 may also
+be valid application data but currently it can only fail if given an invalid B<idx>
+parameter.
+
+On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
+L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>,
+L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>
+
+=head1 HISTORY
+
+CRYPTO_set_ex_data() and CRYPTO_get_ex_data() have been available since SSLeay 0.9.0.
+
+=cut
diff --git a/doc/crypto/DH_generate_key.pod b/doc/crypto/DH_generate_key.pod
new file mode 100644
index 000000000000..81f09fdf45ea
--- /dev/null
+++ b/doc/crypto/DH_generate_key.pod
@@ -0,0 +1,50 @@
+=pod
+
+=head1 NAME
+
+DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ int DH_generate_key(DH *dh);
+
+ int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
+
+=head1 DESCRIPTION
+
+DH_generate_key() performs the first step of a Diffie-Hellman key
+exchange by generating private and public DH values. By calling
+DH_compute_key(), these are combined with the other party's public
+value to compute the shared key.
+
+DH_generate_key() expects B<dh> to contain the shared parameters
+B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value
+unless B<dh-E<gt>priv_key> is already set, and computes the
+corresponding public value B<dh-E<gt>pub_key>, which can then be
+published.
+
+DH_compute_key() computes the shared secret from the private DH value
+in B<dh> and the other party's public value in B<pub_key> and stores
+it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory.
+
+=head1 RETURN VALUES
+
+DH_generate_key() returns 1 on success, 0 otherwise.
+
+DH_compute_key() returns the size of the shared secret on success, -1
+on error.
+
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<DH_size(3)|DH_size(3)>
+
+=head1 HISTORY
+
+DH_generate_key() and DH_compute_key() are available in all versions
+of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/DH_generate_parameters.pod b/doc/crypto/DH_generate_parameters.pod
new file mode 100644
index 000000000000..9081e9ea7cf9
--- /dev/null
+++ b/doc/crypto/DH_generate_parameters.pod
@@ -0,0 +1,73 @@
+=pod
+
+=head1 NAME
+
+DH_generate_parameters, DH_check - generate and check Diffie-Hellman parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ DH *DH_generate_parameters(int prime_len, int generator,
+ void (*callback)(int, int, void *), void *cb_arg);
+
+ int DH_check(DH *dh, int *codes);
+
+=head1 DESCRIPTION
+
+DH_generate_parameters() generates Diffie-Hellman parameters that can
+be shared among a group of users, and returns them in a newly
+allocated B<DH> structure. The pseudo-random number generator must be
+seeded prior to calling DH_generate_parameters().
+
+B<prime_len> is the length in bits of the safe prime to be generated.
+B<generator> is a small number E<gt> 1, typically 2 or 5.
+
+A callback function may be used to provide feedback about the progress
+of the key generation. If B<callback> is not B<NULL>, it will be
+called as described in L<BN_generate_prime(3)|BN_generate_prime(3)> while a random prime
+number is generated, and when a prime has been found, B<callback(3,
+0, cb_arg)> is called.
+
+DH_check() validates Diffie-Hellman parameters. It checks that B<p> is
+a safe prime, and that B<g> is a suitable generator. In the case of an
+error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or
+DH_NOT_SUITABLE_GENERATOR are set in B<*codes>.
+DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be
+checked, i.e. it does not equal 2 or 5.
+
+=head1 RETURN VALUES
+
+DH_generate_parameters() returns a pointer to the DH structure, or
+NULL if the parameter generation fails. The error codes can be
+obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+DH_check() returns 1 if the check could be performed, 0 otherwise.
+
+=head1 NOTES
+
+DH_generate_parameters() may run for several hours before finding a
+suitable prime.
+
+The parameters generated by DH_generate_parameters() are not to be
+used in signature schemes.
+
+=head1 BUGS
+
+If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not
+a usable generator.
+
+=head1 SEE ALSO
+
+L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
+L<DH_free(3)|DH_free(3)>
+
+=head1 HISTORY
+
+DH_check() is available in all versions of SSLeay and OpenSSL.
+The B<cb_arg> argument to DH_generate_parameters() was added in SSLeay 0.9.0.
+
+In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used
+instead of DH_CHECK_P_NOT_SAFE_PRIME.
+
+=cut
diff --git a/doc/crypto/DH_get_ex_new_index.pod b/doc/crypto/DH_get_ex_new_index.pod
new file mode 100644
index 000000000000..fa5eab26502a
--- /dev/null
+++ b/doc/crypto/DH_get_ex_new_index.pod
@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific data to DH structures
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ int DH_get_ex_new_index(long argl, void *argp,
+ CRYPTO_EX_new *new_func,
+ CRYPTO_EX_dup *dup_func,
+ CRYPTO_EX_free *free_func);
+
+ int DH_set_ex_data(DH *d, int idx, void *arg);
+
+ char *DH_get_ex_data(DH *d, int idx);
+
+=head1 DESCRIPTION
+
+These functions handle application specific data in DH
+structures. Their usage is identical to that of
+RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data()
+as described in L<RSA_get_ex_new_index(3)>.
+
+=head1 SEE ALSO
+
+L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dh(3)|dh(3)>
+
+=head1 HISTORY
+
+DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are
+available since OpenSSL 0.9.5.
+
+=cut
diff --git a/doc/crypto/DH_new.pod b/doc/crypto/DH_new.pod
new file mode 100644
index 000000000000..60c930093e02
--- /dev/null
+++ b/doc/crypto/DH_new.pod
@@ -0,0 +1,40 @@
+=pod
+
+=head1 NAME
+
+DH_new, DH_free - allocate and free DH objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ DH* DH_new(void);
+
+ void DH_free(DH *dh);
+
+=head1 DESCRIPTION
+
+DH_new() allocates and initializes a B<DH> structure.
+
+DH_free() frees the B<DH> structure and its components. The values are
+erased before the memory is returned to the system.
+
+=head1 RETURN VALUES
+
+If the allocation fails, DH_new() returns B<NULL> and sets an error
+code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns
+a pointer to the newly allocated structure.
+
+DH_free() returns no value.
+
+=head1 SEE ALSO
+
+L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
+L<DH_generate_parameters(3)|DH_generate_parameters(3)>,
+L<DH_generate_key(3)|DH_generate_key(3)>
+
+=head1 HISTORY
+
+DH_new() and DH_free() are available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/DH_set_method.pod b/doc/crypto/DH_set_method.pod
new file mode 100644
index 000000000000..73261fc4675d
--- /dev/null
+++ b/doc/crypto/DH_set_method.pod
@@ -0,0 +1,129 @@
+=pod
+
+=head1 NAME
+
+DH_set_default_method, DH_get_default_method,
+DH_set_method, DH_new_method, DH_OpenSSL - select DH method
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+ #include <openssl/engine.h>
+
+ void DH_set_default_method(const DH_METHOD *meth);
+
+ const DH_METHOD *DH_get_default_method(void);
+
+ int DH_set_method(DH *dh, const DH_METHOD *meth);
+
+ DH *DH_new_method(ENGINE *engine);
+
+ const DH_METHOD *DH_OpenSSL(void);
+
+=head1 DESCRIPTION
+
+A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman
+operations. By modifying the method, alternative implementations
+such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
+important information about how these DH API functions are affected by the use
+of B<ENGINE> API calls.
+
+Initially, the default DH_METHOD is the OpenSSL internal implementation, as
+returned by DH_OpenSSL().
+
+DH_set_default_method() makes B<meth> the default method for all DH
+structures created later. B<NB>: This is true only whilst no ENGINE has been set
+as a default for DH, so this function is no longer recommended.
+
+DH_get_default_method() returns a pointer to the current default DH_METHOD.
+However, the meaningfulness of this result is dependant on whether the ENGINE
+API is being used, so this function is no longer recommended.
+
+DH_set_method() selects B<meth> to perform all operations using the key B<dh>.
+This will replace the DH_METHOD used by the DH key and if the previous method
+was supplied by an ENGINE, the handle to that ENGINE will be released during the
+change. It is possible to have DH keys that only work with certain DH_METHOD
+implementations (eg. from an ENGINE module that supports embedded
+hardware-protected keys), and in such cases attempting to change the DH_METHOD
+for the key can have unexpected results.
+
+DH_new_method() allocates and initializes a DH structure so that B<engine> will
+be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH
+operations is used, and if no default ENGINE is set, the DH_METHOD controlled by
+DH_set_default_method() is used.
+
+=head1 THE DH_METHOD STRUCTURE
+
+ typedef struct dh_meth_st
+ {
+ /* name of the implementation */
+ const char *name;
+
+ /* generate private and public DH values for key agreement */
+ int (*generate_key)(DH *dh);
+
+ /* compute shared secret */
+ int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh);
+
+ /* compute r = a ^ p mod m (May be NULL for some implementations) */
+ int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
+ const BIGNUM *m, BN_CTX *ctx,
+ BN_MONT_CTX *m_ctx);
+
+ /* called at DH_new */
+ int (*init)(DH *dh);
+
+ /* called at DH_free */
+ int (*finish)(DH *dh);
+
+ int flags;
+
+ char *app_data; /* ?? */
+
+ } DH_METHOD;
+
+=head1 RETURN VALUES
+
+DH_OpenSSL() and DH_get_default_method() return pointers to the respective
+B<DH_METHOD>s.
+
+DH_set_default_method() returns no value.
+
+DH_set_method() returns non-zero if the provided B<meth> was successfully set as
+the method for B<dh> (including unloading the ENGINE handle if the previous
+method was supplied by an ENGINE).
+
+DH_new_method() returns NULL and sets an error code that can be obtained by
+L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it
+returns a pointer to the newly allocated structure.
+
+=head1 NOTES
+
+As of version 0.9.7, DH_METHOD implementations are grouped together with other
+algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a
+default ENGINE is specified for DH functionality using an ENGINE API function,
+that will override any DH defaults set using the DH API (ie.
+DH_set_default_method()). For this reason, the ENGINE API is the recommended way
+to control default implementations for use in DH and other cryptographic
+algorithms.
+
+=head1 SEE ALSO
+
+L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)>
+
+=head1 HISTORY
+
+DH_set_default_method(), DH_get_default_method(), DH_set_method(),
+DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4.
+
+DH_set_default_openssl_method() and DH_get_default_openssl_method() replaced
+DH_set_default_method() and DH_get_default_method() respectively, and
+DH_set_method() and DH_new_method() were altered to use B<ENGINE>s rather than
+B<DH_METHOD>s during development of the engine version of OpenSSL 0.9.6. For
+0.9.7, the handling of defaults in the ENGINE API was restructured so that this
+change was reversed, and behaviour of the other functions resembled more closely
+the previous behaviour. The behaviour of defaults in the ENGINE API now
+transparently overrides the behaviour of defaults in the DH API without
+requiring changing these function prototypes.
+
+=cut
diff --git a/doc/crypto/DH_size.pod b/doc/crypto/DH_size.pod
new file mode 100644
index 000000000000..97f26fda7855
--- /dev/null
+++ b/doc/crypto/DH_size.pod
@@ -0,0 +1,33 @@
+=pod
+
+=head1 NAME
+
+DH_size - get Diffie-Hellman prime size
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ int DH_size(DH *dh);
+
+=head1 DESCRIPTION
+
+This function returns the Diffie-Hellman size in bytes. It can be used
+to determine how much memory must be allocated for the shared secret
+computed by DH_compute_key().
+
+B<dh-E<gt>p> must not be B<NULL>.
+
+=head1 RETURN VALUE
+
+The size in bytes.
+
+=head1 SEE ALSO
+
+L<dh(3)|dh(3)>, L<DH_generate_key(3)|DH_generate_key(3)>
+
+=head1 HISTORY
+
+DH_size() is available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/DSA_SIG_new.pod b/doc/crypto/DSA_SIG_new.pod
new file mode 100644
index 000000000000..3ac614003816
--- /dev/null
+++ b/doc/crypto/DSA_SIG_new.pod
@@ -0,0 +1,40 @@
+=pod
+
+=head1 NAME
+
+DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ DSA_SIG *DSA_SIG_new(void);
+
+ void DSA_SIG_free(DSA_SIG *a);
+
+=head1 DESCRIPTION
+
+DSA_SIG_new() allocates and initializes a B<DSA_SIG> structure.
+
+DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The
+values are erased before the memory is returned to the system.
+
+=head1 RETURN VALUES
+
+If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an
+error code that can be obtained by
+L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer
+to the newly allocated structure.
+
+DSA_SIG_free() returns no value.
+
+=head1 SEE ALSO
+
+L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
+L<DSA_do_sign(3)|DSA_do_sign(3)>
+
+=head1 HISTORY
+
+DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3.
+
+=cut
diff --git a/doc/crypto/DSA_do_sign.pod b/doc/crypto/DSA_do_sign.pod
new file mode 100644
index 000000000000..5dfc733b20e2
--- /dev/null
+++ b/doc/crypto/DSA_do_sign.pod
@@ -0,0 +1,47 @@
+=pod
+
+=head1 NAME
+
+DSA_do_sign, DSA_do_verify - raw DSA signature operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);
+
+ int DSA_do_verify(const unsigned char *dgst, int dgst_len,
+ DSA_SIG *sig, DSA *dsa);
+
+=head1 DESCRIPTION
+
+DSA_do_sign() computes a digital signature on the B<len> byte message
+digest B<dgst> using the private key B<dsa> and returns it in a
+newly allocated B<DSA_SIG> structure.
+
+L<DSA_sign_setup(3)|DSA_sign_setup(3)> may be used to precompute part
+of the signing operation in case signature generation is
+time-critical.
+
+DSA_do_verify() verifies that the signature B<sig> matches a given
+message digest B<dgst> of size B<len>. B<dsa> is the signer's public
+key.
+
+=head1 RETURN VALUES
+
+DSA_do_sign() returns the signature, NULL on error. DSA_do_verify()
+returns 1 for a valid signature, 0 for an incorrect signature and -1
+on error. The error codes can be obtained by
+L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
+L<DSA_SIG_new(3)|DSA_SIG_new(3)>,
+L<DSA_sign(3)|DSA_sign(3)>
+
+=head1 HISTORY
+
+DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3.
+
+=cut
diff --git a/doc/crypto/DSA_dup_DH.pod b/doc/crypto/DSA_dup_DH.pod
new file mode 100644
index 000000000000..7f6f0d1115ad
--- /dev/null
+++ b/doc/crypto/DSA_dup_DH.pod
@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+DSA_dup_DH - create a DH structure out of DSA structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ DH * DSA_dup_DH(const DSA *r);
+
+=head1 DESCRIPTION
+
+DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q
+is lost during that conversion, but the resulting DH parameters
+contain its length.
+
+=head1 RETURN VALUE
+
+DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The
+error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 NOTE
+
+Be careful to avoid small subgroup attacks when using this.
+
+=head1 SEE ALSO
+
+L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+DSA_dup_DH() was added in OpenSSL 0.9.4.
+
+=cut
diff --git a/doc/crypto/DSA_generate_key.pod b/doc/crypto/DSA_generate_key.pod
new file mode 100644
index 000000000000..af83ccfaa16b
--- /dev/null
+++ b/doc/crypto/DSA_generate_key.pod
@@ -0,0 +1,34 @@
+=pod
+
+=head1 NAME
+
+DSA_generate_key - generate DSA key pair
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ int DSA_generate_key(DSA *a);
+
+=head1 DESCRIPTION
+
+DSA_generate_key() expects B<a> to contain DSA parameters. It generates
+a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>.
+
+The PRNG must be seeded prior to calling DSA_generate_key().
+
+=head1 RETURN VALUE
+
+DSA_generate_key() returns 1 on success, 0 otherwise.
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
+L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>
+
+=head1 HISTORY
+
+DSA_generate_key() is available since SSLeay 0.8.
+
+=cut
diff --git a/doc/crypto/DSA_generate_parameters.pod b/doc/crypto/DSA_generate_parameters.pod
new file mode 100644
index 000000000000..be7c924ff8f9
--- /dev/null
+++ b/doc/crypto/DSA_generate_parameters.pod
@@ -0,0 +1,105 @@
+=pod
+
+=head1 NAME
+
+DSA_generate_parameters - generate DSA parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ DSA *DSA_generate_parameters(int bits, unsigned char *seed,
+ int seed_len, int *counter_ret, unsigned long *h_ret,
+ void (*callback)(int, int, void *), void *cb_arg);
+
+=head1 DESCRIPTION
+
+DSA_generate_parameters() generates primes p and q and a generator g
+for use in the DSA.
+
+B<bits> is the length of the prime to be generated; the DSS allows a
+maximum of 1024 bits.
+
+If B<seed> is B<NULL> or B<seed_len> E<lt> 20, the primes will be
+generated at random. Otherwise, the seed is used to generate
+them. If the given seed does not yield a prime q, a new random
+seed is chosen and placed at B<seed>.
+
+DSA_generate_parameters() places the iteration count in
+*B<counter_ret> and a counter used for finding a generator in
+*B<h_ret>, unless these are B<NULL>.
+
+A callback function may be used to provide feedback about the progress
+of the key generation. If B<callback> is not B<NULL>, it will be
+called as follows:
+
+=over 4
+
+=item *
+
+When a candidate for q is generated, B<callback(0, m++, cb_arg)> is called
+(m is 0 for the first candidate).
+
+=item *
+
+When a candidate for q has passed a test by trial division,
+B<callback(1, -1, cb_arg)> is called.
+While a candidate for q is tested by Miller-Rabin primality tests,
+B<callback(1, i, cb_arg)> is called in the outer loop
+(once for each witness that confirms that the candidate may be prime);
+i is the loop counter (starting at 0).
+
+=item *
+
+When a prime q has been found, B<callback(2, 0, cb_arg)> and
+B<callback(3, 0, cb_arg)> are called.
+
+=item *
+
+Before a candidate for p (other than the first) is generated and tested,
+B<callback(0, counter, cb_arg)> is called.
+
+=item *
+
+When a candidate for p has passed the test by trial division,
+B<callback(1, -1, cb_arg)> is called.
+While it is tested by the Miller-Rabin primality test,
+B<callback(1, i, cb_arg)> is called in the outer loop
+(once for each witness that confirms that the candidate may be prime).
+i is the loop counter (starting at 0).
+
+=item *
+
+When p has been found, B<callback(2, 1, cb_arg)> is called.
+
+=item *
+
+When the generator has been found, B<callback(3, 1, cb_arg)> is called.
+
+=back
+
+=head1 RETURN VALUE
+
+DSA_generate_parameters() returns a pointer to the DSA structure, or
+B<NULL> if the parameter generation fails. The error codes can be
+obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 BUGS
+
+Seed lengths E<gt> 20 are not supported.
+
+=head1 SEE ALSO
+
+L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
+L<DSA_free(3)|DSA_free(3)>
+
+=head1 HISTORY
+
+DSA_generate_parameters() appeared in SSLeay 0.8. The B<cb_arg>
+argument was added in SSLeay 0.9.0.
+In versions up to OpenSSL 0.9.4, B<callback(1, ...)> was called
+in the inner loop of the Miller-Rabin test whenever it reached the
+squaring step (the parameters to B<callback> did not reveal how many
+witnesses had been tested); since OpenSSL 0.9.5, B<callback(1, ...)>
+is called as in BN_is_prime(3), i.e. once for each witness.
+=cut
diff --git a/doc/crypto/DSA_get_ex_new_index.pod b/doc/crypto/DSA_get_ex_new_index.pod
new file mode 100644
index 000000000000..4612e708ecc0
--- /dev/null
+++ b/doc/crypto/DSA_get_ex_new_index.pod
@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specific data to DSA structures
+
+=head1 SYNOPSIS
+
+ #include <openssl/DSA.h>
+
+ int DSA_get_ex_new_index(long argl, void *argp,
+ CRYPTO_EX_new *new_func,
+ CRYPTO_EX_dup *dup_func,
+ CRYPTO_EX_free *free_func);
+
+ int DSA_set_ex_data(DSA *d, int idx, void *arg);
+
+ char *DSA_get_ex_data(DSA *d, int idx);
+
+=head1 DESCRIPTION
+
+These functions handle application specific data in DSA
+structures. Their usage is identical to that of
+RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data()
+as described in L<RSA_get_ex_new_index(3)>.
+
+=head1 SEE ALSO
+
+L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dsa(3)|dsa(3)>
+
+=head1 HISTORY
+
+DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are
+available since OpenSSL 0.9.5.
+
+=cut
diff --git a/doc/crypto/DSA_new.pod b/doc/crypto/DSA_new.pod
new file mode 100644
index 000000000000..48e9b82a09c8
--- /dev/null
+++ b/doc/crypto/DSA_new.pod
@@ -0,0 +1,42 @@
+=pod
+
+=head1 NAME
+
+DSA_new, DSA_free - allocate and free DSA objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ DSA* DSA_new(void);
+
+ void DSA_free(DSA *dsa);
+
+=head1 DESCRIPTION
+
+DSA_new() allocates and initializes a B<DSA> structure. It is equivalent to
+calling DSA_new_method(NULL).
+
+DSA_free() frees the B<DSA> structure and its components. The values are
+erased before the memory is returned to the system.
+
+=head1 RETURN VALUES
+
+If the allocation fails, DSA_new() returns B<NULL> and sets an error
+code that can be obtained by
+L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer
+to the newly allocated structure.
+
+DSA_free() returns no value.
+
+=head1 SEE ALSO
+
+L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
+L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>,
+L<DSA_generate_key(3)|DSA_generate_key(3)>
+
+=head1 HISTORY
+
+DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/DSA_set_method.pod b/doc/crypto/DSA_set_method.pod
new file mode 100644
index 000000000000..bc3cfb1f0a78
--- /dev/null
+++ b/doc/crypto/DSA_set_method.pod
@@ -0,0 +1,143 @@
+=pod
+
+=head1 NAME
+
+DSA_set_default_method, DSA_get_default_method,
+DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+ #include <openssl/engine.h>
+
+ void DSA_set_default_method(const DSA_METHOD *meth);
+
+ const DSA_METHOD *DSA_get_default_method(void);
+
+ int DSA_set_method(DSA *dsa, const DSA_METHOD *meth);
+
+ DSA *DSA_new_method(ENGINE *engine);
+
+ DSA_METHOD *DSA_OpenSSL(void);
+
+=head1 DESCRIPTION
+
+A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA
+operations. By modifying the method, alternative implementations
+such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
+important information about how these DSA API functions are affected by the use
+of B<ENGINE> API calls.
+
+Initially, the default DSA_METHOD is the OpenSSL internal implementation,
+as returned by DSA_OpenSSL().
+
+DSA_set_default_method() makes B<meth> the default method for all DSA
+structures created later. B<NB>: This is true only whilst no ENGINE has
+been set as a default for DSA, so this function is no longer recommended.
+
+DSA_get_default_method() returns a pointer to the current default
+DSA_METHOD. However, the meaningfulness of this result is dependant on
+whether the ENGINE API is being used, so this function is no longer
+recommended.
+
+DSA_set_method() selects B<meth> to perform all operations using the key
+B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the
+previous method was supplied by an ENGINE, the handle to that ENGINE will
+be released during the change. It is possible to have DSA keys that only
+work with certain DSA_METHOD implementations (eg. from an ENGINE module
+that supports embedded hardware-protected keys), and in such cases
+attempting to change the DSA_METHOD for the key can have unexpected
+results.
+
+DSA_new_method() allocates and initializes a DSA structure so that B<engine>
+will be used for the DSA operations. If B<engine> is NULL, the default engine
+for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD
+controlled by DSA_set_default_method() is used.
+
+=head1 THE DSA_METHOD STRUCTURE
+
+struct
+ {
+ /* name of the implementation */
+ const char *name;
+
+ /* sign */
+ DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
+ DSA *dsa);
+
+ /* pre-compute k^-1 and r */
+ int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
+ BIGNUM **rp);
+
+ /* verify */
+ int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
+ DSA_SIG *sig, DSA *dsa);
+
+ /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some
+ implementations) */
+ int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
+ BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
+ BN_CTX *ctx, BN_MONT_CTX *in_mont);
+
+ /* compute r = a ^ p mod m (May be NULL for some implementations) */
+ int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a,
+ const BIGNUM *p, const BIGNUM *m,
+ BN_CTX *ctx, BN_MONT_CTX *m_ctx);
+
+ /* called at DSA_new */
+ int (*init)(DSA *DSA);
+
+ /* called at DSA_free */
+ int (*finish)(DSA *DSA);
+
+ int flags;
+
+ char *app_data; /* ?? */
+
+ } DSA_METHOD;
+
+=head1 RETURN VALUES
+
+DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective
+B<DSA_METHOD>s.
+
+DSA_set_default_method() returns no value.
+
+DSA_set_method() returns non-zero if the provided B<meth> was successfully set as
+the method for B<dsa> (including unloading the ENGINE handle if the previous
+method was supplied by an ENGINE).
+
+DSA_new_method() returns NULL and sets an error code that can be
+obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation
+fails. Otherwise it returns a pointer to the newly allocated structure.
+
+=head1 NOTES
+
+As of version 0.9.7, DSA_METHOD implementations are grouped together with other
+algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a
+default ENGINE is specified for DSA functionality using an ENGINE API function,
+that will override any DSA defaults set using the DSA API (ie.
+DSA_set_default_method()). For this reason, the ENGINE API is the recommended way
+to control default implementations for use in DSA and other cryptographic
+algorithms.
+
+=head1 SEE ALSO
+
+L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)>
+
+=head1 HISTORY
+
+DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(),
+DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4.
+
+DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced
+DSA_set_default_method() and DSA_get_default_method() respectively, and
+DSA_set_method() and DSA_new_method() were altered to use B<ENGINE>s rather than
+B<DSA_METHOD>s during development of the engine version of OpenSSL 0.9.6. For
+0.9.7, the handling of defaults in the ENGINE API was restructured so that this
+change was reversed, and behaviour of the other functions resembled more closely
+the previous behaviour. The behaviour of defaults in the ENGINE API now
+transparently overrides the behaviour of defaults in the DSA API without
+requiring changing these function prototypes.
+
+=cut
diff --git a/doc/crypto/DSA_sign.pod b/doc/crypto/DSA_sign.pod
new file mode 100644
index 000000000000..97389e8ec885
--- /dev/null
+++ b/doc/crypto/DSA_sign.pod
@@ -0,0 +1,66 @@
+=pod
+
+=head1 NAME
+
+DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ int DSA_sign(int type, const unsigned char *dgst, int len,
+ unsigned char *sigret, unsigned int *siglen, DSA *dsa);
+
+ int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp,
+ BIGNUM **rp);
+
+ int DSA_verify(int type, const unsigned char *dgst, int len,
+ unsigned char *sigbuf, int siglen, DSA *dsa);
+
+=head1 DESCRIPTION
+
+DSA_sign() computes a digital signature on the B<len> byte message
+digest B<dgst> using the private key B<dsa> and places its ASN.1 DER
+encoding at B<sigret>. The length of the signature is places in
+*B<siglen>. B<sigret> must point to DSA_size(B<dsa>) bytes of memory.
+
+DSA_sign_setup() may be used to precompute part of the signing
+operation in case signature generation is time-critical. It expects
+B<dsa> to contain DSA parameters. It places the precomputed values
+in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing
+the old ones unless *B<kinvp> and *B<rp> are NULL. These values may
+be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>.
+B<ctx> is a pre-allocated B<BN_CTX> or NULL.
+
+DSA_verify() verifies that the signature B<sigbuf> of size B<siglen>
+matches a given message digest B<dgst> of size B<len>.
+B<dsa> is the signer's public key.
+
+The B<type> parameter is ignored.
+
+The PRNG must be seeded before DSA_sign() (or DSA_sign_setup())
+is called.
+
+=head1 RETURN VALUES
+
+DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error.
+DSA_verify() returns 1 for a valid signature, 0 for an incorrect
+signature and -1 on error. The error codes can be obtained by
+L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 CONFORMING TO
+
+US Federal Information Processing Standard FIPS 186 (Digital Signature
+Standard, DSS), ANSI X9.30
+
+=head1 SEE ALSO
+
+L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
+L<DSA_do_sign(3)|DSA_do_sign(3)>
+
+=head1 HISTORY
+
+DSA_sign() and DSA_verify() are available in all versions of SSLeay.
+DSA_sign_setup() was added in SSLeay 0.8.
+
+=cut
diff --git a/doc/crypto/DSA_size.pod b/doc/crypto/DSA_size.pod
new file mode 100644
index 000000000000..ba4f650361c3
--- /dev/null
+++ b/doc/crypto/DSA_size.pod
@@ -0,0 +1,33 @@
+=pod
+
+=head1 NAME
+
+DSA_size - get DSA signature size
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ int DSA_size(const DSA *dsa);
+
+=head1 DESCRIPTION
+
+This function returns the size of an ASN.1 encoded DSA signature in
+bytes. It can be used to determine how much memory must be allocated
+for a DSA signature.
+
+B<dsa-E<gt>q> must not be B<NULL>.
+
+=head1 RETURN VALUE
+
+The size in bytes.
+
+=head1 SEE ALSO
+
+L<dsa(3)|dsa(3)>, L<DSA_sign(3)|DSA_sign(3)>
+
+=head1 HISTORY
+
+DSA_size() is available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/ERR_GET_LIB.pod b/doc/crypto/ERR_GET_LIB.pod
new file mode 100644
index 000000000000..2a129da036cc
--- /dev/null
+++ b/doc/crypto/ERR_GET_LIB.pod
@@ -0,0 +1,51 @@
+=pod
+
+=head1 NAME
+
+ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and
+reason code
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ int ERR_GET_LIB(unsigned long e);
+
+ int ERR_GET_FUNC(unsigned long e);
+
+ int ERR_GET_REASON(unsigned long e);
+
+=head1 DESCRIPTION
+
+The error code returned by ERR_get_error() consists of a library
+number, function code and reason code. ERR_GET_LIB(), ERR_GET_FUNC()
+and ERR_GET_REASON() can be used to extract these.
+
+The library number and function code describe where the error
+occurred, the reason code is the information about what went wrong.
+
+Each sub-library of OpenSSL has a unique library number; function and
+reason codes are unique within each sub-library. Note that different
+libraries may use the same value to signal different functions and
+reasons.
+
+B<ERR_R_...> reason codes such as B<ERR_R_MALLOC_FAILURE> are globally
+unique. However, when checking for sub-library specific reason codes,
+be sure to also compare the library number.
+
+ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are macros.
+
+=head1 RETURN VALUES
+
+The library number, function code and reason code respectively.
+
+=head1 SEE ALSO
+
+L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in
+all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/ERR_clear_error.pod b/doc/crypto/ERR_clear_error.pod
new file mode 100644
index 000000000000..566e1f4e317f
--- /dev/null
+++ b/doc/crypto/ERR_clear_error.pod
@@ -0,0 +1,29 @@
+=pod
+
+=head1 NAME
+
+ERR_clear_error - clear the error queue
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ void ERR_clear_error(void);
+
+=head1 DESCRIPTION
+
+ERR_clear_error() empties the current thread's error queue.
+
+=head1 RETURN VALUES
+
+ERR_clear_error() has no return value.
+
+=head1 SEE ALSO
+
+L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+ERR_clear_error() is available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/ERR_error_string.pod b/doc/crypto/ERR_error_string.pod
new file mode 100644
index 000000000000..cdfa7fe1fe72
--- /dev/null
+++ b/doc/crypto/ERR_error_string.pod
@@ -0,0 +1,73 @@
+=pod
+
+=head1 NAME
+
+ERR_error_string, ERR_error_string_n, ERR_lib_error_string,
+ERR_func_error_string, ERR_reason_error_string - obtain human-readable
+error message
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ char *ERR_error_string(unsigned long e, char *buf);
+ void ERR_error_string_n(unsigned long e, char *buf, size_t len);
+
+ const char *ERR_lib_error_string(unsigned long e);
+ const char *ERR_func_error_string(unsigned long e);
+ const char *ERR_reason_error_string(unsigned long e);
+
+=head1 DESCRIPTION
+
+ERR_error_string() generates a human-readable string representing the
+error code I<e>, and places it at I<buf>. I<buf> must be at least 120
+bytes long. If I<buf> is B<NULL>, the error string is placed in a
+static buffer.
+ERR_error_string_n() is a variant of ERR_error_string() that writes
+at most I<len> characters (including the terminating 0)
+and truncates the string if necessary.
+For ERR_error_string_n(), I<buf> may not be B<NULL>.
+
+The string will have the following format:
+
+ error:[error code]:[library name]:[function name]:[reason string]
+
+I<error code> is an 8 digit hexadecimal number, I<library name>,
+I<function name> and I<reason string> are ASCII text.
+
+ERR_lib_error_string(), ERR_func_error_string() and
+ERR_reason_error_string() return the library name, function
+name and reason string respectively.
+
+The OpenSSL error strings should be loaded by calling
+L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)> or, for SSL
+applications, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
+first.
+If there is no text string registered for the given error code,
+the error string will contain the numeric code.
+
+L<ERR_print_errors(3)|ERR_print_errors(3)> can be used to print
+all error codes currently in the queue.
+
+=head1 RETURN VALUES
+
+ERR_error_string() returns a pointer to a static buffer containing the
+string if I<buf> B<== NULL>, I<buf> otherwise.
+
+ERR_lib_error_string(), ERR_func_error_string() and
+ERR_reason_error_string() return the strings, and B<NULL> if
+none is registered for the error code.
+
+=head1 SEE ALSO
+
+L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
+L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
+L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
+L<ERR_print_errors(3)|ERR_print_errors(3)>
+
+=head1 HISTORY
+
+ERR_error_string() is available in all versions of SSLeay and OpenSSL.
+ERR_error_string_n() was added in OpenSSL 0.9.6.
+
+=cut
diff --git a/doc/crypto/ERR_get_error.pod b/doc/crypto/ERR_get_error.pod
new file mode 100644
index 000000000000..34443045fc0d
--- /dev/null
+++ b/doc/crypto/ERR_get_error.pod
@@ -0,0 +1,76 @@
+=pod
+
+=head1 NAME
+
+ERR_get_error, ERR_peek_error, ERR_peek_last_error,
+ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line,
+ERR_get_error_line_data, ERR_peek_error_line_data,
+ERR_peek_last_error_line_data - obtain error code and data
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ unsigned long ERR_get_error(void);
+ unsigned long ERR_peek_error(void);
+ unsigned long ERR_peek_last_error(void);
+
+ unsigned long ERR_get_error_line(const char **file, int *line);
+ unsigned long ERR_peek_error_line(const char **file, int *line);
+ unsigned long ERR_peek_last_error_line(const char **file, int *line);
+
+ unsigned long ERR_get_error_line_data(const char **file, int *line,
+ const char **data, int *flags);
+ unsigned long ERR_peek_error_line_data(const char **file, int *line,
+ const char **data, int *flags);
+ unsigned long ERR_peek_last_error_line_data(const char **file, int *line,
+ const char **data, int *flags);
+
+=head1 DESCRIPTION
+
+ERR_get_error() returns the earliest error code from the thread's error
+queue and removes the entry. This function can be called repeatedly
+until there are no more error codes to return.
+
+ERR_peek_error() returns the earliest error code from the thread's
+error queue without modifying it.
+
+ERR_peek_last_error() returns the latest error code from the thread's
+error queue without modifying it.
+
+See L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> for obtaining information about
+location and reason of the error, and
+L<ERR_error_string(3)|ERR_error_string(3)> for human-readable error
+messages.
+
+ERR_get_error_line(), ERR_peek_error_line() and
+ERR_peek_last_error_line() are the same as the above, but they
+additionally store the file name and line number where
+the error occurred in *B<file> and *B<line>, unless these are B<NULL>.
+
+ERR_get_error_line_data(), ERR_peek_error_line_data() and
+ERR_get_last_error_line_data() store additional data and flags
+associated with the error code in *B<data>
+and *B<flags>, unless these are B<NULL>. *B<data> contains a string
+if *B<flags>&B<ERR_TXT_STRING>. If it has been allocated by OPENSSL_malloc(),
+*B<flags>&B<ERR_TXT_MALLOCED> is true.
+
+=head1 RETURN VALUES
+
+The error code, or 0 if there is no error in the queue.
+
+=head1 SEE ALSO
+
+L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>,
+L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>
+
+=head1 HISTORY
+
+ERR_get_error(), ERR_peek_error(), ERR_get_error_line() and
+ERR_peek_error_line() are available in all versions of SSLeay and
+OpenSSL. ERR_get_error_line_data() and ERR_peek_error_line_data()
+were added in SSLeay 0.9.0.
+ERR_peek_last_error(), ERR_peek_last_error_line() and
+ERR_peek_last_error_line_data() were added in OpenSSL 0.9.7.
+
+=cut
diff --git a/doc/crypto/ERR_load_crypto_strings.pod b/doc/crypto/ERR_load_crypto_strings.pod
new file mode 100644
index 000000000000..9bdec75a4638
--- /dev/null
+++ b/doc/crypto/ERR_load_crypto_strings.pod
@@ -0,0 +1,46 @@
+=pod
+
+=head1 NAME
+
+ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings -
+load and free error strings
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ void ERR_load_crypto_strings(void);
+ void ERR_free_strings(void);
+
+ #include <openssl/ssl.h>
+
+ void SSL_load_error_strings(void);
+
+=head1 DESCRIPTION
+
+ERR_load_crypto_strings() registers the error strings for all
+B<libcrypto> functions. SSL_load_error_strings() does the same,
+but also registers the B<libssl> error strings.
+
+One of these functions should be called before generating
+textual error messages. However, this is not required when memory
+usage is an issue.
+
+ERR_free_strings() frees all previously loaded error strings.
+
+=head1 RETURN VALUES
+
+ERR_load_crypto_strings(), SSL_load_error_strings() and
+ERR_free_strings() return no values.
+
+=head1 SEE ALSO
+
+L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>
+
+=head1 HISTORY
+
+ERR_load_error_strings(), SSL_load_error_strings() and
+ERR_free_strings() are available in all versions of SSLeay and
+OpenSSL.
+
+=cut
diff --git a/doc/crypto/ERR_load_strings.pod b/doc/crypto/ERR_load_strings.pod
new file mode 100644
index 000000000000..5acdd0edbc5e
--- /dev/null
+++ b/doc/crypto/ERR_load_strings.pod
@@ -0,0 +1,54 @@
+=pod
+
+=head1 NAME
+
+ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load
+arbitrary error strings
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ void ERR_load_strings(int lib, ERR_STRING_DATA str[]);
+
+ int ERR_get_next_error_library(void);
+
+ unsigned long ERR_PACK(int lib, int func, int reason);
+
+=head1 DESCRIPTION
+
+ERR_load_strings() registers error strings for library number B<lib>.
+
+B<str> is an array of error string data:
+
+ typedef struct ERR_string_data_st
+ {
+ unsigned long error;
+ char *string;
+ } ERR_STRING_DATA;
+
+The error code is generated from the library number and a function and
+reason code: B<error> = ERR_PACK(B<lib>, B<func>, B<reason>).
+ERR_PACK() is a macro.
+
+The last entry in the array is {0,0}.
+
+ERR_get_next_error_library() can be used to assign library numbers
+to user libraries at runtime.
+
+=head1 RETURN VALUE
+
+ERR_load_strings() returns no value. ERR_PACK() return the error code.
+ERR_get_next_error_library() returns a new library number.
+
+=head1 SEE ALSO
+
+L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)>
+
+=head1 HISTORY
+
+ERR_load_error_strings() and ERR_PACK() are available in all versions
+of SSLeay and OpenSSL. ERR_get_next_error_library() was added in
+SSLeay 0.9.0.
+
+=cut
diff --git a/doc/crypto/ERR_print_errors.pod b/doc/crypto/ERR_print_errors.pod
new file mode 100644
index 000000000000..b100a5fa2b30
--- /dev/null
+++ b/doc/crypto/ERR_print_errors.pod
@@ -0,0 +1,51 @@
+=pod
+
+=head1 NAME
+
+ERR_print_errors, ERR_print_errors_fp - print error messages
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ void ERR_print_errors(BIO *bp);
+ void ERR_print_errors_fp(FILE *fp);
+
+=head1 DESCRIPTION
+
+ERR_print_errors() is a convenience function that prints the error
+strings for all errors that OpenSSL has recorded to B<bp>, thus
+emptying the error queue.
+
+ERR_print_errors_fp() is the same, except that the output goes to a
+B<FILE>.
+
+
+The error strings will have the following format:
+
+ [pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message]
+
+I<error code> is an 8 digit hexadecimal number. I<library name>,
+I<function name> and I<reason string> are ASCII text, as is I<optional
+text message> if one was set for the respective error code.
+
+If there is no text string registered for the given error code,
+the error string will contain the numeric code.
+
+=head1 RETURN VALUES
+
+ERR_print_errors() and ERR_print_errors_fp() return no values.
+
+=head1 SEE ALSO
+
+L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>,
+L<ERR_get_error(3)|ERR_get_error(3)>,
+L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
+L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
+
+=head1 HISTORY
+
+ERR_print_errors() and ERR_print_errors_fp()
+are available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/ERR_put_error.pod b/doc/crypto/ERR_put_error.pod
new file mode 100644
index 000000000000..acd241fbe476
--- /dev/null
+++ b/doc/crypto/ERR_put_error.pod
@@ -0,0 +1,44 @@
+=pod
+
+=head1 NAME
+
+ERR_put_error, ERR_add_error_data - record an error
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ void ERR_put_error(int lib, int func, int reason, const char *file,
+ int line);
+
+ void ERR_add_error_data(int num, ...);
+
+=head1 DESCRIPTION
+
+ERR_put_error() adds an error code to the thread's error queue. It
+signals that the error of reason code B<reason> occurred in function
+B<func> of library B<lib>, in line number B<line> of B<file>.
+This function is usually called by a macro.
+
+ERR_add_error_data() associates the concatenation of its B<num> string
+arguments with the error code added last.
+
+L<ERR_load_strings(3)|ERR_load_strings(3)> can be used to register
+error strings so that the application can a generate human-readable
+error messages for the error code.
+
+=head1 RETURN VALUES
+
+ERR_put_error() and ERR_add_error_data() return
+no values.
+
+=head1 SEE ALSO
+
+L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)>
+
+=head1 HISTORY
+
+ERR_put_error() is available in all versions of SSLeay and OpenSSL.
+ERR_add_error_data() was added in SSLeay 0.9.0.
+
+=cut
diff --git a/doc/crypto/ERR_remove_state.pod b/doc/crypto/ERR_remove_state.pod
new file mode 100644
index 000000000000..72925fb9f474
--- /dev/null
+++ b/doc/crypto/ERR_remove_state.pod
@@ -0,0 +1,34 @@
+=pod
+
+=head1 NAME
+
+ERR_remove_state - free a thread's error queue
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ void ERR_remove_state(unsigned long pid);
+
+=head1 DESCRIPTION
+
+ERR_remove_state() frees the error queue associated with thread B<pid>.
+If B<pid> == 0, the current thread will have its error queue removed.
+
+Since error queue data structures are allocated automatically for new
+threads, they must be freed when threads are terminated in order to
+avoid memory leaks.
+
+=head1 RETURN VALUE
+
+ERR_remove_state() returns no value.
+
+=head1 SEE ALSO
+
+L<err(3)|err(3)>
+
+=head1 HISTORY
+
+ERR_remove_state() is available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/ERR_set_mark.pod b/doc/crypto/ERR_set_mark.pod
new file mode 100644
index 000000000000..d3ca4f2e770b
--- /dev/null
+++ b/doc/crypto/ERR_set_mark.pod
@@ -0,0 +1,38 @@
+=pod
+
+=head1 NAME
+
+ERR_set_mark, ERR_pop_to_mark - set marks and pop errors until mark
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ int ERR_set_mark(void);
+
+ int ERR_pop_to_mark(void);
+
+=head1 DESCRIPTION
+
+ERR_set_mark() sets a mark on the current topmost error record if there
+is one.
+
+ERR_pop_to_mark() will pop the top of the error stack until a mark is found.
+The mark is then removed. If there is no mark, the whole stack is removed.
+
+=head1 RETURN VALUES
+
+ERR_set_mark() returns 0 if the error stack is empty, otherwise 1.
+
+ERR_pop_to_mark() returns 0 if there was no mark in the error stack, which
+implies that the stack became empty, otherwise 1.
+
+=head1 SEE ALSO
+
+L<err(3)|err(3)>
+
+=head1 HISTORY
+
+ERR_set_mark() and ERR_pop_to_mark() were added in OpenSSL 0.9.8.
+
+=cut
diff --git a/doc/crypto/EVP_BytesToKey.pod b/doc/crypto/EVP_BytesToKey.pod
new file mode 100644
index 000000000000..d375c46e03d5
--- /dev/null
+++ b/doc/crypto/EVP_BytesToKey.pod
@@ -0,0 +1,67 @@
+=pod
+
+=head1 NAME
+
+EVP_BytesToKey - password based encryption routine
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_BytesToKey(const EVP_CIPHER *type,const EVP_MD *md,
+ const unsigned char *salt,
+ const unsigned char *data, int datal, int count,
+ unsigned char *key,unsigned char *iv);
+
+=head1 DESCRIPTION
+
+EVP_BytesToKey() derives a key and IV from various parameters. B<type> is
+the cipher to derive the key and IV for. B<md> is the message digest to use.
+The B<salt> paramter is used as a salt in the derivation: it should point to
+an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing
+B<datal> bytes which is used to derive the keying data. B<count> is the
+iteration count to use. The derived key and IV will be written to B<key>
+and B<iv> respectively.
+
+=head1 NOTES
+
+A typical application of this function is to derive keying material for an
+encryption algorithm from a password in the B<data> parameter.
+
+Increasing the B<count> parameter slows down the algorithm which makes it
+harder for an attacker to peform a brute force attack using a large number
+of candidate passwords.
+
+If the total key and IV length is less than the digest length and
+B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5
+otherwise a non standard extension is used to derive the extra data.
+
+Newer applications should use more standard algorithms such as PKCS#5
+v2.0 for key derivation.
+
+=head1 KEY DERIVATION ALGORITHM
+
+The key and IV is derived by concatenating D_1, D_2, etc until
+enough data is available for the key and IV. D_i is defined as:
+
+ D_i = HASH^count(D_(i-1) || data || salt)
+
+where || denotes concatentaion, D_0 is empty, HASH is the digest
+algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data)
+is HASH(HASH(data)) and so on.
+
+The initial bytes are used for the key and the subsequent bytes for
+the IV.
+
+=head1 RETURN VALUES
+
+EVP_BytesToKey() returns the size of the derived key in bytes.
+
+=head1 SEE ALSO
+
+L<evp(3)|evp(3)>, L<rand(3)|rand(3)>,
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>
+
+=head1 HISTORY
+
+=cut
diff --git a/doc/crypto/EVP_DigestInit.pod b/doc/crypto/EVP_DigestInit.pod
new file mode 100644
index 000000000000..130cd7f60adb
--- /dev/null
+++ b/doc/crypto/EVP_DigestInit.pod
@@ -0,0 +1,256 @@
+=pod
+
+=head1 NAME
+
+EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate,
+EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE,
+EVP_MD_CTX_copy_ex, EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size,
+EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type,
+EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, EVP_dss, EVP_dss1, EVP_mdc2,
+EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj -
+EVP digest routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ void EVP_MD_CTX_init(EVP_MD_CTX *ctx);
+ EVP_MD_CTX *EVP_MD_CTX_create(void);
+
+ int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
+ int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
+ int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md,
+ unsigned int *s);
+
+ int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx);
+ void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx);
+
+ int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);
+
+ int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
+ int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
+ unsigned int *s);
+
+ int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);
+
+ #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */
+
+
+ #define EVP_MD_type(e) ((e)->type)
+ #define EVP_MD_pkey_type(e) ((e)->pkey_type)
+ #define EVP_MD_size(e) ((e)->md_size)
+ #define EVP_MD_block_size(e) ((e)->block_size)
+
+ #define EVP_MD_CTX_md(e) (e)->digest)
+ #define EVP_MD_CTX_size(e) EVP_MD_size((e)->digest)
+ #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest)
+ #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest)
+
+ const EVP_MD *EVP_md_null(void);
+ const EVP_MD *EVP_md2(void);
+ const EVP_MD *EVP_md5(void);
+ const EVP_MD *EVP_sha(void);
+ const EVP_MD *EVP_sha1(void);
+ const EVP_MD *EVP_dss(void);
+ const EVP_MD *EVP_dss1(void);
+ const EVP_MD *EVP_mdc2(void);
+ const EVP_MD *EVP_ripemd160(void);
+
+ const EVP_MD *EVP_get_digestbyname(const char *name);
+ #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a))
+ #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a))
+
+=head1 DESCRIPTION
+
+The EVP digest routines are a high level interface to message digests.
+
+EVP_MD_CTX_init() initializes digest contet B<ctx>.
+
+EVP_MD_CTX_create() allocates, initializes and returns a digest contet.
+
+EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest
+B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this
+function. B<type> will typically be supplied by a functionsuch as EVP_sha1().
+If B<impl> is NULL then the default implementation of digest B<type> is used.
+
+EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the
+digest context B<ctx>. This function can be called several times on the
+same B<ctx> to hash additional data.
+
+EVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places
+it in B<md>. If the B<s> parameter is not NULL then the number of
+bytes of data written (i.e. the length of the digest) will be written
+to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written.
+After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate()
+can be made, but EVP_DigestInit_ex() can be called to initialize a new
+digest operation.
+
+EVP_MD_CTX_cleanup() cleans up digest context B<ctx>, it should be called
+after a digest context is no longer needed.
+
+EVP_MD_CTX_destroy() cleans up digest context B<ctx> and frees up the
+space allocated to it, it should be called only on a context created
+using EVP_MD_CTX_create().
+
+EVP_MD_CTX_copy_ex() can be used to copy the message digest state from
+B<in> to B<out>. This is useful if large amounts of data are to be
+hashed which only differ in the last few bytes. B<out> must be initialized
+before calling this function.
+
+EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except
+the passed context B<ctx> does not have to be initialized, and it always
+uses the default digest implementation.
+
+EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest
+contet B<ctx> is automatically cleaned up.
+
+EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination
+B<out> does not have to be initialized.
+
+EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest
+when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the
+hash.
+
+EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the
+message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure.
+
+EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER
+representing the given message digest when passed an B<EVP_MD> structure.
+For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is
+normally used when setting ASN1 OIDs.
+
+EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed
+B<EVP_MD_CTX>.
+
+EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated
+with this digest. For example EVP_sha1() is associated with RSA so this will
+return B<NID_sha1WithRSAEncryption>. This "link" between digests and signature
+algorithms may not be retained in future versions of OpenSSL.
+
+EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_mdc2() and EVP_ripemd160()
+return B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 digest
+algorithms respectively. The associated signature algorithm is RSA in each case.
+
+EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest
+algorithms but using DSS (DSA) for the signature algorithm.
+
+EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it
+returns is of zero length.
+
+EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
+return an B<EVP_MD> structure when passed a digest name, a digest NID or
+an ASN1_OBJECT structure respectively. The digest table must be initialized
+using, for example, OpenSSL_add_all_digests() for these functions to work.
+
+=head1 RETURN VALUES
+
+EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for
+success and 0 for failure.
+
+EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure.
+
+EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the
+corresponding OBJECT IDENTIFIER or NID_undef if none exists.
+
+EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(),
+EVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block
+size in bytes.
+
+EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(),
+EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the
+corresponding EVP_MD structures.
+
+EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
+return either an B<EVP_MD> structure or NULL if an error occurs.
+
+=head1 NOTES
+
+The B<EVP> interface to message digests should almost always be used in
+preference to the low level interfaces. This is because the code then becomes
+transparent to the digest used and much more flexible.
+
+SHA1 is the digest of choice for new applications. The other digest algorithms
+are still in common use.
+
+For most applications the B<impl> parameter to EVP_DigestInit_ex() will be
+set to NULL to use the default digest implementation.
+
+The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
+obsolete but are retained to maintain compatibility with existing code. New
+applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and
+EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context
+instead of initializing and cleaning it up on each call and allow non default
+implementations of digests to be specified.
+
+In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use
+memory leaks will occur.
+
+=head1 EXAMPLE
+
+This example digests the data "Test Message\n" and "Hello World\n", using the
+digest name passed on the command line.
+
+ #include <stdio.h>
+ #include <openssl/evp.h>
+
+ main(int argc, char *argv[])
+ {
+ EVP_MD_CTX mdctx;
+ const EVP_MD *md;
+ char mess1[] = "Test Message\n";
+ char mess2[] = "Hello World\n";
+ unsigned char md_value[EVP_MAX_MD_SIZE];
+ int md_len, i;
+
+ OpenSSL_add_all_digests();
+
+ if(!argv[1]) {
<