aboutsummaryrefslogtreecommitdiff
path: root/openssl/doc
diff options
context:
space:
mode:
Diffstat (limited to 'openssl/doc')
-rw-r--r--openssl/doc/HOWTO/certificates.txt105
-rw-r--r--openssl/doc/HOWTO/keys.txt73
-rw-r--r--openssl/doc/HOWTO/proxy_certificates.txt322
-rw-r--r--openssl/doc/README12
-rw-r--r--openssl/doc/apps/CA.pl.pod179
-rw-r--r--openssl/doc/apps/asn1parse.pod171
-rw-r--r--openssl/doc/apps/ca.pod671
-rw-r--r--openssl/doc/apps/ciphers.pod434
-rw-r--r--openssl/doc/apps/config.pod279
-rw-r--r--openssl/doc/apps/crl.pod117
-rw-r--r--openssl/doc/apps/crl2pkcs7.pod91
-rw-r--r--openssl/doc/apps/dgst.pod115
-rw-r--r--openssl/doc/apps/dhparam.pod141
-rw-r--r--openssl/doc/apps/dsa.pod158
-rw-r--r--openssl/doc/apps/dsaparam.pod110
-rw-r--r--openssl/doc/apps/ec.pod190
-rw-r--r--openssl/doc/apps/ecparam.pod179
-rw-r--r--openssl/doc/apps/enc.pod279
-rw-r--r--openssl/doc/apps/errstr.pod39
-rw-r--r--openssl/doc/apps/gendsa.pod66
-rw-r--r--openssl/doc/apps/genrsa.pod96
-rw-r--r--openssl/doc/apps/nseq.pod70
-rw-r--r--openssl/doc/apps/ocsp.pod365
-rw-r--r--openssl/doc/apps/openssl.pod361
-rw-r--r--openssl/doc/apps/passwd.pod82
-rw-r--r--openssl/doc/apps/pkcs12.pod330
-rw-r--r--openssl/doc/apps/pkcs7.pod105
-rw-r--r--openssl/doc/apps/pkcs8.pod243
-rw-r--r--openssl/doc/apps/rand.pod55
-rw-r--r--openssl/doc/apps/req.pod611
-rw-r--r--openssl/doc/apps/rsa.pod189
-rw-r--r--openssl/doc/apps/rsautl.pod183
-rw-r--r--openssl/doc/apps/s_client.pod297
-rw-r--r--openssl/doc/apps/s_server.pod348
-rw-r--r--openssl/doc/apps/s_time.pod173
-rw-r--r--openssl/doc/apps/sess_id.pod151
-rw-r--r--openssl/doc/apps/smime.pod385
-rw-r--r--openssl/doc/apps/speed.pod59
-rw-r--r--openssl/doc/apps/spkac.pod133
-rw-r--r--openssl/doc/apps/verify.pod328
-rw-r--r--openssl/doc/apps/version.pod64
-rw-r--r--openssl/doc/apps/x509.pod832
-rw-r--r--openssl/doc/apps/x509v3_config.pod456
-rw-r--r--openssl/doc/c-indentation.el45
-rw-r--r--openssl/doc/crypto/ASN1_OBJECT_new.pod43
-rw-r--r--openssl/doc/crypto/ASN1_STRING_length.pod81
-rw-r--r--openssl/doc/crypto/ASN1_STRING_new.pod44
-rw-r--r--openssl/doc/crypto/ASN1_STRING_print_ex.pod96
-rw-r--r--openssl/doc/crypto/ASN1_generate_nconf.pod262
-rw-r--r--openssl/doc/crypto/BIO_ctrl.pod128
-rw-r--r--openssl/doc/crypto/BIO_f_base64.pod81
-rw-r--r--openssl/doc/crypto/BIO_f_buffer.pod69
-rw-r--r--openssl/doc/crypto/BIO_f_cipher.pod76
-rw-r--r--openssl/doc/crypto/BIO_f_md.pod138
-rw-r--r--openssl/doc/crypto/BIO_f_null.pod32
-rw-r--r--openssl/doc/crypto/BIO_f_ssl.pod313
-rw-r--r--openssl/doc/crypto/BIO_find_type.pod98
-rw-r--r--openssl/doc/crypto/BIO_new.pod65
-rw-r--r--openssl/doc/crypto/BIO_push.pod69
-rw-r--r--openssl/doc/crypto/BIO_read.pod66
-rw-r--r--openssl/doc/crypto/BIO_s_accept.pod195
-rw-r--r--openssl/doc/crypto/BIO_s_bio.pod182
-rw-r--r--openssl/doc/crypto/BIO_s_connect.pod192
-rw-r--r--openssl/doc/crypto/BIO_s_fd.pod89
-rw-r--r--openssl/doc/crypto/BIO_s_file.pod144
-rw-r--r--openssl/doc/crypto/BIO_s_mem.pod115
-rw-r--r--openssl/doc/crypto/BIO_s_null.pod37
-rw-r--r--openssl/doc/crypto/BIO_s_socket.pod63
-rw-r--r--openssl/doc/crypto/BIO_set_callback.pod108
-rw-r--r--openssl/doc/crypto/BIO_should_retry.pod114
-rw-r--r--openssl/doc/crypto/BN_BLINDING_new.pod109
-rw-r--r--openssl/doc/crypto/BN_CTX_new.pod53
-rw-r--r--openssl/doc/crypto/BN_CTX_start.pod52
-rw-r--r--openssl/doc/crypto/BN_add.pod126
-rw-r--r--openssl/doc/crypto/BN_add_word.pod61
-rw-r--r--openssl/doc/crypto/BN_bn2bin.pod95
-rw-r--r--openssl/doc/crypto/BN_cmp.pod48
-rw-r--r--openssl/doc/crypto/BN_copy.pod34
-rw-r--r--openssl/doc/crypto/BN_generate_prime.pod102
-rw-r--r--openssl/doc/crypto/BN_mod_inverse.pod36
-rw-r--r--openssl/doc/crypto/BN_mod_mul_montgomery.pod101
-rw-r--r--openssl/doc/crypto/BN_mod_mul_reciprocal.pod81
-rw-r--r--openssl/doc/crypto/BN_new.pod53
-rw-r--r--openssl/doc/crypto/BN_num_bytes.pod57
-rw-r--r--openssl/doc/crypto/BN_rand.pod58
-rw-r--r--openssl/doc/crypto/BN_set_bit.pod66
-rw-r--r--openssl/doc/crypto/BN_swap.pod23
-rw-r--r--openssl/doc/crypto/BN_zero.pod59
-rw-r--r--openssl/doc/crypto/CONF_modules_free.pod47
-rw-r--r--openssl/doc/crypto/CONF_modules_load_file.pod60
-rw-r--r--openssl/doc/crypto/CRYPTO_set_ex_data.pod51
-rw-r--r--openssl/doc/crypto/DH_generate_key.pod50
-rw-r--r--openssl/doc/crypto/DH_generate_parameters.pod73
-rw-r--r--openssl/doc/crypto/DH_get_ex_new_index.pod36
-rw-r--r--openssl/doc/crypto/DH_new.pod40
-rw-r--r--openssl/doc/crypto/DH_set_method.pod129
-rw-r--r--openssl/doc/crypto/DH_size.pod33
-rw-r--r--openssl/doc/crypto/DSA_SIG_new.pod40
-rw-r--r--openssl/doc/crypto/DSA_do_sign.pod47
-rw-r--r--openssl/doc/crypto/DSA_dup_DH.pod36
-rw-r--r--openssl/doc/crypto/DSA_generate_key.pod34
-rw-r--r--openssl/doc/crypto/DSA_generate_parameters.pod105
-rw-r--r--openssl/doc/crypto/DSA_get_ex_new_index.pod36
-rw-r--r--openssl/doc/crypto/DSA_new.pod42
-rw-r--r--openssl/doc/crypto/DSA_set_method.pod143
-rw-r--r--openssl/doc/crypto/DSA_sign.pod66
-rw-r--r--openssl/doc/crypto/DSA_size.pod33
-rw-r--r--openssl/doc/crypto/ERR_GET_LIB.pod51
-rw-r--r--openssl/doc/crypto/ERR_clear_error.pod29
-rw-r--r--openssl/doc/crypto/ERR_error_string.pod73
-rw-r--r--openssl/doc/crypto/ERR_get_error.pod76
-rw-r--r--openssl/doc/crypto/ERR_load_crypto_strings.pod46
-rw-r--r--openssl/doc/crypto/ERR_load_strings.pod54
-rw-r--r--openssl/doc/crypto/ERR_print_errors.pod51
-rw-r--r--openssl/doc/crypto/ERR_put_error.pod44
-rw-r--r--openssl/doc/crypto/ERR_remove_state.pod34
-rw-r--r--openssl/doc/crypto/ERR_set_mark.pod38
-rw-r--r--openssl/doc/crypto/EVP_BytesToKey.pod67
-rw-r--r--openssl/doc/crypto/EVP_DigestInit.pod256
-rw-r--r--openssl/doc/crypto/EVP_EncryptInit.pod511
-rw-r--r--openssl/doc/crypto/EVP_OpenInit.pod63
-rw-r--r--openssl/doc/crypto/EVP_PKEY_new.pod47
-rw-r--r--openssl/doc/crypto/EVP_PKEY_set1_RSA.pod80
-rw-r--r--openssl/doc/crypto/EVP_SealInit.pod85
-rw-r--r--openssl/doc/crypto/EVP_SignInit.pod95
-rw-r--r--openssl/doc/crypto/EVP_VerifyInit.pod86
-rw-r--r--openssl/doc/crypto/OBJ_nid2obj.pod149
-rw-r--r--openssl/doc/crypto/OPENSSL_Applink.pod21
-rw-r--r--openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod101
-rw-r--r--openssl/doc/crypto/OPENSSL_config.pod82
-rw-r--r--openssl/doc/crypto/OPENSSL_ia32cap.pod43
-rw-r--r--openssl/doc/crypto/OPENSSL_load_builtin_modules.pod51
-rw-r--r--openssl/doc/crypto/OpenSSL_add_all_algorithms.pod66
-rw-r--r--openssl/doc/crypto/PKCS12_create.pod75
-rw-r--r--openssl/doc/crypto/PKCS12_parse.pod50
-rw-r--r--openssl/doc/crypto/PKCS7_decrypt.pod53
-rw-r--r--openssl/doc/crypto/PKCS7_encrypt.pod65
-rw-r--r--openssl/doc/crypto/PKCS7_sign.pod101
-rw-r--r--openssl/doc/crypto/PKCS7_verify.pod116
-rw-r--r--openssl/doc/crypto/RAND_add.pod77
-rw-r--r--openssl/doc/crypto/RAND_bytes.pod50
-rw-r--r--openssl/doc/crypto/RAND_cleanup.pod29
-rw-r--r--openssl/doc/crypto/RAND_egd.pod88
-rw-r--r--openssl/doc/crypto/RAND_load_file.pod53
-rw-r--r--openssl/doc/crypto/RAND_set_rand_method.pod83
-rw-r--r--openssl/doc/crypto/RSA_blinding_on.pod43
-rw-r--r--openssl/doc/crypto/RSA_check_key.pod67
-rw-r--r--openssl/doc/crypto/RSA_generate_key.pod69
-rw-r--r--openssl/doc/crypto/RSA_get_ex_new_index.pod120
-rw-r--r--openssl/doc/crypto/RSA_new.pod41
-rw-r--r--openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod124
-rw-r--r--openssl/doc/crypto/RSA_print.pod49
-rw-r--r--openssl/doc/crypto/RSA_private_encrypt.pod70
-rw-r--r--openssl/doc/crypto/RSA_public_encrypt.pod84
-rw-r--r--openssl/doc/crypto/RSA_set_method.pod202
-rw-r--r--openssl/doc/crypto/RSA_sign.pod62
-rw-r--r--openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod59
-rw-r--r--openssl/doc/crypto/RSA_size.pod33
-rw-r--r--openssl/doc/crypto/SMIME_read_PKCS7.pod71
-rw-r--r--openssl/doc/crypto/SMIME_write_PKCS7.pod61
-rw-r--r--openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod72
-rw-r--r--openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod114
-rw-r--r--openssl/doc/crypto/X509_NAME_get_index_by_NID.pod106
-rw-r--r--openssl/doc/crypto/X509_NAME_print_ex.pod105
-rw-r--r--openssl/doc/crypto/X509_new.pod37
-rw-r--r--openssl/doc/crypto/bio.pod54
-rw-r--r--openssl/doc/crypto/blowfish.pod112
-rw-r--r--openssl/doc/crypto/bn.pod181
-rw-r--r--openssl/doc/crypto/bn_internal.pod226
-rw-r--r--openssl/doc/crypto/buffer.pod73
-rw-r--r--openssl/doc/crypto/crypto.pod85
-rw-r--r--openssl/doc/crypto/d2i_ASN1_OBJECT.pod29
-rw-r--r--openssl/doc/crypto/d2i_DHparams.pod30
-rw-r--r--openssl/doc/crypto/d2i_DSAPublicKey.pod83
-rw-r--r--openssl/doc/crypto/d2i_PKCS8PrivateKey.pod56
-rw-r--r--openssl/doc/crypto/d2i_RSAPublicKey.pod67
-rw-r--r--openssl/doc/crypto/d2i_X509.pod231
-rw-r--r--openssl/doc/crypto/d2i_X509_ALGOR.pod30
-rw-r--r--openssl/doc/crypto/d2i_X509_CRL.pod37
-rw-r--r--openssl/doc/crypto/d2i_X509_NAME.pod31
-rw-r--r--openssl/doc/crypto/d2i_X509_REQ.pod36
-rw-r--r--openssl/doc/crypto/d2i_X509_SIG.pod30
-rw-r--r--openssl/doc/crypto/des.pod358
-rw-r--r--openssl/doc/crypto/des_modes.pod255
-rw-r--r--openssl/doc/crypto/dh.pod78
-rw-r--r--openssl/doc/crypto/dsa.pod114
-rw-r--r--openssl/doc/crypto/ecdsa.pod210
-rw-r--r--openssl/doc/crypto/engine.pod599
-rw-r--r--openssl/doc/crypto/err.pod187
-rw-r--r--openssl/doc/crypto/evp.pod45
-rw-r--r--openssl/doc/crypto/hmac.pod102
-rw-r--r--openssl/doc/crypto/lh_stats.pod60
-rw-r--r--openssl/doc/crypto/lhash.pod294
-rw-r--r--openssl/doc/crypto/md5.pod101
-rw-r--r--openssl/doc/crypto/mdc2.pod64
-rw-r--r--openssl/doc/crypto/pem.pod476
-rw-r--r--openssl/doc/crypto/rand.pod175
-rw-r--r--openssl/doc/crypto/rc4.pod62
-rw-r--r--openssl/doc/crypto/ripemd.pod66
-rw-r--r--openssl/doc/crypto/rsa.pod123
-rw-r--r--openssl/doc/crypto/sha.pod70
-rw-r--r--openssl/doc/crypto/threads.pod175
-rw-r--r--openssl/doc/crypto/ui.pod194
-rw-r--r--openssl/doc/crypto/ui_compat.pod55
-rw-r--r--openssl/doc/crypto/x509.pod64
-rw-r--r--openssl/doc/fingerprints.txt57
-rw-r--r--openssl/doc/openssl-shared.txt32
-rw-r--r--openssl/doc/openssl.txt1254
-rw-r--r--openssl/doc/openssl_button.gifbin0 -> 2063 bytes
-rw-r--r--openssl/doc/openssl_button.html7
-rw-r--r--openssl/doc/ssl/SSL_CIPHER_get_name.pod112
-rw-r--r--openssl/doc/ssl/SSL_COMP_add_compression_method.pod70
-rw-r--r--openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod39
-rw-r--r--openssl/doc/ssl/SSL_CTX_add_session.pod73
-rw-r--r--openssl/doc/ssl/SSL_CTX_ctrl.pod34
-rw-r--r--openssl/doc/ssl/SSL_CTX_flush_sessions.pod49
-rw-r--r--openssl/doc/ssl/SSL_CTX_free.pod41
-rw-r--r--openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod53
-rw-r--r--openssl/doc/ssl/SSL_CTX_get_verify_mode.pod50
-rw-r--r--openssl/doc/ssl/SSL_CTX_load_verify_locations.pod124
-rw-r--r--openssl/doc/ssl/SSL_CTX_new.pod94
-rw-r--r--openssl/doc/ssl/SSL_CTX_sess_number.pod76
-rw-r--r--openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod51
-rw-r--r--openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod87
-rw-r--r--openssl/doc/ssl/SSL_CTX_sessions.pod34
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_cert_store.pod57
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod75
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_cipher_list.pod70
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod94
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod94
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod76
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod150
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_info_callback.pod153
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_max_cert_list.pod77
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_mode.pod81
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_msg_callback.pod99
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_options.pod244
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_quiet_shutdown.pod63
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod137
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_session_id_context.pod83
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_ssl_version.pod61
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_timeout.pod59
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod170
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod166
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_verify.pod294
-rw-r--r--openssl/doc/ssl/SSL_CTX_use_certificate.pod169
-rw-r--r--openssl/doc/ssl/SSL_SESSION_free.pod55
-rw-r--r--openssl/doc/ssl/SSL_SESSION_get_ex_new_index.pod61
-rw-r--r--openssl/doc/ssl/SSL_SESSION_get_time.pod64
-rw-r--r--openssl/doc/ssl/SSL_accept.pod76
-rw-r--r--openssl/doc/ssl/SSL_alert_type_string.pod228
-rw-r--r--openssl/doc/ssl/SSL_clear.pod69
-rw-r--r--openssl/doc/ssl/SSL_connect.pod73
-rw-r--r--openssl/doc/ssl/SSL_do_handshake.pod75
-rw-r--r--openssl/doc/ssl/SSL_free.pod44
-rw-r--r--openssl/doc/ssl/SSL_get_SSL_CTX.pod26
-rw-r--r--openssl/doc/ssl/SSL_get_ciphers.pod42
-rw-r--r--openssl/doc/ssl/SSL_get_client_CA_list.pod53
-rw-r--r--openssl/doc/ssl/SSL_get_current_cipher.pod43
-rw-r--r--openssl/doc/ssl/SSL_get_default_timeout.pod41
-rw-r--r--openssl/doc/ssl/SSL_get_error.pod114
-rw-r--r--openssl/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod61
-rw-r--r--openssl/doc/ssl/SSL_get_ex_new_index.pod59
-rw-r--r--openssl/doc/ssl/SSL_get_fd.pod44
-rw-r--r--openssl/doc/ssl/SSL_get_peer_cert_chain.pod52
-rw-r--r--openssl/doc/ssl/SSL_get_peer_certificate.pod55
-rw-r--r--openssl/doc/ssl/SSL_get_rbio.pod40
-rw-r--r--openssl/doc/ssl/SSL_get_session.pod73
-rw-r--r--openssl/doc/ssl/SSL_get_verify_result.pod57
-rw-r--r--openssl/doc/ssl/SSL_get_version.pod46
-rw-r--r--openssl/doc/ssl/SSL_library_init.pod52
-rw-r--r--openssl/doc/ssl/SSL_load_client_CA_file.pod62
-rw-r--r--openssl/doc/ssl/SSL_new.pod44
-rw-r--r--openssl/doc/ssl/SSL_pending.pod43
-rw-r--r--openssl/doc/ssl/SSL_read.pod124
-rw-r--r--openssl/doc/ssl/SSL_rstate_string.pod59
-rw-r--r--openssl/doc/ssl/SSL_session_reused.pod45
-rw-r--r--openssl/doc/ssl/SSL_set_bio.pod34
-rw-r--r--openssl/doc/ssl/SSL_set_connect_state.pod55
-rw-r--r--openssl/doc/ssl/SSL_set_fd.pod54
-rw-r--r--openssl/doc/ssl/SSL_set_session.pod57
-rw-r--r--openssl/doc/ssl/SSL_set_shutdown.pod72
-rw-r--r--openssl/doc/ssl/SSL_set_verify_result.pod38
-rw-r--r--openssl/doc/ssl/SSL_shutdown.pod125
-rw-r--r--openssl/doc/ssl/SSL_state_string.pod45
-rw-r--r--openssl/doc/ssl/SSL_want.pod77
-rw-r--r--openssl/doc/ssl/SSL_write.pod109
-rw-r--r--openssl/doc/ssl/d2i_SSL_SESSION.pod66
-rw-r--r--openssl/doc/ssl/ssl.pod736
-rw-r--r--openssl/doc/ssleay.txt7030
-rw-r--r--openssl/doc/standards.txt281
291 files changed, 40521 insertions, 0 deletions
diff --git a/openssl/doc/HOWTO/certificates.txt b/openssl/doc/HOWTO/certificates.txt
new file mode 100644
index 000000000..a8a34c7ab
--- /dev/null
+++ b/openssl/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/openssl/doc/HOWTO/keys.txt b/openssl/doc/HOWTO/keys.txt
new file mode 100644
index 000000000..7ae2a3a11
--- /dev/null
+++ b/openssl/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/openssl/doc/HOWTO/proxy_certificates.txt b/openssl/doc/HOWTO/proxy_certificates.txt
new file mode 100644
index 000000000..3d36b02f6
--- /dev/null
+++ b/openssl/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:räksmörgås
+
+ 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/openssl/doc/README b/openssl/doc/README
new file mode 100644
index 000000000..6ecc14d99
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/CA.pl.pod b/openssl/doc/apps/CA.pl.pod
new file mode 100644
index 000000000..ed69952f3
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/asn1parse.pod b/openssl/doc/apps/asn1parse.pod
new file mode 100644
index 000000000..542d96906
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/ca.pod b/openssl/doc/apps/ca.pod
new file mode 100644
index 000000000..5618c2dc9
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/ciphers.pod b/openssl/doc/apps/ciphers.pod
new file mode 100644
index 000000000..694e433ef
--- /dev/null
+++ b/openssl/doc/apps/ciphers.pod
@@ -0,0 +1,434 @@
+=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<AES:ALL:!aNULL:!eNULL:+RC4:@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<CAMELLIA>
+
+cipher suites using Camellia.
+
+=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<SEED>
+
+cipher suites using SEED.
+
+=item B<MD5>
+
+cipher suites using MD5.
+
+=item B<SHA1>, B<SHA>
+
+cipher suites using SHA1.
+
+=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 Not implemented.
+ TLS_DH_DSS_WITH_AES_256_CBC_SHA Not implemented.
+ TLS_DH_RSA_WITH_AES_128_CBC_SHA Not implemented.
+ TLS_DH_RSA_WITH_AES_256_CBC_SHA Not implemented.
+
+ 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 SEED ciphersuites from RFC4162, extending TLS v1.0
+
+ TLS_RSA_WITH_SEED_CBC_SHA SEED-SHA
+
+ TLS_DH_DSS_WITH_SEED_CBC_SHA Not implemented.
+ TLS_DH_RSA_WITH_SEED_CBC_SHA Not implemented.
+
+ TLS_DHE_DSS_WITH_SEED_CBC_SHA DHE-DSS-SEED-SHA
+ TLS_DHE_RSA_WITH_SEED_CBC_SHA DHE-RSA-SEED-SHA
+
+ TLS_DH_anon_WITH_SEED_CBC_SHA ADH-SEED-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/openssl/doc/apps/config.pod b/openssl/doc/apps/config.pod
new file mode 100644
index 000000000..ace34b62b
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/crl.pod b/openssl/doc/apps/crl.pod
new file mode 100644
index 000000000..a40c873b9
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/crl2pkcs7.pod b/openssl/doc/apps/crl2pkcs7.pod
new file mode 100644
index 000000000..3797bc0df
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/dgst.pod b/openssl/doc/apps/dgst.pod
new file mode 100644
index 000000000..908cd2a6d
--- /dev/null
+++ b/openssl/doc/apps/dgst.pod
@@ -0,0 +1,115 @@
+=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<-hmac key>]
+[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<-hmac key>
+
+create a hashed MAC using "key".
+
+=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/openssl/doc/apps/dhparam.pod b/openssl/doc/apps/dhparam.pod
new file mode 100644
index 000000000..c31db95a4
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/dsa.pod b/openssl/doc/apps/dsa.pod
new file mode 100644
index 000000000..ed06b8806
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/dsaparam.pod b/openssl/doc/apps/dsaparam.pod
new file mode 100644
index 000000000..b9b1b93b4
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/ec.pod b/openssl/doc/apps/ec.pod
new file mode 100644
index 000000000..1d4a36dbf
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/ecparam.pod b/openssl/doc/apps/ecparam.pod
new file mode 100644
index 000000000..1a12105da
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/enc.pod b/openssl/doc/apps/enc.pod
new file mode 100644
index 000000000..4391c9336
--- /dev/null
+++ b/openssl/doc/apps/enc.pod
@@ -0,0 +1,279 @@
+=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
+
+ aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode
+ aes-[128|192|256] Alias for aes-[128|192|256]-cbc
+ aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode
+ aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode
+ aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode
+ aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode
+ aes-[128|192|256]-ofb 128/192/256 bit AES 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/openssl/doc/apps/errstr.pod b/openssl/doc/apps/errstr.pod
new file mode 100644
index 000000000..b3c6ccfc9
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/gendsa.pod b/openssl/doc/apps/gendsa.pod
new file mode 100644
index 000000000..2c56cc788
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/genrsa.pod b/openssl/doc/apps/genrsa.pod
new file mode 100644
index 000000000..25af4d147
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/nseq.pod b/openssl/doc/apps/nseq.pod
new file mode 100644
index 000000000..989c3108f
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/ocsp.pod b/openssl/doc/apps/ocsp.pod
new file mode 100644
index 000000000..b58ddc178
--- /dev/null
+++ b/openssl/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. This option B<MUST> come before any B<-cert> options.
+
+=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_other> 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_other> 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_other> 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/openssl/doc/apps/openssl.pod b/openssl/doc/apps/openssl.pod
new file mode 100644
index 000000000..964cdf0f0
--- /dev/null
+++ b/openssl/doc/apps/openssl.pod
@@ -0,0 +1,361 @@
+
+=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
+
+=item B<sha224>
+
+SHA-224 Digest
+
+=item B<sha256>
+
+SHA-256 Digest
+
+=item B<sha384>
+
+SHA-384 Digest
+
+=item B<sha512>
+
+SHA-512 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/openssl/doc/apps/passwd.pod b/openssl/doc/apps/passwd.pod
new file mode 100644
index 000000000..f44982549
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/pkcs12.pod b/openssl/doc/apps/pkcs12.pod
new file mode 100644
index 000000000..7d8414629
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/pkcs7.pod b/openssl/doc/apps/pkcs7.pod
new file mode 100644
index 000000000..a0a636328
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/pkcs8.pod b/openssl/doc/apps/pkcs8.pod
new file mode 100644
index 000000000..68ecd65b1
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/rand.pod b/openssl/doc/apps/rand.pod
new file mode 100644
index 000000000..d1d213ef4
--- /dev/null
+++ b/openssl/doc/apps/rand.pod
@@ -0,0 +1,55 @@
+=pod
+
+=head1 NAME
+
+rand - generate pseudo-random bytes
+
+=head1 SYNOPSIS
+
+B<openssl rand>
+[B<-out> I<file>]
+[B<-rand> I<file(s)>]
+[B<-base64>]
+[B<-hex>]
+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.
+
+=item B<-hex>
+
+Show the output as a hex string.
+
+=back
+
+=head1 SEE ALSO
+
+L<RAND_bytes(3)|RAND_bytes(3)>
+
+=cut
diff --git a/openssl/doc/apps/req.pod b/openssl/doc/apps/req.pod
new file mode 100644
index 000000000..82b565c9d
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/rsa.pod b/openssl/doc/apps/rsa.pod
new file mode 100644
index 000000000..4d7640995
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/rsautl.pod b/openssl/doc/apps/rsautl.pod
new file mode 100644
index 000000000..1a498c2f6
--- /dev/null
+++ b/openssl/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 -pubkey -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/openssl/doc/apps/s_client.pod b/openssl/doc/apps/s_client.pod
new file mode 100644
index 000000000..c44d357cf
--- /dev/null
+++ b/openssl/doc/apps/s_client.pod
@@ -0,0 +1,297 @@
+
+=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<-tlsextdebug>]
+[B<-no_ticket>]
+[B<-sess_out filename>]
+[B<-sess_in filename>]
+[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<-tlsextdebug>
+
+print out a hex dump of any TLS extensions received from the server. Note: this
+option is only available if extension support is explicitly enabled at compile
+time
+
+=item B<-no_ticket>
+
+disable RFC4507bis session ticket support. Note: this option is only available
+if extension support is explicitly enabled at compile time
+
+=item B<-sess_out filename>
+
+output SSL session to B<filename>
+
+=item B<-sess_in sess.pem>
+
+load SSL session from B<filename>. The client will attempt to resume a
+connection from this session.
+
+=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.
+
+Since the SSLv23 client hello cannot include compression methods or extensions
+these will only be supported if its use is disabled, for example by using the
+B<-no_sslv2> option.
+
+TLS extensions are only supported in OpenSSL 0.9.8 if they are explictly
+enabled at compile time using for example the B<enable-tlsext> switch.
+
+=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/openssl/doc/apps/s_server.pod b/openssl/doc/apps/s_server.pod
new file mode 100644
index 000000000..fdcc170e2
--- /dev/null
+++ b/openssl/doc/apps/s_server.pod
@@ -0,0 +1,348 @@
+
+=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<-crl_check>]
+[B<-crl_check_all>]
+[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<-tlsextdebug>]
+[B<-no_ticket>]
+[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<-crl_check>, B<-crl_check_all>
+
+Check the peer certificate has not been revoked by its CA.
+The CRL(s) are appended to the certificate file. With the B<-crl_check_all>
+option all CRLs of all CAs in the chain are checked.
+
+=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<-tlsextdebug>
+
+print out a hex dump of any TLS extensions received from the server.
+
+=item B<-no_ticket>
+
+disable RFC4507bis session ticket support.
+
+=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.
+
+TLS extensions are only supported in OpenSSL 0.9.8 if they are explictly
+enabled at compile time using for example the B<enable-tlsext> switch.
+
+=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/openssl/doc/apps/s_time.pod b/openssl/doc/apps/s_time.pod
new file mode 100644
index 000000000..5a38aa2e0
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/sess_id.pod b/openssl/doc/apps/sess_id.pod
new file mode 100644
index 000000000..9988d2cd3
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/smime.pod b/openssl/doc/apps/smime.pod
new file mode 100644
index 000000000..caf2d2689
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/speed.pod b/openssl/doc/apps/speed.pod
new file mode 100644
index 000000000..0dcdba873
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/spkac.pod b/openssl/doc/apps/spkac.pod
new file mode 100644
index 000000000..c3f1ff9c6
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/verify.pod b/openssl/doc/apps/verify.pod
new file mode 100644
index 000000000..ff2629d2c
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/version.pod b/openssl/doc/apps/version.pod
new file mode 100644
index 000000000..e00324c44
--- /dev/null
+++ b/openssl/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/openssl/doc/apps/x509.pod b/openssl/doc/apps/x509.pod
new file mode 100644
index 000000000..f43c17523
--- /dev/null
+++ b/openssl/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 "-subject_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/openssl/doc/apps/x509v3_config.pod b/openssl/doc/apps/x509v3_config.pod
new file mode 100644
index 000000000..38c46e85c
--- /dev/null
+++ b/openssl/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/openssl/doc/c-indentation.el b/openssl/doc/c-indentation.el
new file mode 100644
index 000000000..90861d397
--- /dev/null
+++ b/openssl/doc/c-indentation.el
@@ -0,0 +1,45 @@
+; 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)
+ (indent-tabs-mode . t)
+ (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/openssl/doc/crypto/ASN1_OBJECT_new.pod b/openssl/doc/crypto/ASN1_OBJECT_new.pod
new file mode 100644
index 000000000..51679bfcd
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ASN1_STRING_length.pod b/openssl/doc/crypto/ASN1_STRING_length.pod
new file mode 100644
index 000000000..c4ec693f1
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ASN1_STRING_new.pod b/openssl/doc/crypto/ASN1_STRING_new.pod
new file mode 100644
index 000000000..5b1bbb7eb
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ASN1_STRING_print_ex.pod b/openssl/doc/crypto/ASN1_STRING_print_ex.pod
new file mode 100644
index 000000000..3891b8879
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ASN1_generate_nconf.pod b/openssl/doc/crypto/ASN1_generate_nconf.pod
new file mode 100644
index 000000000..1157cff51
--- /dev/null
+++ b/openssl/doc/crypto/ASN1_generate_nconf.pod
@@ -0,0 +1,262 @@
+=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:
+
+=over 2
+
+=item B<[modifier,]type[:value]>
+
+=back
+
+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>
+
+Encodes 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<BITSTRING>, B<BITSTR>
+
+Encodes 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 the indices of the set bits, all other
+bits are zero.
+
+=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 BITSTRING with bits 1 and 5 set and all others zero:
+
+ FORMAT=BITLIST,BITSTRING:1,5
+
+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/openssl/doc/crypto/BIO_ctrl.pod b/openssl/doc/crypto/BIO_ctrl.pod
new file mode 100644
index 000000000..722e8b8f4
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_f_base64.pod b/openssl/doc/crypto/BIO_f_base64.pod
new file mode 100644
index 000000000..438af3b6b
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_f_buffer.pod b/openssl/doc/crypto/BIO_f_buffer.pod
new file mode 100644
index 000000000..c9093c6a5
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_f_cipher.pod b/openssl/doc/crypto/BIO_f_cipher.pod
new file mode 100644
index 000000000..02439cea9
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_f_md.pod b/openssl/doc/crypto/BIO_f_md.pod
new file mode 100644
index 000000000..0d24083e6
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_f_null.pod b/openssl/doc/crypto/BIO_f_null.pod
new file mode 100644
index 000000000..b057c1840
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_f_ssl.pod b/openssl/doc/crypto/BIO_f_ssl.pod
new file mode 100644
index 000000000..f0b731731
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_find_type.pod b/openssl/doc/crypto/BIO_find_type.pod
new file mode 100644
index 000000000..bd3b25619
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_new.pod b/openssl/doc/crypto/BIO_new.pod
new file mode 100644
index 000000000..2a245fc8d
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_push.pod b/openssl/doc/crypto/BIO_push.pod
new file mode 100644
index 000000000..8af1d3c09
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_read.pod b/openssl/doc/crypto/BIO_read.pod
new file mode 100644
index 000000000..b34528104
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_s_accept.pod b/openssl/doc/crypto/BIO_s_accept.pod
new file mode 100644
index 000000000..7b63e4621
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_s_bio.pod b/openssl/doc/crypto/BIO_s_bio.pod
new file mode 100644
index 000000000..8d0a55a02
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_s_connect.pod b/openssl/doc/crypto/BIO_s_connect.pod
new file mode 100644
index 000000000..bcf7d8dca
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_s_fd.pod b/openssl/doc/crypto/BIO_s_fd.pod
new file mode 100644
index 000000000..b1de1d101
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_s_file.pod b/openssl/doc/crypto/BIO_s_file.pod
new file mode 100644
index 000000000..b2a29263f
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_s_mem.pod b/openssl/doc/crypto/BIO_s_mem.pod
new file mode 100644
index 000000000..19648acfa
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_s_null.pod b/openssl/doc/crypto/BIO_s_null.pod
new file mode 100644
index 000000000..e5514f723
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_s_socket.pod b/openssl/doc/crypto/BIO_s_socket.pod
new file mode 100644
index 000000000..1c8d3a911
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_set_callback.pod b/openssl/doc/crypto/BIO_set_callback.pod
new file mode 100644
index 000000000..475955624
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BIO_should_retry.pod b/openssl/doc/crypto/BIO_should_retry.pod
new file mode 100644
index 000000000..539c39127
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_BLINDING_new.pod b/openssl/doc/crypto/BN_BLINDING_new.pod
new file mode 100644
index 000000000..7b087f728
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_CTX_new.pod b/openssl/doc/crypto/BN_CTX_new.pod
new file mode 100644
index 000000000..ad8d07db8
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_CTX_start.pod b/openssl/doc/crypto/BN_CTX_start.pod
new file mode 100644
index 000000000..dfcefe1a8
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_add.pod b/openssl/doc/crypto/BN_add.pod
new file mode 100644
index 000000000..88c7a799e
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_add_word.pod b/openssl/doc/crypto/BN_add_word.pod
new file mode 100644
index 000000000..70667d289
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_bn2bin.pod b/openssl/doc/crypto/BN_bn2bin.pod
new file mode 100644
index 000000000..a4b17ca60
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_cmp.pod b/openssl/doc/crypto/BN_cmp.pod
new file mode 100644
index 000000000..23e9ed0b4
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_copy.pod b/openssl/doc/crypto/BN_copy.pod
new file mode 100644
index 000000000..388dd7df2
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_generate_prime.pod b/openssl/doc/crypto/BN_generate_prime.pod
new file mode 100644
index 000000000..7dccacbc1
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_mod_inverse.pod b/openssl/doc/crypto/BN_mod_inverse.pod
new file mode 100644
index 000000000..3ea3975c7
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_mod_mul_montgomery.pod b/openssl/doc/crypto/BN_mod_mul_montgomery.pod
new file mode 100644
index 000000000..6b16351b9
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_mod_mul_reciprocal.pod b/openssl/doc/crypto/BN_mod_mul_reciprocal.pod
new file mode 100644
index 000000000..74a216ddc
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_new.pod b/openssl/doc/crypto/BN_new.pod
new file mode 100644
index 000000000..ab7a105e3
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_num_bytes.pod b/openssl/doc/crypto/BN_num_bytes.pod
new file mode 100644
index 000000000..a6a2e3f81
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_rand.pod b/openssl/doc/crypto/BN_rand.pod
new file mode 100644
index 000000000..81f93c2eb
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_set_bit.pod b/openssl/doc/crypto/BN_set_bit.pod
new file mode 100644
index 000000000..b7c47b9b0
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_swap.pod b/openssl/doc/crypto/BN_swap.pod
new file mode 100644
index 000000000..79efaa144
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/BN_zero.pod b/openssl/doc/crypto/BN_zero.pod
new file mode 100644
index 000000000..b555ec398
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/CONF_modules_free.pod b/openssl/doc/crypto/CONF_modules_free.pod
new file mode 100644
index 000000000..87bc7b783
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/CONF_modules_load_file.pod b/openssl/doc/crypto/CONF_modules_load_file.pod
new file mode 100644
index 000000000..9965d69bf
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/CRYPTO_set_ex_data.pod b/openssl/doc/crypto/CRYPTO_set_ex_data.pod
new file mode 100644
index 000000000..1bd5bed67
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DH_generate_key.pod b/openssl/doc/crypto/DH_generate_key.pod
new file mode 100644
index 000000000..81f09fdf4
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DH_generate_parameters.pod b/openssl/doc/crypto/DH_generate_parameters.pod
new file mode 100644
index 000000000..9081e9ea7
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DH_get_ex_new_index.pod b/openssl/doc/crypto/DH_get_ex_new_index.pod
new file mode 100644
index 000000000..fa5eab265
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DH_new.pod b/openssl/doc/crypto/DH_new.pod
new file mode 100644
index 000000000..60c930093
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DH_set_method.pod b/openssl/doc/crypto/DH_set_method.pod
new file mode 100644
index 000000000..d5cdc3be0
--- /dev/null
+++ b/openssl/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 dependent 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/openssl/doc/crypto/DH_size.pod b/openssl/doc/crypto/DH_size.pod
new file mode 100644
index 000000000..97f26fda7
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DSA_SIG_new.pod b/openssl/doc/crypto/DSA_SIG_new.pod
new file mode 100644
index 000000000..3ac614003
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DSA_do_sign.pod b/openssl/doc/crypto/DSA_do_sign.pod
new file mode 100644
index 000000000..5dfc733b2
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DSA_dup_DH.pod b/openssl/doc/crypto/DSA_dup_DH.pod
new file mode 100644
index 000000000..7f6f0d111
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DSA_generate_key.pod b/openssl/doc/crypto/DSA_generate_key.pod
new file mode 100644
index 000000000..af83ccfaa
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DSA_generate_parameters.pod b/openssl/doc/crypto/DSA_generate_parameters.pod
new file mode 100644
index 000000000..be7c924ff
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DSA_get_ex_new_index.pod b/openssl/doc/crypto/DSA_get_ex_new_index.pod
new file mode 100644
index 000000000..4612e708e
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DSA_new.pod b/openssl/doc/crypto/DSA_new.pod
new file mode 100644
index 000000000..48e9b82a0
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DSA_set_method.pod b/openssl/doc/crypto/DSA_set_method.pod
new file mode 100644
index 000000000..9c1434bd8
--- /dev/null
+++ b/openssl/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 dependent 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/openssl/doc/crypto/DSA_sign.pod b/openssl/doc/crypto/DSA_sign.pod
new file mode 100644
index 000000000..97389e8ec
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/DSA_size.pod b/openssl/doc/crypto/DSA_size.pod
new file mode 100644
index 000000000..ba4f65036
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ERR_GET_LIB.pod b/openssl/doc/crypto/ERR_GET_LIB.pod
new file mode 100644
index 000000000..2a129da03
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ERR_clear_error.pod b/openssl/doc/crypto/ERR_clear_error.pod
new file mode 100644
index 000000000..566e1f4e3
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ERR_error_string.pod b/openssl/doc/crypto/ERR_error_string.pod
new file mode 100644
index 000000000..cdfa7fe1f
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ERR_get_error.pod b/openssl/doc/crypto/ERR_get_error.pod
new file mode 100644
index 000000000..34443045f
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ERR_load_crypto_strings.pod b/openssl/doc/crypto/ERR_load_crypto_strings.pod
new file mode 100644
index 000000000..9bdec75a4
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ERR_load_strings.pod b/openssl/doc/crypto/ERR_load_strings.pod
new file mode 100644
index 000000000..5acdd0edb
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ERR_print_errors.pod b/openssl/doc/crypto/ERR_print_errors.pod
new file mode 100644
index 000000000..b100a5fa2
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ERR_put_error.pod b/openssl/doc/crypto/ERR_put_error.pod
new file mode 100644
index 000000000..acd241fbe
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ERR_remove_state.pod b/openssl/doc/crypto/ERR_remove_state.pod
new file mode 100644
index 000000000..72925fb9f
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/ERR_set_mark.pod b/openssl/doc/crypto/ERR_set_mark.pod
new file mode 100644
index 000000000..d3ca4f2e7
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/EVP_BytesToKey.pod b/openssl/doc/crypto/EVP_BytesToKey.pod
new file mode 100644
index 000000000..d375c46e0
--- /dev/null
+++ b/openssl/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/openssl/doc/crypto/EVP_DigestInit.pod b/openssl/doc/crypto/EVP_DigestInit.pod
new file mode 100644
index 000000000..130cd7f60
--- /dev/null
+++ b/openssl/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]) {
+ printf("Usage: mdtest digestname\n");
+ exit(1);
+ }
+
+ md = EVP_get_digestbyname(argv[1]);
+
+ if(!md) {
+ printf("Unknown message digest %s\n", argv[1]);
+ exit(1);
+ }
+
+ EVP_MD_CTX_init(&mdctx);
+ EVP_DigestInit_ex(&mdctx, md, NULL);
+ EVP_DigestUpdate(&mdctx, mess1, strlen(mess1));
+ EVP_DigestUpdate(&mdctx, mess2, strlen(mess2));
+ EVP_DigestFinal_ex(&mdctx, md_value, &md_len);
+ EVP_MD_CTX_cleanup(&mdctx);
+
+ printf("Digest is: ");
+ for(i = 0; i < md_len; i++) printf("%02x", md_value[i]);
+ printf("\n");
+ }
+
+=head1 BUGS
+
+The link between digests and signing algorithms results in a situation where
+EVP_sha1() must be used with RSA and EVP_dss1() must be used with DSS
+even though they are identical digests.
+
+=head1 SEE ALSO
+
+L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
+L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
+L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
+
+=head1 HISTORY
+
+EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are
+available in all versions of SSLeay and OpenSSL.
+
+EVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(),
+EVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex()
+and EVP_DigestFinal_ex() were added in OpenSSL 0.9.7.
+
+EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(),
+EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were
+changed to return truely const EVP_MD * in OpenSSL 0.9.7.
+
+=cut
diff --git a/openssl/doc/crypto/EVP_EncryptInit.pod b/openssl/doc/crypto/EVP_EncryptInit.pod
new file mode 100644
index 000000000..8271d3dfc
--- /dev/null
+++ b/openssl/doc/crypto/EVP_EncryptInit.pod
@@ -0,0 +1,511 @@
+=pod
+
+=head1 NAME
+
+EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate,
+EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate,
+EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate,
+EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length,
+EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit,
+EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal,
+EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname,
+EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid,
+EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length,
+EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher,
+EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length,
+EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data,
+EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags,
+EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param,
+EVP_CIPHER_CTX_set_padding - EVP cipher routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a);
+
+ int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ ENGINE *impl, unsigned char *key, unsigned char *iv);
+ int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl, unsigned char *in, int inl);
+ int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl);
+
+ int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ ENGINE *impl, unsigned char *key, unsigned char *iv);
+ int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl, unsigned char *in, int inl);
+ int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
+ int *outl);
+
+ int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ ENGINE *impl, unsigned char *key, unsigned char *iv, int enc);
+ int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl, unsigned char *in, int inl);
+ int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
+ int *outl);
+
+ int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ unsigned char *key, unsigned char *iv);
+ int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl);
+
+ int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ unsigned char *key, unsigned char *iv);
+ int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
+ int *outl);
+
+ int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ unsigned char *key, unsigned char *iv, int enc);
+ int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
+ int *outl);
+
+ int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
+ int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
+ int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
+ int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a);
+
+ const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
+ #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a))
+ #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a))
+
+ #define EVP_CIPHER_nid(e) ((e)->nid)
+ #define EVP_CIPHER_block_size(e) ((e)->block_size)
+ #define EVP_CIPHER_key_length(e) ((e)->key_len)
+ #define EVP_CIPHER_iv_length(e) ((e)->iv_len)
+ #define EVP_CIPHER_flags(e) ((e)->flags)
+ #define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE)
+ int EVP_CIPHER_type(const EVP_CIPHER *ctx);
+
+ #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher)
+ #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid)
+ #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size)
+ #define EVP_CIPHER_CTX_key_length(e) ((e)->key_len)
+ #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len)
+ #define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data)
+ #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d))
+ #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c))
+ #define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags)
+ #define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE)
+
+ int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
+ int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
+
+=head1 DESCRIPTION
+
+The EVP cipher routines are a high level interface to certain
+symmetric ciphers.
+
+EVP_CIPHER_CTX_init() initializes cipher contex B<ctx>.
+
+EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
+with cipher B<type> from ENGINE B<impl>. B<ctx> must be initialized
+before calling this function. B<type> is normally supplied
+by a function such as EVP_des_cbc(). If B<impl> is NULL then the
+default implementation is used. B<key> is the symmetric key to use
+and B<iv> is the IV to use (if necessary), the actual number of bytes
+used for the key and IV depends on the cipher. It is possible to set
+all parameters to NULL except B<type> in an initial call and supply
+the remaining parameters in subsequent calls, all of which have B<type>
+set to NULL. This is done when the default cipher parameters are not
+appropriate.
+
+EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and
+writes the encrypted version to B<out>. This function can be called
+multiple times to encrypt successive blocks of data. The amount
+of data written depends on the block alignment of the encrypted data:
+as a result the amount of data written may be anything from zero bytes
+to (inl + cipher_block_size - 1) so B<outl> should contain sufficient
+room. The actual number of bytes written is placed in B<outl>.
+
+If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts
+the "final" data, that is any data that remains in a partial block.
+It uses L<standard block padding|/NOTES> (aka PKCS padding). The encrypted
+final data is written to B<out> which should have sufficient space for
+one cipher block. The number of bytes written is placed in B<outl>. After
+this function is called the encryption operation is finished and no further
+calls to EVP_EncryptUpdate() should be made.
+
+If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more
+data and it will return an error if any data remains in a partial block:
+that is if the total data length is not a multiple of the block size.
+
+EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the
+corresponding decryption operations. EVP_DecryptFinal() will return an
+error code if padding is enabled and the final block is not correctly
+formatted. The parameters and restrictions are identical to the encryption
+operations except that if padding is enabled the decrypted data buffer B<out>
+passed to EVP_DecryptUpdate() should have sufficient room for
+(B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in
+which case B<inl> bytes is sufficient.
+
+EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are
+functions that can be used for decryption or encryption. The operation
+performed depends on the value of the B<enc> parameter. It should be set
+to 1 for encryption, 0 for decryption and -1 to leave the value unchanged
+(the actual value of 'enc' being supplied in a previous call).
+
+EVP_CIPHER_CTX_cleanup() clears all information from a cipher context
+and free up any allocated memory associate with it. It should be called
+after all operations using a cipher are complete so sensitive information
+does not remain in memory.
+
+EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
+similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and
+EVP_CipherInit_ex() except the B<ctx> paramter does not need to be
+initialized and they always use the default cipher implementation.
+
+EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() behave in a
+similar way to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and
+EVP_CipherFinal_ex() except B<ctx> is automatically cleaned up
+after the call.
+
+EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
+return an EVP_CIPHER structure when passed a cipher name, a NID or an
+ASN1_OBJECT structure.
+
+EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when
+passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure. The actual NID
+value is an internal value which may not have a corresponding OBJECT
+IDENTIFIER.
+
+EVP_CIPHER_CTX_set_padding() enables or disables padding. By default
+encryption operations are padded using standard block padding and the
+padding is checked and removed when decrypting. If the B<pad> parameter
+is zero then no padding is performed, the total amount of data encrypted
+or decrypted must then be a multiple of the block size or an error will
+occur.
+
+EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
+length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
+structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length
+for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a
+given cipher, the value of EVP_CIPHER_CTX_key_length() may be different
+for variable key length ciphers.
+
+EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx.
+If the cipher is a fixed length cipher then attempting to set the key
+length to any value other than the fixed value is an error.
+
+EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
+length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>.
+It will return zero if the cipher does not use an IV. The constant
+B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers.
+
+EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
+size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
+structure. The constant B<EVP_MAX_IV_LENGTH> is also the maximum block
+length for all ciphers.
+
+EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed
+cipher or context. This "type" is the actual NID of the cipher OBJECT
+IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and
+128 bit RC2 have the same NID. If the cipher does not have an object
+identifier or does not have ASN1 support this function will return
+B<NID_undef>.
+
+EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed
+an B<EVP_CIPHER_CTX> structure.
+
+EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode:
+EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or
+EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then
+EVP_CIPH_STREAM_CIPHER is returned.
+
+EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based
+on the passed cipher. This will typically include any parameters and an
+IV. The cipher IV (if any) must be set when this call is made. This call
+should be made before the cipher is actually "used" (before any
+EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function
+may fail if the cipher does not have any ASN1 support.
+
+EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1
+AlgorithmIdentifier "parameter". The precise effect depends on the cipher
+In the case of RC2, for example, it will set the IV and effective key length.
+This function should be called after the base cipher type is set but before
+the key is set. For example EVP_CipherInit() will be called with the IV and
+key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally
+EVP_CipherInit() again with all parameters except the key set to NULL. It is
+possible for this function to fail if the cipher does not have any ASN1 support
+or the parameters cannot be set (for example the RC2 effective key length
+is not supported.
+
+EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined
+and set. Currently only the RC2 effective key length and the number of rounds of
+RC5 can be set.
+
+=head1 RETURN VALUES
+
+EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
+return 1 for success and 0 for failure.
+
+EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for failure.
+EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.
+
+EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure.
+EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.
+
+EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure.
+
+EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
+return an B<EVP_CIPHER> structure or NULL on error.
+
+EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID.
+
+EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
+size.
+
+EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
+length.
+
+EVP_CIPHER_CTX_set_padding() always returns 1.
+
+EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
+length or zero if the cipher does not use an IV.
+
+EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's
+OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER.
+
+EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure.
+
+EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for
+success or zero for failure.
+
+=head1 CIPHER LISTING
+
+All algorithms have a fixed key length unless otherwise stated.
+
+=over 4
+
+=item EVP_enc_null()
+
+Null cipher: does nothing.
+
+=item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)
+
+DES in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void)
+
+Two key triple DES in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void)
+
+Three key triple DES in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_desx_cbc(void)
+
+DESX algorithm in CBC mode.
+
+=item EVP_rc4(void)
+
+RC4 stream cipher. This is a variable key length cipher with default key length 128 bits.
+
+=item EVP_rc4_40(void)
+
+RC4 stream cipher with 40 bit key length. This is obsolete and new code should use EVP_rc4()
+and the EVP_CIPHER_CTX_set_key_length() function.
+
+=item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void)
+
+IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void)
+
+RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
+length cipher with an additional parameter called "effective key bits" or "effective key length".
+By default both are set to 128 bits.
+
+=item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)
+
+RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits.
+These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and
+EVP_CIPHER_CTX_ctrl() to set the key length and effective key length.
+
+=item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);
+
+Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
+length cipher.
+
+=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void)
+
+CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
+length cipher.
+
+=item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void)
+
+RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length
+cipher with an additional "number of rounds" parameter. By default the key length is set to 128
+bits and 12 rounds.
+
+=back
+
+=head1 NOTES
+
+Where possible the B<EVP> interface to symmetric ciphers should be used in
+preference to the low level interfaces. This is because the code then becomes
+transparent to the cipher used and much more flexible.
+
+PKCS padding works by adding B<n> padding bytes of value B<n> to make the total
+length of the encrypted data a multiple of the block size. Padding is always
+added so if the data is already a multiple of the block size B<n> will equal
+the block size. For example if the block size is 8 and 11 bytes are to be
+encrypted then 5 padding bytes of value 5 will be added.
+
+When decrypting the final block is checked to see if it has the correct form.
+
+Although the decryption operation can produce an error if padding is enabled,
+it is not a strong test that the input data or key is correct. A random block
+has better than 1 in 256 chance of being of the correct format and problems with
+the input data earlier on will not produce a final decrypt error.
+
+If padding is disabled then the decryption operation will always succeed if
+the total amount of data decrypted is a multiple of the block size.
+
+The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(),
+EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for
+compatibility with existing code. New code should use EVP_EncryptInit_ex(),
+EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
+EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an
+existing context without allocating and freeing it up on each call.
+
+=head1 BUGS
+
+For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is
+a limitation of the current RC5 code rather than the EVP interface.
+
+EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with
+default key lengths. If custom ciphers exceed these values the results are
+unpredictable. This is because it has become standard practice to define a
+generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes.
+
+The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested
+for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
+
+=head1 EXAMPLES
+
+Get the number of rounds used in RC5:
+
+ int nrounds;
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds);
+
+Get the RC2 effective key length:
+
+ int key_bits;
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits);
+
+Set the number of rounds used in RC5:
+
+ int nrounds;
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL);
+
+Set the effective key length used in RC2:
+
+ int key_bits;
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL);
+
+Encrypt a string using blowfish:
+
+ int do_crypt(char *outfile)
+ {
+ unsigned char outbuf[1024];
+ int outlen, tmplen;
+ /* Bogus key and IV: we'd normally set these from
+ * another source.
+ */
+ unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
+ unsigned char iv[] = {1,2,3,4,5,6,7,8};
+ char intext[] = "Some Crypto Text";
+ EVP_CIPHER_CTX ctx;
+ FILE *out;
+ EVP_CIPHER_CTX_init(&ctx);
+ EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv);
+
+ if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))
+ {
+ /* Error */
+ return 0;
+ }
+ /* Buffer passed to EVP_EncryptFinal() must be after data just
+ * encrypted to avoid overwriting it.
+ */
+ if(!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen))
+ {
+ /* Error */
+ return 0;
+ }
+ outlen += tmplen;
+ EVP_CIPHER_CTX_cleanup(&ctx);
+ /* Need binary mode for fopen because encrypted data is
+ * binary data. Also cannot use strlen() on it because
+ * it wont be null terminated and may contain embedded
+ * nulls.
+ */
+ out = fopen(outfile, "wb");
+ fwrite(outbuf, 1, outlen, out);
+ fclose(out);
+ return 1;
+ }
+
+The ciphertext from the above example can be decrypted using the B<openssl>
+utility with the command line:
+
+ S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d>
+
+General encryption, decryption function example using FILE I/O and RC2 with an
+80 bit key:
+
+ int do_crypt(FILE *in, FILE *out, int do_encrypt)
+ {
+ /* Allow enough space in output buffer for additional block */
+ inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
+ int inlen, outlen;
+ /* Bogus key and IV: we'd normally set these from
+ * another source.
+ */
+ unsigned char key[] = "0123456789";
+ unsigned char iv[] = "12345678";
+ /* Don't set key or IV because we will modify the parameters */
+ EVP_CIPHER_CTX_init(&ctx);
+ EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt);
+ EVP_CIPHER_CTX_set_key_length(&ctx, 10);
+ /* We finished modifying parameters so now we can set key and IV */
+ EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
+
+ for(;;)
+ {
+ inlen = fread(inbuf, 1, 1024, in);
+ if(inlen <= 0) break;
+ if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen))
+ {
+ /* Error */
+ EVP_CIPHER_CTX_cleanup(&ctx);
+ return 0;
+ }
+ fwrite(outbuf, 1, outlen, out);
+ }
+ if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen))
+ {
+ /* Error */
+ EVP_CIPHER_CTX_cleanup(&ctx);
+ return 0;
+ }
+ fwrite(outbuf, 1, outlen, out);
+
+ EVP_CIPHER_CTX_cleanup(&ctx);
+ return 1;
+ }
+
+
+=head1 SEE ALSO
+
+L<evp(3)|evp(3)>
+
+=head1 HISTORY
+
+EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(),
+EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(),
+EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in
+OpenSSL 0.9.7.
+
+=cut
diff --git a/openssl/doc/crypto/EVP_OpenInit.pod b/openssl/doc/crypto/EVP_OpenInit.pod
new file mode 100644
index 000000000..2e710da94
--- /dev/null
+++ b/openssl/doc/crypto/EVP_OpenInit.pod
@@ -0,0 +1,63 @@
+=pod
+
+=head1 NAME
+
+EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek,
+ int ekl,unsigned char *iv,EVP_PKEY *priv);
+ int EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl, unsigned char *in, int inl);
+ int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl);
+
+=head1 DESCRIPTION
+
+The EVP envelope routines are a high level interface to envelope
+decryption. They decrypt a public key encrypted symmetric key and
+then decrypt data using it.
+
+EVP_OpenInit() initializes a cipher context B<ctx> for decryption
+with cipher B<type>. It decrypts the encrypted symmetric key of length
+B<ekl> bytes passed in the B<ek> parameter using the private key B<priv>.
+The IV is supplied in the B<iv> parameter.
+
+EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties
+as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as
+documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual
+page.
+
+=head1 NOTES
+
+It is possible to call EVP_OpenInit() twice in the same way as
+EVP_DecryptInit(). The first call should have B<priv> set to NULL
+and (after setting any cipher parameters) it should be called again
+with B<type> set to NULL.
+
+If the cipher passed in the B<type> parameter is a variable length
+cipher then the key length will be set to the value of the recovered
+key length. If the cipher is a fixed length cipher then the recovered
+key length must match the fixed cipher length.
+
+=head1 RETURN VALUES
+
+EVP_OpenInit() returns 0 on error or a non zero integer (actually the
+recovered secret key size) if successful.
+
+EVP_OpenUpdate() returns 1 for success or 0 for failure.
+
+EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success.
+
+=head1 SEE ALSO
+
+L<evp(3)|evp(3)>, L<rand(3)|rand(3)>,
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
+L<EVP_SealInit(3)|EVP_SealInit(3)>
+
+=head1 HISTORY
+
+=cut
diff --git a/openssl/doc/crypto/EVP_PKEY_new.pod b/openssl/doc/crypto/EVP_PKEY_new.pod
new file mode 100644
index 000000000..10687e458
--- /dev/null
+++ b/openssl/doc/crypto/EVP_PKEY_new.pod
@@ -0,0 +1,47 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_new, EVP_PKEY_free - private key allocation functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_PKEY *EVP_PKEY_new(void);
+ void EVP_PKEY_free(EVP_PKEY *key);
+
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_new() function allocates an empty B<EVP_PKEY>
+structure which is used by OpenSSL to store private keys.
+
+EVP_PKEY_free() frees up the private key B<key>.
+
+=head1 NOTES
+
+The B<EVP_PKEY> structure is used by various OpenSSL functions
+which require a general private key without reference to any
+particular algorithm.
+
+The structure returned by EVP_PKEY_new() is empty. To add a
+private key to this empty structure the functions described in
+L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> should be used.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY>
+structure of B<NULL> if an error occurred.
+
+EVP_PKEY_free() does not return a value.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod b/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod
new file mode 100644
index 000000000..2db692e27
--- /dev/null
+++ b/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod
@@ -0,0 +1,80 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
+EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
+EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY,
+EVP_PKEY_type - EVP_PKEY assignment functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_set1_RSA(EVP_PKEY *pkey,RSA *key);
+ int EVP_PKEY_set1_DSA(EVP_PKEY *pkey,DSA *key);
+ int EVP_PKEY_set1_DH(EVP_PKEY *pkey,DH *key);
+ int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey,EC_KEY *key);
+
+ RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
+ DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
+ DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
+ EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
+
+ int EVP_PKEY_assign_RSA(EVP_PKEY *pkey,RSA *key);
+ int EVP_PKEY_assign_DSA(EVP_PKEY *pkey,DSA *key);
+ int EVP_PKEY_assign_DH(EVP_PKEY *pkey,DH *key);
+ int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey,EC_KEY *key);
+
+ int EVP_PKEY_type(int type);
+
+=head1 DESCRIPTION
+
+EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
+EVP_PKEY_set1_EC_KEY() set the key referenced by B<pkey> to B<key>.
+
+EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
+EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or
+B<NULL> if the key is not of the correct type.
+
+EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
+and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key>
+however these use the supplied B<key> internally and so B<key>
+will be freed when the parent B<pkey> is freed.
+
+EVP_PKEY_type() returns the type of key corresponding to the value
+B<type>. The type of a key can be obtained with
+EVP_PKEY_type(pkey->type). The return value will be EVP_PKEY_RSA,
+EVP_PKEY_DSA, EVP_PKEY_DH or EVP_PKEY_EC for the corresponding
+key types or NID_undef if the key type is unassigned.
+
+=head1 NOTES
+
+In accordance with the OpenSSL naming convention the key obtained
+from or assigned to the B<pkey> using the B<1> functions must be
+freed as well as B<pkey>.
+
+EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
+EVP_PKEY_assign_EC_KEY() are implemented as macros.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
+EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure.
+
+EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
+EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if
+an error occurred.
+
+EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
+and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/EVP_SealInit.pod b/openssl/doc/crypto/EVP_SealInit.pod
new file mode 100644
index 000000000..7d793e19e
--- /dev/null
+++ b/openssl/doc/crypto/EVP_SealInit.pod
@@ -0,0 +1,85 @@
+=pod
+
+=head1 NAME
+
+EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ unsigned char **ek, int *ekl, unsigned char *iv,
+ EVP_PKEY **pubk, int npubk);
+ int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl, unsigned char *in, int inl);
+ int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl);
+
+=head1 DESCRIPTION
+
+The EVP envelope routines are a high level interface to envelope
+encryption. They generate a random key and IV (if required) then
+"envelope" it by using public key encryption. Data can then be
+encrypted using this key.
+
+EVP_SealInit() initializes a cipher context B<ctx> for encryption
+with cipher B<type> using a random secret key and IV. B<type> is normally
+supplied by a function such as EVP_des_cbc(). The secret key is encrypted
+using one or more public keys, this allows the same encrypted data to be
+decrypted using any of the corresponding private keys. B<ek> is an array of
+buffers where the public key encrypted secret key will be written, each buffer
+must contain enough room for the corresponding encrypted key: that is
+B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual
+size of each encrypted secret key is written to the array B<ekl>. B<pubk> is
+an array of B<npubk> public keys.
+
+The B<iv> parameter is a buffer where the generated IV is written to. It must
+contain enough room for the corresponding cipher's IV, as determined by (for
+example) EVP_CIPHER_iv_length(type).
+
+If the cipher does not require an IV then the B<iv> parameter is ignored
+and can be B<NULL>.
+
+EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties
+as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as
+documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual
+page.
+
+=head1 RETURN VALUES
+
+EVP_SealInit() returns 0 on error or B<npubk> if successful.
+
+EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for
+failure.
+
+=head1 NOTES
+
+Because a random secret key is generated the random number generator
+must be seeded before calling EVP_SealInit().
+
+The public key must be RSA because it is the only OpenSSL public key
+algorithm that supports key transport.
+
+Envelope encryption is the usual method of using public key encryption
+on large amounts of data, this is because public key encryption is slow
+but symmetric encryption is fast. So symmetric encryption is used for
+bulk encryption and the small random symmetric key used is transferred
+using public key encryption.
+
+It is possible to call EVP_SealInit() twice in the same way as
+EVP_EncryptInit(). The first call should have B<npubk> set to 0
+and (after setting any cipher parameters) it should be called again
+with B<type> set to NULL.
+
+=head1 SEE ALSO
+
+L<evp(3)|evp(3)>, L<rand(3)|rand(3)>,
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
+L<EVP_OpenInit(3)|EVP_OpenInit(3)>
+
+=head1 HISTORY
+
+EVP_SealFinal() did not return a value before OpenSSL 0.9.7.
+
+=cut
diff --git a/openssl/doc/crypto/EVP_SignInit.pod b/openssl/doc/crypto/EVP_SignInit.pod
new file mode 100644
index 000000000..b6e62ce7f
--- /dev/null
+++ b/openssl/doc/crypto/EVP_SignInit.pod
@@ -0,0 +1,95 @@
+=pod
+
+=head1 NAME
+
+EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
+ int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
+ int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey);
+
+ void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
+
+ int EVP_PKEY_size(EVP_PKEY *pkey);
+
+=head1 DESCRIPTION
+
+The EVP signature routines are a high level interface to digital
+signatures.
+
+EVP_SignInit_ex() sets up signing context B<ctx> to use digest
+B<type> from ENGINE B<impl>. B<ctx> must be initialized with
+EVP_MD_CTX_init() before calling this function.
+
+EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the
+signature context B<ctx>. This function can be called several times on the
+same B<ctx> to include additional data.
+
+EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and
+places the signature in B<sig>. The number of bytes of data written (i.e. the
+length of the signature) will be written to the integer at B<s>, at most
+EVP_PKEY_size(pkey) bytes will be written.
+
+EVP_SignInit() initializes a signing context B<ctx> to use the default
+implementation of digest B<type>.
+
+EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual
+signature returned by EVP_SignFinal() may be smaller.
+
+=head1 RETURN VALUES
+
+EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1
+for success and 0 for failure.
+
+EVP_PKEY_size() returns the maximum size of a signature in bytes.
+
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 NOTES
+
+The B<EVP> interface to digital signatures should almost always be used in
+preference to the low level interfaces. This is because the code then becomes
+transparent to the algorithm used and much more flexible.
+
+Due to the link between message digests and public key algorithms the correct
+digest algorithm must be used with the correct public key type. A list of
+algorithms and associated public key algorithms appears in
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>.
+
+When signing with DSA private keys the random number generator must be seeded
+or the operation will fail. The random number generator does not need to be
+seeded for RSA signatures.
+
+The call to EVP_SignFinal() internally finalizes a copy of the digest context.
+This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called
+later to digest and sign additional data.
+
+Since only a copy of the digest context is ever finalized the context must
+be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
+will occur.
+
+=head1 BUGS
+
+Older versions of this documentation wrongly stated that calls to
+EVP_SignUpdate() could not be made after calling EVP_SignFinal().
+
+=head1 SEE ALSO
+
+L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>,
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>,
+L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
+L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
+L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
+
+=head1 HISTORY
+
+EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are
+available in all versions of SSLeay and OpenSSL.
+
+EVP_SignInit_ex() was added in OpenSSL 0.9.7.
+
+=cut
diff --git a/openssl/doc/crypto/EVP_VerifyInit.pod b/openssl/doc/crypto/EVP_VerifyInit.pod
new file mode 100644
index 000000000..b6afaedee
--- /dev/null
+++ b/openssl/doc/crypto/EVP_VerifyInit.pod
@@ -0,0 +1,86 @@
+=pod
+
+=head1 NAME
+
+EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
+ int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
+ int EVP_VerifyFinal(EVP_MD_CTX *ctx,unsigned char *sigbuf, unsigned int siglen,EVP_PKEY *pkey);
+
+ int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);
+
+=head1 DESCRIPTION
+
+The EVP signature verification routines are a high level interface to digital
+signatures.
+
+EVP_VerifyInit_ex() sets up verification context B<ctx> to use digest
+B<type> from ENGINE B<impl>. B<ctx> must be initialized by calling
+EVP_MD_CTX_init() before calling this function.
+
+EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
+verification context B<ctx>. This function can be called several times on the
+same B<ctx> to include additional data.
+
+EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey>
+and against the B<siglen> bytes at B<sigbuf>.
+
+EVP_VerifyInit() initializes verification context B<ctx> to use the default
+implementation of digest B<type>.
+
+=head1 RETURN VALUES
+
+EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for
+failure.
+
+EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if some
+other error occurred.
+
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 NOTES
+
+The B<EVP> interface to digital signatures should almost always be used in
+preference to the low level interfaces. This is because the code then becomes
+transparent to the algorithm used and much more flexible.
+
+Due to the link between message digests and public key algorithms the correct
+digest algorithm must be used with the correct public key type. A list of
+algorithms and associated public key algorithms appears in
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>.
+
+The call to EVP_VerifyFinal() internally finalizes a copy of the digest context.
+This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can be called
+later to digest and verify additional data.
+
+Since only a copy of the digest context is ever finalized the context must
+be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
+will occur.
+
+=head1 BUGS
+
+Older versions of this documentation wrongly stated that calls to
+EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal().
+
+=head1 SEE ALSO
+
+L<evp(3)|evp(3)>,
+L<EVP_SignInit(3)|EVP_SignInit(3)>,
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>,
+L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
+L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
+L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
+
+=head1 HISTORY
+
+EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are
+available in all versions of SSLeay and OpenSSL.
+
+EVP_VerifyInit_ex() was added in OpenSSL 0.9.7
+
+=cut
diff --git a/openssl/doc/crypto/OBJ_nid2obj.pod b/openssl/doc/crypto/OBJ_nid2obj.pod
new file mode 100644
index 000000000..7dcc07923
--- /dev/null
+++ b/openssl/doc/crypto/OBJ_nid2obj.pod
@@ -0,0 +1,149 @@
+=pod
+
+=head1 NAME
+
+OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid,
+OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup - ASN1 object utility
+functions
+
+=head1 SYNOPSIS
+
+ ASN1_OBJECT * OBJ_nid2obj(int n);
+ const char * OBJ_nid2ln(int n);
+ const char * OBJ_nid2sn(int n);
+
+ int OBJ_obj2nid(const ASN1_OBJECT *o);
+ int OBJ_ln2nid(const char *ln);
+ int OBJ_sn2nid(const char *sn);
+
+ int OBJ_txt2nid(const char *s);
+
+ ASN1_OBJECT * OBJ_txt2obj(const char *s, int no_name);
+ int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name);
+
+ int OBJ_cmp(const ASN1_OBJECT *a,const ASN1_OBJECT *b);
+ ASN1_OBJECT * OBJ_dup(const ASN1_OBJECT *o);
+
+ int OBJ_create(const char *oid,const char *sn,const char *ln);
+ void OBJ_cleanup(void);
+
+=head1 DESCRIPTION
+
+The ASN1 object utility functions process ASN1_OBJECT structures which are
+a representation of the ASN1 OBJECT IDENTIFIER (OID) type.
+
+OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to
+an ASN1_OBJECT structure, its long name and its short name respectively,
+or B<NULL> is an error occurred.
+
+OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID
+for the object B<o>, the long name <ln> or the short name <sn> respectively
+or NID_undef if an error occurred.
+
+OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be
+a long name, a short name or the numerical respresentation of an object.
+
+OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure.
+If B<no_name> is 0 then long names and short names will be interpreted
+as well as numerical forms. If B<no_name> is 1 only the numerical form
+is acceptable.
+
+OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation.
+The representation is written as a null terminated string to B<buf>
+at most B<buf_len> bytes are written, truncating the result if necessary.
+The total amount of space required is returned. If B<no_name> is 0 then
+if the object has a long or short name then that will be used, otherwise
+the numerical form will be used. If B<no_name> is 1 then the numerical
+form will always be used.
+
+OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned.
+
+OBJ_dup() returns a copy of B<o>.
+
+OBJ_create() adds a new object to the internal table. B<oid> is the
+numerical form of the object, B<sn> the short name and B<ln> the
+long name. A new NID is returned for the created object.
+
+OBJ_cleanup() cleans up OpenSSLs internal object table: this should
+be called before an application exits if any new objects were added
+using OBJ_create().
+
+=head1 NOTES
+
+Objects in OpenSSL can have a short name, a long name and a numerical
+identifier (NID) associated with them. A standard set of objects is
+represented in an internal table. The appropriate values are defined
+in the header file B<objects.h>.
+
+For example the OID for commonName has the following definitions:
+
+ #define SN_commonName "CN"
+ #define LN_commonName "commonName"
+ #define NID_commonName 13
+
+New objects can be added by calling OBJ_create().
+
+Table objects have certain advantages over other objects: for example
+their NIDs can be used in a C language switch statement. They are
+also static constant structures which are shared: that is there
+is only a single constant structure for each table object.
+
+Objects which are not in the table have the NID value NID_undef.
+
+Objects do not need to be in the internal tables to be processed,
+the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical
+form of an OID.
+
+=head1 EXAMPLES
+
+Create an object for B<commonName>:
+
+ ASN1_OBJECT *o;
+ o = OBJ_nid2obj(NID_commonName);
+
+Check if an object is B<commonName>
+
+ if (OBJ_obj2nid(obj) == NID_commonName)
+ /* Do something */
+
+Create a new NID and initialize an object from it:
+
+ int new_nid;
+ ASN1_OBJECT *obj;
+ new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
+
+ obj = OBJ_nid2obj(new_nid);
+
+Create a new object directly:
+
+ obj = OBJ_txt2obj("1.2.3.4", 1);
+
+=head1 BUGS
+
+OBJ_obj2txt() is awkward and messy to use: it doesn't follow the
+convention of other OpenSSL functions where the buffer can be set
+to B<NULL> to determine the amount of data that should be written.
+Instead B<buf> must point to a valid buffer and B<buf_len> should
+be set to a positive value. A buffer length of 80 should be more
+than enough to handle any OID encountered in practice.
+
+=head1 RETURN VALUES
+
+OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
+error occurred.
+
+OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
+on error.
+
+OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
+a NID or B<NID_undef> on error.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/OPENSSL_Applink.pod b/openssl/doc/crypto/OPENSSL_Applink.pod
new file mode 100644
index 000000000..e54de12cc
--- /dev/null
+++ b/openssl/doc/crypto/OPENSSL_Applink.pod
@@ -0,0 +1,21 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_Applink - glue between OpenSSL BIO and Win32 compiler run-time
+
+=head1 SYNOPSIS
+
+ __declspec(dllexport) void **OPENSSL_Applink();
+
+=head1 DESCRIPTION
+
+OPENSSL_Applink is application-side interface which provides a glue
+between OpenSSL BIO layer and Win32 compiler run-time environment.
+Even though it appears at application side, it's essentially OpenSSL
+private interface. For this reason application developers are not
+expected to implement it, but to compile provided module with
+compiler of their choice and link it into the target application.
+The referred module is available as <openssl>/ms/applink.c.
+
+=cut
diff --git a/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod b/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod
new file mode 100644
index 000000000..c39ac35e7
--- /dev/null
+++ b/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod
@@ -0,0 +1,101 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_VERSION_NUMBER, SSLeay, SSLeay_version - get OpenSSL version number
+
+=head1 SYNOPSIS
+
+ #include <openssl/opensslv.h>
+ #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL
+
+ #include <openssl/crypto.h>
+ long SSLeay(void);
+ const char *SSLeay_version(int t);
+
+=head1 DESCRIPTION
+
+OPENSSL_VERSION_NUMBER is a numeric release version identifier:
+
+ MMNNFFPPS: major minor fix patch status
+
+The status nibble has one of the values 0 for development, 1 to e for betas
+1 to 14, and f for release.
+
+for example
+
+ 0x000906000 == 0.9.6 dev
+ 0x000906023 == 0.9.6b beta 3
+ 0x00090605f == 0.9.6e release
+
+Versions prior to 0.9.3 have identifiers E<lt> 0x0930.
+Versions between 0.9.3 and 0.9.5 had a version identifier with this
+interpretation:
+
+ MMNNFFRBB major minor fix final beta/patch
+
+for example
+
+ 0x000904100 == 0.9.4 release
+ 0x000905000 == 0.9.5 dev
+
+Version 0.9.5a had an interim interpretation that is like the current one,
+except the patch level got the highest bit set, to keep continuity. The
+number was therefore 0x0090581f.
+
+
+For backward compatibility, SSLEAY_VERSION_NUMBER is also defined.
+
+SSLeay() returns this number. The return value can be compared to the
+macro to make sure that the correct version of the library has been
+loaded, especially when using DLLs on Windows systems.
+
+SSLeay_version() returns different strings depending on B<t>:
+
+=over 4
+
+=item SSLEAY_VERSION
+
+The text variant of the version number and the release date. For example,
+"OpenSSL 0.9.5a 1 Apr 2000".
+
+=item SSLEAY_CFLAGS
+
+The compiler flags set for the compilation process in the form
+"compiler: ..." if available or "compiler: information not available"
+otherwise.
+
+=item SSLEAY_BUILT_ON
+
+The date of the build process in the form "built on: ..." if available
+or "built on: date not available" otherwise.
+
+=item SSLEAY_PLATFORM
+
+The "Configure" target of the library build in the form "platform: ..."
+if available or "platform: information not available" otherwise.
+
+=item SSLEAY_DIR
+
+The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "...""
+if available or "OPENSSLDIR: N/A" otherwise.
+
+=back
+
+For an unknown B<t>, the text "not available" is returned.
+
+=head1 RETURN VALUE
+
+The version number.
+
+=head1 SEE ALSO
+
+L<crypto(3)|crypto(3)>
+
+=head1 HISTORY
+
+SSLeay() and SSLEAY_VERSION_NUMBER are available in all versions of SSLeay and OpenSSL.
+OPENSSL_VERSION_NUMBER is available in all versions of OpenSSL.
+B<SSLEAY_DIR> was added in OpenSSL 0.9.7.
+
+=cut
diff --git a/openssl/doc/crypto/OPENSSL_config.pod b/openssl/doc/crypto/OPENSSL_config.pod
new file mode 100644
index 000000000..e7bba2aac
--- /dev/null
+++ b/openssl/doc/crypto/OPENSSL_config.pod
@@ -0,0 +1,82 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/conf.h>
+
+ void OPENSSL_config(const char *config_name);
+ void OPENSSL_no_config(void);
+
+=head1 DESCRIPTION
+
+OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf>
+configuration file name using B<config_name>. If B<config_name> is NULL then
+the default name B<openssl_conf> will be used. Any errors are ignored. Further
+calls to OPENSSL_config() will have no effect. The configuration file format
+is documented in the L<conf(5)|conf(5)> manual page.
+
+OPENSSL_no_config() disables configuration. If called before OPENSSL_config()
+no configuration takes place.
+
+=head1 NOTES
+
+It is B<strongly> recommended that B<all> new applications call OPENSSL_config()
+or the more sophisticated functions such as CONF_modules_load() during
+initialization (that is before starting any threads). By doing this
+an application does not need to keep track of all configuration options
+and some new functionality can be supported automatically.
+
+It is also possible to automatically call OPENSSL_config() when an application
+calls OPENSSL_add_all_algorithms() by compiling an application with the
+preprocessor symbol B<OPENSSL_LOAD_CONF> #define'd. In this way configuration
+can be added without source changes.
+
+The environment variable B<OPENSSL_CONF> can be set to specify the location
+of the configuration file.
+
+Currently ASN1 OBJECTs and ENGINE configuration can be performed future
+versions of OpenSSL will add new configuration options.
+
+There are several reasons why calling the OpenSSL configuration routines is
+advisable. For example new ENGINE functionality was added to OpenSSL 0.9.7.
+In OpenSSL 0.9.7 control functions can be supported by ENGINEs, this can be
+used (among other things) to load dynamic ENGINEs from shared libraries (DSOs).
+However very few applications currently support the control interface and so
+very few can load and use dynamic ENGINEs. Equally in future more sophisticated
+ENGINEs will require certain control operations to customize them. If an
+application calls OPENSSL_config() it doesn't need to know or care about
+ENGINE control operations because they can be performed by editing a
+configuration file.
+
+Applications should free up configuration at application closedown by calling
+CONF_modules_free().
+
+=head1 RESTRICTIONS
+
+The OPENSSL_config() function is designed to be a very simple "call it and
+forget it" function. As a result its behaviour is somewhat limited. It ignores
+all errors silently and it can only load from the standard configuration file
+location for example.
+
+It is however B<much> better than nothing. Applications which need finer
+control over their configuration functionality should use the configuration
+functions such as CONF_load_modules() directly.
+
+=head1 RETURN VALUES
+
+Neither OPENSSL_config() nor OPENSSL_no_config() return a value.
+
+=head1 SEE ALSO
+
+L<conf(5)|conf(5)>, L<CONF_load_modules_file(3)|CONF_load_modules_file(3)>,
+L<CONF_modules_free(3),CONF_modules_free(3)>
+
+=head1 HISTORY
+
+OPENSSL_config() and OPENSSL_no_config() first appeared in OpenSSL 0.9.7
+
+=cut
diff --git a/openssl/doc/crypto/OPENSSL_ia32cap.pod b/openssl/doc/crypto/OPENSSL_ia32cap.pod
new file mode 100644
index 000000000..2e659d34a
--- /dev/null
+++ b/openssl/doc/crypto/OPENSSL_ia32cap.pod
@@ -0,0 +1,43 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_ia32cap - finding the IA-32 processor capabilities
+
+=head1 SYNOPSIS
+
+ unsigned long *OPENSSL_ia32cap_loc(void);
+ #define OPENSSL_ia32cap (*(OPENSSL_ia32cap_loc()))
+
+=head1 DESCRIPTION
+
+Value returned by OPENSSL_ia32cap_loc() is address of a variable
+containing IA-32 processor capabilities bit vector as it appears in EDX
+register after executing CPUID instruction with EAX=1 input value (see
+Intel Application Note #241618). Naturally it's meaningful on IA-32[E]
+platforms only. The variable is normally set up automatically upon
+toolkit initialization, but can be manipulated afterwards to modify
+crypto library behaviour. For the moment of this writing six bits are
+significant, namely:
+
+1. bit #28 denoting Hyperthreading, which is used to distiguish
+ cores with shared cache;
+2. bit #26 denoting SSE2 support;
+3. bit #25 denoting SSE support;
+4. bit #23 denoting MMX support;
+5. bit #20, reserved by Intel, is used to choose between RC4 code
+ pathes;
+6. bit #4 denoting presence of Time-Stamp Counter.
+
+For example, clearing bit #26 at run-time disables high-performance
+SSE2 code present in the crypto library. You might have to do this if
+target OpenSSL application is executed on SSE2 capable CPU, but under
+control of OS which does not support SSE2 extentions. Even though you
+can manipulate the value programmatically, you most likely will find it
+more appropriate to set up an environment variable with the same name
+prior starting target application, e.g. on Intel P4 processor 'env
+OPENSSL_ia32cap=0x12900010 apps/openssl', to achieve same effect
+without modifying the application source code. Alternatively you can
+reconfigure the toolkit with no-sse2 option and recompile.
+
+=cut
diff --git a/openssl/doc/crypto/OPENSSL_load_builtin_modules.pod b/openssl/doc/crypto/OPENSSL_load_builtin_modules.pod
new file mode 100644
index 000000000..f14dfaf00
--- /dev/null
+++ b/openssl/doc/crypto/OPENSSL_load_builtin_modules.pod
@@ -0,0 +1,51 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_load_builtin_modules - add standard configuration modules
+
+=head1 SYNOPSIS
+
+ #include <openssl/conf.h>
+
+ void OPENSSL_load_builtin_modules(void);
+ void ASN1_add_oid_module(void);
+ ENGINE_add_conf_module();
+
+=head1 DESCRIPTION
+
+The function OPENSSL_load_builtin_modules() adds all the standard OpenSSL
+configuration modules to the internal list. They can then be used by the
+OpenSSL configuration code.
+
+ASN1_add_oid_module() adds just the ASN1 OBJECT module.
+
+ENGINE_add_conf_module() adds just the ENGINE configuration module.
+
+=head1 NOTES
+
+If the simple configuration function OPENSSL_config() is called then
+OPENSSL_load_builtin_modules() is called automatically.
+
+Applications which use the configuration functions directly will need to
+call OPENSSL_load_builtin_modules() themselves I<before> any other
+configuration code.
+
+Applications should call OPENSSL_load_builtin_modules() to load all
+configuration modules instead of adding modules selectively: otherwise
+functionality may be missing from the application if an when new
+modules are added.
+
+=head1 RETURN VALUE
+
+None of the functions return a value.
+
+=head1 SEE ALSO
+
+L<conf(3)|conf(3)>, L<OPENSSL_config(3)|OPENSSL_config(3)>
+
+=head1 HISTORY
+
+These functions first appeared in OpenSSL 0.9.7.
+
+=cut
diff --git a/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod b/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod
new file mode 100644
index 000000000..e63411b5b
--- /dev/null
+++ b/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod
@@ -0,0 +1,66 @@
+=pod
+
+=head1 NAME
+
+OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests -
+add algorithms to internal table
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ void OpenSSL_add_all_algorithms(void);
+ void OpenSSL_add_all_ciphers(void);
+ void OpenSSL_add_all_digests(void);
+
+ void EVP_cleanup(void);
+
+=head1 DESCRIPTION
+
+OpenSSL keeps an internal table of digest algorithms and ciphers. It uses
+this table to lookup ciphers via functions such as EVP_get_cipher_byname().
+
+OpenSSL_add_all_digests() adds all digest algorithms to the table.
+
+OpenSSL_add_all_algorithms() adds all algorithms to the table (digests and
+ciphers).
+
+OpenSSL_add_all_ciphers() adds all encryption algorithms to the table including
+password based encryption algorithms.
+
+EVP_cleanup() removes all ciphers and digests from the table.
+
+=head1 RETURN VALUES
+
+None of the functions return a value.
+
+=head1 NOTES
+
+A typical application will call OpenSSL_add_all_algorithms() initially and
+EVP_cleanup() before exiting.
+
+An application does not need to add algorithms to use them explicitly, for example
+by EVP_sha1(). It just needs to add them if it (or any of the functions it calls)
+needs to lookup algorithms.
+
+The cipher and digest lookup functions are used in many parts of the library. If
+the table is not initialized several functions will misbehave and complain they
+cannot find algorithms. This includes the PEM, PKCS#12, SSL and S/MIME libraries.
+This is a common query in the OpenSSL mailing lists.
+
+Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a
+statically linked executable can be quite large. If this is important it is possible
+to just add the required ciphers and digests.
+
+=head1 BUGS
+
+Although the functions do not return error codes it is possible for them to fail.
+This will only happen as a result of a memory allocation failure so this is not
+too much of a problem in practice.
+
+=head1 SEE ALSO
+
+L<evp(3)|evp(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>,
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>
+
+=cut
diff --git a/openssl/doc/crypto/PKCS12_create.pod b/openssl/doc/crypto/PKCS12_create.pod
new file mode 100644
index 000000000..de7cab2bd
--- /dev/null
+++ b/openssl/doc/crypto/PKCS12_create.pod
@@ -0,0 +1,75 @@
+=pod
+
+=head1 NAME
+
+PKCS12_create - create a PKCS#12 structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs12.h>
+
+ PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert, STACK_OF(X509) *ca,
+ int nid_key, int nid_cert, int iter, int mac_iter, int keytype);
+
+=head1 DESCRIPTION
+
+PKCS12_create() creates a PKCS#12 structure.
+
+B<pass> is the passphrase to use. B<name> is the B<friendlyName> to use for
+the supplied certifictate and key. B<pkey> is the private key to include in
+the structure and B<cert> its corresponding certificates. B<ca>, if not B<NULL>
+is an optional set of certificates to also include in the structure.
+
+B<nid_key> and B<nid_cert> are the encryption algorithms that should be used
+for the key and certificate respectively. B<iter> is the encryption algorithm
+iteration count to use and B<mac_iter> is the MAC iteration count to use.
+B<keytype> is the type of key.
+
+=head1 NOTES
+
+The parameters B<nid_key>, B<nid_cert>, B<iter>, B<mac_iter> and B<keytype>
+can all be set to zero and sensible defaults will be used.
+
+These defaults are: 40 bit RC2 encryption for certificates, triple DES
+encryption for private keys, a key iteration count of PKCS12_DEFAULT_ITER
+(currently 2048) and a MAC iteration count of 1.
+
+The default MAC iteration count is 1 in order to retain compatibility with
+old software which did not interpret MAC iteration counts. If such compatibility
+is not required then B<mac_iter> should be set to PKCS12_DEFAULT_ITER.
+
+B<keytype> adds a flag to the store private key. This is a non standard extension
+that is only currently interpreted by MSIE. If set to zero the flag is omitted,
+if set to B<KEY_SIG> the key can be used for signing only, if set to B<KEY_EX>
+it can be used for signing and encryption. This option was useful for old
+export grade software which could use signing only keys of arbitrary size but
+had restrictions on the permissible sizes of keys which could be used for
+encryption.
+
+=head1 NEW FUNCTIONALITY IN OPENSSL 0.9.8
+
+Some additional functionality was added to PKCS12_create() in OpenSSL
+0.9.8. These extensions are detailed below.
+
+If a certificate contains an B<alias> or B<keyid> then this will be
+used for the corresponding B<friendlyName> or B<localKeyID> in the
+PKCS12 structure.
+
+Either B<pkey>, B<cert> or both can be B<NULL> to indicate that no key or
+certficate is required. In previous versions both had to be present or
+a fatal error is returned.
+
+B<nid_key> or B<nid_cert> can be set to -1 indicating that no encryption
+should be used.
+
+B<mac_iter> can be set to -1 and the MAC will then be omitted entirely.
+
+=head1 SEE ALSO
+
+L<d2i_PKCS12(3)|d2i_PKCS12(3)>
+
+=head1 HISTORY
+
+PKCS12_create was added in OpenSSL 0.9.3
+
+=cut
diff --git a/openssl/doc/crypto/PKCS12_parse.pod b/openssl/doc/crypto/PKCS12_parse.pod
new file mode 100644
index 000000000..51344f883
--- /dev/null
+++ b/openssl/doc/crypto/PKCS12_parse.pod
@@ -0,0 +1,50 @@
+=pod
+
+=head1 NAME
+
+PKCS12_parse - parse a PKCS#12 structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs12.h>
+
+int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, STACK_OF(X509) **ca);
+
+=head1 DESCRIPTION
+
+PKCS12_parse() parses a PKCS12 structure.
+
+B<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use.
+If successful the private key will be written to B<*pkey>, the corresponding
+certificate to B<*cert> and any additional certificates to B<*ca>.
+
+=head1 NOTES
+
+The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL>
+in which case additional certificates will be discarded. B<*ca> can also
+be a valid STACK in which case additional certificates are appended to
+B<*ca>. If B<*ca> is B<NULL> a new STACK will be allocated.
+
+The B<friendlyName> and B<localKeyID> attributes (if present) on each certificate
+will be stored in the B<alias> and B<keyid> attributes of the B<X509> structure.
+
+=head1 BUGS
+
+Only a single private key and corresponding certificate is returned by this function.
+More complex PKCS#12 files with multiple private keys will only return the first
+match.
+
+Only B<friendlyName> and B<localKeyID> attributes are currently stored in certificates.
+Other attributes are discarded.
+
+Attributes currently cannot be store in the private key B<EVP_PKEY> structure.
+
+=head1 SEE ALSO
+
+L<d2i_PKCS12(3)|d2i_PKCS12(3)>
+
+=head1 HISTORY
+
+PKCS12_parse was added in OpenSSL 0.9.3
+
+=cut
diff --git a/openssl/doc/crypto/PKCS7_decrypt.pod b/openssl/doc/crypto/PKCS7_decrypt.pod
new file mode 100644
index 000000000..b0ca067b8
--- /dev/null
+++ b/openssl/doc/crypto/PKCS7_decrypt.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure
+
+=head1 SYNOPSIS
+
+int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+PKCS7_decrypt() extracts and decrypts the content from a PKCS#7 envelopedData
+structure. B<pkey> is the private key of the recipient, B<cert> is the
+recipients certificate, B<data> is a BIO to write the content to and
+B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+OpenSSL_add_all_algorithms() (or equivalent) should be called before using this
+function or errors about unknown algorithms will occur.
+
+Although the recipients certificate is not needed to decrypt the data it is needed
+to locate the appropriate (of possible several) recipients in the PKCS#7 structure.
+
+The following flags can be passed in the B<flags> parameter.
+
+If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted
+from the content. If the content is not of type B<text/plain> then an error is
+returned.
+
+=head1 RETURN VALUES
+
+PKCS7_decrypt() returns either 1 for success or 0 for failure.
+The error can be obtained from ERR_get_error(3)
+
+=head1 BUGS
+
+PKCS7_decrypt() must be passed the correct recipient key and certificate. It would
+be better if it could look up the correct key and certificate from a database.
+
+The lack of single pass processing and need to hold all data in memory as
+mentioned in PKCS7_sign() also applies to PKCS7_verify().
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)>
+
+=head1 HISTORY
+
+PKCS7_decrypt() was added to OpenSSL 0.9.5
+
+=cut
diff --git a/openssl/doc/crypto/PKCS7_encrypt.pod b/openssl/doc/crypto/PKCS7_encrypt.pod
new file mode 100644
index 000000000..1a507b22a
--- /dev/null
+++ b/openssl/doc/crypto/PKCS7_encrypt.pod
@@ -0,0 +1,65 @@
+=pod
+
+=head1 NAME
+
+PKCS7_encrypt - create a PKCS#7 envelopedData structure
+
+=head1 SYNOPSIS
+
+PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags);
+
+=head1 DESCRIPTION
+
+PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B<certs>
+is a list of recipient certificates. B<in> is the content to be encrypted.
+B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+Only RSA keys are supported in PKCS#7 and envelopedData so the recipient certificates
+supplied to this function must all contain RSA public keys, though they do not have to
+be signed using the RSA algorithm.
+
+EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use because
+most clients will support it.
+
+Some old "export grade" clients may only support weak encryption using 40 or 64 bit
+RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc() respectively.
+
+The algorithm passed in the B<cipher> parameter must support ASN1 encoding of its
+parameters.
+
+Many browsers implement a "sign and encrypt" option which is simply an S/MIME
+envelopedData containing an S/MIME signed message. This can be readily produced
+by storing the S/MIME signed message in a memory BIO and passing it to
+PKCS7_encrypt().
+
+The following flags can be passed in the B<flags> parameter.
+
+If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended
+to the data.
+
+Normally the supplied content is translated into MIME canonical format (as required
+by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation occurs. This
+option should be used if the supplied data is in binary format otherwise the translation
+will corrupt it. If B<PKCS7_BINARY> is set then B<PKCS7_TEXT> is ignored.
+
+=head1 RETURN VALUES
+
+PKCS7_encrypt() returns either a valid PKCS7 structure or NULL if an error occurred.
+The error can be obtained from ERR_get_error(3).
+
+=head1 BUGS
+
+The lack of single pass processing and need to hold all data in memory as
+mentioned in PKCS7_sign() also applies to PKCS7_verify().
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>
+
+=head1 HISTORY
+
+PKCS7_decrypt() was added to OpenSSL 0.9.5
+
+=cut
diff --git a/openssl/doc/crypto/PKCS7_sign.pod b/openssl/doc/crypto/PKCS7_sign.pod
new file mode 100644
index 000000000..ffd0c734b
--- /dev/null
+++ b/openssl/doc/crypto/PKCS7_sign.pod
@@ -0,0 +1,101 @@
+=pod
+
+=head1 NAME
+
+PKCS7_sign - create a PKCS#7 signedData structure
+
+=head1 SYNOPSIS
+
+PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert>
+is the certificate to sign with, B<pkey> is the corresponsding private key.
+B<certs> is an optional additional set of certificates to include in the
+PKCS#7 structure (for example any intermediate CAs in the chain).
+
+The data to be signed is read from BIO B<data>.
+
+B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+Any of the following flags (ored together) can be passed in the B<flags> parameter.
+
+Many S/MIME clients expect the signed content to include valid MIME headers. If
+the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended
+to the data.
+
+If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
+PKCS7 structure, the signer's certificate must still be supplied in the B<signcert>
+parameter though. This can reduce the size of the signature if the signers certificate
+can be obtained by other means: for example a previously signed message.
+
+The data being signed is included in the PKCS7 structure, unless B<PKCS7_DETACHED>
+is set in which case it is omitted. This is used for PKCS7 detached signatures
+which are used in S/MIME plaintext signed messages for example.
+
+Normally the supplied content is translated into MIME canonical format (as required
+by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation occurs. This
+option should be used if the supplied data is in binary format otherwise the translation
+will corrupt it.
+
+The signedData structure includes several PKCS#7 autenticatedAttributes including
+the signing time, the PKCS#7 content type and the supported list of ciphers in
+an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no authenticatedAttributes
+will be used. If B<PKCS7_NOSMIMECAP> is set then just the SMIMECapabilities are
+omitted.
+
+If present the SMIMECapabilities attribute indicates support for the following
+algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any
+of these algorithms is disabled then it will not be included.
+
+If the flags B<PKCS7_PARTSIGN> is set then the returned B<PKCS7> structure
+is just initialized ready to perform the signing operation. The signing
+is however B<not> performed and the data to be signed is not read from
+the B<data> parameter. Signing is deferred until after the data has been
+written. In this way data can be signed in a single pass. Currently the
+flag B<PKCS7_DETACHED> B<must> also be set.
+
+=head1 NOTES
+
+Currently the flag B<PKCS7_PARTSIGN> is only supported for detached
+data. If this flag is set the returned B<PKCS7> structure is B<not>
+complete and outputting its contents via a function that does not
+properly finalize the B<PKCS7> structure will give unpredictable
+results.
+
+At present only the SMIME_write_PKCS7() function properly finalizes the
+structure.
+
+=head1 BUGS
+
+PKCS7_sign() is somewhat limited. It does not support multiple signers, some
+advanced attributes such as counter signatures are not supported.
+
+The SHA1 digest algorithm is currently always used.
+
+When the signed data is not detached it will be stored in memory within the
+B<PKCS7> structure. This effectively limits the size of messages which can be
+signed due to memory restraints. There should be a way to sign data without
+having to hold it all in memory, this would however require fairly major
+revisions of the OpenSSL ASN1 code.
+
+
+=head1 RETURN VALUES
+
+PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error occurred.
+The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)>
+
+=head1 HISTORY
+
+PKCS7_sign() was added to OpenSSL 0.9.5
+
+The B<PKCS7_PARTSIGN> flag was added in OpenSSL 0.9.8
+
+=cut
diff --git a/openssl/doc/crypto/PKCS7_verify.pod b/openssl/doc/crypto/PKCS7_verify.pod
new file mode 100644
index 000000000..3490b5dc8
--- /dev/null
+++ b/openssl/doc/crypto/PKCS7_verify.pod
@@ -0,0 +1,116 @@
+=pod
+
+=head1 NAME
+
+PKCS7_verify - verify a PKCS#7 signedData structure
+
+=head1 SYNOPSIS
+
+int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags);
+
+STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags);
+
+=head1 DESCRIPTION
+
+PKCS7_verify() verifies a PKCS#7 signedData structure. B<p7> is the PKCS7
+structure to verify. B<certs> is a set of certificates in which to search for
+the signer's certificate. B<store> is a trusted certficate store (used for
+chain verification). B<indata> is the signed data if the content is not
+present in B<p7> (that is it is detached). The content is written to B<out>
+if it is not NULL.
+
+B<flags> is an optional set of flags, which can be used to modify the verify
+operation.
+
+PKCS7_get0_signers() retrieves the signer's certificates from B<p7>, it does
+B<not> check their validity or whether any signatures are valid. The B<certs>
+and B<flags> parameters have the same meanings as in PKCS7_verify().
+
+=head1 VERIFY PROCESS
+
+Normally the verify process proceeds as follows.
+
+Initially some sanity checks are performed on B<p7>. The type of B<p7> must
+be signedData. There must be at least one signature on the data and if
+the content is detached B<indata> cannot be B<NULL>.
+
+An attempt is made to locate all the signer's certificates, first looking in
+the B<certs> parameter (if it is not B<NULL>) and then looking in any certificates
+contained in the B<p7> structure itself. If any signer's certificates cannot be
+located the operation fails.
+
+Each signer's certificate is chain verified using the B<smimesign> purpose and
+the supplied trusted certificate store. Any internal certificates in the message
+are used as untrusted CAs. If any chain verify fails an error code is returned.
+
+Finally the signed content is read (and written to B<out> is it is not NULL) and
+the signature's checked.
+
+If all signature's verify correctly then the function is successful.
+
+Any of the following flags (ored together) can be passed in the B<flags> parameter
+to change the default verify behaviour. Only the flag B<PKCS7_NOINTERN> is
+meaningful to PKCS7_get0_signers().
+
+If B<PKCS7_NOINTERN> is set the certificates in the message itself are not
+searched when locating the signer's certificate. This means that all the signers
+certificates must be in the B<certs> parameter.
+
+If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted
+from the content. If the content is not of type B<text/plain> then an error is
+returned.
+
+If B<PKCS7_NOVERIFY> is set the signer's certificates are not chain verified.
+
+If B<PKCS7_NOCHAIN> is set then the certificates contained in the message are
+not used as untrusted CAs. This means that the whole verify chain (apart from
+the signer's certificate) must be contained in the trusted store.
+
+If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked.
+
+=head1 NOTES
+
+One application of B<PKCS7_NOINTERN> is to only accept messages signed by
+a small number of certificates. The acceptable certificates would be passed
+in the B<certs> parameter. In this case if the signer is not one of the
+certificates supplied in B<certs> then the verify will fail because the
+signer cannot be found.
+
+Care should be taken when modifying the default verify behaviour, for example
+setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification
+and any signed message will be considered valid. This combination is however
+useful if one merely wishes to write the content to B<out> and its validity
+is not considered important.
+
+Chain verification should arguably be performed using the signing time rather
+than the current time. However since the signing time is supplied by the
+signer it cannot be trusted without additional evidence (such as a trusted
+timestamp).
+
+=head1 RETURN VALUES
+
+PKCS7_verify() returns 1 for a successful verification and zero or a negative
+value if an error occurs.
+
+PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred.
+
+The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 BUGS
+
+The trusted certificate store is not searched for the signers certificate,
+this is primarily due to the inadequacies of the current B<X509_STORE>
+functionality.
+
+The lack of single pass processing and need to hold all data in memory as
+mentioned in PKCS7_sign() also applies to PKCS7_verify().
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>
+
+=head1 HISTORY
+
+PKCS7_verify() was added to OpenSSL 0.9.5
+
+=cut
diff --git a/openssl/doc/crypto/RAND_add.pod b/openssl/doc/crypto/RAND_add.pod
new file mode 100644
index 000000000..67c66f3e0
--- /dev/null
+++ b/openssl/doc/crypto/RAND_add.pod
@@ -0,0 +1,77 @@
+=pod
+
+=head1 NAME
+
+RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add
+entropy to the PRNG
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ void RAND_seed(const void *buf, int num);
+
+ void RAND_add(const void *buf, int num, double entropy);
+
+ int RAND_status(void);
+
+ int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam);
+ void RAND_screen(void);
+
+=head1 DESCRIPTION
+
+RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. Thus,
+if the data at B<buf> are unpredictable to an adversary, this
+increases the uncertainty about the state and makes the PRNG output
+less predictable. Suitable input comes from user interaction (random
+key presses, mouse movements) and certain hardware events. The
+B<entropy> argument is (the lower bound of) an estimate of how much
+randomness is contained in B<buf>, measured in bytes. Details about
+sources of randomness and how to estimate their entropy can be found
+in the literature, e.g. RFC 1750.
+
+RAND_add() may be called with sensitive data such as user entered
+passwords. The seed values cannot be recovered from the PRNG output.
+
+OpenSSL makes sure that the PRNG state is unique for each thread. On
+systems that provide C</dev/urandom>, the randomness device is used
+to seed the PRNG transparently. However, on all other systems, the
+application is responsible for seeding the PRNG by calling RAND_add(),
+L<RAND_egd(3)|RAND_egd(3)>
+or L<RAND_load_file(3)|RAND_load_file(3)>.
+
+RAND_seed() is equivalent to RAND_add() when B<num == entropy>.
+
+RAND_event() collects the entropy from Windows events such as mouse
+movements and other user interaction. It should be called with the
+B<iMsg>, B<wParam> and B<lParam> arguments of I<all> messages sent to
+the window procedure. It will estimate the entropy contained in the
+event message (if any), and add it to the PRNG. The program can then
+process the messages as usual.
+
+The RAND_screen() function is available for the convenience of Windows
+programmers. It adds the current contents of the screen to the PRNG.
+For applications that can catch Windows events, seeding the PRNG by
+calling RAND_event() is a significantly better source of
+randomness. It should be noted that both methods cannot be used on
+servers that run without user interaction.
+
+=head1 RETURN VALUES
+
+RAND_status() and RAND_event() return 1 if the PRNG has been seeded
+with enough data, 0 otherwise.
+
+The other functions do not return values.
+
+=head1 SEE ALSO
+
+L<rand(3)|rand(3)>, L<RAND_egd(3)|RAND_egd(3)>,
+L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)>
+
+=head1 HISTORY
+
+RAND_seed() and RAND_screen() are available in all versions of SSLeay
+and OpenSSL. RAND_add() and RAND_status() have been added in OpenSSL
+0.9.5, RAND_event() in OpenSSL 0.9.5a.
+
+=cut
diff --git a/openssl/doc/crypto/RAND_bytes.pod b/openssl/doc/crypto/RAND_bytes.pod
new file mode 100644
index 000000000..1a9b91e28
--- /dev/null
+++ b/openssl/doc/crypto/RAND_bytes.pod
@@ -0,0 +1,50 @@
+=pod
+
+=head1 NAME
+
+RAND_bytes, RAND_pseudo_bytes - generate random data
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ int RAND_bytes(unsigned char *buf, int num);
+
+ int RAND_pseudo_bytes(unsigned char *buf, int num);
+
+=head1 DESCRIPTION
+
+RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes
+into B<buf>. An error occurs if the PRNG has not been seeded with
+enough randomness to ensure an unpredictable byte sequence.
+
+RAND_pseudo_bytes() puts B<num> pseudo-random bytes into B<buf>.
+Pseudo-random byte sequences generated by RAND_pseudo_bytes() will be
+unique if they are of sufficient length, but 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.
+
+The contents of B<buf> is mixed into the entropy pool before retrieving
+the new pseudo-random bytes unless disabled at compile time (see FAQ).
+
+=head1 RETURN VALUES
+
+RAND_bytes() returns 1 on success, 0 otherwise. The error code can be
+obtained by L<ERR_get_error(3)|ERR_get_error(3)>. RAND_pseudo_bytes() returns 1 if the
+bytes generated are cryptographically strong, 0 otherwise. Both
+functions return -1 if they are not supported by the current RAND
+method.
+
+=head1 SEE ALSO
+
+L<rand(3)|rand(3)>, L<ERR_get_error(3)|ERR_get_error(3)>,
+L<RAND_add(3)|RAND_add(3)>
+
+=head1 HISTORY
+
+RAND_bytes() is available in all versions of SSLeay and OpenSSL. It
+has a return value since OpenSSL 0.9.5. RAND_pseudo_bytes() was added
+in OpenSSL 0.9.5.
+
+=cut
diff --git a/openssl/doc/crypto/RAND_cleanup.pod b/openssl/doc/crypto/RAND_cleanup.pod
new file mode 100644
index 000000000..3a8f0749a
--- /dev/null
+++ b/openssl/doc/crypto/RAND_cleanup.pod
@@ -0,0 +1,29 @@
+=pod
+
+=head1 NAME
+
+RAND_cleanup - erase the PRNG state
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ void RAND_cleanup(void);
+
+=head1 DESCRIPTION
+
+RAND_cleanup() erases the memory used by the PRNG.
+
+=head1 RETURN VALUE
+
+RAND_cleanup() returns no value.
+
+=head1 SEE ALSO
+
+L<rand(3)|rand(3)>
+
+=head1 HISTORY
+
+RAND_cleanup() is available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/openssl/doc/crypto/RAND_egd.pod b/openssl/doc/crypto/RAND_egd.pod
new file mode 100644
index 000000000..8b8c61d16
--- /dev/null
+++ b/openssl/doc/crypto/RAND_egd.pod
@@ -0,0 +1,88 @@
+=pod
+
+=head1 NAME
+
+RAND_egd - query entropy gathering daemon
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ int RAND_egd(const char *path);
+ int RAND_egd_bytes(const char *path, int bytes);
+
+ int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes);
+
+=head1 DESCRIPTION
+
+RAND_egd() queries the entropy gathering daemon EGD on socket B<path>.
+It queries 255 bytes and uses L<RAND_add(3)|RAND_add(3)> to seed the
+OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for
+RAND_egd_bytes(path, 255);
+
+RAND_egd_bytes() queries the entropy gathering daemon EGD on socket B<path>.
+It queries B<bytes> bytes and uses L<RAND_add(3)|RAND_add(3)> to seed the
+OpenSSL built-in PRNG.
+This function is more flexible than RAND_egd().
+When only one secret key must
+be generated, it is not necessary to request the full amount 255 bytes from
+the EGD socket. This can be advantageous, since the amount of entropy
+that can be retrieved from EGD over time is limited.
+
+RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket
+B<path>. If B<buf> is given, B<bytes> bytes are queried and written into
+B<buf>. If B<buf> is NULL, B<bytes> bytes are queried and used to seed the
+OpenSSL built-in PRNG using L<RAND_add(3)|RAND_add(3)>.
+
+=head1 NOTES
+
+On systems without /dev/*random devices providing entropy from the kernel,
+the EGD entropy gathering daemon can be used to collect entropy. It provides
+a socket interface through which entropy can be gathered in chunks up to
+255 bytes. Several chunks can be queried during one connection.
+
+EGD is available from http://www.lothar.com/tech/crypto/ (C<perl
+Makefile.PL; make; make install> to install). It is run as B<egd>
+I<path>, where I<path> is an absolute path designating a socket. When
+RAND_egd() is called with that path as an argument, it tries to read
+random bytes that EGD has collected. RAND_egd() retrieves entropy from the
+daemon using the daemon's "non-blocking read" command which shall
+be answered immediately by the daemon without waiting for additional
+entropy to be collected. The write and read socket operations in the
+communication are blocking.
+
+Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is
+available from
+http://prngd.sourceforge.net/ .
+PRNGD does employ an internal PRNG itself and can therefore never run
+out of entropy.
+
+OpenSSL automatically queries EGD when entropy is requested via RAND_bytes()
+or the status is checked via RAND_status() for the first time, if the socket
+is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool.
+
+=head1 RETURN VALUE
+
+RAND_egd() and RAND_egd_bytes() return the number of bytes read from the
+daemon on success, and -1 if the connection failed or the daemon did not
+return enough data to fully seed the PRNG.
+
+RAND_query_egd_bytes() returns the number of bytes read from the daemon on
+success, and -1 if the connection failed. The PRNG state is not considered.
+
+=head1 SEE ALSO
+
+L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>,
+L<RAND_cleanup(3)|RAND_cleanup(3)>
+
+=head1 HISTORY
+
+RAND_egd() is available since OpenSSL 0.9.5.
+
+RAND_egd_bytes() is available since OpenSSL 0.9.6.
+
+RAND_query_egd_bytes() is available since OpenSSL 0.9.7.
+
+The automatic query of /var/run/egd-pool et al was added in OpenSSL 0.9.7.
+
+=cut
diff --git a/openssl/doc/crypto/RAND_load_file.pod b/openssl/doc/crypto/RAND_load_file.pod
new file mode 100644
index 000000000..d8c134e62
--- /dev/null
+++ b/openssl/doc/crypto/RAND_load_file.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ const char *RAND_file_name(char *buf, size_t num);
+
+ int RAND_load_file(const char *filename, long max_bytes);
+
+ int RAND_write_file(const char *filename);
+
+=head1 DESCRIPTION
+
+RAND_file_name() generates a default path for the random seed
+file. B<buf> points to a buffer of size B<num> in which to store the
+filename. The seed file is $RANDFILE if that environment variable is
+set, $HOME/.rnd otherwise. If $HOME is not set either, or B<num> is
+too small for the path name, an error occurs.
+
+RAND_load_file() reads a number of bytes from file B<filename> and
+adds them to the PRNG. If B<max_bytes> is non-negative,
+up to to B<max_bytes> are read; starting with OpenSSL 0.9.5,
+if B<max_bytes> is -1, the complete file is read.
+
+RAND_write_file() writes a number of random bytes (currently 1024) to
+file B<filename> which can be used to initialize the PRNG by calling
+RAND_load_file() in a later session.
+
+=head1 RETURN VALUES
+
+RAND_load_file() returns the number of bytes read.
+
+RAND_write_file() returns the number of bytes written, and -1 if the
+bytes written were generated without appropriate seed.
+
+RAND_file_name() returns a pointer to B<buf> on success, and NULL on
+error.
+
+=head1 SEE ALSO
+
+L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)>
+
+=head1 HISTORY
+
+RAND_load_file(), RAND_write_file() and RAND_file_name() are available in
+all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/openssl/doc/crypto/RAND_set_rand_method.pod b/openssl/doc/crypto/RAND_set_rand_method.pod
new file mode 100644
index 000000000..e5b780fad
--- /dev/null
+++ b/openssl/doc/crypto/RAND_set_rand_method.pod
@@ -0,0 +1,83 @@
+=pod
+
+=head1 NAME
+
+RAND_set_rand_method, RAND_get_rand_method, RAND_SSLeay - select RAND method
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ void RAND_set_rand_method(const RAND_METHOD *meth);
+
+ const RAND_METHOD *RAND_get_rand_method(void);
+
+ RAND_METHOD *RAND_SSLeay(void);
+
+=head1 DESCRIPTION
+
+A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number
+generation. By modifying the method, alternative implementations such as
+hardware RNGs may be used. IMPORTANT: See the NOTES section for important
+information about how these RAND API functions are affected by the use of
+B<ENGINE> API calls.
+
+Initially, the default RAND_METHOD is the OpenSSL internal implementation, as
+returned by RAND_SSLeay().
+
+RAND_set_default_method() makes B<meth> the method for PRNG use. B<NB>: This is
+true only whilst no ENGINE has been set as a default for RAND, so this function
+is no longer recommended.
+
+RAND_get_default_method() returns a pointer to the current RAND_METHOD.
+However, the meaningfulness of this result is dependent on whether the ENGINE
+API is being used, so this function is no longer recommended.
+
+=head1 THE RAND_METHOD STRUCTURE
+
+ typedef struct rand_meth_st
+ {
+ void (*seed)(const void *buf, int num);
+ int (*bytes)(unsigned char *buf, int num);
+ void (*cleanup)(void);
+ void (*add)(const void *buf, int num, int entropy);
+ int (*pseudorand)(unsigned char *buf, int num);
+ int (*status)(void);
+ } RAND_METHOD;
+
+The components point to the implementation of RAND_seed(),
+RAND_bytes(), RAND_cleanup(), RAND_add(), RAND_pseudo_rand()
+and RAND_status().
+Each component may be NULL if the function is not implemented.
+
+=head1 RETURN VALUES
+
+RAND_set_rand_method() returns no value. RAND_get_rand_method() and
+RAND_SSLeay() return pointers to the respective methods.
+
+=head1 NOTES
+
+As of version 0.9.7, RAND_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 RAND functionality using an ENGINE API function,
+that will override any RAND defaults set using the RAND API (ie.
+RAND_set_rand_method()). For this reason, the ENGINE API is the recommended way
+to control default implementations for use in RAND and other cryptographic
+algorithms.
+
+=head1 SEE ALSO
+
+L<rand(3)|rand(3)>, L<engine(3)|engine(3)>
+
+=head1 HISTORY
+
+RAND_set_rand_method(), RAND_get_rand_method() and RAND_SSLeay() are
+available in all versions of OpenSSL.
+
+In the engine version of version 0.9.6, RAND_set_rand_method() was altered to
+take an ENGINE pointer as its argument. As of version 0.9.7, that has been
+reverted as the ENGINE API transparently overrides RAND defaults if used,
+otherwise RAND API functions work as before. RAND_set_rand_engine() was also
+introduced in version 0.9.7.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_blinding_on.pod b/openssl/doc/crypto/RSA_blinding_on.pod
new file mode 100644
index 000000000..fd2c69abd
--- /dev/null
+++ b/openssl/doc/crypto/RSA_blinding_on.pod
@@ -0,0 +1,43 @@
+=pod
+
+=head1 NAME
+
+RSA_blinding_on, RSA_blinding_off - protect the RSA operation from timing attacks
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);
+
+ void RSA_blinding_off(RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA is vulnerable to timing attacks. In a setup where attackers can
+measure the time of RSA decryption or signature operations, blinding
+must be used to protect the RSA operation from that attack.
+
+RSA_blinding_on() turns blinding on for key B<rsa> and generates a
+random blinding factor. B<ctx> is B<NULL> or a pre-allocated and
+initialized B<BN_CTX>. The random number generator must be seeded
+prior to calling RSA_blinding_on().
+
+RSA_blinding_off() turns blinding off and frees the memory used for
+the blinding factor.
+
+=head1 RETURN VALUES
+
+RSA_blinding_on() returns 1 on success, and 0 if an error occurred.
+
+RSA_blinding_off() returns no value.
+
+=head1 SEE ALSO
+
+L<rsa(3)|rsa(3)>, L<rand(3)|rand(3)>
+
+=head1 HISTORY
+
+RSA_blinding_on() and RSA_blinding_off() appeared in SSLeay 0.9.0.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_check_key.pod b/openssl/doc/crypto/RSA_check_key.pod
new file mode 100644
index 000000000..a5198f3db
--- /dev/null
+++ b/openssl/doc/crypto/RSA_check_key.pod
@@ -0,0 +1,67 @@
+=pod
+
+=head1 NAME
+
+RSA_check_key - validate private RSA keys
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_check_key(RSA *rsa);
+
+=head1 DESCRIPTION
+
+This function validates RSA keys. It checks that B<p> and B<q> are
+in fact prime, and that B<n = p*q>.
+
+It also checks that B<d*e = 1 mod (p-1*q-1)>,
+and that B<dmp1>, B<dmq1> and B<iqmp> are set correctly or are B<NULL>.
+
+As such, this function can not be used with any arbitrary RSA key object,
+even if it is otherwise fit for regular RSA operation. See B<NOTES> for more
+information.
+
+=head1 RETURN VALUE
+
+RSA_check_key() returns 1 if B<rsa> is a valid RSA key, and 0 otherwise.
+-1 is returned if an error occurs while checking the key.
+
+If the key is invalid or an error occurred, the reason code can be
+obtained using L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 NOTES
+
+This function does not work on RSA public keys that have only the modulus
+and public exponent elements populated. It performs integrity checks on all
+the RSA key material, so the RSA key structure must contain all the private
+key data too.
+
+Unlike most other RSA functions, this function does B<not> work
+transparently with any underlying ENGINE implementation because it uses the
+key data in the RSA structure directly. An ENGINE implementation can
+override the way key data is stored and handled, and can even provide
+support for HSM keys - in which case the RSA structure may contain B<no>
+key data at all! If the ENGINE in question is only being used for
+acceleration or analysis purposes, then in all likelihood the RSA key data
+is complete and untouched, but this can't be assumed in the general case.
+
+=head1 BUGS
+
+A method of verifying the RSA key using opaque RSA API functions might need
+to be considered. Right now RSA_check_key() simply uses the RSA structure
+elements directly, bypassing the RSA_METHOD table altogether (and
+completely violating encapsulation and object-orientation in the process).
+The best fix will probably be to introduce a "check_key()" handler to the
+RSA_METHOD function table so that alternative implementations can also
+provide their own verifiers.
+
+=head1 SEE ALSO
+
+L<rsa(3)|rsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
+
+=head1 HISTORY
+
+RSA_check_key() appeared in OpenSSL 0.9.4.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_generate_key.pod b/openssl/doc/crypto/RSA_generate_key.pod
new file mode 100644
index 000000000..52dbb14a5
--- /dev/null
+++ b/openssl/doc/crypto/RSA_generate_key.pod
@@ -0,0 +1,69 @@
+=pod
+
+=head1 NAME
+
+RSA_generate_key - generate RSA key pair
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ RSA *RSA_generate_key(int num, unsigned long e,
+ void (*callback)(int,int,void *), void *cb_arg);
+
+=head1 DESCRIPTION
+
+RSA_generate_key() generates a key pair and returns it in a newly
+allocated B<RSA> structure. The pseudo-random number generator must
+be seeded prior to calling RSA_generate_key().
+
+The modulus size will be B<num> bits, and the public exponent will be
+B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure.
+The exponent is an odd number, typically 3, 17 or 65537.
+
+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 *
+
+While a random prime number is generated, it is called as
+described in L<BN_generate_prime(3)|BN_generate_prime(3)>.
+
+=item *
+
+When the n-th randomly generated prime is rejected as not
+suitable for the key, B<callback(2, n, cb_arg)> is called.
+
+=item *
+
+When a random p has been found with p-1 relatively prime to B<e>,
+it is called as B<callback(3, 0, cb_arg)>.
+
+=back
+
+The process is then repeated for prime q with B<callback(3, 1, cb_arg)>.
+
+=head1 RETURN VALUE
+
+If key generation fails, RSA_generate_key() returns B<NULL>; the
+error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 BUGS
+
+B<callback(2, x, cb_arg)> is used with two different meanings.
+
+RSA_generate_key() goes into an infinite loop for illegal input values.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,
+L<RSA_free(3)|RSA_free(3)>
+
+=head1 HISTORY
+
+The B<cb_arg> argument was added in SSLeay 0.9.0.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_get_ex_new_index.pod b/openssl/doc/crypto/RSA_get_ex_new_index.pod
new file mode 100644
index 000000000..7d0fd1f91
--- /dev/null
+++ b/openssl/doc/crypto/RSA_get_ex_new_index.pod
@@ -0,0 +1,120 @@
+=pod
+
+=head1 NAME
+
+RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA structures
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_get_ex_new_index(long argl, void *argp,
+ CRYPTO_EX_new *new_func,
+ CRYPTO_EX_dup *dup_func,
+ CRYPTO_EX_free *free_func);
+
+ int RSA_set_ex_data(RSA *r, int idx, void *arg);
+
+ void *RSA_get_ex_data(RSA *r, int idx);
+
+ typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
+ int idx, long argl, void *argp);
+ typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
+ int idx, long argl, void *argp);
+ typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
+ int idx, long argl, void *argp);
+
+=head1 DESCRIPTION
+
+Several OpenSSL structures can have application specific data attached to them.
+This has several potential uses, it can be used to cache data associated with
+a structure (for example the hash of some part of the structure) or some
+additional data (for example a handle to the data in an external library).
+
+Since the application data can be anything at all it is passed and retrieved
+as a B<void *> type.
+
+The B<RSA_get_ex_new_index()> function is initially called to "register" some
+new application specific data. It takes three optional function pointers which
+are called when the parent structure (in this case an RSA structure) is
+initially created, when it is copied and when it is freed up. If any or all of
+these function pointer arguments are not used they should be set to NULL. The
+precise manner in which these function pointers are called is described in more
+detail below. B<RSA_get_ex_new_index()> also takes additional long and pointer
+parameters which will be passed to the supplied functions but which otherwise
+have no special meaning. It returns an B<index> which should be stored
+(typically in a static variable) and passed used in the B<idx> parameter in
+the remaining functions. Each successful call to B<RSA_get_ex_new_index()>
+will return an index greater than any previously returned, this is important
+because the optional functions are called in order of increasing index value.
+
+B<RSA_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<RSA_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<RSA_set_ex_data()> call.
+
+B<new_func()> is called when a structure is initially allocated (for example
+with B<RSA_new()>. The parent structure members will not have any meaningful
+values at this point. This function will typically be used to allocate any
+application specific structure.
+
+B<free_func()> is called when a structure is being freed up. The dynamic parent
+structure members should not be accessed because they will be freed up when
+this function is called.
+
+B<new_func()> and B<free_func()> take the same parameters. B<parent> is a
+pointer to the parent RSA structure. B<ptr> is a the application specific data
+(this wont be of much use in B<new_func()>. B<ad> is a pointer to the
+B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions
+B<CRYPTO_get_ex_data()> and B<CRYPTO_set_ex_data()> can be called to manipulate
+it. The B<idx> parameter is the index: this will be the same value returned by
+B<RSA_get_ex_new_index()> when the functions were initially registered. Finally
+the B<argl> and B<argp> parameters are the values originally passed to the same
+corresponding parameters when B<RSA_get_ex_new_index()> was called.
+
+B<dup_func()> is called when a structure is being copied. Pointers to the
+destination and source B<CRYPTO_EX_DATA> structures are passed in the B<to> and
+B<from> parameters respectively. The B<from_d> parameter is passed a pointer to
+the source application data when the function is called, when the function returns
+the value is copied to the destination: the application can thus modify the data
+pointed to by B<from_d> and have different values in the source and destination.
+The B<idx>, B<argl> and B<argp> parameters are the same as those in B<new_func()>
+and B<free_func()>.
+
+=head1 RETURN VALUES
+
+B<RSA_get_ex_new_index()> returns a new index or -1 on failure (note 0 is a valid
+index value).
+
+B<RSA_set_ex_data()> returns 1 on success or 0 on failure.
+
+B<RSA_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.
+
+B<new_func()> and B<dup_func()> should return 0 for failure and 1 for success.
+
+On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 BUGS
+
+B<dup_func()> is currently never called.
+
+The return value of B<new_func()> is ignored.
+
+The B<new_func()> function isn't very useful because no meaningful values are
+present in the parent RSA structure when it is called.
+
+=head1 SEE ALSO
+
+L<rsa(3)|rsa(3)>, L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>
+
+=head1 HISTORY
+
+RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are
+available since SSLeay 0.9.0.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_new.pod b/openssl/doc/crypto/RSA_new.pod
new file mode 100644
index 000000000..3d15b9282
--- /dev/null
+++ b/openssl/doc/crypto/RSA_new.pod
@@ -0,0 +1,41 @@
+=pod
+
+=head1 NAME
+
+RSA_new, RSA_free - allocate and free RSA objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ RSA * RSA_new(void);
+
+ void RSA_free(RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA_new() allocates and initializes an B<RSA> structure. It is equivalent to
+calling RSA_new_method(NULL).
+
+RSA_free() frees the B<RSA> structure and its components. The key is
+erased before the memory is returned to the system.
+
+=head1 RETURN VALUES
+
+If the allocation fails, RSA_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.
+
+RSA_free() returns no value.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>,
+L<RSA_generate_key(3)|RSA_generate_key(3)>,
+L<RSA_new_method(3)|RSA_new_method(3)>
+
+=head1 HISTORY
+
+RSA_new() and RSA_free() are available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod b/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod
new file mode 100644
index 000000000..b8f678fe7
--- /dev/null
+++ b/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod
@@ -0,0 +1,124 @@
+=pod
+
+=head1 NAME
+
+RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1,
+RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2,
+RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP,
+RSA_padding_add_SSLv23, RSA_padding_check_SSLv23,
+RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption
+padding
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen,
+ unsigned char *f, int fl);
+
+ int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen,
+ unsigned char *f, int fl, int rsa_len);
+
+ int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen,
+ unsigned char *f, int fl);
+
+ int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen,
+ unsigned char *f, int fl, int rsa_len);
+
+ int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen,
+ unsigned char *f, int fl, unsigned char *p, int pl);
+
+ int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen,
+ unsigned char *f, int fl, int rsa_len, unsigned char *p, int pl);
+
+ int RSA_padding_add_SSLv23(unsigned char *to, int tlen,
+ unsigned char *f, int fl);
+
+ int RSA_padding_check_SSLv23(unsigned char *to, int tlen,
+ unsigned char *f, int fl, int rsa_len);
+
+ int RSA_padding_add_none(unsigned char *to, int tlen,
+ unsigned char *f, int fl);
+
+ int RSA_padding_check_none(unsigned char *to, int tlen,
+ unsigned char *f, int fl, int rsa_len);
+
+=head1 DESCRIPTION
+
+The RSA_padding_xxx_xxx() functions are called from the RSA encrypt,
+decrypt, sign and verify functions. Normally they should not be called
+from application programs.
+
+However, they can also be called directly to implement padding for other
+asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and
+RSA_padding_check_PKCS1_OAEP() may be used in an application combined
+with B<RSA_NO_PADDING> in order to implement OAEP with an encoding
+parameter.
+
+RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into
+B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl>
+does not meet the size requirements of the encoding method.
+
+The following encoding methods are implemented:
+
+=over 4
+
+=item PKCS1_type_1
+
+PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures
+
+=item PKCS1_type_2
+
+PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2)
+
+=item PKCS1_OAEP
+
+PKCS #1 v2.0 EME-OAEP
+
+=item SSLv23
+
+PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification
+
+=item none
+
+simply copy the data
+
+=back
+
+The random number generator must be seeded prior to calling
+RSA_padding_add_xxx().
+
+RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
+a valid encoding for a B<rsa_len> byte RSA key in the respective
+encoding method and stores the recovered data of at most B<tlen> bytes
+(for B<RSA_NO_PADDING>: of size B<tlen>)
+at B<to>.
+
+For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
+of length B<pl>. B<p> may be B<NULL> if B<pl> is 0.
+
+=head1 RETURN VALUES
+
+The RSA_padding_add_xxx() functions return 1 on success, 0 on error.
+The RSA_padding_check_xxx() functions return the length of the
+recovered data, -1 on error. Error codes can be obtained by calling
+L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>,
+L<RSA_private_decrypt(3)|RSA_private_decrypt(3)>,
+L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)>
+
+=head1 HISTORY
+
+RSA_padding_add_PKCS1_type_1(), RSA_padding_check_PKCS1_type_1(),
+RSA_padding_add_PKCS1_type_2(), RSA_padding_check_PKCS1_type_2(),
+RSA_padding_add_SSLv23(), RSA_padding_check_SSLv23(),
+RSA_padding_add_none() and RSA_padding_check_none() appeared in
+SSLeay 0.9.0.
+
+RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() were
+added in OpenSSL 0.9.2b.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_print.pod b/openssl/doc/crypto/RSA_print.pod
new file mode 100644
index 000000000..c971e91f4
--- /dev/null
+++ b/openssl/doc/crypto/RSA_print.pod
@@ -0,0 +1,49 @@
+=pod
+
+=head1 NAME
+
+RSA_print, RSA_print_fp,
+DSAparams_print, DSAparams_print_fp, DSA_print, DSA_print_fp,
+DHparams_print, DHparams_print_fp - print cryptographic parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_print(BIO *bp, RSA *x, int offset);
+ int RSA_print_fp(FILE *fp, RSA *x, int offset);
+
+ #include <openssl/dsa.h>
+
+ int DSAparams_print(BIO *bp, DSA *x);
+ int DSAparams_print_fp(FILE *fp, DSA *x);
+ int DSA_print(BIO *bp, DSA *x, int offset);
+ int DSA_print_fp(FILE *fp, DSA *x, int offset);
+
+ #include <openssl/dh.h>
+
+ int DHparams_print(BIO *bp, DH *x);
+ int DHparams_print_fp(FILE *fp, DH *x);
+
+=head1 DESCRIPTION
+
+A human-readable hexadecimal output of the components of the RSA
+key, DSA parameters or key or DH parameters is printed to B<bp> or B<fp>.
+
+The output lines are indented by B<offset> spaces.
+
+=head1 RETURN VALUES
+
+These functions return 1 on success, 0 on error.
+
+=head1 SEE ALSO
+
+L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)>
+
+=head1 HISTORY
+
+RSA_print(), RSA_print_fp(), DSA_print(), DSA_print_fp(), DH_print(),
+DH_print_fp() are available in all versions of SSLeay and OpenSSL.
+DSAparams_print() and DSAparams_print_fp() were added in SSLeay 0.8.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_private_encrypt.pod b/openssl/doc/crypto/RSA_private_encrypt.pod
new file mode 100644
index 000000000..746a80c79
--- /dev/null
+++ b/openssl/doc/crypto/RSA_private_encrypt.pod
@@ -0,0 +1,70 @@
+=pod
+
+=head1 NAME
+
+RSA_private_encrypt, RSA_public_decrypt - low level signature operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_private_encrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ int RSA_public_decrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+=head1 DESCRIPTION
+
+These functions handle RSA signatures at a low level.
+
+RSA_private_encrypt() signs the B<flen> bytes at B<from> (usually a
+message digest with an algorithm identifier) using the private key
+B<rsa> and stores the signature in B<to>. B<to> must point to
+B<RSA_size(rsa)> bytes of memory.
+
+B<padding> denotes one of the following modes:
+
+=over 4
+
+=item RSA_PKCS1_PADDING
+
+PKCS #1 v1.5 padding. This function does not handle the
+B<algorithmIdentifier> specified in PKCS #1. When generating or
+verifying PKCS #1 signatures, L<RSA_sign(3)|RSA_sign(3)> and L<RSA_verify(3)|RSA_verify(3)> should be
+used.
+
+=item RSA_NO_PADDING
+
+Raw RSA signature. This mode should I<only> be used to implement
+cryptographically sound padding modes in the application code.
+Signing user data directly with RSA is insecure.
+
+=back
+
+RSA_public_decrypt() recovers the message digest from the B<flen>
+bytes long signature at B<from> using the signer's public key
+B<rsa>. B<to> must point to a memory section large enough to hold the
+message digest (which is smaller than B<RSA_size(rsa) -
+11>). B<padding> is the padding mode that was used to sign the data.
+
+=head1 RETURN VALUES
+
+RSA_private_encrypt() returns the size of the signature (i.e.,
+RSA_size(rsa)). RSA_public_decrypt() returns the size of the
+recovered message digest.
+
+On error, -1 is returned; the error codes 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)>, L<rsa(3)|rsa(3)>,
+L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)>
+
+=head1 HISTORY
+
+The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is
+available since SSLeay 0.9.0.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_public_encrypt.pod b/openssl/doc/crypto/RSA_public_encrypt.pod
new file mode 100644
index 000000000..ab0fe3b2c
--- /dev/null
+++ b/openssl/doc/crypto/RSA_public_encrypt.pod
@@ -0,0 +1,84 @@
+=pod
+
+=head1 NAME
+
+RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_public_encrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ int RSA_private_decrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+=head1 DESCRIPTION
+
+RSA_public_encrypt() encrypts the B<flen> bytes at B<from> (usually a
+session key) using the public key B<rsa> and stores the ciphertext in
+B<to>. B<to> must point to RSA_size(B<rsa>) bytes of memory.
+
+B<padding> denotes one of the following modes:
+
+=over 4
+
+=item RSA_PKCS1_PADDING
+
+PKCS #1 v1.5 padding. This currently is the most widely used mode.
+
+=item RSA_PKCS1_OAEP_PADDING
+
+EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty
+encoding parameter. This mode is recommended for all new applications.
+
+=item RSA_SSLV23_PADDING
+
+PKCS #1 v1.5 padding with an SSL-specific modification that denotes
+that the server is SSL3 capable.
+
+=item RSA_NO_PADDING
+
+Raw RSA encryption. This mode should I<only> be used to implement
+cryptographically sound padding modes in the application code.
+Encrypting user data directly with RSA is insecure.
+
+=back
+
+B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5
+based padding modes, less than RSA_size(B<rsa>) - 41 for
+RSA_PKCS1_OAEP_PADDING and exactly RSA_size(B<rsa>) for RSA_NO_PADDING.
+The random number generator must be seeded prior to calling
+RSA_public_encrypt().
+
+RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the
+private key B<rsa> and stores the plaintext in B<to>. B<to> must point
+to a memory section large enough to hold the decrypted data (which is
+smaller than RSA_size(B<rsa>)). B<padding> is the padding mode that
+was used to encrypt the data.
+
+=head1 RETURN VALUES
+
+RSA_public_encrypt() returns the size of the encrypted data (i.e.,
+RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the
+recovered plaintext.
+
+On error, -1 is returned; the error codes can be
+obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 CONFORMING TO
+
+SSL, PKCS #1 v2.0
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,
+L<RSA_size(3)|RSA_size(3)>
+
+=head1 HISTORY
+
+The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is
+available since SSLeay 0.9.0, OAEP was added in OpenSSL 0.9.2b.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_set_method.pod b/openssl/doc/crypto/RSA_set_method.pod
new file mode 100644
index 000000000..2c963d7e5
--- /dev/null
+++ b/openssl/doc/crypto/RSA_set_method.pod
@@ -0,0 +1,202 @@
+=pod
+
+=head1 NAME
+
+RSA_set_default_method, RSA_get_default_method, RSA_set_method,
+RSA_get_method, RSA_PKCS1_SSLeay, RSA_null_method, RSA_flags,
+RSA_new_method - select RSA method
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ void RSA_set_default_method(const RSA_METHOD *meth);
+
+ RSA_METHOD *RSA_get_default_method(void);
+
+ int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
+
+ RSA_METHOD *RSA_get_method(const RSA *rsa);
+
+ RSA_METHOD *RSA_PKCS1_SSLeay(void);
+
+ RSA_METHOD *RSA_null_method(void);
+
+ int RSA_flags(const RSA *rsa);
+
+ RSA *RSA_new_method(RSA_METHOD *method);
+
+=head1 DESCRIPTION
+
+An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
+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 RSA API functions are affected by the
+use of B<ENGINE> API calls.
+
+Initially, the default RSA_METHOD is the OpenSSL internal implementation,
+as returned by RSA_PKCS1_SSLeay().
+
+RSA_set_default_method() makes B<meth> the default method for all RSA
+structures created later. B<NB>: This is true only whilst no ENGINE has
+been set as a default for RSA, so this function is no longer recommended.
+
+RSA_get_default_method() returns a pointer to the current default
+RSA_METHOD. However, the meaningfulness of this result is dependent on
+whether the ENGINE API is being used, so this function is no longer
+recommended.
+
+RSA_set_method() selects B<meth> to perform all operations using the key
+B<rsa>. This will replace the RSA_METHOD used by the RSA 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 RSA keys that only
+work with certain RSA_METHOD implementations (eg. from an ENGINE module
+that supports embedded hardware-protected keys), and in such cases
+attempting to change the RSA_METHOD for the key can have unexpected
+results.
+
+RSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>.
+This method may or may not be supplied by an ENGINE implementation, but if
+it is, the return value can only be guaranteed to be valid as long as the
+RSA key itself is valid and does not have its implementation changed by
+RSA_set_method().
+
+RSA_flags() returns the B<flags> that are set for B<rsa>'s current
+RSA_METHOD. See the BUGS section.
+
+RSA_new_method() allocates and initializes an RSA structure so that
+B<engine> will be used for the RSA operations. If B<engine> is NULL, the
+default ENGINE for RSA operations is used, and if no default ENGINE is set,
+the RSA_METHOD controlled by RSA_set_default_method() is used.
+
+RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.
+
+RSA_new_method() allocates and initializes an B<RSA> structure so that
+B<method> will be used for the RSA operations. If B<method> is B<NULL>,
+the default method is used.
+
+=head1 THE RSA_METHOD STRUCTURE
+
+ typedef struct rsa_meth_st
+ {
+ /* name of the implementation */
+ const char *name;
+
+ /* encrypt */
+ int (*rsa_pub_enc)(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ /* verify arbitrary data */
+ int (*rsa_pub_dec)(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ /* sign arbitrary data */
+ int (*rsa_priv_enc)(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ /* decrypt */
+ int (*rsa_priv_dec)(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
+ implementations) */
+ int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
+
+ /* compute r = a ^ p mod m (May be NULL for some implementations) */
+ int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
+ const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
+
+ /* called at RSA_new */
+ int (*init)(RSA *rsa);
+
+ /* called at RSA_free */
+ int (*finish)(RSA *rsa);
+
+ /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key
+ * operations, even if p,q,dmp1,dmq1,iqmp
+ * are NULL
+ * RSA_FLAG_SIGN_VER - enable rsa_sign and rsa_verify
+ * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
+ */
+ int flags;
+
+ char *app_data; /* ?? */
+
+ /* sign. For backward compatibility, this is used only
+ * if (flags & RSA_FLAG_SIGN_VER)
+ */
+ int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
+ unsigned char *sigret, unsigned int *siglen, RSA *rsa);
+
+ /* verify. For backward compatibility, this is used only
+ * if (flags & RSA_FLAG_SIGN_VER)
+ */
+ int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
+ unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
+
+ } RSA_METHOD;
+
+=head1 RETURN VALUES
+
+RSA_PKCS1_SSLeay(), RSA_PKCS1_null_method(), RSA_get_default_method()
+and RSA_get_method() return pointers to the respective RSA_METHODs.
+
+RSA_set_default_method() returns no value.
+
+RSA_set_method() returns a pointer to the old RSA_METHOD implementation
+that was replaced. However, this return value should probably be ignored
+because if it was supplied by an ENGINE, the pointer could be invalidated
+at any time if the ENGINE is unloaded (in fact it could be unloaded as a
+result of the RSA_set_method() function releasing its handle to the
+ENGINE). For this reason, the return type may be replaced with a B<void>
+declaration in a future release.
+
+RSA_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, RSA_METHOD implementations are grouped together with
+other algorithmic APIs (eg. DSA_METHOD, EVP_CIPHER, etc) into B<ENGINE>
+modules. If a default ENGINE is specified for RSA functionality using an
+ENGINE API function, that will override any RSA defaults set using the RSA
+API (ie. RSA_set_default_method()). For this reason, the ENGINE API is the
+recommended way to control default implementations for use in RSA and other
+cryptographic algorithms.
+
+=head1 BUGS
+
+The behaviour of RSA_flags() is a mis-feature that is left as-is for now
+to avoid creating compatibility problems. RSA functionality, such as the
+encryption functions, are controlled by the B<flags> value in the RSA key
+itself, not by the B<flags> value in the RSA_METHOD attached to the RSA key
+(which is what this function returns). If the flags element of an RSA key
+is changed, the changes will be honoured by RSA functionality but will not
+be reflected in the return value of the RSA_flags() function - in effect
+RSA_flags() behaves more like an RSA_default_flags() function (which does
+not currently exist).
+
+=head1 SEE ALSO
+
+L<rsa(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)>
+
+=head1 HISTORY
+
+RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8.
+RSA_get_default_method(), RSA_set_method() and RSA_get_method() as
+well as the rsa_sign and rsa_verify components of RSA_METHOD were
+added in OpenSSL 0.9.4.
+
+RSA_set_default_openssl_method() and RSA_get_default_openssl_method()
+replaced RSA_set_default_method() and RSA_get_default_method()
+respectively, and RSA_set_method() and RSA_new_method() were altered to use
+B<ENGINE>s rather than B<RSA_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 RSA API without requiring changing these
+function prototypes.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_sign.pod b/openssl/doc/crypto/RSA_sign.pod
new file mode 100644
index 000000000..8553be8e9
--- /dev/null
+++ b/openssl/doc/crypto/RSA_sign.pod
@@ -0,0 +1,62 @@
+=pod
+
+=head1 NAME
+
+RSA_sign, RSA_verify - RSA signatures
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_sign(int type, const unsigned char *m, unsigned int m_len,
+ unsigned char *sigret, unsigned int *siglen, RSA *rsa);
+
+ int RSA_verify(int type, const unsigned char *m, unsigned int m_len,
+ unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA_sign() signs the message digest B<m> of size B<m_len> using the
+private key B<rsa> as specified in PKCS #1 v2.0. It stores the
+signature in B<sigret> and the signature size in B<siglen>. B<sigret>
+must point to RSA_size(B<rsa>) bytes of memory.
+
+B<type> denotes the message digest algorithm that was used to generate
+B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and B<NID_md5>;
+see L<objects(3)|objects(3)> for details. If B<type> is B<NID_md5_sha1>,
+an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding
+and no algorithm identifier) is created.
+
+RSA_verify() verifies that the signature B<sigbuf> of size B<siglen>
+matches a given message digest B<m> of size B<m_len>. B<type> denotes
+the message digest algorithm that was used to generate the signature.
+B<rsa> is the signer's public key.
+
+=head1 RETURN VALUES
+
+RSA_sign() returns 1 on success, 0 otherwise. RSA_verify() returns 1
+on successful verification, 0 otherwise.
+
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 BUGS
+
+Certain signatures with an improper algorithm identifier are accepted
+for compatibility with SSLeay 0.4.5 :-)
+
+=head1 CONFORMING TO
+
+SSL, PKCS #1 v2.0
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>,
+L<rsa(3)|rsa(3)>, L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>,
+L<RSA_public_decrypt(3)|RSA_public_decrypt(3)>
+
+=head1 HISTORY
+
+RSA_sign() and RSA_verify() are available in all versions of SSLeay
+and OpenSSL.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod
new file mode 100644
index 000000000..e70380bbf
--- /dev/null
+++ b/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod
@@ -0,0 +1,59 @@
+=pod
+
+=head1 NAME
+
+RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m,
+ unsigned int m_len, unsigned char *sigret, unsigned int *siglen,
+ RSA *rsa);
+
+ int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m,
+ unsigned int m_len, unsigned char *sigbuf, unsigned int siglen,
+ RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA_sign_ASN1_OCTET_STRING() signs the octet string B<m> of size
+B<m_len> using the private key B<rsa> represented in DER using PKCS #1
+padding. It stores the signature in B<sigret> and the signature size
+in B<siglen>. B<sigret> must point to B<RSA_size(rsa)> bytes of
+memory.
+
+B<dummy> is ignored.
+
+The random number generator must be seeded prior to calling RSA_sign_ASN1_OCTET_STRING().
+
+RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf>
+of size B<siglen> is the DER representation of a given octet string
+B<m> of size B<m_len>. B<dummy> is ignored. B<rsa> is the signer's
+public key.
+
+=head1 RETURN VALUES
+
+RSA_sign_ASN1_OCTET_STRING() returns 1 on success, 0 otherwise.
+RSA_verify_ASN1_OCTET_STRING() returns 1 on successful verification, 0
+otherwise.
+
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 BUGS
+
+These functions serve no recognizable purpose.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>,
+L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>,
+L<RSA_verify(3)|RSA_verify(3)>
+
+=head1 HISTORY
+
+RSA_sign_ASN1_OCTET_STRING() and RSA_verify_ASN1_OCTET_STRING() were
+added in SSLeay 0.8.
+
+=cut
diff --git a/openssl/doc/crypto/RSA_size.pod b/openssl/doc/crypto/RSA_size.pod
new file mode 100644
index 000000000..5b7f835f9
--- /dev/null
+++ b/openssl/doc/crypto/RSA_size.pod
@@ -0,0 +1,33 @@
+=pod
+
+=head1 NAME
+
+RSA_size - get RSA modulus size
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_size(const RSA *rsa);
+
+=head1 DESCRIPTION
+
+This function returns the RSA modulus size in bytes. It can be used to
+determine how much memory must be allocated for an RSA encrypted
+value.
+
+B<rsa-E<gt>n> must not be B<NULL>.
+
+=head1 RETURN VALUE
+
+The size in bytes.
+
+=head1 SEE ALSO
+
+L<rsa(3)|rsa(3)>
+
+=head1 HISTORY
+
+RSA_size() is available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/openssl/doc/crypto/SMIME_read_PKCS7.pod b/openssl/doc/crypto/SMIME_read_PKCS7.pod
new file mode 100644
index 000000000..ffafa3788
--- /dev/null
+++ b/openssl/doc/crypto/SMIME_read_PKCS7.pod
@@ -0,0 +1,71 @@
+=pod
+
+=head1 NAME
+
+SMIME_read_PKCS7 - parse S/MIME message.
+
+=head1 SYNOPSIS
+
+PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont);
+
+=head1 DESCRIPTION
+
+SMIME_read_PKCS7() parses a message in S/MIME format.
+
+B<in> is a BIO to read the message from.
+
+If cleartext signing is used then the content is saved in
+a memory bio which is written to B<*bcont>, otherwise
+B<*bcont> is set to B<NULL>.
+
+The parsed PKCS#7 structure is returned or B<NULL> if an
+error occurred.
+
+=head1 NOTES
+
+If B<*bcont> is not B<NULL> then the message is clear text
+signed. B<*bcont> can then be passed to PKCS7_verify() with
+the B<PKCS7_DETACHED> flag set.
+
+Otherwise the type of the returned structure can be determined
+using PKCS7_type().
+
+To support future functionality if B<bcont> is not B<NULL>
+B<*bcont> should be initialized to B<NULL>. For example:
+
+ BIO *cont = NULL;
+ PKCS7 *p7;
+
+ p7 = SMIME_read_PKCS7(in, &cont);
+
+=head1 BUGS
+
+The MIME parser used by SMIME_read_PKCS7() is somewhat primitive.
+While it will handle most S/MIME messages more complex compound
+formats may not work.
+
+The parser assumes that the PKCS7 structure is always base64
+encoded and will not handle the case where it is in binary format
+or uses quoted printable format.
+
+The use of a memory BIO to hold the signed content limits the size
+of message which can be processed due to memory restraints: a
+streaming single pass option should be available.
+
+=head1 RETURN VALUES
+
+SMIME_read_PKCS7() returns a valid B<PKCS7> structure or B<NULL>
+is an error occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_type(3)|PKCS7_type(3)>
+L<SMIME_read_PKCS7(3)|SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>,
+L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)>
+L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>
+
+=head1 HISTORY
+
+SMIME_read_PKCS7() was added to OpenSSL 0.9.5
+
+=cut
diff --git a/openssl/doc/crypto/SMIME_write_PKCS7.pod b/openssl/doc/crypto/SMIME_write_PKCS7.pod
new file mode 100644
index 000000000..61945b388
--- /dev/null
+++ b/openssl/doc/crypto/SMIME_write_PKCS7.pod
@@ -0,0 +1,61 @@
+=pod
+
+=head1 NAME
+
+SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format.
+
+=head1 SYNOPSIS
+
+int SMIME_write_PKCS7(BIO *out, PKCS7 *p7, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+SMIME_write_PKCS7() adds the appropriate MIME headers to a PKCS#7
+structure to produce an S/MIME message.
+
+B<out> is the BIO to write the data to. B<p7> is the appropriate
+B<PKCS7> structure. If cleartext signing (B<multipart/signed>) is
+being used then the signed data must be supplied in the B<data>
+argument. B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+The following flags can be passed in the B<flags> parameter.
+
+If B<PKCS7_DETACHED> is set then cleartext signing will be used,
+this option only makes sense for signedData where B<PKCS7_DETACHED>
+is also set when PKCS7_sign() is also called.
+
+If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain>
+are added to the content, this only makes sense if B<PKCS7_DETACHED>
+is also set.
+
+If the B<PKCS7_PARTSIGN> flag is set the signed data is finalized
+and output along with the content. This flag should only be set
+if B<PKCS7_DETACHED> is also set and the previous call to PKCS7_sign()
+also set these flags.
+
+If cleartext signing is being used and B<PKCS7_PARTSIGN> not set then
+the data must be read twice: once to compute the signature in PKCS7_sign()
+and once to output the S/MIME message.
+
+=head1 BUGS
+
+SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there
+should be an option to disable this.
+
+=head1 RETURN VALUES
+
+SMIME_write_PKCS7() returns 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>,
+L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)>
+L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>
+
+=head1 HISTORY
+
+SMIME_write_PKCS7() was added to OpenSSL 0.9.5
+
+=cut
diff --git a/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod b/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod
new file mode 100644
index 000000000..11b35f6fd
--- /dev/null
+++ b/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod
@@ -0,0 +1,72 @@
+=pod
+
+=head1 NAME
+
+X509_NAME_ENTRY_get_object, X509_NAME_ENTRY_get_data,
+X509_NAME_ENTRY_set_object, X509_NAME_ENTRY_set_data,
+X509_NAME_ENTRY_create_by_txt, X509_NAME_ENTRY_create_by_NID,
+X509_NAME_ENTRY_create_by_OBJ - X509_NAME_ENTRY utility functions
+
+=head1 SYNOPSIS
+
+ASN1_OBJECT * X509_NAME_ENTRY_get_object(X509_NAME_ENTRY *ne);
+ASN1_STRING * X509_NAME_ENTRY_get_data(X509_NAME_ENTRY *ne);
+
+int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, ASN1_OBJECT *obj);
+int X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *ne, int type, const unsigned char *bytes, int len);
+
+X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY **ne, const char *field, int type, const unsigned char *bytes, int len);
+X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY **ne, int nid, int type,unsigned char *bytes, int len);
+X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len);
+
+=head1 DESCRIPTION
+
+X509_NAME_ENTRY_get_object() retrieves the field name of B<ne> in
+and B<ASN1_OBJECT> structure.
+
+X509_NAME_ENTRY_get_data() retrieves the field value of B<ne> in
+and B<ASN1_STRING> structure.
+
+X509_NAME_ENTRY_set_object() sets the field name of B<ne> to B<obj>.
+
+X509_NAME_ENTRY_set_data() sets the field value of B<ne> to string type
+B<type> and value determined by B<bytes> and B<len>.
+
+X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID()
+and X509_NAME_ENTRY_create_by_OBJ() create and return an
+B<X509_NAME_ENTRY> structure.
+
+=head1 NOTES
+
+X509_NAME_ENTRY_get_object() and X509_NAME_ENTRY_get_data() can be
+used to examine an B<X509_NAME_ENTRY> function as returned by
+X509_NAME_get_entry() for example.
+
+X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID(),
+and X509_NAME_ENTRY_create_by_OBJ() create and return an
+
+X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_OBJ(),
+X509_NAME_ENTRY_create_by_NID() and X509_NAME_ENTRY_set_data()
+are seldom used in practice because B<X509_NAME_ENTRY> structures
+are almost always part of B<X509_NAME> structures and the
+corresponding B<X509_NAME> functions are typically used to
+create and add new entries in a single operation.
+
+The arguments of these functions support similar options to the similarly
+named ones of the corresponding B<X509_NAME> functions such as
+X509_NAME_add_entry_by_txt(). So for example B<type> can be set to
+B<MBSTRING_ASC> but in the case of X509_set_data() the field name must be
+set first so the relevant field information can be looked up internally.
+
+=head1 RETURN VALUES
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>,
+L<OBJ_nid2obj(3),OBJ_nid2obj(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod b/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod
new file mode 100644
index 000000000..e2ab4b0d2
--- /dev/null
+++ b/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod
@@ -0,0 +1,114 @@
+=pod
+
+=head1 NAME
+
+X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID,
+X509_NAME_add_entry, X509_NAME_delete_entry - X509_NAME modification functions
+
+=head1 SYNOPSIS
+
+int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, const unsigned char *bytes, int len, int loc, int set);
+
+int X509_NAME_add_entry_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, int type, unsigned char *bytes, int len, int loc, int set);
+
+int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set);
+
+int X509_NAME_add_entry(X509_NAME *name,X509_NAME_ENTRY *ne, int loc, int set);
+
+X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc);
+
+=head1 DESCRIPTION
+
+X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ() and
+X509_NAME_add_entry_by_NID() add a field whose name is defined
+by a string B<field>, an object B<obj> or a NID B<nid> respectively.
+The field value to be added is in B<bytes> of length B<len>. If
+B<len> is -1 then the field length is calculated internally using
+strlen(bytes).
+
+The type of field is determined by B<type> which can either be a
+definition of the type of B<bytes> (such as B<MBSTRING_ASC>) or a
+standard ASN1 type (such as B<V_ASN1_IA5STRING>). The new entry is
+added to a position determined by B<loc> and B<set>.
+
+X509_NAME_add_entry() adds a copy of B<X509_NAME_ENTRY> structure B<ne>
+to B<name>. The new entry is added to a position determined by B<loc>
+and B<set>. Since a copy of B<ne> is added B<ne> must be freed up after
+the call.
+
+X509_NAME_delete_entry() deletes an entry from B<name> at position
+B<loc>. The deleted entry is returned and must be freed up.
+
+=head1 NOTES
+
+The use of string types such as B<MBSTRING_ASC> or B<MBSTRING_UTF8>
+is strongly recommened for the B<type> parameter. This allows the
+internal code to correctly determine the type of the field and to
+apply length checks according to the relevant standards. This is
+done using ASN1_STRING_set_by_NID().
+
+If instead an ASN1 type is used no checks are performed and the
+supplied data in B<bytes> is used directly.
+
+In X509_NAME_add_entry_by_txt() the B<field> string represents
+the field name using OBJ_txt2obj(field, 0).
+
+The B<loc> and B<set> parameters determine where a new entry should
+be added. For almost all applications B<loc> can be set to -1 and B<set>
+to 0. This adds a new entry to the end of B<name> as a single valued
+RelativeDistinguishedName (RDN).
+
+B<loc> actually determines the index where the new entry is inserted:
+if it is -1 it is appended.
+
+B<set> determines how the new type is added. If it is zero a
+new RDN is created.
+
+If B<set> is -1 or 1 it is added to the previous or next RDN
+structure respectively. This will then be a multivalued RDN:
+since multivalues RDNs are very seldom used B<set> is almost
+always set to zero.
+
+=head1 EXAMPLES
+
+Create an B<X509_NAME> structure:
+
+"C=UK, O=Disorganized Organization, CN=Joe Bloggs"
+
+ X509_NAME *nm;
+ nm = X509_NAME_new();
+ if (nm == NULL)
+ /* Some error */
+ if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
+ "C", "UK", -1, -1, 0))
+ /* Error */
+ if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
+ "O", "Disorganized Organization", -1, -1, 0))
+ /* Error */
+ if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
+ "CN", "Joe Bloggs", -1, -1, 0))
+ /* Error */
+
+=head1 RETURN VALUES
+
+X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(),
+X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for
+success of 0 if an error occurred.
+
+X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY>
+structure of B<NULL> if an error occurred.
+
+=head1 BUGS
+
+B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a
+different algorithm to determine field types. Since this form does
+not understand multicharacter types, performs no length checks and
+can result in invalid field types its use is strongly discouraged.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>
+
+=head1 HISTORY
+
+=cut
diff --git a/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod b/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod
new file mode 100644
index 000000000..333323d73
--- /dev/null
+++ b/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod
@@ -0,0 +1,106 @@
+=pod
+
+=head1 NAME
+
+X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
+X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ -
+X509_NAME lookup and enumeration functions
+
+=head1 SYNOPSIS
+
+int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos);
+int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos);
+
+int X509_NAME_entry_count(X509_NAME *name);
+X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc);
+
+int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len);
+int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len);
+
+=head1 DESCRIPTION
+
+These functions allow an B<X509_NAME> structure to be examined. The
+B<X509_NAME> structure is the same as the B<Name> type defined in
+RFC2459 (and elsewhere) and used for example in certificate subject
+and issuer names.
+
+X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve
+the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos>
+should initially be set to -1. If there are no more entries -1 is returned.
+
+X509_NAME_entry_count() returns the total number of entries in B<name>.
+
+X509_NAME_get_entry() retrieves the B<X509_NAME_ENTRY> from B<name>
+corresponding to index B<loc>. Acceptable values for B<loc> run from
+0 to (X509_NAME_entry_count(name) - 1). The value returned is an
+internal pointer which must not be freed.
+
+X509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve
+the "text" from the first entry in B<name> which matches B<nid> or
+B<obj>, if no such entry exists -1 is returned. At most B<len> bytes
+will be written and the text written to B<buf> will be null
+terminated. The length of the output string written is returned
+excluding the terminating null. If B<buf> is <NULL> then the amount
+of space needed in B<buf> (excluding the final null) is returned.
+
+=head1 NOTES
+
+X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are
+legacy functions which have various limitations which make them
+of minimal use in practice. They can only find the first matching
+entry and will copy the contents of the field verbatim: this can
+be highly confusing if the target is a muticharacter string type
+like a BMPString or a UTF8String.
+
+For a more general solution X509_NAME_get_index_by_NID() or
+X509_NAME_get_index_by_OBJ() should be used followed by
+X509_NAME_get_entry() on any matching indices and then the
+various B<X509_NAME_ENTRY> utility functions on the result.
+
+=head1 EXAMPLES
+
+Process all entries:
+
+ int i;
+ X509_NAME_ENTRY *e;
+
+ for (i = 0; i < X509_NAME_entry_count(nm); i++)
+ {
+ e = X509_NAME_get_entry(nm, i);
+ /* Do something with e */
+ }
+
+Process all commonName entries:
+
+ int loc;
+ X509_NAME_ENTRY *e;
+
+ loc = -1;
+ for (;;)
+ {
+ lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
+ if (lastpos == -1)
+ break;
+ e = X509_NAME_get_entry(nm, lastpos);
+ /* Do something with e */
+ }
+
+=head1 RETURN VALUES
+
+X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ()
+return the index of the next matching entry or -1 if not found.
+
+X509_NAME_entry_count() returns the total number of entries.
+
+X509_NAME_get_entry() returns an B<X509_NAME> pointer to the
+requested entry or B<NULL> if the index is invalid.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/X509_NAME_print_ex.pod b/openssl/doc/crypto/X509_NAME_print_ex.pod
new file mode 100644
index 000000000..2579a5dc9
--- /dev/null
+++ b/openssl/doc/crypto/X509_NAME_print_ex.pod
@@ -0,0 +1,105 @@
+=pod
+
+=head1 NAME
+
+X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print,
+X509_NAME_oneline - X509_NAME printing routines.
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509_NAME_print_ex(BIO *out, X509_NAME *nm, int indent, unsigned long flags);
+ int X509_NAME_print_ex_fp(FILE *fp, X509_NAME *nm, int indent, unsigned long flags);
+ char * X509_NAME_oneline(X509_NAME *a,char *buf,int size);
+ int X509_NAME_print(BIO *bp, X509_NAME *name, int obase);
+
+=head1 DESCRIPTION
+
+X509_NAME_print_ex() prints a human readable version of B<nm> to BIO B<out>. Each
+line (for multiline formats) is indented by B<indent> spaces. The output format
+can be extensively customised by use of the B<flags> parameter.
+
+X509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output is
+written to FILE pointer B<fp>.
+
+X509_NAME_oneline() prints an ASCII version of B<a> to B<buf>. At most B<size>
+bytes will be written. If B<buf> is B<NULL> then a buffer is dynamically allocated
+and returned, otherwise B<buf> is returned.
+
+X509_NAME_print() prints out B<name> to B<bp> indenting each line by B<obase>
+characters. Multiple lines are used if the output (including indent) exceeds
+80 characters.
+
+=head1 NOTES
+
+The functions X509_NAME_oneline() and X509_NAME_print() are legacy functions which
+produce a non standard output form, they don't handle multi character fields and
+have various quirks and inconsistencies. Their use is strongly discouraged in new
+applications.
+
+Although there are a large number of possible flags for most purposes
+B<XN_FLAG_ONELINE>, B<XN_FLAG_MULTILINE> or B<XN_FLAG_RFC2253> will suffice.
+As noted on the L<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)> manual page
+for UTF8 terminals the B<ASN1_STRFLGS_ESC_MSB> should be unset: so for example
+B<XN_FLAG_ONELINE & ~ASN1_STRFLGS_ESC_MSB> would be used.
+
+The complete set of the flags supported by X509_NAME_print_ex() is listed below.
+
+Several options can be ored together.
+
+The options B<XN_FLAG_SEP_COMMA_PLUS>, B<XN_FLAG_SEP_CPLUS_SPC>,
+B<XN_FLAG_SEP_SPLUS_SPC> and B<XN_FLAG_SEP_MULTILINE> determine the field separators
+to use. Two distinct separators are used between distinct RelativeDistinguishedName
+components and separate values in the same RDN for a multi-valued RDN. Multi-valued
+RDNs are currently very rare so the second separator will hardly ever be used.
+
+B<XN_FLAG_SEP_COMMA_PLUS> uses comma and plus as separators. B<XN_FLAG_SEP_CPLUS_SPC>
+uses comma and plus with spaces: this is more readable that plain comma and plus.
+B<XN_FLAG_SEP_SPLUS_SPC> uses spaced semicolon and plus. B<XN_FLAG_SEP_MULTILINE> uses
+spaced newline and plus respectively.
+
+If B<XN_FLAG_DN_REV> is set the whole DN is printed in reversed order.
+
+The fields B<XN_FLAG_FN_SN>, B<XN_FLAG_FN_LN>, B<XN_FLAG_FN_OID>,
+B<XN_FLAG_FN_NONE> determine how a field name is displayed. It will
+use the short name (e.g. CN) the long name (e.g. commonName) always
+use OID numerical form (normally OIDs are only used if the field name is not
+recognised) and no field name respectively.
+
+If B<XN_FLAG_SPC_EQ> is set then spaces will be placed around the '=' character
+separating field names and values.
+
+If B<XN_FLAG_DUMP_UNKNOWN_FIELDS> is set then the encoding of unknown fields is
+printed instead of the values.
+
+If B<XN_FLAG_FN_ALIGN> is set then field names are padded to 20 characters: this
+is only of use for multiline format.
+
+Additionally all the options supported by ASN1_STRING_print_ex() can be used to
+control how each field value is displayed.
+
+In addition a number options can be set for commonly used formats.
+
+B<XN_FLAG_RFC2253> sets options which produce an output compatible with RFC2253 it
+is equivalent to:
+ B<ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS>
+
+
+B<XN_FLAG_ONELINE> is a more readable one line format which is the same as:
+ B<ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN>
+
+B<XN_FLAG_MULTILINE> is a multiline format which is the same as:
+ B<ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE | XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN>
+
+B<XN_FLAG_COMPAT> uses a format identical to X509_NAME_print(): in fact it calls X509_NAME_print() internally.
+
+=head1 SEE ALSO
+
+L<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/X509_new.pod b/openssl/doc/crypto/X509_new.pod
new file mode 100644
index 000000000..fd5fc65ce
--- /dev/null
+++ b/openssl/doc/crypto/X509_new.pod
@@ -0,0 +1,37 @@
+=pod
+
+=head1 NAME
+
+X509_new, X509_free - X509 certificate ASN1 allocation functions
+
+=head1 SYNOPSIS
+
+ X509 *X509_new(void);
+ void X509_free(X509 *a);
+
+=head1 DESCRIPTION
+
+The X509 ASN1 allocation routines, allocate and free an
+X509 structure, which represents an X509 certificate.
+
+X509_new() allocates and initializes a X509 structure.
+
+X509_free() frees up the B<X509> structure B<a>.
+
+=head1 RETURN VALUES
+
+If the allocation fails, X509_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.
+
+X509_free() returns no value.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509(3)|d2i_X509(3)>
+
+=head1 HISTORY
+
+X509_new() and X509_free() are available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/openssl/doc/crypto/bio.pod b/openssl/doc/crypto/bio.pod
new file mode 100644
index 000000000..f9239226f
--- /dev/null
+++ b/openssl/doc/crypto/bio.pod
@@ -0,0 +1,54 @@
+=pod
+
+=head1 NAME
+
+bio - I/O abstraction
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+TBA
+
+
+=head1 DESCRIPTION
+
+A BIO is an I/O abstraction, it hides many of the underlying I/O
+details from an application. If an application uses a BIO for its
+I/O it can transparently handle SSL connections, unencrypted network
+connections and file I/O.
+
+There are two type of BIO, a source/sink BIO and a filter BIO.
+
+As its name implies a source/sink BIO is a source and/or sink of data,
+examples include a socket BIO and a file BIO.
+
+A filter BIO takes data from one BIO and passes it through to
+another, or the application. The data may be left unmodified (for
+example a message digest BIO) or translated (for example an
+encryption BIO). The effect of a filter BIO may change according
+to the I/O operation it is performing: for example an encryption
+BIO will encrypt data if it is being written to and decrypt data
+if it is being read from.
+
+BIOs can be joined together to form a chain (a single BIO is a chain
+with one component). A chain normally consist of one source/sink
+BIO and one or more filter BIOs. Data read from or written to the
+first BIO then traverses the chain to the end (normally a source/sink
+BIO).
+
+=head1 SEE ALSO
+
+L<BIO_ctrl(3)|BIO_ctrl(3)>,
+L<BIO_f_base64(3)|BIO_f_base64(3)>, L<BIO_f_buffer(3)|BIO_f_buffer(3)>,
+L<BIO_f_cipher(3)|BIO_f_cipher(3)>, L<BIO_f_md(3)|BIO_f_md(3)>,
+L<BIO_f_null(3)|BIO_f_null(3)>, L<BIO_f_ssl(3)|BIO_f_ssl(3)>,
+L<BIO_find_type(3)|BIO_find_type(3)>, L<BIO_new(3)|BIO_new(3)>,
+L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>,
+L<BIO_push(3)|BIO_push(3)>, L<BIO_read(3)|BIO_read(3)>,
+L<BIO_s_accept(3)|BIO_s_accept(3)>, L<BIO_s_bio(3)|BIO_s_bio(3)>,
+L<BIO_s_connect(3)|BIO_s_connect(3)>, L<BIO_s_fd(3)|BIO_s_fd(3)>,
+L<BIO_s_file(3)|BIO_s_file(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>,
+L<BIO_s_null(3)|BIO_s_null(3)>, L<BIO_s_socket(3)|BIO_s_socket(3)>,
+L<BIO_set_callback(3)|BIO_set_callback(3)>,
+L<BIO_should_retry(3)|BIO_should_retry(3)>
diff --git a/openssl/doc/crypto/blowfish.pod b/openssl/doc/crypto/blowfish.pod
new file mode 100644
index 000000000..5b2d274c1
--- /dev/null
+++ b/openssl/doc/crypto/blowfish.pod
@@ -0,0 +1,112 @@
+=pod
+
+=head1 NAME
+
+blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt,
+BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption
+
+=head1 SYNOPSIS
+
+ #include <openssl/blowfish.h>
+
+ void BF_set_key(BF_KEY *key, int len, const unsigned char *data);
+
+ void BF_ecb_encrypt(const unsigned char *in, unsigned char *out,
+ BF_KEY *key, int enc);
+ void BF_cbc_encrypt(const unsigned char *in, unsigned char *out,
+ long length, BF_KEY *schedule, unsigned char *ivec, int enc);
+ void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, BF_KEY *schedule, unsigned char *ivec, int *num,
+ int enc);
+ void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, BF_KEY *schedule, unsigned char *ivec, int *num);
+ const char *BF_options(void);
+
+ void BF_encrypt(BF_LONG *data,const BF_KEY *key);
+ void BF_decrypt(BF_LONG *data,const BF_KEY *key);
+
+=head1 DESCRIPTION
+
+This library implements the Blowfish cipher, which was invented and described
+by Counterpane (see http://www.counterpane.com/blowfish.html ).
+
+Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data.
+It uses a variable size key, but typically, 128 bit (16 byte) keys are
+considered good for strong encryption. Blowfish can be used in the same
+modes as DES (see L<des_modes(7)|des_modes(7)>). Blowfish is currently one
+of the faster block ciphers. It is quite a bit faster than DES, and much
+faster than IDEA or RC2.
+
+Blowfish consists of a key setup phase and the actual encryption or decryption
+phase.
+
+BF_set_key() sets up the B<BF_KEY> B<key> using the B<len> bytes long key
+at B<data>.
+
+BF_ecb_encrypt() is the basic Blowfish encryption and decryption function.
+It encrypts or decrypts the first 64 bits of B<in> using the key B<key>,
+putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
+or decryption (B<BF_DECRYPT>) shall be performed. The vector pointed at by
+B<in> and B<out> must be 64 bits in length, no less. If they are larger,
+everything after the first 64 bits is ignored.
+
+The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt()
+all operate on variable length data. They all take an initialization vector
+B<ivec> which needs to be passed along into the next call of the same function
+for the same message. B<ivec> may be initialized with anything, but the
+recipient needs to know what it was initialized with, or it won't be able
+to decrypt. Some programs and protocols simplify this, like SSH, where
+B<ivec> is simply initialized to zero.
+BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while
+BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable
+number of bytes (the amount does not have to be an exact multiple of 8). The
+purpose of the latter two is to simulate stream ciphers, and therefore, they
+need the parameter B<num>, which is a pointer to an integer where the current
+offset in B<ivec> is stored between calls. This integer must be initialized
+to zero when B<ivec> is initialized.
+
+BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It
+encrypts or decrypts the 64 bits chunks of B<in> using the key B<schedule>,
+putting the result in B<out>. B<enc> decides if encryption (BF_ENCRYPT) or
+decryption (BF_DECRYPT) shall be performed. B<ivec> must point at an 8 byte
+long initialization vector.
+
+BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback.
+It encrypts or decrypts the bytes in B<in> using the key B<schedule>,
+putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
+or decryption (B<BF_DECRYPT>) shall be performed. B<ivec> must point at an
+8 byte long initialization vector. B<num> must point at an integer which must
+be initially zero.
+
+BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback.
+It uses the same parameters as BF_cfb64_encrypt(), which must be initialized
+the same way.
+
+BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish
+encryption. They encrypt/decrypt the first 64 bits of the vector pointed by
+B<data>, using the key B<key>. These functions should not be used unless you
+implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt().
+If you still want to use these functions, you should be aware that they take
+each 32-bit chunk in host-byte order, which is little-endian on little-endian
+platforms and big-endian on big-endian ones.
+
+=head1 RETURN VALUES
+
+None of the functions presented here return any value.
+
+=head1 NOTE
+
+Applications should use the higher level functions
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling the
+blowfish functions directly.
+
+=head1 SEE ALSO
+
+L<des_modes(7)|des_modes(7)>
+
+=head1 HISTORY
+
+The Blowfish functions are available in all versions of SSLeay and OpenSSL.
+
+=cut
+
diff --git a/openssl/doc/crypto/bn.pod b/openssl/doc/crypto/bn.pod
new file mode 100644
index 000000000..cd2f8e50c
--- /dev/null
+++ b/openssl/doc/crypto/bn.pod
@@ -0,0 +1,181 @@
+=pod
+
+=head1 NAME
+
+bn - multiprecision integer arithmetics
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BIGNUM *BN_new(void);
+ void BN_free(BIGNUM *a);
+ void BN_init(BIGNUM *);
+ void BN_clear(BIGNUM *a);
+ void BN_clear_free(BIGNUM *a);
+
+ BN_CTX *BN_CTX_new(void);
+ void BN_CTX_init(BN_CTX *c);
+ void BN_CTX_free(BN_CTX *c);
+
+ BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b);
+ BIGNUM *BN_dup(const BIGNUM *a);
+
+ BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b);
+
+ int BN_num_bytes(const BIGNUM *a);
+ int BN_num_bits(const BIGNUM *a);
+ int BN_num_bits_word(BN_ULONG w);
+
+ void BN_set_negative(BIGNUM *a, int n);
+ int BN_is_negative(const BIGNUM *a);
+
+ 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 *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
+ int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+ BN_CTX *ctx);
+ int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+ BN_CTX *ctx);
+ int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+ BN_CTX *ctx);
+ int BN_mod_sqr(BIGNUM *ret, 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);
+
+ 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);
+
+ 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);
+
+ 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);
+
+ 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);
+
+ BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add,
+ BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);
+ int BN_is_prime(const BIGNUM *p, int nchecks,
+ void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);
+
+ 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);
+
+ 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);
+
+ BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,
+ BN_CTX *ctx);
+
+ 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_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,
+ BN_RECP_CTX *recp, BN_CTX *ctx);
+
+ 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);
+
+ 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
+
+This library performs arithmetic operations on integers of arbitrary
+size. It was written for use in public key cryptography, such as RSA
+and Diffie-Hellman.
+
+It uses dynamic memory allocation for storing its data structures.
+That means that there is no limit on the size of the numbers
+manipulated by these functions, but return values must always be
+checked in case a memory allocation error has occurred.
+
+The basic object in this library is a B<BIGNUM>. It is used to hold a
+single large integer. This type should be considered opaque and fields
+should not be modified or accessed directly.
+
+The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>;
+L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations.
+Comparison is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)>
+describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of
+random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime
+numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion
+of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>.
+
+=head1 SEE ALSO
+
+L<bn_internal(3)|bn_internal(3)>,
+L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,
+L<BN_new(3)|BN_new(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>,
+L<BN_copy(3)|BN_copy(3)>, L<BN_swap(3)|BN_swap(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>,
+L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>,
+L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>,
+L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>,
+L<BN_bn2bin(3)|BN_bn2bin(3)>, L<BN_mod_inverse(3)|BN_mod_inverse(3)>,
+L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>,
+L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>,
+L<BN_BLINDING_new(3)|BN_BLINDING_new(3)>
+
+=cut
diff --git a/openssl/doc/crypto/bn_internal.pod b/openssl/doc/crypto/bn_internal.pod
new file mode 100644
index 000000000..891914678
--- /dev/null
+++ b/openssl/doc/crypto/bn_internal.pod
@@ -0,0 +1,226 @@
+=pod
+
+=head1 NAME
+
+bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words,
+bn_add_words, bn_sub_words, bn_mul_comba4, bn_mul_comba8,
+bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal,
+bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive,
+bn_mul_low_recursive, bn_mul_high, bn_sqr_normal, bn_sqr_recursive,
+bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top,
+bn_print, bn_dump, bn_set_max, bn_set_high, bn_set_low - BIGNUM
+library internal functions
+
+=head1 SYNOPSIS
+
+ BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w);
+ BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num,
+ BN_ULONG w);
+ void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num);
+ BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d);
+ BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp,
+ int num);
+ BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp,
+ int num);
+
+ void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b);
+ void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b);
+ void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a);
+ void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a);
+
+ int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n);
+
+ void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b,
+ int nb);
+ void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n);
+ void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2,
+ int dna,int dnb,BN_ULONG *tmp);
+ void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b,
+ int n, int tna,int tnb, BN_ULONG *tmp);
+ void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b,
+ int n2, BN_ULONG *tmp);
+ void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l,
+ int n2, BN_ULONG *tmp);
+
+ void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp);
+ void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp);
+
+ void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c);
+ void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c);
+ void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a);
+
+ BIGNUM *bn_expand(BIGNUM *a, int bits);
+ BIGNUM *bn_wexpand(BIGNUM *a, int n);
+ BIGNUM *bn_expand2(BIGNUM *a, int n);
+ void bn_fix_top(BIGNUM *a);
+
+ void bn_check_top(BIGNUM *a);
+ void bn_print(BIGNUM *a);
+ void bn_dump(BN_ULONG *d, int n);
+ void bn_set_max(BIGNUM *a);
+ void bn_set_high(BIGNUM *r, BIGNUM *a, int n);
+ void bn_set_low(BIGNUM *r, BIGNUM *a, int n);
+
+=head1 DESCRIPTION
+
+This page documents the internal functions used by the OpenSSL
+B<BIGNUM> implementation. They are described here to facilitate
+debugging and extending the library. They are I<not> to be used by
+applications.
+
+=head2 The BIGNUM structure
+
+ typedef struct bignum_st
+ {
+ int top; /* number of words used in d */
+ BN_ULONG *d; /* pointer to an array containing the integer value */
+ int max; /* size of the d array */
+ int neg; /* sign */
+ } BIGNUM;
+
+The integer value is stored in B<d>, a malloc()ed array of words (B<BN_ULONG>),
+least significant word first. A B<BN_ULONG> can be either 16, 32 or 64 bits
+in size, depending on the 'number of bits' (B<BITS2>) specified in
+C<openssl/bn.h>.
+
+B<max> is the size of the B<d> array that has been allocated. B<top>
+is the number of words being used, so for a value of 4, bn.d[0]=4 and
+bn.top=1. B<neg> is 1 if the number is negative. When a B<BIGNUM> is
+B<0>, the B<d> field can be B<NULL> and B<top> == B<0>.
+
+Various routines in this library require the use of temporary
+B<BIGNUM> variables during their execution. 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. This structure contains B<BN_CTX_NUM> B<BIGNUM>s, see
+L<BN_CTX_start(3)|BN_CTX_start(3)>.
+
+=head2 Low-level arithmetic operations
+
+These functions are implemented in C and for several platforms in
+assembly language:
+
+bn_mul_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> word
+arrays B<rp> and B<ap>. It computes B<ap> * B<w>, places the result
+in B<rp>, and returns the high word (carry).
+
+bn_mul_add_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num>
+word arrays B<rp> and B<ap>. It computes B<ap> * B<w> + B<rp>, places
+the result in B<rp>, and returns the high word (carry).
+
+bn_sqr_words(B<rp>, B<ap>, B<n>) operates on the B<num> word array
+B<ap> and the 2*B<num> word array B<ap>. It computes B<ap> * B<ap>
+word-wise, and places the low and high bytes of the result in B<rp>.
+
+bn_div_words(B<h>, B<l>, B<d>) divides the two word number (B<h>,B<l>)
+by B<d> and returns the result.
+
+bn_add_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word
+arrays B<ap>, B<bp> and B<rp>. It computes B<ap> + B<bp>, places the
+result in B<rp>, and returns the high word (carry).
+
+bn_sub_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word
+arrays B<ap>, B<bp> and B<rp>. It computes B<ap> - B<bp>, places the
+result in B<rp>, and returns the carry (1 if B<bp> E<gt> B<ap>, 0
+otherwise).
+
+bn_mul_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and
+B<b> and the 8 word array B<r>. It computes B<a>*B<b> and places the
+result in B<r>.
+
+bn_mul_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and
+B<b> and the 16 word array B<r>. It computes B<a>*B<b> and places the
+result in B<r>.
+
+bn_sqr_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and
+B<b> and the 8 word array B<r>.
+
+bn_sqr_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and
+B<b> and the 16 word array B<r>.
+
+The following functions are implemented in C:
+
+bn_cmp_words(B<a>, B<b>, B<n>) operates on the B<n> word arrays B<a>
+and B<b>. It returns 1, 0 and -1 if B<a> is greater than, equal and
+less than B<b>.
+
+bn_mul_normal(B<r>, B<a>, B<na>, B<b>, B<nb>) operates on the B<na>
+word array B<a>, the B<nb> word array B<b> and the B<na>+B<nb> word
+array B<r>. It computes B<a>*B<b> and places the result in B<r>.
+
+bn_mul_low_normal(B<r>, B<a>, B<b>, B<n>) operates on the B<n> word
+arrays B<r>, B<a> and B<b>. It computes the B<n> low words of
+B<a>*B<b> and places the result in B<r>.
+
+bn_mul_recursive(B<r>, B<a>, B<b>, B<n2>, B<dna>, B<dnb>, B<t>) operates
+on the word arrays B<a> and B<b> of length B<n2>+B<dna> and B<n2>+B<dnb>
+(B<dna> and B<dnb> are currently allowed to be 0 or negative) and the 2*B<n2>
+word arrays B<r> and B<t>. B<n2> must be a power of 2. It computes
+B<a>*B<b> and places the result in B<r>.
+
+bn_mul_part_recursive(B<r>, B<a>, B<b>, B<n>, B<tna>, B<tnb>, B<tmp>)
+operates on the word arrays B<a> and B<b> of length B<n>+B<tna> and
+B<n>+B<tnb> and the 4*B<n> word arrays B<r> and B<tmp>.
+
+bn_mul_low_recursive(B<r>, B<a>, B<b>, B<n2>, B<tmp>) operates on the
+B<n2> word arrays B<r> and B<tmp> and the B<n2>/2 word arrays B<a>
+and B<b>.
+
+bn_mul_high(B<r>, B<a>, B<b>, B<l>, B<n2>, B<tmp>) operates on the
+B<n2> word arrays B<r>, B<a>, B<b> and B<l> (?) and the 3*B<n2> word
+array B<tmp>.
+
+BN_mul() calls bn_mul_normal(), or an optimized implementation if the
+factors have the same size: bn_mul_comba8() is used if they are 8
+words long, bn_mul_recursive() if they are larger than
+B<BN_MULL_SIZE_NORMAL> and the size is an exact multiple of the word
+size, and bn_mul_part_recursive() for others that are larger than
+B<BN_MULL_SIZE_NORMAL>.
+
+bn_sqr_normal(B<r>, B<a>, B<n>, B<tmp>) operates on the B<n> word array
+B<a> and the 2*B<n> word arrays B<tmp> and B<r>.
+
+The implementations use the following macros which, depending on the
+architecture, may use "long long" C operations or inline assembler.
+They are defined in C<bn_lcl.h>.
+
+mul(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<c> and places the
+low word of the result in B<r> and the high word in B<c>.
+
+mul_add(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<r>+B<c> and
+places the low word of the result in B<r> and the high word in B<c>.
+
+sqr(B<r0>, B<r1>, B<a>) computes B<a>*B<a> and places the low word
+of the result in B<r0> and the high word in B<r1>.
+
+=head2 Size changes
+
+bn_expand() ensures that B<b> has enough space for a B<bits> bit
+number. bn_wexpand() ensures that B<b> has enough space for an
+B<n> word number. If the number has to be expanded, both macros
+call bn_expand2(), which allocates a new B<d> array and copies the
+data. They return B<NULL> on error, B<b> otherwise.
+
+The bn_fix_top() macro reduces B<a-E<gt>top> to point to the most
+significant non-zero word plus one when B<a> has shrunk.
+
+=head2 Debugging
+
+bn_check_top() verifies that C<((a)-E<gt>top E<gt>= 0 && (a)-E<gt>top
+E<lt>= (a)-E<gt>max)>. A violation will cause the program to abort.
+
+bn_print() prints B<a> to stderr. bn_dump() prints B<n> words at B<d>
+(in reverse order, i.e. most significant word first) to stderr.
+
+bn_set_max() makes B<a> a static number with a B<max> of its current size.
+This is used by bn_set_low() and bn_set_high() to make B<r> a read-only
+B<BIGNUM> that contains the B<n> low or high words of B<a>.
+
+If B<BN_DEBUG> is not defined, bn_check_top(), bn_print(), bn_dump()
+and bn_set_max() are defined as empty macros.
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>
+
+=cut
diff --git a/openssl/doc/crypto/buffer.pod b/openssl/doc/crypto/buffer.pod
new file mode 100644
index 000000000..781f5b11e
--- /dev/null
+++ b/openssl/doc/crypto/buffer.pod
@@ -0,0 +1,73 @@
+=pod
+
+=head1 NAME
+
+BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - simple
+character arrays structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/buffer.h>
+
+ BUF_MEM *BUF_MEM_new(void);
+
+ void BUF_MEM_free(BUF_MEM *a);
+
+ int BUF_MEM_grow(BUF_MEM *str, int len);
+
+ char * BUF_strdup(const char *str);
+
+=head1 DESCRIPTION
+
+The buffer library handles simple character arrays. Buffers are used for
+various purposes in the library, most notably memory BIOs.
+
+The library uses the BUF_MEM structure defined in buffer.h:
+
+ typedef struct buf_mem_st
+ {
+ int length; /* current number of bytes */
+ char *data;
+ int max; /* size of buffer */
+ } BUF_MEM;
+
+B<length> is the current size of the buffer in bytes, B<max> is the amount of
+memory allocated to the buffer. There are three functions which handle these
+and one "miscellaneous" function.
+
+BUF_MEM_new() allocates a new buffer of zero size.
+
+BUF_MEM_free() frees up an already existing buffer. The data is zeroed
+before freeing up in case the buffer contains sensitive data.
+
+BUF_MEM_grow() changes the size of an already existing buffer to
+B<len>. Any data already in the buffer is preserved if it increases in
+size.
+
+BUF_strdup() copies a null terminated string into a block of allocated
+memory and returns a pointer to the allocated block.
+Unlike the standard C library strdup() this function uses OPENSSL_malloc() and so
+should be used in preference to the standard library strdup() because it can
+be used for memory leak checking or replacing the malloc() function.
+
+The memory allocated from BUF_strdup() should be freed up using the OPENSSL_free()
+function.
+
+=head1 RETURN VALUES
+
+BUF_MEM_new() returns the buffer or NULL on error.
+
+BUF_MEM_free() has no return value.
+
+BUF_MEM_grow() returns zero on error or the new size (i.e. B<len>).
+
+=head1 SEE ALSO
+
+L<bio(3)|bio(3)>
+
+=head1 HISTORY
+
+BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all
+versions of SSLeay and OpenSSL. BUF_strdup() was added in SSLeay 0.8.
+
+=cut
diff --git a/openssl/doc/crypto/crypto.pod b/openssl/doc/crypto/crypto.pod
new file mode 100644
index 000000000..7a527992b
--- /dev/null
+++ b/openssl/doc/crypto/crypto.pod
@@ -0,0 +1,85 @@
+=pod
+
+=head1 NAME
+
+crypto - OpenSSL cryptographic library
+
+=head1 SYNOPSIS
+
+=head1 DESCRIPTION
+
+The OpenSSL B<crypto> library implements a wide range of cryptographic
+algorithms used in various Internet standards. The services provided
+by this library are used by the OpenSSL implementations of SSL, TLS
+and S/MIME, and they have also been used to implement SSH, OpenPGP, and
+other cryptographic standards.
+
+=head1 OVERVIEW
+
+B<libcrypto> consists of a number of sub-libraries that implement the
+individual algorithms.
+
+The functionality includes symmetric encryption, public key
+cryptography and key agreement, certificate handling, cryptographic
+hash functions and a cryptographic pseudo-random number generator.
+
+=over 4
+
+=item SYMMETRIC CIPHERS
+
+L<blowfish(3)|blowfish(3)>, L<cast(3)|cast(3)>, L<des(3)|des(3)>,
+L<idea(3)|idea(3)>, L<rc2(3)|rc2(3)>, L<rc4(3)|rc4(3)>, L<rc5(3)|rc5(3)>
+
+=item PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT
+
+L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rsa(3)|rsa(3)>
+
+=item CERTIFICATES
+
+L<x509(3)|x509(3)>, L<x509v3(3)|x509v3(3)>
+
+=item AUTHENTICATION CODES, HASH FUNCTIONS
+
+L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, L<md4(3)|md4(3)>,
+L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
+L<sha(3)|sha(3)>
+
+=item AUXILIARY FUNCTIONS
+
+L<err(3)|err(3)>, L<threads(3)|threads(3)>, L<rand(3)|rand(3)>,
+L<OPENSSL_VERSION_NUMBER(3)|OPENSSL_VERSION_NUMBER(3)>
+
+=item INPUT/OUTPUT, DATA ENCODING
+
+L<asn1(3)|asn1(3)>, L<bio(3)|bio(3)>, L<evp(3)|evp(3)>, L<pem(3)|pem(3)>,
+L<pkcs7(3)|pkcs7(3)>, L<pkcs12(3)|pkcs12(3)>
+
+=item INTERNAL FUNCTIONS
+
+L<bn(3)|bn(3)>, L<buffer(3)|buffer(3)>, L<lhash(3)|lhash(3)>,
+L<objects(3)|objects(3)>, L<stack(3)|stack(3)>,
+L<txt_db(3)|txt_db(3)>
+
+=back
+
+=head1 NOTES
+
+Some of the newer functions follow a naming convention using the numbers
+B<0> and B<1>. For example the functions:
+
+ int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
+ int X509_add1_trust_object(X509 *x, ASN1_OBJECT *obj);
+
+The B<0> version uses the supplied structure pointer directly
+in the parent and it will be freed up when the parent is freed.
+In the above example B<crl> would be freed but B<rev> would not.
+
+The B<1> function uses a copy of the supplied structure pointer
+(or in some cases increases its link count) in the parent and
+so both (B<x> and B<obj> above) should be freed up.
+
+=head1 SEE ALSO
+
+L<openssl(1)|openssl(1)>, L<ssl(3)|ssl(3)>
+
+=cut
diff --git a/openssl/doc/crypto/d2i_ASN1_OBJECT.pod b/openssl/doc/crypto/d2i_ASN1_OBJECT.pod
new file mode 100644
index 000000000..45bb18492
--- /dev/null
+++ b/openssl/doc/crypto/d2i_ASN1_OBJECT.pod
@@ -0,0 +1,29 @@
+=pod
+
+=head1 NAME
+
+d2i_ASN1_OBJECT, i2d_ASN1_OBJECT - ASN1 OBJECT IDENTIFIER functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/objects.h>
+
+ ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **a, unsigned char **pp, long length);
+ int i2d_ASN1_OBJECT(ASN1_OBJECT *a, unsigned char **pp);
+
+=head1 DESCRIPTION
+
+These functions decode and encode an ASN1 OBJECT IDENTIFIER.
+
+Othewise these behave in a similar way to d2i_X509() and i2d_X509()
+described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)|d2i_X509(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/d2i_DHparams.pod b/openssl/doc/crypto/d2i_DHparams.pod
new file mode 100644
index 000000000..1e98aebec
--- /dev/null
+++ b/openssl/doc/crypto/d2i_DHparams.pod
@@ -0,0 +1,30 @@
+=pod
+
+=head1 NAME
+
+d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ DH *d2i_DHparams(DH **a, unsigned char **pp, long length);
+ int i2d_DHparams(DH *a, unsigned char **pp);
+
+=head1 DESCRIPTION
+
+These functions decode and encode PKCS#3 DH parameters using the
+DHparameter structure described in PKCS#3.
+
+Othewise these behave in a similar way to d2i_X509() and i2d_X509()
+described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)|d2i_X509(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/d2i_DSAPublicKey.pod b/openssl/doc/crypto/d2i_DSAPublicKey.pod
new file mode 100644
index 000000000..22c1b50f2
--- /dev/null
+++ b/openssl/doc/crypto/d2i_DSAPublicKey.pod
@@ -0,0 +1,83 @@
+=pod
+
+=head1 NAME
+
+d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey,
+d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding
+and parsing functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+ #include <openssl/x509.h>
+
+ DSA * d2i_DSAPublicKey(DSA **a, const unsigned char **pp, long length);
+
+ int i2d_DSAPublicKey(const DSA *a, unsigned char **pp);
+
+ DSA * d2i_DSA_PUBKEY(DSA **a, const unsigned char **pp, long length);
+
+ int i2d_DSA_PUBKEY(const DSA *a, unsigned char **pp);
+
+ DSA * d2i_DSAPrivateKey(DSA **a, const unsigned char **pp, long length);
+
+ int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp);
+
+ DSA * d2i_DSAparams(DSA **a, const unsigned char **pp, long length);
+
+ int i2d_DSAparams(const DSA *a, unsigned char **pp);
+
+ DSA * d2i_DSA_SIG(DSA_SIG **a, const unsigned char **pp, long length);
+
+ int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp);
+
+=head1 DESCRIPTION
+
+d2i_DSAPublicKey() and i2d_DSAPublicKey() decode and encode the DSA public key
+components structure.
+
+d2i_DSA_PUBKEY() and i2d_DSA_PUBKEY() decode and encode an DSA public key using
+a SubjectPublicKeyInfo (certificate public key) structure.
+
+d2i_DSAPrivateKey(), i2d_DSAPrivateKey() decode and encode the DSA private key
+components.
+
+d2i_DSAparams(), i2d_DSAparams() decode and encode the DSA parameters using
+a B<Dss-Parms> structure as defined in RFC2459.
+
+d2i_DSA_SIG(), i2d_DSA_SIG() decode and encode a DSA signature using a
+B<Dss-Sig-Value> structure as defined in RFC2459.
+
+The usage of all of these functions is similar to the d2i_X509() and
+i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
+
+=head1 NOTES
+
+The B<DSA> structure passed to the private key encoding functions should have
+all the private key components present.
+
+The data encoded by the private key functions is unencrypted and therefore
+offers no private key security.
+
+The B<DSA_PUBKEY> functions should be used in preference to the B<DSAPublicKey>
+functions when encoding public keys because they use a standard format.
+
+The B<DSAPublicKey> functions use an non standard format the actual data encoded
+depends on the value of the B<write_params> field of the B<a> key parameter.
+If B<write_params> is zero then only the B<pub_key> field is encoded as an
+B<INTEGER>. If B<write_params> is 1 then a B<SEQUENCE> consisting of the
+B<p>, B<q>, B<g> and B<pub_key> respectively fields are encoded.
+
+The B<DSAPrivateKey> functions also use a non standard structure consiting
+consisting of a SEQUENCE containing the B<p>, B<q>, B<g> and B<pub_key> and
+B<priv_key> fields respectively.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)|d2i_X509(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/d2i_PKCS8PrivateKey.pod b/openssl/doc/crypto/d2i_PKCS8PrivateKey.pod
new file mode 100644
index 000000000..a54b77908
--- /dev/null
+++ b/openssl/doc/crypto/d2i_PKCS8PrivateKey.pod
@@ -0,0 +1,56 @@
+=pod
+
+=head1 NAME
+
+d2i_PKCS8PrivateKey_bio, d2i_PKCS8PrivateKey_fp,
+i2d_PKCS8PrivateKey_bio, i2d_PKCS8PrivateKey_fp,
+i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp - PKCS#8 format private key functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u);
+ EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u);
+
+ int i2d_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int i2d_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+=head1 DESCRIPTION
+
+The PKCS#8 functions encode and decode private keys in PKCS#8 format using both
+PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption algorithms.
+
+Other than the use of DER as opposed to PEM these functions are identical to the
+corresponding B<PEM> function as described in the L<pem(3)|pem(3)> manual page.
+
+=head1 NOTES
+
+Before using these functions L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>
+should be called to initialize the internal algorithm lookup tables otherwise errors about
+unknown algorithms will occur if an attempt is made to decrypt a private key.
+
+These functions are currently the only way to store encrypted private keys using DER format.
+
+Currently all the functions use BIOs or FILE pointers, there are no functions which
+work directly on memory: this can be readily worked around by converting the buffers
+to memory BIOs, see L<BIO_s_mem(3)|BIO_s_mem(3)> for details.
+
+=head1 SEE ALSO
+
+L<pem(3)|pem(3)>
+
+=cut
diff --git a/openssl/doc/crypto/d2i_RSAPublicKey.pod b/openssl/doc/crypto/d2i_RSAPublicKey.pod
new file mode 100644
index 000000000..279b29c87
--- /dev/null
+++ b/openssl/doc/crypto/d2i_RSAPublicKey.pod
@@ -0,0 +1,67 @@
+=pod
+
+=head1 NAME
+
+d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey,
+d2i_RSA_PUBKEY, i2d_RSA_PUBKEY, i2d_Netscape_RSA,
+d2i_Netscape_RSA - RSA public and private key encoding functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+ #include <openssl/x509.h>
+
+ RSA * d2i_RSAPublicKey(RSA **a, unsigned char **pp, long length);
+
+ int i2d_RSAPublicKey(RSA *a, unsigned char **pp);
+
+ RSA * d2i_RSA_PUBKEY(RSA **a, unsigned char **pp, long length);
+
+ int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp);
+
+ RSA * d2i_RSAPrivateKey(RSA **a, unsigned char **pp, long length);
+
+ int i2d_RSAPrivateKey(RSA *a, unsigned char **pp);
+
+ int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
+
+ RSA * d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)());
+
+=head1 DESCRIPTION
+
+d2i_RSAPublicKey() and i2d_RSAPublicKey() decode and encode a PKCS#1 RSAPublicKey
+structure.
+
+d2i_RSA_PUBKEY() and i2d_RSA_PUBKEY() decode and encode an RSA public key using
+a SubjectPublicKeyInfo (certificate public key) structure.
+
+d2i_RSAPrivateKey(), i2d_RSAPrivateKey() decode and encode a PKCS#1 RSAPrivateKey
+structure.
+
+d2i_Netscape_RSA(), i2d_Netscape_RSA() decode and encode an RSA private key in
+NET format.
+
+The usage of all of these functions is similar to the d2i_X509() and
+i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
+
+=head1 NOTES
+
+The B<RSA> structure passed to the private key encoding functions should have
+all the PKCS#1 private key components present.
+
+The data encoded by the private key functions is unencrypted and therefore
+offers no private key security.
+
+The NET format functions are present to provide compatibility with certain very
+old software. This format has some severe security weaknesses and should be
+avoided if possible.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)|d2i_X509(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/d2i_X509.pod b/openssl/doc/crypto/d2i_X509.pod
new file mode 100644
index 000000000..5bfa18afb
--- /dev/null
+++ b/openssl/doc/crypto/d2i_X509.pod
@@ -0,0 +1,231 @@
+=pod
+
+=head1 NAME
+
+d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio,
+i2d_X509_fp - X509 encode and decode functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509 *d2i_X509(X509 **px, const unsigned char **in, int len);
+ int i2d_X509(X509 *x, unsigned char **out);
+
+ X509 *d2i_X509_bio(BIO *bp, X509 **x);
+ X509 *d2i_X509_fp(FILE *fp, X509 **x);
+
+ int i2d_X509_bio(X509 *x, BIO *bp);
+ int i2d_X509_fp(X509 *x, FILE *fp);
+
+=head1 DESCRIPTION
+
+The X509 encode and decode routines encode and parse an
+B<X509> structure, which represents an X509 certificate.
+
+d2i_X509() attempts to decode B<len> bytes at B<*in>. If
+successful a pointer to the B<X509> structure is returned. If an error
+occurred then B<NULL> is returned. If B<px> is not B<NULL> then the
+returned structure is written to B<*px>. If B<*px> is not B<NULL>
+then it is assumed that B<*px> contains a valid B<X509>
+structure and an attempt is made to reuse it. If the call is
+successful B<*in> is incremented to the byte following the
+parsed data.
+
+i2d_X509() encodes the structure pointed to by B<x> into DER format.
+If B<out> is not B<NULL> is writes the DER encoded data to the buffer
+at B<*out>, and increments it to point after the data just written.
+If the return value is negative an error occurred, otherwise it
+returns the length of the encoded data.
+
+For OpenSSL 0.9.7 and later if B<*out> is B<NULL> memory will be
+allocated for a buffer and the encoded data written to it. In this
+case B<*out> is not incremented and it points to the start of the
+data just written.
+
+d2i_X509_bio() is similar to d2i_X509() except it attempts
+to parse data from BIO B<bp>.
+
+d2i_X509_fp() is similar to d2i_X509() except it attempts
+to parse data from FILE pointer B<fp>.
+
+i2d_X509_bio() is similar to i2d_X509() except it writes
+the encoding of the structure B<x> to BIO B<bp> and it
+returns 1 for success and 0 for failure.
+
+i2d_X509_fp() is similar to i2d_X509() except it writes
+the encoding of the structure B<x> to BIO B<bp> and it
+returns 1 for success and 0 for failure.
+
+=head1 NOTES
+
+The letters B<i> and B<d> in for example B<i2d_X509> stand for
+"internal" (that is an internal C structure) and "DER". So that
+B<i2d_X509> converts from internal to DER.
+
+The functions can also understand B<BER> forms.
+
+The actual X509 structure passed to i2d_X509() must be a valid
+populated B<X509> structure it can B<not> simply be fed with an
+empty structure such as that returned by X509_new().
+
+The encoded data is in binary form and may contain embedded zeroes.
+Therefore any FILE pointers or BIOs should be opened in binary mode.
+Functions such as B<strlen()> will B<not> return the correct length
+of the encoded structure.
+
+The ways that B<*in> and B<*out> are incremented after the operation
+can trap the unwary. See the B<WARNINGS> section for some common
+errors.
+
+The reason for the auto increment behaviour is to reflect a typical
+usage of ASN1 functions: after one structure is encoded or decoded
+another will processed after it.
+
+=head1 EXAMPLES
+
+Allocate and encode the DER encoding of an X509 structure:
+
+ int len;
+ unsigned char *buf, *p;
+
+ len = i2d_X509(x, NULL);
+
+ buf = OPENSSL_malloc(len);
+
+ if (buf == NULL)
+ /* error */
+
+ p = buf;
+
+ i2d_X509(x, &p);
+
+If you are using OpenSSL 0.9.7 or later then this can be
+simplified to:
+
+
+ int len;
+ unsigned char *buf;
+
+ buf = NULL;
+
+ len = i2d_X509(x, &buf);
+
+ if (len < 0)
+ /* error */
+
+Attempt to decode a buffer:
+
+ X509 *x;
+
+ unsigned char *buf, *p;
+
+ int len;
+
+ /* Something to setup buf and len */
+
+ p = buf;
+
+ x = d2i_X509(NULL, &p, len);
+
+ if (x == NULL)
+ /* Some error */
+
+Alternative technique:
+
+ X509 *x;
+
+ unsigned char *buf, *p;
+
+ int len;
+
+ /* Something to setup buf and len */
+
+ p = buf;
+
+ x = NULL;
+
+ if(!d2i_X509(&x, &p, len))
+ /* Some error */
+
+
+=head1 WARNINGS
+
+The use of temporary variable is mandatory. A common
+mistake is to attempt to use a buffer directly as follows:
+
+ int len;
+ unsigned char *buf;
+
+ len = i2d_X509(x, NULL);
+
+ buf = OPENSSL_malloc(len);
+
+ if (buf == NULL)
+ /* error */
+
+ i2d_X509(x, &buf);
+
+ /* Other stuff ... */
+
+ OPENSSL_free(buf);
+
+This code will result in B<buf> apparently containing garbage because
+it was incremented after the call to point after the data just written.
+Also B<buf> will no longer contain the pointer allocated by B<OPENSSL_malloc()>
+and the subsequent call to B<OPENSSL_free()> may well crash.
+
+The auto allocation feature (setting buf to NULL) only works on OpenSSL
+0.9.7 and later. Attempts to use it on earlier versions will typically
+cause a segmentation violation.
+
+Another trap to avoid is misuse of the B<xp> argument to B<d2i_X509()>:
+
+ X509 *x;
+
+ if (!d2i_X509(&x, &p, len))
+ /* Some error */
+
+This will probably crash somewhere in B<d2i_X509()>. The reason for this
+is that the variable B<x> is uninitialized and an attempt will be made to
+interpret its (invalid) value as an B<X509> structure, typically causing
+a segmentation violation. If B<x> is set to NULL first then this will not
+happen.
+
+=head1 BUGS
+
+In some versions of OpenSSL the "reuse" behaviour of d2i_X509() when
+B<*px> is valid is broken and some parts of the reused structure may
+persist if they are not present in the new one. As a result the use
+of this "reuse" behaviour is strongly discouraged.
+
+i2d_X509() will not return an error in many versions of OpenSSL,
+if mandatory fields are not initialized due to a programming error
+then the encoded structure may contain invalid data or omit the
+fields entirely and will not be parsed by d2i_X509(). This may be
+fixed in future so code should not assume that i2d_X509() will
+always succeed.
+
+=head1 RETURN VALUES
+
+d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure
+or B<NULL> if an error occurs. The error code that can be obtained by
+L<ERR_get_error(3)|ERR_get_error(3)>.
+
+i2d_X509(), i2d_X509_bio() and i2d_X509_fp() return a the number of bytes
+successfully encoded or a negative value if an error occurs. The error code
+can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+i2d_X509_bio() and i2d_X509_fp() returns 1 for success and 0 if an error
+occurs The error code 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
+
+d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp
+are available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/openssl/doc/crypto/d2i_X509_ALGOR.pod b/openssl/doc/crypto/d2i_X509_ALGOR.pod
new file mode 100644
index 000000000..9e5cd92ca
--- /dev/null
+++ b/openssl/doc/crypto/d2i_X509_ALGOR.pod
@@ -0,0 +1,30 @@
+=pod
+
+=head1 NAME
+
+d2i_X509_ALGOR, i2d_X509_ALGOR - AlgorithmIdentifier functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509_ALGOR *d2i_X509_ALGOR(X509_ALGOR **a, unsigned char **pp, long length);
+ int i2d_X509_ALGOR(X509_ALGOR *a, unsigned char **pp);
+
+=head1 DESCRIPTION
+
+These functions decode and encode an B<X509_ALGOR> structure which is
+equivalent to the B<AlgorithmIdentifier> structure.
+
+Othewise these behave in a similar way to d2i_X509() and i2d_X509()
+described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)|d2i_X509(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/d2i_X509_CRL.pod b/openssl/doc/crypto/d2i_X509_CRL.pod
new file mode 100644
index 000000000..e7295a5d6
--- /dev/null
+++ b/openssl/doc/crypto/d2i_X509_CRL.pod
@@ -0,0 +1,37 @@
+=pod
+
+=head1 NAME
+
+d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_509_CRL_fp,
+i2d_X509_CRL_bio, i2d_X509_CRL_fp - PKCS#10 certificate request functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509_CRL *d2i_X509_CRL(X509_CRL **a, const unsigned char **pp, long length);
+ int i2d_X509_CRL(X509_CRL *a, unsigned char **pp);
+
+ X509_CRL *d2i_X509_CRL_bio(BIO *bp, X509_CRL **x);
+ X509_CRL *d2i_X509_CRL_fp(FILE *fp, X509_CRL **x);
+
+ int i2d_X509_CRL_bio(X509_CRL *x, BIO *bp);
+ int i2d_X509_CRL_fp(X509_CRL *x, FILE *fp);
+
+=head1 DESCRIPTION
+
+These functions decode and encode an X509 CRL (certificate revocation
+list).
+
+Othewise the functions behave in a similar way to d2i_X509() and i2d_X509()
+described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)|d2i_X509(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/d2i_X509_NAME.pod b/openssl/doc/crypto/d2i_X509_NAME.pod
new file mode 100644
index 000000000..343ffe151
--- /dev/null
+++ b/openssl/doc/crypto/d2i_X509_NAME.pod
@@ -0,0 +1,31 @@
+=pod
+
+=head1 NAME
+
+d2i_X509_NAME, i2d_X509_NAME - X509_NAME encoding functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509_NAME *d2i_X509_NAME(X509_NAME **a, unsigned char **pp, long length);
+ int i2d_X509_NAME(X509_NAME *a, unsigned char **pp);
+
+=head1 DESCRIPTION
+
+These functions decode and encode an B<X509_NAME> structure which is the
+the same as the B<Name> type defined in RFC2459 (and elsewhere) and used
+for example in certificate subject and issuer names.
+
+Othewise the functions behave in a similar way to d2i_X509() and i2d_X509()
+described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)|d2i_X509(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/d2i_X509_REQ.pod b/openssl/doc/crypto/d2i_X509_REQ.pod
new file mode 100644
index 000000000..ae32a3891
--- /dev/null
+++ b/openssl/doc/crypto/d2i_X509_REQ.pod
@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+d2i_X509_REQ, i2d_X509_REQ, d2i_X509_REQ_bio, d2i_X509_REQ_fp,
+i2d_X509_REQ_bio, i2d_X509_REQ_fp - PKCS#10 certificate request functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509_REQ *d2i_X509_REQ(X509_REQ **a, const unsigned char **pp, long length);
+ int i2d_X509_REQ(X509_REQ *a, unsigned char **pp);
+
+ X509_REQ *d2i_X509_REQ_bio(BIO *bp, X509_REQ **x);
+ X509_REQ *d2i_X509_REQ_fp(FILE *fp, X509_REQ **x);
+
+ int i2d_X509_REQ_bio(X509_REQ *x, BIO *bp);
+ int i2d_X509_REQ_fp(X509_REQ *x, FILE *fp);
+
+=head1 DESCRIPTION
+
+These functions decode and encode a PKCS#10 certificate request.
+
+Othewise these behave in a similar way to d2i_X509() and i2d_X509()
+described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)|d2i_X509(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/d2i_X509_SIG.pod b/openssl/doc/crypto/d2i_X509_SIG.pod
new file mode 100644
index 000000000..e48fd79a5
--- /dev/null
+++ b/openssl/doc/crypto/d2i_X509_SIG.pod
@@ -0,0 +1,30 @@
+=pod
+
+=head1 NAME
+
+d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509_SIG *d2i_X509_SIG(X509_SIG **a, unsigned char **pp, long length);
+ int i2d_X509_SIG(X509_SIG *a, unsigned char **pp);
+
+=head1 DESCRIPTION
+
+These functions decode and encode an X509_SIG structure which is
+equivalent to the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
+
+Othewise these behave in a similar way to d2i_X509() and i2d_X509()
+described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)|d2i_X509(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
diff --git a/openssl/doc/crypto/des.pod b/openssl/doc/crypto/des.pod
new file mode 100644
index 000000000..6f0cf1cc5
--- /dev/null
+++ b/openssl/doc/crypto/des.pod
@@ -0,0 +1,358 @@
+=pod
+
+=head1 NAME
+
+DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked,
+DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key,
+DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt,
+DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt,
+DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt,
+DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt,
+DES_ede3_cbcm_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt,
+DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys,
+DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption
+
+=head1 SYNOPSIS
+
+ #include <openssl/des.h>
+
+ void DES_random_key(DES_cblock *ret);
+
+ int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule);
+ int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule);
+ int DES_set_key_checked(const_DES_cblock *key,
+ DES_key_schedule *schedule);
+ void DES_set_key_unchecked(const_DES_cblock *key,
+ DES_key_schedule *schedule);
+
+ void DES_set_odd_parity(DES_cblock *key);
+ int DES_is_weak_key(const_DES_cblock *key);
+
+ void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output,
+ DES_key_schedule *ks, int enc);
+ void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output,
+ DES_key_schedule *ks1, DES_key_schedule *ks2, int enc);
+ void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output,
+ DES_key_schedule *ks1, DES_key_schedule *ks2,
+ DES_key_schedule *ks3, int enc);
+
+ void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output,
+ long length, DES_key_schedule *schedule, DES_cblock *ivec,
+ int enc);
+ void DES_cfb_encrypt(const unsigned char *in, unsigned char *out,
+ int numbits, long length, DES_key_schedule *schedule,
+ DES_cblock *ivec, int enc);
+ void DES_ofb_encrypt(const unsigned char *in, unsigned char *out,
+ int numbits, long length, DES_key_schedule *schedule,
+ DES_cblock *ivec);
+ void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output,
+ long length, DES_key_schedule *schedule, DES_cblock *ivec,
+ int enc);
+ void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, DES_key_schedule *schedule, DES_cblock *ivec,
+ int *num, int enc);
+ void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, DES_key_schedule *schedule, DES_cblock *ivec,
+ int *num);
+
+ void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output,
+ long length, DES_key_schedule *schedule, DES_cblock *ivec,
+ const_DES_cblock *inw, const_DES_cblock *outw, int enc);
+
+ void DES_ede2_cbc_encrypt(const unsigned char *input,
+ unsigned char *output, long length, DES_key_schedule *ks1,
+ DES_key_schedule *ks2, DES_cblock *ivec, int enc);
+ void DES_ede2_cfb64_encrypt(const unsigned char *in,
+ unsigned char *out, long length, DES_key_schedule *ks1,
+ DES_key_schedule *ks2, DES_cblock *ivec, int *num, int enc);
+ void DES_ede2_ofb64_encrypt(const unsigned char *in,
+ unsigned char *out, long length, DES_key_schedule *ks1,
+ DES_key_schedule *ks2, DES_cblock *ivec, int *num);
+
+ void DES_ede3_cbc_encrypt(const unsigned char *input,
+ unsigned char *output, long length, DES_key_schedule *ks1,
+ DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec,
+ int enc);
+ void DES_ede3_cbcm_encrypt(const unsigned char *in, unsigned char *out,
+ long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
+ DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2,
+ int enc);
+ void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
+ DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc);
+ void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, DES_key_schedule *ks1,
+ DES_key_schedule *ks2, DES_key_schedule *ks3,
+ DES_cblock *ivec, int *num);
+
+ DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output,
+ long length, DES_key_schedule *schedule,
+ const_DES_cblock *ivec);
+ DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[],
+ long length, int out_count, DES_cblock *seed);
+ void DES_string_to_key(const char *str, DES_cblock *key);
+ void DES_string_to_2keys(const char *str, DES_cblock *key1,
+ DES_cblock *key2);
+
+ char *DES_fcrypt(const char *buf, const char *salt, char *ret);
+ char *DES_crypt(const char *buf, const char *salt);
+
+ int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched,
+ DES_cblock *iv);
+ int DES_enc_write(int fd, const void *buf, int len,
+ DES_key_schedule *sched, DES_cblock *iv);
+
+=head1 DESCRIPTION
+
+This library contains a fast implementation of the DES encryption
+algorithm.
+
+There are two phases to the use of DES encryption. The first is the
+generation of a I<DES_key_schedule> from a key, the second is the
+actual encryption. A DES key is of type I<DES_cblock>. This type is
+consists of 8 bytes with odd parity. The least significant bit in
+each byte is the parity bit. The key schedule is an expanded form of
+the key; it is used to speed the encryption process.
+
+DES_random_key() generates a random key. The PRNG must be seeded
+prior to using this function (see L<rand(3)|rand(3)>). If the PRNG
+could not generate a secure key, 0 is returned.
+
+Before a DES key can be used, it must be converted into the
+architecture dependent I<DES_key_schedule> via the
+DES_set_key_checked() or DES_set_key_unchecked() function.
+
+DES_set_key_checked() will check that the key passed is of odd parity
+and is not a week or semi-weak key. If the parity is wrong, then -1
+is returned. If the key is a weak key, then -2 is returned. If an
+error is returned, the key schedule is not generated.
+
+DES_set_key() works like
+DES_set_key_checked() if the I<DES_check_key> flag is non-zero,
+otherwise like DES_set_key_unchecked(). These functions are available
+for compatibility; it is recommended to use a function that does not
+depend on a global variable.
+
+DES_set_odd_parity() sets the parity of the passed I<key> to odd.
+
+DES_is_weak_key() returns 1 is the passed key is a weak key, 0 if it
+is ok. The probability that a randomly generated key is weak is
+1/2^52, so it is not really worth checking for them.
+
+The following routines mostly operate on an input and output stream of
+I<DES_cblock>s.
+
+DES_ecb_encrypt() is the basic DES encryption routine that encrypts or
+decrypts a single 8-byte I<DES_cblock> in I<electronic code book>
+(ECB) mode. It always transforms the input data, pointed to by
+I<input>, into the output data, pointed to by the I<output> argument.
+If the I<encrypt> argument is non-zero (DES_ENCRYPT), the I<input>
+(cleartext) is encrypted in to the I<output> (ciphertext) using the
+key_schedule specified by the I<schedule> argument, previously set via
+I<DES_set_key>. If I<encrypt> is zero (DES_DECRYPT), the I<input> (now
+ciphertext) is decrypted into the I<output> (now cleartext). Input
+and output may overlap. DES_ecb_encrypt() does not return a value.
+
+DES_ecb3_encrypt() encrypts/decrypts the I<input> block by using
+three-key Triple-DES encryption in ECB mode. This involves encrypting
+the input with I<ks1>, decrypting with the key schedule I<ks2>, and
+then encrypting with I<ks3>. This routine greatly reduces the chances
+of brute force breaking of DES and has the advantage of if I<ks1>,
+I<ks2> and I<ks3> are the same, it is equivalent to just encryption
+using ECB mode and I<ks1> as the key.
+
+The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES
+encryption by using I<ks1> for the final encryption.
+
+DES_ncbc_encrypt() encrypts/decrypts using the I<cipher-block-chaining>
+(CBC) mode of DES. If the I<encrypt> argument is non-zero, the
+routine cipher-block-chain encrypts the cleartext data pointed to by
+the I<input> argument into the ciphertext pointed to by the I<output>
+argument, using the key schedule provided by the I<schedule> argument,
+and initialization vector provided by the I<ivec> argument. If the
+I<length> argument is not an integral multiple of eight bytes, the
+last block is copied to a temporary area and zero filled. The output
+is always an integral multiple of eight bytes.
+
+DES_xcbc_encrypt() is RSA's DESX mode of DES. It uses I<inw> and
+I<outw> to 'whiten' the encryption. I<inw> and I<outw> are secret
+(unlike the iv) and are as such, part of the key. So the key is sort
+of 24 bytes. This is much better than CBC DES.
+
+DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with
+three keys. This means that each DES operation inside the CBC mode is
+really an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL.
+
+The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by
+reusing I<ks1> for the final encryption. C<C=E(ks1,D(ks2,E(ks1,M)))>.
+This form of Triple-DES is used by the RSAREF library.
+
+DES_pcbc_encrypt() encrypt/decrypts using the propagating cipher block
+chaining mode used by Kerberos v4. Its parameters are the same as
+DES_ncbc_encrypt().
+
+DES_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This
+method takes an array of characters as input and outputs and array of
+characters. It does not require any padding to 8 character groups.
+Note: the I<ivec> variable is changed and the new changed value needs to
+be passed to the next call to this function. Since this function runs
+a complete DES ECB encryption per I<numbits>, this function is only
+suggested for use when sending small numbers of characters.
+
+DES_cfb64_encrypt()
+implements CFB mode of DES with 64bit feedback. Why is this
+useful you ask? Because this routine will allow you to encrypt an
+arbitrary number of bytes, no 8 byte padding. Each call to this
+routine will encrypt the input bytes to output and then update ivec
+and num. num contains 'how far' we are though ivec. If this does
+not make much sense, read more about cfb mode of DES :-).
+
+DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as
+DES_cfb64_encrypt() except that Triple-DES is used.
+
+DES_ofb_encrypt() encrypts using output feedback mode. This method
+takes an array of characters as input and outputs and array of
+characters. It does not require any padding to 8 character groups.
+Note: the I<ivec> variable is changed and the new changed value needs to
+be passed to the next call to this function. Since this function runs
+a complete DES ECB encryption per numbits, this function is only
+suggested for use when sending small numbers of characters.
+
+DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output
+Feed Back mode.
+
+DES_ede3_ofb64_encrypt() and DES_ede2_ofb64_encrypt() is the same as
+DES_ofb64_encrypt(), using Triple-DES.
+
+The following functions are included in the DES library for
+compatibility with the MIT Kerberos library.
+
+DES_cbc_cksum() produces an 8 byte checksum based on the input stream
+(via CBC encryption). The last 4 bytes of the checksum are returned
+and the complete 8 bytes are placed in I<output>. This function is
+used by Kerberos v4. Other applications should use
+L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead.
+
+DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte
+checksum from the input bytes. The algorithm can be iterated over the
+input, depending on I<out_count>, 1, 2, 3 or 4 times. If I<output> is
+non-NULL, the 8 bytes generated by each pass are written into
+I<output>.
+
+The following are DES-based transformations:
+
+DES_fcrypt() is a fast version of the Unix crypt(3) function. This
+version takes only a small amount of space relative to other fast
+crypt() implementations. This is different to the normal crypt in
+that the third parameter is the buffer that the return value is
+written into. It needs to be at least 14 bytes long. This function
+is thread safe, unlike the normal crypt.
+
+DES_crypt() is a faster replacement for the normal system crypt().
+This function calls DES_fcrypt() with a static array passed as the
+third parameter. This emulates the normal non-thread safe semantics
+of crypt(3).
+
+DES_enc_write() writes I<len> bytes to file descriptor I<fd> from
+buffer I<buf>. The data is encrypted via I<pcbc_encrypt> (default)
+using I<sched> for the key and I<iv> as a starting vector. The actual
+data send down I<fd> consists of 4 bytes (in network byte order)
+containing the length of the following encrypted data. The encrypted
+data then follows, padded with random data out to a multiple of 8
+bytes.
+
+DES_enc_read() is used to read I<len> bytes from file descriptor
+I<fd> into buffer I<buf>. The data being read from I<fd> is assumed to
+have come from DES_enc_write() and is decrypted using I<sched> for
+the key schedule and I<iv> for the initial vector.
+
+B<Warning:> The data format used by DES_enc_write() and DES_enc_read()
+has a cryptographic weakness: When asked to write more than MAXWRITE
+bytes, DES_enc_write() will split the data into several chunks that
+are all encrypted using the same IV. So don't use these functions
+unless you are sure you know what you do (in which case you might not
+want to use them anyway). They cannot handle non-blocking sockets.
+DES_enc_read() uses an internal state and thus cannot be used on
+multiple files.
+
+I<DES_rw_mode> is used to specify the encryption mode to use with
+DES_enc_read() and DES_end_write(). If set to I<DES_PCBC_MODE> (the
+default), DES_pcbc_encrypt is used. If set to I<DES_CBC_MODE>
+DES_cbc_encrypt is used.
+
+=head1 NOTES
+
+Single-key DES is insecure due to its short key size. ECB mode is
+not suitable for most applications; see L<des_modes(7)|des_modes(7)>.
+
+The L<evp(3)|evp(3)> library provides higher-level encryption functions.
+
+=head1 BUGS
+
+DES_3cbc_encrypt() is flawed and must not be used in applications.
+
+DES_cbc_encrypt() does not modify B<ivec>; use DES_ncbc_encrypt()
+instead.
+
+DES_cfb_encrypt() and DES_ofb_encrypt() operates on input of 8 bits.
+What this means is that if you set numbits to 12, and length to 2, the
+first 12 bits will come from the 1st input byte and the low half of
+the second input byte. The second 12 bits will have the low 8 bits
+taken from the 3rd input byte and the top 4 bits taken from the 4th
+input byte. The same holds for output. This function has been
+implemented this way because most people will be using a multiple of 8
+and because once you get into pulling bytes input bytes apart things
+get ugly!
+
+DES_string_to_key() is available for backward compatibility with the
+MIT library. New applications should use a cryptographic hash function.
+The same applies for DES_string_to_2key().
+
+=head1 CONFORMING TO
+
+ANSI X3.106
+
+The B<des> library was written to be source code compatible with
+the MIT Kerberos library.
+
+=head1 SEE ALSO
+
+crypt(3), L<des_modes(7)|des_modes(7)>, L<evp(3)|evp(3)>, L<rand(3)|rand(3)>
+
+=head1 HISTORY
+
+In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid
+clashes with older versions of libdes. Compatibility des_ functions
+are provided for a short while, as well as crypt().
+Declarations for these are in <openssl/des_old.h>. There is no DES_
+variant for des_random_seed().
+This will happen to other functions
+as well if they are deemed redundant (des_random_seed() just calls
+RAND_seed() and is present for backward compatibility only), buggy or
+already scheduled for removal.
+
+des_cbc_cksum(), des_cbc_encrypt(), des_ecb_encrypt(),
+des_is_weak_key(), des_key_sched(), des_pcbc_encrypt(),
+des_quad_cksum(), des_random_key() and des_string_to_key()
+are available in the MIT Kerberos library;
+des_check_key_parity(), des_fixup_key_parity() and des_is_weak_key()
+are available in newer versions of that library.
+
+des_set_key_checked() and des_set_key_unchecked() were added in
+OpenSSL 0.9.5.
+
+des_generate_random_block(), des_init_random_number_generator(),
+des_new_random_key(), des_set_random_generator_seed() and
+des_set_sequence_number() and des_rand_data() are used in newer
+versions of Kerberos but are not implemented here.
+
+des_random_key() generated cryptographically weak random data in
+SSLeay and in OpenSSL prior version 0.9.5, as well as in the original
+MIT library.
+
+=head1 AUTHOR
+
+Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project
+(http://www.openssl.org).
+
+=cut
diff --git a/openssl/doc/crypto/des_modes.pod b/openssl/doc/crypto/des_modes.pod
new file mode 100644
index 000000000..e883ca8fd
--- /dev/null
+++ b/openssl/doc/crypto/des_modes.pod
@@ -0,0 +1,255 @@
+=pod
+
+=for comment openssl_manual_section:7
+
+=head1 NAME
+
+des_modes - the variants of DES and other crypto algorithms of OpenSSL
+
+=head1 DESCRIPTION
+
+Several crypto algorithms for OpenSSL can be used in a number of modes. Those
+are used for using block ciphers in a way similar to stream ciphers, among
+other things.
+
+=head1 OVERVIEW
+
+=head2 Electronic Codebook Mode (ECB)
+
+Normally, this is found as the function I<algorithm>_ecb_encrypt().
+
+=over 2
+
+=item *
+
+64 bits are enciphered at a time.
+
+=item *
+
+The order of the blocks can be rearranged without detection.
+
+=item *
+
+The same plaintext block always produces the same ciphertext block
+(for the same key) making it vulnerable to a 'dictionary attack'.
+
+=item *
+
+An error will only affect one ciphertext block.
+
+=back
+
+=head2 Cipher Block Chaining Mode (CBC)
+
+Normally, this is found as the function I<algorithm>_cbc_encrypt().
+Be aware that des_cbc_encrypt() is not really DES CBC (it does
+not update the IV); use des_ncbc_encrypt() instead.
+
+=over 2
+
+=item *
+
+a multiple of 64 bits are enciphered at a time.
+
+=item *
+
+The CBC mode produces the same ciphertext whenever the same
+plaintext is encrypted using the same key and starting variable.
+
+=item *
+
+The chaining operation makes the ciphertext blocks dependent on the
+current and all preceding plaintext blocks and therefore blocks can not
+be rearranged.
+
+=item *
+
+The use of different starting variables prevents the same plaintext
+enciphering to the same ciphertext.
+
+=item *
+
+An error will affect the current and the following ciphertext blocks.
+
+=back
+
+=head2 Cipher Feedback Mode (CFB)
+
+Normally, this is found as the function I<algorithm>_cfb_encrypt().
+
+=over 2
+
+=item *
+
+a number of bits (j) <= 64 are enciphered at a time.
+
+=item *
+
+The CFB mode produces the same ciphertext whenever the same
+plaintext is encrypted using the same key and starting variable.
+
+=item *
+
+The chaining operation makes the ciphertext variables dependent on the
+current and all preceding variables and therefore j-bit variables are
+chained together and can not be rearranged.
+
+=item *
+
+The use of different starting variables prevents the same plaintext
+enciphering to the same ciphertext.
+
+=item *
+
+The strength of the CFB mode depends on the size of k (maximal if
+j == k). In my implementation this is always the case.
+
+=item *
+
+Selection of a small value for j will require more cycles through
+the encipherment algorithm per unit of plaintext and thus cause
+greater processing overheads.
+
+=item *
+
+Only multiples of j bits can be enciphered.
+
+=item *
+
+An error will affect the current and the following ciphertext variables.
+
+=back
+
+=head2 Output Feedback Mode (OFB)
+
+Normally, this is found as the function I<algorithm>_ofb_encrypt().
+
+=over 2
+
+
+=item *
+
+a number of bits (j) <= 64 are enciphered at a time.
+
+=item *
+
+The OFB mode produces the same ciphertext whenever the same
+plaintext enciphered using the same key and starting variable. More
+over, in the OFB mode the same key stream is produced when the same
+key and start variable are used. Consequently, for security reasons
+a specific start variable should be used only once for a given key.
+
+=item *
+
+The absence of chaining makes the OFB more vulnerable to specific attacks.
+
+=item *
+
+The use of different start variables values prevents the same
+plaintext enciphering to the same ciphertext, by producing different
+key streams.
+
+=item *
+
+Selection of a small value for j will require more cycles through
+the encipherment algorithm per unit of plaintext and thus cause
+greater processing overheads.
+
+=item *
+
+Only multiples of j bits can be enciphered.
+
+=item *
+
+OFB mode of operation does not extend ciphertext errors in the
+resultant plaintext output. Every bit error in the ciphertext causes
+only one bit to be in error in the deciphered plaintext.
+
+=item *
+
+OFB mode is not self-synchronizing. If the two operation of
+encipherment and decipherment get out of synchronism, the system needs
+to be re-initialized.
+
+=item *
+
+Each re-initialization should use a value of the start variable
+different from the start variable values used before with the same
+key. The reason for this is that an identical bit stream would be
+produced each time from the same parameters. This would be
+susceptible to a 'known plaintext' attack.
+
+=back
+
+=head2 Triple ECB Mode
+
+Normally, this is found as the function I<algorithm>_ecb3_encrypt().
+
+=over 2
+
+=item *
+
+Encrypt with key1, decrypt with key2 and encrypt with key3 again.
+
+=item *
+
+As for ECB encryption but increases the key length to 168 bits.
+There are theoretic attacks that can be used that make the effective
+key length 112 bits, but this attack also requires 2^56 blocks of
+memory, not very likely, even for the NSA.
+
+=item *
+
+If both keys are the same it is equivalent to encrypting once with
+just one key.
+
+=item *
+
+If the first and last key are the same, the key length is 112 bits.
+There are attacks that could reduce the effective key strength
+to only slightly more than 56 bits, but these require a lot of memory.
+
+=item *
+
+If all 3 keys are the same, this is effectively the same as normal
+ecb mode.
+
+=back
+
+=head2 Triple CBC Mode
+
+Normally, this is found as the function I<algorithm>_ede3_cbc_encrypt().
+
+=over 2
+
+
+=item *
+
+Encrypt with key1, decrypt with key2 and then encrypt with key3.
+
+=item *
+
+As for CBC encryption but increases the key length to 168 bits with
+the same restrictions as for triple ecb mode.
+
+=back
+
+=head1 NOTES
+
+This text was been written in large parts by Eric Young in his original
+documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed
+it to:
+
+ AS 2805.5.2
+ Australian Standard
+ Electronic funds transfer - Requirements for interfaces,
+ Part 5.2: Modes of operation for an n-bit block cipher algorithm
+ Appendix A
+
+=head1 SEE ALSO
+
+L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<idea(3)|idea(3)>,
+L<rc2(3)|rc2(3)>
+
+=cut
+
diff --git a/openssl/doc/crypto/dh.pod b/openssl/doc/crypto/dh.pod
new file mode 100644
index 000000000..c3ccd0620
--- /dev/null
+++ b/openssl/doc/crypto/dh.pod
@@ -0,0 +1,78 @@
+=pod
+
+=head1 NAME
+
+dh - Diffie-Hellman key agreement
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+ #include <openssl/engine.h>
+
+ DH * DH_new(void);
+ void DH_free(DH *dh);
+
+ int DH_size(const DH *dh);
+
+ DH * DH_generate_parameters(int prime_len, int generator,
+ void (*callback)(int, int, void *), void *cb_arg);
+ int DH_check(const DH *dh, int *codes);
+
+ int DH_generate_key(DH *dh);
+ int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
+
+ 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);
+
+ int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(),
+ int (*dup_func)(), void (*free_func)());
+ int DH_set_ex_data(DH *d, int idx, char *arg);
+ char *DH_get_ex_data(DH *d, int idx);
+
+ DH * d2i_DHparams(DH **a, unsigned char **pp, long length);
+ int i2d_DHparams(const DH *a, unsigned char **pp);
+
+ int DHparams_print_fp(FILE *fp, const DH *x);
+ int DHparams_print(BIO *bp, const DH *x);
+
+=head1 DESCRIPTION
+
+These functions implement the Diffie-Hellman key agreement protocol.
+The generation of shared DH parameters is described in
+L<DH_generate_parameters(3)|DH_generate_parameters(3)>; L<DH_generate_key(3)|DH_generate_key(3)> describes how
+to perform a key agreement.
+
+The B<DH> structure consists of several BIGNUM components.
+
+ struct
+ {
+ BIGNUM *p; // prime number (shared)
+ BIGNUM *g; // generator of Z_p (shared)
+ BIGNUM *priv_key; // private DH value x
+ BIGNUM *pub_key; // public DH value g^x
+ // ...
+ };
+ DH
+
+Note that DH keys may use non-standard B<DH_METHOD> implementations,
+either directly or by the use of B<ENGINE> modules. In some cases (eg. an
+ENGINE providing support for hardware-embedded keys), these BIGNUM values
+will not be used by the implementation or may be used for alternative data
+storage. For this reason, applications should generally avoid using DH
+structure elements directly and instead use API functions to query or
+modify keys.
+
+=head1 SEE ALSO
+
+L<dhparam(1)|dhparam(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>,
+L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<engine(3)|engine(3)>,
+L<DH_set_method(3)|DH_set_method(3)>, L<DH_new(3)|DH_new(3)>,
+L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>,
+L<DH_generate_parameters(3)|DH_generate_parameters(3)>,
+L<DH_compute_key(3)|DH_compute_key(3)>, L<d2i_DHparams(3)|d2i_DHparams(3)>,
+L<RSA_print(3)|RSA_print(3)>
+
+=cut
diff --git a/openssl/doc/crypto/dsa.pod b/openssl/doc/crypto/dsa.pod
new file mode 100644
index 000000000..da07d2b93
--- /dev/null
+++ b/openssl/doc/crypto/dsa.pod
@@ -0,0 +1,114 @@
+=pod
+
+=head1 NAME
+
+dsa - Digital Signature Algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+ #include <openssl/engine.h>
+
+ DSA * DSA_new(void);
+ void DSA_free(DSA *dsa);
+
+ int DSA_size(const DSA *dsa);
+
+ 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);
+
+ DH * DSA_dup_DH(const DSA *r);
+
+ int DSA_generate_key(DSA *dsa);
+
+ int DSA_sign(int dummy, 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 dummy, const unsigned char *dgst, int len,
+ const unsigned char *sigbuf, int siglen, DSA *dsa);
+
+ 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);
+ const DSA_METHOD *DSA_OpenSSL(void);
+
+ int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(),
+ int (*dup_func)(), void (*free_func)());
+ int DSA_set_ex_data(DSA *d, int idx, char *arg);
+ char *DSA_get_ex_data(DSA *d, int idx);
+
+ DSA_SIG *DSA_SIG_new(void);
+ void DSA_SIG_free(DSA_SIG *a);
+ int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp);
+ DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length);
+
+ 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);
+
+ DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length);
+ DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length);
+ DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length);
+ int i2d_DSAPublicKey(const DSA *a, unsigned char **pp);
+ int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp);
+ int i2d_DSAparams(const DSA *a,unsigned char **pp);
+
+ int DSAparams_print(BIO *bp, const DSA *x);
+ int DSAparams_print_fp(FILE *fp, const DSA *x);
+ int DSA_print(BIO *bp, const DSA *x, int off);
+ int DSA_print_fp(FILE *bp, const DSA *x, int off);
+
+=head1 DESCRIPTION
+
+These functions implement the Digital Signature Algorithm (DSA). The
+generation of shared DSA parameters is described in
+L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>;
+L<DSA_generate_key(3)|DSA_generate_key(3)> describes how to
+generate a signature key. Signature generation and verification are
+described in L<DSA_sign(3)|DSA_sign(3)>.
+
+The B<DSA> structure consists of several BIGNUM components.
+
+ struct
+ {
+ BIGNUM *p; // prime number (public)
+ BIGNUM *q; // 160-bit subprime, q | p-1 (public)
+ BIGNUM *g; // generator of subgroup (public)
+ BIGNUM *priv_key; // private key x
+ BIGNUM *pub_key; // public key y = g^x
+ // ...
+ }
+ DSA;
+
+In public keys, B<priv_key> is NULL.
+
+Note that DSA keys may use non-standard B<DSA_METHOD> implementations,
+either directly or by the use of B<ENGINE> modules. In some cases (eg. an
+ENGINE providing support for hardware-embedded keys), these BIGNUM values
+will not be used by the implementation or may be used for alternative data
+storage. For this reason, applications should generally avoid using DSA
+structure elements directly and instead use API functions to query or
+modify keys.
+
+=head1 CONFORMING TO
+
+US Federal Information Processing Standard FIPS 186 (Digital Signature
+Standard, DSS), ANSI X9.30
+
+=head1 SEE ALSO
+
+L<bn(3)|bn(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>,
+L<rsa(3)|rsa(3)>, L<sha(3)|sha(3)>, L<engine(3)|engine(3)>,
+L<DSA_new(3)|DSA_new(3)>,
+L<DSA_size(3)|DSA_size(3)>,
+L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>,
+L<DSA_dup_DH(3)|DSA_dup_DH(3)>,
+L<DSA_generate_key(3)|DSA_generate_key(3)>,
+L<DSA_sign(3)|DSA_sign(3)>, L<DSA_set_method(3)|DSA_set_method(3)>,
+L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>,
+L<RSA_print(3)|RSA_print(3)>
+
+=cut
diff --git a/openssl/doc/crypto/ecdsa.pod b/openssl/doc/crypto/ecdsa.pod
new file mode 100644
index 000000000..49b10f224
--- /dev/null
+++ b/openssl/doc/crypto/ecdsa.pod
@@ -0,0 +1,210 @@
+=pod
+
+=head1 NAME
+
+ecdsa - Elliptic Curve Digital Signature Algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/ecdsa.h>
+
+ ECDSA_SIG* ECDSA_SIG_new(void);
+ void ECDSA_SIG_free(ECDSA_SIG *sig);
+ int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
+ ECDSA_SIG* d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp,
+ long len);
+
+ ECDSA_SIG* ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
+ EC_KEY *eckey);
+ ECDSA_SIG* ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
+ const BIGNUM *kinv, const BIGNUM *rp,
+ EC_KEY *eckey);
+ int ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
+ const ECDSA_SIG *sig, EC_KEY* eckey);
+ int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx,
+ BIGNUM **kinv, BIGNUM **rp);
+ int ECDSA_sign(int type, const unsigned char *dgst,
+ int dgstlen, unsigned char *sig,
+ unsigned int *siglen, EC_KEY *eckey);
+ int ECDSA_sign_ex(int type, const unsigned char *dgst,
+ int dgstlen, unsigned char *sig,
+ unsigned int *siglen, const BIGNUM *kinv,
+ const BIGNUM *rp, EC_KEY *eckey);
+ int ECDSA_verify(int type, const unsigned char *dgst,
+ int dgstlen, const unsigned char *sig,
+ int siglen, EC_KEY *eckey);
+ int ECDSA_size(const EC_KEY *eckey);
+
+ const ECDSA_METHOD* ECDSA_OpenSSL(void);
+ void ECDSA_set_default_method(const ECDSA_METHOD *meth);
+ const ECDSA_METHOD* ECDSA_get_default_method(void);
+ int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth);
+
+ int ECDSA_get_ex_new_index(long argl, void *argp,
+ CRYPTO_EX_new *new_func,
+ CRYPTO_EX_dup *dup_func,
+ CRYPTO_EX_free *free_func);
+ int ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg);
+ void* ECDSA_get_ex_data(EC_KEY *d, int idx);
+
+=head1 DESCRIPTION
+
+The B<ECDSA_SIG> structure consists of two BIGNUMs for the
+r and s value of a ECDSA signature (see X9.62 or FIPS 186-2).
+
+ struct
+ {
+ BIGNUM *r;
+ BIGNUM *s;
+ } ECDSA_SIG;
+
+ECDSA_SIG_new() allocates a new B<ECDSA_SIG> structure (note: this
+function also allocates the BIGNUMs) and initialize it.
+
+ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>.
+
+i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature
+B<sig> and writes the encoded signature to B<*pp> (note: if B<pp>
+is NULL B<i2d_ECDSA_SIG> returns the expected length in bytes of
+the DER encoded signature). B<i2d_ECDSA_SIG> returns the length
+of the DER encoded signature (or 0 on error).
+
+d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns
+the decoded signature in a newly allocated B<ECDSA_SIG> structure.
+B<*sig> points to the buffer containing the DER encoded signature
+of size B<len>.
+
+ECDSA_size() returns the maximum length of a DER encoded
+ECDSA signature created with the private EC key B<eckey>.
+
+ECDSA_sign_setup() may be used to precompute parts of the
+signing operation. B<eckey> is the private EC key and B<ctx>
+is a pointer to B<BN_CTX> structure (or NULL). The precomputed
+values or returned in B<kinv> and B<rp> and can be used in a
+later call to B<ECDSA_sign_ex> or B<ECDSA_do_sign_ex>.
+
+ECDSA_sign() is wrapper function for ECDSA_sign_ex with B<kinv>
+and B<rp> set to NULL.
+
+ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes
+hash value B<dgst> using the private EC key B<eckey> and the optional
+pre-computed values B<kinv> and B<rp>. The DER encoded signatures is
+stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig>
+must point to B<ECDSA_size> bytes of memory. The parameter B<type>
+is ignored.
+
+ECDSA_verify() verifies that the signature in B<sig> of size
+B<siglen> is a valid ECDSA signature of the hash value
+value B<dgst> of size B<dgstlen> using the public key B<eckey>.
+The parameter B<type> is ignored.
+
+ECDSA_do_sign() is wrapper function for ECDSA_do_sign_ex with B<kinv>
+and B<rp> set to NULL.
+
+ECDSA_do_sign_ex() computes a digital signature of the B<dgst_len>
+bytes hash value B<dgst> using the private key B<eckey> and the
+optional pre-computed values B<kinv> and B<rp>. The signature is
+returned in a newly allocated B<ECDSA_SIG> structure (or NULL on error).
+
+ECDSA_do_verify() verifies that the signature B<sig> is a valid
+ECDSA signature of the hash value B<dgst> of size B<dgst_len>
+using the public key B<eckey>.
+
+=head1 RETURN VALUES
+
+ECDSA_size() returns the maximum length signature or 0 on error.
+
+ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or -1
+on error.
+
+ECDSA_verify() and ECDSA_do_verify() return 1 for a valid
+signature, 0 for an invalid signature and -1 on error.
+The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 EXAMPLES
+
+Creating a ECDSA signature of given SHA-1 hash value using the
+named curve secp192k1.
+
+First step: create a EC_KEY object (note: this part is B<not> ECDSA
+specific)
+
+ int ret;
+ ECDSA_SIG *sig;
+ EC_KEY *eckey = EC_KEY_new();
+ if (eckey == NULL)
+ {
+ /* error */
+ }
+ key->group = EC_GROUP_new_by_nid(NID_secp192k1);
+ if (key->group == NULL)
+ {
+ /* error */
+ }
+ if (!EC_KEY_generate_key(eckey))
+ {
+ /* error */
+ }
+
+Second step: compute the ECDSA signature of a SHA-1 hash value
+using B<ECDSA_do_sign>
+
+ sig = ECDSA_do_sign(digest, 20, eckey);
+ if (sig == NULL)
+ {
+ /* error */
+ }
+
+or using B<ECDSA_sign>
+
+ unsigned char *buffer, *pp;
+ int buf_len;
+ buf_len = ECDSA_size(eckey);
+ buffer = OPENSSL_malloc(buf_len);
+ pp = buffer;
+ if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey);
+ {
+ /* error */
+ }
+
+Third step: verify the created ECDSA signature using B<ECDSA_do_verify>
+
+ ret = ECDSA_do_verify(digest, 20, sig, eckey);
+
+or using B<ECDSA_verify>
+
+ ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey);
+
+and finally evaluate the return value:
+
+ if (ret == -1)
+ {
+ /* error */
+ }
+ else if (ret == 0)
+ {
+ /* incorrect signature */
+ }
+ else /* ret == 1 */
+ {
+ /* signature ok */
+ }
+
+=head1 CONFORMING TO
+
+ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
+(Digital Signature Standard, DSS)
+
+=head1 SEE ALSO
+
+L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)>
+
+=head1 HISTORY
+
+The ecdsa implementation was first introduced in OpenSSL 0.9.8
+
+=head1 AUTHOR
+
+Nils Larsch for the OpenSSL project (http://www.openssl.org).
+
+=cut
diff --git a/openssl/doc/crypto/engine.pod b/openssl/doc/crypto/engine.pod
new file mode 100644
index 000000000..f5ab1c3e5
--- /dev/null
+++ b/openssl/doc/crypto/engine.pod
@@ -0,0 +1,599 @@
+=pod
+
+=head1 NAME
+
+engine - ENGINE cryptographic module support
+
+=head1 SYNOPSIS
+
+ #include <openssl/engine.h>
+
+ ENGINE *ENGINE_get_first(void);
+ ENGINE *ENGINE_get_last(void);
+ ENGINE *ENGINE_get_next(ENGINE *e);
+ ENGINE *ENGINE_get_prev(ENGINE *e);
+
+ int ENGINE_add(ENGINE *e);
+ int ENGINE_remove(ENGINE *e);
+
+ ENGINE *ENGINE_by_id(const char *id);
+
+ int ENGINE_init(ENGINE *e);
+ int ENGINE_finish(ENGINE *e);
+
+ void ENGINE_load_openssl(void);
+ void ENGINE_load_dynamic(void);
+ #ifndef OPENSSL_NO_STATIC_ENGINE
+ void ENGINE_load_4758cca(void);
+ void ENGINE_load_aep(void);
+ void ENGINE_load_atalla(void);
+ void ENGINE_load_chil(void);
+ void ENGINE_load_cswift(void);
+ void ENGINE_load_gmp(void);
+ void ENGINE_load_nuron(void);
+ void ENGINE_load_sureware(void);
+ void ENGINE_load_ubsec(void);
+ #endif
+ void ENGINE_load_cryptodev(void);
+ void ENGINE_load_builtin_engines(void);
+
+ void ENGINE_cleanup(void);
+
+ ENGINE *ENGINE_get_default_RSA(void);
+ ENGINE *ENGINE_get_default_DSA(void);
+ ENGINE *ENGINE_get_default_ECDH(void);
+ ENGINE *ENGINE_get_default_ECDSA(void);
+ ENGINE *ENGINE_get_default_DH(void);
+ ENGINE *ENGINE_get_default_RAND(void);
+ ENGINE *ENGINE_get_cipher_engine(int nid);
+ ENGINE *ENGINE_get_digest_engine(int nid);
+
+ int ENGINE_set_default_RSA(ENGINE *e);
+ int ENGINE_set_default_DSA(ENGINE *e);
+ int ENGINE_set_default_ECDH(ENGINE *e);
+ int ENGINE_set_default_ECDSA(ENGINE *e);
+ int ENGINE_set_default_DH(ENGINE *e);
+ int ENGINE_set_default_RAND(ENGINE *e);
+ int ENGINE_set_default_ciphers(ENGINE *e);
+ int ENGINE_set_default_digests(ENGINE *e);
+ int ENGINE_set_default_string(ENGINE *e, const char *list);
+
+ int ENGINE_set_default(ENGINE *e, unsigned int flags);
+
+ unsigned int ENGINE_get_table_flags(void);
+ void ENGINE_set_table_flags(unsigned int flags);
+
+ int ENGINE_register_RSA(ENGINE *e);
+ void ENGINE_unregister_RSA(ENGINE *e);
+ void ENGINE_register_all_RSA(void);
+ int ENGINE_register_DSA(ENGINE *e);
+ void ENGINE_unregister_DSA(ENGINE *e);
+ void ENGINE_register_all_DSA(void);
+ int ENGINE_register_ECDH(ENGINE *e);
+ void ENGINE_unregister_ECDH(ENGINE *e);
+ void ENGINE_register_all_ECDH(void);
+ int ENGINE_register_ECDSA(ENGINE *e);
+ void ENGINE_unregister_ECDSA(ENGINE *e);
+ void ENGINE_register_all_ECDSA(void);
+ int ENGINE_register_DH(ENGINE *e);
+ void ENGINE_unregister_DH(ENGINE *e);
+ void ENGINE_register_all_DH(void);
+ int ENGINE_register_RAND(ENGINE *e);
+ void ENGINE_unregister_RAND(ENGINE *e);
+ void ENGINE_register_all_RAND(void);
+ int ENGINE_register_STORE(ENGINE *e);
+ void ENGINE_unregister_STORE(ENGINE *e);
+ void ENGINE_register_all_STORE(void);
+ int ENGINE_register_ciphers(ENGINE *e);
+ void ENGINE_unregister_ciphers(ENGINE *e);
+ void ENGINE_register_all_ciphers(void);
+ int ENGINE_register_digests(ENGINE *e);
+ void ENGINE_unregister_digests(ENGINE *e);
+ void ENGINE_register_all_digests(void);
+ int ENGINE_register_complete(ENGINE *e);
+ int ENGINE_register_all_complete(void);
+
+ int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void));
+ int ENGINE_cmd_is_executable(ENGINE *e, int cmd);
+ int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
+ long i, void *p, void (*f)(void), int cmd_optional);
+ int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
+ int cmd_optional);
+
+ int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg);
+ void *ENGINE_get_ex_data(const ENGINE *e, int idx);
+
+ int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
+ CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
+
+ ENGINE *ENGINE_new(void);
+ int ENGINE_free(ENGINE *e);
+ int ENGINE_up_ref(ENGINE *e);
+
+ int ENGINE_set_id(ENGINE *e, const char *id);
+ int ENGINE_set_name(ENGINE *e, const char *name);
+ int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);
+ int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);
+ int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth);
+ int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth);
+ int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);
+ int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);
+ int ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *rand_meth);
+ int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
+ int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
+ int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
+ int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
+ int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);
+ int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);
+ int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);
+ int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);
+ int ENGINE_set_flags(ENGINE *e, int flags);
+ int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);
+
+ const char *ENGINE_get_id(const ENGINE *e);
+ const char *ENGINE_get_name(const ENGINE *e);
+ const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);
+ const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);
+ const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e);
+ const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e);
+ const DH_METHOD *ENGINE_get_DH(const ENGINE *e);
+ const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);
+ const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e);
+ ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);
+ ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);
+ ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);
+ ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);
+ ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);
+ ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);
+ ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);
+ ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);
+ const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);
+ const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);
+ int ENGINE_get_flags(const ENGINE *e);
+ const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);
+
+ EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
+ UI_METHOD *ui_method, void *callback_data);
+ EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
+ UI_METHOD *ui_method, void *callback_data);
+
+ void ENGINE_add_conf_module(void);
+
+=head1 DESCRIPTION
+
+These functions create, manipulate, and use cryptographic modules in the
+form of B<ENGINE> objects. These objects act as containers for
+implementations of cryptographic algorithms, and support a
+reference-counted mechanism to allow them to be dynamically loaded in and
+out of the running application.
+
+The cryptographic functionality that can be provided by an B<ENGINE>
+implementation includes the following abstractions;
+
+ RSA_METHOD - for providing alternative RSA implementations
+ DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD,
+ STORE_METHOD - similarly for other OpenSSL APIs
+ EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid')
+ EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid')
+ key-loading - loading public and/or private EVP_PKEY keys
+
+=head2 Reference counting and handles
+
+Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be
+treated as handles - ie. not only as pointers, but also as references to
+the underlying ENGINE object. Ie. one should obtain a new reference when
+making copies of an ENGINE pointer if the copies will be used (and
+released) independently.
+
+ENGINE objects have two levels of reference-counting to match the way in
+which the objects are used. At the most basic level, each ENGINE pointer is
+inherently a B<structural> reference - a structural reference is required
+to use the pointer value at all, as this kind of reference is a guarantee
+that the structure can not be deallocated until the reference is released.
+
+However, a structural reference provides no guarantee that the ENGINE is
+initiliased and able to use any of its cryptographic
+implementations. Indeed it's quite possible that most ENGINEs will not
+initialise at all in typical environments, as ENGINEs are typically used to
+support specialised hardware. To use an ENGINE's functionality, you need a
+B<functional> reference. This kind of reference can be considered a
+specialised form of structural reference, because each functional reference
+implicitly contains a structural reference as well - however to avoid
+difficult-to-find programming bugs, it is recommended to treat the two
+kinds of reference independently. If you have a functional reference to an
+ENGINE, you have a guarantee that the ENGINE has been initialised ready to
+perform cryptographic operations and will remain uninitialised
+until after you have released your reference.
+
+I<Structural references>
+
+This basic type of reference is used for instantiating new ENGINEs,
+iterating across OpenSSL's internal linked-list of loaded
+ENGINEs, reading information about an ENGINE, etc. Essentially a structural
+reference is sufficient if you only need to query or manipulate the data of
+an ENGINE implementation rather than use its functionality.
+
+The ENGINE_new() function returns a structural reference to a new (empty)
+ENGINE object. There are other ENGINE API functions that return structural
+references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(),
+ENGINE_get_next(), ENGINE_get_prev(). All structural references should be
+released by a corresponding to call to the ENGINE_free() function - the
+ENGINE object itself will only actually be cleaned up and deallocated when
+the last structural reference is released.
+
+It should also be noted that many ENGINE API function calls that accept a
+structural reference will internally obtain another reference - typically
+this happens whenever the supplied ENGINE will be needed by OpenSSL after
+the function has returned. Eg. the function to add a new ENGINE to
+OpenSSL's internal list is ENGINE_add() - if this function returns success,
+then OpenSSL will have stored a new structural reference internally so the
+caller is still responsible for freeing their own reference with
+ENGINE_free() when they are finished with it. In a similar way, some
+functions will automatically release the structural reference passed to it
+if part of the function's job is to do so. Eg. the ENGINE_get_next() and
+ENGINE_get_prev() functions are used for iterating across the internal
+ENGINE list - they will return a new structural reference to the next (or
+previous) ENGINE in the list or NULL if at the end (or beginning) of the
+list, but in either case the structural reference passed to the function is
+released on behalf of the caller.
+
+To clarify a particular function's handling of references, one should
+always consult that function's documentation "man" page, or failing that
+the openssl/engine.h header file includes some hints.
+
+I<Functional references>
+
+As mentioned, functional references exist when the cryptographic
+functionality of an ENGINE is required to be available. A functional
+reference can be obtained in one of two ways; from an existing structural
+reference to the required ENGINE, or by asking OpenSSL for the default
+operational ENGINE for a given cryptographic purpose.
+
+To obtain a functional reference from an existing structural reference,
+call the ENGINE_init() function. This returns zero if the ENGINE was not
+already operational and couldn't be successfully initialised (eg. lack of
+system drivers, no special hardware attached, etc), otherwise it will
+return non-zero to indicate that the ENGINE is now operational and will
+have allocated a new B<functional> reference to the ENGINE. All functional
+references are released by calling ENGINE_finish() (which removes the
+implicit structural reference as well).
+
+The second way to get a functional reference is by asking OpenSSL for a
+default implementation for a given task, eg. by ENGINE_get_default_RSA(),
+ENGINE_get_default_cipher_engine(), etc. These are discussed in the next
+section, though they are not usually required by application programmers as
+they are used automatically when creating and using the relevant
+algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc.
+
+=head2 Default implementations
+
+For each supported abstraction, the ENGINE code maintains an internal table
+of state to control which implementations are available for a given
+abstraction and which should be used by default. These implementations are
+registered in the tables and indexed by an 'nid' value, because
+abstractions like EVP_CIPHER and EVP_DIGEST support many distinct
+algorithms and modes, and ENGINEs can support arbitrarily many of them.
+In the case of other abstractions like RSA, DSA, etc, there is only one
+"algorithm" so all implementations implicitly register using the same 'nid'
+index.
+
+When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg.
+when calling RSA_new_method(NULL)), a "get_default" call will be made to the
+ENGINE subsystem to process the corresponding state table and return a
+functional reference to an initialised ENGINE whose implementation should be
+used. If no ENGINE should (or can) be used, it will return NULL and the caller
+will operate with a NULL ENGINE handle - this usually equates to using the
+conventional software implementation. In the latter case, OpenSSL will from
+then on behave the way it used to before the ENGINE API existed.
+
+Each state table has a flag to note whether it has processed this
+"get_default" query since the table was last modified, because to process
+this question it must iterate across all the registered ENGINEs in the
+table trying to initialise each of them in turn, in case one of them is
+operational. If it returns a functional reference to an ENGINE, it will
+also cache another reference to speed up processing future queries (without
+needing to iterate across the table). Likewise, it will cache a NULL
+response if no ENGINE was available so that future queries won't repeat the
+same iteration unless the state table changes. This behaviour can also be
+changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using
+ENGINE_set_table_flags()), no attempted initialisations will take place,
+instead the only way for the state table to return a non-NULL ENGINE to the
+"get_default" query will be if one is expressly set in the table. Eg.
+ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except
+that it also sets the state table's cached response for the "get_default"
+query. In the case of abstractions like EVP_CIPHER, where implementations are
+indexed by 'nid', these flags and cached-responses are distinct for each 'nid'
+value.
+
+=head2 Application requirements
+
+This section will explain the basic things an application programmer should
+support to make the most useful elements of the ENGINE functionality
+available to the user. The first thing to consider is whether the
+programmer wishes to make alternative ENGINE modules available to the
+application and user. OpenSSL maintains an internal linked list of
+"visible" ENGINEs from which it has to operate - at start-up, this list is
+empty and in fact if an application does not call any ENGINE API calls and
+it uses static linking against openssl, then the resulting application
+binary will not contain any alternative ENGINE code at all. So the first
+consideration is whether any/all available ENGINE implementations should be
+made visible to OpenSSL - this is controlled by calling the various "load"
+functions, eg.
+
+ /* Make the "dynamic" ENGINE available */
+ void ENGINE_load_dynamic(void);
+ /* Make the CryptoSwift hardware acceleration support available */
+ void ENGINE_load_cswift(void);
+ /* Make support for nCipher's "CHIL" hardware available */
+ void ENGINE_load_chil(void);
+ ...
+ /* Make ALL ENGINE implementations bundled with OpenSSL available */
+ void ENGINE_load_builtin_engines(void);
+
+Having called any of these functions, ENGINE objects would have been
+dynamically allocated and populated with these implementations and linked
+into OpenSSL's internal linked list. At this point it is important to
+mention an important API function;
+
+ void ENGINE_cleanup(void);
+
+If no ENGINE API functions are called at all in an application, then there
+are no inherent memory leaks to worry about from the ENGINE functionality,
+however if any ENGINEs are loaded, even if they are never registered or
+used, it is necessary to use the ENGINE_cleanup() function to
+correspondingly cleanup before program exit, if the caller wishes to avoid
+memory leaks. This mechanism uses an internal callback registration table
+so that any ENGINE API functionality that knows it requires cleanup can
+register its cleanup details to be called during ENGINE_cleanup(). This
+approach allows ENGINE_cleanup() to clean up after any ENGINE functionality
+at all that your program uses, yet doesn't automatically create linker
+dependencies to all possible ENGINE functionality - only the cleanup
+callbacks required by the functionality you do use will be required by the
+linker.
+
+The fact that ENGINEs are made visible to OpenSSL (and thus are linked into
+the program and loaded into memory at run-time) does not mean they are
+"registered" or called into use by OpenSSL automatically - that behaviour
+is something for the application to control. Some applications
+will want to allow the user to specify exactly which ENGINE they want used
+if any is to be used at all. Others may prefer to load all support and have
+OpenSSL automatically use at run-time any ENGINE that is able to
+successfully initialise - ie. to assume that this corresponds to
+acceleration hardware attached to the machine or some such thing. There are
+probably numerous other ways in which applications may prefer to handle
+things, so we will simply illustrate the consequences as they apply to a
+couple of simple cases and leave developers to consider these and the
+source code to openssl's builtin utilities as guides.
+
+I<Using a specific ENGINE implementation>
+
+Here we'll assume an application has been configured by its user or admin
+to want to use the "ACME" ENGINE if it is available in the version of
+OpenSSL the application was compiled with. If it is available, it should be
+used by default for all RSA, DSA, and symmetric cipher operation, otherwise
+OpenSSL should use its builtin software as per usual. The following code
+illustrates how to approach this;
+
+ ENGINE *e;
+ const char *engine_id = "ACME";
+ ENGINE_load_builtin_engines();
+ e = ENGINE_by_id(engine_id);
+ if(!e)
+ /* the engine isn't available */
+ return;
+ if(!ENGINE_init(e)) {
+ /* the engine couldn't initialise, release 'e' */
+ ENGINE_free(e);
+ return;
+ }
+ if(!ENGINE_set_default_RSA(e))
+ /* This should only happen when 'e' can't initialise, but the previous
+ * statement suggests it did. */
+ abort();
+ ENGINE_set_default_DSA(e);
+ ENGINE_set_default_ciphers(e);
+ /* Release the functional reference from ENGINE_init() */
+ ENGINE_finish(e);
+ /* Release the structural reference from ENGINE_by_id() */
+ ENGINE_free(e);
+
+I<Automatically using builtin ENGINE implementations>
+
+Here we'll assume we want to load and register all ENGINE implementations
+bundled with OpenSSL, such that for any cryptographic algorithm required by
+OpenSSL - if there is an ENGINE that implements it and can be initialise,
+it should be used. The following code illustrates how this can work;
+
+ /* Load all bundled ENGINEs into memory and make them visible */
+ ENGINE_load_builtin_engines();
+ /* Register all of them for every algorithm they collectively implement */
+ ENGINE_register_all_complete();
+
+That's all that's required. Eg. the next time OpenSSL tries to set up an
+RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to
+ENGINE_init() and if any of those succeed, that ENGINE will be set as the
+default for RSA use from then on.
+
+=head2 Advanced configuration support
+
+There is a mechanism supported by the ENGINE framework that allows each
+ENGINE implementation to define an arbitrary set of configuration
+"commands" and expose them to OpenSSL and any applications based on
+OpenSSL. This mechanism is entirely based on the use of name-value pairs
+and assumes ASCII input (no unicode or UTF for now!), so it is ideal if
+applications want to provide a transparent way for users to provide
+arbitrary configuration "directives" directly to such ENGINEs. It is also
+possible for the application to dynamically interrogate the loaded ENGINE
+implementations for the names, descriptions, and input flags of their
+available "control commands", providing a more flexible configuration
+scheme. However, if the user is expected to know which ENGINE device he/she
+is using (in the case of specialised hardware, this goes without saying)
+then applications may not need to concern themselves with discovering the
+supported control commands and simply prefer to pass settings into ENGINEs
+exactly as they are provided by the user.
+
+Before illustrating how control commands work, it is worth mentioning what
+they are typically used for. Broadly speaking there are two uses for
+control commands; the first is to provide the necessary details to the
+implementation (which may know nothing at all specific to the host system)
+so that it can be initialised for use. This could include the path to any
+driver or config files it needs to load, required network addresses,
+smart-card identifiers, passwords to initialise protected devices,
+logging information, etc etc. This class of commands typically needs to be
+passed to an ENGINE B<before> attempting to initialise it, ie. before
+calling ENGINE_init(). The other class of commands consist of settings or
+operations that tweak certain behaviour or cause certain operations to take
+place, and these commands may work either before or after ENGINE_init(), or
+in some cases both. ENGINE implementations should provide indications of
+this in the descriptions attached to builtin control commands and/or in
+external product documentation.
+
+I<Issuing control commands to an ENGINE>
+
+Let's illustrate by example; a function for which the caller supplies the
+name of the ENGINE it wishes to use, a table of string-pairs for use before
+initialisation, and another table for use after initialisation. Note that
+the string-pairs used for control commands consist of a command "name"
+followed by the command "parameter" - the parameter could be NULL in some
+cases but the name can not. This function should initialise the ENGINE
+(issuing the "pre" commands beforehand and the "post" commands afterwards)
+and set it as the default for everything except RAND and then return a
+boolean success or failure.
+
+ int generic_load_engine_fn(const char *engine_id,
+ const char **pre_cmds, int pre_num,
+ const char **post_cmds, int post_num)
+ {
+ ENGINE *e = ENGINE_by_id(engine_id);
+ if(!e) return 0;
+ while(pre_num--) {
+ if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) {
+ fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
+ pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)");
+ ENGINE_free(e);
+ return 0;
+ }
+ pre_cmds += 2;
+ }
+ if(!ENGINE_init(e)) {
+ fprintf(stderr, "Failed initialisation\n");
+ ENGINE_free(e);
+ return 0;
+ }
+ /* ENGINE_init() returned a functional reference, so free the structural
+ * reference from ENGINE_by_id(). */
+ ENGINE_free(e);
+ while(post_num--) {
+ if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) {
+ fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
+ post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)");
+ ENGINE_finish(e);
+ return 0;
+ }
+ post_cmds += 2;
+ }
+ ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);
+ /* Success */
+ return 1;
+ }
+
+Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can
+relax the semantics of the function - if set non-zero it will only return
+failure if the ENGINE supported the given command name but failed while
+executing it, if the ENGINE doesn't support the command name it will simply
+return success without doing anything. In this case we assume the user is
+only supplying commands specific to the given ENGINE so we set this to
+FALSE.
+
+I<Discovering supported control commands>
+
+It is possible to discover at run-time the names, numerical-ids, descriptions
+and input parameters of the control commands supported by an ENGINE using a
+structural reference. Note that some control commands are defined by OpenSSL
+itself and it will intercept and handle these control commands on behalf of the
+ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command.
+openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands
+implemented by ENGINEs should be numbered from. Any command value lower than
+this symbol is considered a "generic" command is handled directly by the
+OpenSSL core routines.
+
+It is using these "core" control commands that one can discover the the control
+commands implemented by a given ENGINE, specifically the commands;
+
+ #define ENGINE_HAS_CTRL_FUNCTION 10
+ #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11
+ #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12
+ #define ENGINE_CTRL_GET_CMD_FROM_NAME 13
+ #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14
+ #define ENGINE_CTRL_GET_NAME_FROM_CMD 15
+ #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16
+ #define ENGINE_CTRL_GET_DESC_FROM_CMD 17
+ #define ENGINE_CTRL_GET_CMD_FLAGS 18
+
+Whilst these commands are automatically processed by the OpenSSL framework code,
+they use various properties exposed by each ENGINE to process these
+queries. An ENGINE has 3 properties it exposes that can affect how this behaves;
+it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in
+the ENGINE's flags, and it can expose an array of control command descriptions.
+If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will
+simply pass all these "core" control commands directly to the ENGINE's ctrl()
+handler (and thus, it must have supplied one), so it is up to the ENGINE to
+reply to these "discovery" commands itself. If that flag is not set, then the
+OpenSSL framework code will work with the following rules;
+
+ if no ctrl() handler supplied;
+ ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero),
+ all other commands fail.
+ if a ctrl() handler was supplied but no array of control commands;
+ ENGINE_HAS_CTRL_FUNCTION returns TRUE,
+ all other commands fail.
+ if a ctrl() handler and array of control commands was supplied;
+ ENGINE_HAS_CTRL_FUNCTION returns TRUE,
+ all other commands proceed processing ...
+
+If the ENGINE's array of control commands is empty then all other commands will
+fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of
+the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the
+identifier of a command supported by the ENGINE and returns the next command
+identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string
+name for a command and returns the corresponding identifier or fails if no such
+command name exists, and the remaining commands take a command identifier and
+return properties of the corresponding commands. All except
+ENGINE_CTRL_GET_FLAGS return the string length of a command name or description,
+or populate a supplied character buffer with a copy of the command name or
+description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following
+possible values;
+
+ #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001
+ #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002
+ #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004
+ #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008
+
+If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely
+informational to the caller - this flag will prevent the command being usable
+for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string().
+"INTERNAL" commands are not intended to be exposed to text-based configuration
+by applications, administrations, users, etc. These can support arbitrary
+operations via ENGINE_ctrl(), including passing to and/or from the control
+commands data of any arbitrary type. These commands are supported in the
+discovery mechanisms simply to allow applications determinie if an ENGINE
+supports certain specific commands it might want to use (eg. application "foo"
+might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" -
+and ENGINE could therefore decide whether or not to support this "foo"-specific
+extension).
+
+=head2 Future developments
+
+The ENGINE API and internal architecture is currently being reviewed. Slated for
+possible release in 0.9.8 is support for transparent loading of "dynamic"
+ENGINEs (built as self-contained shared-libraries). This would allow ENGINE
+implementations to be provided independently of OpenSSL libraries and/or
+OpenSSL-based applications, and would also remove any requirement for
+applications to explicitly use the "dynamic" ENGINE to bind to shared-library
+implementations.
+
+=head1 SEE ALSO
+
+L<rsa(3)|rsa(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rand(3)|rand(3)>
+
+=cut
diff --git a/openssl/doc/crypto/err.pod b/openssl/doc/crypto/err.pod
new file mode 100644
index 000000000..6f729554d
--- /dev/null
+++ b/openssl/doc/crypto/err.pod
@@ -0,0 +1,187 @@
+=pod
+
+=head1 NAME
+
+err - error codes
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ unsigned long ERR_get_error(void);
+ unsigned long ERR_peek_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_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);
+
+ int ERR_GET_LIB(unsigned long e);
+ int ERR_GET_FUNC(unsigned long e);
+ int ERR_GET_REASON(unsigned long e);
+
+ void ERR_clear_error(void);
+
+ char *ERR_error_string(unsigned long e, char *buf);
+ 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);
+
+ void ERR_print_errors(BIO *bp);
+ void ERR_print_errors_fp(FILE *fp);
+
+ void ERR_load_crypto_strings(void);
+ void ERR_free_strings(void);
+
+ void ERR_remove_state(unsigned long pid);
+
+ void ERR_put_error(int lib, int func, int reason, const char *file,
+ int line);
+ void ERR_add_error_data(int num, ...);
+
+ void ERR_load_strings(int lib,ERR_STRING_DATA str[]);
+ unsigned long ERR_PACK(int lib, int func, int reason);
+ int ERR_get_next_error_library(void);
+
+=head1 DESCRIPTION
+
+When a call to the OpenSSL library fails, this is usually signalled
+by the return value, and an error code is stored in an error queue
+associated with the current thread. The B<err> library provides
+functions to obtain these error codes and textual error messages.
+
+The L<ERR_get_error(3)|ERR_get_error(3)> manpage describes how to
+access error codes.
+
+Error codes contain information about where the error occurred, and
+what went wrong. L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> describes how to
+extract this information. A method to obtain human-readable error
+messages is described in L<ERR_error_string(3)|ERR_error_string(3)>.
+
+L<ERR_clear_error(3)|ERR_clear_error(3)> can be used to clear the
+error queue.
+
+Note that L<ERR_remove_state(3)|ERR_remove_state(3)> should be used to
+avoid memory leaks when threads are terminated.
+
+=head1 ADDING NEW ERROR CODES TO OPENSSL
+
+See L<ERR_put_error(3)> if you want to record error codes in the
+OpenSSL error system from within your application.
+
+The remainder of this section is of interest only if you want to add
+new error codes to OpenSSL or add error codes from external libraries.
+
+=head2 Reporting errors
+
+Each sub-library has a specific macro XXXerr() that is used to report
+errors. Its first argument is a function code B<XXX_F_...>, the second
+argument is a reason code B<XXX_R_...>. Function codes are derived
+from the function names; reason codes consist of textual error
+descriptions. For example, the function ssl23_read() reports a
+"handshake failure" as follows:
+
+ SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE);
+
+Function and reason codes should consist of upper case characters,
+numbers and underscores only. The error file generation script translates
+function codes into function names by looking in the header files
+for an appropriate function name, if none is found it just uses
+the capitalized form such as "SSL23_READ" in the above example.
+
+The trailing section of a reason code (after the "_R_") is translated
+into lower case and underscores changed to spaces.
+
+When you are using new function or reason codes, run B<make errors>.
+The necessary B<#define>s will then automatically be added to the
+sub-library's header file.
+
+Although a library will normally report errors using its own specific
+XXXerr macro, another library's macro can be used. This is normally
+only done when a library wants to include ASN1 code which must use
+the ASN1err() macro.
+
+=head2 Adding new libraries
+
+When adding a new sub-library to OpenSSL, assign it a library number
+B<ERR_LIB_XXX>, define a macro XXXerr() (both in B<err.h>), add its
+name to B<ERR_str_libraries[]> (in B<crypto/err/err.c>), and add
+C<ERR_load_XXX_strings()> to the ERR_load_crypto_strings() function
+(in B<crypto/err/err_all.c>). Finally, add an entry
+
+ L XXX xxx.h xxx_err.c
+
+to B<crypto/err/openssl.ec>, and add B<xxx_err.c> to the Makefile.
+Running B<make errors> will then generate a file B<xxx_err.c>, and
+add all error codes used in the library to B<xxx.h>.
+
+Additionally the library include file must have a certain form.
+Typically it will initially look like this:
+
+ #ifndef HEADER_XXX_H
+ #define HEADER_XXX_H
+
+ #ifdef __cplusplus
+ extern "C" {
+ #endif
+
+ /* Include files */
+
+ #include <openssl/bio.h>
+ #include <openssl/x509.h>
+
+ /* Macros, structures and function prototypes */
+
+
+ /* BEGIN ERROR CODES */
+
+The B<BEGIN ERROR CODES> sequence is used by the error code
+generation script as the point to place new error codes, any text
+after this point will be overwritten when B<make errors> is run.
+The closing #endif etc will be automatically added by the script.
+
+The generated C error code file B<xxx_err.c> will load the header
+files B<stdio.h>, B<openssl/err.h> and B<openssl/xxx.h> so the
+header file must load any additional header files containing any
+definitions it uses.
+
+=head1 USING ERROR CODES IN EXTERNAL LIBRARIES
+
+It is also possible to use OpenSSL's error code scheme in external
+libraries. The library needs to load its own codes and call the OpenSSL
+error code insertion script B<mkerr.pl> explicitly to add codes to
+the header file and generate the C error code file. This will normally
+be done if the external library needs to generate new ASN1 structures
+but it can also be used to add more general purpose error code handling.
+
+TBA more details
+
+=head1 INTERNALS
+
+The error queues are stored in a hash table with one B<ERR_STATE>
+entry for each pid. ERR_get_state() returns the current thread's
+B<ERR_STATE>. An B<ERR_STATE> can hold up to B<ERR_NUM_ERRORS> error
+codes. When more error codes are added, the old ones are overwritten,
+on the assumption that the most recent errors are most important.
+
+Error strings are also stored in hash table. The hash tables can
+be obtained by calling ERR_get_err_state_table(void) and
+ERR_get_string_table(void) respectively.
+
+=head1 SEE ALSO
+
+L<CRYPTO_set_id_callback(3)|CRYPTO_set_id_callback(3)>,
+L<CRYPTO_set_locking_callback(3)|CRYPTO_set_locking_callback(3)>,
+L<ERR_get_error(3)|ERR_get_error(3)>,
+L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>,
+L<ERR_clear_error(3)|ERR_clear_error(3)>,
+L<ERR_error_string(3)|ERR_error_string(3)>,
+L<ERR_print_errors(3)|ERR_print_errors(3)>,
+L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
+L<ERR_remove_state(3)|ERR_remove_state(3)>,
+L<ERR_put_error(3)|ERR_put_error(3)>,
+L<ERR_load_strings(3)|ERR_load_strings(3)>,
+L<SSL_get_error(3)|SSL_get_error(3)>
+
+=cut
diff --git a/openssl/doc/crypto/evp.pod b/openssl/doc/crypto/evp.pod
new file mode 100644
index 000000000..b3ca14314
--- /dev/null
+++ b/openssl/doc/crypto/evp.pod
@@ -0,0 +1,45 @@
+=pod
+
+=head1 NAME
+
+evp - high-level cryptographic functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+=head1 DESCRIPTION
+
+The EVP library provides a high-level interface to cryptographic
+functions.
+
+B<EVP_Seal>I<...> and B<EVP_Open>I<...> provide public key encryption
+and decryption to implement digital "envelopes".
+
+The B<EVP_Sign>I<...> and B<EVP_Verify>I<...> functions implement
+digital signatures.
+
+Symmetric encryption is available with the B<EVP_Encrypt>I<...>
+functions. The B<EVP_Digest>I<...> functions provide message digests.
+
+Algorithms are loaded with OpenSSL_add_all_algorithms(3).
+
+All the symmetric algorithms (ciphers) and digests can be replaced by ENGINE
+modules providing alternative implementations. If ENGINE implementations of
+ciphers or digests are registered as defaults, then the various EVP functions
+will automatically use those implementations automatically in preference to
+built in software implementations. For more information, consult the engine(3)
+man page.
+
+=head1 SEE ALSO
+
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>,
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
+L<EVP_OpenInit(3)|EVP_OpenInit(3)>,
+L<EVP_SealInit(3)|EVP_SealInit(3)>,
+L<EVP_SignInit(3)|EVP_SignInit(3)>,
+L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>,
+L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>,
+L<engine(3)|engine(3)>
+
+=cut
diff --git a/openssl/doc/crypto/hmac.pod b/openssl/doc/crypto/hmac.pod
new file mode 100644
index 000000000..0bd79a6d3
--- /dev/null
+++ b/openssl/doc/crypto/hmac.pod
@@ -0,0 +1,102 @@
+=pod
+
+=head1 NAME
+
+HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message
+authentication code
+
+=head1 SYNOPSIS
+
+ #include <openssl/hmac.h>
+
+ unsigned char *HMAC(const EVP_MD *evp_md, const void *key,
+ int key_len, const unsigned char *d, int n,
+ unsigned char *md, unsigned int *md_len);
+
+ void HMAC_CTX_init(HMAC_CTX *ctx);
+
+ void HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
+ const EVP_MD *md);
+ void HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len,
+ const EVP_MD *md, ENGINE *impl);
+ void HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len);
+ void HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);
+
+ void HMAC_CTX_cleanup(HMAC_CTX *ctx);
+ void HMAC_cleanup(HMAC_CTX *ctx);
+
+=head1 DESCRIPTION
+
+HMAC is a MAC (message authentication code), i.e. a keyed hash
+function used for message authentication, which is based on a hash
+function.
+
+HMAC() computes the message authentication code of the B<n> bytes at
+B<d> using the hash function B<evp_md> and the key B<key> which is
+B<key_len> bytes long.
+
+It places the result in B<md> (which must have space for the output of
+the hash function, which is no more than B<EVP_MAX_MD_SIZE> bytes).
+If B<md> is NULL, the digest is placed in a static array. The size of
+the output is placed in B<md_len>, unless it is B<NULL>.
+
+B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc.
+B<key> and B<evp_md> may be B<NULL> if a key and hash function have
+been set in a previous call to HMAC_Init() for that B<HMAC_CTX>.
+
+HMAC_CTX_init() initialises a B<HMAC_CTX> before first use. It must be
+called.
+
+HMAC_CTX_cleanup() erases the key and other data from the B<HMAC_CTX>
+and releases any associated resources. It must be called when an
+B<HMAC_CTX> is no longer required.
+
+HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back
+compatibility with 0.9.6b, it is deprecated.
+
+The following functions may be used if the message is not completely
+stored in memory:
+
+HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash
+function B<evp_md> and the key B<key> which is B<key_len> bytes
+long. It is deprecated and only included for backward compatibility
+with OpenSSL 0.9.6b.
+
+HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use
+the function B<evp_md> and key B<key>. Either can be NULL, in which
+case the existing one will be reused. HMAC_CTX_init() must have been
+called before the first use of an B<HMAC_CTX> in this
+function. B<N.B. HMAC_Init() had this undocumented behaviour in
+previous versions of OpenSSL - failure to switch to HMAC_Init_ex() in
+programs that expect it will cause them to stop working>.
+
+HMAC_Update() can be called repeatedly with chunks of the message to
+be authenticated (B<len> bytes at B<data>).
+
+HMAC_Final() places the message authentication code in B<md>, which
+must have space for the hash function output.
+
+=head1 RETURN VALUES
+
+HMAC() returns a pointer to the message authentication code.
+
+HMAC_CTX_init(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and
+HMAC_CTX_cleanup() do not return values.
+
+=head1 CONFORMING TO
+
+RFC 2104
+
+=head1 SEE ALSO
+
+L<sha(3)|sha(3)>, L<evp(3)|evp(3)>
+
+=head1 HISTORY
+
+HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup()
+are available since SSLeay 0.9.0.
+
+HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available
+since OpenSSL 0.9.7.
+
+=cut
diff --git a/openssl/doc/crypto/lh_stats.pod b/openssl/doc/crypto/lh_stats.pod
new file mode 100644
index 000000000..3eeaa72e5
--- /dev/null
+++ b/openssl/doc/crypto/lh_stats.pod
@@ -0,0 +1,60 @@
+=pod
+
+=head1 NAME
+
+lh_stats, lh_node_stats, lh_node_usage_stats, lh_stats_bio,
+lh_node_stats_bio, lh_node_usage_stats_bio - LHASH statistics
+
+=head1 SYNOPSIS
+
+ #include <openssl/lhash.h>
+
+ void lh_stats(LHASH *table, FILE *out);
+ void lh_node_stats(LHASH *table, FILE *out);
+ void lh_node_usage_stats(LHASH *table, FILE *out);
+
+ void lh_stats_bio(LHASH *table, BIO *out);
+ void lh_node_stats_bio(LHASH *table, BIO *out);
+ void lh_node_usage_stats_bio(LHASH *table, BIO *out);
+
+=head1 DESCRIPTION
+
+The B<LHASH> structure records statistics about most aspects of
+accessing the hash table. This is mostly a legacy of Eric Young
+writing this library for the reasons of implementing what looked like
+a nice algorithm rather than for a particular software product.
+
+lh_stats() prints out statistics on the size of the hash table, how
+many entries are in it, and the number and result of calls to the
+routines in this library.
+
+lh_node_stats() prints the number of entries for each 'bucket' in the
+hash table.
+
+lh_node_usage_stats() prints out a short summary of the state of the
+hash table. It prints the 'load' and the 'actual load'. The load is
+the average number of data items per 'bucket' in the hash table. The
+'actual load' is the average number of items per 'bucket', but only
+for buckets which contain entries. So the 'actual load' is the
+average number of searches that will need to find an item in the hash
+table, while the 'load' is the average number that will be done to
+record a miss.
+
+lh_stats_bio(), lh_node_stats_bio() and lh_node_usage_stats_bio()
+are the same as the above, except that the output goes to a B<BIO>.
+
+=head1 RETURN VALUES
+
+These functions do not return values.
+
+=head1 SEE ALSO
+
+L<bio(3)|bio(3)>, L<lhash(3)|lhash(3)>
+
+=head1 HISTORY
+
+These functions are available in all versions of SSLeay and OpenSSL.
+
+This manpage is derived from the SSLeay documentation.
+
+=cut
diff --git a/openssl/doc/crypto/lhash.pod b/openssl/doc/crypto/lhash.pod
new file mode 100644
index 000000000..dcdbb43a8
--- /dev/null
+++ b/openssl/doc/crypto/lhash.pod
@@ -0,0 +1,294 @@
+=pod
+
+=head1 NAME
+
+lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_error - dynamic hash table
+
+=head1 SYNOPSIS
+
+ #include <openssl/lhash.h>
+
+ LHASH *lh_new(LHASH_HASH_FN_TYPE hash, LHASH_COMP_FN_TYPE compare);
+ void lh_free(LHASH *table);
+
+ void *lh_insert(LHASH *table, void *data);
+ void *lh_delete(LHASH *table, void *data);
+ void *lh_retrieve(LHASH *table, void *data);
+
+ void lh_doall(LHASH *table, LHASH_DOALL_FN_TYPE func);
+ void lh_doall_arg(LHASH *table, LHASH_DOALL_ARG_FN_TYPE func,
+ void *arg);
+
+ int lh_error(LHASH *table);
+
+ typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *);
+ typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *);
+ typedef void (*LHASH_DOALL_FN_TYPE)(const void *);
+ typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *);
+
+=head1 DESCRIPTION
+
+This library implements dynamic hash tables. The hash table entries
+can be arbitrary structures. Usually they consist of key and value
+fields.
+
+lh_new() creates a new B<LHASH> structure to store arbitrary data
+entries, and provides the 'hash' and 'compare' callbacks to be used in
+organising the table's entries. The B<hash> callback takes a pointer
+to a table entry as its argument and returns an unsigned long hash
+value for its key field. The hash value is normally truncated to a
+power of 2, so make sure that your hash function returns well mixed
+low order bits. The B<compare> callback takes two arguments (pointers
+to two hash table entries), and returns 0 if their keys are equal,
+non-zero otherwise. If your hash table will contain items of some
+particular type and the B<hash> and B<compare> callbacks hash/compare
+these types, then the B<DECLARE_LHASH_HASH_FN> and
+B<IMPLEMENT_LHASH_COMP_FN> macros can be used to create callback
+wrappers of the prototypes required by lh_new(). These provide
+per-variable casts before calling the type-specific callbacks written
+by the application author. These macros, as well as those used for
+the "doall" callbacks, are defined as;
+
+ #define DECLARE_LHASH_HASH_FN(f_name,o_type) \
+ unsigned long f_name##_LHASH_HASH(const void *);
+ #define IMPLEMENT_LHASH_HASH_FN(f_name,o_type) \
+ unsigned long f_name##_LHASH_HASH(const void *arg) { \
+ o_type a = (o_type)arg; \
+ return f_name(a); }
+ #define LHASH_HASH_FN(f_name) f_name##_LHASH_HASH
+
+ #define DECLARE_LHASH_COMP_FN(f_name,o_type) \
+ int f_name##_LHASH_COMP(const void *, const void *);
+ #define IMPLEMENT_LHASH_COMP_FN(f_name,o_type) \
+ int f_name##_LHASH_COMP(const void *arg1, const void *arg2) { \
+ o_type a = (o_type)arg1; \
+ o_type b = (o_type)arg2; \
+ return f_name(a,b); }
+ #define LHASH_COMP_FN(f_name) f_name##_LHASH_COMP
+
+ #define DECLARE_LHASH_DOALL_FN(f_name,o_type) \
+ void f_name##_LHASH_DOALL(const void *);
+ #define IMPLEMENT_LHASH_DOALL_FN(f_name,o_type) \
+ void f_name##_LHASH_DOALL(const void *arg) { \
+ o_type a = (o_type)arg; \
+ f_name(a); }
+ #define LHASH_DOALL_FN(f_name) f_name##_LHASH_DOALL
+
+ #define DECLARE_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \
+ void f_name##_LHASH_DOALL_ARG(const void *, const void *);
+ #define IMPLEMENT_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \
+ void f_name##_LHASH_DOALL_ARG(const void *arg1, const void *arg2) { \
+ o_type a = (o_type)arg1; \
+ a_type b = (a_type)arg2; \
+ f_name(a,b); }
+ #define LHASH_DOALL_ARG_FN(f_name) f_name##_LHASH_DOALL_ARG
+
+An example of a hash table storing (pointers to) structures of type 'STUFF'
+could be defined as follows;
+
+ /* Calculates the hash value of 'tohash' (implemented elsewhere) */
+ unsigned long STUFF_hash(const STUFF *tohash);
+ /* Orders 'arg1' and 'arg2' (implemented elsewhere) */
+ int STUFF_cmp(const STUFF *arg1, const STUFF *arg2);
+ /* Create the type-safe wrapper functions for use in the LHASH internals */
+ static IMPLEMENT_LHASH_HASH_FN(STUFF_hash, const STUFF *)
+ static IMPLEMENT_LHASH_COMP_FN(STUFF_cmp, const STUFF *);
+ /* ... */
+ int main(int argc, char *argv[]) {
+ /* Create the new hash table using the hash/compare wrappers */
+ LHASH *hashtable = lh_new(LHASH_HASH_FN(STUFF_hash),
+ LHASH_COMP_FN(STUFF_cmp));
+ /* ... */
+ }
+
+lh_free() frees the B<LHASH> structure B<table>. Allocated hash table
+entries will not be freed; consider using lh_doall() to deallocate any
+remaining entries in the hash table (see below).
+
+lh_insert() inserts the structure pointed to by B<data> into B<table>.
+If there already is an entry with the same key, the old value is
+replaced. Note that lh_insert() stores pointers, the data are not
+copied.
+
+lh_delete() deletes an entry from B<table>.
+
+lh_retrieve() looks up an entry in B<table>. Normally, B<data> is
+a structure with the key field(s) set; the function will return a
+pointer to a fully populated structure.
+
+lh_doall() will, for every entry in the hash table, call B<func> with
+the data item as its parameter. For lh_doall() and lh_doall_arg(),
+function pointer casting should be avoided in the callbacks (see
+B<NOTE>) - instead, either declare the callbacks to match the
+prototype required in lh_new() or use the declare/implement macros to
+create type-safe wrappers that cast variables prior to calling your
+type-specific callbacks. An example of this is illustrated here where
+the callback is used to cleanup resources for items in the hash table
+prior to the hashtable itself being deallocated:
+
+ /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */
+ void STUFF_cleanup(STUFF *a);
+ /* Implement a prototype-compatible wrapper for "STUFF_cleanup" */
+ IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF *)
+ /* ... then later in the code ... */
+ /* So to run "STUFF_cleanup" against all items in a hash table ... */
+ lh_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup));
+ /* Then the hash table itself can be deallocated */
+ lh_free(hashtable);
+
+When doing this, be careful if you delete entries from the hash table
+in your callbacks: the table may decrease in size, moving the item
+that you are currently on down lower in the hash table - this could
+cause some entries to be skipped during the iteration. The second
+best solution to this problem is to set hash-E<gt>down_load=0 before
+you start (which will stop the hash table ever decreasing in size).
+The best solution is probably to avoid deleting items from the hash
+table inside a "doall" callback!
+
+lh_doall_arg() is the same as lh_doall() except that B<func> will be
+called with B<arg> as the second argument and B<func> should be of
+type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype that is passed
+both the table entry and an extra argument). As with lh_doall(), you
+can instead choose to declare your callback with a prototype matching
+the types you are dealing with and use the declare/implement macros to
+create compatible wrappers that cast variables before calling your
+type-specific callbacks. An example of this is demonstrated here
+(printing all hash table entries to a BIO that is provided by the
+caller):
+
+ /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */
+ void STUFF_print(const STUFF *a, BIO *output_bio);
+ /* Implement a prototype-compatible wrapper for "STUFF_print" */
+ static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF_print, const STUFF *, BIO *)
+ /* ... then later in the code ... */
+ /* Print out the entire hashtable to a particular BIO */
+ lh_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), logging_bio);
+
+lh_error() can be used to determine if an error occurred in the last
+operation. lh_error() is a macro.
+
+=head1 RETURN VALUES
+
+lh_new() returns B<NULL> on error, otherwise a pointer to the new
+B<LHASH> structure.
+
+When a hash table entry is replaced, lh_insert() returns the value
+being replaced. B<NULL> is returned on normal operation and on error.
+
+lh_delete() returns the entry being deleted. B<NULL> is returned if
+there is no such value in the hash table.
+
+lh_retrieve() returns the hash table entry if it has been found,
+B<NULL> otherwise.
+
+lh_error() returns 1 if an error occurred in the last operation, 0
+otherwise.
+
+lh_free(), lh_doall() and lh_doall_arg() return no values.
+
+=head1 NOTE
+
+The various LHASH macros and callback types exist to make it possible
+to write type-safe code without resorting to function-prototype
+casting - an evil that makes application code much harder to
+audit/verify and also opens the window of opportunity for stack
+corruption and other hard-to-find bugs. It also, apparently, violates
+ANSI-C.
+
+The LHASH code regards table entries as constant data. As such, it
+internally represents lh_insert()'d items with a "const void *"
+pointer type. This is why callbacks such as those used by lh_doall()
+and lh_doall_arg() declare their prototypes with "const", even for the
+parameters that pass back the table items' data pointers - for
+consistency, user-provided data is "const" at all times as far as the
+LHASH code is concerned. However, as callers are themselves providing
+these pointers, they can choose whether they too should be treating
+all such parameters as constant.
+
+As an example, a hash table may be maintained by code that, for
+reasons of encapsulation, has only "const" access to the data being
+indexed in the hash table (ie. it is returned as "const" from
+elsewhere in their code) - in this case the LHASH prototypes are
+appropriate as-is. Conversely, if the caller is responsible for the
+life-time of the data in question, then they may well wish to make
+modifications to table item passed back in the lh_doall() or
+lh_doall_arg() callbacks (see the "STUFF_cleanup" example above). If
+so, the caller can either cast the "const" away (if they're providing
+the raw callbacks themselves) or use the macros to declare/implement
+the wrapper functions without "const" types.
+
+Callers that only have "const" access to data they're indexing in a
+table, yet declare callbacks without constant types (or cast the
+"const" away themselves), are therefore creating their own risks/bugs
+without being encouraged to do so by the API. On a related note,
+those auditing code should pay special attention to any instances of
+DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types
+without any "const" qualifiers.
+
+=head1 BUGS
+
+lh_insert() returns B<NULL> both for success and error.
+
+=head1 INTERNALS
+
+The following description is based on the SSLeay documentation:
+
+The B<lhash> library implements a hash table described in the
+I<Communications of the ACM> in 1991. What makes this hash table
+different is that as the table fills, the hash table is increased (or
+decreased) in size via OPENSSL_realloc(). When a 'resize' is done, instead of
+all hashes being redistributed over twice as many 'buckets', one
+bucket is split. So when an 'expand' is done, there is only a minimal
+cost to redistribute some values. Subsequent inserts will cause more
+single 'bucket' redistributions but there will never be a sudden large
+cost due to redistributing all the 'buckets'.
+
+The state for a particular hash table is kept in the B<LHASH> structure.
+The decision to increase or decrease the hash table size is made
+depending on the 'load' of the hash table. The load is the number of
+items in the hash table divided by the size of the hash table. The
+default values are as follows. If (hash->up_load E<lt> load) =E<gt>
+expand. if (hash-E<gt>down_load E<gt> load) =E<gt> contract. The
+B<up_load> has a default value of 1 and B<down_load> has a default value
+of 2. These numbers can be modified by the application by just
+playing with the B<up_load> and B<down_load> variables. The 'load' is
+kept in a form which is multiplied by 256. So
+hash-E<gt>up_load=8*256; will cause a load of 8 to be set.
+
+If you are interested in performance the field to watch is
+num_comp_calls. The hash library keeps track of the 'hash' value for
+each item so when a lookup is done, the 'hashes' are compared, if
+there is a match, then a full compare is done, and
+hash-E<gt>num_comp_calls is incremented. If num_comp_calls is not equal
+to num_delete plus num_retrieve it means that your hash function is
+generating hashes that are the same for different values. It is
+probably worth changing your hash function if this is the case because
+even if your hash table has 10 items in a 'bucket', it can be searched
+with 10 B<unsigned long> compares and 10 linked list traverses. This
+will be much less expensive that 10 calls to your compare function.
+
+lh_strhash() is a demo string hashing function:
+
+ unsigned long lh_strhash(const char *c);
+
+Since the B<LHASH> routines would normally be passed structures, this
+routine would not normally be passed to lh_new(), rather it would be
+used in the function passed to lh_new().
+
+=head1 SEE ALSO
+
+L<lh_stats(3)|lh_stats(3)>
+
+=head1 HISTORY
+
+The B<lhash> library is available in all versions of SSLeay and OpenSSL.
+lh_error() was added in SSLeay 0.9.1b.
+
+This manpage is derived from the SSLeay documentation.
+
+In OpenSSL 0.9.7, all lhash functions that were passed function pointers
+were changed for better type safety, and the function types LHASH_COMP_FN_TYPE,
+LHASH_HASH_FN_TYPE, LHASH_DOALL_FN_TYPE and LHASH_DOALL_ARG_FN_TYPE
+became available.
+
+=cut
diff --git a/openssl/doc/crypto/md5.pod b/openssl/doc/crypto/md5.pod
new file mode 100644
index 000000000..d11d5c32c
--- /dev/null
+++ b/openssl/doc/crypto/md5.pod
@@ -0,0 +1,101 @@
+=pod
+
+=head1 NAME
+
+MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update,
+MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/md2.h>
+
+ unsigned char *MD2(const unsigned char *d, unsigned long n,
+ unsigned char *md);
+
+ int MD2_Init(MD2_CTX *c);
+ int MD2_Update(MD2_CTX *c, const unsigned char *data,
+ unsigned long len);
+ int MD2_Final(unsigned char *md, MD2_CTX *c);
+
+
+ #include <openssl/md4.h>
+
+ unsigned char *MD4(const unsigned char *d, unsigned long n,
+ unsigned char *md);
+
+ int MD4_Init(MD4_CTX *c);
+ int MD4_Update(MD4_CTX *c, const void *data,
+ unsigned long len);
+ int MD4_Final(unsigned char *md, MD4_CTX *c);
+
+
+ #include <openssl/md5.h>
+
+ unsigned char *MD5(const unsigned char *d, unsigned long n,
+ unsigned char *md);
+
+ int MD5_Init(MD5_CTX *c);
+ int MD5_Update(MD5_CTX *c, const void *data,
+ unsigned long len);
+ int MD5_Final(unsigned char *md, MD5_CTX *c);
+
+=head1 DESCRIPTION
+
+MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output.
+
+MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest
+of the B<n> bytes at B<d> and place it in B<md> (which must have space
+for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16
+bytes of output). If B<md> is NULL, the digest is placed in a static
+array.
+
+The following functions may be used if the message is not completely
+stored in memory:
+
+MD2_Init() initializes a B<MD2_CTX> structure.
+
+MD2_Update() can be called repeatedly with chunks of the message to
+be hashed (B<len> bytes at B<data>).
+
+MD2_Final() places the message digest in B<md>, which must have space
+for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MD2_CTX>.
+
+MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and
+MD5_Final() are analogous using an B<MD4_CTX> and B<MD5_CTX> structure.
+
+Applications should use the higher level functions
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>
+etc. instead of calling the hash functions directly.
+
+=head1 NOTE
+
+MD2, MD4, and MD5 are recommended only for compatibility with existing
+applications. In new applications, SHA-1 or RIPEMD-160 should be
+preferred.
+
+=head1 RETURN VALUES
+
+MD2(), MD4(), and MD5() return pointers to the hash value.
+
+MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(),
+MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() return 1 for
+success, 0 otherwise.
+
+=head1 CONFORMING TO
+
+RFC 1319, RFC 1320, RFC 1321
+
+=head1 SEE ALSO
+
+L<sha(3)|sha(3)>, L<ripemd(3)|ripemd(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>
+
+=head1 HISTORY
+
+MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(),
+MD5_Update() and MD5_Final() are available in all versions of SSLeay
+and OpenSSL.
+
+MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and
+above.
+
+=cut
diff --git a/openssl/doc/crypto/mdc2.pod b/openssl/doc/crypto/mdc2.pod
new file mode 100644
index 000000000..41f648af3
--- /dev/null
+++ b/openssl/doc/crypto/mdc2.pod
@@ -0,0 +1,64 @@
+=pod
+
+=head1 NAME
+
+MDC2, MDC2_Init, MDC2_Update, MDC2_Final - MDC2 hash function
+
+=head1 SYNOPSIS
+
+ #include <openssl/mdc2.h>
+
+ unsigned char *MDC2(const unsigned char *d, unsigned long n,
+ unsigned char *md);
+
+ int MDC2_Init(MDC2_CTX *c);
+ int MDC2_Update(MDC2_CTX *c, const unsigned char *data,
+ unsigned long len);
+ int MDC2_Final(unsigned char *md, MDC2_CTX *c);
+
+=head1 DESCRIPTION
+
+MDC2 is a method to construct hash functions with 128 bit output from
+block ciphers. These functions are an implementation of MDC2 with
+DES.
+
+MDC2() computes the MDC2 message digest of the B<n>
+bytes at B<d> and places it in B<md> (which must have space for
+MDC2_DIGEST_LENGTH == 16 bytes of output). If B<md> is NULL, the digest
+is placed in a static array.
+
+The following functions may be used if the message is not completely
+stored in memory:
+
+MDC2_Init() initializes a B<MDC2_CTX> structure.
+
+MDC2_Update() can be called repeatedly with chunks of the message to
+be hashed (B<len> bytes at B<data>).
+
+MDC2_Final() places the message digest in B<md>, which must have space
+for MDC2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MDC2_CTX>.
+
+Applications should use the higher level functions
+L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the
+hash functions directly.
+
+=head1 RETURN VALUES
+
+MDC2() returns a pointer to the hash value.
+
+MDC2_Init(), MDC2_Update() and MDC2_Final() return 1 for success, 0 otherwise.
+
+=head1 CONFORMING TO
+
+ISO/IEC 10118-2, with DES
+
+=head1 SEE ALSO
+
+L<sha(3)|sha(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>
+
+=head1 HISTORY
+
+MDC2(), MDC2_Init(), MDC2_Update() and MDC2_Final() are available since
+SSLeay 0.8.
+
+=cut
diff --git a/openssl/doc/crypto/pem.pod b/openssl/doc/crypto/pem.pod
new file mode 100644
index 000000000..4f9a27df0
--- /dev/null
+++ b/openssl/doc/crypto/pem.pod
@@ -0,0 +1,476 @@
+=pod
+
+=head1 NAME
+
+PEM - PEM routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/pem.h>
+
+ EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
+ pem_password_cb *cb, void *u);
+
+ EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
+ pem_password_cb *cb, void *u);
+
+ EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
+ int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
+
+ RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
+ pem_password_cb *cb, void *u);
+
+ RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
+ pem_password_cb *cb, void *u);
+
+ RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
+
+ int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
+
+ RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
+ pem_password_cb *cb, void *u);
+
+ RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
+
+ int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
+
+ DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
+ pem_password_cb *cb, void *u);
+
+ DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
+ pem_password_cb *cb, void *u);
+
+ DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
+
+ int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
+
+ DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
+
+ DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
+
+ int PEM_write_DSAparams(FILE *fp, DSA *x);
+
+ DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
+
+ DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_DHparams(BIO *bp, DH *x);
+
+ int PEM_write_DHparams(FILE *fp, DH *x);
+
+ X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
+
+ X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_X509(BIO *bp, X509 *x);
+
+ int PEM_write_X509(FILE *fp, X509 *x);
+
+ X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
+
+ X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
+
+ int PEM_write_X509_AUX(FILE *fp, X509 *x);
+
+ X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
+ pem_password_cb *cb, void *u);
+
+ X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
+
+ int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
+
+ int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
+
+ int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
+
+ X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
+ pem_password_cb *cb, void *u);
+ X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
+ int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);
+
+ PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
+
+ PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
+
+ int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
+
+ NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
+ NETSCAPE_CERT_SEQUENCE **x,
+ pem_password_cb *cb, void *u);
+
+ NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
+ NETSCAPE_CERT_SEQUENCE **x,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
+
+ int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);
+
+=head1 DESCRIPTION
+
+The PEM functions read or write structures in PEM format. In
+this sense PEM format is simply base64 encoded data surrounded
+by header lines.
+
+For more details about the meaning of arguments see the
+B<PEM FUNCTION ARGUMENTS> section.
+
+Each operation has four functions associated with it. For
+clarity the term "B<foobar> functions" will be used to collectively
+refer to the PEM_read_bio_foobar(), PEM_read_foobar(),
+PEM_write_bio_foobar() and PEM_write_foobar() functions.
+
+The B<PrivateKey> functions read or write a private key in
+PEM format using an EVP_PKEY structure. The write routines use
+"traditional" private key format and can handle both RSA and DSA
+private keys. The read functions can additionally transparently
+handle PKCS#8 format encrypted and unencrypted keys too.
+
+PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey()
+write a private key in an EVP_PKEY structure in PKCS#8
+EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption
+algorithms. The B<cipher> argument specifies the encryption algoritm to
+use: unlike all other PEM routines the encryption is applied at the
+PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no
+encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead.
+
+PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
+also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
+it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
+to use is specified in the B<nid> parameter and should be the NID of the
+corresponding OBJECT IDENTIFIER (see NOTES section).
+
+The B<PUBKEY> functions process a public key using an EVP_PKEY
+structure. The public key is encoded as a SubjectPublicKeyInfo
+structure.
+
+The B<RSAPrivateKey> functions process an RSA private key using an
+RSA structure. It handles the same formats as the B<PrivateKey>
+functions but an error occurs if the private key is not RSA.
+
+The B<RSAPublicKey> functions process an RSA public key using an
+RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey
+structure.
+
+The B<RSA_PUBKEY> functions also process an RSA public key using
+an RSA structure. However the public key is encoded using a
+SubjectPublicKeyInfo structure and an error occurs if the public
+key is not RSA.
+
+The B<DSAPrivateKey> functions process a DSA private key using a
+DSA structure. It handles the same formats as the B<PrivateKey>
+functions but an error occurs if the private key is not DSA.
+
+The B<DSA_PUBKEY> functions process a DSA public key using
+a DSA structure. The public key is encoded using a
+SubjectPublicKeyInfo structure and an error occurs if the public
+key is not DSA.
+
+The B<DSAparams> functions process DSA parameters using a DSA
+structure. The parameters are encoded using a foobar structure.
+
+The B<DHparams> functions process DH parameters using a DH
+structure. The parameters are encoded using a PKCS#3 DHparameter
+structure.
+
+The B<X509> functions process an X509 certificate using an X509
+structure. They will also process a trusted X509 certificate but
+any trust settings are discarded.
+
+The B<X509_AUX> functions process a trusted X509 certificate using
+an X509 structure.
+
+The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10
+certificate request using an X509_REQ structure. The B<X509_REQ>
+write functions use B<CERTIFICATE REQUEST> in the header whereas
+the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST>
+(as required by some CAs). The B<X509_REQ> read functions will
+handle either form so there are no B<X509_REQ_NEW> read functions.
+
+The B<X509_CRL> functions process an X509 CRL using an X509_CRL
+structure.
+
+The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7
+structure.
+
+The B<NETSCAPE_CERT_SEQUENCE> functions process a Netscape Certificate
+Sequence using a NETSCAPE_CERT_SEQUENCE structure.
+
+=head1 PEM FUNCTION ARGUMENTS
+
+The PEM functions have many common arguments.
+
+The B<bp> BIO parameter (if present) specifies the BIO to read from
+or write to.
+
+The B<fp> FILE parameter (if present) specifies the FILE pointer to
+read from or write to.
+
+The PEM read functions all take an argument B<TYPE **x> and return
+a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function
+uses. If B<x> is NULL then the parameter is ignored. If B<x> is not
+NULL but B<*x> is NULL then the structure returned will be written
+to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made
+to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections).
+Irrespective of the value of B<x> a pointer to the structure is always
+returned (or NULL if an error occurred).
+
+The PEM functions which write private keys take an B<enc> parameter
+which specifies the encryption algorithm to use, encryption is done
+at the PEM level. If this parameter is set to NULL then the private
+key is written in unencrypted form.
+
+The B<cb> argument is the callback to use when querying for the pass
+phrase used for encrypted PEM structures (normally only private keys).
+
+For the PEM write routines if the B<kstr> parameter is not NULL then
+B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is
+ignored.
+
+If the B<cb> parameters is set to NULL and the B<u> parameter is not
+NULL then the B<u> parameter is interpreted as a null terminated string
+to use as the passphrase. If both B<cb> and B<u> are NULL then the
+default callback routine is used which will typically prompt for the
+passphrase on the current terminal with echoing turned off.
+
+The default passphrase callback is sometimes inappropriate (for example
+in a GUI application) so an alternative can be supplied. The callback
+routine has the following form:
+
+ int cb(char *buf, int size, int rwflag, void *u);
+
+B<buf> is the buffer to write the passphrase to. B<size> is the maximum
+length of the passphrase (i.e. the size of buf). B<rwflag> is a flag
+which is set to 0 when reading and 1 when writing. A typical routine
+will ask the user to verify the passphrase (for example by prompting
+for it twice) if B<rwflag> is 1. The B<u> parameter has the same
+value as the B<u> parameter passed to the PEM routine. It allows
+arbitrary data to be passed to the callback by the application
+(for example a window handle in a GUI application). The callback
+B<must> return the number of characters in the passphrase or 0 if
+an error occurred.
+
+=head1 EXAMPLES
+
+Although the PEM routines take several arguments in almost all applications
+most of them are set to 0 or NULL.
+
+Read a certificate in PEM format from a BIO:
+
+ X509 *x;
+ x = PEM_read_bio_X509(bp, NULL, 0, NULL);
+ if (x == NULL)
+ {
+ /* Error */
+ }
+
+Alternative method:
+
+ X509 *x = NULL;
+ if (!PEM_read_bio_X509(bp, &x, 0, NULL))
+ {
+ /* Error */
+ }
+
+Write a certificate to a BIO:
+
+ if (!PEM_write_bio_X509(bp, x))
+ {
+ /* Error */
+ }
+
+Write an unencrypted private key to a FILE pointer:
+
+ if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
+ {
+ /* Error */
+ }
+
+Write a private key (using traditional format) to a BIO using
+triple DES encryption, the pass phrase is prompted for:
+
+ if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
+ {
+ /* Error */
+ }
+
+Write a private key (using PKCS#8 format) to a BIO using triple
+DES encryption, using the pass phrase "hello":
+
+ if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello"))
+ {
+ /* Error */
+ }
+
+Read a private key from a BIO using the pass phrase "hello":
+
+ key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
+ if (key == NULL)
+ {
+ /* Error */
+ }
+
+Read a private key from a BIO using a pass phrase callback:
+
+ key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
+ if (key == NULL)
+ {
+ /* Error */
+ }
+
+Skeleton pass phrase callback:
+
+ int pass_cb(char *buf, int size, int rwflag, void *u);
+ {
+ int len;
+ char *tmp;
+ /* We'd probably do something else if 'rwflag' is 1 */
+ printf("Enter pass phrase for \"%s\"\n", u);
+
+ /* get pass phrase, length 'len' into 'tmp' */
+ tmp = "hello";
+ len = strlen(tmp);
+
+ if (len <= 0) return 0;
+ /* if too long, truncate */
+ if (len > size) len = size;
+ memcpy(buf, tmp, len);
+ return len;
+ }
+
+=head1 NOTES
+
+The old B<PrivateKey> write routines are retained for compatibility.
+New applications should write private keys using the
+PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
+because they are more secure (they use an iteration count of 2048 whereas
+the traditional routines use a count of 1) unless compatibility with older
+versions of OpenSSL is important.
+
+The B<PrivateKey> read routines can be used in all applications because
+they handle all formats transparently.
+
+A frequent cause of problems is attempting to use the PEM routines like
+this:
+
+ X509 *x;
+ PEM_read_bio_X509(bp, &x, 0, NULL);
+
+this is a bug because an attempt will be made to reuse the data at B<x>
+which is an uninitialised pointer.
+
+=head1 PEM ENCRYPTION FORMAT
+
+This old B<PrivateKey> routines use a non standard technique for encryption.
+
+The private key (or other data) takes the following form:
+
+ -----BEGIN RSA PRIVATE KEY-----
+ Proc-Type: 4,ENCRYPTED
+ DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
+
+ ...base64 encoded data...
+ -----END RSA PRIVATE KEY-----
+
+The line beginning DEK-Info contains two comma separated pieces of information:
+the encryption algorithm name as used by EVP_get_cipherbyname() and an 8
+byte B<salt> encoded as a set of hexadecimal digits.
+
+After this is the base64 encoded encrypted data.
+
+The encryption key is determined using EVP_bytestokey(), using B<salt> and an
+iteration count of 1. The IV used is the value of B<salt> and *not* the IV
+returned by EVP_bytestokey().
+
+=head1 BUGS
+
+The PEM read routines in some versions of OpenSSL will not correctly reuse
+an existing structure. Therefore the following:
+
+ PEM_read_bio_X509(bp, &x, 0, NULL);
+
+where B<x> already contains a valid certificate, may not work, whereas:
+
+ X509_free(x);
+ x = PEM_read_bio_X509(bp, NULL, 0, NULL);
+
+is guaranteed to work.
+
+=head1 RETURN CODES
+
+The read routines return either a pointer to the structure read or NULL
+if an error occurred.
+
+The write routines return 1 for success or 0 for failure.
diff --git a/openssl/doc/crypto/rand.pod b/openssl/doc/crypto/rand.pod
new file mode 100644
index 000000000..1c068c85b
--- /dev/null
+++ b/openssl/doc/crypto/rand.pod
@@ -0,0 +1,175 @@
+=pod
+
+=head1 NAME
+
+rand - pseudo-random number generator
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ int RAND_set_rand_engine(ENGINE *engine);
+
+ int RAND_bytes(unsigned char *buf, int num);
+ int RAND_pseudo_bytes(unsigned char *buf, int num);
+
+ void RAND_seed(const void *buf, int num);
+ void RAND_add(const void *buf, int num, int entropy);
+ int RAND_status(void);
+
+ int RAND_load_file(const char *file, long max_bytes);
+ int RAND_write_file(const char *file);
+ const char *RAND_file_name(char *file, size_t num);
+
+ int RAND_egd(const char *path);
+
+ void RAND_set_rand_method(const RAND_METHOD *meth);
+ const RAND_METHOD *RAND_get_rand_method(void);
+ RAND_METHOD *RAND_SSLeay(void);
+
+ void RAND_cleanup(void);
+
+ /* For Win32 only */
+ void RAND_screen(void);
+ int RAND_event(UINT, WPARAM, LPARAM);
+
+=head1 DESCRIPTION
+
+Since the introduction of the ENGINE API, the recommended way of controlling
+default implementations is by using the ENGINE API functions. The default
+B<RAND_METHOD>, as set by RAND_set_rand_method() and returned by
+RAND_get_rand_method(), is only used if no ENGINE has been set as the default
+"rand" implementation. Hence, these two functions are no longer the recommened
+way to control defaults.
+
+If an alternative B<RAND_METHOD> implementation is being used (either set
+directly or as provided by an ENGINE module), then it is entirely responsible
+for the generation and management of a cryptographically secure PRNG stream. The
+mechanisms described below relate solely to the software PRNG implementation
+built in to OpenSSL and used by default.
+
+These functions implement a cryptographically secure pseudo-random
+number generator (PRNG). It is used by other library functions for
+example to generate random keys, and applications can use it when they
+need randomness.
+
+A cryptographic PRNG must be seeded with unpredictable data such as
+mouse movements or keys pressed at random by the user. This is
+described in L<RAND_add(3)|RAND_add(3)>. Its state can be saved in a seed file
+(see L<RAND_load_file(3)|RAND_load_file(3)>) to avoid having to go through the
+seeding process whenever the application is started.
+
+L<RAND_bytes(3)|RAND_bytes(3)> describes how to obtain random data from the
+PRNG.
+
+=head1 INTERNALS
+
+The RAND_SSLeay() method implements a PRNG based on a cryptographic
+hash function.
+
+The following description of its design is based on the SSLeay
+documentation:
+
+First up I will state the things I believe I need for a good RNG.
+
+=over 4
+
+=item 1
+
+A good hashing algorithm to mix things up and to convert the RNG 'state'
+to random numbers.
+
+=item 2
+
+An initial source of random 'state'.
+
+=item 3
+
+The state should be very large. If the RNG is being used to generate
+4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum).
+If your RNG state only has 128 bits, you are obviously limiting the
+search space to 128 bits, not 2048. I'm probably getting a little
+carried away on this last point but it does indicate that it may not be
+a bad idea to keep quite a lot of RNG state. It should be easier to
+break a cipher than guess the RNG seed data.
+
+=item 4
+
+Any RNG seed data should influence all subsequent random numbers
+generated. This implies that any random seed data entered will have
+an influence on all subsequent random numbers generated.
+
+=item 5
+
+When using data to seed the RNG state, the data used should not be
+extractable from the RNG state. I believe this should be a
+requirement because one possible source of 'secret' semi random
+data would be a private key or a password. This data must
+not be disclosed by either subsequent random numbers or a
+'core' dump left by a program crash.
+
+=item 6
+
+Given the same initial 'state', 2 systems should deviate in their RNG state
+(and hence the random numbers generated) over time if at all possible.
+
+=item 7
+
+Given the random number output stream, it should not be possible to determine
+the RNG state or the next random number.
+
+=back
+
+The algorithm is as follows.
+
+There is global state made up of a 1023 byte buffer (the 'state'), a
+working hash value ('md'), and a counter ('count').
+
+Whenever seed data is added, it is inserted into the 'state' as
+follows.
+
+The input is chopped up into units of 20 bytes (or less for
+the last block). Each of these blocks is run through the hash
+function as follows: The data passed to the hash function
+is the current 'md', the same number of bytes from the 'state'
+(the location determined by in incremented looping index) as
+the current 'block', the new key data 'block', and 'count'
+(which is incremented after each use).
+The result of this is kept in 'md' and also xored into the
+'state' at the same locations that were used as input into the
+hash function. I
+believe this system addresses points 1 (hash function; currently
+SHA-1), 3 (the 'state'), 4 (via the 'md'), 5 (by the use of a hash
+function and xor).
+
+When bytes are extracted from the RNG, the following process is used.
+For each group of 10 bytes (or less), we do the following:
+
+Input into the hash function the local 'md' (which is initialized from
+the global 'md' before any bytes are generated), the bytes that are to
+be overwritten by the random bytes, and bytes from the 'state'
+(incrementing looping index). From this digest output (which is kept
+in 'md'), the top (up to) 10 bytes are returned to the caller and the
+bottom 10 bytes are xored into the 'state'.
+
+Finally, after we have finished 'num' random bytes for the caller,
+'count' (which is incremented) and the local and global 'md' are fed
+into the hash function and the results are kept in the global 'md'.
+
+I believe the above addressed points 1 (use of SHA-1), 6 (by hashing
+into the 'state' the 'old' data from the caller that is about to be
+overwritten) and 7 (by not using the 10 bytes given to the caller to
+update the 'state', but they are used to update 'md').
+
+So of the points raised, only 2 is not addressed (but see
+L<RAND_add(3)|RAND_add(3)>).
+
+=head1 SEE ALSO
+
+L<BN_rand(3)|BN_rand(3)>, L<RAND_add(3)|RAND_add(3)>,
+L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_egd(3)|RAND_egd(3)>,
+L<RAND_bytes(3)|RAND_bytes(3)>,
+L<RAND_set_rand_method(3)|RAND_set_rand_method(3)>,
+L<RAND_cleanup(3)|RAND_cleanup(3)>
+
+=cut
diff --git a/openssl/doc/crypto/rc4.pod b/openssl/doc/crypto/rc4.pod
new file mode 100644
index 000000000..b6d3a4342
--- /dev/null
+++ b/openssl/doc/crypto/rc4.pod
@@ -0,0 +1,62 @@
+=pod
+
+=head1 NAME
+
+RC4_set_key, RC4 - RC4 encryption
+
+=head1 SYNOPSIS
+
+ #include <openssl/rc4.h>
+
+ void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data);
+
+ void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata,
+ unsigned char *outdata);
+
+=head1 DESCRIPTION
+
+This library implements the Alleged RC4 cipher, which is described for
+example in I<Applied Cryptography>. It is believed to be compatible
+with RC4[TM], a proprietary cipher of RSA Security Inc.
+
+RC4 is a stream cipher with variable key length. Typically, 128 bit
+(16 byte) keys are used for strong encryption, but shorter insecure
+key sizes have been widely used due to export restrictions.
+
+RC4 consists of a key setup phase and the actual encryption or
+decryption phase.
+
+RC4_set_key() sets up the B<RC4_KEY> B<key> using the B<len> bytes long
+key at B<data>.
+
+RC4() encrypts or decrypts the B<len> bytes of data at B<indata> using
+B<key> and places the result at B<outdata>. Repeated RC4() calls with
+the same B<key> yield a continuous key stream.
+
+Since RC4 is a stream cipher (the input is XORed with a pseudo-random
+key stream to produce the output), decryption uses the same function
+calls as encryption.
+
+Applications should use the higher level functions
+L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>
+etc. instead of calling the RC4 functions directly.
+
+=head1 RETURN VALUES
+
+RC4_set_key() and RC4() do not return values.
+
+=head1 NOTE
+
+Certain conditions have to be observed to securely use stream ciphers.
+It is not permissible to perform multiple encryptions using the same
+key stream.
+
+=head1 SEE ALSO
+
+L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<rc2(3)|rc2(3)>
+
+=head1 HISTORY
+
+RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/openssl/doc/crypto/ripemd.pod b/openssl/doc/crypto/ripemd.pod
new file mode 100644
index 000000000..264bb99ae
--- /dev/null
+++ b/openssl/doc/crypto/ripemd.pod
@@ -0,0 +1,66 @@
+=pod
+
+=head1 NAME
+
+RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final -
+RIPEMD-160 hash function
+
+=head1 SYNOPSIS
+
+ #include <openssl/ripemd.h>
+
+ unsigned char *RIPEMD160(const unsigned char *d, unsigned long n,
+ unsigned char *md);
+
+ int RIPEMD160_Init(RIPEMD160_CTX *c);
+ int RIPEMD160_Update(RIPEMD_CTX *c, const void *data,
+ unsigned long len);
+ int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c);
+
+=head1 DESCRIPTION
+
+RIPEMD-160 is a cryptographic hash function with a
+160 bit output.
+
+RIPEMD160() computes the RIPEMD-160 message digest of the B<n>
+bytes at B<d> and places it in B<md> (which must have space for
+RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest
+is placed in a static array.
+
+The following functions may be used if the message is not completely
+stored in memory:
+
+RIPEMD160_Init() initializes a B<RIPEMD160_CTX> structure.
+
+RIPEMD160_Update() can be called repeatedly with chunks of the message to
+be hashed (B<len> bytes at B<data>).
+
+RIPEMD160_Final() places the message digest in B<md>, which must have
+space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases
+the B<RIPEMD160_CTX>.
+
+Applications should use the higher level functions
+L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the
+hash functions directly.
+
+=head1 RETURN VALUES
+
+RIPEMD160() returns a pointer to the hash value.
+
+RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for
+success, 0 otherwise.
+
+=head1 CONFORMING TO
+
+ISO/IEC 10118-3 (draft) (??)
+
+=head1 SEE ALSO
+
+L<sha(3)|sha(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>
+
+=head1 HISTORY
+
+RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and
+RIPEMD160_Final() are available since SSLeay 0.9.0.
+
+=cut
diff --git a/openssl/doc/crypto/rsa.pod b/openssl/doc/crypto/rsa.pod
new file mode 100644
index 000000000..45ac53ffc
--- /dev/null
+++ b/openssl/doc/crypto/rsa.pod
@@ -0,0 +1,123 @@
+=pod
+
+=head1 NAME
+
+rsa - RSA public key cryptosystem
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+ #include <openssl/engine.h>
+
+ RSA * RSA_new(void);
+ void RSA_free(RSA *rsa);
+
+ int RSA_public_encrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+ int RSA_private_decrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+ int RSA_private_encrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa,int padding);
+ int RSA_public_decrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa,int padding);
+
+ int RSA_sign(int type, unsigned char *m, unsigned int m_len,
+ unsigned char *sigret, unsigned int *siglen, RSA *rsa);
+ int RSA_verify(int type, unsigned char *m, unsigned int m_len,
+ unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
+
+ int RSA_size(const RSA *rsa);
+
+ RSA *RSA_generate_key(int num, unsigned long e,
+ void (*callback)(int,int,void *), void *cb_arg);
+
+ int RSA_check_key(RSA *rsa);
+
+ int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);
+ void RSA_blinding_off(RSA *rsa);
+
+ void RSA_set_default_method(const RSA_METHOD *meth);
+ const RSA_METHOD *RSA_get_default_method(void);
+ int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
+ const RSA_METHOD *RSA_get_method(const RSA *rsa);
+ RSA_METHOD *RSA_PKCS1_SSLeay(void);
+ RSA_METHOD *RSA_null_method(void);
+ int RSA_flags(const RSA *rsa);
+ RSA *RSA_new_method(ENGINE *engine);
+
+ int RSA_print(BIO *bp, RSA *x, int offset);
+ int RSA_print_fp(FILE *fp, RSA *x, int offset);
+
+ int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(),
+ int (*dup_func)(), void (*free_func)());
+ int RSA_set_ex_data(RSA *r,int idx,char *arg);
+ char *RSA_get_ex_data(RSA *r, int idx);
+
+ int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m,
+ unsigned int m_len, unsigned char *sigret, unsigned int *siglen,
+ RSA *rsa);
+ int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m,
+ unsigned int m_len, unsigned char *sigbuf, unsigned int siglen,
+ RSA *rsa);
+
+=head1 DESCRIPTION
+
+These functions implement RSA public key encryption and signatures
+as defined in PKCS #1 v2.0 [RFC 2437].
+
+The B<RSA> structure consists of several BIGNUM components. It can
+contain public as well as private RSA keys:
+
+ struct
+ {
+ BIGNUM *n; // public modulus
+ BIGNUM *e; // public exponent
+ BIGNUM *d; // private exponent
+ BIGNUM *p; // secret prime factor
+ BIGNUM *q; // secret prime factor
+ BIGNUM *dmp1; // d mod (p-1)
+ BIGNUM *dmq1; // d mod (q-1)
+ BIGNUM *iqmp; // q^-1 mod p
+ // ...
+ };
+ RSA
+
+In public keys, the private exponent and the related secret values are
+B<NULL>.
+
+B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private
+keys, but the RSA operations are much faster when these values are
+available.
+
+Note that RSA keys may use non-standard B<RSA_METHOD> implementations,
+either directly or by the use of B<ENGINE> modules. In some cases (eg. an
+ENGINE providing support for hardware-embedded keys), these BIGNUM values
+will not be used by the implementation or may be used for alternative data
+storage. For this reason, applications should generally avoid using RSA
+structure elements directly and instead use API functions to query or
+modify keys.
+
+=head1 CONFORMING TO
+
+SSL, PKCS #1 v2.0
+
+=head1 PATENTS
+
+RSA was covered by a US patent which expired in September 2000.
+
+=head1 SEE ALSO
+
+L<rsa(1)|rsa(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>,
+L<rand(3)|rand(3)>, L<engine(3)|engine(3)>, L<RSA_new(3)|RSA_new(3)>,
+L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>,
+L<RSA_sign(3)|RSA_sign(3)>, L<RSA_size(3)|RSA_size(3)>,
+L<RSA_generate_key(3)|RSA_generate_key(3)>,
+L<RSA_check_key(3)|RSA_check_key(3)>,
+L<RSA_blinding_on(3)|RSA_blinding_on(3)>,
+L<RSA_set_method(3)|RSA_set_method(3)>, L<RSA_print(3)|RSA_print(3)>,
+L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
+L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>,
+L<RSA_sign_ASN1_OCTET_STRING(3)|RSA_sign_ASN1_OCTET_STRING(3)>,
+L<RSA_padding_add_PKCS1_type_1(3)|RSA_padding_add_PKCS1_type_1(3)>
+
+=cut
diff --git a/openssl/doc/crypto/sha.pod b/openssl/doc/crypto/sha.pod
new file mode 100644
index 000000000..94ab7bc72
--- /dev/null
+++ b/openssl/doc/crypto/sha.pod
@@ -0,0 +1,70 @@
+=pod
+
+=head1 NAME
+
+SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/sha.h>
+
+ unsigned char *SHA1(const unsigned char *d, unsigned long n,
+ unsigned char *md);
+
+ int SHA1_Init(SHA_CTX *c);
+ int SHA1_Update(SHA_CTX *c, const void *data,
+ unsigned long len);
+ int SHA1_Final(unsigned char *md, SHA_CTX *c);
+
+=head1 DESCRIPTION
+
+SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a
+160 bit output.
+
+SHA1() computes the SHA-1 message digest of the B<n>
+bytes at B<d> and places it in B<md> (which must have space for
+SHA_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest
+is placed in a static array.
+
+The following functions may be used if the message is not completely
+stored in memory:
+
+SHA1_Init() initializes a B<SHA_CTX> structure.
+
+SHA1_Update() can be called repeatedly with chunks of the message to
+be hashed (B<len> bytes at B<data>).
+
+SHA1_Final() places the message digest in B<md>, which must have space
+for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B<SHA_CTX>.
+
+Applications should use the higher level functions
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>
+etc. instead of calling the hash functions directly.
+
+The predecessor of SHA-1, SHA, is also implemented, but it should be
+used only when backward compatibility is required.
+
+=head1 RETURN VALUES
+
+SHA1() returns a pointer to the hash value.
+
+SHA1_Init(), SHA1_Update() and SHA1_Final() return 1 for success, 0 otherwise.
+
+=head1 CONFORMING TO
+
+SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure Hash
+Standard),
+SHA-1: US Federal Information Processing Standard FIPS PUB 180-1 (Secure Hash
+Standard),
+ANSI X9.30
+
+=head1 SEE ALSO
+
+L<ripemd(3)|ripemd(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>
+
+=head1 HISTORY
+
+SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all
+versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/openssl/doc/crypto/threads.pod b/openssl/doc/crypto/threads.pod
new file mode 100644
index 000000000..3df4ecd77
--- /dev/null
+++ b/openssl/doc/crypto/threads.pod
@@ -0,0 +1,175 @@
+=pod
+
+=head1 NAME
+
+CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks,
+CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback,
+CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid,
+CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support
+
+=head1 SYNOPSIS
+
+ #include <openssl/crypto.h>
+
+ void CRYPTO_set_locking_callback(void (*locking_function)(int mode,
+ int n, const char *file, int line));
+
+ void CRYPTO_set_id_callback(unsigned long (*id_function)(void));
+
+ int CRYPTO_num_locks(void);
+
+
+ /* struct CRYPTO_dynlock_value needs to be defined by the user */
+ struct CRYPTO_dynlock_value;
+
+ void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value *
+ (*dyn_create_function)(char *file, int line));
+ void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function)
+ (int mode, struct CRYPTO_dynlock_value *l,
+ const char *file, int line));
+ void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function)
+ (struct CRYPTO_dynlock_value *l, const char *file, int line));
+
+ int CRYPTO_get_new_dynlockid(void);
+
+ void CRYPTO_destroy_dynlockid(int i);
+
+ void CRYPTO_lock(int mode, int n, const char *file, int line);
+
+ #define CRYPTO_w_lock(type) \
+ CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
+ #define CRYPTO_w_unlock(type) \
+ CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
+ #define CRYPTO_r_lock(type) \
+ CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__)
+ #define CRYPTO_r_unlock(type) \
+ CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__)
+ #define CRYPTO_add(addr,amount,type) \
+ CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__)
+
+=head1 DESCRIPTION
+
+OpenSSL can safely be used in multi-threaded applications provided
+that at least two callback functions are set.
+
+locking_function(int mode, int n, const char *file, int line) is
+needed to perform locking on shared data structures.
+(Note that OpenSSL uses a number of global data structures that
+will be implicitly shared whenever multiple threads use OpenSSL.)
+Multi-threaded applications will crash at random if it is not set.
+
+locking_function() must be able to handle up to CRYPTO_num_locks()
+different mutex locks. It sets the B<n>-th lock if B<mode> &
+B<CRYPTO_LOCK>, and releases it otherwise.
+
+B<file> and B<line> are the file number of the function setting the
+lock. They can be useful for debugging.
+
+id_function(void) is a function that returns a thread ID, for example
+pthread_self() if it returns an integer (see NOTES below). It isn't
+needed on Windows nor on platforms where getpid() returns a different
+ID for each thread (see NOTES below).
+
+Additionally, OpenSSL supports dynamic locks, and sometimes, some parts
+of OpenSSL need it for better performance. To enable this, the following
+is required:
+
+=over 4
+
+=item *
+Three additional callback function, dyn_create_function, dyn_lock_function
+and dyn_destroy_function.
+
+=item *
+A structure defined with the data that each lock needs to handle.
+
+=back
+
+struct CRYPTO_dynlock_value has to be defined to contain whatever structure
+is needed to handle locks.
+
+dyn_create_function(const char *file, int line) is needed to create a
+lock. Multi-threaded applications might crash at random if it is not set.
+
+dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line)
+is needed to perform locking off dynamic lock numbered n. Multi-threaded
+applications might crash at random if it is not set.
+
+dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is
+needed to destroy the lock l. Multi-threaded applications might crash at
+random if it is not set.
+
+CRYPTO_get_new_dynlockid() is used to create locks. It will call
+dyn_create_function for the actual creation.
+
+CRYPTO_destroy_dynlockid() is used to destroy locks. It will call
+dyn_destroy_function for the actual destruction.
+
+CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield
+describing what should be done with the lock. n is the number of the
+lock as returned from CRYPTO_get_new_dynlockid(). mode can be combined
+from the following values. These values are pairwise exclusive, with
+undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE
+should not be used together):
+
+ CRYPTO_LOCK 0x01
+ CRYPTO_UNLOCK 0x02
+ CRYPTO_READ 0x04
+ CRYPTO_WRITE 0x08
+
+=head1 RETURN VALUES
+
+CRYPTO_num_locks() returns the required number of locks.
+
+CRYPTO_get_new_dynlockid() returns the index to the newly created lock.
+
+The other functions return no values.
+
+=head1 NOTES
+
+You can find out if OpenSSL was configured with thread support:
+
+ #define OPENSSL_THREAD_DEFINES
+ #include <openssl/opensslconf.h>
+ #if defined(OPENSSL_THREADS)
+ // thread support enabled
+ #else
+ // no thread support
+ #endif
+
+Also, dynamic locks are currently not used internally by OpenSSL, but
+may do so in the future.
+
+Defining id_function(void) has it's own issues. Generally speaking,
+pthread_self() should be used, even on platforms where getpid() gives
+different answers in each thread, since that may depend on the machine
+the program is run on, not the machine where the program is being
+compiled. For instance, Red Hat 8 Linux and earlier used
+LinuxThreads, whose getpid() returns a different value for each
+thread. Red Hat 9 Linux and later use NPTL, which is
+Posix-conformant, and has a getpid() that returns the same value for
+all threads in a process. A program compiled on Red Hat 8 and run on
+Red Hat 9 will therefore see getpid() returning the same value for
+all threads.
+
+There is still the issue of platforms where pthread_self() returns
+something other than an integer. This is a bit unusual, and this
+manual has no cookbook solution for that case.
+
+=head1 EXAMPLES
+
+B<crypto/threads/mttest.c> shows examples of the callback functions on
+Solaris, Irix and Win32.
+
+=head1 HISTORY
+
+CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are
+available in all versions of SSLeay and OpenSSL.
+CRYPTO_num_locks() was added in OpenSSL 0.9.4.
+All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev.
+
+=head1 SEE ALSO
+
+L<crypto(3)|crypto(3)>
+
+=cut
diff --git a/openssl/doc/crypto/ui.pod b/openssl/doc/crypto/ui.pod
new file mode 100644
index 000000000..6df68d604
--- /dev/null
+++ b/openssl/doc/crypto/ui.pod
@@ -0,0 +1,194 @@
+=pod
+
+=head1 NAME
+
+UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string,
+UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean,
+UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string,
+UI_add_error_string, UI_dup_error_string, UI_construct_prompt,
+UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process,
+UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method,
+UI_set_method, UI_OpenSSL, ERR_load_UI_strings - New User Interface
+
+=head1 SYNOPSIS
+
+ #include <openssl/ui.h>
+
+ typedef struct ui_st UI;
+ typedef struct ui_method_st UI_METHOD;
+
+ UI *UI_new(void);
+ UI *UI_new_method(const UI_METHOD *method);
+ void UI_free(UI *ui);
+
+ int UI_add_input_string(UI *ui, const char *prompt, int flags,
+ char *result_buf, int minsize, int maxsize);
+ int UI_dup_input_string(UI *ui, const char *prompt, int flags,
+ char *result_buf, int minsize, int maxsize);
+ int UI_add_verify_string(UI *ui, const char *prompt, int flags,
+ char *result_buf, int minsize, int maxsize, const char *test_buf);
+ int UI_dup_verify_string(UI *ui, const char *prompt, int flags,
+ char *result_buf, int minsize, int maxsize, const char *test_buf);
+ int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc,
+ const char *ok_chars, const char *cancel_chars,
+ int flags, char *result_buf);
+ int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc,
+ const char *ok_chars, const char *cancel_chars,
+ int flags, char *result_buf);
+ int UI_add_info_string(UI *ui, const char *text);
+ int UI_dup_info_string(UI *ui, const char *text);
+ int UI_add_error_string(UI *ui, const char *text);
+ int UI_dup_error_string(UI *ui, const char *text);
+
+ /* These are the possible flags. They can be or'ed together. */
+ #define UI_INPUT_FLAG_ECHO 0x01
+ #define UI_INPUT_FLAG_DEFAULT_PWD 0x02
+
+ char *UI_construct_prompt(UI *ui_method,
+ const char *object_desc, const char *object_name);
+
+ void *UI_add_user_data(UI *ui, void *user_data);
+ void *UI_get0_user_data(UI *ui);
+
+ const char *UI_get0_result(UI *ui, int i);
+
+ int UI_process(UI *ui);
+
+ int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)());
+ #define UI_CTRL_PRINT_ERRORS 1
+ #define UI_CTRL_IS_REDOABLE 2
+
+ void UI_set_default_method(const UI_METHOD *meth);
+ const UI_METHOD *UI_get_default_method(void);
+ const UI_METHOD *UI_get_method(UI *ui);
+ const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth);
+
+ UI_METHOD *UI_OpenSSL(void);
+
+=head1 DESCRIPTION
+
+UI stands for User Interface, and is general purpose set of routines to
+prompt the user for text-based information. Through user-written methods
+(see L<ui_create(3)|ui_create(3)>), prompting can be done in any way
+imaginable, be it plain text prompting, through dialog boxes or from a
+cell phone.
+
+All the functions work through a context of the type UI. This context
+contains all the information needed to prompt correctly as well as a
+reference to a UI_METHOD, which is an ordered vector of functions that
+carry out the actual prompting.
+
+The first thing to do is to create a UI with UI_new() or UI_new_method(),
+then add information to it with the UI_add or UI_dup functions. Also,
+user-defined random data can be passed down to the underlying method
+through calls to UI_add_user_data. The default UI method doesn't care
+about these data, but other methods might. Finally, use UI_process()
+to actually perform the prompting and UI_get0_result() to find the result
+to the prompt.
+
+A UI can contain more than one prompt, which are performed in the given
+sequence. Each prompt gets an index number which is returned by the
+UI_add and UI_dup functions, and has to be used to get the corresponding
+result with UI_get0_result().
+
+The functions are as follows:
+
+UI_new() creates a new UI using the default UI method. When done with
+this UI, it should be freed using UI_free().
+
+UI_new_method() creates a new UI using the given UI method. When done with
+this UI, it should be freed using UI_free().
+
+UI_OpenSSL() returns the built-in UI method (note: not the default one,
+since the default can be changed. See further on). This method is the
+most machine/OS dependent part of OpenSSL and normally generates the
+most problems when porting.
+
+UI_free() removes a UI from memory, along with all other pieces of memory
+that's connected to it, like duplicated input strings, results and others.
+
+UI_add_input_string() and UI_add_verify_string() add a prompt to the UI,
+as well as flags and a result buffer and the desired minimum and maximum
+sizes of the result. The given information is used to prompt for
+information, for example a password, and to verify a password (i.e. having
+the user enter it twice and check that the same string was entered twice).
+UI_add_verify_string() takes and extra argument that should be a pointer
+to the result buffer of the input string that it's supposed to verify, or
+verification will fail.
+
+UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered
+in a boolean way, with a single character for yes and a different character
+for no. A set of characters that can be used to cancel the prompt is given
+as well. The prompt itself is really divided in two, one part being the
+descriptive text (given through the I<prompt> argument) and one describing
+the possible answers (given through the I<action_desc> argument).
+
+UI_add_info_string() and UI_add_error_string() add strings that are shown at
+the same time as the prompt for extra information or to show an error string.
+The difference between the two is only conceptual. With the builtin method,
+there's no technical difference between them. Other methods may make a
+difference between them, however.
+
+The flags currently supported are UI_INPUT_FLAG_ECHO, which is relevant for
+UI_add_input_string() and will have the users response be echoed (when
+prompting for a password, this flag should obviously not be used, and
+UI_INPUT_FLAG_DEFAULT_PWD, which means that a default password of some
+sort will be used (completely depending on the application and the UI
+method).
+
+UI_dup_input_string(), UI_dup_verify_string(), UI_dup_input_boolean(),
+UI_dup_info_string() and UI_dup_error_string() are basically the same
+as their UI_add counterparts, except that they make their own copies
+of all strings.
+
+UI_construct_prompt() is a helper function that can be used to create
+a prompt from two pieces of information: an description and a name.
+The default constructor (if there is none provided by the method used)
+creates a string "Enter I<description> for I<name>:". With the
+description "pass phrase" and the file name "foo.key", that becomes
+"Enter pass phrase for foo.key:". Other methods may create whatever
+string and may include encodings that will be processed by the other
+method functions.
+
+UI_add_user_data() adds a piece of memory for the method to use at any
+time. The builtin UI method doesn't care about this info. Note that several
+calls to this function doesn't add data, it replaces the previous blob
+with the one given as argument.
+
+UI_get0_user_data() retrieves the data that has last been given to the
+UI with UI_add_user_data().
+
+UI_get0_result() returns a pointer to the result buffer associated with
+the information indexed by I<i>.
+
+UI_process() goes through the information given so far, does all the printing
+and prompting and returns.
+
+UI_ctrl() adds extra control for the application author. For now, it
+understands two commands: UI_CTRL_PRINT_ERRORS, which makes UI_process()
+print the OpenSSL error stack as part of processing the UI, and
+UI_CTRL_IS_REDOABLE, which returns a flag saying if the used UI can
+be used again or not.
+
+UI_set_default_method() changes the default UI method to the one given.
+
+UI_get_default_method() returns a pointer to the current default UI method.
+
+UI_get_method() returns the UI method associated with a given UI.
+
+UI_set_method() changes the UI method associated with a given UI.
+
+=head1 SEE ALSO
+
+L<ui_create(3)|ui_create(3)>, L<ui_compat(3)|ui_compat(3)>
+
+=head1 HISTORY
+
+The UI section was first introduced in OpenSSL 0.9.7.
+
+=head1 AUTHOR
+
+Richard Levitte (richard@levitte.org) for the OpenSSL project
+(http://www.openssl.org).
+
+=cut
diff --git a/openssl/doc/crypto/ui_compat.pod b/openssl/doc/crypto/ui_compat.pod
new file mode 100644
index 000000000..9ab3c69bf
--- /dev/null
+++ b/openssl/doc/crypto/ui_compat.pod
@@ -0,0 +1,55 @@
+=pod
+
+=head1 NAME
+
+des_read_password, des_read_2passwords, des_read_pw_string, des_read_pw -
+Compatibility user interface functions
+
+=head1 SYNOPSIS
+
+ int des_read_password(DES_cblock *key,const char *prompt,int verify);
+ int des_read_2passwords(DES_cblock *key1,DES_cblock *key2,
+ const char *prompt,int verify);
+
+ int des_read_pw_string(char *buf,int length,const char *prompt,int verify);
+ int des_read_pw(char *buf,char *buff,int size,const char *prompt,int verify);
+
+=head1 DESCRIPTION
+
+The DES library contained a few routines to prompt for passwords. These
+aren't necessarely dependent on DES, and have therefore become part of the
+UI compatibility library.
+
+des_read_pw() writes the string specified by I<prompt> to standard output
+turns echo off and reads an input string from the terminal. The string is
+returned in I<buf>, which must have spac for at least I<size> bytes.
+If I<verify> is set, the user is asked for the password twice and unless
+the two copies match, an error is returned. The second password is stored
+in I<buff>, which must therefore also be at least I<size> bytes. A return
+code of -1 indicates a system error, 1 failure due to use interaction, and
+0 is success. All other functions described here use des_read_pw() to do
+the work.
+
+des_read_pw_string() is a variant of des_read_pw() that provides a buffer
+for you if I<verify> is set.
+
+des_read_password() calls des_read_pw() and converts the password to a
+DES key by calling DES_string_to_key(); des_read_2password() operates in
+the same way as des_read_password() except that it generates two keys
+by using the DES_string_to_2key() function.
+
+=head1 NOTES
+
+des_read_pw_string() is available in the MIT Kerberos library as well, and
+is also available under the name EVP_read_pw_string().
+
+=head1 SEE ALSO
+
+L<ui(3)|ui(3)>, L<ui_create(3)|ui_create(3)>
+
+=head1 AUTHOR
+
+Richard Levitte (richard@levitte.org) for the OpenSSL project
+(http://www.openssl.org).
+
+=cut
diff --git a/openssl/doc/crypto/x509.pod b/openssl/doc/crypto/x509.pod
new file mode 100644
index 000000000..f9e58e0e4
--- /dev/null
+++ b/openssl/doc/crypto/x509.pod
@@ -0,0 +1,64 @@
+=pod
+
+=head1 NAME
+
+x509 - X.509 certificate handling
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+=head1 DESCRIPTION
+
+A X.509 certificate is a structured grouping of information about
+an individual, a device, or anything one can imagine. A X.509 CRL
+(certificate revocation list) is a tool to help determine if a
+certificate is still valid. The exact definition of those can be
+found in the X.509 document from ITU-T, or in RFC3280 from PKIX.
+In OpenSSL, the type X509 is used to express such a certificate, and
+the type X509_CRL is used to express a CRL.
+
+A related structure is a certificate request, defined in PKCS#10 from
+RSA Security, Inc, also reflected in RFC2896. In OpenSSL, the type
+X509_REQ is used to express such a certificate request.
+
+To handle some complex parts of a certificate, there are the types
+X509_NAME (to express a certificate name), X509_ATTRIBUTE (to express
+a certificate attributes), X509_EXTENSION (to express a certificate
+extension) and a few more.
+
+Finally, there's the supertype X509_INFO, which can contain a CRL, a
+certificate and a corresponding private key.
+
+B<X509_>I<...>, B<d2i_X509_>I<...> and B<i2d_X509_>I<...> handle X.509
+certificates, with some exceptions, shown below.
+
+B<X509_CRL_>I<...>, B<d2i_X509_CRL_>I<...> and B<i2d_X509_CRL_>I<...>
+handle X.509 CRLs.
+
+B<X509_REQ_>I<...>, B<d2i_X509_REQ_>I<...> and B<i2d_X509_REQ_>I<...>
+handle PKCS#10 certificate requests.
+
+B<X509_NAME_>I<...> handle certificate names.
+
+B<X509_ATTRIBUTE_>I<...> handle certificate attributes.
+
+B<X509_EXTENSION_>I<...> handle certificate extensions.
+
+=head1 SEE ALSO
+
+L<X509_NAME_ENTRY_get_object(3)|X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_add_entry_by_txt(3)|X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_add_entry_by_NID(3)|X509_NAME_add_entry_by_NID(3)>,
+L<X509_NAME_print_ex(3)|X509_NAME_print_ex(3)>,
+L<X509_NAME_new(3)|X509_NAME_new(3)>,
+L<d2i_X509(3)|d2i_X509(3)>,
+L<d2i_X509_ALGOR(3)|d2i_X509_ALGOR(3)>,
+L<d2i_X509_CRL(3)|d2i_X509_CRL(3)>,
+L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>,
+L<d2i_X509_REQ(3)|d2i_X509_REQ(3)>,
+L<d2i_X509_SIG(3)|d2i_X509_SIG(3)>,
+L<crypto(3)|crypto(3)>,
+L<x509v3(3)|x509v3(3)>
+
+=cut
diff --git a/openssl/doc/fingerprints.txt b/openssl/doc/fingerprints.txt
new file mode 100644
index 000000000..7d05a8559
--- /dev/null
+++ b/openssl/doc/fingerprints.txt
@@ -0,0 +1,57 @@
+ Fingerprints
+
+OpenSSL releases are signed with PGP/GnuPG keys. You can find the
+signatures in separate files in the same location you find the
+distributions themselves. The normal file name is the same as the
+distribution file, with '.asc' added. For example, the signature for
+the distribution of OpenSSL 0.9.7f, openssl-0.9.7f.tar.gz, is found in
+the file openssl-0.9.7f.tar.gz.asc.
+
+The following is the list of fingerprints for the keys that are
+currently in use (have been used since summer 2004) to sign OpenSSL
+distributions:
+
+pub 1024D/F709453B 2003-10-20
+ Key fingerprint = C4CA B749 C34F 7F4C C04F DAC9 A7AF 9E78 F709 453B
+uid Richard Levitte <richard@levitte.org>
+uid Richard Levitte <levitte@openssl.org>
+uid Richard Levitte <levitte@lp.se>
+
+pub 2048R/F295C759 1998-12-13
+ Key fingerprint = D0 5D 8C 61 6E 27 E6 60 41 EC B1 B8 D5 7E E5 97
+uid Dr S N Henson <shenson@drh-consultancy.demon.co.uk>
+
+pub 1024R/49A563D9 1997-02-24
+ Key fingerprint = 7B 79 19 FA 71 6B 87 25 0E 77 21 E5 52 D9 83 BF
+uid Mark Cox <mjc@redhat.com>
+uid Mark Cox <mark@awe.com>
+uid Mark Cox <mjc@apache.org>
+
+pub 1024R/26BB437D 1997-04-28
+ Key fingerprint = 00 C9 21 8E D1 AB 70 37 DD 67 A2 3A 0A 6F 8D A5
+uid Ralf S. Engelschall <rse@engelschall.com>
+
+pub 1024R/9C58A66D 1997-04-03
+ Key fingerprint = 13 D0 B8 9D 37 30 C3 ED AC 9C 24 7D 45 8C 17 67
+uid jaenicke@openssl.org
+uid Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>
+
+pub 1024D/2118CF83 1998-07-13
+ Key fingerprint = 7656 55DE 62E3 96FF 2587 EB6C 4F6D E156 2118 CF83
+uid Ben Laurie <ben@thebunker.net>
+uid Ben Laurie <ben@cryptix.org>
+uid Ben Laurie <ben@algroup.co.uk>
+sub 4096g/1F5143E7 1998-07-13
+
+pub 1024R/5A6A9B85 1994-03-22
+ Key fingerprint = C7 AC 7E AD 56 6A 65 EC F6 16 66 83 7E 86 68 28
+uid Bodo Moeller <2005@bmoeller.de>
+uid Bodo Moeller <2003@bmoeller.de>
+uid Bodo Moeller <2004@bmoeller.de>
+uid Bodo Moeller <bmoeller@acm.org>
+uid Bodo Moeller <bodo@openssl.org>
+uid Bodo Moeller <bm@ulf.mali.sub.org>
+uid Bodo Moeller <3moeller@informatik.uni-hamburg.de>
+uid Bodo Moeller <Bodo_Moeller@public.uni-hamburg.de>
+uid Bodo Moeller <3moeller@rzdspc5.informatik.uni-hamburg.de>
+
diff --git a/openssl/doc/openssl-shared.txt b/openssl/doc/openssl-shared.txt
new file mode 100644
index 000000000..5cf84a054
--- /dev/null
+++ b/openssl/doc/openssl-shared.txt
@@ -0,0 +1,32 @@
+The OpenSSL shared libraries are often installed in a directory like
+/usr/local/ssl/lib.
+
+If this directory is not in a standard system path for dynamic/shared
+libraries, then you will have problems linking and executing
+applications that use OpenSSL libraries UNLESS:
+
+* you link with static (archive) libraries. If you are truly
+ paranoid about security, you should use static libraries.
+* you use the GNU libtool code during linking
+ (http://www.gnu.org/software/libtool/libtool.html)
+* you use pkg-config during linking (this requires that
+ PKG_CONFIG_PATH includes the path to the OpenSSL shared
+ library directory), and make use of -R or -rpath.
+ (http://www.freedesktop.org/software/pkgconfig/)
+* you specify the system-wide link path via a command such
+ as crle(1) on Solaris systems.
+* you add the OpenSSL shared library directory to /etc/ld.so.conf
+ and run ldconfig(8) on Linux systems.
+* you define the LD_LIBRARY_PATH, LIBPATH, SHLIB_PATH (HP),
+ DYLD_LIBRARY_PATH (MacOS X) or PATH (Cygwin and DJGPP)
+ environment variable and add the OpenSSL shared library
+ directory to it.
+
+One common tool to check the dynamic dependencies of an executable
+or dynamic library is ldd(1) on most UNIX systems.
+
+See any operating system documentation and manpages about shared
+libraries for your version of UNIX. The following manpages may be
+helpful: ld(1), ld.so(1), ld.so.1(1) [Solaris], dld.sl(1) [HP],
+ldd(1), crle(1) [Solaris], pldd(1) [Solaris], ldconfig(8) [Linux],
+chatr(1) [HP].
diff --git a/openssl/doc/openssl.txt b/openssl/doc/openssl.txt
new file mode 100644
index 000000000..f8817b0a7
--- /dev/null
+++ b/openssl/doc/openssl.txt
@@ -0,0 +1,1254 @@
+
+This is some preliminary documentation for OpenSSL.
+
+Contents:
+
+ OpenSSL X509V3 extension configuration
+ X509V3 Extension code: programmers guide
+ PKCS#12 Library
+
+
+==============================================================================
+ OpenSSL X509V3 extension configuration
+==============================================================================
+
+OpenSSL X509V3 extension configuration: preliminary documentation.
+
+INTRODUCTION.
+
+For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now
+possible to add and print out common X509 V3 certificate and CRL extensions.
+
+BEGINNERS NOTE
+
+For most simple applications you don't need to know too much about extensions:
+the default openssl.cnf values will usually do sensible things.
+
+If you want to know more you can initially quickly look through the sections
+describing how the standard OpenSSL utilities display and add extensions and
+then the list of supported extensions.
+
+For more technical information about the meaning of extensions see:
+
+http://www.imc.org/ietf-pkix/
+http://home.netscape.com/eng/security/certs.html
+
+PRINTING EXTENSIONS.
+
+Extension values are automatically printed out for supported extensions.
+
+openssl x509 -in cert.pem -text
+openssl crl -in crl.pem -text
+
+will give information in the extension printout, for example:
+
+ X509v3 extensions:
+ X509v3 Basic Constraints:
+ CA:TRUE
+ X509v3 Subject Key Identifier:
+ 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15
+ X509v3 Authority Key Identifier:
+ keyid:73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15, DirName:/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/Email=email@1.address/Email=email@2.address, serial:00
+ X509v3 Key Usage:
+ Certificate Sign, CRL Sign
+ X509v3 Subject Alternative Name:
+ email:email@1.address, email:email@2.address
+
+CONFIGURATION FILES.
+
+The OpenSSL utilities 'ca' and 'req' can now have extension sections listing
+which certificate extensions to include. In each case a line:
+
+x509_extensions = extension_section
+
+indicates which section contains the extensions. In the case of 'req' the
+extension section is used when the -x509 option is present to create a
+self signed root certificate.
+
+The 'x509' utility also supports extensions when it signs a certificate.
+The -extfile option is used to set the configuration file containing the
+extensions. In this case a line with:
+
+extensions = extension_section
+
+in the nameless (default) section is used. If no such line is included then
+it uses the default section.
+
+You can also add extensions to CRLs: a line
+
+crl_extensions = crl_extension_section
+
+will include extensions when the -gencrl option is used with the 'ca' utility.
+You can add any extension to a CRL but of the supported extensions only
+issuerAltName and authorityKeyIdentifier make any real sense. Note: these are
+CRL extensions NOT CRL *entry* extensions which cannot currently be generated.
+CRL entry extensions can be displayed.
+
+NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL
+you should not include a crl_extensions line in the configuration file.
+
+As with all configuration files you can use the inbuilt environment expansion
+to allow the values to be passed in the environment. Therefore if you have
+several extension sections used for different purposes you can have a line:
+
+x509_extensions = $ENV::ENV_EXT
+
+and set the ENV_EXT environment variable before calling the relevant utility.
+
+EXTENSION SYNTAX.
+
+Extensions have the basic form:
+
+extension_name=[critical,] extension_options
+
+the use of the critical option makes the extension critical. Extreme caution
+should be made when using the critical flag. If an extension is marked
+as critical then any client that does not understand the extension should
+reject it as invalid. Some broken software will reject certificates which
+have *any* critical extensions (these violates PKIX but we have to live
+with it).
+
+There are three main types of extension: string extensions, multi-valued
+extensions, and raw 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. However it should be noted that in some cases the
+same name can appear multiple times, for example,
+
+subjectAltName=email:steve@here,email:steve@there
+
+in this case an equivalent long form is:
+
+subjectAltName=@alt_section
+
+[alt_section]
+
+email.1=steve@here
+email.2=steve@there
+
+This is because the configuration file code cannot handle the same name
+occurring twice in the same section.
+
+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.
+
+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 arbitrary 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
+
+WARNING: DER should be used with caution. It is possible to create totally
+invalid extensions unless care is taken.
+
+CURRENTLY SUPPORTED EXTENSIONS.
+
+If you aren't sure about extensions then they can be largely ignored: its only
+when you want to do things like restrict certificate usage when you need to
+worry about them.
+
+The only extension that a beginner might want to look at is Basic Constraints.
+If in addition you want to try Netscape object signing the you should also
+look at Netscape Certificate Type.
+
+Literal String extensions.
+
+In each case the 'value' of the extension is placed directly in the
+extension. Currently supported extensions in this category are: nsBaseUrl,
+nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl,
+nsSslServerName and nsComment.
+
+For example:
+
+nsComment="This is a test comment"
+
+Bit Strings.
+
+Bit string extensions just consist of a list of supported bits, currently
+two extensions are in this category: PKIX keyUsage and the Netscape specific
+nsCertType.
+
+nsCertType (netscape certificate type) takes the flags: client, server, email,
+objsign, reserved, sslCA, emailCA, objCA.
+
+keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
+keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign,
+encipherOnly, decipherOnly.
+
+For example:
+
+nsCertType=server
+
+keyUsage=digitalSignature, nonRepudiation
+
+Hints on Netscape Certificate Type.
+
+Other than Basic Constraints this is the only extension a beginner might
+want to use, if you want to try Netscape object signing, otherwise it can
+be ignored.
+
+If you want a certificate that can be used just for object signing then:
+
+nsCertType=objsign
+
+will do the job. If you want to use it as a normal end user and server
+certificate as well then
+
+nsCertType=objsign,email,server
+
+is more appropriate. You cannot use a self signed certificate for object
+signing (well Netscape signtool can but it cheats!) so you need to create
+a CA certificate and sign an end user certificate with it.
+
+Side note: If you want to conform to the Netscape specifications then you
+should really also set:
+
+nsCertType=objCA
+
+in the *CA* certificate for just an object signing CA and
+
+nsCertType=objCA,emailCA,sslCA
+
+for everything. Current Netscape software doesn't enforce this so it can
+be omitted.
+
+Basic Constraints.
+
+This is generally the only extension you need to worry about for simple
+applications. If you want your certificate to be usable as a CA certificate
+(in addition to an end user certificate) then you set this to:
+
+basicConstraints=CA:TRUE
+
+if you want to be certain the certificate cannot be used as a CA then do:
+
+basicConstraints=CA:FALSE
+
+The rest of this section describes more advanced usage.
+
+Basic constraints is a multi-valued extension that supports a CA and an
+optional pathlen option. The CA option takes the values true and false and
+pathlen takes an integer. Note if the CA option is false the pathlen option
+should be omitted.
+
+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. This all
+assumes that the software correctly interprets this extension of course.
+
+Examples:
+
+basicConstraints=CA:TRUE
+basicConstraints=critical,CA:TRUE, pathlen:0
+
+NOTE: for a CA to be considered valid it must have the CA option set to
+TRUE. An end user certificate MUST NOT have the CA value set to true.
+According to PKIX recommendations it should exclude the extension entirely,
+however some software may require CA set to FALSE for end entity certificates.
+
+Extended Key Usage.
+
+This extensions consists of a list of usages.
+
+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
+
+For example, under IE5 a CA can be used for any purpose: by including a list
+of the above usages the CA can be restricted to only authorised uses.
+
+Note: software packages may place additional interpretations on certificate
+use, in particular some usages may only work for selected CAs. Don't for example
+expect just including msSGC or nsSGC will automatically mean that a certificate
+can be used for SGC ("step up" encryption) otherwise anyone could use it.
+
+Examples:
+
+extendedKeyUsage=critical,codeSigning,1.2.3.4
+extendedKeyUsage=nsSGC,msSGC
+
+Subject Key Identifier.
+
+This is really a string extension and can take two possible values. Either
+a hex string giving details of the extension value to include or the word
+'hash' which then automatically follow PKIX guidelines in selecting and
+appropriate key identifier. The use of the hex string is strongly discouraged.
+
+Example: subjectKeyIdentifier=hash
+
+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. Normally this will only be done if the keyid option fails or
+is not included: the "always" flag will always include the value.
+
+Subject Alternative Name.
+
+The subject alternative name extension allows various literal values to be
+included in the configuration file. These include "email" (an email address)
+"URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
+registered ID: OBJECT IDENTIFIER), IP (and IP address) and otherName.
+
+Also the email option include a special 'copy' value. This will automatically
+include and email addresses contained in the certificate subject name in
+the extension.
+
+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=email:my@other.address,RID:1.2.3.4
+subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
+
+Issuer Alternative Name.
+
+The issuer alternative name option supports all the literal options of
+subject alternative name. It does *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
+
+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 '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. OCSP gives the
+location of an OCSP responder: this is used by Netscape PSM and other software.
+
+Example:
+
+authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
+authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
+
+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.
+
+If you see this extension with <UNSUPPORTED> when you attempt to print it out
+or it doesn't appear to display correctly then let me know, including the
+certificate (mail me at steve@openssl.org) .
+
+Examples:
+
+crlDistributionPoints=URI:http://www.myhost.com/myca.crl
+crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl
+
+Certificate Policies.
+
+This is a RAW extension. It attempts to display the contents of this extension:
+unfortunately this extension is often improperly encoded.
+
+The certificate policies extension will rarely be used in practice: few
+software packages interpret it correctly or at all. IE5 does partially
+support this extension: but it needs the 'ia5org' option because it will
+only correctly support a broken encoding. Of the options below only the
+policy OID, explicitText and CPS options are displayed with IE5.
+
+All the fields of this extension can be set by using the appropriate syntax.
+
+If you follow the PKIX recommendations of not including any qualifiers and just
+using only 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
+
+TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field,
+according to PKIX it should be of type DisplayText but Verisign uses an
+IA5STRING and IE5 needs this too.
+
+Display only extensions.
+
+Some extensions are only partially supported and currently are only displayed
+but cannot be set. These include private key usage period, CRL number, and
+CRL reason.
+
+==============================================================================
+ X509V3 Extension code: programmers guide
+==============================================================================
+
+The purpose of the extension code is twofold. It allows an extension to be
+created from a string or structure describing its contents and it prints out an
+extension in a human or machine readable form.
+
+1. Initialisation and cleanup.
+
+No special initialisation is needed before calling the extension functions.
+You used to have to call X509V3_add_standard_extensions(); but this is no longer
+required and this function no longer does anything.
+
+void X509V3_EXT_cleanup(void);
+
+This function should be called to cleanup the extension code if any custom
+extensions have been added. If no custom extensions have been added then this
+call does nothing. After this call all custom extension code is freed up but
+you can still use the standard extensions.
+
+2. Printing and parsing extensions.
+
+The simplest way to print out extensions is via the standard X509 printing
+routines: if you use the standard X509_print() function, the supported
+extensions will be printed out automatically.
+
+The following functions allow finer control over extension display:
+
+int X509V3_EXT_print(BIO *out, X509_EXTENSION *ext, int flag, int indent);
+int X509V3_EXT_print_fp(FILE *out, X509_EXTENSION *ext, int flag, int indent);
+
+These two functions print out an individual extension to a BIO or FILE pointer.
+Currently the flag argument is unused and should be set to 0. The 'indent'
+argument is the number of spaces to indent each line.
+
+void *X509V3_EXT_d2i(X509_EXTENSION *ext);
+
+This function parses an extension and returns its internal structure. The
+precise structure you get back depends on the extension being parsed. If the
+extension if basicConstraints you will get back a pointer to a
+BASIC_CONSTRAINTS structure. Check out the source in crypto/x509v3 for more
+details about the structures returned. The returned structure should be freed
+after use using the relevant free function, BASIC_CONSTRAINTS_free() for
+example.
+
+void * X509_get_ext_d2i(X509 *x, int nid, int *crit, int *idx);
+void * X509_CRL_get_ext_d2i(X509_CRL *x, int nid, int *crit, int *idx);
+void * X509_REVOKED_get_ext_d2i(X509_REVOKED *x, int nid, int *crit, int *idx);
+void * X509V3_get_d2i(STACK_OF(X509_EXTENSION) *x, int nid, int *crit, int *idx);
+
+These functions combine the operations of searching for extensions and
+parsing them. They search a certificate, a CRL a CRL entry or a stack
+of extensions respectively for extension whose NID is 'nid' and return
+the parsed result of NULL if an error occurred. For example:
+
+BASIC_CONSTRAINTS *bs;
+bs = X509_get_ext_d2i(cert, NID_basic_constraints, NULL, NULL);
+
+This will search for the basicConstraints extension and either return
+it value or NULL. NULL can mean either the extension was not found, it
+occurred more than once or it could not be parsed.
+
+If 'idx' is NULL then an extension is only parsed if it occurs precisely
+once. This is standard behaviour because extensions normally cannot occur
+more than once. If however more than one extension of the same type can
+occur it can be used to parse successive extensions for example:
+
+int i;
+void *ext;
+
+i = -1;
+for(;;) {
+ ext = X509_get_ext_d2i(x, nid, crit, &idx);
+ if(ext == NULL) break;
+ /* Do something with ext */
+}
+
+If 'crit' is not NULL and the extension was found then the int it points to
+is set to 1 for critical extensions and 0 for non critical. Therefore if the
+function returns NULL but 'crit' is set to 0 or 1 then the extension was
+found but it could not be parsed.
+
+The int pointed to by crit will be set to -1 if the extension was not found
+and -2 if the extension occurred more than once (this will only happen if
+idx is NULL). In both cases the function will return NULL.
+
+3. Generating extensions.
+
+An extension will typically be generated from a configuration file, or some
+other kind of configuration database.
+
+int X509V3_EXT_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section,
+ X509 *cert);
+int X509V3_EXT_CRL_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section,
+ X509_CRL *crl);
+
+These functions add all the extensions in the given section to the given
+certificate or CRL. They will normally be called just before the certificate
+or CRL is due to be signed. Both return 0 on error on non zero for success.
+
+In each case 'conf' is the LHASH pointer of the configuration file to use
+and 'section' is the section containing the extension details.
+
+See the 'context functions' section for a description of the ctx parameter.
+
+
+X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *name,
+ char *value);
+
+This function returns an extension based on a name and value pair, if the
+pair will not need to access other sections in a config file (or there is no
+config file) then the 'conf' parameter can be set to NULL.
+
+X509_EXTENSION *X509V3_EXT_conf_nid(char *conf, X509V3_CTX *ctx, int nid,
+ char *value);
+
+This function creates an extension in the same way as X509V3_EXT_conf() but
+takes the NID of the extension rather than its name.
+
+For example to produce basicConstraints with the CA flag and a path length of
+10:
+
+x = X509V3_EXT_conf_nid(NULL, NULL, NID_basic_constraints,"CA:TRUE,pathlen:10");
+
+
+X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc);
+
+This function sets up an extension from its internal structure. The ext_nid
+parameter is the NID of the extension and 'crit' is the critical flag.
+
+4. Context functions.
+
+The following functions set and manipulate an extension context structure.
+The purpose of the extension context is to allow the extension code to
+access various structures relating to the "environment" of the certificate:
+for example the issuers certificate or the certificate request.
+
+void X509V3_set_ctx(X509V3_CTX *ctx, X509 *issuer, X509 *subject,
+ X509_REQ *req, X509_CRL *crl, int flags);
+
+This function sets up an X509V3_CTX structure with details of the certificate
+environment: specifically the issuers certificate, the subject certificate,
+the certificate request and the CRL: if these are not relevant or not
+available then they can be set to NULL. The 'flags' parameter should be set
+to zero.
+
+X509V3_set_ctx_test(ctx)
+
+This macro is used to set the 'ctx' structure to a 'test' value: this is to
+allow the syntax of an extension (or configuration file) to be tested.
+
+X509V3_set_ctx_nodb(ctx)
+
+This macro is used when no configuration database is present.
+
+void X509V3_set_conf_lhash(X509V3_CTX *ctx, LHASH *lhash);
+
+This function is used to set the configuration database when it is an LHASH
+structure: typically a configuration file.
+
+The following functions are used to access a configuration database: they
+should only be used in RAW extensions.
+
+char * X509V3_get_string(X509V3_CTX *ctx, char *name, char *section);
+
+This function returns the value of the parameter "name" in "section", or NULL
+if there has been an error.
+
+void X509V3_string_free(X509V3_CTX *ctx, char *str);
+
+This function frees up the string returned by the above function.
+
+STACK_OF(CONF_VALUE) * X509V3_get_section(X509V3_CTX *ctx, char *section);
+
+This function returns a whole section as a STACK_OF(CONF_VALUE) .
+
+void X509V3_section_free( X509V3_CTX *ctx, STACK_OF(CONF_VALUE) *section);
+
+This function frees up the STACK returned by the above function.
+
+Note: it is possible to use the extension code with a custom configuration
+database. To do this the "db_meth" element of the X509V3_CTX structure should
+be set to an X509V3_CTX_METHOD structure. This structure contains the following
+function pointers:
+
+char * (*get_string)(void *db, char *section, char *value);
+STACK_OF(CONF_VALUE) * (*get_section)(void *db, char *section);
+void (*free_string)(void *db, char * string);
+void (*free_section)(void *db, STACK_OF(CONF_VALUE) *section);
+
+these will be called and passed the 'db' element in the X509V3_CTX structure
+to access the database. If a given function is not implemented or not required
+it can be set to NULL.
+
+5. String helper functions.
+
+There are several "i2s" and "s2i" functions that convert structures to and
+from ASCII strings. In all the "i2s" cases the returned string should be
+freed using Free() after use. Since some of these are part of other extension
+code they may take a 'method' parameter. Unless otherwise stated it can be
+safely set to NULL.
+
+char *i2s_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, ASN1_OCTET_STRING *oct);
+
+This returns a hex string from an ASN1_OCTET_STRING.
+
+char * i2s_ASN1_INTEGER(X509V3_EXT_METHOD *meth, ASN1_INTEGER *aint);
+char * i2s_ASN1_ENUMERATED(X509V3_EXT_METHOD *meth, ASN1_ENUMERATED *aint);
+
+These return a string decimal representations of an ASN1_INTEGER and an
+ASN1_ENUMERATED type, respectively.
+
+ASN1_OCTET_STRING *s2i_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method,
+ X509V3_CTX *ctx, char *str);
+
+This converts an ASCII hex string to an ASN1_OCTET_STRING.
+
+ASN1_INTEGER * s2i_ASN1_INTEGER(X509V3_EXT_METHOD *meth, char *value);
+
+This converts a decimal ASCII string into an ASN1_INTEGER.
+
+6. Multi valued extension helper functions.
+
+The following functions can be used to manipulate STACKs of CONF_VALUE
+structures, as used by multi valued extensions.
+
+int X509V3_get_value_bool(CONF_VALUE *value, int *asn1_bool);
+
+This function expects a boolean value in 'value' and sets 'asn1_bool' to
+it. That is it sets it to 0 for FALSE or 0xff for TRUE. The following
+strings are acceptable: "TRUE", "true", "Y", "y", "YES", "yes", "FALSE"
+"false", "N", "n", "NO" or "no".
+
+int X509V3_get_value_int(CONF_VALUE *value, ASN1_INTEGER **aint);
+
+This accepts a decimal integer of arbitrary length and sets an ASN1_INTEGER.
+
+int X509V3_add_value(const char *name, const char *value,
+ STACK_OF(CONF_VALUE) **extlist);
+
+This simply adds a string name and value pair.
+
+int X509V3_add_value_uchar(const char *name, const unsigned char *value,
+ STACK_OF(CONF_VALUE) **extlist);
+
+The same as above but for an unsigned character value.
+
+int X509V3_add_value_bool(const char *name, int asn1_bool,
+ STACK_OF(CONF_VALUE) **extlist);
+
+This adds either "TRUE" or "FALSE" depending on the value of 'asn1_bool'
+
+int X509V3_add_value_bool_nf(char *name, int asn1_bool,
+ STACK_OF(CONF_VALUE) **extlist);
+
+This is the same as above except it adds nothing if asn1_bool is FALSE.
+
+int X509V3_add_value_int(const char *name, ASN1_INTEGER *aint,
+ STACK_OF(CONF_VALUE) **extlist);
+
+This function adds the value of the ASN1_INTEGER in decimal form.
+
+7. Other helper functions.
+
+<to be added>
+
+ADDING CUSTOM EXTENSIONS.
+
+Currently there are three types of supported extensions.
+
+String extensions are simple strings where the value is placed directly in the
+extensions, and the string returned is printed out.
+
+Multi value extensions are passed a STACK_OF(CONF_VALUE) name and value pairs
+or return a STACK_OF(CONF_VALUE).
+
+Raw extensions are just passed a BIO or a value and it is the extensions
+responsibility to handle all the necessary printing.
+
+There are two ways to add an extension. One is simply as an alias to an already
+existing extension. An alias is an extension that is identical in ASN1 structure
+to an existing extension but has a different OBJECT IDENTIFIER. This can be
+done by calling:
+
+int X509V3_EXT_add_alias(int nid_to, int nid_from);
+
+'nid_to' is the new extension NID and 'nid_from' is the already existing
+extension NID.
+
+Alternatively an extension can be written from scratch. This involves writing
+the ASN1 code to encode and decode the extension and functions to print out and
+generate the extension from strings. The relevant functions are then placed in
+a X509V3_EXT_METHOD structure and int X509V3_EXT_add(X509V3_EXT_METHOD *ext);
+called.
+
+The X509V3_EXT_METHOD structure is described below.
+
+struct {
+int ext_nid;
+int ext_flags;
+X509V3_EXT_NEW ext_new;
+X509V3_EXT_FREE ext_free;
+X509V3_EXT_D2I d2i;
+X509V3_EXT_I2D i2d;
+X509V3_EXT_I2S i2s;
+X509V3_EXT_S2I s2i;
+X509V3_EXT_I2V i2v;
+X509V3_EXT_V2I v2i;
+X509V3_EXT_R2I r2i;
+X509V3_EXT_I2R i2r;
+
+void *usr_data;
+};
+
+The elements have the following meanings.
+
+ext_nid is the NID of the object identifier of the extension.
+
+ext_flags is set of flags. Currently the only external flag is
+ X509V3_EXT_MULTILINE which means a multi valued extensions
+ should be printed on separate lines.
+
+usr_data is an extension specific pointer to any relevant data. This
+ allows extensions to share identical code but have different
+ uses. An example of this is the bit string extension which uses
+ usr_data to contain a list of the bit names.
+
+All the remaining elements are function pointers.
+
+ext_new is a pointer to a function that allocates memory for the
+ extension ASN1 structure: for example ASN1_OBJECT_new().
+
+ext_free is a pointer to a function that free up memory of the extension
+ ASN1 structure: for example ASN1_OBJECT_free().
+
+d2i is the standard ASN1 function that converts a DER buffer into
+ the internal ASN1 structure: for example d2i_ASN1_IA5STRING().
+
+i2d is the standard ASN1 function that converts the internal
+ structure into the DER representation: for example
+ i2d_ASN1_IA5STRING().
+
+The remaining functions are depend on the type of extension. One i2X and
+one X2i should be set and the rest set to NULL. The types set do not need
+to match up, for example the extension could be set using the multi valued
+v2i function and printed out using the raw i2r.
+
+All functions have the X509V3_EXT_METHOD passed to them in the 'method'
+parameter and an X509V3_CTX structure. Extension code can then access the
+parent structure via the 'method' parameter to for example make use of the value
+of usr_data. If the code needs to use detail relating to the request it can
+use the 'ctx' parameter.
+
+A note should be given here about the 'flags' member of the 'ctx' parameter.
+If it has the value CTX_TEST then the configuration syntax is being checked
+and no actual certificate or CRL exists. Therefore any attempt in the config
+file to access such information should silently succeed. If the syntax is OK
+then it should simply return a (possibly bogus) extension, otherwise it
+should return NULL.
+
+char *i2s(struct v3_ext_method *method, void *ext);
+
+This function takes the internal structure in the ext parameter and returns
+a Malloc'ed string representing its value.
+
+void * s2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str);
+
+This function takes the string representation in the ext parameter and returns
+an allocated internal structure: ext_free() will be used on this internal
+structure after use.
+
+i2v and v2i handle a STACK_OF(CONF_VALUE):
+
+typedef struct
+{
+ char *section;
+ char *name;
+ char *value;
+} CONF_VALUE;
+
+Only the name and value members are currently used.
+
+STACK_OF(CONF_VALUE) * i2v(struct v3_ext_method *method, void *ext);
+
+This function is passed the internal structure in the ext parameter and
+returns a STACK of CONF_VALUE structures. The values of name, value,
+section and the structure itself will be freed up with Free after use.
+Several helper functions are available to add values to this STACK.
+
+void * v2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx,
+ STACK_OF(CONF_VALUE) *values);
+
+This function takes a STACK_OF(CONF_VALUE) structures and should set the
+values of the external structure. This typically uses the name element to
+determine which structure element to set and the value element to determine
+what to set it to. Several helper functions are available for this
+purpose (see above).
+
+int i2r(struct v3_ext_method *method, void *ext, BIO *out, int indent);
+
+This function is passed the internal extension structure in the ext parameter
+and sends out a human readable version of the extension to out. The 'indent'
+parameter should be noted to determine the necessary amount of indentation
+needed on the output.
+
+void * r2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str);
+
+This is just passed the string representation of the extension. It is intended
+to be used for more elaborate extensions where the standard single and multi
+valued options are insufficient. They can use the 'ctx' parameter to parse the
+configuration database themselves. See the context functions section for details
+of how to do this.
+
+Note: although this type takes the same parameters as the "r2s" function there
+is a subtle difference. Whereas an "r2i" function can access a configuration
+database an "s2i" function MUST NOT. This is so the internal code can safely
+assume that an "s2i" function will work without a configuration database.
+
+==============================================================================
+ PKCS#12 Library
+==============================================================================
+
+This section describes the internal PKCS#12 support. There are very few
+differences between the old external library and the new internal code at
+present. This may well change because the external library will not be updated
+much in future.
+
+This version now includes a couple of high level PKCS#12 functions which
+generally "do the right thing" and should make it much easier to handle PKCS#12
+structures.
+
+HIGH LEVEL FUNCTIONS.
+
+For most applications you only need concern yourself with the high level
+functions. They can parse and generate simple PKCS#12 files as produced by
+Netscape and MSIE or indeed any compliant PKCS#12 file containing a single
+private key and certificate pair.
+
+1. Initialisation and cleanup.
+
+No special initialisation is needed for the internal PKCS#12 library: the
+standard SSLeay_add_all_algorithms() is sufficient. If you do not wish to
+add all algorithms (you should at least add SHA1 though) then you can manually
+initialise the PKCS#12 library with:
+
+PKCS12_PBE_add();
+
+The memory allocated by the PKCS#12 library is freed up when EVP_cleanup() is
+called or it can be directly freed with:
+
+EVP_PBE_cleanup();
+
+after this call (or EVP_cleanup() ) no more PKCS#12 library functions should
+be called.
+
+2. I/O functions.
+
+i2d_PKCS12_bio(bp, p12)
+
+This writes out a PKCS12 structure to a BIO.
+
+i2d_PKCS12_fp(fp, p12)
+
+This is the same but for a FILE pointer.
+
+d2i_PKCS12_bio(bp, p12)
+
+This reads in a PKCS12 structure from a BIO.
+
+d2i_PKCS12_fp(fp, p12)
+
+This is the same but for a FILE pointer.
+
+3. High level functions.
+
+3.1 Parsing with PKCS12_parse().
+
+int PKCS12_parse(PKCS12 *p12, char *pass, EVP_PKEY **pkey, X509 **cert,
+ STACK **ca);
+
+This function takes a PKCS12 structure and a password (ASCII, null terminated)
+and returns the private key, the corresponding certificate and any CA
+certificates. If any of these is not required it can be passed as a NULL.
+The 'ca' parameter should be either NULL, a pointer to NULL or a valid STACK
+structure. Typically to read in a PKCS#12 file you might do:
+
+p12 = d2i_PKCS12_fp(fp, NULL);
+PKCS12_parse(p12, password, &pkey, &cert, NULL); /* CAs not wanted */
+PKCS12_free(p12);
+
+3.2 PKCS#12 creation with PKCS12_create().
+
+PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert,
+ STACK *ca, int nid_key, int nid_cert, int iter,
+ int mac_iter, int keytype);
+
+This function will create a PKCS12 structure from a given password, name,
+private key, certificate and optional STACK of CA certificates. The remaining
+5 parameters can be set to 0 and sensible defaults will be used.
+
+The parameters nid_key and nid_cert are the key and certificate encryption
+algorithms, iter is the encryption iteration count, mac_iter is the MAC
+iteration count and keytype is the type of private key. If you really want
+to know what these last 5 parameters do then read the low level section.
+
+Typically to create a PKCS#12 file the following could be used:
+
+p12 = PKCS12_create(pass, "My Certificate", pkey, cert, NULL, 0,0,0,0,0);
+i2d_PKCS12_fp(fp, p12);
+PKCS12_free(p12);
+
+3.3 Changing a PKCS#12 structure password.
+
+int PKCS12_newpass(PKCS12 *p12, char *oldpass, char *newpass);
+
+This changes the password of an already existing PKCS#12 structure. oldpass
+is the old password and newpass is the new one. An error occurs if the old
+password is incorrect.
+
+LOW LEVEL FUNCTIONS.
+
+In some cases the high level functions do not provide the necessary
+functionality. For example if you want to generate or parse more complex
+PKCS#12 files. The sample pkcs12 application uses the low level functions
+to display details about the internal structure of a PKCS#12 file.
+
+Introduction.
+
+This is a brief description of how a PKCS#12 file is represented internally:
+some knowledge of PKCS#12 is assumed.
+
+A PKCS#12 object contains several levels.
+
+At the lowest level is a PKCS12_SAFEBAG. This can contain a certificate, a
+CRL, a private key, encrypted or unencrypted, a set of safebags (so the
+structure can be nested) or other secrets (not documented at present).
+A safebag can optionally have attributes, currently these are: a unicode
+friendlyName (a Unicode string) or a localKeyID (a string of bytes).
+
+At the next level is an authSafe which is a set of safebags collected into
+a PKCS#7 ContentInfo. This can be just plain data, or encrypted itself.
+
+At the top level is the PKCS12 structure itself which contains a set of
+authSafes in an embedded PKCS#7 Contentinfo of type data. In addition it
+contains a MAC which is a kind of password protected digest to preserve
+integrity (so any unencrypted stuff below can't be tampered with).
+
+The reason for these levels is so various objects can be encrypted in various
+ways. For example you might want to encrypt a set of private keys with
+triple-DES and then include the related certificates either unencrypted or
+with lower encryption. Yes it's the dreaded crypto laws at work again which
+allow strong encryption on private keys and only weak encryption on other
+stuff.
+
+To build one of these things you turn all certificates and keys into safebags
+(with optional attributes). You collect the safebags into (one or more) STACKS
+and convert these into authsafes (encrypted or unencrypted). The authsafes
+are collected into a STACK and added to a PKCS12 structure. Finally a MAC
+inserted.
+
+Pulling one apart is basically the reverse process. The MAC is verified against
+the given password. The authsafes are extracted and each authsafe split into
+a set of safebags (possibly involving decryption). Finally the safebags are
+decomposed into the original keys and certificates and the attributes used to
+match up private key and certificate pairs.
+
+Anyway here are the functions that do the dirty work.
+
+1. Construction functions.
+
+1.1 Safebag functions.
+
+M_PKCS12_x5092certbag(x509)
+
+This macro takes an X509 structure and returns a certificate bag. The
+X509 structure can be freed up after calling this function.
+
+M_PKCS12_x509crl2certbag(crl)
+
+As above but for a CRL.
+
+PKCS8_PRIV_KEY_INFO *PKEY2PKCS8(EVP_PKEY *pkey)
+
+Take a private key and convert it into a PKCS#8 PrivateKeyInfo structure.
+Works for both RSA and DSA private keys. NB since the PKCS#8 PrivateKeyInfo
+structure contains a private key data in plain text form it should be free'd
+up as soon as it has been encrypted for security reasons (freeing up the
+structure zeros out the sensitive data). This can be done with
+PKCS8_PRIV_KEY_INFO_free().
+
+PKCS8_add_keyusage(PKCS8_PRIV_KEY_INFO *p8, int usage)
+
+This sets the key type when a key is imported into MSIE or Outlook 98. Two
+values are currently supported: KEY_EX and KEY_SIG. KEY_EX is an exchange type
+key that can also be used for signing but its size is limited in the export
+versions of MS software to 512 bits, it is also the default. KEY_SIG is a
+signing only key but the keysize is unlimited (well 16K is supposed to work).
+If you are using the domestic version of MSIE then you can ignore this because
+KEY_EX is not limited and can be used for both.
+
+PKCS12_SAFEBAG *PKCS12_MAKE_KEYBAG(PKCS8_PRIV_KEY_INFO *p8)
+
+Convert a PKCS8 private key structure into a keybag. This routine embeds the
+p8 structure in the keybag so p8 should not be freed up or used after it is
+called. The p8 structure will be freed up when the safebag is freed.
+
+PKCS12_SAFEBAG *PKCS12_MAKE_SHKEYBAG(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8)
+
+Convert a PKCS#8 structure into a shrouded key bag (encrypted). p8 is not
+embedded and can be freed up after use.
+
+int PKCS12_add_localkeyid(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen)
+int PKCS12_add_friendlyname(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen)
+
+Add a local key id or a friendlyname to a safebag.
+
+1.2 Authsafe functions.
+
+PKCS7 *PKCS12_pack_p7data(STACK *sk)
+Take a stack of safebags and convert them into an unencrypted authsafe. The
+stack of safebags can be freed up after calling this function.
+
+PKCS7 *PKCS12_pack_p7encdata(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, STACK *bags);
+
+As above but encrypted.
+
+1.3 PKCS12 functions.
+
+PKCS12 *PKCS12_init(int mode)
+
+Initialise a PKCS12 structure (currently mode should be NID_pkcs7_data).
+
+M_PKCS12_pack_authsafes(p12, safes)
+
+This macro takes a STACK of authsafes and adds them to a PKCS#12 structure.
+
+int PKCS12_set_mac(PKCS12 *p12, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, EVP_MD *md_type);
+
+Add a MAC to a PKCS12 structure. If EVP_MD is NULL use SHA-1, the spec suggests
+that SHA-1 should be used.
+
+2. Extraction Functions.
+
+2.1 Safebags.
+
+M_PKCS12_bag_type(bag)
+
+Return the type of "bag". Returns one of the following
+
+NID_keyBag
+NID_pkcs8ShroudedKeyBag 7
+NID_certBag 8
+NID_crlBag 9
+NID_secretBag 10
+NID_safeContentsBag 11
+
+M_PKCS12_cert_bag_type(bag)
+
+Returns type of certificate bag, following are understood.
+
+NID_x509Certificate 14
+NID_sdsiCertificate 15
+
+M_PKCS12_crl_bag_type(bag)
+
+Returns crl bag type, currently only NID_crlBag is recognised.
+
+M_PKCS12_certbag2x509(bag)
+
+This macro extracts an X509 certificate from a certificate bag.
+
+M_PKCS12_certbag2x509crl(bag)
+
+As above but for a CRL.
+
+EVP_PKEY * PKCS82PKEY(PKCS8_PRIV_KEY_INFO *p8)
+
+Extract a private key from a PKCS8 private key info structure.
+
+M_PKCS12_decrypt_skey(bag, pass, passlen)
+
+Decrypt a shrouded key bag and return a PKCS8 private key info structure.
+Works with both RSA and DSA keys
+
+char *PKCS12_get_friendlyname(bag)
+
+Returns the friendlyName of a bag if present or NULL if none. The returned
+string is a null terminated ASCII string allocated with Malloc(). It should
+thus be freed up with Free() after use.
+
+2.2 AuthSafe functions.
+
+M_PKCS12_unpack_p7data(p7)
+
+Extract a STACK of safe bags from a PKCS#7 data ContentInfo.
+
+#define M_PKCS12_unpack_p7encdata(p7, pass, passlen)
+
+As above but for an encrypted content info.
+
+2.3 PKCS12 functions.
+
+M_PKCS12_unpack_authsafes(p12)
+
+Extract a STACK of authsafes from a PKCS12 structure.
+
+M_PKCS12_mac_present(p12)
+
+Check to see if a MAC is present.
+
+int PKCS12_verify_mac(PKCS12 *p12, unsigned char *pass, int passlen)
+
+Verify a MAC on a PKCS12 structure. Returns an error if MAC not present.
+
+
+Notes.
+
+1. All the function return 0 or NULL on error.
+2. Encryption based functions take a common set of parameters. These are
+described below.
+
+pass, passlen
+ASCII password and length. The password on the MAC is called the "integrity
+password" the encryption password is called the "privacy password" in the
+PKCS#12 documentation. The passwords do not have to be the same. If -1 is
+passed for the length it is worked out by the function itself (currently
+this is sometimes done whatever is passed as the length but that may change).
+
+salt, saltlen
+A 'salt' if salt is NULL a random salt is used. If saltlen is also zero a
+default length is used.
+
+iter
+Iteration count. This is a measure of how many times an internal function is
+called to encrypt the data. The larger this value is the longer it takes, it
+makes dictionary attacks on passwords harder. NOTE: Some implementations do
+not support an iteration count on the MAC. If the password for the MAC and
+encryption is the same then there is no point in having a high iteration
+count for encryption if the MAC has no count. The MAC could be attacked
+and the password used for the main decryption.
+
+pbe_nid
+This is the NID of the password based encryption method used. The following are
+supported.
+NID_pbe_WithSHA1And128BitRC4
+NID_pbe_WithSHA1And40BitRC4
+NID_pbe_WithSHA1And3_Key_TripleDES_CBC
+NID_pbe_WithSHA1And2_Key_TripleDES_CBC
+NID_pbe_WithSHA1And128BitRC2_CBC
+NID_pbe_WithSHA1And40BitRC2_CBC
+
+Which you use depends on the implementation you are exporting to. "Export
+grade" (i.e. cryptographically challenged) products cannot support all
+algorithms. Typically you may be able to use any encryption on shrouded key
+bags but they must then be placed in an unencrypted authsafe. Other authsafes
+may only support 40bit encryption. Of course if you are using SSLeay
+throughout you can strongly encrypt everything and have high iteration counts
+on everything.
+
+3. For decryption routines only the password and length are needed.
+
+4. Unlike the external version the nid's of objects are the values of the
+constants: that is NID_certBag is the real nid, therefore there is no
+PKCS12_obj_offset() function. Note the object constants are not the same as
+those of the external version. If you use these constants then you will need
+to recompile your code.
+
+5. With the exception of PKCS12_MAKE_KEYBAG(), after calling any function or
+macro of the form PKCS12_MAKE_SOMETHING(other) the "other" structure can be
+reused or freed up safely.
+
diff --git a/openssl/doc/openssl_button.gif b/openssl/doc/openssl_button.gif
new file mode 100644
index 000000000..3d3c90c9f
--- /dev/null
+++ b/openssl/doc/openssl_button.gif
Binary files differ
diff --git a/openssl/doc/openssl_button.html b/openssl/doc/openssl_button.html
new file mode 100644
index 000000000..44c91bd3d
--- /dev/null
+++ b/openssl/doc/openssl_button.html
@@ -0,0 +1,7 @@
+
+<!-- the `Includes OpenSSL Cryptogaphy Software' button -->
+<!-- freely usable by any application linked against OpenSSL -->
+<a href="http://www.openssl.org/">
+<img src="openssl_button.gif"
+ width=102 height=47 border=0></a>
+
diff --git a/openssl/doc/ssl/SSL_CIPHER_get_name.pod b/openssl/doc/ssl/SSL_CIPHER_get_name.pod
new file mode 100644
index 000000000..f62a869a9
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CIPHER_get_name.pod
@@ -0,0 +1,112 @@
+=pod
+
+=head1 NAME
+
+SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher);
+ int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
+ char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
+ char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int size);
+
+=head1 DESCRIPTION
+
+SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the
+argument is the NULL pointer, a pointer to the constant value "NONE" is
+returned.
+
+SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. If
+B<alg_bits> is not NULL, it contains the number of bits processed by the
+chosen algorithm. If B<cipher> is NULL, 0 is returned.
+
+SSL_CIPHER_get_version() returns the protocol version for B<cipher>, currently
+"SSLv2", "SSLv3", or "TLSv1". If B<cipher> is NULL, "(NONE)" is returned.
+
+SSL_CIPHER_description() returns a textual description of the cipher used
+into the buffer B<buf> of length B<len> provided. B<len> must be at least
+128 bytes, otherwise a pointer to the string "Buffer too small" is
+returned. If B<buf> is NULL, a buffer of 128 bytes is allocated using
+OPENSSL_malloc(). If the allocation fails, a pointer to the string
+"OPENSSL_malloc Error" is returned.
+
+=head1 NOTES
+
+The number of bits processed can be different from the secret bits. An
+export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm
+does use the full 128 bits (which would be returned for B<alg_bits>), of
+which however 88bits are fixed. The search space is hence only 40 bits.
+
+The string returned by SSL_CIPHER_description() in case of success consists
+of cleartext information separated by one or more blanks in the following
+sequence:
+
+=over 4
+
+=item <ciphername>
+
+Textual representation of the cipher name.
+
+=item <protocol version>
+
+Protocol version: B<SSLv2>, B<SSLv3>. The TLSv1 ciphers are flagged with SSLv3.
+
+=item Kx=<key exchange>
+
+Key exchange method: B<RSA> (for export ciphers as B<RSA(512)> or
+B<RSA(1024)>), B<DH> (for export ciphers as B<DH(512)> or B<DH(1024)>),
+B<DH/RSA>, B<DH/DSS>, B<Fortezza>.
+
+=item Au=<authentication>
+
+Authentication method: B<RSA>, B<DSS>, B<DH>, B<None>. None is the
+representation of anonymous ciphers.
+
+=item Enc=<symmetric encryption method>
+
+Encryption method with number of secret bits: B<DES(40)>, B<DES(56)>,
+B<3DES(168)>, B<RC4(40)>, B<RC4(56)>, B<RC4(64)>, B<RC4(128)>,
+B<RC2(40)>, B<RC2(56)>, B<RC2(128)>, B<IDEA(128)>, B<Fortezza>, B<None>.
+
+=item Mac=<message authentication code>
+
+Message digest: B<MD5>, B<SHA1>.
+
+=item <export flag>
+
+If the cipher is flagged exportable with respect to old US crypto
+regulations, the word "B<export>" is printed.
+
+=back
+
+=head1 EXAMPLES
+
+Some examples for the output of SSL_CIPHER_description():
+
+ EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
+ EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1
+ RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5
+ EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
+
+=head1 BUGS
+
+If SSL_CIPHER_description() is called with B<cipher> being NULL, the
+library crashes.
+
+If SSL_CIPHER_description() cannot handle a built-in cipher, the according
+description of the cipher property is B<unknown>. This case should not
+occur.
+
+=head1 RETURN VALUES
+
+See DESCRIPTION
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>,
+L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<ciphers(1)|ciphers(1)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_COMP_add_compression_method.pod b/openssl/doc/ssl/SSL_COMP_add_compression_method.pod
new file mode 100644
index 000000000..42fa66b19
--- /dev/null
+++ b/openssl/doc/ssl/SSL_COMP_add_compression_method.pod
@@ -0,0 +1,70 @@
+=pod
+
+=head1 NAME
+
+SSL_COMP_add_compression_method - handle SSL/TLS integrated compression methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm);
+
+=head1 DESCRIPTION
+
+SSL_COMP_add_compression_method() adds the compression method B<cm> with
+the identifier B<id> to the list of available compression methods. This
+list is globally maintained for all SSL operations within this application.
+It cannot be set for specific SSL_CTX or SSL objects.
+
+=head1 NOTES
+
+The TLS standard (or SSLv3) allows the integration of compression methods
+into the communication. The TLS RFC does however not specify compression
+methods or their corresponding identifiers, so there is currently no compatible
+way to integrate compression with unknown peers. It is therefore currently not
+recommended to integrate compression into applications. Applications for
+non-public use may agree on certain compression methods. Using different
+compression methods with the same identifier will lead to connection failure.
+
+An OpenSSL client speaking a protocol that allows compression (SSLv3, TLSv1)
+will unconditionally send the list of all compression methods enabled with
+SSL_COMP_add_compression_method() to the server during the handshake.
+Unlike the mechanisms to set a cipher list, there is no method available to
+restrict the list of compression method on a per connection basis.
+
+An OpenSSL server will match the identifiers listed by a client against
+its own compression methods and will unconditionally activate compression
+when a matching identifier is found. There is no way to restrict the list
+of compression methods supported on a per connection basis.
+
+The OpenSSL library has the compression methods B<COMP_rle()> and (when
+especially enabled during compilation) B<COMP_zlib()> available.
+
+=head1 WARNINGS
+
+Once the identities of the compression methods for the TLS protocol have
+been standardized, the compression API will most likely be changed. Using
+it in the current state is not recommended.
+
+=head1 RETURN VALUES
+
+SSL_COMP_add_compression_method() may return the following values:
+
+=over 4
+
+=item 0
+
+The operation succeeded.
+
+=item 1
+
+The operation failed. Check the error queue to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
new file mode 100644
index 000000000..ee28f5ccc
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
@@ -0,0 +1,39 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_add_extra_chain_cert - add certificate to chain
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_add_extra_chain_cert(SSL_CTX ctx, X509 *x509)
+
+=head1 DESCRIPTION
+
+SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the certificate
+chain presented together with the certificate. Several certificates
+can be added one after the other.
+
+=head1 NOTES
+
+When constructing the certificate chain, the chain will be formed from
+these certificates explicitly specified. If no chain is specified,
+the library will try to complete the chain from the available CA
+certificates in the trusted CA storage, see
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.
+
+=head1 RETURN VALUES
+
+SSL_CTX_add_extra_chain_cert() returns 1 on success. Check out the
+error stack to find out the reason for failure otherwise.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
+L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>,
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_add_session.pod b/openssl/doc/ssl/SSL_CTX_add_session.pod
new file mode 100644
index 000000000..82676b26b
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_add_session.pod
@@ -0,0 +1,73 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c);
+ int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c);
+
+ int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
+ int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
+
+=head1 DESCRIPTION
+
+SSL_CTX_add_session() adds the session B<c> to the context B<ctx>. The
+reference count for session B<c> is incremented by 1. If a session with
+the same session id already exists, the old session is removed by calling
+L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>.
+
+SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>.
+L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> is called once for B<c>.
+
+SSL_add_session() and SSL_remove_session() are synonyms for their
+SSL_CTX_*() counterparts.
+
+=head1 NOTES
+
+When adding a new session to the internal session cache, it is examined
+whether a session with the same session id already exists. In this case
+it is assumed that both sessions are identical. If the same session is
+stored in a different SSL_SESSION object, The old session is
+removed and replaced by the new session. If the session is actually
+identical (the SSL_SESSION object is identical), SSL_CTX_add_session()
+is a no-op, and the return value is 0.
+
+If a server SSL_CTX is configured with the SSL_SESS_CACHE_NO_INTERNAL_STORE
+flag then the internal cache will not be populated automatically by new
+sessions negotiated by the SSL/TLS implementation, even though the internal
+cache will be searched automatically for session-resume requests (the
+latter can be surpressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the
+application can use SSL_CTX_add_session() directly to have full control
+over the sessions that can be resumed if desired.
+
+
+=head1 RETURN VALUES
+
+The following values are returned by all functions:
+
+=over 4
+
+=item 0
+
+ The operation failed. In case of the add operation, it was tried to add
+ the same (identical) session twice. In case of the remove operation, the
+ session was not found in the cache.
+
+=item 1
+
+ The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_ctrl.pod b/openssl/doc/ssl/SSL_CTX_ctrl.pod
new file mode 100644
index 000000000..fb6adcf50
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_ctrl.pod
@@ -0,0 +1,34 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_ctrl, SSL_CTX_callback_ctrl, SSL_ctrl, SSL_callback_ctrl - internal handling functions for SSL_CTX and SSL objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, void *parg);
+ long SSL_CTX_callback_ctrl(SSL_CTX *, int cmd, void (*fp)());
+
+ long SSL_ctrl(SSL *ssl, int cmd, long larg, void *parg);
+ long SSL_callback_ctrl(SSL *, int cmd, void (*fp)());
+
+=head1 DESCRIPTION
+
+The SSL_*_ctrl() family of functions is used to manipulate settings of
+the SSL_CTX and SSL objects. Depending on the command B<cmd> the arguments
+B<larg>, B<parg>, or B<fp> are evaluated. These functions should never
+be called directly. All functionalities needed are made available via
+other functions or macros.
+
+=head1 RETURN VALUES
+
+The return values of the SSL*_ctrl() functions depend on the command
+supplied via the B<cmd> parameter.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_flush_sessions.pod b/openssl/doc/ssl/SSL_CTX_flush_sessions.pod
new file mode 100644
index 000000000..148c36c87
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_flush_sessions.pod
@@ -0,0 +1,49 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm);
+ void SSL_flush_sessions(SSL_CTX *ctx, long tm);
+
+=head1 DESCRIPTION
+
+SSL_CTX_flush_sessions() causes a run through the session cache of
+B<ctx> to remove sessions expired at time B<tm>.
+
+SSL_flush_sessions() is a synonym for SSL_CTX_flush_sessions().
+
+=head1 NOTES
+
+If enabled, the internal session cache will collect all sessions established
+up to the specified maximum number (see SSL_CTX_sess_set_cache_size()).
+As sessions will not be reused ones they are expired, they should be
+removed from the cache to save resources. This can either be done
+ automatically whenever 255 new sessions were established (see
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>)
+or manually by calling SSL_CTX_flush_sessions().
+
+The parameter B<tm> specifies the time which should be used for the
+expiration test, in most cases the actual time given by time(0)
+will be used.
+
+SSL_CTX_flush_sessions() will only check sessions stored in the internal
+cache. When a session is found and removed, the remove_session_cb is however
+called to synchronize with the external cache (see
+L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>).
+
+=head1 RETURN VALUES
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>,
+L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_free.pod b/openssl/doc/ssl/SSL_CTX_free.pod
new file mode 100644
index 000000000..51d867696
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_free.pod
@@ -0,0 +1,41 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_free - free an allocated SSL_CTX object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_free(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_free() decrements the reference count of B<ctx>, and removes the
+SSL_CTX object pointed to by B<ctx> and frees up the allocated memory if the
+the reference count has reached 0.
+
+It also calls the free()ing procedures for indirectly affected items, if
+applicable: the session cache, the list of ciphers, the list of Client CAs,
+the certificates and keys.
+
+=head1 WARNINGS
+
+If a session-remove callback is set (SSL_CTX_sess_set_remove_cb()), this
+callback will be called for each session being freed from B<ctx>'s
+session cache. This implies, that all corresponding sessions from an
+external session cache are removed as well. If this is not desired, the user
+should explicitly unset the callback by calling
+SSL_CTX_sess_set_remove_cb(B<ctx>, NULL) prior to calling SSL_CTX_free().
+
+=head1 RETURN VALUES
+
+SSL_CTX_free() does not provide diagnostic information.
+
+=head1 SEE ALSO
+
+L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<ssl(3)|ssl(3)>,
+L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod b/openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod
new file mode 100644
index 000000000..0c40a91f2
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data - internal application specific data functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_get_ex_new_index(long argl, void *argp,
+ CRYPTO_EX_new *new_func,
+ CRYPTO_EX_dup *dup_func,
+ CRYPTO_EX_free *free_func);
+
+ int SSL_CTX_set_ex_data(SSL_CTX *ctx, int idx, void *arg);
+
+ void *SSL_CTX_get_ex_data(const SSL_CTX *ctx, int idx);
+
+ typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
+ int idx, long argl, void *argp);
+ typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
+ int idx, long argl, void *argp);
+ typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
+ int idx, long argl, void *argp);
+
+=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.
+
+SSL_CTX_get_ex_new_index() is used to register a new index for application
+specific data.
+
+SSL_CTX_set_ex_data() is used to store application data at B<arg> for B<idx>
+into the B<ctx> object.
+
+SSL_CTX_get_ex_data() is used to retrieve the information for B<idx> from
+B<ctx>.
+
+A detailed description for the B<*_get_ex_new_index()> functionality
+can be found in L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>.
+The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in
+L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
+L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod b/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod
new file mode 100644
index 000000000..2a3747e75
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod
@@ -0,0 +1,50 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback - get currently set verification parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_get_verify_mode(const SSL_CTX *ctx);
+ int SSL_get_verify_mode(const SSL *ssl);
+ int SSL_CTX_get_verify_depth(const SSL_CTX *ctx);
+ int SSL_get_verify_depth(const SSL *ssl);
+ int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int, X509_STORE_CTX *);
+ int (*SSL_get_verify_callback(const SSL *ssl))(int, X509_STORE_CTX *);
+
+=head1 DESCRIPTION
+
+SSL_CTX_get_verify_mode() returns the verification mode currently set in
+B<ctx>.
+
+SSL_get_verify_mode() returns the verification mode currently set in
+B<ssl>.
+
+SSL_CTX_get_verify_depth() returns the verification depth limit currently set
+in B<ctx>. If no limit has been explicitly set, -1 is returned and the
+default value will be used.
+
+SSL_get_verify_depth() returns the verification depth limit currently set
+in B<ssl>. If no limit has been explicitly set, -1 is returned and the
+default value will be used.
+
+SSL_CTX_get_verify_callback() returns a function pointer to the verification
+callback currently set in B<ctx>. If no callback was explicitly set, the
+NULL pointer is returned and the default callback will be used.
+
+SSL_get_verify_callback() returns a function pointer to the verification
+callback currently set in B<ssl>. If no callback was explicitly set, the
+NULL pointer is returned and the default callback will be used.
+
+=head1 RETURN VALUES
+
+See DESCRIPTION
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod b/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod
new file mode 100644
index 000000000..84a799fc7
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod
@@ -0,0 +1,124 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_load_verify_locations - set default locations for trusted CA
+certificates
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
+ const char *CApath);
+
+=head1 DESCRIPTION
+
+SSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at
+which CA certificates for verification purposes are located. The certificates
+available via B<CAfile> and B<CApath> are trusted.
+
+=head1 NOTES
+
+If B<CAfile> is not NULL, it points to a file of CA certificates in PEM
+format. The file can contain several CA certificates identified by
+
+ -----BEGIN CERTIFICATE-----
+ ... (CA certificate in base64 encoding) ...
+ -----END CERTIFICATE-----
+
+sequences. Before, between, and after the certificates text is allowed
+which can be used e.g. for descriptions of the certificates.
+
+The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations()
+function.
+
+If B<CApath> is not NULL, it points to a directory containing CA certificates
+in PEM format. The files each contain one CA certificate. The files are
+looked up by the CA subject name hash value, which must hence be available.
+If more than one CA certificate with the same name hash value exist, the
+extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search
+is performed in the ordering of the extension number, regardless of other
+properties of the certificates.
+Use the B<c_rehash> utility to create the necessary links.
+
+The certificates in B<CApath> are only looked up when required, e.g. when
+building the certificate chain or when actually performing the verification
+of a peer certificate.
+
+When looking up CA certificates, the OpenSSL library will first search the
+certificates in B<CAfile>, then those in B<CApath>. Certificate matching
+is done based on the subject name, the key identifier (if present), and the
+serial number as taken from the certificate to be verified. If these data
+do not match, the next certificate will be tried. If a first certificate
+matching the parameters is found, the verification process will be performed;
+no other certificates for the same parameters will be searched in case of
+failure.
+
+In server mode, when requesting a client certificate, the server must send
+the list of CAs of which it will accept client certificates. This list
+is not influenced by the contents of B<CAfile> or B<CApath> and must
+explicitly be set using the
+L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>
+family of functions.
+
+When building its own certificate chain, an OpenSSL client/server will
+try to fill in missing certificates from B<CAfile>/B<CApath>, if the
+certificate chain was not explicitly specified (see
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>.
+
+=head1 WARNINGS
+
+If several CA certificates matching the name, key identifier, and serial
+number condition are available, only the first one will be examined. This
+may lead to unexpected results if the same CA certificate is available
+with different expiration dates. If a "certificate expired" verification
+error occurs, no other certificate will be searched. Make sure to not
+have expired certificates mixed with valid ones.
+
+=head1 EXAMPLES
+
+Generate a CA certificate file with descriptive text from the CA certificates
+ca1.pem ca2.pem ca3.pem:
+
+ #!/bin/sh
+ rm CAfile.pem
+ for i in ca1.pem ca2.pem ca3.pem ; do
+ openssl x509 -in $i -text >> CAfile.pem
+ done
+
+Prepare the directory /some/where/certs containing several CA certificates
+for use as B<CApath>:
+
+ cd /some/where/certs
+ c_rehash .
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 0
+
+The operation failed because B<CAfile> and B<CApath> are NULL or the
+processing at one of the locations specified failed. Check the error
+stack to find out the reason.
+
+=item 1
+
+The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,
+L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_new.pod b/openssl/doc/ssl/SSL_CTX_new.pod
new file mode 100644
index 000000000..465220a75
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_new.pod
@@ -0,0 +1,94 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_new - create a new SSL_CTX object as framework for TLS/SSL enabled functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_CTX *SSL_CTX_new(SSL_METHOD *method);
+
+=head1 DESCRIPTION
+
+SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish
+TLS/SSL enabled connections.
+
+=head1 NOTES
+
+The SSL_CTX object uses B<method> as connection method. The methods exist
+in a generic type (for client and server use), a server only type, and a
+client only type. B<method> can be of the following types:
+
+=over 4
+
+=item SSLv2_method(void), SSLv2_server_method(void), SSLv2_client_method(void)
+
+A TLS/SSL connection established with these methods will only understand
+the SSLv2 protocol. A client will send out SSLv2 client hello messages
+and will also indicate that it only understand SSLv2. A server will only
+understand SSLv2 client hello messages.
+
+=item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void)
+
+A TLS/SSL connection established with these methods will only understand the
+SSLv3 protocol. A client will send out SSLv3 client hello messages
+and will indicate that it only understands SSLv3. A server will only understand
+SSLv3 client hello messages. This especially means, that it will
+not understand SSLv2 client hello messages which are widely used for
+compatibility reasons, see SSLv23_*_method().
+
+=item TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void)
+
+A TLS/SSL connection established with these methods will only understand the
+TLSv1 protocol. A client will send out TLSv1 client hello messages
+and will indicate that it only understands TLSv1. A server will only understand
+TLSv1 client hello messages. This especially means, that it will
+not understand SSLv2 client hello messages which are widely used for
+compatibility reasons, see SSLv23_*_method(). It will also not understand
+SSLv3 client hello messages.
+
+=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)
+
+A TLS/SSL connection established with these methods will understand the SSLv2,
+SSLv3, and TLSv1 protocol. A client will send out SSLv2 client hello messages
+and will indicate that it also understands SSLv3 and TLSv1. A server will
+understand SSLv2, SSLv3, and TLSv1 client hello messages. This is the best
+choice when compatibility is a concern.
+
+=back
+
+The list of protocols available can later be limited using the SSL_OP_NO_SSLv2,
+SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 options of the B<SSL_CTX_set_options()> or
+B<SSL_set_options()> functions. Using these options it is possible to choose
+e.g. SSLv23_server_method() and be able to negotiate with all possible
+clients, but to only allow newer protocols like SSLv3 or TLSv1.
+
+SSL_CTX_new() initializes the list of ciphers, the session cache setting,
+the callbacks, the keys and certificates, and the options to its default
+values.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+The creation of a new SSL_CTX object failed. Check the error stack to
+find out the reason.
+
+=item Pointer to an SSL_CTX object
+
+The return value points to an allocated SSL_CTX object.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_CTX_free(3)|SSL_CTX_free(3)>, L<SSL_accept(3)|SSL_accept(3)>,
+L<ssl(3)|ssl(3)>, L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_sess_number.pod b/openssl/doc/ssl/SSL_CTX_sess_number.pod
new file mode 100644
index 000000000..19aa4e290
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_sess_number.pod
@@ -0,0 +1,76 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_sess_number, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_accept, SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_hits, SSL_CTX_sess_cb_hits, SSL_CTX_sess_misses, SSL_CTX_sess_timeouts, SSL_CTX_sess_cache_full - obtain session cache statistics
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_sess_number(SSL_CTX *ctx);
+ long SSL_CTX_sess_connect(SSL_CTX *ctx);
+ long SSL_CTX_sess_connect_good(SSL_CTX *ctx);
+ long SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx);
+ long SSL_CTX_sess_accept(SSL_CTX *ctx);
+ long SSL_CTX_sess_accept_good(SSL_CTX *ctx);
+ long SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx);
+ long SSL_CTX_sess_hits(SSL_CTX *ctx);
+ long SSL_CTX_sess_cb_hits(SSL_CTX *ctx);
+ long SSL_CTX_sess_misses(SSL_CTX *ctx);
+ long SSL_CTX_sess_timeouts(SSL_CTX *ctx);
+ long SSL_CTX_sess_cache_full(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_sess_number() returns the current number of sessions in the internal
+session cache.
+
+SSL_CTX_sess_connect() returns the number of started SSL/TLS handshakes in
+client mode.
+
+SSL_CTX_sess_connect_good() returns the number of successfully established
+SSL/TLS sessions in client mode.
+
+SSL_CTX_sess_connect_renegotiate() returns the number of start renegotiations
+in client mode.
+
+SSL_CTX_sess_accept() returns the number of started SSL/TLS handshakes in
+server mode.
+
+SSL_CTX_sess_accept_good() returns the number of successfully established
+SSL/TLS sessions in server mode.
+
+SSL_CTX_sess_accept_renegotiate() returns the number of start renegotiations
+in server mode.
+
+SSL_CTX_sess_hits() returns the number of successfully reused sessions.
+In client mode a session set with L<SSL_set_session(3)|SSL_set_session(3)>
+successfully reused is counted as a hit. In server mode a session successfully
+retrieved from internal or external cache is counted as a hit.
+
+SSL_CTX_sess_cb_hits() returns the number of successfully retrieved sessions
+from the external session cache in server mode.
+
+SSL_CTX_sess_misses() returns the number of sessions proposed by clients
+that were not found in the internal session cache in server mode.
+
+SSL_CTX_sess_timeouts() returns the number of sessions proposed by clients
+and either found in the internal or external session cache in server mode,
+ but that were invalid due to timeout. These sessions are not included in
+the SSL_CTX_sess_hits() count.
+
+SSL_CTX_sess_cache_full() returns the number of sessions that were removed
+because the maximum session cache size was exceeded.
+
+=head1 RETURN VALUES
+
+The functions return the values indicated in the DESCRIPTION section.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>
+L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod b/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod
new file mode 100644
index 000000000..c8b99f4ee
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod
@@ -0,0 +1,51 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session cache size
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t);
+ long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_sess_set_cache_size() sets the size of the internal session cache
+of context B<ctx> to B<t>.
+
+SSL_CTX_sess_get_cache_size() returns the currently valid session cache size.
+
+=head1 NOTES
+
+The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT,
+currently 1024*20, so that up to 20000 sessions can be held. This size
+can be modified using the SSL_CTX_sess_set_cache_size() call. A special
+case is the size 0, which is used for unlimited size.
+
+When the maximum number of sessions is reached, no more new sessions are
+added to the cache. New space may be added by calling
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> to remove
+expired sessions.
+
+If the size of the session cache is reduced and more sessions are already
+in the session cache, old session will be removed at the next time a
+session shall be added. This removal is not synchronized with the
+expiration of sessions.
+
+=head1 RETURN VALUES
+
+SSL_CTX_sess_set_cache_size() returns the previously valid size.
+
+SSL_CTX_sess_get_cache_size() returns the currently valid size.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>,
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod
new file mode 100644
index 000000000..b9d54a40a
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod
@@ -0,0 +1,87 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
+ int (*new_session_cb)(SSL *, SSL_SESSION *));
+ void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
+ void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *));
+ void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
+ SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *));
+
+ int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess);
+ void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
+ SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy);
+
+ int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess);
+ void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
+ SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data,
+ int len, int *copy);
+
+=head1 DESCRIPTION
+
+SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically
+called whenever a new session was negotiated.
+
+SSL_CTX_sess_set_remove_cb() sets the callback function, which is
+automatically called whenever a session is removed by the SSL engine,
+because it is considered faulty or the session has become obsolete because
+of exceeding the timeout value.
+
+SSL_CTX_sess_set_get_cb() sets the callback function which is called,
+whenever a SSL/TLS client proposed to resume a session but the session
+could not be found in the internal session cache (see
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>).
+(SSL/TLS server only.)
+
+SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and
+SSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the
+provided callback functions. If a callback function has not been set,
+the NULL pointer is returned.
+
+=head1 NOTES
+
+In order to allow external session caching, synchronization with the internal
+session cache is realized via callback functions. Inside these callback
+functions, session can be saved to disk or put into a database using the
+L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> interface.
+
+The new_session_cb() is called, whenever a new session has been negotiated
+and session caching is enabled (see
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>).
+The new_session_cb() is passed the B<ssl> connection and the ssl session
+B<sess>. If the callback returns B<0>, the session will be immediately
+removed again.
+
+The remove_session_cb() is called, whenever the SSL engine removes a session
+from the internal cache. This happens when the session is removed because
+it is expired or when a connection was not shutdown cleanly. It also happens
+for all sessions in the internal session cache when
+L<SSL_CTX_free(3)|SSL_CTX_free(3)> is called. The remove_session_cb() is passed
+the B<ctx> and the ssl session B<sess>. It does not provide any feedback.
+
+The get_session_cb() is only called on SSL/TLS servers with the session id
+proposed by the client. The get_session_cb() is always called, also when
+session caching was disabled. The get_session_cb() is passed the
+B<ssl> connection, the session id of length B<length> at the memory location
+B<data>. With the parameter B<copy> the callback can require the
+SSL engine to increment the reference count of the SSL_SESSION object,
+Normally the reference count is not incremented and therefore the
+session must not be explicitly freed with
+L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>,
+L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
+L<SSL_CTX_free(3)|SSL_CTX_free(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_sessions.pod b/openssl/doc/ssl/SSL_CTX_sessions.pod
new file mode 100644
index 000000000..e05aab3c1
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_sessions.pod
@@ -0,0 +1,34 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_sessions - access internal session cache
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ struct lhash_st *SSL_CTX_sessions(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_sessions() returns a pointer to the lhash databases containing the
+internal session cache for B<ctx>.
+
+=head1 NOTES
+
+The sessions in the internal session cache are kept in an
+L<lhash(3)|lhash(3)> type database. It is possible to directly
+access this database e.g. for searching. In parallel, the sessions
+form a linked list which is maintained separately from the
+L<lhash(3)|lhash(3)> operations, so that the database must not be
+modified directly but by using the
+L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)> family of functions.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<lhash(3)|lhash(3)>,
+L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_cert_store.pod b/openssl/doc/ssl/SSL_CTX_set_cert_store.pod
new file mode 100644
index 000000000..6acf0d9f9
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_cert_store.pod
@@ -0,0 +1,57 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_cert_store, SSL_CTX_get_cert_store - manipulate X509 certificate verification storage
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *store);
+ X509_STORE *SSL_CTX_get_cert_store(const SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_cert_store() sets/replaces the certificate verification storage
+of B<ctx> to/with B<store>. If another X509_STORE object is currently
+set in B<ctx>, it will be X509_STORE_free()ed.
+
+SSL_CTX_get_cert_store() returns a pointer to the current certificate
+verification storage.
+
+=head1 NOTES
+
+In order to verify the certificates presented by the peer, trusted CA
+certificates must be accessed. These CA certificates are made available
+via lookup methods, handled inside the X509_STORE. From the X509_STORE
+the X509_STORE_CTX used when verifying certificates is created.
+
+Typically the trusted certificate store is handled indirectly via using
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.
+Using the SSL_CTX_set_cert_store() and SSL_CTX_get_cert_store() functions
+it is possible to manipulate the X509_STORE object beyond the
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
+call.
+
+Currently no detailed documentation on how to use the X509_STORE
+object is available. Not all members of the X509_STORE are used when
+the verification takes place. So will e.g. the verify_callback() be
+overridden with the verify_callback() set via the
+L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> family of functions.
+This document must therefore be updated when documentation about the
+X509_STORE object and its handling becomes available.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_cert_store() does not return diagnostic output.
+
+SSL_CTX_get_cert_store() returns the current setting.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,
+L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod
new file mode 100644
index 000000000..c0f4f8570
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod
@@ -0,0 +1,75 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*callback)(X509_STORE_CTX *,void *), void *arg);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_cert_verify_callback() sets the verification callback function for
+I<ctx>. SSL objects that are created from I<ctx> inherit the setting valid at
+the time when L<SSL_new(3)|SSL_new(3)> is called.
+
+=head1 NOTES
+
+Whenever a certificate is verified during a SSL/TLS handshake, a verification
+function is called. If the application does not explicitly specify a
+verification callback function, the built-in verification function is used.
+If a verification callback I<callback> is specified via
+SSL_CTX_set_cert_verify_callback(), the supplied callback function is called
+instead. By setting I<callback> to NULL, the default behaviour is restored.
+
+When the verification must be performed, I<callback> will be called with
+the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The
+argument I<arg> is specified by the application when setting I<callback>.
+
+I<callback> should return 1 to indicate verification success and 0 to
+indicate verification failure. If SSL_VERIFY_PEER is set and I<callback>
+returns 0, the handshake will fail. As the verification procedure may
+allow to continue the connection in case of failure (by always returning 1)
+the verification result must be set in any case using the B<error>
+member of I<x509_store_ctx> so that the calling application will be informed
+about the detailed result of the verification procedure!
+
+Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback>
+function set using L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>.
+
+=head1 WARNINGS
+
+Do not mix the verification callback described in this function with the
+B<verify_callback> function called during the verification process. The
+latter is set using the L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
+family of functions.
+
+Providing a complete verification procedure including certificate purpose
+settings etc is a complex task. The built-in procedure is quite powerful
+and in most cases it should be sufficient to modify its behaviour using
+the B<verify_callback> function.
+
+=head1 BUGS
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_cert_verify_callback() does not provide diagnostic information.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>,
+L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
+
+=head1 HISTORY
+
+Previous to OpenSSL 0.9.7, the I<arg> argument to B<SSL_CTX_set_cert_verify_callback>
+was ignored, and I<callback> was called simply as
+ int (*callback)(X509_STORE_CTX *)
+To compile software written for previous versions of OpenSSL, a dummy
+argument will have to be added to I<callback>.
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod b/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod
new file mode 100644
index 000000000..ed64f6415
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod
@@ -0,0 +1,70 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);
+ int SSL_set_cipher_list(SSL *ssl, const char *str);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_cipher_list() sets the list of available ciphers for B<ctx>
+using the control string B<str>. The format of the string is described
+in L<ciphers(1)|ciphers(1)>. The list of ciphers is inherited by all
+B<ssl> objects created from B<ctx>.
+
+SSL_set_cipher_list() sets the list of ciphers only for B<ssl>.
+
+=head1 NOTES
+
+The control string B<str> should be universally usable and not depend
+on details of the library configuration (ciphers compiled in). Thus no
+syntax checking takes place. Items that are not recognized, because the
+corresponding ciphers are not compiled in or because they are mistyped,
+are simply ignored. Failure is only flagged if no ciphers could be collected
+at all.
+
+It should be noted, that inclusion of a cipher to be used into the list is
+a necessary condition. On the client side, the inclusion into the list is
+also sufficient. On the server side, additional restrictions apply. All ciphers
+have additional requirements. ADH ciphers don't need a certificate, but
+DH-parameters must have been set. All other ciphers need a corresponding
+certificate and key.
+
+A RSA cipher can only be chosen, when a RSA certificate is available.
+RSA export ciphers with a keylength of 512 bits for the RSA key require
+a temporary 512 bit RSA key, as typically the supplied key has a length
+of 1024 bit (see
+L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>).
+RSA ciphers using EDH need a certificate and key and additional DH-parameters
+(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
+
+A DSA cipher can only be chosen, when a DSA certificate is available.
+DSA ciphers always use DH key exchange and therefore need DH-parameters
+(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
+
+When these conditions are not met for any cipher in the list (e.g. a
+client only supports export RSA ciphers with a asymmetric key length
+of 512 bits and the server is not configured to use temporary RSA
+keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated
+and the handshake will fail.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher
+could be selected and 0 on complete failure.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
+L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
+L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
+L<ciphers(1)|ciphers(1)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod b/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod
new file mode 100644
index 000000000..632b556d1
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod
@@ -0,0 +1,94 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
+SSL_add_client_CA - set list of CAs sent to the client when requesting a
+client certificate
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
+ void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
+ int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
+ int SSL_add_client_CA(SSL *ssl, X509 *cacert);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
+requesting a client certificate for B<ctx>.
+
+SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
+requesting a client certificate for the chosen B<ssl>, overriding the
+setting valid for B<ssl>'s SSL_CTX object.
+
+SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
+list of CAs sent to the client when requesting a client certificate for
+B<ctx>.
+
+SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
+list of CAs sent to the client when requesting a client certificate for
+the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
+
+=head1 NOTES
+
+When a TLS/SSL server requests a client certificate (see
+B<SSL_CTX_set_verify_options()>), it sends a list of CAs, for which
+it will accept certificates, to the client.
+
+This list must explicitly be set using SSL_CTX_set_client_CA_list() for
+B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list
+specified overrides the previous setting. The CAs listed do not become
+trusted (B<list> only contains the names, not the complete certificates); use
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
+to additionally load them for verification.
+
+If the list of acceptable CAs is compiled in a file, the
+L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>
+function can be used to help importing the necessary data.
+
+SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional
+items the list of client CAs. If no list was specified before using
+SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client
+CA list for B<ctx> or B<ssl> (as appropriate) is opened.
+
+These functions are only useful for TLS/SSL servers.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
+diagnostic information.
+
+SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
+values:
+
+=over 4
+
+=item 1
+
+The operation succeeded.
+
+=item 0
+
+A failure while manipulating the STACK_OF(X509_NAME) object occurred or
+the X509_NAME could not be extracted from B<cacert>. Check the error stack
+to find out the reason.
+
+=back
+
+=head1 EXAMPLES
+
+Scan all certificates in B<CAfile> and list them as acceptable CAs:
+
+ SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile));
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
+L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>,
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod
new file mode 100644
index 000000000..3465b5c7b
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod
@@ -0,0 +1,94 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
+ int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
+ int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_client_cert_cb() sets the B<client_cert_cb()> callback, that is
+called when a client certificate is requested by a server and no certificate
+was yet set for the SSL object.
+
+When B<client_cert_cb()> is NULL, no callback function is used.
+
+SSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback
+function.
+
+client_cert_cb() is the application defined callback. If it wants to
+set a certificate, a certificate/private key combination must be set
+using the B<x509> and B<pkey> arguments and "1" must be returned. The
+certificate will be installed into B<ssl>, see the NOTES and BUGS sections.
+If no certificate should be set, "0" has to be returned and no certificate
+will be sent. A negative return value will suspend the handshake and the
+handshake function will return immediatly. L<SSL_get_error(3)|SSL_get_error(3)>
+will return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was
+suspended. The next call to the handshake function will again lead to the call
+of client_cert_cb(). It is the job of the client_cert_cb() to store information
+about the state of the last call, if required to continue.
+
+=head1 NOTES
+
+During a handshake (or renegotiation) a server may request a certificate
+from the client. A client certificate must only be sent, when the server
+did send the request.
+
+When a certificate was set using the
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> family of functions,
+it will be sent to the server. The TLS standard requires that only a
+certificate is sent, if it matches the list of acceptable CAs sent by the
+server. This constraint is violated by the default behavior of the OpenSSL
+library. Using the callback function it is possible to implement a proper
+selection routine or to allow a user interaction to choose the certificate to
+be sent.
+
+If a callback function is defined and no certificate was yet defined for the
+SSL object, the callback function will be called.
+If the callback function returns a certificate, the OpenSSL library
+will try to load the private key and certificate data into the SSL
+object using the SSL_use_certificate() and SSL_use_private_key() functions.
+Thus it will permanently install the certificate and key for this SSL
+object. It will not be reset by calling L<SSL_clear(3)|SSL_clear(3)>.
+If the callback returns no certificate, the OpenSSL library will not send
+a certificate.
+
+=head1 BUGS
+
+The client_cert_cb() cannot return a complete certificate chain, it can
+only return one client certificate. If the chain only has a length of 2,
+the root CA certificate may be omitted according to the TLS standard and
+thus a standard conforming answer can be sent to the server. For a
+longer chain, the client must send the complete chain (with the option
+to leave out the root CA certificate). This can only be accomplished by
+either adding the intermediate CA certificates into the trusted
+certificate store for the SSL_CTX object (resulting in having to add
+CA certificates that otherwise maybe would not be trusted), or by adding
+the chain certificates using the
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
+function, which is only available for the SSL_CTX object as a whole and that
+therefore probably can only apply for one client certificate, making
+the concept of the callback function (to allow the choice from several
+certificates) questionable.
+
+Once the SSL object has been used in conjunction with the callback function,
+the certificate will be set for the SSL object and will not be cleared
+even when L<SSL_clear(3)|SSL_clear(3)> is being called. It is therefore
+mandatory to destroy the SSL object using L<SSL_free(3)|SSL_free(3)>
+and create a new one to return to the previous state.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
+L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod
new file mode 100644
index 000000000..2b87f01ca
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod
@@ -0,0 +1,76 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata - set passwd callback for encrypted PEM file handling
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb);
+ void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u);
+
+ int pem_passwd_cb(char *buf, int size, int rwflag, void *userdata);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_default_passwd_cb() sets the default password callback called
+when loading/storing a PEM certificate with encryption.
+
+SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to B<userdata> which
+will be provided to the password callback on invocation.
+
+The pem_passwd_cb(), which must be provided by the application, hands back the
+password to be used during decryption. On invocation a pointer to B<userdata>
+is provided. The pem_passwd_cb must write the password into the provided buffer
+B<buf> which is of size B<size>. The actual length of the password must
+be returned to the calling function. B<rwflag> indicates whether the
+callback is used for reading/decryption (rwflag=0) or writing/encryption
+(rwflag=1).
+
+=head1 NOTES
+
+When loading or storing private keys, a password might be supplied to
+protect the private key. The way this password can be supplied may depend
+on the application. If only one private key is handled, it can be practical
+to have pem_passwd_cb() handle the password dialog interactively. If several
+keys have to be handled, it can be practical to ask for the password once,
+then keep it in memory and use it several times. In the last case, the
+password could be stored into the B<userdata> storage and the
+pem_passwd_cb() only returns the password already stored.
+
+When asking for the password interactively, pem_passwd_cb() can use
+B<rwflag> to check, whether an item shall be encrypted (rwflag=1).
+In this case the password dialog may ask for the same password twice
+for comparison in order to catch typos, that would make decryption
+impossible.
+
+Other items in PEM formatting (certificates) can also be encrypted, it is
+however not usual, as certificate information is considered public.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_default_passwd_cb() and SSL_CTX_set_default_passwd_cb_userdata()
+do not provide diagnostic information.
+
+=head1 EXAMPLES
+
+The following example returns the password provided as B<userdata> to the
+calling function. The password is considered to be a '\0' terminated
+string. If the password does not fit into the buffer, the password is
+truncated.
+
+ int pem_passwd_cb(char *buf, int size, int rwflag, void *password)
+ {
+ strncpy(buf, (char *)(password), size);
+ buf[size - 1] = '\0';
+ return(strlen(buf));
+ }
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod b/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod
new file mode 100644
index 000000000..798e8443a
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod
@@ -0,0 +1,150 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, SSL_has_matching_session_id - manipulate generation of SSL session IDs (server only)
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ typedef int (*GEN_SESSION_CB)(const SSL *ssl, unsigned char *id,
+ unsigned int *id_len);
+
+ int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb);
+ int SSL_set_generate_session_id(SSL *ssl, GEN_SESSION_CB, cb);
+ int SSL_has_matching_session_id(const SSL *ssl, const unsigned char *id,
+ unsigned int id_len);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_generate_session_id() sets the callback function for generating
+new session ids for SSL/TLS sessions for B<ctx> to be B<cb>.
+
+SSL_set_generate_session_id() sets the callback function for generating
+new session ids for SSL/TLS sessions for B<ssl> to be B<cb>.
+
+SSL_has_matching_session_id() checks, whether a session with id B<id>
+(of length B<id_len>) is already contained in the internal session cache
+of the parent context of B<ssl>.
+
+=head1 NOTES
+
+When a new session is established between client and server, the server
+generates a session id. The session id is an arbitrary sequence of bytes.
+The length of the session id is 16 bytes for SSLv2 sessions and between
+1 and 32 bytes for SSLv3/TLSv1. The session id is not security critical
+but must be unique for the server. Additionally, the session id is
+transmitted in the clear when reusing the session so it must not contain
+sensitive information.
+
+Without a callback being set, an OpenSSL server will generate a unique
+session id from pseudo random numbers of the maximum possible length.
+Using the callback function, the session id can be changed to contain
+additional information like e.g. a host id in order to improve load balancing
+or external caching techniques.
+
+The callback function receives a pointer to the memory location to put
+B<id> into and a pointer to the maximum allowed length B<id_len>. The
+buffer at location B<id> is only guaranteed to have the size B<id_len>.
+The callback is only allowed to generate a shorter id and reduce B<id_len>;
+the callback B<must never> increase B<id_len> or write to the location
+B<id> exceeding the given limit.
+
+If a SSLv2 session id is generated and B<id_len> is reduced, it will be
+restored after the callback has finished and the session id will be padded
+with 0x00. It is not recommended to change the B<id_len> for SSLv2 sessions.
+The callback can use the L<SSL_get_version(3)|SSL_get_version(3)> function
+to check, whether the session is of type SSLv2.
+
+The location B<id> is filled with 0x00 before the callback is called, so the
+callback may only fill part of the possible length and leave B<id_len>
+untouched while maintaining reproducibility.
+
+Since the sessions must be distinguished, session ids must be unique.
+Without the callback a random number is used, so that the probability
+of generating the same session id is extremely small (2^128 possible ids
+for an SSLv2 session, 2^256 for SSLv3/TLSv1). In order to assure the
+uniqueness of the generated session id, the callback must call
+SSL_has_matching_session_id() and generate another id if a conflict occurs.
+If an id conflict is not resolved, the handshake will fail.
+If the application codes e.g. a unique host id, a unique process number, and
+a unique sequence number into the session id, uniqueness could easily be
+achieved without randomness added (it should however be taken care that
+no confidential information is leaked this way). If the application can not
+guarantee uniqueness, it is recommended to use the maximum B<id_len> and
+fill in the bytes not used to code special information with random data
+to avoid collisions.
+
+SSL_has_matching_session_id() will only query the internal session cache,
+not the external one. Since the session id is generated before the
+handshake is completed, it is not immediately added to the cache. If
+another thread is using the same internal session cache, a race condition
+can occur in that another thread generates the same session id.
+Collisions can also occur when using an external session cache, since
+the external cache is not tested with SSL_has_matching_session_id()
+and the same race condition applies.
+
+When calling SSL_has_matching_session_id() for an SSLv2 session with
+reduced B<id_len>, the match operation will be performed using the
+fixed length required and with a 0x00 padded id.
+
+The callback must return 0 if it cannot generate a session id for whatever
+reason and return 1 on success.
+
+=head1 EXAMPLES
+
+The callback function listed will generate a session id with the
+server id given, and will fill the rest with pseudo random bytes:
+
+ const char session_id_prefix = "www-18";
+
+ #define MAX_SESSION_ID_ATTEMPTS 10
+ static int generate_session_id(const SSL *ssl, unsigned char *id,
+ unsigned int *id_len)
+ {
+ unsigned int count = 0;
+ const char *version;
+
+ version = SSL_get_version(ssl);
+ if (!strcmp(version, "SSLv2"))
+ /* we must not change id_len */;
+
+ do {
+ RAND_pseudo_bytes(id, *id_len);
+ /* Prefix the session_id with the required prefix. NB: If our
+ * prefix is too long, clip it - but there will be worse effects
+ * anyway, eg. the server could only possibly create 1 session
+ * ID (ie. the prefix!) so all future session negotiations will
+ * fail due to conflicts. */
+ memcpy(id, session_id_prefix,
+ (strlen(session_id_prefix) < *id_len) ?
+ strlen(session_id_prefix) : *id_len);
+ }
+ while(SSL_has_matching_session_id(ssl, id, *id_len) &&
+ (++count < MAX_SESSION_ID_ATTEMPTS));
+ if(count >= MAX_SESSION_ID_ATTEMPTS)
+ return 0;
+ return 1;
+ }
+
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
+always return 1.
+
+SSL_has_matching_session_id() returns 1 if another session with the
+same id is already in the cache.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_get_version(3)|SSL_get_version(3)>
+
+=head1 HISTORY
+
+SSL_CTX_set_generate_session_id(), SSL_set_generate_session_id()
+and SSL_has_matching_session_id() have been introduced in
+OpenSSL 0.9.7.
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_info_callback.pod b/openssl/doc/ssl/SSL_CTX_set_info_callback.pod
new file mode 100644
index 000000000..0b4affd5e
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_info_callback.pod
@@ -0,0 +1,153 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)());
+ void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))();
+
+ void SSL_set_info_callback(SSL *ssl, void (*callback)());
+ void (*SSL_get_info_callback(const SSL *ssl))();
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to
+obtain state information for SSL objects created from B<ctx> during connection
+setup and use. The setting for B<ctx> is overridden from the setting for
+a specific SSL object, if specified.
+When B<callback> is NULL, not callback function is used.
+
+SSL_set_info_callback() sets the B<callback> function, that can be used to
+obtain state information for B<ssl> during connection setup and use.
+When B<callback> is NULL, the callback setting currently valid for
+B<ctx> is used.
+
+SSL_CTX_get_info_callback() returns a pointer to the currently set information
+callback function for B<ctx>.
+
+SSL_get_info_callback() returns a pointer to the currently set information
+callback function for B<ssl>.
+
+=head1 NOTES
+
+When setting up a connection and during use, it is possible to obtain state
+information from the SSL/TLS engine. When set, an information callback function
+is called whenever the state changes, an alert appears, or an error occurs.
+
+The callback function is called as B<callback(SSL *ssl, int where, int ret)>.
+The B<where> argument specifies information about where (in which context)
+the callback function was called. If B<ret> is 0, an error condition occurred.
+If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert
+information.
+
+B<where> is a bitmask made up of the following bits:
+
+=over 4
+
+=item SSL_CB_LOOP
+
+Callback has been called to indicate state change inside a loop.
+
+=item SSL_CB_EXIT
+
+Callback has been called to indicate error exit of a handshake function.
+(May be soft error with retry option for non-blocking setups.)
+
+=item SSL_CB_READ
+
+Callback has been called during read operation.
+
+=item SSL_CB_WRITE
+
+Callback has been called during write operation.
+
+=item SSL_CB_ALERT
+
+Callback has been called due to an alert being sent or received.
+
+=item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ)
+
+=item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE)
+
+=item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP)
+
+=item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT)
+
+=item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP)
+
+=item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT)
+
+=item SSL_CB_HANDSHAKE_START
+
+Callback has been called because a new handshake is started.
+
+=item SSL_CB_HANDSHAKE_DONE 0x20
+
+Callback has been called because a handshake is finished.
+
+=back
+
+The current state information can be obtained using the
+L<SSL_state_string(3)|SSL_state_string(3)> family of functions.
+
+The B<ret> information can be evaluated using the
+L<SSL_alert_type_string(3)|SSL_alert_type_string(3)> family of functions.
+
+=head1 RETURN VALUES
+
+SSL_set_info_callback() does not provide diagnostic information.
+
+SSL_get_info_callback() returns the current setting.
+
+=head1 EXAMPLES
+
+The following example callback function prints state strings, information
+about alerts being handled and error messages to the B<bio_err> BIO.
+
+ void apps_ssl_info_callback(SSL *s, int where, int ret)
+ {
+ const char *str;
+ int w;
+
+ w=where& ~SSL_ST_MASK;
+
+ if (w & SSL_ST_CONNECT) str="SSL_connect";
+ else if (w & SSL_ST_ACCEPT) str="SSL_accept";
+ else str="undefined";
+
+ if (where & SSL_CB_LOOP)
+ {
+ BIO_printf(bio_err,"%s:%s\n",str,SSL_state_string_long(s));
+ }
+ else if (where & SSL_CB_ALERT)
+ {
+ str=(where & SSL_CB_READ)?"read":"write";
+ BIO_printf(bio_err,"SSL3 alert %s:%s:%s\n",
+ str,
+ SSL_alert_type_string_long(ret),
+ SSL_alert_desc_string_long(ret));
+ }
+ else if (where & SSL_CB_EXIT)
+ {
+ if (ret == 0)
+ BIO_printf(bio_err,"%s:failed in %s\n",
+ str,SSL_state_string_long(s));
+ else if (ret < 0)
+ {
+ BIO_printf(bio_err,"%s:error in %s\n",
+ str,SSL_state_string_long(s));
+ }
+ }
+ }
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_state_string(3)|SSL_state_string(3)>,
+L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_max_cert_list.pod b/openssl/doc/ssl/SSL_CTX_set_max_cert_list.pod
new file mode 100644
index 000000000..da68cb9fc
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_max_cert_list.pod
@@ -0,0 +1,77 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list, SSL_get_max_cert_list, - manipulate allowed for the peer's certificate chain
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_max_cert_list(SSL_CTX *ctx, long size);
+ long SSL_CTX_get_max_cert_list(SSL_CTX *ctx);
+
+ long SSL_set_max_cert_list(SSL *ssl, long size);
+ long SSL_get_max_cert_list(SSL *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_max_cert_list() sets the maximum size allowed for the peer's
+certificate chain for all SSL objects created from B<ctx> to be <size> bytes.
+The SSL objects inherit the setting valid for B<ctx> at the time
+L<SSL_new(3)|SSL_new(3)> is being called.
+
+SSL_CTX_get_max_cert_list() returns the currently set maximum size for B<ctx>.
+
+SSL_set_max_cert_list() sets the maximum size allowed for the peer's
+certificate chain for B<ssl> to be <size> bytes. This setting stays valid
+until a new value is set.
+
+SSL_get_max_cert_list() returns the currently set maximum size for B<ssl>.
+
+=head1 NOTES
+
+During the handshake process, the peer may send a certificate chain.
+The TLS/SSL standard does not give any maximum size of the certificate chain.
+The OpenSSL library handles incoming data by a dynamically allocated buffer.
+In order to prevent this buffer from growing without bounds due to data
+received from a faulty or malicious peer, a maximum size for the certificate
+chain is set.
+
+The default value for the maximum certificate chain size is 100kB (30kB
+on the 16bit DOS platform). This should be sufficient for usual certificate
+chains (OpenSSL's default maximum chain length is 10, see
+L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, and certificates
+without special extensions have a typical size of 1-2kB).
+
+For special applications it can be necessary to extend the maximum certificate
+chain size allowed to be sent by the peer, see e.g. the work on
+"Internet X.509 Public Key Infrastructure Proxy Certificate Profile"
+and "TLS Delegation Protocol" at http://www.ietf.org/ and
+http://www.globus.org/ .
+
+Under normal conditions it should never be necessary to set a value smaller
+than the default, as the buffer is handled dynamically and only uses the
+memory actually required by the data sent by the peer.
+
+If the maximum certificate chain size allowed is exceeded, the handshake will
+fail with a SSL_R_EXCESSIVE_MESSAGE_SIZE error.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_max_cert_list() and SSL_set_max_cert_list() return the previously
+set value.
+
+SSL_CTX_get_max_cert_list() and SSL_get_max_cert_list() return the currently
+set value.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>,
+L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
+
+=head1 HISTORY
+
+SSL*_set/get_max_cert_list() have been introduced in OpenSSL 0.9.7.
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_mode.pod b/openssl/doc/ssl/SSL_CTX_set_mode.pod
new file mode 100644
index 000000000..9822544e5
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_mode.pod
@@ -0,0 +1,81 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_mode(SSL_CTX *ctx, long mode);
+ long SSL_set_mode(SSL *ssl, long mode);
+
+ long SSL_CTX_get_mode(SSL_CTX *ctx);
+ long SSL_get_mode(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>.
+Options already set before are not cleared.
+
+SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>.
+Options already set before are not cleared.
+
+SSL_CTX_get_mode() returns the mode set for B<ctx>.
+
+SSL_get_mode() returns the mode set for B<ssl>.
+
+=head1 NOTES
+
+The following mode changes are available:
+
+=over 4
+
+=item SSL_MODE_ENABLE_PARTIAL_WRITE
+
+Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success
+when just a single record has been written). When not set (the default),
+SSL_write() will only report success once the complete chunk was written.
+Once SSL_write() returns with r, r bytes have been successfully written
+and the next call to SSL_write() must only send the n-r bytes left,
+imitating the behaviour of write().
+
+=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
+
+Make it possible to retry SSL_write() with changed buffer location
+(the buffer contents must stay the same). This is not the default to avoid
+the misconception that non-blocking SSL_write() behaves like
+non-blocking write().
+
+=item SSL_MODE_AUTO_RETRY
+
+Never bother the application with retries if the transport is blocking.
+If a renegotiation take place during normal operation, a
+L<SSL_read(3)|SSL_read(3)> or L<SSL_write(3)|SSL_write(3)> would return
+with -1 and indicate the need to retry with SSL_ERROR_WANT_READ.
+In a non-blocking environment applications must be prepared to handle
+incomplete read/write operations.
+In a blocking environment, applications are not always prepared to
+deal with read/write operations returning without success report. The
+flag SSL_MODE_AUTO_RETRY will cause read/write operations to only
+return after the handshake and successful completion.
+
+=back
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask
+after adding B<mode>.
+
+SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_read(3)|SSL_read(3)>, L<SSL_write(3)|SSL_write(3)>
+
+=head1 HISTORY
+
+SSL_MODE_AUTO_RETRY as been added in OpenSSL 0.9.6.
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod b/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod
new file mode 100644
index 000000000..0015e6ea7
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod
@@ -0,0 +1,99 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_get_msg_callback_arg - install callback for observing protocol messages
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
+ void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
+
+ void SSL_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
+ void SSL_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to
+define a message callback function I<cb> for observing all SSL/TLS
+protocol messages (such as handshake messages) that are received or
+sent. SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg()
+can be used to set argument I<arg> to the callback function, which is
+available for arbitrary application use.
+
+SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify
+default settings that will be copied to new B<SSL> objects by
+L<SSL_new(3)|SSL_new(3)>. SSL_set_msg_callback() and
+SSL_set_msg_callback_arg() modify the actual settings of an B<SSL>
+object. Using a B<0> pointer for I<cb> disables the message callback.
+
+When I<cb> is called by the SSL/TLS library for a protocol message,
+the function arguments have the following meaning:
+
+=over 4
+
+=item I<write_p>
+
+This flag is B<0> when a protocol message has been received and B<1>
+when a protocol message has been sent.
+
+=item I<version>
+
+The protocol version according to which the protocol message is
+interpreted by the library. Currently, this is one of
+B<SSL2_VERSION>, B<SSL3_VERSION> and B<TLS1_VERSION> (for SSL 2.0, SSL
+3.0 and TLS 1.0, respectively).
+
+=item I<content_type>
+
+In the case of SSL 2.0, this is always B<0>. In the case of SSL 3.0
+or TLS 1.0, this is one of the B<ContentType> values defined in the
+protocol specification (B<change_cipher_spec(20)>, B<alert(21)>,
+B<handshake(22)>; but never B<application_data(23)> because the
+callback will only be called for protocol messages).
+
+=item I<buf>, I<len>
+
+I<buf> points to a buffer containing the protocol message, which
+consists of I<len> bytes. The buffer is no longer valid after the
+callback function has returned.
+
+=item I<ssl>
+
+The B<SSL> object that received or sent the message.
+
+=item I<arg>
+
+The user-defined argument optionally defined by
+SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg().
+
+=back
+
+=head1 NOTES
+
+Protocol messages are passed to the callback function after decryption
+and fragment collection where applicable. (Thus record boundaries are
+not visible.)
+
+If processing a received protocol message results in an error,
+the callback function may not be called. For example, the callback
+function will never see messages that are considered too large to be
+processed.
+
+Due to automatic protocol version negotiation, I<version> is not
+necessarily the protocol version used by the sender of the message: If
+a TLS 1.0 ClientHello message is received by an SSL 3.0-only server,
+I<version> will be B<SSL3_VERSION>.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>
+
+=head1 HISTORY
+
+SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(),
+SSL_set_msg_callback() and SSL_get_msg_callback_arg() were added in OpenSSL 0.9.7.
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_options.pod b/openssl/doc/ssl/SSL_CTX_set_options.pod
new file mode 100644
index 000000000..eaed19080
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_options.pod
@@ -0,0 +1,244 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine options
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_options(SSL_CTX *ctx, long options);
+ long SSL_set_options(SSL *ssl, long options);
+
+ long SSL_CTX_get_options(SSL_CTX *ctx);
+ long SSL_get_options(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
+Options already set before are not cleared!
+
+SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>.
+Options already set before are not cleared!
+
+SSL_CTX_get_options() returns the options set for B<ctx>.
+
+SSL_get_options() returns the options set for B<ssl>.
+
+=head1 NOTES
+
+The behaviour of the SSL library can be changed by setting several options.
+The options are coded as bitmasks and can be combined by a logical B<or>
+operation (|). Options can only be added but can never be reset.
+
+SSL_CTX_set_options() and SSL_set_options() affect the (external)
+protocol behaviour of the SSL library. The (internal) behaviour of
+the API can be changed by using the similar
+L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> and SSL_set_mode() functions.
+
+During a handshake, the option settings of the SSL object are used. When
+a new SSL object is created from a context using SSL_new(), the current
+option setting is copied. Changes to B<ctx> do not affect already created
+SSL objects. SSL_clear() does not affect the settings.
+
+The following B<bug workaround> options are available:
+
+=over 4
+
+=item SSL_OP_MICROSOFT_SESS_ID_BUG
+
+www.microsoft.com - when talking SSLv2, if session-id reuse is
+performed, the session-id passed back in the server-finished message
+is different from the one decided upon.
+
+=item SSL_OP_NETSCAPE_CHALLENGE_BUG
+
+Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte
+challenge but then appears to only use 16 bytes when generating the
+encryption keys. Using 16 bytes is ok but it should be ok to use 32.
+According to the SSLv3 spec, one should use 32 bytes for the challenge
+when operating in SSLv2/v3 compatibility mode, but as mentioned above,
+this breaks this server so 16 bytes is the way to go.
+
+=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
+
+ssl3.netscape.com:443, first a connection is established with RC4-MD5.
+If it is then resumed, we end up using DES-CBC3-SHA. It should be
+RC4-MD5 according to 7.6.1.3, 'cipher_suite'.
+
+Netscape-Enterprise/2.01 (https://merchant.netscape.com) has this bug.
+It only really shows up when connecting via SSLv2/v3 then reconnecting
+via SSLv3. The cipher list changes....
+
+NEW INFORMATION. Try connecting with a cipher list of just
+DES-CBC-SHA:RC4-MD5. For some weird reason, each new connection uses
+RC4-MD5, but a re-connect tries to use DES-CBC-SHA. So netscape, when
+doing a re-connect, always takes the first cipher in the cipher list.
+
+=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
+
+...
+
+=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
+
+...
+
+=item SSL_OP_MSIE_SSLV2_RSA_PADDING
+
+As of OpenSSL 0.9.7h and 0.9.8a, this option has no effect.
+
+=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG
+
+...
+
+=item SSL_OP_TLS_D5_BUG
+
+...
+
+=item SSL_OP_TLS_BLOCK_PADDING_BUG
+
+...
+
+=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
+
+Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol
+vulnerability affecting CBC ciphers, which cannot be handled by some
+broken SSL implementations. This option has no effect for connections
+using other ciphers.
+
+=item SSL_OP_ALL
+
+All of the above bug workarounds.
+
+=back
+
+It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround
+options if compatibility with somewhat broken implementations is
+desired.
+
+The following B<modifying> options are available:
+
+=over 4
+
+=item SSL_OP_TLS_ROLLBACK_BUG
+
+Disable version rollback attack detection.
+
+During the client key exchange, the client must send the same information
+about acceptable SSL/TLS protocol levels as during the first hello. Some
+clients violate this rule by adapting to the server's answer. (Example:
+the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
+only understands up to SSLv3. In this case the client must still use the
+same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
+to the server's answer and violate the version rollback protection.)
+
+=item SSL_OP_SINGLE_DH_USE
+
+Always create a new key when using temporary/ephemeral DH parameters
+(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
+This option must be used to prevent small subgroup attacks, when
+the DH parameters were not generated using "strong" primes
+(e.g. when using DSA-parameters, see L<dhparam(1)|dhparam(1)>).
+If "strong" primes were used, it is not strictly necessary to generate
+a new DH key during each handshake but it is also recommended.
+B<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever
+temporary/ephemeral DH parameters are used.
+
+=item SSL_OP_EPHEMERAL_RSA
+
+Always use ephemeral (temporary) RSA key when doing RSA operations
+(see L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>).
+According to the specifications this is only done, when a RSA key
+can only be used for signature operations (namely under export ciphers
+with restricted RSA keylength). By setting this option, ephemeral
+RSA keys are always used. This option breaks compatibility with the
+SSL/TLS specifications and may lead to interoperability problems with
+clients and should therefore never be used. Ciphers with EDH (ephemeral
+Diffie-Hellman) key exchange should be used instead.
+
+=item SSL_OP_CIPHER_SERVER_PREFERENCE
+
+When choosing a cipher, use the server's preferences instead of the client
+preferences. When not set, the SSL server will always follow the clients
+preferences. When set, the SSLv3/TLSv1 server will choose following its
+own preferences. Because of the different protocol, for SSLv2 the server
+will send its list of preferences to the client and the client chooses.
+
+=item SSL_OP_PKCS1_CHECK_1
+
+...
+
+=item SSL_OP_PKCS1_CHECK_2
+
+...
+
+=item SSL_OP_NETSCAPE_CA_DN_BUG
+
+If we accept a netscape connection, demand a client cert, have a
+non-self-signed CA which does not have its CA in netscape, and the
+browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta
+
+=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
+
+...
+
+=item SSL_OP_NO_SSLv2
+
+Do not use the SSLv2 protocol.
+
+=item SSL_OP_NO_SSLv3
+
+Do not use the SSLv3 protocol.
+
+=item SSL_OP_NO_TLSv1
+
+Do not use the TLSv1 protocol.
+
+=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
+
+When performing renegotiation as a server, always start a new session
+(i.e., session resumption requests are only accepted in the initial
+handshake). This option is not needed for clients.
+
+=item SSL_OP_NO_TICKET
+
+Normally clients and servers will, where possible, transparently make use
+of RFC4507bis tickets for stateless session resumption if extension support
+is explicitly set when OpenSSL is compiled.
+
+If this option is set this functionality is disabled and tickets will
+not be used by clients or servers.
+
+=back
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_options() and SSL_set_options() return the new options bitmask
+after adding B<options>.
+
+SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
+L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
+L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
+L<dhparam(1)|dhparam(1)>
+
+=head1 HISTORY
+
+B<SSL_OP_CIPHER_SERVER_PREFERENCE> and
+B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in
+OpenSSL 0.9.7.
+
+B<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically
+enabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL>
+and must be explicitly set.
+
+B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e.
+Versions up to OpenSSL 0.9.6c do not include the countermeasure that
+can be disabled with this option (in OpenSSL 0.9.6d, it was always
+enabled).
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_quiet_shutdown.pod b/openssl/doc/ssl/SSL_CTX_set_quiet_shutdown.pod
new file mode 100644
index 000000000..393f8ff0b
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_quiet_shutdown.pod
@@ -0,0 +1,63 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_quiet_shutdown, SSL_CTX_get_quiet_shutdown, SSL_set_quiet_shutdown, SSL_get_quiet_shutdown - manipulate shutdown behaviour
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode);
+ int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx);
+
+ void SSL_set_quiet_shutdown(SSL *ssl, int mode);
+ int SSL_get_quiet_shutdown(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ctx> to be
+B<mode>. SSL objects created from B<ctx> inherit the B<mode> valid at the time
+L<SSL_new(3)|SSL_new(3)> is called. B<mode> may be 0 or 1.
+
+SSL_CTX_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ctx>.
+
+SSL_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ssl> to be
+B<mode>. The setting stays valid until B<ssl> is removed with
+L<SSL_free(3)|SSL_free(3)> or SSL_set_quiet_shutdown() is called again.
+It is not changed when L<SSL_clear(3)|SSL_clear(3)> is called.
+B<mode> may be 0 or 1.
+
+SSL_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ssl>.
+
+=head1 NOTES
+
+Normally when a SSL connection is finished, the parties must send out
+"close notify" alert messages using L<SSL_shutdown(3)|SSL_shutdown(3)>
+for a clean shutdown.
+
+When setting the "quiet shutdown" flag to 1, L<SSL_shutdown(3)|SSL_shutdown(3)>
+will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.
+(L<SSL_shutdown(3)|SSL_shutdown(3)> then behaves like
+L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> called with
+SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.)
+The session is thus considered to be shutdown, but no "close notify" alert
+is sent to the peer. This behaviour violates the TLS standard.
+
+The default is normal shutdown behaviour as described by the TLS standard.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_quiet_shutdown() and SSL_set_quiet_shutdown() do not return
+diagnostic information.
+
+SSL_CTX_get_quiet_shutdown() and SSL_get_quiet_shutdown return the current
+setting.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>,
+L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, L<SSL_new(3)|SSL_new(3)>,
+L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod
new file mode 100644
index 000000000..c5d2f43df
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod
@@ -0,0 +1,137 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode);
+ long SSL_CTX_get_session_cache_mode(SSL_CTX ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_session_cache_mode() enables/disables session caching
+by setting the operational mode for B<ctx> to <mode>.
+
+SSL_CTX_get_session_cache_mode() returns the currently used cache mode.
+
+=head1 NOTES
+
+The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse.
+The sessions can be held in memory for each B<ctx>, if more than one
+SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX
+object.
+
+In order to reuse a session, a client must send the session's id to the
+server. It can only send exactly one id. The server then either
+agrees to reuse the session or it starts a full handshake (to create a new
+session).
+
+A server will lookup up the session in its internal session storage. If the
+session is not found in internal storage or lookups for the internal storage
+have been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try
+the external storage if available.
+
+Since a client may try to reuse a session intended for use in a different
+context, the session id context must be set by the server (see
+L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>).
+
+The following session cache modes and modifiers are available:
+
+=over 4
+
+=item SSL_SESS_CACHE_OFF
+
+No session caching for client or server takes place.
+
+=item SSL_SESS_CACHE_CLIENT
+
+Client sessions are added to the session cache. As there is no reliable way
+for the OpenSSL library to know whether a session should be reused or which
+session to choose (due to the abstract BIO layer the SSL engine does not
+have details about the connection), the application must select the session
+to be reused by using the L<SSL_set_session(3)|SSL_set_session(3)>
+function. This option is not activated by default.
+
+=item SSL_SESS_CACHE_SERVER
+
+Server sessions are added to the session cache. When a client proposes a
+session to be reused, the server looks for the corresponding session in (first)
+the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set),
+then (second) in the external cache if available. If the session is found, the
+server will try to reuse the session. This is the default.
+
+=item SSL_SESS_CACHE_BOTH
+
+Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time.
+
+=item SSL_SESS_CACHE_NO_AUTO_CLEAR
+
+Normally the session cache is checked for expired sessions every
+255 connections using the
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> function. Since
+this may lead to a delay which cannot be controlled, the automatic
+flushing may be disabled and
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> can be called
+explicitly by the application.
+
+=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
+
+By setting this flag, session-resume operations in an SSL/TLS server will not
+automatically look up sessions in the internal cache, even if sessions are
+automatically stored there. If external session caching callbacks are in use,
+this flag guarantees that all lookups are directed to the external cache.
+As automatic lookup only applies for SSL/TLS servers, the flag has no effect on
+clients.
+
+=item SSL_SESS_CACHE_NO_INTERNAL_STORE
+
+Depending on the presence of SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER,
+sessions negotiated in an SSL/TLS handshake may be cached for possible reuse.
+Normally a new session is added to the internal cache as well as any external
+session caching (callback) that is configured for the SSL_CTX. This flag will
+prevent sessions being stored in the internal cache (though the application can
+add them manually using L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>). Note:
+in any SSL/TLS servers where external caching is configured, any successful
+session lookups in the external cache (ie. for session-resume requests) would
+normally be copied into the local cache before processing continues - this flag
+prevents these additions to the internal cache as well.
+
+=item SSL_SESS_CACHE_NO_INTERNAL
+
+Enable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and
+SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time.
+
+
+=back
+
+The default mode is SSL_SESS_CACHE_SERVER.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_session_cache_mode() returns the previously set cache mode.
+
+SSL_CTX_get_session_cache_mode() returns the currently set cache mode.
+
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
+L<SSL_session_reused(3)|SSL_session_reused(3)>,
+L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>,
+L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>,
+L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>,
+L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>,
+L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>,
+L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>,
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>
+
+=head1 HISTORY
+
+SSL_SESS_CACHE_NO_INTERNAL_STORE and SSL_SESS_CACHE_NO_INTERNAL
+were introduced in OpenSSL 0.9.6h.
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod b/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod
new file mode 100644
index 000000000..58fc68550
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod
@@ -0,0 +1,83 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only)
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx,
+ unsigned int sid_ctx_len);
+ int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx,
+ unsigned int sid_ctx_len);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length
+B<sid_ctx_len> within which a session can be reused for the B<ctx> object.
+
+SSL_set_session_id_context() sets the context B<sid_ctx> of length
+B<sid_ctx_len> within which a session can be reused for the B<ssl> object.
+
+=head1 NOTES
+
+Sessions are generated within a certain context. When exporting/importing
+sessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible,
+to re-import a session generated from another context (e.g. another
+application), which might lead to malfunctions. Therefore each application
+must set its own session id context B<sid_ctx> which is used to distinguish
+the contexts and is stored in exported sessions. The B<sid_ctx> can be
+any kind of binary data with a given length, it is therefore possible
+to use e.g. the name of the application and/or the hostname and/or service
+name ...
+
+The session id context becomes part of the session. The session id context
+is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and
+SSL_set_session_id_context() functions are therefore only useful on the
+server side.
+
+OpenSSL clients will check the session id context returned by the server
+when reusing a session.
+
+The maximum length of the B<sid_ctx> is limited to
+B<SSL_MAX_SSL_SESSION_ID_LENGTH>.
+
+=head1 WARNINGS
+
+If the session id context is not set on an SSL/TLS server and client
+certificates are used, stored sessions
+will not be reused but a fatal error will be flagged and the handshake
+will fail.
+
+If a server returns a different session id context to an OpenSSL client
+when reusing a session, an error will be flagged and the handshake will
+fail. OpenSSL servers will always return the correct session id context,
+as an OpenSSL server checks the session id context itself before reusing
+a session as described above.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_session_id_context() and SSL_set_session_id_context()
+return the following values:
+
+=over 4
+
+=item 0
+
+The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded
+the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error
+is logged to the error stack.
+
+=item 1
+
+The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod b/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod
new file mode 100644
index 000000000..002018096
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod
@@ -0,0 +1,61 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method
+- choose a new TLS/SSL method
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_ssl_version(SSL_CTX *ctx, SSL_METHOD *method);
+ int SSL_set_ssl_method(SSL *s, SSL_METHOD *method);
+ SSL_METHOD *SSL_get_ssl_method(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_ssl_version() sets a new default TLS/SSL B<method> for SSL objects
+newly created from this B<ctx>. SSL objects already created with
+L<SSL_new(3)|SSL_new(3)> are not affected, except when
+L<SSL_clear(3)|SSL_clear(3)> is being called.
+
+SSL_set_ssl_method() sets a new TLS/SSL B<method> for a particular B<ssl>
+object. It may be reset, when SSL_clear() is called.
+
+SSL_get_ssl_method() returns a function pointer to the TLS/SSL method
+set in B<ssl>.
+
+=head1 NOTES
+
+The available B<method> choices are described in
+L<SSL_CTX_new(3)|SSL_CTX_new(3)>.
+
+When L<SSL_clear(3)|SSL_clear(3)> is called and no session is connected to
+an SSL object, the method of the SSL object is reset to the method currently
+set in the corresponding SSL_CTX object.
+
+=head1 RETURN VALUES
+
+The following return values can occur for SSL_CTX_set_ssl_version()
+and SSL_set_ssl_method():
+
+=over 4
+
+=item 0
+
+The new choice failed, check the error stack to find out the reason.
+
+=item 1
+
+The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<SSL_new(3)|SSL_new(3)>,
+L<SSL_clear(3)|SSL_clear(3)>, L<ssl(3)|ssl(3)>,
+L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_timeout.pod b/openssl/doc/ssl/SSL_CTX_set_timeout.pod
new file mode 100644
index 000000000..e3de27c47
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_timeout.pod
@@ -0,0 +1,59 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for session caching
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_timeout(SSL_CTX *ctx, long t);
+ long SSL_CTX_get_timeout(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_timeout() sets the timeout for newly created sessions for
+B<ctx> to B<t>. The timeout value B<t> must be given in seconds.
+
+SSL_CTX_get_timeout() returns the currently set timeout value for B<ctx>.
+
+=head1 NOTES
+
+Whenever a new session is created, it is assigned a maximum lifetime. This
+lifetime is specified by storing the creation time of the session and the
+timeout value valid at this time. If the actual time is later than creation
+time plus timeout, the session is not reused.
+
+Due to this realization, all sessions behave according to the timeout value
+valid at the time of the session negotiation. Changes of the timeout value
+do not affect already established sessions.
+
+The expiration time of a single session can be modified using the
+L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)> family of functions.
+
+Expired sessions are removed from the internal session cache, whenever
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> is called, either
+directly by the application or automatically (see
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>)
+
+The default value for session timeout is decided on a per protocol
+basis, see L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>.
+All currently supported protocols have the same default timeout value
+of 300 seconds.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_timeout() returns the previously set timeout value.
+
+SSL_CTX_get_timeout() returns the currently set timeout value.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>,
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>,
+L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
new file mode 100644
index 000000000..29d1f8a6f
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
@@ -0,0 +1,170 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, SSL_set_tmp_dh - handle DH keys for ephemeral key exchange
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx,
+ DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
+ long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh);
+
+ void SSL_set_tmp_dh_callback(SSL_CTX *ctx,
+ DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
+ long SSL_set_tmp_dh(SSL *ssl, DH *dh)
+
+ DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be
+used when a DH parameters are required to B<tmp_dh_callback>.
+The callback is inherited by all B<ssl> objects created from B<ctx>.
+
+SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>.
+The key is inherited by all B<ssl> objects created from B<ctx>.
+
+SSL_set_tmp_dh_callback() sets the callback only for B<ssl>.
+
+SSL_set_tmp_dh() sets the parameters only for B<ssl>.
+
+These functions apply to SSL/TLS servers only.
+
+=head1 NOTES
+
+When using a cipher with RSA authentication, an ephemeral DH key exchange
+can take place. Ciphers with DSA keys always use ephemeral DH keys as well.
+In these cases, the session data are negotiated using the
+ephemeral/temporary DH key and the key supplied and certified
+by the certificate chain is only used for signing.
+Anonymous ciphers (without a permanent server key) also use ephemeral DH keys.
+
+Using ephemeral DH key exchange yields forward secrecy, as the connection
+can only be decrypted, when the DH key is known. By generating a temporary
+DH key inside the server application that is lost when the application
+is left, it becomes impossible for an attacker to decrypt past sessions,
+even if he gets hold of the normal (certified) key, as this key was
+only used for signing.
+
+In order to perform a DH key exchange the server must use a DH group
+(DH parameters) and generate a DH key. The server will always generate a new
+DH key during the negotiation, when the DH parameters are supplied via
+callback and/or when the SSL_OP_SINGLE_DH_USE option of
+L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)> is set. It will
+immediately create a DH key, when DH parameters are supplied via
+SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set. In this case,
+it may happen that a key is generated on initialization without later
+being needed, while on the other hand the computer time during the
+negotiation is being saved.
+
+If "strong" primes were used to generate the DH parameters, it is not strictly
+necessary to generate a new key for each handshake but it does improve forward
+secrecy. If it is not assured, that "strong" primes were used (see especially
+the section about DSA parameters below), SSL_OP_SINGLE_DH_USE must be used
+in order to prevent small subgroup attacks. Always using SSL_OP_SINGLE_DH_USE
+has an impact on the computer time needed during negotiation, but it is not
+very large, so application authors/users should consider to always enable
+this option.
+
+As generating DH parameters is extremely time consuming, an application
+should not generate the parameters on the fly but supply the parameters.
+DH parameters can be reused, as the actual key is newly generated during
+the negotiation. The risk in reusing DH parameters is that an attacker
+may specialize on a very often used DH group. Applications should therefore
+generate their own DH parameters during the installation process using the
+openssl L<dhparam(1)|dhparam(1)> application. In order to reduce the computer
+time needed for this generation, it is possible to use DSA parameters
+instead (see L<dhparam(1)|dhparam(1)>), but in this case SSL_OP_SINGLE_DH_USE
+is mandatory.
+
+Application authors may compile in DH parameters. Files dh512.pem,
+dh1024.pem, dh2048.pem, and dh4096 in the 'apps' directory of current
+version of the OpenSSL distribution contain the 'SKIP' DH parameters,
+which use safe primes and were generated verifiably pseudo-randomly.
+These files can be converted into C code using the B<-C> option of the
+L<dhparam(1)|dhparam(1)> application.
+Authors may also generate their own set of parameters using
+L<dhparam(1)|dhparam(1)>, but a user may not be sure how the parameters were
+generated. The generation of DH parameters during installation is therefore
+recommended.
+
+An application may either directly specify the DH parameters or
+can supply the DH parameters via a callback function. The callback approach
+has the advantage, that the callback may supply DH parameters for different
+key lengths.
+
+The B<tmp_dh_callback> is called with the B<keylength> needed and
+the B<is_export> information. The B<is_export> flag is set, when the
+ephemeral DH key exchange is performed with an export cipher.
+
+=head1 EXAMPLES
+
+Handle DH parameters for key lengths of 512 and 1024 bits. (Error handling
+partly left out.)
+
+ ...
+ /* Set up ephemeral DH stuff */
+ DH *dh_512 = NULL;
+ DH *dh_1024 = NULL;
+ FILE *paramfile;
+
+ ...
+ /* "openssl dhparam -out dh_param_512.pem -2 512" */
+ paramfile = fopen("dh_param_512.pem", "r");
+ if (paramfile) {
+ dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
+ fclose(paramfile);
+ }
+ /* "openssl dhparam -out dh_param_1024.pem -2 1024" */
+ paramfile = fopen("dh_param_1024.pem", "r");
+ if (paramfile) {
+ dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
+ fclose(paramfile);
+ }
+ ...
+
+ /* "openssl dhparam -C -2 512" etc... */
+ DH *get_dh512() { ... }
+ DH *get_dh1024() { ... }
+
+ DH *tmp_dh_callback(SSL *s, int is_export, int keylength)
+ {
+ DH *dh_tmp=NULL;
+
+ switch (keylength) {
+ case 512:
+ if (!dh_512)
+ dh_512 = get_dh512();
+ dh_tmp = dh_512;
+ break;
+ case 1024:
+ if (!dh_1024)
+ dh_1024 = get_dh1024();
+ dh_tmp = dh_1024;
+ break;
+ default:
+ /* Generating a key on the fly is very costly, so use what is there */
+ setup_dh_parameters_like_above();
+ }
+ return(dh_tmp);
+ }
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return
+diagnostic output.
+
+SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
+on failure. Check the error queue to find out the reason of failure.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
+L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
+L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
+L<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod b/openssl/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod
new file mode 100644
index 000000000..534643cd9
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod
@@ -0,0 +1,166 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_tmp_rsa_callback, SSL_CTX_set_tmp_rsa, SSL_CTX_need_tmp_rsa, SSL_set_tmp_rsa_callback, SSL_set_tmp_rsa, SSL_need_tmp_rsa - handle RSA keys for ephemeral key exchange
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx,
+ RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
+ long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa);
+ long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx);
+
+ void SSL_set_tmp_rsa_callback(SSL_CTX *ctx,
+ RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
+ long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa)
+ long SSL_need_tmp_rsa(SSL *ssl)
+
+ RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_tmp_rsa_callback() sets the callback function for B<ctx> to be
+used when a temporary/ephemeral RSA key is required to B<tmp_rsa_callback>.
+The callback is inherited by all SSL objects newly created from B<ctx>
+with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected.
+
+SSL_CTX_set_tmp_rsa() sets the temporary/ephemeral RSA key to be used to be
+B<rsa>. The key is inherited by all SSL objects newly created from B<ctx>
+with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected.
+
+SSL_CTX_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed
+for RSA-based strength-limited 'exportable' ciphersuites because a RSA key
+with a keysize larger than 512 bits is installed.
+
+SSL_set_tmp_rsa_callback() sets the callback only for B<ssl>.
+
+SSL_set_tmp_rsa() sets the key only for B<ssl>.
+
+SSL_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed,
+for RSA-based strength-limited 'exportable' ciphersuites because a RSA key
+with a keysize larger than 512 bits is installed.
+
+These functions apply to SSL/TLS servers only.
+
+=head1 NOTES
+
+When using a cipher with RSA authentication, an ephemeral RSA key exchange
+can take place. In this case the session data are negotiated using the
+ephemeral/temporary RSA key and the RSA key supplied and certified
+by the certificate chain is only used for signing.
+
+Under previous export restrictions, ciphers with RSA keys shorter (512 bits)
+than the usual key length of 1024 bits were created. To use these ciphers
+with RSA keys of usual length, an ephemeral key exchange must be performed,
+as the normal (certified) key cannot be directly used.
+
+Using ephemeral RSA key exchange yields forward secrecy, as the connection
+can only be decrypted, when the RSA key is known. By generating a temporary
+RSA key inside the server application that is lost when the application
+is left, it becomes impossible for an attacker to decrypt past sessions,
+even if he gets hold of the normal (certified) RSA key, as this key was
+used for signing only. The downside is that creating a RSA key is
+computationally expensive.
+
+Additionally, the use of ephemeral RSA key exchange is only allowed in
+the TLS standard, when the RSA key can be used for signing only, that is
+for export ciphers. Using ephemeral RSA key exchange for other purposes
+violates the standard and can break interoperability with clients.
+It is therefore strongly recommended to not use ephemeral RSA key
+exchange and use EDH (Ephemeral Diffie-Hellman) key exchange instead
+in order to achieve forward secrecy (see
+L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
+
+On OpenSSL servers ephemeral RSA key exchange is therefore disabled by default
+and must be explicitly enabled using the SSL_OP_EPHEMERAL_RSA option of
+L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, violating the TLS/SSL
+standard. When ephemeral RSA key exchange is required for export ciphers,
+it will automatically be used without this option!
+
+An application may either directly specify the key or can supply the key via
+a callback function. The callback approach has the advantage, that the
+callback may generate the key only in case it is actually needed. As the
+generation of a RSA key is however costly, it will lead to a significant
+delay in the handshake procedure. Another advantage of the callback function
+is that it can supply keys of different size (e.g. for SSL_OP_EPHEMERAL_RSA
+usage) while the explicit setting of the key is only useful for key size of
+512 bits to satisfy the export restricted ciphers and does give away key length
+if a longer key would be allowed.
+
+The B<tmp_rsa_callback> is called with the B<keylength> needed and
+the B<is_export> information. The B<is_export> flag is set, when the
+ephemeral RSA key exchange is performed with an export cipher.
+
+=head1 EXAMPLES
+
+Generate temporary RSA keys to prepare ephemeral RSA key exchange. As the
+generation of a RSA key costs a lot of computer time, they saved for later
+reuse. For demonstration purposes, two keys for 512 bits and 1024 bits
+respectively are generated.
+
+ ...
+ /* Set up ephemeral RSA stuff */
+ RSA *rsa_512 = NULL;
+ RSA *rsa_1024 = NULL;
+
+ rsa_512 = RSA_generate_key(512,RSA_F4,NULL,NULL);
+ if (rsa_512 == NULL)
+ evaluate_error_queue();
+
+ rsa_1024 = RSA_generate_key(1024,RSA_F4,NULL,NULL);
+ if (rsa_1024 == NULL)
+ evaluate_error_queue();
+
+ ...
+
+ RSA *tmp_rsa_callback(SSL *s, int is_export, int keylength)
+ {
+ RSA *rsa_tmp=NULL;
+
+ switch (keylength) {
+ case 512:
+ if (rsa_512)
+ rsa_tmp = rsa_512;
+ else { /* generate on the fly, should not happen in this example */
+ rsa_tmp = RSA_generate_key(keylength,RSA_F4,NULL,NULL);
+ rsa_512 = rsa_tmp; /* Remember for later reuse */
+ }
+ break;
+ case 1024:
+ if (rsa_1024)
+ rsa_tmp=rsa_1024;
+ else
+ should_not_happen_in_this_example();
+ break;
+ default:
+ /* Generating a key on the fly is very costly, so use what is there */
+ if (rsa_1024)
+ rsa_tmp=rsa_1024;
+ else
+ rsa_tmp=rsa_512; /* Use at least a shorter key */
+ }
+ return(rsa_tmp);
+ }
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_tmp_rsa_callback() and SSL_set_tmp_rsa_callback() do not return
+diagnostic output.
+
+SSL_CTX_set_tmp_rsa() and SSL_set_tmp_rsa() do return 1 on success and 0
+on failure. Check the error queue to find out the reason of failure.
+
+SSL_CTX_need_tmp_rsa() and SSL_need_tmp_rsa() return 1 if a temporary
+RSA key is needed and 0 otherwise.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
+L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
+L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
+L<SSL_new(3)|SSL_new(3)>, L<ciphers(1)|ciphers(1)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_set_verify.pod b/openssl/doc/ssl/SSL_CTX_set_verify.pod
new file mode 100644
index 000000000..81566839d
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_set_verify.pod
@@ -0,0 +1,294 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_verify(SSL_CTX *ctx, int mode,
+ int (*verify_callback)(int, X509_STORE_CTX *));
+ void SSL_set_verify(SSL *s, int mode,
+ int (*verify_callback)(int, X509_STORE_CTX *));
+ void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth);
+ void SSL_set_verify_depth(SSL *s, int depth);
+
+ int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and
+specifies the B<verify_callback> function to be used. If no callback function
+shall be specified, the NULL pointer can be used for B<verify_callback>.
+
+SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and
+specifies the B<verify_callback> function to be used. If no callback function
+shall be specified, the NULL pointer can be used for B<verify_callback>. In
+this case last B<verify_callback> set specifically for this B<ssl> remains. If
+no special B<callback> was set before, the default callback for the underlying
+B<ctx> is used, that was valid at the time B<ssl> was created with
+L<SSL_new(3)|SSL_new(3)>.
+
+SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain
+verification that shall be allowed for B<ctx>. (See the BUGS section.)
+
+SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain
+verification that shall be allowed for B<ssl>. (See the BUGS section.)
+
+=head1 NOTES
+
+The verification of certificates can be controlled by a set of logically
+or'ed B<mode> flags:
+
+=over 4
+
+=item SSL_VERIFY_NONE
+
+B<Server mode:> the server will not send a client certificate request to the
+client, so the client will not send a certificate.
+
+B<Client mode:> if not using an anonymous cipher (by default disabled), the
+server will send a certificate which will be checked. The result of the
+certificate verification process can be checked after the TLS/SSL handshake
+using the L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> function.
+The handshake will be continued regardless of the verification result.
+
+=item SSL_VERIFY_PEER
+
+B<Server mode:> the server sends a client certificate request to the client.
+The certificate returned (if any) is checked. If the verification process
+fails, the TLS/SSL handshake is
+immediately terminated with an alert message containing the reason for
+the verification failure.
+The behaviour can be controlled by the additional
+SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags.
+
+B<Client mode:> the server certificate is verified. If the verification process
+fails, the TLS/SSL handshake is
+immediately terminated with an alert message containing the reason for
+the verification failure. If no server certificate is sent, because an
+anonymous cipher is used, SSL_VERIFY_PEER is ignored.
+
+=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT
+
+B<Server mode:> if the client did not return a certificate, the TLS/SSL
+handshake is immediately terminated with a "handshake failure" alert.
+This flag must be used together with SSL_VERIFY_PEER.
+
+B<Client mode:> ignored
+
+=item SSL_VERIFY_CLIENT_ONCE
+
+B<Server mode:> only request a client certificate on the initial TLS/SSL
+handshake. Do not ask for a client certificate again in case of a
+renegotiation. This flag must be used together with SSL_VERIFY_PEER.
+
+B<Client mode:> ignored
+
+=back
+
+Exactly one of the B<mode> flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be
+set at any time.
+
+The actual verification procedure is performed either using the built-in
+verification procedure or using another application provided verification
+function set with
+L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>.
+The following descriptions apply in the case of the built-in procedure. An
+application provided procedure also has access to the verify depth information
+and the verify_callback() function, but the way this information is used
+may be different.
+
+SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up
+to which depth certificates in a chain are used during the verification
+procedure. If the certificate chain is longer than allowed, the certificates
+above the limit are ignored. Error messages are generated as if these
+certificates would not be present, most likely a
+X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued.
+The depth count is "level 0:peer certificate", "level 1: CA certificate",
+"level 2: higher level CA certificate", and so on. Setting the maximum
+depth to 2 allows the levels 0, 1, and 2. The default depth limit is 9,
+allowing for the peer certificate and additional 9 CA certificates.
+
+The B<verify_callback> function is used to control the behaviour when the
+SSL_VERIFY_PEER flag is set. It must be supplied by the application and
+receives two arguments: B<preverify_ok> indicates, whether the verification of
+the certificate in question was passed (preverify_ok=1) or not
+(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used
+for the certificate chain verification.
+
+The certificate chain is checked starting with the deepest nesting level
+(the root CA certificate) and worked upward to the peer's certificate.
+At each level signatures and issuer attributes are checked. Whenever
+a verification error is found, the error number is stored in B<x509_ctx>
+and B<verify_callback> is called with B<preverify_ok>=0. By applying
+X509_CTX_store_* functions B<verify_callback> can locate the certificate
+in question and perform additional steps (see EXAMPLES). If no error is
+found for a certificate, B<verify_callback> is called with B<preverify_ok>=1
+before advancing to the next level.
+
+The return value of B<verify_callback> controls the strategy of the further
+verification process. If B<verify_callback> returns 0, the verification
+process is immediately stopped with "verification failed" state. If
+SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and
+the TLS/SSL handshake is terminated. If B<verify_callback> returns 1,
+the verification process is continued. If B<verify_callback> always returns
+1, the TLS/SSL handshake will not be terminated with respect to verification
+failures and the connection will be established. The calling process can
+however retrieve the error code of the last verification error using
+L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> or by maintaining its
+own error storage managed by B<verify_callback>.
+
+If no B<verify_callback> is specified, the default callback will be used.
+Its return value is identical to B<preverify_ok>, so that any verification
+failure will lead to a termination of the TLS/SSL handshake with an
+alert message, if SSL_VERIFY_PEER is set.
+
+=head1 BUGS
+
+In client mode, it is not checked whether the SSL_VERIFY_PEER flag
+is set, but whether SSL_VERIFY_NONE is not set. This can lead to
+unexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not
+used as required (exactly one must be set at any time).
+
+The certificate verification depth set with SSL[_CTX]_verify_depth()
+stops the verification at a certain depth. The error message produced
+will be that of an incomplete certificate chain and not
+X509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected.
+
+=head1 RETURN VALUES
+
+The SSL*_set_verify*() functions do not provide diagnostic information.
+
+=head1 EXAMPLES
+
+The following code sequence realizes an example B<verify_callback> function
+that will always continue the TLS/SSL handshake regardless of verification
+failure, if wished. The callback realizes a verification depth limit with
+more informational output.
+
+All verification errors are printed, informations about the certificate chain
+are printed on request.
+The example is realized for a server that does allow but not require client
+certificates.
+
+The example makes use of the ex_data technique to store application data
+into/retrieve application data from the SSL structure
+(see L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>,
+L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
+
+ ...
+ typedef struct {
+ int verbose_mode;
+ int verify_depth;
+ int always_continue;
+ } mydata_t;
+ int mydata_index;
+ ...
+ static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx)
+ {
+ char buf[256];
+ X509 *err_cert;
+ int err, depth;
+ SSL *ssl;
+ mydata_t *mydata;
+
+ err_cert = X509_STORE_CTX_get_current_cert(ctx);
+ err = X509_STORE_CTX_get_error(ctx);
+ depth = X509_STORE_CTX_get_error_depth(ctx);
+
+ /*
+ * Retrieve the pointer to the SSL of the connection currently treated
+ * and the application specific data stored into the SSL object.
+ */
+ ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx());
+ mydata = SSL_get_ex_data(ssl, mydata_index);
+
+ X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256);
+
+ /*
+ * Catch a too long certificate chain. The depth limit set using
+ * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so
+ * that whenever the "depth>verify_depth" condition is met, we
+ * have violated the limit and want to log this error condition.
+ * We must do it here, because the CHAIN_TOO_LONG error would not
+ * be found explicitly; only errors introduced by cutting off the
+ * additional certificates would be logged.
+ */
+ if (depth > mydata->verify_depth) {
+ preverify_ok = 0;
+ err = X509_V_ERR_CERT_CHAIN_TOO_LONG;
+ X509_STORE_CTX_set_error(ctx, err);
+ }
+ if (!preverify_ok) {
+ printf("verify error:num=%d:%s:depth=%d:%s\n", err,
+ X509_verify_cert_error_string(err), depth, buf);
+ }
+ else if (mydata->verbose_mode)
+ {
+ printf("depth=%d:%s\n", depth, buf);
+ }
+
+ /*
+ * At this point, err contains the last verification error. We can use
+ * it for something special
+ */
+ if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT))
+ {
+ X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), buf, 256);
+ printf("issuer= %s\n", buf);
+ }
+
+ if (mydata->always_continue)
+ return 1;
+ else
+ return preverify_ok;
+ }
+ ...
+
+ mydata_t mydata;
+
+ ...
+ mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL);
+
+ ...
+ SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE,
+ verify_callback);
+
+ /*
+ * Let the verify_callback catch the verify_depth error so that we get
+ * an appropriate error in the logfile.
+ */
+ SSL_CTX_set_verify_depth(verify_depth + 1);
+
+ /*
+ * Set up the SSL specific data into "mydata" and store it into th SSL
+ * structure.
+ */
+ mydata.verify_depth = verify_depth; ...
+ SSL_set_ex_data(ssl, mydata_index, &mydata);
+
+ ...
+ SSL_accept(ssl); /* check of success left out for clarity */
+ if (peer = SSL_get_peer_certificate(ssl))
+ {
+ if (SSL_get_verify_result(ssl) == X509_V_OK)
+ {
+ /* The client sent a certificate which verified OK */
+ }
+ }
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>,
+L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>,
+L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,
+L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>,
+L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>,
+L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
+L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_CTX_use_certificate.pod b/openssl/doc/ssl/SSL_CTX_use_certificate.pod
new file mode 100644
index 000000000..10be95fdb
--- /dev/null
+++ b/openssl/doc/ssl/SSL_CTX_use_certificate.pod
@@ -0,0 +1,169 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1, SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file, SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey, SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key - load certificate and key data
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
+ int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);
+ int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);
+ int SSL_use_certificate(SSL *ssl, X509 *x);
+ int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len);
+ int SSL_use_certificate_file(SSL *ssl, const char *file, int type);
+
+ int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);
+
+ int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
+ int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d,
+ long len);
+ int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);
+ int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);
+ int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);
+ int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);
+ int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);
+ int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len);
+ int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);
+ int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);
+ int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);
+ int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);
+
+ int SSL_CTX_check_private_key(const SSL_CTX *ctx);
+ int SSL_check_private_key(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+These functions load the certificates and private keys into the SSL_CTX
+or SSL object, respectively.
+
+The SSL_CTX_* class of functions loads the certificates and keys into the
+SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl>
+created from B<ctx> with L<SSL_new(3)|SSL_new(3)> by copying, so that
+changes applied to B<ctx> do not propagate to already existing SSL objects.
+
+The SSL_* class of functions only loads certificates and keys into a
+specific SSL object. The specific information is kept, when
+L<SSL_clear(3)|SSL_clear(3)> is called for this SSL object.
+
+SSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>,
+SSL_use_certificate() loads B<x> into B<ssl>. The rest of the
+certificates needed to form the complete certificate chain can be
+specified using the
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
+function.
+
+SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from
+the memory location B<d> (with length B<len>) into B<ctx>,
+SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>.
+
+SSL_CTX_use_certificate_file() loads the first certificate stored in B<file>
+into B<ctx>. The formatting B<type> of the certificate must be specified
+from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
+SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>.
+See the NOTES section on why SSL_CTX_use_certificate_chain_file()
+should be preferred.
+
+SSL_CTX_use_certificate_chain_file() loads a certificate chain from
+B<file> into B<ctx>. The certificates must be in PEM format and must
+be sorted starting with the subject's certificate (actual client or server
+certificate), followed by intermediate CA certificates if applicable, and
+ending at the highest level (root) CA.
+There is no corresponding function working on a single SSL object.
+
+SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>.
+SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA
+to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>;
+SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>.
+If a certificate has already been set and the private does not belong
+to the certificate an error is returned. To change a certificate, private
+key pair the new certificate needs to be set with SSL_use_certificate()
+or SSL_CTX_use_certificate() before setting the private key with
+SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey().
+
+
+SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk>
+stored at memory location B<d> (length B<len>) to B<ctx>.
+SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA
+stored at memory location B<d> (length B<len>) to B<ctx>.
+SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private
+key to B<ssl>.
+
+SSL_CTX_use_PrivateKey_file() adds the first private key found in
+B<file> to B<ctx>. The formatting B<type> of the certificate must be specified
+from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
+SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in
+B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found
+in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private
+RSA key found to B<ssl>.
+
+SSL_CTX_check_private_key() checks the consistency of a private key with
+the corresponding certificate loaded into B<ctx>. If more than one
+key/certificate pair (RSA/DSA) is installed, the last item installed will
+be checked. If e.g. the last item was a RSA certificate or key, the RSA
+key/certificate pair will be checked. SSL_check_private_key() performs
+the same check for B<ssl>. If no key/certificate was explicitly added for
+this B<ssl>, the last item added into B<ctx> will be checked.
+
+=head1 NOTES
+
+The internal certificate store of OpenSSL can hold two private key/certificate
+pairs at a time: one key/certificate of type RSA and one key/certificate
+of type DSA. The certificate used depends on the cipher select, see
+also L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>.
+
+When reading certificates and private keys from file, files of type
+SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain
+one certificate or private key, consequently
+SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting.
+Files of type SSL_FILETYPE_PEM can contain more than one item.
+
+SSL_CTX_use_certificate_chain_file() adds the first certificate found
+in the file to the certificate store. The other certificates are added
+to the store of chain certificates using
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>.
+There exists only one extra chain store, so that the same chain is appended
+to both types of certificates, RSA and DSA! If it is not intended to use
+both type of certificate at the same time, it is recommended to use the
+SSL_CTX_use_certificate_chain_file() instead of the
+SSL_CTX_use_certificate_file() function in order to allow the use of
+complete certificate chains even when no trusted CA storage is used or
+when the CA issuing the certificate shall not be added to the trusted
+CA storage.
+
+If additional certificates are needed to complete the chain during the
+TLS negotiation, CA certificates are additionally looked up in the
+locations of trusted CA certificates, see
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.
+
+The private keys loaded from file can be encrypted. In order to successfully
+load encrypted keys, a function returning the passphrase must have been
+supplied, see
+L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>.
+(Certificate files might be encrypted as well from the technical point
+of view, it however does not make sense as the data in the certificate
+is considered public anyway.)
+
+=head1 RETURN VALUES
+
+On success, the functions return 1.
+Otherwise check out the error stack to find out the reason.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,
+L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>,
+L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
+L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
+
+=head1 HISTORY
+
+Support for DER encoded private keys (SSL_FILETYPE_ASN1) in
+SSL_CTX_use_PrivateKey_file() and SSL_use_PrivateKey_file() was added
+in 0.9.8 .
+
+=cut
diff --git a/openssl/doc/ssl/SSL_SESSION_free.pod b/openssl/doc/ssl/SSL_SESSION_free.pod
new file mode 100644
index 000000000..110ec73ab
--- /dev/null
+++ b/openssl/doc/ssl/SSL_SESSION_free.pod
@@ -0,0 +1,55 @@
+=pod
+
+=head1 NAME
+
+SSL_SESSION_free - free an allocated SSL_SESSION structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_SESSION_free(SSL_SESSION *session);
+
+=head1 DESCRIPTION
+
+SSL_SESSION_free() decrements the reference count of B<session> and removes
+the B<SSL_SESSION> structure pointed to by B<session> and frees up the allocated
+memory, if the reference count has reached 0.
+
+=head1 NOTES
+
+SSL_SESSION objects are allocated, when a TLS/SSL handshake operation
+is successfully completed. Depending on the settings, see
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
+the SSL_SESSION objects are internally referenced by the SSL_CTX and
+linked into its session cache. SSL objects may be using the SSL_SESSION object;
+as a session may be reused, several SSL objects may be using one SSL_SESSION
+object at the same time. It is therefore crucial to keep the reference
+count (usage information) correct and not delete a SSL_SESSION object
+that is still used, as this may lead to program failures due to
+dangling pointers. These failures may also appear delayed, e.g.
+when an SSL_SESSION object was completely freed as the reference count
+incorrectly became 0, but it is still referenced in the internal
+session cache and the cache list is processed during a
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> operation.
+
+SSL_SESSION_free() must only be called for SSL_SESSION objects, for
+which the reference count was explicitly incremented (e.g.
+by calling SSL_get1_session(), see L<SSL_get_session(3)|SSL_get_session(3)>)
+or when the SSL_SESSION object was generated outside a TLS handshake
+operation, e.g. by using L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>.
+It must not be called on other SSL_SESSION objects, as this would cause
+incorrect reference counts and therefore program failures.
+
+=head1 RETURN VALUES
+
+SSL_SESSION_free() does not provide diagnostic information.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_get_session(3)|SSL_get_session(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>,
+ L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_SESSION_get_ex_new_index.pod b/openssl/doc/ssl/SSL_SESSION_get_ex_new_index.pod
new file mode 100644
index 000000000..657cda931
--- /dev/null
+++ b/openssl/doc/ssl/SSL_SESSION_get_ex_new_index.pod
@@ -0,0 +1,61 @@
+=pod
+
+=head1 NAME
+
+SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data - internal application specific data functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_SESSION_get_ex_new_index(long argl, void *argp,
+ CRYPTO_EX_new *new_func,
+ CRYPTO_EX_dup *dup_func,
+ CRYPTO_EX_free *free_func);
+
+ int SSL_SESSION_set_ex_data(SSL_SESSION *session, int idx, void *arg);
+
+ void *SSL_SESSION_get_ex_data(const SSL_SESSION *session, int idx);
+
+ typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
+ int idx, long argl, void *argp);
+ typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
+ int idx, long argl, void *argp);
+ typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
+ int idx, long argl, void *argp);
+
+=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.
+
+SSL_SESSION_get_ex_new_index() is used to register a new index for application
+specific data.
+
+SSL_SESSION_set_ex_data() is used to store application data at B<arg> for B<idx>
+into the B<session> object.
+
+SSL_SESSION_get_ex_data() is used to retrieve the information for B<idx> from
+B<session>.
+
+A detailed description for the B<*_get_ex_new_index()> functionality
+can be found in L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>.
+The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in
+L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>.
+
+=head1 WARNINGS
+
+The application data is only maintained for sessions held in memory. The
+application data is not included when dumping the session with
+i2d_SSL_SESSION() (and all functions indirectly calling the dump functions
+like PEM_write_SSL_SESSION() and PEM_write_bio_SSL_SESSION()) and can
+therefore not be restored.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
+L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_SESSION_get_time.pod b/openssl/doc/ssl/SSL_SESSION_get_time.pod
new file mode 100644
index 000000000..490337a32
--- /dev/null
+++ b/openssl/doc/ssl/SSL_SESSION_get_time.pod
@@ -0,0 +1,64 @@
+=pod
+
+=head1 NAME
+
+SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, SSL_SESSION_set_timeout - retrieve and manipulate session time and timeout settings
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_SESSION_get_time(const SSL_SESSION *s);
+ long SSL_SESSION_set_time(SSL_SESSION *s, long tm);
+ long SSL_SESSION_get_timeout(const SSL_SESSION *s);
+ long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm);
+
+ long SSL_get_time(const SSL_SESSION *s);
+ long SSL_set_time(SSL_SESSION *s, long tm);
+ long SSL_get_timeout(const SSL_SESSION *s);
+ long SSL_set_timeout(SSL_SESSION *s, long tm);
+
+=head1 DESCRIPTION
+
+SSL_SESSION_get_time() returns the time at which the session B<s> was
+established. The time is given in seconds since the Epoch and therefore
+compatible to the time delivered by the time() call.
+
+SSL_SESSION_set_time() replaces the creation time of the session B<s> with
+the chosen value B<tm>.
+
+SSL_SESSION_get_timeout() returns the timeout value set for session B<s>
+in seconds.
+
+SSL_SESSION_set_timeout() sets the timeout value for session B<s> in seconds
+to B<tm>.
+
+The SSL_get_time(), SSL_set_time(), SSL_get_timeout(), and SSL_set_timeout()
+functions are synonyms for the SSL_SESSION_*() counterparts.
+
+=head1 NOTES
+
+Sessions are expired by examining the creation time and the timeout value.
+Both are set at creation time of the session to the actual time and the
+default timeout value at creation, respectively, as set by
+L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>.
+Using these functions it is possible to extend or shorten the lifetime
+of the session.
+
+=head1 RETURN VALUES
+
+SSL_SESSION_get_time() and SSL_SESSION_get_timeout() return the currently
+valid values.
+
+SSL_SESSION_set_time() and SSL_SESSION_set_timeout() return 1 on success.
+
+If any of the function is passed the NULL pointer for the session B<s>,
+0 is returned.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>,
+L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_accept.pod b/openssl/doc/ssl/SSL_accept.pod
new file mode 100644
index 000000000..cc724c0d5
--- /dev/null
+++ b/openssl/doc/ssl/SSL_accept.pod
@@ -0,0 +1,76 @@
+=pod
+
+=head1 NAME
+
+SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_accept(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_accept() waits for a TLS/SSL client to initiate the TLS/SSL handshake.
+The communication channel must already have been set and assigned to the
+B<ssl> by setting an underlying B<BIO>.
+
+=head1 NOTES
+
+The behaviour of SSL_accept() depends on the underlying BIO.
+
+If the underlying BIO is B<blocking>, SSL_accept() will only return once the
+handshake has been finished or an error occurred, except for SGC (Server
+Gated Cryptography). For SGC, SSL_accept() may return with -1, but
+SSL_get_error() will yield B<SSL_ERROR_WANT_READ/WRITE> and SSL_accept()
+should be called again.
+
+If the underlying BIO is B<non-blocking>, SSL_accept() will also return
+when the underlying BIO could not satisfy the needs of SSL_accept()
+to continue the handshake, indicating the problem by the return value -1.
+In this case a call to SSL_get_error() with the
+return value of SSL_accept() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
+taking appropriate action to satisfy the needs of SSL_accept().
+The action depends on the underlying BIO. When using a non-blocking socket,
+nothing is to be done, but select() can be used to check for the required
+condition. When using a buffering BIO, like a BIO pair, data must be written
+into or retrieved out of the BIO before being able to continue.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 1
+
+The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been
+established.
+
+=item 0
+
+The TLS/SSL handshake was not successful but was shut down controlled and
+by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
+return value B<ret> to find out the reason.
+
+=item E<lt>0
+
+The TLS/SSL handshake was not successful because a fatal error occurred either
+at the protocol level or a connection failure occurred. The shutdown was
+not clean. It can also occur of action is need to continue the operation
+for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
+to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
+L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
+L<SSL_do_handshake(3)|SSL_do_handshake(3)>,
+L<SSL_CTX_new(3)|SSL_CTX_new(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_alert_type_string.pod b/openssl/doc/ssl/SSL_alert_type_string.pod
new file mode 100644
index 000000000..94e28cc30
--- /dev/null
+++ b/openssl/doc/ssl/SSL_alert_type_string.pod
@@ -0,0 +1,228 @@
+=pod
+
+=head1 NAME
+
+SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_alert_type_string(int value);
+ const char *SSL_alert_type_string_long(int value);
+
+ const char *SSL_alert_desc_string(int value);
+ const char *SSL_alert_desc_string_long(int value);
+
+=head1 DESCRIPTION
+
+SSL_alert_type_string() returns a one letter string indicating the
+type of the alert specified by B<value>.
+
+SSL_alert_type_string_long() returns a string indicating the type of the alert
+specified by B<value>.
+
+SSL_alert_desc_string() returns a two letter string as a short form
+describing the reason of the alert specified by B<value>.
+
+SSL_alert_desc_string_long() returns a string describing the reason
+of the alert specified by B<value>.
+
+=head1 NOTES
+
+When one side of an SSL/TLS communication wants to inform the peer about
+a special situation, it sends an alert. The alert is sent as a special message
+and does not influence the normal data stream (unless its contents results
+in the communication being canceled).
+
+A warning alert is sent, when a non-fatal error condition occurs. The
+"close notify" alert is sent as a warning alert. Other examples for
+non-fatal errors are certificate errors ("certificate expired",
+"unsupported certificate"), for which a warning alert may be sent.
+(The sending party may however decide to send a fatal error.) The
+receiving side may cancel the connection on reception of a warning
+alert on it discretion.
+
+Several alert messages must be sent as fatal alert messages as specified
+by the TLS RFC. A fatal alert always leads to a connection abort.
+
+=head1 RETURN VALUES
+
+The following strings can occur for SSL_alert_type_string() or
+SSL_alert_type_string_long():
+
+=over 4
+
+=item "W"/"warning"
+
+=item "F"/"fatal"
+
+=item "U"/"unknown"
+
+This indicates that no support is available for this alert type.
+Probably B<value> does not contain a correct alert message.
+
+=back
+
+The following strings can occur for SSL_alert_desc_string() or
+SSL_alert_desc_string_long():
+
+=over 4
+
+=item "CN"/"close notify"
+
+The connection shall be closed. This is a warning alert.
+
+=item "UM"/"unexpected message"
+
+An inappropriate message was received. This alert is always fatal
+and should never be observed in communication between proper
+implementations.
+
+=item "BM"/"bad record mac"
+
+This alert is returned if a record is received with an incorrect
+MAC. This message is always fatal.
+
+=item "DF"/"decompression failure"
+
+The decompression function received improper input (e.g. data
+that would expand to excessive length). This message is always
+fatal.
+
+=item "HF"/"handshake failure"
+
+Reception of a handshake_failure alert message indicates that the
+sender was unable to negotiate an acceptable set of security
+parameters given the options available. This is a fatal error.
+
+=item "NC"/"no certificate"
+
+A client, that was asked to send a certificate, does not send a certificate
+(SSLv3 only).
+
+=item "BC"/"bad certificate"
+
+A certificate was corrupt, contained signatures that did not
+verify correctly, etc
+
+=item "UC"/"unsupported certificate"
+
+A certificate was of an unsupported type.
+
+=item "CR"/"certificate revoked"
+
+A certificate was revoked by its signer.
+
+=item "CE"/"certificate expired"
+
+A certificate has expired or is not currently valid.
+
+=item "CU"/"certificate unknown"
+
+Some other (unspecified) issue arose in processing the
+certificate, rendering it unacceptable.
+
+=item "IP"/"illegal parameter"
+
+A field in the handshake was out of range or inconsistent with
+other fields. This is always fatal.
+
+=item "DC"/"decryption failed"
+
+A TLSCiphertext decrypted in an invalid way: either it wasn't an
+even multiple of the block length or its padding values, when
+checked, weren't correct. This message is always fatal.
+
+=item "RO"/"record overflow"
+
+A TLSCiphertext record was received which had a length more than
+2^14+2048 bytes, or a record decrypted to a TLSCompressed record
+with more than 2^14+1024 bytes. This message is always fatal.
+
+=item "CA"/"unknown CA"
+
+A valid certificate chain or partial chain was received, but the
+certificate was not accepted because the CA certificate could not
+be located or couldn't be matched with a known, trusted CA. This
+message is always fatal.
+
+=item "AD"/"access denied"
+
+A valid certificate was received, but when access control was
+applied, the sender decided not to proceed with negotiation.
+This message is always fatal.
+
+=item "DE"/"decode error"
+
+A message could not be decoded because some field was out of the
+specified range or the length of the message was incorrect. This
+message is always fatal.
+
+=item "CY"/"decrypt error"
+
+A handshake cryptographic operation failed, including being
+unable to correctly verify a signature, decrypt a key exchange,
+or validate a finished message.
+
+=item "ER"/"export restriction"
+
+A negotiation not in compliance with export restrictions was
+detected; for example, attempting to transfer a 1024 bit
+ephemeral RSA key for the RSA_EXPORT handshake method. This
+message is always fatal.
+
+=item "PV"/"protocol version"
+
+The protocol version the client has attempted to negotiate is
+recognized, but not supported. (For example, old protocol
+versions might be avoided for security reasons). This message is
+always fatal.
+
+=item "IS"/"insufficient security"
+
+Returned instead of handshake_failure when a negotiation has
+failed specifically because the server requires ciphers more
+secure than those supported by the client. This message is always
+fatal.
+
+=item "IE"/"internal error"
+
+An internal error unrelated to the peer or the correctness of the
+protocol makes it impossible to continue (such as a memory
+allocation failure). This message is always fatal.
+
+=item "US"/"user canceled"
+
+This handshake is being canceled for some reason unrelated to a
+protocol failure. If the user cancels an operation after the
+handshake is complete, just closing the connection by sending a
+close_notify is more appropriate. This alert should be followed
+by a close_notify. This message is generally a warning.
+
+=item "NR"/"no renegotiation"
+
+Sent by the client in response to a hello request or by the
+server in response to a client hello after initial handshaking.
+Either of these would normally lead to renegotiation; when that
+is not appropriate, the recipient should respond with this alert;
+at that point, the original requester can decide whether to
+proceed with the connection. One case where this would be
+appropriate would be where a server has spawned a process to
+satisfy a request; the process might receive security parameters
+(key length, authentication, etc.) at startup and it might be
+difficult to communicate changes to these parameters after that
+point. This message is always a warning.
+
+=item "UK"/"unknown"
+
+This indicates that no description is available for this alert type.
+Probably B<value> does not contain a correct alert message.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_clear.pod b/openssl/doc/ssl/SSL_clear.pod
new file mode 100644
index 000000000..8e077e31c
--- /dev/null
+++ b/openssl/doc/ssl/SSL_clear.pod
@@ -0,0 +1,69 @@
+=pod
+
+=head1 NAME
+
+SSL_clear - reset SSL object to allow another connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_clear(SSL *ssl);
+
+=head1 DESCRIPTION
+
+Reset B<ssl> to allow another connection. All settings (method, ciphers,
+BIOs) are kept.
+
+=head1 NOTES
+
+SSL_clear is used to prepare an SSL object for a new connection. While all
+settings are kept, a side effect is the handling of the current SSL session.
+If a session is still B<open>, it is considered bad and will be removed
+from the session cache, as required by RFC2246. A session is considered open,
+if L<SSL_shutdown(3)|SSL_shutdown(3)> was not called for the connection
+or at least L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> was used to
+set the SSL_SENT_SHUTDOWN state.
+
+If a session was closed cleanly, the session object will be kept and all
+settings corresponding. This explicitly means, that e.g. the special method
+used during the session will be kept for the next handshake. So if the
+session was a TLSv1 session, a SSL client object will use a TLSv1 client
+method for the next handshake and a SSL server object will use a TLSv1
+server method, even if SSLv23_*_methods were chosen on startup. This
+will might lead to connection failures (see L<SSL_new(3)|SSL_new(3)>)
+for a description of the method's properties.
+
+=head1 WARNINGS
+
+SSL_clear() resets the SSL object to allow for another connection. The
+reset operation however keeps several settings of the last sessions
+(some of these settings were made automatically during the last
+handshake). It only makes sense when opening a new session (or reusing
+an old one) with the same peer that shares these settings.
+SSL_clear() is not a short form for the sequence
+L<SSL_free(3)|SSL_free(3)>; L<SSL_new(3)|SSL_new(3)>; .
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 0
+
+The SSL_clear() operation could not be performed. Check the error stack to
+find out the reason.
+
+=item 1
+
+The SSL_clear() operation was successful.
+
+=back
+
+L<SSL_new(3)|SSL_new(3)>, L<SSL_free(3)|SSL_free(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
+L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, L<ssl(3)|ssl(3)>,
+L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_connect.pod b/openssl/doc/ssl/SSL_connect.pod
new file mode 100644
index 000000000..cc56ebb75
--- /dev/null
+++ b/openssl/doc/ssl/SSL_connect.pod
@@ -0,0 +1,73 @@
+=pod
+
+=head1 NAME
+
+SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_connect(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_connect() initiates the TLS/SSL handshake with a server. The communication
+channel must already have been set and assigned to the B<ssl> by setting an
+underlying B<BIO>.
+
+=head1 NOTES
+
+The behaviour of SSL_connect() depends on the underlying BIO.
+
+If the underlying BIO is B<blocking>, SSL_connect() will only return once the
+handshake has been finished or an error occurred.
+
+If the underlying BIO is B<non-blocking>, SSL_connect() will also return
+when the underlying BIO could not satisfy the needs of SSL_connect()
+to continue the handshake, indicating the problem by the return value -1.
+In this case a call to SSL_get_error() with the
+return value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
+taking appropriate action to satisfy the needs of SSL_connect().
+The action depends on the underlying BIO. When using a non-blocking socket,
+nothing is to be done, but select() can be used to check for the required
+condition. When using a buffering BIO, like a BIO pair, data must be written
+into or retrieved out of the BIO before being able to continue.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 1
+
+The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been
+established.
+
+=item 0
+
+The TLS/SSL handshake was not successful but was shut down controlled and
+by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
+return value B<ret> to find out the reason.
+
+=item E<lt>0
+
+The TLS/SSL handshake was not successful, because a fatal error occurred either
+at the protocol level or a connection failure occurred. The shutdown was
+not clean. It can also occur of action is need to continue the operation
+for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
+to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
+L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
+L<SSL_do_handshake(3)|SSL_do_handshake(3)>,
+L<SSL_CTX_new(3)|SSL_CTX_new(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_do_handshake.pod b/openssl/doc/ssl/SSL_do_handshake.pod
new file mode 100644
index 000000000..243576451
--- /dev/null
+++ b/openssl/doc/ssl/SSL_do_handshake.pod
@@ -0,0 +1,75 @@
+=pod
+
+=head1 NAME
+
+SSL_do_handshake - perform a TLS/SSL handshake
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_do_handshake(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the
+connection is in client mode, the handshake will be started. The handshake
+routines may have to be explicitly set in advance using either
+L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or
+L<SSL_set_accept_state(3)|SSL_set_accept_state(3)>.
+
+=head1 NOTES
+
+The behaviour of SSL_do_handshake() depends on the underlying BIO.
+
+If the underlying BIO is B<blocking>, SSL_do_handshake() will only return
+once the handshake has been finished or an error occurred, except for SGC
+(Server Gated Cryptography). For SGC, SSL_do_handshake() may return with -1,
+but SSL_get_error() will yield B<SSL_ERROR_WANT_READ/WRITE> and
+SSL_do_handshake() should be called again.
+
+If the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return
+when the underlying BIO could not satisfy the needs of SSL_do_handshake()
+to continue the handshake. In this case a call to SSL_get_error() with the
+return value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
+taking appropriate action to satisfy the needs of SSL_do_handshake().
+The action depends on the underlying BIO. When using a non-blocking socket,
+nothing is to be done, but select() can be used to check for the required
+condition. When using a buffering BIO, like a BIO pair, data must be written
+into or retrieved out of the BIO before being able to continue.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 1
+
+The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been
+established.
+
+=item 0
+
+The TLS/SSL handshake was not successful but was shut down controlled and
+by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
+return value B<ret> to find out the reason.
+
+=item E<lt>0
+
+The TLS/SSL handshake was not successful because a fatal error occurred either
+at the protocol level or a connection failure occurred. The shutdown was
+not clean. It can also occur of action is need to continue the operation
+for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
+to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>,
+L<SSL_accept(3)|SSL_accept(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
+L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_free.pod b/openssl/doc/ssl/SSL_free.pod
new file mode 100644
index 000000000..13c1abd9e
--- /dev/null
+++ b/openssl/doc/ssl/SSL_free.pod
@@ -0,0 +1,44 @@
+=pod
+
+=head1 NAME
+
+SSL_free - free an allocated SSL structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_free(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_free() decrements the reference count of B<ssl>, and removes the SSL
+structure pointed to by B<ssl> and frees up the allocated memory if the
+reference count has reached 0.
+
+=head1 NOTES
+
+SSL_free() also calls the free()ing procedures for indirectly affected items, if
+applicable: the buffering BIO, the read and write BIOs,
+cipher lists specially created for this B<ssl>, the B<SSL_SESSION>.
+Do not explicitly free these indirectly freed up items before or after
+calling SSL_free(), as trying to free things twice may lead to program
+failure.
+
+The ssl session has reference counts from two users: the SSL object, for
+which the reference count is removed by SSL_free() and the internal
+session cache. If the session is considered bad, because
+L<SSL_shutdown(3)|SSL_shutdown(3)> was not called for the connection
+and L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> was not used to set the
+SSL_SENT_SHUTDOWN state, the session will also be removed
+from the session cache as required by RFC2246.
+
+=head1 RETURN VALUES
+
+SSL_free() does not provide diagnostic information.
+
+L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
+L<ssl(3)|ssl(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_SSL_CTX.pod b/openssl/doc/ssl/SSL_get_SSL_CTX.pod
new file mode 100644
index 000000000..659c482c7
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_SSL_CTX.pod
@@ -0,0 +1,26 @@
+=pod
+
+=head1 NAME
+
+SSL_get_SSL_CTX - get the SSL_CTX from which an SSL is created
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_SSL_CTX() returns a pointer to the SSL_CTX object, from which
+B<ssl> was created with L<SSL_new(3)|SSL_new(3)>.
+
+=head1 RETURN VALUES
+
+The pointer to the SSL_CTX object is returned.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_ciphers.pod b/openssl/doc/ssl/SSL_get_ciphers.pod
new file mode 100644
index 000000000..aecadd913
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_ciphers.pod
@@ -0,0 +1,42 @@
+=pod
+
+=head1 NAME
+
+SSL_get_ciphers, SSL_get_cipher_list - get list of available SSL_CIPHERs
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl);
+ const char *SSL_get_cipher_list(const SSL *ssl, int priority);
+
+=head1 DESCRIPTION
+
+SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B<ssl>,
+sorted by preference. If B<ssl> is NULL or no ciphers are available, NULL
+is returned.
+
+SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER
+listed for B<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are
+available, or there are less ciphers than B<priority> available, NULL
+is returned.
+
+=head1 NOTES
+
+The details of the ciphers obtained by SSL_get_ciphers() can be obtained using
+the L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> family of functions.
+
+Call SSL_get_cipher_list() with B<priority> starting from 0 to obtain the
+sorted list of available ciphers, until NULL is returned.
+
+=head1 RETURN VALUES
+
+See DESCRIPTION
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
+L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_client_CA_list.pod b/openssl/doc/ssl/SSL_get_client_CA_list.pod
new file mode 100644
index 000000000..68181b240
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_client_CA_list.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
+ STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for
+B<ctx> using L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>.
+
+SSL_get_client_CA_list() returns the list of client CAs explicitly
+set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with
+L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, when in
+server mode. In client mode, SSL_get_client_CA_list returns the list of
+client CAs sent from the server, if any.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
+diagnostic information.
+
+SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
+values:
+
+=over 4
+
+=item STACK_OF(X509_NAMES)
+
+List of CA names explicitly set (for B<ctx> or in server mode) or send
+by the server (client mode).
+
+=item NULL
+
+No client CA list was explicitly set (for B<ctx> or in server mode) or
+the server did not send a list of CAs (client mode).
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,
+L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_current_cipher.pod b/openssl/doc/ssl/SSL_get_current_cipher.pod
new file mode 100644
index 000000000..e5ab12491
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_current_cipher.pod
@@ -0,0 +1,43 @@
+=pod
+
+=head1 NAME
+
+SSL_get_current_cipher, SSL_get_cipher, SSL_get_cipher_name,
+SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl);
+ #define SSL_get_cipher(s) \
+ SSL_CIPHER_get_name(SSL_get_current_cipher(s))
+ #define SSL_get_cipher_name(s) \
+ SSL_CIPHER_get_name(SSL_get_current_cipher(s))
+ #define SSL_get_cipher_bits(s,np) \
+ SSL_CIPHER_get_bits(SSL_get_current_cipher(s),np)
+ #define SSL_get_cipher_version(s) \
+ SSL_CIPHER_get_version(SSL_get_current_cipher(s))
+
+=head1 DESCRIPTION
+
+SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing
+the description of the actually used cipher of a connection established with
+the B<ssl> object.
+
+SSL_get_cipher() and SSL_get_cipher_name() are identical macros to obtain the
+name of the currently used cipher. SSL_get_cipher_bits() is a
+macro to obtain the number of secret/algorithm bits used and
+SSL_get_cipher_version() returns the protocol name.
+See L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> for more details.
+
+=head1 RETURN VALUES
+
+SSL_get_current_cipher() returns the cipher actually used or NULL, when
+no session has been established.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_default_timeout.pod b/openssl/doc/ssl/SSL_get_default_timeout.pod
new file mode 100644
index 000000000..a648a9b82
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_default_timeout.pod
@@ -0,0 +1,41 @@
+=pod
+
+=head1 NAME
+
+SSL_get_default_timeout - get default session timeout value
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_get_default_timeout(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_default_timeout() returns the default timeout value assigned to
+SSL_SESSION objects negotiated for the protocol valid for B<ssl>.
+
+=head1 NOTES
+
+Whenever a new session is negotiated, it is assigned a timeout value,
+after which it will not be accepted for session reuse. If the timeout
+value was not explicitly set using
+L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, the hardcoded default
+timeout for the protocol will be used.
+
+SSL_get_default_timeout() return this hardcoded value, which is 300 seconds
+for all currently supported protocols (SSLv2, SSLv3, and TLSv1).
+
+=head1 RETURN VALUES
+
+See description.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>,
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>,
+L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_error.pod b/openssl/doc/ssl/SSL_get_error.pod
new file mode 100644
index 000000000..48c6b15db
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_error.pod
@@ -0,0 +1,114 @@
+=pod
+
+=head1 NAME
+
+SSL_get_error - obtain result code for TLS/SSL I/O operation
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_get_error(const SSL *ssl, int ret);
+
+=head1 DESCRIPTION
+
+SSL_get_error() returns a result code (suitable for the C "switch"
+statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(),
+SSL_read(), SSL_peek(), or SSL_write() on B<ssl>. The value returned by
+that TLS/SSL I/O function must be passed to SSL_get_error() in parameter
+B<ret>.
+
+In addition to B<ssl> and B<ret>, SSL_get_error() inspects the
+current thread's OpenSSL error queue. Thus, SSL_get_error() must be
+used in the same thread that performed the TLS/SSL I/O operation, and no
+other OpenSSL function calls should appear in between. The current
+thread's error queue must be empty before the TLS/SSL I/O operation is
+attempted, or SSL_get_error() will not work reliably.
+
+=head1 RETURN VALUES
+
+The following return values can currently occur:
+
+=over 4
+
+=item SSL_ERROR_NONE
+
+The TLS/SSL I/O operation completed. This result code is returned
+if and only if B<ret E<gt> 0>.
+
+=item SSL_ERROR_ZERO_RETURN
+
+The TLS/SSL connection has been closed. If the protocol version is SSL 3.0
+or TLS 1.0, this result code is returned only if a closure
+alert has occurred in the protocol, i.e. if the connection has been
+closed cleanly. Note that in this case B<SSL_ERROR_ZERO_RETURN>
+does not necessarily indicate that the underlying transport
+has been closed.
+
+=item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
+
+The operation did not complete; the same TLS/SSL I/O function should be
+called again later. If, by then, the underlying B<BIO> has data
+available for reading (if the result code is B<SSL_ERROR_WANT_READ>)
+or allows writing data (B<SSL_ERROR_WANT_WRITE>), then some TLS/SSL
+protocol progress will take place, i.e. at least part of an TLS/SSL
+record will be read or written. Note that the retry may again lead to
+a B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE> condition.
+There is no fixed upper limit for the number of iterations that
+may be necessary until progress becomes visible at application
+protocol level.
+
+For socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or
+poll() on the underlying socket can be used to find out when the
+TLS/SSL I/O function should be retried.
+
+Caveat: Any TLS/SSL I/O function can lead to either of
+B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>. In particular,
+SSL_read() or SSL_peek() may want to write data and SSL_write() may want
+to read data. This is mainly because TLS/SSL handshakes may occur at any
+time during the protocol (initiated by either the client or the server);
+SSL_read(), SSL_peek(), and SSL_write() will handle any pending handshakes.
+
+=item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT
+
+The operation did not complete; the same TLS/SSL I/O function should be
+called again later. The underlying BIO was not connected yet to the peer
+and the call would block in connect()/accept(). The SSL function should be
+called again when the connection is established. These messages can only
+appear with a BIO_s_connect() or BIO_s_accept() BIO, respectively.
+In order to find out, when the connection has been successfully established,
+on many platforms select() or poll() for writing on the socket file descriptor
+can be used.
+
+=item SSL_ERROR_WANT_X509_LOOKUP
+
+The operation did not complete because an application callback set by
+SSL_CTX_set_client_cert_cb() has asked to be called again.
+The TLS/SSL I/O function should be called again later.
+Details depend on the application.
+
+=item SSL_ERROR_SYSCALL
+
+Some I/O error occurred. The OpenSSL error queue may contain more
+information on the error. If the error queue is empty
+(i.e. ERR_get_error() returns 0), B<ret> can be used to find out more
+about the error: If B<ret == 0>, an EOF was observed that violates
+the protocol. If B<ret == -1>, the underlying B<BIO> reported an
+I/O error (for socket I/O on Unix systems, consult B<errno> for details).
+
+=item SSL_ERROR_SSL
+
+A failure in the SSL library occurred, usually a protocol error. The
+OpenSSL error queue contains more information on the error.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<err(3)|err(3)>
+
+=head1 HISTORY
+
+SSL_get_error() was added in SSLeay 0.8.
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod b/openssl/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod
new file mode 100644
index 000000000..165c6a5b2
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod
@@ -0,0 +1,61 @@
+=pod
+
+=head1 NAME
+
+SSL_get_ex_data_X509_STORE_CTX_idx - get ex_data index to access SSL structure
+from X509_STORE_CTX
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_get_ex_data_X509_STORE_CTX_idx(void);
+
+=head1 DESCRIPTION
+
+SSL_get_ex_data_X509_STORE_CTX_idx() returns the index number under which
+the pointer to the SSL object is stored into the X509_STORE_CTX object.
+
+=head1 NOTES
+
+Whenever a X509_STORE_CTX object is created for the verification of the
+peers certificate during a handshake, a pointer to the SSL object is
+stored into the X509_STORE_CTX object to identify the connection affected.
+To retrieve this pointer the X509_STORE_CTX_get_ex_data() function can
+be used with the correct index. This index is globally the same for all
+X509_STORE_CTX objects and can be retrieved using
+SSL_get_ex_data_X509_STORE_CTX_idx(). The index value is set when
+SSL_get_ex_data_X509_STORE_CTX_idx() is first called either by the application
+program directly or indirectly during other SSL setup functions or during
+the handshake.
+
+The value depends on other index values defined for X509_STORE_CTX objects
+before the SSL index is created.
+
+=head1 RETURN VALUES
+
+=over 4
+
+=item E<gt>=0
+
+The index value to access the pointer.
+
+=item E<lt>0
+
+An error occurred, check the error stack for a detailed error message.
+
+=back
+
+=head1 EXAMPLES
+
+The index returned from SSL_get_ex_data_X509_STORE_CTX_idx() allows to
+access the SSL object for the connection to be accessed during the
+verify_callback() when checking the peers certificate. Please check
+the example in L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>,
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>,
+L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_ex_new_index.pod b/openssl/doc/ssl/SSL_get_ex_new_index.pod
new file mode 100644
index 000000000..228d23d8c
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_ex_new_index.pod
@@ -0,0 +1,59 @@
+=pod
+
+=head1 NAME
+
+SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data - internal application specific data functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_get_ex_new_index(long argl, void *argp,
+ CRYPTO_EX_new *new_func,
+ CRYPTO_EX_dup *dup_func,
+ CRYPTO_EX_free *free_func);
+
+ int SSL_set_ex_data(SSL *ssl, int idx, void *arg);
+
+ void *SSL_get_ex_data(const SSL *ssl, int idx);
+
+ typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
+ int idx, long argl, void *argp);
+ typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
+ int idx, long argl, void *argp);
+ typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
+ int idx, long argl, void *argp);
+
+=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.
+
+SSL_get_ex_new_index() is used to register a new index for application
+specific data.
+
+SSL_set_ex_data() is used to store application data at B<arg> for B<idx> into
+the B<ssl> object.
+
+SSL_get_ex_data() is used to retrieve the information for B<idx> from
+B<ssl>.
+
+A detailed description for the B<*_get_ex_new_index()> functionality
+can be found in L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>.
+The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in
+L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>.
+
+=head1 EXAMPLES
+
+An example on how to use the functionality is included in the example
+verify_callback() in L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
+L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>,
+L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_fd.pod b/openssl/doc/ssl/SSL_get_fd.pod
new file mode 100644
index 000000000..89260b522
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_fd.pod
@@ -0,0 +1,44 @@
+=pod
+
+=head1 NAME
+
+SSL_get_fd - get file descriptor linked to an SSL object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_get_fd(const SSL *ssl);
+ int SSL_get_rfd(const SSL *ssl);
+ int SSL_get_wfd(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_fd() returns the file descriptor which is linked to B<ssl>.
+SSL_get_rfd() and SSL_get_wfd() return the file descriptors for the
+read or the write channel, which can be different. If the read and the
+write channel are different, SSL_get_fd() will return the file descriptor
+of the read channel.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item -1
+
+The operation failed, because the underlying BIO is not of the correct type
+(suitable for file descriptors).
+
+=item E<gt>=0
+
+The file descriptor linked to B<ssl>.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_set_fd(3)|SSL_set_fd(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_peer_cert_chain.pod b/openssl/doc/ssl/SSL_get_peer_cert_chain.pod
new file mode 100644
index 000000000..49fb88f86
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_peer_cert_chain.pod
@@ -0,0 +1,52 @@
+=pod
+
+=head1 NAME
+
+SSL_get_peer_cert_chain - get the X509 certificate chain of the peer
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ STACKOF(X509) *SSL_get_peer_cert_chain(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_peer_cert_chain() returns a pointer to STACKOF(X509) certificates
+forming the certificate chain of the peer. If called on the client side,
+the stack also contains the peer's certificate; if called on the server
+side, the peer's certificate must be obtained separately using
+L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>.
+If the peer did not present a certificate, NULL is returned.
+
+=head1 NOTES
+
+The peer certificate chain is not necessarily available after reusing
+a session, in which case a NULL pointer is returned.
+
+The reference count of the STACKOF(X509) object is not incremented.
+If the corresponding session is freed, the pointer must not be used
+any longer.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+No certificate was presented by the peer or no connection was established
+or the certificate chain is no longer available when a session is reused.
+
+=item Pointer to a STACKOF(X509)
+
+The return value points to the certificate chain presented by the peer.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_peer_certificate.pod b/openssl/doc/ssl/SSL_get_peer_certificate.pod
new file mode 100644
index 000000000..ef7c8be18
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_peer_certificate.pod
@@ -0,0 +1,55 @@
+=pod
+
+=head1 NAME
+
+SSL_get_peer_certificate - get the X509 certificate of the peer
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ X509 *SSL_get_peer_certificate(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_peer_certificate() returns a pointer to the X509 certificate the
+peer presented. If the peer did not present a certificate, NULL is returned.
+
+=head1 NOTES
+
+Due to the protocol definition, a TLS/SSL server will always send a
+certificate, if present. A client will only send a certificate when
+explicitly requested to do so by the server (see
+L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>). If an anonymous cipher
+is used, no certificates are sent.
+
+That a certificate is returned does not indicate information about the
+verification state, use L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>
+to check the verification state.
+
+The reference count of the X509 object is incremented by one, so that it
+will not be destroyed when the session containing the peer certificate is
+freed. The X509 object must be explicitly freed using X509_free().
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+No certificate was presented by the peer or no connection was established.
+
+=item Pointer to an X509 certificate
+
+The return value points to the certificate presented by the peer.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
+L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_rbio.pod b/openssl/doc/ssl/SSL_get_rbio.pod
new file mode 100644
index 000000000..3d98233ca
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_rbio.pod
@@ -0,0 +1,40 @@
+=pod
+
+=head1 NAME
+
+SSL_get_rbio - get BIO linked to an SSL object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ BIO *SSL_get_rbio(SSL *ssl);
+ BIO *SSL_get_wbio(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_rbio() and SSL_get_wbio() return pointers to the BIOs for the
+read or the write channel, which can be different. The reference count
+of the BIO is not incremented.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+No BIO was connected to the SSL object
+
+=item Any other pointer
+
+The BIO linked to B<ssl>.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_session.pod b/openssl/doc/ssl/SSL_get_session.pod
new file mode 100644
index 000000000..0c41caa92
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_session.pod
@@ -0,0 +1,73 @@
+=pod
+
+=head1 NAME
+
+SSL_get_session - retrieve TLS/SSL session data
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_SESSION *SSL_get_session(const SSL *ssl);
+ SSL_SESSION *SSL_get0_session(const SSL *ssl);
+ SSL_SESSION *SSL_get1_session(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_session() returns a pointer to the B<SSL_SESSION> actually used in
+B<ssl>. The reference count of the B<SSL_SESSION> is not incremented, so
+that the pointer can become invalid by other operations.
+
+SSL_get0_session() is the same as SSL_get_session().
+
+SSL_get1_session() is the same as SSL_get_session(), but the reference
+count of the B<SSL_SESSION> is incremented by one.
+
+=head1 NOTES
+
+The ssl session contains all information required to re-establish the
+connection without a new handshake.
+
+SSL_get0_session() returns a pointer to the actual session. As the
+reference counter is not incremented, the pointer is only valid while
+the connection is in use. If L<SSL_clear(3)|SSL_clear(3)> or
+L<SSL_free(3)|SSL_free(3)> is called, the session may be removed completely
+(if considered bad), and the pointer obtained will become invalid. Even
+if the session is valid, it can be removed at any time due to timeout
+during L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>.
+
+If the data is to be kept, SSL_get1_session() will increment the reference
+count, so that the session will not be implicitly removed by other operations
+but stays in memory. In order to remove the session
+L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> must be explicitly called once
+to decrement the reference count again.
+
+SSL_SESSION objects keep internal link information about the session cache
+list, when being inserted into one SSL_CTX object's session cache.
+One SSL_SESSION object, regardless of its reference count, must therefore
+only be used with one SSL_CTX object (and the SSL objects created
+from this SSL_CTX object).
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+There is no session available in B<ssl>.
+
+=item Pointer to an SSL
+
+The return value points to the data of an SSL session.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_free(3)|SSL_free(3)>,
+L<SSL_clear(3)|SSL_clear(3)>,
+L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_verify_result.pod b/openssl/doc/ssl/SSL_get_verify_result.pod
new file mode 100644
index 000000000..55b56a53f
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_verify_result.pod
@@ -0,0 +1,57 @@
+=pod
+
+=head1 NAME
+
+SSL_get_verify_result - get result of peer certificate verification
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_get_verify_result(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_verify_result() returns the result of the verification of the
+X509 certificate presented by the peer, if any.
+
+=head1 NOTES
+
+SSL_get_verify_result() can only return one error code while the verification
+of a certificate can fail because of many reasons at the same time. Only
+the last verification error that occurred during the processing is available
+from SSL_get_verify_result().
+
+The verification result is part of the established session and is restored
+when a session is reused.
+
+=head1 BUGS
+
+If no peer certificate was presented, the returned result code is
+X509_V_OK. This is because no verification error occurred, it does however
+not indicate success. SSL_get_verify_result() is only useful in connection
+with L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>.
+
+=head1 RETURN VALUES
+
+The following return values can currently occur:
+
+=over 4
+
+=item X509_V_OK
+
+The verification succeeded or no peer certificate was presented.
+
+=item Any other value
+
+Documented in L<verify(1)|verify(1)>.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_set_verify_result(3)|SSL_set_verify_result(3)>,
+L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>,
+L<verify(1)|verify(1)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_get_version.pod b/openssl/doc/ssl/SSL_get_version.pod
new file mode 100644
index 000000000..cc271db2c
--- /dev/null
+++ b/openssl/doc/ssl/SSL_get_version.pod
@@ -0,0 +1,46 @@
+=pod
+
+=head1 NAME
+
+SSL_get_version - get the protocol version of a connection.
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_get_version(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_cipher_version() returns the name of the protocol used for the
+connection B<ssl>.
+
+=head1 RETURN VALUES
+
+The following strings can occur:
+
+=over 4
+
+=item SSLv2
+
+The connection uses the SSLv2 protocol.
+
+=item SSLv3
+
+The connection uses the SSLv3 protocol.
+
+=item TLSv1
+
+The connection uses the TLSv1 protocol.
+
+=item unknown
+
+This indicates that no version has been set (no connection established).
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_library_init.pod b/openssl/doc/ssl/SSL_library_init.pod
new file mode 100644
index 000000000..ecf3c4858
--- /dev/null
+++ b/openssl/doc/ssl/SSL_library_init.pod
@@ -0,0 +1,52 @@
+=pod
+
+=head1 NAME
+
+SSL_library_init, OpenSSL_add_ssl_algorithms, SSLeay_add_ssl_algorithms
+- initialize SSL library by registering algorithms
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_library_init(void);
+ #define OpenSSL_add_ssl_algorithms() SSL_library_init()
+ #define SSLeay_add_ssl_algorithms() SSL_library_init()
+
+=head1 DESCRIPTION
+
+SSL_library_init() registers the available ciphers and digests.
+
+OpenSSL_add_ssl_algorithms() and SSLeay_add_ssl_algorithms() are synonyms
+for SSL_library_init().
+
+=head1 NOTES
+
+SSL_library_init() must be called before any other action takes place.
+
+=head1 WARNING
+
+SSL_library_init() only registers ciphers. Another important initialization
+is the seeding of the PRNG (Pseudo Random Number Generator), which has to
+be performed separately.
+
+=head1 EXAMPLES
+
+A typical TLS/SSL application will start with the library initialization,
+will provide readable error messages and will seed the PRNG.
+
+ SSL_load_error_strings(); /* readable error messages */
+ SSL_library_init(); /* initialize library */
+ actions_to_seed_PRNG();
+
+=head1 RETURN VALUES
+
+SSL_library_init() always returns "1", so it is safe to discard the return
+value.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>,
+L<RAND_add(3)|RAND_add(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_load_client_CA_file.pod b/openssl/doc/ssl/SSL_load_client_CA_file.pod
new file mode 100644
index 000000000..02527dc2e
--- /dev/null
+++ b/openssl/doc/ssl/SSL_load_client_CA_file.pod
@@ -0,0 +1,62 @@
+=pod
+
+=head1 NAME
+
+SSL_load_client_CA_file - load certificate names from file
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file);
+
+=head1 DESCRIPTION
+
+SSL_load_client_CA_file() reads certificates from B<file> and returns
+a STACK_OF(X509_NAME) with the subject names found.
+
+=head1 NOTES
+
+SSL_load_client_CA_file() reads a file of PEM formatted certificates and
+extracts the X509_NAMES of the certificates found. While the name suggests
+the specific usage as support function for
+L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,
+it is not limited to CA certificates.
+
+=head1 EXAMPLES
+
+Load names of CAs from file and use it as a client CA list:
+
+ SSL_CTX *ctx;
+ STACK_OF(X509_NAME) *cert_names;
+
+ ...
+ cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
+ if (cert_names != NULL)
+ SSL_CTX_set_client_CA_list(ctx, cert_names);
+ else
+ error_handling();
+ ...
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+The operation failed, check out the error stack for the reason.
+
+=item Pointer to STACK_OF(X509_NAME)
+
+Pointer to the subject names of the successfully read certificates.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>,
+L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_new.pod b/openssl/doc/ssl/SSL_new.pod
new file mode 100644
index 000000000..25300e978
--- /dev/null
+++ b/openssl/doc/ssl/SSL_new.pod
@@ -0,0 +1,44 @@
+=pod
+
+=head1 NAME
+
+SSL_new - create a new SSL structure for a connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL *SSL_new(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_new() creates a new B<SSL> structure which is needed to hold the
+data for a TLS/SSL connection. The new structure inherits the settings
+of the underlying context B<ctx>: connection method (SSLv2/v3/TLSv1),
+options, verification settings, timeout settings.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+The creation of a new SSL structure failed. Check the error stack to
+find out the reason.
+
+=item Pointer to an SSL structure
+
+The return value points to an allocated SSL structure.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_free(3)|SSL_free(3)>, L<SSL_clear(3)|SSL_clear(3)>,
+L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
+L<SSL_get_SSL_CTX(3)|SSL_get_SSL_CTX(3)>,
+L<ssl(3)|ssl(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_pending.pod b/openssl/doc/ssl/SSL_pending.pod
new file mode 100644
index 000000000..43f2874e8
--- /dev/null
+++ b/openssl/doc/ssl/SSL_pending.pod
@@ -0,0 +1,43 @@
+=pod
+
+=head1 NAME
+
+SSL_pending - obtain number of readable bytes buffered in an SSL object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_pending(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_pending() returns the number of bytes which are available inside
+B<ssl> for immediate read.
+
+=head1 NOTES
+
+Data are received in blocks from the peer. Therefore data can be buffered
+inside B<ssl> and are ready for immediate retrieval with
+L<SSL_read(3)|SSL_read(3)>.
+
+=head1 RETURN VALUES
+
+The number of bytes pending is returned.
+
+=head1 BUGS
+
+SSL_pending() takes into account only bytes from the TLS/SSL record
+that is currently being processed (if any). If the B<SSL> object's
+I<read_ahead> flag is set, additional protocol bytes may have been
+read containing more TLS/SSL records; these are ignored by
+SSL_pending().
+
+Up to OpenSSL 0.9.6, SSL_pending() does not check if the record type
+of pending data is application data.
+
+=head1 SEE ALSO
+
+L<SSL_read(3)|SSL_read(3)>, L<ssl(3)|ssl(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_read.pod b/openssl/doc/ssl/SSL_read.pod
new file mode 100644
index 000000000..7038cd2d7
--- /dev/null
+++ b/openssl/doc/ssl/SSL_read.pod
@@ -0,0 +1,124 @@
+=pod
+
+=head1 NAME
+
+SSL_read - read bytes from a TLS/SSL connection.
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_read(SSL *ssl, void *buf, int num);
+
+=head1 DESCRIPTION
+
+SSL_read() tries to read B<num> bytes from the specified B<ssl> into the
+buffer B<buf>.
+
+=head1 NOTES
+
+If necessary, SSL_read() will negotiate a TLS/SSL session, if
+not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or
+L<SSL_accept(3)|SSL_accept(3)>. If the
+peer requests a re-negotiation, it will be performed transparently during
+the SSL_read() operation. The behaviour of SSL_read() depends on the
+underlying BIO.
+
+For the transparent negotiation to succeed, the B<ssl> must have been
+initialized to client or server mode. This is being done by calling
+L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state()
+before the first call to an SSL_read() or L<SSL_write(3)|SSL_write(3)>
+function.
+
+SSL_read() works based on the SSL/TLS records. The data are received in
+records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a
+record has been completely received, it can be processed (decryption and
+check of integrity). Therefore data that was not retrieved at the last
+call of SSL_read() can still be buffered inside the SSL layer and will be
+retrieved on the next call to SSL_read(). If B<num> is higher than the
+number of bytes buffered, SSL_read() will return with the bytes buffered.
+If no more bytes are in the buffer, SSL_read() will trigger the processing
+of the next record. Only when the record has been received and processed
+completely, SSL_read() will return reporting success. At most the contents
+of the record will be returned. As the size of an SSL/TLS record may exceed
+the maximum packet size of the underlying transport (e.g. TCP), it may
+be necessary to read several packets from the transport layer before the
+record is complete and SSL_read() can succeed.
+
+If the underlying BIO is B<blocking>, SSL_read() will only return, once the
+read operation has been finished or an error occurred, except when a
+renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
+This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
+L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call.
+
+If the underlying BIO is B<non-blocking>, SSL_read() will also return
+when the underlying BIO could not satisfy the needs of SSL_read()
+to continue the operation. In this case a call to
+L<SSL_get_error(3)|SSL_get_error(3)> with the
+return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
+call to SSL_read() can also cause write operations! The calling process
+then must repeat the call after taking appropriate action to satisfy the
+needs of SSL_read(). The action depends on the underlying BIO. When using a
+non-blocking socket, nothing is to be done, but select() can be used to check
+for the required condition. When using a buffering BIO, like a BIO pair, data
+must be written into or retrieved out of the BIO before being able to continue.
+
+L<SSL_pending(3)|SSL_pending(3)> can be used to find out whether there
+are buffered bytes available for immediate retrieval. In this case
+SSL_read() can be called without blocking or actually receiving new
+data from the underlying socket.
+
+=head1 WARNING
+
+When an SSL_read() operation has to be repeated because of
+B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
+with the same arguments.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item E<gt>0
+
+The read operation was successful; the return value is the number of
+bytes actually read from the TLS/SSL connection.
+
+=item 0
+
+The read operation was not successful. The reason may either be a clean
+shutdown due to a "close notify" alert sent by the peer (in which case
+the SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set
+(see L<SSL_shutdown(3)|SSL_shutdown(3)>,
+L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>). It is also possible, that
+the peer simply shut down the underlying transport and the shutdown is
+incomplete. Call SSL_get_error() with the return value B<ret> to find out,
+whether an error occurred or the connection was shut down cleanly
+(SSL_ERROR_ZERO_RETURN).
+
+SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
+only be detected, whether the underlying connection was closed. It cannot
+be checked, whether the closure was initiated by the peer or by something
+else.
+
+=item E<lt>0
+
+The read operation was not successful, because either an error occurred
+or action must be taken by the calling process. Call SSL_get_error() with the
+return value B<ret> to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>,
+L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
+L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>
+L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
+L<SSL_pending(3)|SSL_pending(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
+L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_rstate_string.pod b/openssl/doc/ssl/SSL_rstate_string.pod
new file mode 100644
index 000000000..bdb8a1fcd
--- /dev/null
+++ b/openssl/doc/ssl/SSL_rstate_string.pod
@@ -0,0 +1,59 @@
+=pod
+
+=head1 NAME
+
+SSL_rstate_string, SSL_rstate_string_long - get textual description of state of an SSL object during read operation
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_rstate_string(SSL *ssl);
+ const char *SSL_rstate_string_long(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_rstate_string() returns a 2 letter string indicating the current read state
+of the SSL object B<ssl>.
+
+SSL_rstate_string_long() returns a string indicating the current read state of
+the SSL object B<ssl>.
+
+=head1 NOTES
+
+When performing a read operation, the SSL/TLS engine must parse the record,
+consisting of header and body. When working in a blocking environment,
+SSL_rstate_string[_long]() should always return "RD"/"read done".
+
+This function should only seldom be needed in applications.
+
+=head1 RETURN VALUES
+
+SSL_rstate_string() and SSL_rstate_string_long() can return the following
+values:
+
+=over 4
+
+=item "RH"/"read header"
+
+The header of the record is being evaluated.
+
+=item "RB"/"read body"
+
+The body of the record is being evaluated.
+
+=item "RD"/"read done"
+
+The record has been completely processed.
+
+=item "unknown"/"unknown"
+
+The read state is unknown. This should never happen.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_session_reused.pod b/openssl/doc/ssl/SSL_session_reused.pod
new file mode 100644
index 000000000..da7d06264
--- /dev/null
+++ b/openssl/doc/ssl/SSL_session_reused.pod
@@ -0,0 +1,45 @@
+=pod
+
+=head1 NAME
+
+SSL_session_reused - query whether a reused session was negotiated during handshake
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_session_reused(SSL *ssl);
+
+=head1 DESCRIPTION
+
+Query, whether a reused session was negotiated during the handshake.
+
+=head1 NOTES
+
+During the negotiation, a client can propose to reuse a session. The server
+then looks up the session in its cache. If both client and server agree
+on the session, it will be reused and a flag is being set that can be
+queried by the application.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 0
+
+A new session was negotiated.
+
+=item 1
+
+A session was reused.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_set_bio.pod b/openssl/doc/ssl/SSL_set_bio.pod
new file mode 100644
index 000000000..67c9756d3
--- /dev/null
+++ b/openssl/doc/ssl/SSL_set_bio.pod
@@ -0,0 +1,34 @@
+=pod
+
+=head1 NAME
+
+SSL_set_bio - connect the SSL object with a BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio);
+
+=head1 DESCRIPTION
+
+SSL_set_bio() connects the BIOs B<rbio> and B<wbio> for the read and write
+operations of the TLS/SSL (encrypted) side of B<ssl>.
+
+The SSL engine inherits the behaviour of B<rbio> and B<wbio>, respectively.
+If a BIO is non-blocking, the B<ssl> will also have non-blocking behaviour.
+
+If there was already a BIO connected to B<ssl>, BIO_free() will be called
+(for both the reading and writing side, if different).
+
+=head1 RETURN VALUES
+
+SSL_set_bio() cannot fail.
+
+=head1 SEE ALSO
+
+L<SSL_get_rbio(3)|SSL_get_rbio(3)>,
+L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_set_connect_state.pod b/openssl/doc/ssl/SSL_set_connect_state.pod
new file mode 100644
index 000000000..d88a057de
--- /dev/null
+++ b/openssl/doc/ssl/SSL_set_connect_state.pod
@@ -0,0 +1,55 @@
+=pod
+
+=head1 NAME
+
+SSL_set_connect_state, SSL_get_accept_state - prepare SSL object to work in client or server mode
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_set_connect_state(SSL *ssl);
+
+ void SSL_set_accept_state(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_set_connect_state() sets B<ssl> to work in client mode.
+
+SSL_set_accept_state() sets B<ssl> to work in server mode.
+
+=head1 NOTES
+
+When the SSL_CTX object was created with L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
+it was either assigned a dedicated client method, a dedicated server
+method, or a generic method, that can be used for both client and
+server connections. (The method might have been changed with
+L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)> or
+SSL_set_ssl_method().)
+
+When beginning a new handshake, the SSL engine must know whether it must
+call the connect (client) or accept (server) routines. Even though it may
+be clear from the method chosen, whether client or server mode was
+requested, the handshake routines must be explicitly set.
+
+When using the L<SSL_connect(3)|SSL_connect(3)> or
+L<SSL_accept(3)|SSL_accept(3)> routines, the correct handshake
+routines are automatically set. When performing a transparent negotiation
+using L<SSL_write(3)|SSL_write(3)> or L<SSL_read(3)|SSL_read(3)>, the
+handshake routines must be explicitly set in advance using either
+SSL_set_connect_state() or SSL_set_accept_state().
+
+=head1 RETURN VALUES
+
+SSL_set_connect_state() and SSL_set_accept_state() do not return diagnostic
+information.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
+L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>,
+L<SSL_write(3)|SSL_write(3)>, L<SSL_read(3)|SSL_read(3)>,
+L<SSL_do_handshake(3)|SSL_do_handshake(3)>,
+L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_set_fd.pod b/openssl/doc/ssl/SSL_set_fd.pod
new file mode 100644
index 000000000..70291128f
--- /dev/null
+++ b/openssl/doc/ssl/SSL_set_fd.pod
@@ -0,0 +1,54 @@
+=pod
+
+=head1 NAME
+
+SSL_set_fd - connect the SSL object with a file descriptor
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_set_fd(SSL *ssl, int fd);
+ int SSL_set_rfd(SSL *ssl, int fd);
+ int SSL_set_wfd(SSL *ssl, int fd);
+
+=head1 DESCRIPTION
+
+SSL_set_fd() sets the file descriptor B<fd> as the input/output facility
+for the TLS/SSL (encrypted) side of B<ssl>. B<fd> will typically be the
+socket file descriptor of a network connection.
+
+When performing the operation, a B<socket BIO> is automatically created to
+interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine
+inherit the behaviour of B<fd>. If B<fd> is non-blocking, the B<ssl> will
+also have non-blocking behaviour.
+
+If there was already a BIO connected to B<ssl>, BIO_free() will be called
+(for both the reading and writing side, if different).
+
+SSL_set_rfd() and SSL_set_wfd() perform the respective action, but only
+for the read channel or the write channel, which can be set independently.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 0
+
+The operation failed. Check the error stack to find out why.
+
+=item 1
+
+The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_fd(3)|SSL_get_fd(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>,
+L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_set_session.pod b/openssl/doc/ssl/SSL_set_session.pod
new file mode 100644
index 000000000..5f54714ad
--- /dev/null
+++ b/openssl/doc/ssl/SSL_set_session.pod
@@ -0,0 +1,57 @@
+=pod
+
+=head1 NAME
+
+SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_set_session(SSL *ssl, SSL_SESSION *session);
+
+=head1 DESCRIPTION
+
+SSL_set_session() sets B<session> to be used when the TLS/SSL connection
+is to be established. SSL_set_session() is only useful for TLS/SSL clients.
+When the session is set, the reference count of B<session> is incremented
+by 1. If the session is not reused, the reference count is decremented
+again during SSL_connect(). Whether the session was reused can be queried
+with the L<SSL_session_reused(3)|SSL_session_reused(3)> call.
+
+If there is already a session set inside B<ssl> (because it was set with
+SSL_set_session() before or because the same B<ssl> was already used for
+a connection), SSL_SESSION_free() will be called for that session.
+
+=head1 NOTES
+
+SSL_SESSION objects keep internal link information about the session cache
+list, when being inserted into one SSL_CTX object's session cache.
+One SSL_SESSION object, regardless of its reference count, must therefore
+only be used with one SSL_CTX object (and the SSL objects created
+from this SSL_CTX object).
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 0
+
+The operation failed; check the error stack to find out the reason.
+
+=item 1
+
+The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
+L<SSL_get_session(3)|SSL_get_session(3)>,
+L<SSL_session_reused(3)|SSL_session_reused(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_set_shutdown.pod b/openssl/doc/ssl/SSL_set_shutdown.pod
new file mode 100644
index 000000000..011a022a1
--- /dev/null
+++ b/openssl/doc/ssl/SSL_set_shutdown.pod
@@ -0,0 +1,72 @@
+=pod
+
+=head1 NAME
+
+SSL_set_shutdown, SSL_get_shutdown - manipulate shutdown state of an SSL connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_set_shutdown(SSL *ssl, int mode);
+
+ int SSL_get_shutdown(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_set_shutdown() sets the shutdown state of B<ssl> to B<mode>.
+
+SSL_get_shutdown() returns the shutdown mode of B<ssl>.
+
+=head1 NOTES
+
+The shutdown state of an ssl connection is a bitmask of:
+
+=over 4
+
+=item 0
+
+No shutdown setting, yet.
+
+=item SSL_SENT_SHUTDOWN
+
+A "close notify" shutdown alert was sent to the peer, the connection is being
+considered closed and the session is closed and correct.
+
+=item SSL_RECEIVED_SHUTDOWN
+
+A shutdown alert was received form the peer, either a normal "close notify"
+or a fatal error.
+
+=back
+
+SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time.
+
+The shutdown state of the connection is used to determine the state of
+the ssl session. If the session is still open, when
+L<SSL_clear(3)|SSL_clear(3)> or L<SSL_free(3)|SSL_free(3)> is called,
+it is considered bad and removed according to RFC2246.
+The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN
+(according to the TLS RFC, it is acceptable to only send the "close notify"
+alert but to not wait for the peer's answer, when the underlying connection
+is closed).
+SSL_set_shutdown() can be used to set this state without sending a
+close alert to the peer (see L<SSL_shutdown(3)|SSL_shutdown(3)>).
+
+If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set,
+for setting SSL_SENT_SHUTDOWN the application must however still call
+L<SSL_shutdown(3)|SSL_shutdown(3)> or SSL_set_shutdown() itself.
+
+=head1 RETURN VALUES
+
+SSL_set_shutdown() does not return diagnostic information.
+
+SSL_get_shutdown() returns the current setting.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>,
+L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>,
+L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_set_verify_result.pod b/openssl/doc/ssl/SSL_set_verify_result.pod
new file mode 100644
index 000000000..04ab101aa
--- /dev/null
+++ b/openssl/doc/ssl/SSL_set_verify_result.pod
@@ -0,0 +1,38 @@
+=pod
+
+=head1 NAME
+
+SSL_set_verify_result - override result of peer certificate verification
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_set_verify_result(SSL *ssl, long verify_result);
+
+=head1 DESCRIPTION
+
+SSL_set_verify_result() sets B<verify_result> of the object B<ssl> to be the
+result of the verification of the X509 certificate presented by the peer,
+if any.
+
+=head1 NOTES
+
+SSL_set_verify_result() overrides the verification result. It only changes
+the verification result of the B<ssl> object. It does not become part of the
+established session, so if the session is to be reused later, the original
+value will reappear.
+
+The valid codes for B<verify_result> are documented in L<verify(1)|verify(1)>.
+
+=head1 RETURN VALUES
+
+SSL_set_verify_result() does not provide a return value.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
+L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>,
+L<verify(1)|verify(1)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_shutdown.pod b/openssl/doc/ssl/SSL_shutdown.pod
new file mode 100644
index 000000000..89911acbc
--- /dev/null
+++ b/openssl/doc/ssl/SSL_shutdown.pod
@@ -0,0 +1,125 @@
+=pod
+
+=head1 NAME
+
+SSL_shutdown - shut down a TLS/SSL connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_shutdown(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_shutdown() shuts down an active TLS/SSL connection. It sends the
+"close notify" shutdown alert to the peer.
+
+=head1 NOTES
+
+SSL_shutdown() tries to send the "close notify" shutdown alert to the peer.
+Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and
+a currently open session is considered closed and good and will be kept in the
+session cache for further reuse.
+
+The shutdown procedure consists of 2 steps: the sending of the "close notify"
+shutdown alert and the reception of the peer's "close notify" shutdown
+alert. According to the TLS standard, it is acceptable for an application
+to only send its shutdown alert and then close the underlying connection
+without waiting for the peer's response (this way resources can be saved,
+as the process can already terminate or serve another connection).
+When the underlying connection shall be used for more communications, the
+complete shutdown procedure (bidirectional "close notify" alerts) must be
+performed, so that the peers stay synchronized.
+
+SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step
+behaviour.
+
+=over 4
+
+=item When the application is the first party to send the "close notify"
+alert, SSL_shutdown() will only send the alert and then set the
+SSL_SENT_SHUTDOWN flag (so that the session is considered good and will
+be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional
+shutdown is enough (the underlying connection shall be closed anyway), this
+first call to SSL_shutdown() is sufficient. In order to complete the
+bidirectional shutdown handshake, SSL_shutdown() must be called again.
+The second call will make SSL_shutdown() wait for the peer's "close notify"
+shutdown alert. On success, the second call to SSL_shutdown() will return
+with 1.
+
+=item If the peer already sent the "close notify" alert B<and> it was
+already processed implicitly inside another function
+(L<SSL_read(3)|SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set.
+SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN
+flag and will immediately return with 1.
+Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the
+SSL_get_shutdown() (see also L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> call.
+
+=back
+
+It is therefore recommended, to check the return value of SSL_shutdown()
+and call SSL_shutdown() again, if the bidirectional shutdown is not yet
+complete (return value of the first call is 0). As the shutdown is not
+specially handled in the SSLv2 protocol, SSL_shutdown() will succeed on
+the first call.
+
+The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
+
+If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
+handshake step has been finished or an error occurred.
+
+If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
+when the underlying BIO could not satisfy the needs of SSL_shutdown()
+to continue the handshake. In this case a call to SSL_get_error() with the
+return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
+taking appropriate action to satisfy the needs of SSL_shutdown().
+The action depends on the underlying BIO. When using a non-blocking socket,
+nothing is to be done, but select() can be used to check for the required
+condition. When using a buffering BIO, like a BIO pair, data must be written
+into or retrieved out of the BIO before being able to continue.
+
+SSL_shutdown() can be modified to only set the connection to "shutdown"
+state but not actually send the "close notify" alert messages,
+see L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>.
+When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
+and return 1.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 1
+
+The shutdown was successfully completed. The "close notify" alert was sent
+and the peer's "close notify" alert was received.
+
+=item 0
+
+The shutdown is not yet finished. Call SSL_shutdown() for a second time,
+if a bidirectional shutdown shall be performed.
+The output of L<SSL_get_error(3)|SSL_get_error(3)> may be misleading, as an
+erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred.
+
+=item -1
+
+The shutdown was not successful because a fatal error occurred either
+at the protocol level or a connection failure occurred. It can also occur if
+action is need to continue the operation for non-blocking BIOs.
+Call L<SSL_get_error(3)|SSL_get_error(3)> with the return value B<ret>
+to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>,
+L<SSL_accept(3)|SSL_accept(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
+L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>,
+L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>,
+L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_state_string.pod b/openssl/doc/ssl/SSL_state_string.pod
new file mode 100644
index 000000000..fe25d47c7
--- /dev/null
+++ b/openssl/doc/ssl/SSL_state_string.pod
@@ -0,0 +1,45 @@
+=pod
+
+=head1 NAME
+
+SSL_state_string, SSL_state_string_long - get textual description of state of an SSL object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_state_string(const SSL *ssl);
+ const char *SSL_state_string_long(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_state_string() returns a 6 letter string indicating the current state
+of the SSL object B<ssl>.
+
+SSL_state_string_long() returns a string indicating the current state of
+the SSL object B<ssl>.
+
+=head1 NOTES
+
+During its use, an SSL objects passes several states. The state is internally
+maintained. Querying the state information is not very informative before
+or when a connection has been established. It however can be of significant
+interest during the handshake.
+
+When using non-blocking sockets, the function call performing the handshake
+may return with SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE condition,
+so that SSL_state_string[_long]() may be called.
+
+For both blocking or non-blocking sockets, the details state information
+can be used within the info_callback function set with the
+SSL_set_info_callback() call.
+
+=head1 RETURN VALUES
+
+Detailed description of possible states to be included later.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_want.pod b/openssl/doc/ssl/SSL_want.pod
new file mode 100644
index 000000000..c0059c0d4
--- /dev/null
+++ b/openssl/doc/ssl/SSL_want.pod
@@ -0,0 +1,77 @@
+=pod
+
+=head1 NAME
+
+SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup - obtain state information TLS/SSL I/O operation
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_want(const SSL *ssl);
+ int SSL_want_nothing(const SSL *ssl);
+ int SSL_want_read(const SSL *ssl);
+ int SSL_want_write(const SSL *ssl);
+ int SSL_want_x509_lookup(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_want() returns state information for the SSL object B<ssl>.
+
+The other SSL_want_*() calls are shortcuts for the possible states returned
+by SSL_want().
+
+=head1 NOTES
+
+SSL_want() examines the internal state information of the SSL object. Its
+return values are similar to that of L<SSL_get_error(3)|SSL_get_error(3)>.
+Unlike L<SSL_get_error(3)|SSL_get_error(3)>, which also evaluates the
+error queue, the results are obtained by examining an internal state flag
+only. The information must therefore only be used for normal operation under
+non-blocking I/O. Error conditions are not handled and must be treated
+using L<SSL_get_error(3)|SSL_get_error(3)>.
+
+The result returned by SSL_want() should always be consistent with
+the result of L<SSL_get_error(3)|SSL_get_error(3)>.
+
+=head1 RETURN VALUES
+
+The following return values can currently occur for SSL_want():
+
+=over 4
+
+=item SSL_NOTHING
+
+There is no data to be written or to be read.
+
+=item SSL_WRITING
+
+There are data in the SSL buffer that must be written to the underlying
+B<BIO> layer in order to complete the actual SSL_*() operation.
+A call to L<SSL_get_error(3)|SSL_get_error(3)> should return
+SSL_ERROR_WANT_WRITE.
+
+=item SSL_READING
+
+More data must be read from the underlying B<BIO> layer in order to
+complete the actual SSL_*() operation.
+A call to L<SSL_get_error(3)|SSL_get_error(3)> should return
+SSL_ERROR_WANT_READ.
+
+=item SSL_X509_LOOKUP
+
+The operation did not complete because an application callback set by
+SSL_CTX_set_client_cert_cb() has asked to be called again.
+A call to L<SSL_get_error(3)|SSL_get_error(3)> should return
+SSL_ERROR_WANT_X509_LOOKUP.
+
+=back
+
+SSL_want_nothing(), SSL_want_read(), SSL_want_write(), SSL_want_x509_lookup()
+return 1, when the corresponding condition is true or 0 otherwise.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<err(3)|err(3)>, L<SSL_get_error(3)|SSL_get_error(3)>
+
+=cut
diff --git a/openssl/doc/ssl/SSL_write.pod b/openssl/doc/ssl/SSL_write.pod
new file mode 100644
index 000000000..e013c12d5
--- /dev/null
+++ b/openssl/doc/ssl/SSL_write.pod
@@ -0,0 +1,109 @@
+=pod
+
+=head1 NAME
+
+SSL_write - write bytes to a TLS/SSL connection.
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_write(SSL *ssl, const void *buf, int num);
+
+=head1 DESCRIPTION
+
+SSL_write() writes B<num> bytes from the buffer B<buf> into the specified
+B<ssl> connection.
+
+=head1 NOTES
+
+If necessary, SSL_write() will negotiate a TLS/SSL session, if
+not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or
+L<SSL_accept(3)|SSL_accept(3)>. If the
+peer requests a re-negotiation, it will be performed transparently during
+the SSL_write() operation. The behaviour of SSL_write() depends on the
+underlying BIO.
+
+For the transparent negotiation to succeed, the B<ssl> must have been
+initialized to client or server mode. This is being done by calling
+L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state()
+before the first call to an L<SSL_read(3)|SSL_read(3)> or SSL_write() function.
+
+If the underlying BIO is B<blocking>, SSL_write() will only return, once the
+write operation has been finished or an error occurred, except when a
+renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
+This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
+L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call.
+
+If the underlying BIO is B<non-blocking>, SSL_write() will also return,
+when the underlying BIO could not satisfy the needs of SSL_write()
+to continue the operation. In this case a call to
+L<SSL_get_error(3)|SSL_get_error(3)> with the
+return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
+call to SSL_write() can also cause read operations! The calling process
+then must repeat the call after taking appropriate action to satisfy the
+needs of SSL_write(). The action depends on the underlying BIO. When using a
+non-blocking socket, nothing is to be done, but select() can be used to check
+for the required condition. When using a buffering BIO, like a BIO pair, data
+must be written into or retrieved out of the BIO before being able to continue.
+
+SSL_write() will only return with success, when the complete contents
+of B<buf> of length B<num> has been written. This default behaviour
+can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of
+L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>. When this flag is set,
+SSL_write() will also return with success, when a partial write has been
+successfully completed. In this case the SSL_write() operation is considered
+completed. The bytes are sent and a new SSL_write() operation with a new
+buffer (with the already sent bytes removed) must be started.
+A partial write is performed with the size of a message block, which is
+16kB for SSLv3/TLSv1.
+
+=head1 WARNING
+
+When an SSL_write() operation has to be repeated because of
+B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
+with the same arguments.
+
+When calling SSL_write() with num=0 bytes to be sent the behaviour is
+undefined.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item E<gt>0
+
+The write operation was successful, the return value is the number of
+bytes actually written to the TLS/SSL connection.
+
+=item 0
+
+The write operation was not successful. Probably the underlying connection
+was closed. Call SSL_get_error() with the return value B<ret> to find out,
+whether an error occurred or the connection was shut down cleanly
+(SSL_ERROR_ZERO_RETURN).
+
+SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
+only be detected, whether the underlying connection was closed. It cannot
+be checked, why the closure happened.
+
+=item E<lt>0
+
+The write operation was not successful, because either an error occurred
+or action must be taken by the calling process. Call SSL_get_error() with the
+return value B<ret> to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_read(3)|SSL_read(3)>,
+L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
+L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>
+L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
+L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
+
+=cut
diff --git a/openssl/doc/ssl/d2i_SSL_SESSION.pod b/openssl/doc/ssl/d2i_SSL_SESSION.pod
new file mode 100644
index 000000000..81d276477
--- /dev/null
+++ b/openssl/doc/ssl/d2i_SSL_SESSION.pod
@@ -0,0 +1,66 @@
+=pod
+
+=head1 NAME
+
+d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length);
+ int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp);
+
+=head1 DESCRIPTION
+
+d2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS
+session, stored as binary data at location B<pp> with length B<length>, into
+an SSL_SESSION object.
+
+i2d_SSL_SESSION() transforms the SSL_SESSION object B<in> into the ASN1
+representation and stores it into the memory location pointed to by B<pp>.
+The length of the resulting ASN1 representation is returned. If B<pp> is
+the NULL pointer, only the length is calculated and returned.
+
+=head1 NOTES
+
+The SSL_SESSION object is built from several malloc()ed parts, it can
+therefore not be moved, copied or stored directly. In order to store
+session data on disk or into a database, it must be transformed into
+a binary ASN1 representation.
+
+When using d2i_SSL_SESSION(), the SSL_SESSION object is automatically
+allocated. The reference count is 1, so that the session must be
+explicitly removed using L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
+unless the SSL_SESSION object is completely taken over, when being called
+inside the get_session_cb() (see
+L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>).
+
+SSL_SESSION objects keep internal link information about the session cache
+list, when being inserted into one SSL_CTX object's session cache.
+One SSL_SESSION object, regardless of its reference count, must therefore
+only be used with one SSL_CTX object (and the SSL objects created
+from this SSL_CTX object).
+
+When using i2d_SSL_SESSION(), the memory location pointed to by B<pp> must be
+large enough to hold the binary representation of the session. There is no
+known limit on the size of the created ASN1 representation, so the necessary
+amount of space should be obtained by first calling i2d_SSL_SESSION() with
+B<pp=NULL>, and obtain the size needed, then allocate the memory and
+call i2d_SSL_SESSION() again.
+
+=head1 RETURN VALUES
+
+d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION
+object. In case of failure the NULL-pointer is returned and the error message
+can be retrieved from the error stack.
+
+i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes.
+When the session is not valid, B<0> is returned and no operation is performed.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
+L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>
+
+=cut
diff --git a/openssl/doc/ssl/ssl.pod b/openssl/doc/ssl/ssl.pod
new file mode 100644
index 000000000..266697d22
--- /dev/null
+++ b/openssl/doc/ssl/ssl.pod
@@ -0,0 +1,736 @@
+
+=pod
+
+=head1 NAME
+
+SSL - OpenSSL SSL/TLS library
+
+=head1 SYNOPSIS
+
+=head1 DESCRIPTION
+
+The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and
+Transport Layer Security (TLS v1) protocols. It provides a rich API which is
+documented here.
+
+At first the library must be initialized; see
+L<SSL_library_init(3)|SSL_library_init(3)>.
+
+Then an B<SSL_CTX> object is created as a framework to establish
+TLS/SSL enabled connections (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>).
+Various options regarding certificates, algorithms etc. can be set
+in this object.
+
+When a network connection has been created, it can be assigned to an
+B<SSL> object. After the B<SSL> object has been created using
+L<SSL_new(3)|SSL_new(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)> or
+L<SSL_set_bio(3)|SSL_set_bio(3)> can be used to associate the network
+connection with the object.
+
+Then the TLS/SSL handshake is performed using
+L<SSL_accept(3)|SSL_accept(3)> or L<SSL_connect(3)|SSL_connect(3)>
+respectively.
+L<SSL_read(3)|SSL_read(3)> and L<SSL_write(3)|SSL_write(3)> are used
+to read and write data on the TLS/SSL connection.
+L<SSL_shutdown(3)|SSL_shutdown(3)> can be used to shut down the
+TLS/SSL connection.
+
+=head1 DATA STRUCTURES
+
+Currently the OpenSSL B<ssl> library functions deals with the following data
+structures:
+
+=over 4
+
+=item B<SSL_METHOD> (SSL Method)
+
+That's a dispatch structure describing the internal B<ssl> library
+methods/functions which implement the various protocol versions (SSLv1, SSLv2
+and TLSv1). It's needed to create an B<SSL_CTX>.
+
+=item B<SSL_CIPHER> (SSL Cipher)
+
+This structure holds the algorithm information for a particular cipher which
+are a core part of the SSL/TLS protocol. The available ciphers are configured
+on a B<SSL_CTX> basis and the actually used ones are then part of the
+B<SSL_SESSION>.
+
+=item B<SSL_CTX> (SSL Context)
+
+That's the global context structure which is created by a server or client
+once per program life-time and which holds mainly default values for the
+B<SSL> structures which are later created for the connections.
+
+=item B<SSL_SESSION> (SSL Session)
+
+This is a structure containing the current TLS/SSL session details for a
+connection: B<SSL_CIPHER>s, client and server certificates, keys, etc.
+
+=item B<SSL> (SSL Connection)
+
+That's the main SSL/TLS structure which is created by a server or client per
+established connection. This actually is the core structure in the SSL API.
+Under run-time the application usually deals with this structure which has
+links to mostly all other structures.
+
+=back
+
+
+=head1 HEADER FILES
+
+Currently the OpenSSL B<ssl> library provides the following C header files
+containing the prototypes for the data structures and and functions:
+
+=over 4
+
+=item B<ssl.h>
+
+That's the common header file for the SSL/TLS API. Include it into your
+program to make the API of the B<ssl> library available. It internally
+includes both more private SSL headers and headers from the B<crypto> library.
+Whenever you need hard-core details on the internals of the SSL API, look
+inside this header file.
+
+=item B<ssl2.h>
+
+That's the sub header file dealing with the SSLv2 protocol only.
+I<Usually you don't have to include it explicitly because
+it's already included by ssl.h>.
+
+=item B<ssl3.h>
+
+That's the sub header file dealing with the SSLv3 protocol only.
+I<Usually you don't have to include it explicitly because
+it's already included by ssl.h>.
+
+=item B<ssl23.h>
+
+That's the sub header file dealing with the combined use of the SSLv2 and
+SSLv3 protocols.
+I<Usually you don't have to include it explicitly because
+it's already included by ssl.h>.
+
+=item B<tls1.h>
+
+That's the sub header file dealing with the TLSv1 protocol only.
+I<Usually you don't have to include it explicitly because
+it's already included by ssl.h>.
+
+=back
+
+=head1 API FUNCTIONS
+
+Currently the OpenSSL B<ssl> library exports 214 API functions.
+They are documented in the following:
+
+=head2 DEALING WITH PROTOCOL METHODS
+
+Here we document the various API functions which deal with the SSL/TLS
+protocol methods defined in B<SSL_METHOD> structures.
+
+=over 4
+
+=item SSL_METHOD *B<SSLv2_client_method>(void);
+
+Constructor for the SSLv2 SSL_METHOD structure for a dedicated client.
+
+=item SSL_METHOD *B<SSLv2_server_method>(void);
+
+Constructor for the SSLv2 SSL_METHOD structure for a dedicated server.
+
+=item SSL_METHOD *B<SSLv2_method>(void);
+
+Constructor for the SSLv2 SSL_METHOD structure for combined client and server.
+
+=item SSL_METHOD *B<SSLv3_client_method>(void);
+
+Constructor for the SSLv3 SSL_METHOD structure for a dedicated client.
+
+=item SSL_METHOD *B<SSLv3_server_method>(void);
+
+Constructor for the SSLv3 SSL_METHOD structure for a dedicated server.
+
+=item SSL_METHOD *B<SSLv3_method>(void);
+
+Constructor for the SSLv3 SSL_METHOD structure for combined client and server.
+
+=item SSL_METHOD *B<TLSv1_client_method>(void);
+
+Constructor for the TLSv1 SSL_METHOD structure for a dedicated client.
+
+=item SSL_METHOD *B<TLSv1_server_method>(void);
+
+Constructor for the TLSv1 SSL_METHOD structure for a dedicated server.
+
+=item SSL_METHOD *B<TLSv1_method>(void);
+
+Constructor for the TLSv1 SSL_METHOD structure for combined client and server.
+
+=back
+
+=head2 DEALING WITH CIPHERS
+
+Here we document the various API functions which deal with the SSL/TLS
+ciphers defined in B<SSL_CIPHER> structures.
+
+=over 4
+
+=item char *B<SSL_CIPHER_description>(SSL_CIPHER *cipher, char *buf, int len);
+
+Write a string to I<buf> (with a maximum size of I<len>) containing a human
+readable description of I<cipher>. Returns I<buf>.
+
+=item int B<SSL_CIPHER_get_bits>(SSL_CIPHER *cipher, int *alg_bits);
+
+Determine the number of bits in I<cipher>. Because of export crippled ciphers
+there are two bits: The bits the algorithm supports in general (stored to
+I<alg_bits>) and the bits which are actually used (the return value).
+
+=item const char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher);
+
+Return the internal name of I<cipher> as a string. These are the various
+strings defined by the I<SSL2_TXT_xxx>, I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx>
+definitions in the header files.
+
+=item char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher);
+
+Returns a string like "C<TLSv1/SSLv3>" or "C<SSLv2>" which indicates the
+SSL/TLS protocol version to which I<cipher> belongs (i.e. where it was defined
+in the specification the first time).
+
+=back
+
+=head2 DEALING WITH PROTOCOL CONTEXTS
+
+Here we document the various API functions which deal with the SSL/TLS
+protocol context defined in the B<SSL_CTX> structure.
+
+=over 4
+
+=item int B<SSL_CTX_add_client_CA>(SSL_CTX *ctx, X509 *x);
+
+=item long B<SSL_CTX_add_extra_chain_cert>(SSL_CTX *ctx, X509 *x509);
+
+=item int B<SSL_CTX_add_session>(SSL_CTX *ctx, SSL_SESSION *c);
+
+=item int B<SSL_CTX_check_private_key>(const SSL_CTX *ctx);
+
+=item long B<SSL_CTX_ctrl>(SSL_CTX *ctx, int cmd, long larg, char *parg);
+
+=item void B<SSL_CTX_flush_sessions>(SSL_CTX *s, long t);
+
+=item void B<SSL_CTX_free>(SSL_CTX *a);
+
+=item char *B<SSL_CTX_get_app_data>(SSL_CTX *ctx);
+
+=item X509_STORE *B<SSL_CTX_get_cert_store>(SSL_CTX *ctx);
+
+=item STACK *B<SSL_CTX_get_client_CA_list>(const SSL_CTX *ctx);
+
+=item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
+
+=item char *B<SSL_CTX_get_ex_data>(const SSL_CTX *s, int idx);
+
+=item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
+
+=item void (*B<SSL_CTX_get_info_callback>(SSL_CTX *ctx))(SSL *ssl, int cb, int ret);
+
+=item int B<SSL_CTX_get_quiet_shutdown>(const SSL_CTX *ctx);
+
+=item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx);
+
+=item long B<SSL_CTX_get_timeout>(const SSL_CTX *ctx);
+
+=item int (*B<SSL_CTX_get_verify_callback>(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx);
+
+=item int B<SSL_CTX_get_verify_mode>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_load_verify_locations>(SSL_CTX *ctx, char *CAfile, char *CApath);
+
+=item long B<SSL_CTX_need_tmp_RSA>(SSL_CTX *ctx);
+
+=item SSL_CTX *B<SSL_CTX_new>(SSL_METHOD *meth);
+
+=item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c);
+
+=item int B<SSL_CTX_sess_accept>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_accept_good>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_accept_renegotiate>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_cache_full>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_cb_hits>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_connect>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_connect_good>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_connect_renegotiate>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_get_cache_size>(SSL_CTX *ctx);
+
+=item SSL_SESSION *(*B<SSL_CTX_sess_get_get_cb>(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy);
+
+=item int (*B<SSL_CTX_sess_get_new_cb>(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess);
+
+=item void (*B<SSL_CTX_sess_get_remove_cb>(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess);
+
+=item int B<SSL_CTX_sess_hits>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_misses>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_number>(SSL_CTX *ctx);
+
+=item void B<SSL_CTX_sess_set_cache_size>(SSL_CTX *ctx,t);
+
+=item void B<SSL_CTX_sess_set_get_cb>(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy));
+
+=item void B<SSL_CTX_sess_set_new_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess));
+
+=item void B<SSL_CTX_sess_set_remove_cb>(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess));
+
+=item int B<SSL_CTX_sess_timeouts>(SSL_CTX *ctx);
+
+=item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx);
+
+=item void B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg);
+
+=item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs);
+
+=item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg)
+
+=item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str);
+
+=item void B<SSL_CTX_set_client_CA_list>(SSL_CTX *ctx, STACK *list);
+
+=item void B<SSL_CTX_set_client_cert_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
+
+=item void B<SSL_CTX_set_default_passwd_cb>(SSL_CTX *ctx, int (*cb);(void))
+
+=item void B<SSL_CTX_set_default_read_ahead>(SSL_CTX *ctx, int m);
+
+=item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg);
+
+=item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret));
+
+=item void B<SSL_CTX_set_msg_callback>(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
+
+=item void B<SSL_CTX_set_msg_callback_arg>(SSL_CTX *ctx, void *arg);
+
+=item void B<SSL_CTX_set_options>(SSL_CTX *ctx, unsigned long op);
+
+=item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode);
+
+=item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode);
+
+=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, SSL_METHOD *meth);
+
+=item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t);
+
+=item long B<SSL_CTX_set_tmp_dh>(SSL_CTX* ctx, DH *dh);
+
+=item long B<SSL_CTX_set_tmp_dh_callback>(SSL_CTX *ctx, DH *(*cb)(void));
+
+=item long B<SSL_CTX_set_tmp_rsa>(SSL_CTX *ctx, RSA *rsa);
+
+=item SSL_CTX_set_tmp_rsa_callback
+
+C<long B<SSL_CTX_set_tmp_rsa_callback>(SSL_CTX *B<ctx>, RSA *(*B<cb>)(SSL *B<ssl>, int B<export>, int B<keylength>));>
+
+Sets the callback which will be called when a temporary private key is
+required. The B<C<export>> flag will be set if the reason for needing
+a temp key is that an export ciphersuite is in use, in which case,
+B<C<keylength>> will contain the required keylength in bits. Generate a key of
+appropriate size (using ???) and return it.
+
+=item SSL_set_tmp_rsa_callback
+
+long B<SSL_set_tmp_rsa_callback>(SSL *ssl, RSA *(*cb)(SSL *ssl, int export, int keylength));
+
+The same as B<SSL_CTX_set_tmp_rsa_callback>, except it operates on an SSL
+session instead of a context.
+
+=item void B<SSL_CTX_set_verify>(SSL_CTX *ctx, int mode, int (*cb);(void))
+
+=item int B<SSL_CTX_use_PrivateKey>(SSL_CTX *ctx, EVP_PKEY *pkey);
+
+=item int B<SSL_CTX_use_PrivateKey_ASN1>(int type, SSL_CTX *ctx, unsigned char *d, long len);
+
+=item int B<SSL_CTX_use_PrivateKey_file>(SSL_CTX *ctx, char *file, int type);
+
+=item int B<SSL_CTX_use_RSAPrivateKey>(SSL_CTX *ctx, RSA *rsa);
+
+=item int B<SSL_CTX_use_RSAPrivateKey_ASN1>(SSL_CTX *ctx, unsigned char *d, long len);
+
+=item int B<SSL_CTX_use_RSAPrivateKey_file>(SSL_CTX *ctx, char *file, int type);
+
+=item int B<SSL_CTX_use_certificate>(SSL_CTX *ctx, X509 *x);
+
+=item int B<SSL_CTX_use_certificate_ASN1>(SSL_CTX *ctx, int len, unsigned char *d);
+
+=item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, char *file, int type);
+
+=back
+
+=head2 DEALING WITH SESSIONS
+
+Here we document the various API functions which deal with the SSL/TLS
+sessions defined in the B<SSL_SESSION> structures.
+
+=over 4
+
+=item int B<SSL_SESSION_cmp>(const SSL_SESSION *a, const SSL_SESSION *b);
+
+=item void B<SSL_SESSION_free>(SSL_SESSION *ss);
+
+=item char *B<SSL_SESSION_get_app_data>(SSL_SESSION *s);
+
+=item char *B<SSL_SESSION_get_ex_data>(const SSL_SESSION *s, int idx);
+
+=item int B<SSL_SESSION_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
+
+=item long B<SSL_SESSION_get_time>(const SSL_SESSION *s);
+
+=item long B<SSL_SESSION_get_timeout>(const SSL_SESSION *s);
+
+=item unsigned long B<SSL_SESSION_hash>(const SSL_SESSION *a);
+
+=item SSL_SESSION *B<SSL_SESSION_new>(void);
+
+=item int B<SSL_SESSION_print>(BIO *bp, const SSL_SESSION *x);
+
+=item int B<SSL_SESSION_print_fp>(FILE *fp, const SSL_SESSION *x);
+
+=item void B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a);
+
+=item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg);
+
+=item long B<SSL_SESSION_set_time>(SSL_SESSION *s, long t);
+
+=item long B<SSL_SESSION_set_timeout>(SSL_SESSION *s, long t);
+
+=back
+
+=head2 DEALING WITH CONNECTIONS
+
+Here we document the various API functions which deal with the SSL/TLS
+connection defined in the B<SSL> structure.
+
+=over 4
+
+=item int B<SSL_accept>(SSL *ssl);
+
+=item int B<SSL_add_dir_cert_subjects_to_stack>(STACK *stack, const char *dir);
+
+=item int B<SSL_add_file_cert_subjects_to_stack>(STACK *stack, const char *file);
+
+=item int B<SSL_add_client_CA>(SSL *ssl, X509 *x);
+
+=item char *B<SSL_alert_desc_string>(int value);
+
+=item char *B<SSL_alert_desc_string_long>(int value);
+
+=item char *B<SSL_alert_type_string>(int value);
+
+=item char *B<SSL_alert_type_string_long>(int value);
+
+=item int B<SSL_check_private_key>(const SSL *ssl);
+
+=item void B<SSL_clear>(SSL *ssl);
+
+=item long B<SSL_clear_num_renegotiations>(SSL *ssl);
+
+=item int B<SSL_connect>(SSL *ssl);
+
+=item void B<SSL_copy_session_id>(SSL *t, const SSL *f);
+
+=item long B<SSL_ctrl>(SSL *ssl, int cmd, long larg, char *parg);
+
+=item int B<SSL_do_handshake>(SSL *ssl);
+
+=item SSL *B<SSL_dup>(SSL *ssl);
+
+=item STACK *B<SSL_dup_CA_list>(STACK *sk);
+
+=item void B<SSL_free>(SSL *ssl);
+
+=item SSL_CTX *B<SSL_get_SSL_CTX>(const SSL *ssl);
+
+=item char *B<SSL_get_app_data>(SSL *ssl);
+
+=item X509 *B<SSL_get_certificate>(const SSL *ssl);
+
+=item const char *B<SSL_get_cipher>(const SSL *ssl);
+
+=item int B<SSL_get_cipher_bits>(const SSL *ssl, int *alg_bits);
+
+=item char *B<SSL_get_cipher_list>(const SSL *ssl, int n);
+
+=item char *B<SSL_get_cipher_name>(const SSL *ssl);
+
+=item char *B<SSL_get_cipher_version>(const SSL *ssl);
+
+=item STACK *B<SSL_get_ciphers>(const SSL *ssl);
+
+=item STACK *B<SSL_get_client_CA_list>(const SSL *ssl);
+
+=item SSL_CIPHER *B<SSL_get_current_cipher>(SSL *ssl);
+
+=item long B<SSL_get_default_timeout>(const SSL *ssl);
+
+=item int B<SSL_get_error>(const SSL *ssl, int i);
+
+=item char *B<SSL_get_ex_data>(const SSL *ssl, int idx);
+
+=item int B<SSL_get_ex_data_X509_STORE_CTX_idx>(void);
+
+=item int B<SSL_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
+
+=item int B<SSL_get_fd>(const SSL *ssl);
+
+=item void (*B<SSL_get_info_callback>(const SSL *ssl);)()
+
+=item STACK *B<SSL_get_peer_cert_chain>(const SSL *ssl);
+
+=item X509 *B<SSL_get_peer_certificate>(const SSL *ssl);
+
+=item EVP_PKEY *B<SSL_get_privatekey>(SSL *ssl);
+
+=item int B<SSL_get_quiet_shutdown>(const SSL *ssl);
+
+=item BIO *B<SSL_get_rbio>(const SSL *ssl);
+
+=item int B<SSL_get_read_ahead>(const SSL *ssl);
+
+=item SSL_SESSION *B<SSL_get_session>(const SSL *ssl);
+
+=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int len);
+
+=item int B<SSL_get_shutdown>(const SSL *ssl);
+
+=item SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl);
+
+=item int B<SSL_get_state>(const SSL *ssl);
+
+=item long B<SSL_get_time>(const SSL *ssl);
+
+=item long B<SSL_get_timeout>(const SSL *ssl);
+
+=item int (*B<SSL_get_verify_callback>(const SSL *ssl))(int,X509_STORE_CTX *)
+
+=item int B<SSL_get_verify_mode>(const SSL *ssl);
+
+=item long B<SSL_get_verify_result>(const SSL *ssl);
+
+=item char *B<SSL_get_version>(const SSL *ssl);
+
+=item BIO *B<SSL_get_wbio>(const SSL *ssl);
+
+=item int B<SSL_in_accept_init>(SSL *ssl);
+
+=item int B<SSL_in_before>(SSL *ssl);
+
+=item int B<SSL_in_connect_init>(SSL *ssl);
+
+=item int B<SSL_in_init>(SSL *ssl);
+
+=item int B<SSL_is_init_finished>(SSL *ssl);
+
+=item STACK *B<SSL_load_client_CA_file>(char *file);
+
+=item void B<SSL_load_error_strings>(void);
+
+=item SSL *B<SSL_new>(SSL_CTX *ctx);
+
+=item long B<SSL_num_renegotiations>(SSL *ssl);
+
+=item int B<SSL_peek>(SSL *ssl, void *buf, int num);
+
+=item int B<SSL_pending>(const SSL *ssl);
+
+=item int B<SSL_read>(SSL *ssl, void *buf, int num);
+
+=item int B<SSL_renegotiate>(SSL *ssl);
+
+=item char *B<SSL_rstate_string>(SSL *ssl);
+
+=item char *B<SSL_rstate_string_long>(SSL *ssl);
+
+=item long B<SSL_session_reused>(SSL *ssl);
+
+=item void B<SSL_set_accept_state>(SSL *ssl);
+
+=item void B<SSL_set_app_data>(SSL *ssl, char *arg);
+
+=item void B<SSL_set_bio>(SSL *ssl, BIO *rbio, BIO *wbio);
+
+=item int B<SSL_set_cipher_list>(SSL *ssl, char *str);
+
+=item void B<SSL_set_client_CA_list>(SSL *ssl, STACK *list);
+
+=item void B<SSL_set_connect_state>(SSL *ssl);
+
+=item int B<SSL_set_ex_data>(SSL *ssl, int idx, char *arg);
+
+=item int B<SSL_set_fd>(SSL *ssl, int fd);
+
+=item void B<SSL_set_info_callback>(SSL *ssl, void (*cb);(void))
+
+=item void B<SSL_set_msg_callback>(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
+
+=item void B<SSL_set_msg_callback_arg>(SSL *ctx, void *arg);
+
+=item void B<SSL_set_options>(SSL *ssl, unsigned long op);
+
+=item void B<SSL_set_quiet_shutdown>(SSL *ssl, int mode);
+
+=item void B<SSL_set_read_ahead>(SSL *ssl, int yes);
+
+=item int B<SSL_set_rfd>(SSL *ssl, int fd);
+
+=item int B<SSL_set_session>(SSL *ssl, SSL_SESSION *session);
+
+=item void B<SSL_set_shutdown>(SSL *ssl, int mode);
+
+=item int B<SSL_set_ssl_method>(SSL *ssl, SSL_METHOD *meth);
+
+=item void B<SSL_set_time>(SSL *ssl, long t);
+
+=item void B<SSL_set_timeout>(SSL *ssl, long t);
+
+=item void B<SSL_set_verify>(SSL *ssl, int mode, int (*callback);(void))
+
+=item void B<SSL_set_verify_result>(SSL *ssl, long arg);
+
+=item int B<SSL_set_wfd>(SSL *ssl, int fd);
+
+=item int B<SSL_shutdown>(SSL *ssl);
+
+=item int B<SSL_state>(const SSL *ssl);
+
+=item char *B<SSL_state_string>(const SSL *ssl);
+
+=item char *B<SSL_state_string_long>(const SSL *ssl);
+
+=item long B<SSL_total_renegotiations>(SSL *ssl);
+
+=item int B<SSL_use_PrivateKey>(SSL *ssl, EVP_PKEY *pkey);
+
+=item int B<SSL_use_PrivateKey_ASN1>(int type, SSL *ssl, unsigned char *d, long len);
+
+=item int B<SSL_use_PrivateKey_file>(SSL *ssl, char *file, int type);
+
+=item int B<SSL_use_RSAPrivateKey>(SSL *ssl, RSA *rsa);
+
+=item int B<SSL_use_RSAPrivateKey_ASN1>(SSL *ssl, unsigned char *d, long len);
+
+=item int B<SSL_use_RSAPrivateKey_file>(SSL *ssl, char *file, int type);
+
+=item int B<SSL_use_certificate>(SSL *ssl, X509 *x);
+
+=item int B<SSL_use_certificate_ASN1>(SSL *ssl, int len, unsigned char *d);
+
+=item int B<SSL_use_certificate_file>(SSL *ssl, char *file, int type);
+
+=item int B<SSL_version>(const SSL *ssl);
+
+=item int B<SSL_want>(const SSL *ssl);
+
+=item int B<SSL_want_nothing>(const SSL *ssl);
+
+=item int B<SSL_want_read>(const SSL *ssl);
+
+=item int B<SSL_want_write>(const SSL *ssl);
+
+=item int B<SSL_want_x509_lookup>(const SSL *ssl);
+
+=item int B<SSL_write>(SSL *ssl, const void *buf, int num);
+
+=back
+
+=head1 SEE ALSO
+
+L<openssl(1)|openssl(1)>, L<crypto(3)|crypto(3)>,
+L<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>,
+L<SSL_connect(3)|SSL_connect(3)>,
+L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>,
+L<SSL_COMP_add_compression_method(3)|SSL_COMP_add_compression_method(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>,
+L<SSL_CTX_ctrl(3)|SSL_CTX_ctrl(3)>,
+L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>,
+L<SSL_CTX_get_ex_new_index(3)|SSL_CTX_get_ex_new_index(3)>,
+L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>,
+L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
+L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
+L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>,
+L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>,
+L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>,
+L<SSL_CTX_sessions(3)|SSL_CTX_sessions(3)>,
+L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)>,
+L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>,
+L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
+L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,
+L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>,
+L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>,
+L<SSL_CTX_set_generate_session_id(3)|SSL_CTX_set_generate_session_id(3)>,
+L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>,
+L<SSL_CTX_set_max_cert_list(3)|SSL_CTX_set_max_cert_list(3)>,
+L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>,
+L<SSL_CTX_set_msg_callback(3)|SSL_CTX_set_msg_callback(3)>,
+L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
+L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>,
+L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>,
+L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>,
+L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
+L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
+L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>,
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
+L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>,
+L<SSL_do_handshake(3)|SSL_do_handshake(3)>,
+L<SSL_get_SSL_CTX(3)|SSL_get_SSL_CTX(3)>,
+L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,
+L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
+L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>,
+L<SSL_get_error(3)|SSL_get_error(3)>,
+L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
+L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>,
+L<SSL_get_fd(3)|SSL_get_fd(3)>,
+L<SSL_get_peer_cert_chain(3)|SSL_get_peer_cert_chain(3)>,
+L<SSL_get_rbio(3)|SSL_get_rbio(3)>,
+L<SSL_get_session(3)|SSL_get_session(3)>,
+L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
+L<SSL_get_version(3)|SSL_get_version(3)>,
+L<SSL_library_init(3)|SSL_library_init(3)>,
+L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>,
+L<SSL_new(3)|SSL_new(3)>,
+L<SSL_pending(3)|SSL_pending(3)>,
+L<SSL_read(3)|SSL_read(3)>,
+L<SSL_rstate_string(3)|SSL_rstate_string(3)>,
+L<SSL_session_reused(3)|SSL_session_reused(3)>,
+L<SSL_set_bio(3)|SSL_set_bio(3)>,
+L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
+L<SSL_set_fd(3)|SSL_set_fd(3)>,
+L<SSL_set_session(3)|SSL_set_session(3)>,
+L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>,
+L<SSL_state_string(3)|SSL_state_string(3)>,
+L<SSL_want(3)|SSL_want(3)>,
+L<SSL_write(3)|SSL_write(3)>,
+L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
+L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>,
+L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>,
+L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>
+
+=head1 HISTORY
+
+The L<ssl(3)|ssl(3)> document appeared in OpenSSL 0.9.2
+
+=cut
+
diff --git a/openssl/doc/ssleay.txt b/openssl/doc/ssleay.txt
new file mode 100644
index 000000000..a8b04d705
--- /dev/null
+++ b/openssl/doc/ssleay.txt
@@ -0,0 +1,7030 @@
+
+Bundle of old SSLeay documentation files [OBSOLETE!]
+
+*** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! ***
+
+OBSOLETE means that nothing in this document should be trusted. This
+document is provided mostly for historical purposes (it wasn't even up
+to date at the time SSLeay 0.8.1 was released) and as inspiration. If
+you copy some snippet of code from this document, please _check_ that
+it really is correct from all points of view. For example, you can
+check with the other documents in this directory tree, or by comparing
+with relevant parts of the include files.
+
+People have done the mistake of trusting what's written here. Please
+don't do that.
+
+*** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! ***
+
+
+==== readme ========================================================
+
+This is the old 0.6.6 docuementation. Most of the cipher stuff is still
+relevent but I'm working (very slowly) on new docuemtation.
+The current version can be found online at
+
+http://www.cryptsoft.com/ssleay/doc
+
+==== API.doc ========================================================
+
+SSL - SSLv2/v3/v23 etc.
+
+BIO - methods and how they plug together
+
+MEM - memory allocation callback
+
+CRYPTO - locking for threads
+
+EVP - Ciphers/Digests/signatures
+
+RSA - methods
+
+X509 - certificate retrieval
+
+X509 - validation
+
+X509 - X509v3 extensions
+
+Objects - adding object identifiers
+
+ASN.1 - parsing
+
+PEM - parsing
+
+==== ssl/readme =====================================================
+
+22 Jun 1996
+This file belongs in ../apps, but I'll leave it here because it deals
+with SSL :-) It is rather dated but it gives you an idea of how
+things work.
+===
+
+17 Jul 1995
+I have been changing things quite a bit and have not fully updated
+this file, so take what you read with a grain of salt
+eric
+===
+The s_client and s_server programs can be used to test SSL capable
+IP/port addresses and the verification of the X509 certificates in use
+by these services. I strongly advise having a look at the code to get
+an idea of how to use the authentication under SSLeay. Any feedback
+on changes and improvements would be greatly accepted.
+
+This file will probably be gibberish unless you have read
+rfc1421, rfc1422, rfc1423 and rfc1424 which describe PEM
+authentication.
+
+A Brief outline (and examples) how to use them to do so.
+
+NOTE:
+The environment variable SSL_CIPER is used to specify the prefered
+cipher to use, play around with setting it's value to combinations of
+RC4-MD5, EXP-RC4-MD5, CBC-DES-MD5, CBC3-DES-MD5, CFB-DES-NULL
+in a : separated list.
+
+This directory contains 3 X509 certificates which can be used by these programs.
+client.pem: a file containing a certificate and private key to be used
+ by s_client.
+server.pem :a file containing a certificate and private key to be used
+ by s_server.
+eay1024.pem:the certificate used to sign client.pem and server.pem.
+ This would be your CA's certificate. There is also a link
+ from the file a8556381.0 to eay1024.PEM. The value a8556381
+ is returned by 'x509 -hash -noout <eay1024.pem' and is the
+ value used by X509 verification routines to 'find' this
+ certificte when search a directory for it.
+ [the above is not true any more, the CA cert is
+ ../certs/testca.pem which is signed by ../certs/mincomca.pem]
+
+When testing the s_server, you may get
+bind: Address already in use
+errors. These indicate the port is still being held by the unix
+kernel and you are going to have to wait for it to let go of it. If
+this is the case, remember to use the port commands on the s_server and
+s_client to talk on an alternative port.
+
+=====
+s_client.
+This program can be used to connect to any IP/hostname:port that is
+talking SSL. Once connected, it will attempt to authenticate the
+certificate it was passed and if everything works as expected, a 2
+directional channel will be open. Any text typed will be sent to the
+other end. type Q<cr> to exit. Flags are as follows.
+-host arg : Arg is the host or IP address to connect to.
+-port arg : Arg is the port to connect to (https is 443).
+-verify arg : Turn on authentication of the server certificate.
+ : Arg specifies the 'depth', this will covered below.
+-cert arg : The optional certificate to use. This certificate
+ : will be returned to the server if the server
+ : requests it for client authentication.
+-key arg : The private key that matches the certificate
+ : specified by the -cert option. If this is not
+ : specified (but -cert is), the -cert file will be
+ : searched for the Private key. Both files are
+ : assumed to be in PEM format.
+-CApath arg : When to look for certificates when 'verifying' the
+ : certificate from the server.
+-CAfile arg : A file containing certificates to be used for
+ : 'verifying' the server certificate.
+-reconnect : Once a connection has been made, drop it and
+ : reconnect with same session-id. This is for testing :-).
+
+The '-verify n' parameter specifies not only to verify the servers
+certificate but to also only take notice of 'n' levels. The best way
+to explain is to show via examples.
+Given
+s_server -cert server.PEM is running.
+
+s_client
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
+ issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify error:num=1:unable to get issuer certificate
+ verify return:1
+ CIPHER is CBC-DES-MD5
+What has happened is that the 'SSLeay demo server' certificate's
+issuer ('CA') could not be found but because verify is not on, we
+don't care and the connection has been made anyway. It is now 'up'
+using CBC-DES-MD5 mode. This is an unauthenticate secure channel.
+You may not be talking to the right person but the data going to them
+is encrypted.
+
+s_client -verify 0
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
+ issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify error:num=1:unable to get issuer certificate
+ verify return:1
+ CIPHER is CBC-DES-MD5
+We are 'verifying' but only to depth 0, so since the 'SSLeay demo server'
+certificate passed the date and checksum, we are happy to proceed.
+
+s_client -verify 1
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
+ issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify error:num=1:unable to get issuer certificate
+ verify return:0
+ ERROR
+ verify error:unable to get issuer certificate
+In this case we failed to make the connection because we could not
+authenticate the certificate because we could not find the
+'CA' certificate.
+
+s_client -verify 1 -CAfile eay1024.PEM
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
+ verify return:1
+ depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify return:1
+ CIPHER is CBC-DES-MD5
+We loaded the certificates from the file eay1024.PEM. Everything
+checked out and so we made the connection.
+
+s_client -verify 1 -CApath .
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
+ verify return:1
+ depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify return:1
+ CIPHER is CBC-DES-MD5
+We looked in out local directory for issuer certificates and 'found'
+a8556381.0 and so everything is ok.
+
+It is worth noting that 'CA' is a self certified certificate. If you
+are passed one of these, it will fail to 'verify' at depth 0 because
+we need to lookup the certifier of a certificate from some information
+that we trust and keep locally.
+
+SSL_CIPHER=CBC3-DES-MD5:RC4-MD5
+export SSL_CIPHER
+s_client -verify 10 -CApath . -reconnect
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
+ verify return:1
+ depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify return:1
+ drop the connection and reconnect with the same session id
+ CIPHER is CBC3-DES-MD5
+This has done a full connection and then re-estabished it with the
+same session id but a new socket. No RSA stuff occures on the second
+connection. Note that we said we would prefer to use CBC3-DES-MD5
+encryption and so, since the server supports it, we are.
+
+=====
+s_server
+This program accepts SSL connections on a specified port
+Once connected, it will estabish an SSL connection and optionaly
+attempt to authenticate the client. A 2 directional channel will be
+open. Any text typed will be sent to the other end. Type Q<cr> to exit.
+Flags are as follows.
+-port arg : Arg is the port to listen on.
+-verify arg : Turn on authentication of the client if they have a
+ : certificate. Arg specifies the 'depth'.
+-Verify arg : Turn on authentication of the client. If they don't
+ : have a valid certificate, drop the connection.
+-cert arg : The certificate to use. This certificate
+ : will be passed to the client. If it is not
+ : specified, it will default to server.PEM
+-key arg : The private key that matches the certificate
+ : specified by the -cert option. If this is not
+ : specified (but -cert is), the -cert file will be
+ : searched for the Private key. Both files are
+ : assumed to be in PEM format. Default is server.PEM
+-CApath arg : When to look for certificates when 'verifying' the
+ : certificate from the client.
+-CAfile arg : A file containing certificates to be used for
+ : 'verifying' the client certificate.
+
+For the following 'demo' I will specify the s_server command and
+the s_client command and then list the output from the s_server.
+s_server
+s_client
+ CONNECTED
+ CIPHER is CBC-DES-MD5
+Everything up and running
+
+s_server -verify 0
+s_client
+ CONNECTED
+ CIPHER is CBC-DES-MD5
+Ok since no certificate was returned and we don't care.
+
+s_server -verify 0
+./s_client -cert client.PEM
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
+ issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify error:num=1:unable to get issuer certificate
+ verify return:1
+ CIPHER is CBC-DES-MD5
+Ok since we were only verifying to level 0
+
+s_server -verify 4
+s_client -cert client.PEM
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
+ issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify error:num=1:unable to get issuer certificate
+ verify return:0
+ ERROR
+ verify error:unable to get issuer certificate
+Bad because we could not authenticate the returned certificate.
+
+s_server -verify 4 -CApath .
+s_client -cert client.PEM
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
+ verify return:1
+ depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify return:1
+ CIPHER is CBC-DES-MD5
+Ok because we could authenticate the returned certificate :-).
+
+s_server -Verify 0 -CApath .
+s_client
+ CONNECTED
+ ERROR
+ SSL error:function is:REQUEST_CERTIFICATE
+ :error is :client end did not return a certificate
+Error because no certificate returned.
+
+s_server -Verify 4 -CApath .
+s_client -cert client.PEM
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
+ verify return:1
+ depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify return:1
+ CIPHER is CBC-DES-MD5
+Full authentication of the client.
+
+So in summary to do full authentication of both ends
+s_server -Verify 9 -CApath .
+s_client -cert client.PEM -CApath . -verify 9
+From the server side
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
+ verify return:1
+ depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify return:1
+ CIPHER is CBC-DES-MD5
+From the client side
+ CONNECTED
+ depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
+ verify return:1
+ depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
+ verify return:1
+ CIPHER is CBC-DES-MD5
+
+For general probing of the 'internet https' servers for the
+distribution area, run
+s_client -host www.netscape.com -port 443 -verify 4 -CApath ../rsa/hash
+Then enter
+GET /
+and you should be talking to the https server on that host.
+
+www.rsa.com was refusing to respond to connections on 443 when I was
+testing.
+
+have fun :-).
+
+eric
+
+==== a_verify.doc ========================================================
+
+From eay@mincom.com Fri Oct 4 18:29:06 1996
+Received: by orb.mincom.oz.au id AA29080
+ (5.65c/IDA-1.4.4 for eay); Fri, 4 Oct 1996 08:29:07 +1000
+Date: Fri, 4 Oct 1996 08:29:06 +1000 (EST)
+From: Eric Young <eay@mincom.oz.au>
+X-Sender: eay@orb
+To: wplatzer <wplatzer@iaik.tu-graz.ac.at>
+Cc: Eric Young <eay@mincom.oz.au>, SSL Mailing List <ssl-users@mincom.com>
+Subject: Re: Netscape's Public Key
+In-Reply-To: <19961003134837.NTM0049@iaik.tu-graz.ac.at>
+Message-Id: <Pine.SOL.3.91.961004081346.8018K-100000@orb>
+Mime-Version: 1.0
+Content-Type: TEXT/PLAIN; charset=US-ASCII
+Status: RO
+X-Status:
+
+On Thu, 3 Oct 1996, wplatzer wrote:
+> I get Public Key from Netscape (Gold 3.0b4), but cannot do anything
+> with it... It looks like (asn1parse):
+>
+> 0:d=0 hl=3 l=180 cons: SEQUENCE
+> 3:d=1 hl=2 l= 96 cons: SEQUENCE
+> 5:d=2 hl=2 l= 92 cons: SEQUENCE
+> 7:d=3 hl=2 l= 13 cons: SEQUENCE
+> 9:d=4 hl=2 l= 9 prim: OBJECT :rsaEncryption
+> 20:d=4 hl=2 l= 0 prim: NULL
+> 22:d=3 hl=2 l= 75 prim: BIT STRING
+> 99:d=2 hl=2 l= 0 prim: IA5STRING :
+> 101:d=1 hl=2 l= 13 cons: SEQUENCE
+> 103:d=2 hl=2 l= 9 prim: OBJECT :md5withRSAEncryption
+> 114:d=2 hl=2 l= 0 prim: NULL
+> 116:d=1 hl=2 l= 65 prim: BIT STRING
+>
+> The first BIT STRING is the public key and the second BIT STRING is
+> the signature.
+> But a public key consists of the public exponent and the modulus. Are
+> both numbers in the first BIT STRING?
+> Is there a document simply describing this coding stuff (checking
+> signature, get the public key, etc.)?
+
+Minimal in SSLeay. If you want to see what the modulus and exponent are,
+try asn1parse -offset 25 -length 75 <key.pem
+asn1parse will currently stuff up on the 'length 75' part (fixed in next
+release) but it will print the stuff. If you are after more
+documentation on ASN.1, have a look at www.rsa.com and get their PKCS
+documents, most of my initial work on SSLeay was done using them.
+
+As for SSLeay,
+util/crypto.num and util/ssl.num are lists of all exported functions in
+the library (but not macros :-(.
+
+The ones for extracting public keys from certificates and certificate
+requests are EVP_PKEY * X509_REQ_extract_key(X509_REQ *req);
+EVP_PKEY * X509_extract_key(X509 *x509);
+
+To verify a signature on a signed ASN.1 object
+int X509_verify(X509 *a,EVP_PKEY *key);
+int X509_REQ_verify(X509_REQ *a,EVP_PKEY *key);
+int X509_CRL_verify(X509_CRL *a,EVP_PKEY *key);
+int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *a,EVP_PKEY *key);
+
+I should mention that EVP_PKEY can be used to hold a public or a private key,
+since for things like RSA and DSS, a public key is just a subset of what
+is stored for the private key.
+
+To sign any of the above structures
+
+int X509_sign(X509 *a,EVP_PKEY *key,EVP_MD *md);
+int X509_REQ_sign(X509_REQ *a,EVP_PKEY *key,EVP_MD *md);
+int X509_CRL_sign(X509_CRL *a,EVP_PKEY *key,EVP_MD *md);
+int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *a,EVP_PKEY *key,EVP_MD *md);
+
+where md is the message digest to sign with.
+
+There are all defined in x509.h and all the _sign and _verify functions are
+actually macros to the ASN1_sign() and ASN1_verify() functions.
+These functions will put the correct algorithm identifiers in the correct
+places in the structures.
+
+eric
+--
+Eric Young | BOOL is tri-state according to Bill Gates.
+AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage().
+
+==== x509 =======================================================
+
+X509_verify()
+X509_sign()
+
+X509_get_version()
+X509_get_serialNumber()
+X509_get_issuer()
+X509_get_subject()
+X509_get_notBefore()
+X509_get_notAfter()
+X509_get_pubkey()
+
+X509_set_version()
+X509_set_serialNumber()
+X509_set_issuer()
+X509_set_subject()
+X509_set_notBefore()
+X509_set_notAfter()
+X509_set_pubkey()
+
+X509_get_extensions()
+X509_set_extensions()
+
+X509_EXTENSIONS_clear()
+X509_EXTENSIONS_retrieve()
+X509_EXTENSIONS_add()
+X509_EXTENSIONS_delete()
+
+==== x509 attribute ================================================
+
+PKCS7
+ STACK of X509_ATTRIBUTES
+ ASN1_OBJECT
+ STACK of ASN1_TYPE
+
+So it is
+
+p7.xa[].obj
+p7.xa[].data[]
+
+get_obj_by_nid(STACK , nid)
+get_num_by_nid(STACK , nid)
+get_data_by_nid(STACK , nid, index)
+
+X509_ATTRIBUTE *X509_ATTRIBUTE_new(void );
+void X509_ATTRIBUTE_free(X509_ATTRIBUTE *a);
+
+X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **ex,
+ int nid, STACK *value);
+
+X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **ex,
+ int nid, STACK *value);
+
+int X509_ATTRIBUTE_set_object(X509_ATTRIBUTE *ex,ASN1_OBJECT *obj);
+int X509_ATTRIBUTE_add_data(X509_ATTRIBUTE *ex, int index,
+ ASN1_TYPE *value);
+
+ASN1_OBJECT * X509_ATTRIBUTE_get_object(X509_ATTRIBUTE *ex);
+int X509_ATTRIBUTE_get_num(X509_ATTRIBUTE *ne);
+ASN1_TYPE * X509_ATTRIBUTE_get_data(X509_ATTRIBUTE *ne,int index);
+
+ASN1_TYPE * X509_ATTRIBUTE_get_data_by_NID(X509_ATTRIBUTE *ne,
+ ASN1_OBJECT *obj);
+
+X509_ATTRIBUTE *PKCS7_get_s_att_by_NID(PKCS7 *p7,int nid);
+X509_ATTRIBUTE *PKCS7_get_u_att_by_NID(PKCS7 *p7,int nid);
+
+==== x509 v3 ========================================================
+
+The 'new' system.
+
+The X509_EXTENSION_METHOD includes extensions and attributes and/or names.
+Basically everthing that can be added to an X509 with an OID identifying it.
+
+It operates via 2 methods per object id.
+int a2i_XXX(X509 *x,char *str,int len);
+int i2a_XXX(BIO *bp,X509 *x);
+
+The a2i_XXX function will add the object with a value converted from the
+string into the X509. Len can be -1 in which case the length is calculated
+via strlen(str). Applications can always use direct knowledge to load and
+unload the relevent objects themselves.
+
+i2a_XXX will print to the passed BIO, a text representation of the
+relevet object. Use a memory BIO if you want it printed to a buffer :-).
+
+X509_add_by_NID(X509 *x,int nid,char *str,int len);
+X509_add_by_OBJ(X509 *x,ASN1_OBJECT *obj,char *str,int len);
+
+X509_print_by_name(BIO *bp,X509 *x);
+X509_print_by_NID(BIO *bp,X509 *x);
+X509_print_by_OBJ(BIO *bp,X509 *x);
+
+==== verify ========================================================
+
+X509_verify_cert_chain(
+ CERT_STORE *cert_store,
+ STACK /* X509 */ *certs,
+ int *verify_result,
+ int (*verify_error_callback)()
+ char *argument_to_callback, /* SSL */
+
+app_verify_callback(
+ char *app_verify_arg, /* from SSL_CTX */
+ STACK /* X509 */ *certs,
+ int *verify_result,
+ int (*verify_error_callback)()
+ SSL *s,
+
+int X509_verify_cert(
+ CERT_STORE *cert_store,
+ X509 *x509,
+ int *verify_result,
+ int (*verify_error_callback)(),
+ char *arg,
+
+==== apps.doc ========================================================
+
+The applications
+
+Ok, where to begin....
+In the begining, when SSLeay was small (April 1995), there
+were but few applications, they did happily cohabit in
+the one bin directory. Then over time, they did multiply and grow,
+and they started to look like microsoft software; 500k to print 'hello world'.
+A new approach was needed. They were coalessed into one 'Monolithic'
+application, ssleay. This one program is composed of many programs that
+can all be compiled independantly.
+
+ssleay has 3 modes of operation.
+1) If the ssleay binaray has the name of one of its component programs, it
+executes that program and then exits. This can be achieve by using hard or
+symbolic links, or failing that, just renaming the binary.
+2) If the first argument to ssleay is the name of one of the component
+programs, that program runs that program and then exits.
+3) If there are no arguments, ssleay enters a 'command' mode. Each line is
+interpreted as a program name plus arguments. After each 'program' is run,
+ssleay returns to the comand line.
+
+dgst - message digests
+enc - encryption and base64 encoding
+
+ans1parse - 'pulls' appart ASN.1 encoded objects like certificates.
+
+dh - Diffle-Hellman parameter manipulation.
+rsa - RSA manipulations.
+crl - Certificate revokion list manipulations
+x509 - X509 cert fiddles, including signing.
+pkcs7 - pkcs7 manipulation, only DER versions right now.
+
+genrsa - generate an RSA private key.
+gendh - Generate a set of Diffle-Hellman parameters.
+req - Generate a PKCS#10 object, a certificate request.
+
+s_client - SSL client program
+s_server - SSL server program
+s_time - A SSL protocol timing program
+s_mult - Another SSL server, but it multiplexes
+ connections.
+s_filter - under development
+
+errstr - Convert SSLeay error numbers to strings.
+ca - Sign certificate requests, and generate
+ certificate revokion lists
+crl2pkcs7 - put a crl and certifcates into a pkcs7 object.
+speed - Benchmark the ciphers.
+verify - Check certificates
+hashdir - under development
+
+[ there a now a few more options, play with the program to see what they
+ are ]
+
+==== asn1.doc ========================================================
+
+The ASN.1 Routines.
+
+ASN.1 is a specification for how to encode structured 'data' in binary form.
+The approach I have take to the manipulation of structures and their encoding
+into ASN.1 is as follows.
+
+For each distinct structure there are 4 function of the following form
+TYPE *TYPE_new(void);
+void TYPE_free(TYPE *);
+TYPE *d2i_TYPE(TYPE **a,unsigned char **pp,long length);
+long i2d_TYPE(TYPE *a,unsigned char **pp); /* CHECK RETURN VALUE */
+
+where TYPE is the type of the 'object'. The TYPE that have these functions
+can be in one of 2 forms, either the internal C malloc()ed data structure
+or in the DER (a variant of ASN.1 encoding) binary encoding which is just
+an array of unsigned bytes. The 'i2d' functions converts from the internal
+form to the DER form and the 'd2i' functions convert from the DER form to
+the internal form.
+
+The 'new' function returns a malloc()ed version of the structure with all
+substructures either created or left as NULL pointers. For 'optional'
+fields, they are normally left as NULL to indicate no value. For variable
+size sub structures (often 'SET OF' or 'SEQUENCE OF' in ASN.1 syntax) the
+STACK data type is used to hold the values. Have a read of stack.doc
+and have a look at the relevant header files to see what I mean. If there
+is an error while malloc()ing the structure, NULL is returned.
+
+The 'free' function will free() all the sub components of a particular
+structure. If any of those sub components have been 'removed', replace
+them with NULL pointers, the 'free' functions are tolerant of NULL fields.
+
+The 'd2i' function copies a binary representation into a C structure. It
+operates as follows. 'a' is a pointer to a pointer to
+the structure to populate, 'pp' is a pointer to a pointer to where the DER
+byte string is located and 'length' is the length of the '*pp' data.
+If there are no errors, a pointer to the populated structure is returned.
+If there is an error, NULL is returned. Errors can occur because of
+malloc() failures but normally they will be due to syntax errors in the DER
+encoded data being parsed. It is also an error if there was an
+attempt to read more that 'length' bytes from '*p'. If
+everything works correctly, the value in '*p' is updated
+to point at the location just beyond where the DER
+structure was read from. In this way, chained calls to 'd2i' type
+functions can be made, with the pointer into the 'data' array being
+'walked' along the input byte array.
+Depending on the value passed for 'a', different things will be done. If
+'a' is NULL, a new structure will be malloc()ed and returned. If '*a' is
+NULL, a new structure will be malloc()ed and put into '*a' and returned.
+If '*a' is not NULL, the structure in '*a' will be populated, or in the
+case of an error, free()ed and then returned.
+Having these semantics means that a structure
+can call a 'd2i' function to populate a field and if the field is currently
+NULL, the structure will be created.
+
+The 'i2d' function type is used to copy a C structure to a byte array.
+The parameter 'a' is the structure to convert and '*p' is where to put it.
+As for the 'd2i' type structure, 'p' is updated to point after the last
+byte written. If p is NULL, no data is written. The function also returns
+the number of bytes written. Where this becomes useful is that if the
+function is called with a NULL 'p' value, the length is returned. This can
+then be used to malloc() an array of bytes and then the same function can
+be recalled passing the malloced array to be written to. e.g.
+
+int len;
+unsigned char *bytes,*p;
+len=i2d_X509(x,NULL); /* get the size of the ASN1 encoding of 'x' */
+if ((bytes=(unsigned char *)malloc(len)) == NULL)
+ goto err;
+p=bytes;
+i2d_X509(x,&p);
+
+Please note that a new variable, 'p' was passed to i2d_X509. After the
+call to i2d_X509 p has been incremented by len bytes.
+
+Now the reason for this functional organisation is that it allows nested
+structures to be built up by calling these functions as required. There
+are various macros used to help write the general 'i2d', 'd2i', 'new' and
+'free' functions. They are discussed in another file and would only be
+used by some-one wanting to add new structures to the library. As you
+might be able to guess, the process of writing ASN.1 files can be a bit CPU
+expensive for complex structures. I'm willing to live with this since the
+simpler library code make my life easier and hopefully most programs using
+these routines will have their execution profiles dominated by cipher or
+message digest routines.
+What follows is a list of 'TYPE' values and the corresponding ASN.1
+structure and where it is used.
+
+TYPE ASN.1
+ASN1_INTEGER INTEGER
+ASN1_BIT_STRING BIT STRING
+ASN1_OCTET_STRING OCTET STRING
+ASN1_OBJECT OBJECT IDENTIFIER
+ASN1_PRINTABLESTRING PrintableString
+ASN1_T61STRING T61String
+ASN1_IA5STRING IA5String
+ASN1_UTCTIME UTCTime
+ASN1_TYPE Any of the above mentioned types plus SEQUENCE and SET
+
+Most of the above mentioned types are actualled stored in the
+ASN1_BIT_STRING type and macros are used to differentiate between them.
+The 3 types used are
+
+typedef struct asn1_object_st
+ {
+ /* both null if a dynamic ASN1_OBJECT, one is
+ * defined if a 'static' ASN1_OBJECT */
+ char *sn,*ln;
+ int nid;
+ int length;
+ unsigned char *data;
+ } ASN1_OBJECT;
+This is used to store ASN1 OBJECTS. Read 'objects.doc' for details ono
+routines to manipulate this structure. 'sn' and 'ln' are used to hold text
+strings that represent the object (short name and long or lower case name).
+These are used by the 'OBJ' library. 'nid' is a number used by the OBJ
+library to uniquely identify objects. The ASN1 routines will populate the
+'length' and 'data' fields which will contain the bit string representing
+the object.
+
+typedef struct asn1_bit_string_st
+ {
+ int length;
+ int type;
+ unsigned char *data;
+ } ASN1_BIT_STRING;
+This structure is used to hold all the other base ASN1 types except for
+ASN1_UTCTIME (which is really just a 'char *'). Length is the number of
+bytes held in data and type is the ASN1 type of the object (there is a list
+in asn1.h).
+
+typedef struct asn1_type_st
+ {
+ int type;
+ union {
+ char *ptr;
+ ASN1_INTEGER * integer;
+ ASN1_BIT_STRING * bit_string;
+ ASN1_OCTET_STRING * octet_string;
+ ASN1_OBJECT * object;
+ ASN1_PRINTABLESTRING * printablestring;
+ ASN1_T61STRING * t61string;
+ ASN1_IA5STRING * ia5string;
+ ASN1_UTCTIME * utctime;
+ ASN1_BIT_STRING * set;
+ ASN1_BIT_STRING * sequence;
+ } value;
+ } ASN1_TYPE;
+This structure is used in a few places when 'any' type of object can be
+expected.
+
+X509 Certificate
+X509_CINF CertificateInfo
+X509_ALGOR AlgorithmIdentifier
+X509_NAME Name
+X509_NAME_ENTRY A single sub component of the name.
+X509_VAL Validity
+X509_PUBKEY SubjectPublicKeyInfo
+The above mentioned types are declared in x509.h. They are all quite
+straight forward except for the X509_NAME/X509_NAME_ENTRY pair.
+A X509_NAME is a STACK (see stack.doc) of X509_NAME_ENTRY's.
+typedef struct X509_name_entry_st
+ {
+ ASN1_OBJECT *object;
+ ASN1_BIT_STRING *value;
+ int set;
+ int size; /* temp variable */
+ } X509_NAME_ENTRY;
+The size is a temporary variable used by i2d_NAME and set is the set number
+for the particular NAME_ENTRY. A X509_NAME is encoded as a sequence of
+sequence of sets. Normally each set contains only a single item.
+Sometimes it contains more. Normally throughout this library there will be
+only one item per set. The set field contains the 'set' that this entry is
+a member of. So if you have just created a X509_NAME structure and
+populated it with X509_NAME_ENTRYs, you should then traverse the X509_NAME
+(which is just a STACK) and set the 'set/' field to incrementing numbers.
+For more details on why this is done, read the ASN.1 spec for Distinguished
+Names.
+
+X509_REQ CertificateRequest
+X509_REQ_INFO CertificateRequestInfo
+These are used to hold certificate requests.
+
+X509_CRL CertificateRevocationList
+These are used to hold a certificate revocation list
+
+RSAPrivateKey PrivateKeyInfo
+RSAPublicKey PublicKeyInfo
+Both these 'function groups' operate on 'RSA' structures (see rsa.doc).
+The difference is that the RSAPublicKey operations only manipulate the m
+and e fields in the RSA structure.
+
+DSAPrivateKey DSS private key
+DSAPublicKey DSS public key
+Both these 'function groups' operate on 'DSS' structures (see dsa.doc).
+The difference is that the RSAPublicKey operations only manipulate the
+XXX fields in the DSA structure.
+
+DHparams DHParameter
+This is used to hold the p and g value for The Diffie-Hellman operation.
+The function deal with the 'DH' strucure (see dh.doc).
+
+Now all of these function types can be used with several other functions to give
+quite useful set of general manipulation routines. Normally one would
+not uses these functions directly but use them via macros.
+
+char *ASN1_dup(int (*i2d)(),char *(*d2i)(),char *x);
+'x' is the input structure case to a 'char *', 'i2d' is the 'i2d_TYPE'
+function for the type that 'x' is and d2i is the 'd2i_TYPE' function for the
+type that 'x' is. As is obvious from the parameters, this function
+duplicates the strucutre by transforming it into the DER form and then
+re-loading it into a new strucutre and returning the new strucutre. This
+is obviously a bit cpu intensive but when faced with a complex dynamic
+structure this is the simplest programming approach. There are macros for
+duplicating the major data types but is simple to add extras.
+
+char *ASN1_d2i_fp(char *(*new)(),char *(*d2i)(),FILE *fp,unsigned char **x);
+'x' is a pointer to a pointer of the 'desired type'. new and d2i are the
+corresponding 'TYPE_new' and 'd2i_TYPE' functions for the type and 'fp' is
+an open file pointer to read from. This function reads from 'fp' as much
+data as it can and then uses 'd2i' to parse the bytes to load and return
+the parsed strucutre in 'x' (if it was non-NULL) and to actually return the
+strucutre. The behavior of 'x' is as per all the other d2i functions.
+
+char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x);
+The 'BIO' is the new IO type being used in SSLeay (see bio.doc). This
+function is the same as ASN1_d2i_fp() except for the BIO argument.
+ASN1_d2i_fp() actually calls this function.
+
+int ASN1_i2d_fp(int (*i2d)(),FILE *out,unsigned char *x);
+'x' is converted to bytes by 'i2d' and then written to 'out'. ASN1_i2d_fp
+and ASN1_d2i_fp are not really symetric since ASN1_i2d_fp will read all
+available data from the file pointer before parsing a single item while
+ASN1_i2d_fp can be used to write a sequence of data objects. To read a
+series of objects from a file I would sugest loading the file into a buffer
+and calling the relevent 'd2i' functions.
+
+char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x);
+This function is the same as ASN1_i2d_fp() except for the BIO argument.
+ASN1_i2d_fp() actually calls this function.
+
+char * PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)());
+This function will read the next PEM encoded (base64) object of the same
+type as 'x' (loaded by the d2i function). 'name' is the name that is in
+the '-----BEGIN name-----' that designates the start of that object type.
+If the data is encrypted, 'cb' will be called to prompt for a password. If
+it is NULL a default function will be used to prompt from the password.
+'x' is delt with as per the standard 'd2i' function interface. This
+function can be used to read a series of objects from a file. While any
+data type can be encrypted (see PEM_ASN1_write) only RSA private keys tend
+to be encrypted.
+
+char * PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *fp,
+ char **x,int (*cb)());
+Same as PEM_ASN1_read() except using a BIO. This is called by
+PEM_ASN1_read().
+
+int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,EVP_CIPHER *enc,
+ unsigned char *kstr,int klen,int (*callback)());
+
+int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *fp,
+ char *x,EVP_CIPHER *enc,unsigned char *kstr,int klen,
+ int (*callback)());
+
+int ASN1_sign(int (*i2d)(), X509_ALGOR *algor1, X509_ALGOR *algor2,
+ ASN1_BIT_STRING *signature, char *data, RSA *rsa, EVP_MD *type);
+int ASN1_verify(int (*i2d)(), X509_ALGOR *algor1,
+ ASN1_BIT_STRING *signature,char *data, RSA *rsa);
+
+int ASN1_BIT_STRING_cmp(ASN1_BIT_STRING *a, ASN1_BIT_STRING *b);
+ASN1_BIT_STRING *ASN1_BIT_STRING_type_new(int type );
+
+int ASN1_UTCTIME_check(ASN1_UTCTIME *a);
+void ASN1_UTCTIME_print(BIO *fp,ASN1_UTCTIME *a);
+ASN1_UTCTIME *ASN1_UTCTIME_dup(ASN1_UTCTIME *a);
+
+ASN1_BIT_STRING *d2i_asn1_print_type(ASN1_BIT_STRING **a,unsigned char **pp,
+ long length,int type);
+
+int i2d_ASN1_SET(STACK *a, unsigned char **pp,
+ int (*func)(), int ex_tag, int ex_class);
+STACK * d2i_ASN1_SET(STACK **a, unsigned char **pp, long length,
+ char *(*func)(), int ex_tag, int ex_class);
+
+int i2a_ASN1_OBJECT(BIO *bp,ASN1_OBJECT *object);
+int i2a_ASN1_INTEGER(BIO *bp, ASN1_INTEGER *a);
+int a2i_ASN1_INTEGER(BIO *bp,ASN1_INTEGER *bs,char *buf,int size);
+
+int ASN1_INTEGER_set(ASN1_INTEGER *a, long v);
+long ASN1_INTEGER_get(ASN1_INTEGER *a);
+ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai);
+BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn);
+
+/* given a string, return the correct type. Max is the maximum number
+ * of bytes to parse. It stops parsing when 'max' bytes have been
+ * processed or a '\0' is hit */
+int ASN1_PRINTABLE_type(unsigned char *s,int max);
+
+void ASN1_parse(BIO *fp,unsigned char *pp,long len);
+
+int i2d_ASN1_bytes(ASN1_BIT_STRING *a, unsigned char **pp, int tag, int class);
+ASN1_BIT_STRING *d2i_ASN1_bytes(ASN1_OCTET_STRING **a, unsigned char **pp,
+ long length, int Ptag, int Pclass);
+
+/* PARSING */
+int asn1_Finish(ASN1_CTX *c);
+
+/* SPECIALS */
+int ASN1_get_object(unsigned char **pp, long *plength, int *ptag,
+ int *pclass, long omax);
+int ASN1_check_infinite_end(unsigned char **p,long len);
+void ASN1_put_object(unsigned char **pp, int constructed, int length,
+ int tag, int class);
+int ASN1_object_size(int constructed, int length, int tag);
+
+X509 * X509_get_cert(CERTIFICATE_CTX *ctx,X509_NAME * name,X509 *tmp_x509);
+int X509_add_cert(CERTIFICATE_CTX *ctx,X509 *);
+
+char * X509_cert_verify_error_string(int n);
+int X509_add_cert_file(CERTIFICATE_CTX *c,char *file, int type);
+char * X509_gmtime (char *s, long adj);
+int X509_add_cert_dir (CERTIFICATE_CTX *c,char *dir, int type);
+int X509_load_verify_locations (CERTIFICATE_CTX *ctx,
+ char *file_env, char *dir_env);
+int X509_set_default_verify_paths(CERTIFICATE_CTX *cts);
+X509 * X509_new_D2i_X509(int len, unsigned char *p);
+char * X509_get_default_cert_area(void );
+char * X509_get_default_cert_dir(void );
+char * X509_get_default_cert_file(void );
+char * X509_get_default_cert_dir_env(void );
+char * X509_get_default_cert_file_env(void );
+char * X509_get_default_private_dir(void );
+X509_REQ *X509_X509_TO_req(X509 *x, RSA *rsa);
+int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)());
+
+CERTIFICATE_CTX *CERTIFICATE_CTX_new();
+void CERTIFICATE_CTX_free(CERTIFICATE_CTX *c);
+
+void X509_NAME_print(BIO *fp, X509_NAME *name, int obase);
+int X509_print_fp(FILE *fp,X509 *x);
+int X509_print(BIO *fp,X509 *x);
+
+X509_INFO * X509_INFO_new(void);
+void X509_INFO_free(X509_INFO *a);
+
+char * X509_NAME_oneline(X509_NAME *a);
+
+#define X509_verify(x,rsa)
+#define X509_REQ_verify(x,rsa)
+#define X509_CRL_verify(x,rsa)
+
+#define X509_sign(x,rsa,md)
+#define X509_REQ_sign(x,rsa,md)
+#define X509_CRL_sign(x,rsa,md)
+
+#define X509_dup(x509)
+#define d2i_X509_fp(fp,x509)
+#define i2d_X509_fp(fp,x509)
+#define d2i_X509_bio(bp,x509)
+#define i2d_X509_bio(bp,x509)
+
+#define X509_CRL_dup(crl)
+#define d2i_X509_CRL_fp(fp,crl)
+#define i2d_X509_CRL_fp(fp,crl)
+#define d2i_X509_CRL_bio(bp,crl)
+#define i2d_X509_CRL_bio(bp,crl)
+
+#define X509_REQ_dup(req)
+#define d2i_X509_REQ_fp(fp,req)
+#define i2d_X509_REQ_fp(fp,req)
+#define d2i_X509_REQ_bio(bp,req)
+#define i2d_X509_REQ_bio(bp,req)
+
+#define RSAPrivateKey_dup(rsa)
+#define d2i_RSAPrivateKey_fp(fp,rsa)
+#define i2d_RSAPrivateKey_fp(fp,rsa)
+#define d2i_RSAPrivateKey_bio(bp,rsa)
+#define i2d_RSAPrivateKey_bio(bp,rsa)
+
+#define X509_NAME_dup(xn)
+#define X509_NAME_ENTRY_dup(ne)
+
+void X509_REQ_print_fp(FILE *fp,X509_REQ *req);
+void X509_REQ_print(BIO *fp,X509_REQ *req);
+
+RSA *X509_REQ_extract_key(X509_REQ *req);
+RSA *X509_extract_key(X509 *x509);
+
+int X509_issuer_and_serial_cmp(X509 *a, X509 *b);
+unsigned long X509_issuer_and_serial_hash(X509 *a);
+
+X509_NAME * X509_get_issuer_name(X509 *a);
+int X509_issuer_name_cmp(X509 *a, X509 *b);
+unsigned long X509_issuer_name_hash(X509 *a);
+
+X509_NAME * X509_get_subject_name(X509 *a);
+int X509_subject_name_cmp(X509 *a,X509 *b);
+unsigned long X509_subject_name_hash(X509 *x);
+
+int X509_NAME_cmp (X509_NAME *a, X509_NAME *b);
+unsigned long X509_NAME_hash(X509_NAME *x);
+
+
+==== bio.doc ========================================================
+
+BIO Routines
+
+This documentation is rather sparse, you are probably best
+off looking at the code for specific details.
+
+The BIO library is a IO abstraction that was originally
+inspired by the need to have callbacks to perform IO to FILE
+pointers when using Windows 3.1 DLLs. There are two types
+of BIO; a source/sink type and a filter type.
+The source/sink methods are as follows:
+- BIO_s_mem() memory buffer - a read/write byte array that
+ grows until memory runs out :-).
+- BIO_s_file() FILE pointer - A wrapper around the normal
+ 'FILE *' commands, good for use with stdin/stdout.
+- BIO_s_fd() File descriptor - A wrapper around file
+ descriptors, often used with pipes.
+- BIO_s_socket() Socket - Used around sockets. It is
+ mostly in the Microsoft world that sockets are different
+ from file descriptors and there are all those ugly winsock
+ commands.
+- BIO_s_null() Null - read nothing and write nothing.; a
+ useful endpoint for filter type BIO's specifically things
+ like the message digest BIO.
+
+The filter types are
+- BIO_f_buffer() IO buffering - does output buffering into
+ larger chunks and performs input buffering to allow gets()
+ type functions.
+- BIO_f_md() Message digest - a transparent filter that can
+ be asked to return a message digest for the data that has
+ passed through it.
+- BIO_f_cipher() Encrypt or decrypt all data passing
+ through the filter.
+- BIO_f_base64() Base64 decode on read and encode on write.
+- BIO_f_ssl() A filter that performs SSL encryption on the
+ data sent through it.
+
+Base BIO functions.
+The BIO library has a set of base functions that are
+implemented for each particular type. Filter BIOs will
+normally call the equivalent function on the source/sink BIO
+that they are layered on top of after they have performed
+some modification to the data stream. Multiple filter BIOs
+can be 'push' into a stack of modifers, so to read from a
+file, unbase64 it, then decrypt it, a BIO_f_cipher,
+BIO_f_base64 and a BIO_s_file would probably be used. If a
+sha-1 and md5 message digest needed to be generated, a stack
+two BIO_f_md() BIOs and a BIO_s_null() BIO could be used.
+The base functions are
+- BIO *BIO_new(BIO_METHOD *type); Create a new BIO of type 'type'.
+- int BIO_free(BIO *a); Free a BIO structure. Depending on
+ the configuration, this will free the underlying data
+ object for a source/sink BIO.
+- int BIO_read(BIO *b, char *data, int len); Read upto 'len'
+ bytes into 'data'.
+- int BIO_gets(BIO *bp,char *buf, int size); Depending on
+ the BIO, this can either be a 'get special' or a get one
+ line of data, as per fgets();
+- int BIO_write(BIO *b, char *data, int len); Write 'len'
+ bytes from 'data' to the 'b' BIO.
+- int BIO_puts(BIO *bp,char *buf); Either a 'put special' or
+ a write null terminated string as per fputs().
+- long BIO_ctrl(BIO *bp,int cmd,long larg,char *parg); A
+ control function which is used to manipulate the BIO
+ structure and modify it's state and or report on it. This
+ function is just about never used directly, rather it
+ should be used in conjunction with BIO_METHOD specific
+ macros.
+- BIO *BIO_push(BIO *new_top, BIO *old); new_top is apped to the
+ top of the 'old' BIO list. new_top should be a filter BIO.
+ All writes will go through 'new_top' first and last on read.
+ 'old' is returned.
+- BIO *BIO_pop(BIO *bio); the new topmost BIO is returned, NULL if
+ there are no more.
+
+If a particular low level BIO method is not supported
+(normally BIO_gets()), -2 will be returned if that method is
+called. Otherwise the IO methods (read, write, gets, puts)
+will return the number of bytes read or written, and 0 or -1
+for error (or end of input). For the -1 case,
+BIO_should_retry(bio) can be called to determine if it was a
+genuine error or a temporary problem. -2 will also be
+returned if the BIO has not been initalised yet, in all
+cases, the correct error codes are set (accessible via the
+ERR library).
+
+
+The following functions are convenience functions:
+- int BIO_printf(BIO *bio, char * format, ..); printf but
+ to a BIO handle.
+- long BIO_ctrl_int(BIO *bp,int cmd,long larg,int iarg); a
+ convenience function to allow a different argument types
+ to be passed to BIO_ctrl().
+- int BIO_dump(BIO *b,char *bytes,int len); output 'len'
+ bytes from 'bytes' in a hex dump debug format.
+- long BIO_debug_callback(BIO *bio, int cmd, char *argp, int
+ argi, long argl, long ret) - a default debug BIO callback,
+ this is mentioned below. To use this one normally has to
+ use the BIO_set_callback_arg() function to assign an
+ output BIO for the callback to use.
+- BIO *BIO_find_type(BIO *bio,int type); when there is a 'stack'
+ of BIOs, this function scan the list and returns the first
+ that is of type 'type', as listed in buffer.h under BIO_TYPE_XXX.
+- void BIO_free_all(BIO *bio); Free the bio and all other BIOs
+ in the list. It walks the bio->next_bio list.
+
+
+
+Extra commands are normally implemented as macros calling BIO_ctrl().
+- BIO_number_read(BIO *bio) - the number of bytes processed
+ by BIO_read(bio,.).
+- BIO_number_written(BIO *bio) - the number of bytes written
+ by BIO_write(bio,.).
+- BIO_reset(BIO *bio) - 'reset' the BIO.
+- BIO_eof(BIO *bio) - non zero if we are at the current end
+ of input.
+- BIO_set_close(BIO *bio, int close_flag) - set the close flag.
+- BIO_get_close(BIO *bio) - return the close flag.
+ BIO_pending(BIO *bio) - return the number of bytes waiting
+ to be read (normally buffered internally).
+- BIO_flush(BIO *bio) - output any data waiting to be output.
+- BIO_should_retry(BIO *io) - after a BIO_read/BIO_write
+ operation returns 0 or -1, a call to this function will
+ return non zero if you should retry the call later (this
+ is for non-blocking IO).
+- BIO_should_read(BIO *io) - we should retry when data can
+ be read.
+- BIO_should_write(BIO *io) - we should retry when data can
+ be written.
+- BIO_method_name(BIO *io) - return a string for the method name.
+- BIO_method_type(BIO *io) - return the unique ID of the BIO method.
+- BIO_set_callback(BIO *io, long (*callback)(BIO *io, int
+ cmd, char *argp, int argi, long argl, long ret); - sets
+ the debug callback.
+- BIO_get_callback(BIO *io) - return the assigned function
+ as mentioned above.
+- BIO_set_callback_arg(BIO *io, char *arg) - assign some
+ data against the BIO. This is normally used by the debug
+ callback but could in reality be used for anything. To
+ get an idea of how all this works, have a look at the code
+ in the default debug callback mentioned above. The
+ callback can modify the return values.
+
+Details of the BIO_METHOD structure.
+typedef struct bio_method_st
+ {
+ int type;
+ char *name;
+ int (*bwrite)();
+ int (*bread)();
+ int (*bputs)();
+ int (*bgets)();
+ long (*ctrl)();
+ int (*create)();
+ int (*destroy)();
+ } BIO_METHOD;
+
+The 'type' is the numeric type of the BIO, these are listed in buffer.h;
+'Name' is a textual representation of the BIO 'type'.
+The 7 function pointers point to the respective function
+methods, some of which can be NULL if not implemented.
+The BIO structure
+typedef struct bio_st
+ {
+ BIO_METHOD *method;
+ long (*callback)(BIO * bio, int mode, char *argp, int
+ argi, long argl, long ret);
+ char *cb_arg; /* first argument for the callback */
+ int init;
+ int shutdown;
+ int flags; /* extra storage */
+ int num;
+ char *ptr;
+ struct bio_st *next_bio; /* used by filter BIOs */
+ int references;
+ unsigned long num_read;
+ unsigned long num_write;
+ } BIO;
+
+- 'Method' is the BIO method.
+- 'callback', when configured, is called before and after
+ each BIO method is called for that particular BIO. This
+ is intended primarily for debugging and of informational feedback.
+- 'init' is 0 when the BIO can be used for operation.
+ Often, after a BIO is created, a number of operations may
+ need to be performed before it is available for use. An
+ example is for BIO_s_sock(). A socket needs to be
+ assigned to the BIO before it can be used.
+- 'shutdown', this flag indicates if the underlying
+ comunication primative being used should be closed/freed
+ when the BIO is closed.
+- 'flags' is used to hold extra state. It is primarily used
+ to hold information about why a non-blocking operation
+ failed and to record startup protocol information for the
+ SSL BIO.
+- 'num' and 'ptr' are used to hold instance specific state
+ like file descriptors or local data structures.
+- 'next_bio' is used by filter BIOs to hold the pointer of the
+ next BIO in the chain. written data is sent to this BIO and
+ data read is taken from it.
+- 'references' is used to indicate the number of pointers to
+ this structure. This needs to be '1' before a call to
+ BIO_free() is made if the BIO_free() function is to
+ actually free() the structure, otherwise the reference
+ count is just decreased. The actual BIO subsystem does
+ not really use this functionality but it is useful when
+ used in more advanced applicaion.
+- num_read and num_write are the total number of bytes
+ read/written via the 'read()' and 'write()' methods.
+
+BIO_ctrl operations.
+The following is the list of standard commands passed as the
+second parameter to BIO_ctrl() and should be supported by
+all BIO as best as possible. Some are optional, some are
+manditory, in any case, where is makes sense, a filter BIO
+should pass such requests to underlying BIO's.
+- BIO_CTRL_RESET - Reset the BIO back to an initial state.
+- BIO_CTRL_EOF - return 0 if we are not at the end of input,
+ non 0 if we are.
+- BIO_CTRL_INFO - BIO specific special command, normal
+ information return.
+- BIO_CTRL_SET - set IO specific parameter.
+- BIO_CTRL_GET - get IO specific parameter.
+- BIO_CTRL_GET_CLOSE - Get the close on BIO_free() flag, one
+ of BIO_CLOSE or BIO_NOCLOSE.
+- BIO_CTRL_SET_CLOSE - Set the close on BIO_free() flag.
+- BIO_CTRL_PENDING - Return the number of bytes available
+ for instant reading
+- BIO_CTRL_FLUSH - Output pending data, return number of bytes output.
+- BIO_CTRL_SHOULD_RETRY - After an IO error (-1 returned)
+ should we 'retry' when IO is possible on the underlying IO object.
+- BIO_CTRL_RETRY_TYPE - What kind of IO are we waiting on.
+
+The following command is a special BIO_s_file() specific option.
+- BIO_CTRL_SET_FILENAME - specify a file to open for IO.
+
+The BIO_CTRL_RETRY_TYPE needs a little more explanation.
+When performing non-blocking IO, or say reading on a memory
+BIO, when no data is present (or cannot be written),
+BIO_read() and/or BIO_write() will return -1.
+BIO_should_retry(bio) will return true if this is due to an
+IO condition rather than an actual error. In the case of
+BIO_s_mem(), a read when there is no data will return -1 and
+a should retry when there is more 'read' data.
+The retry type is deduced from 2 macros
+BIO_should_read(bio) and BIO_should_write(bio).
+Now while it may appear obvious that a BIO_read() failure
+should indicate that a retry should be performed when more
+read data is available, this is often not true when using
+things like an SSL BIO. During the SSL protocol startup
+multiple reads and writes are performed, triggered by any
+SSL_read or SSL_write.
+So to write code that will transparently handle either a
+socket or SSL BIO,
+ i=BIO_read(bio,..)
+ if (I == -1)
+ {
+ if (BIO_should_retry(bio))
+ {
+ if (BIO_should_read(bio))
+ {
+ /* call us again when BIO can be read */
+ }
+ if (BIO_should_write(bio))
+ {
+ /* call us again when BIO can be written */
+ }
+ }
+ }
+
+At this point in time only read and write conditions can be
+used but in the future I can see the situation for other
+conditions, specifically with SSL there could be a condition
+of a X509 certificate lookup taking place and so the non-
+blocking BIO_read would require a retry when the certificate
+lookup subsystem has finished it's lookup. This is all
+makes more sense and is easy to use in a event loop type
+setup.
+When using the SSL BIO, either SSL_read() or SSL_write()s
+can be called during the protocol startup and things will
+still work correctly.
+The nice aspect of the use of the BIO_should_retry() macro
+is that all the errno codes that indicate a non-fatal error
+are encapsulated in one place. The Windows specific error
+codes and WSAGetLastError() calls are also hidden from the
+application.
+
+Notes on each BIO method.
+Normally buffer.h is just required but depending on the
+BIO_METHOD, ssl.h or evp.h will also be required.
+
+BIO_METHOD *BIO_s_mem(void);
+- BIO_set_mem_buf(BIO *bio, BUF_MEM *bm, int close_flag) -
+ set the underlying BUF_MEM structure for the BIO to use.
+- BIO_get_mem_ptr(BIO *bio, char **pp) - if pp is not NULL,
+ set it to point to the memory array and return the number
+ of bytes available.
+A read/write BIO. Any data written is appended to the
+memory array and any read is read from the front. This BIO
+can be used for read/write at the same time. BIO_gets() is
+supported in the fgets() sense.
+BIO_CTRL_INFO can be used to retrieve pointers to the memory
+buffer and it's length.
+
+BIO_METHOD *BIO_s_file(void);
+- BIO_set_fp(BIO *bio, FILE *fp, int close_flag) - set 'FILE *' to use.
+- BIO_get_fp(BIO *bio, FILE **fp) - get the 'FILE *' in use.
+- BIO_read_filename(BIO *bio, char *name) - read from file.
+- BIO_write_filename(BIO *bio, char *name) - write to file.
+- BIO_append_filename(BIO *bio, char *name) - append to file.
+This BIO sits over the normal system fread()/fgets() type
+functions. Gets() is supported. This BIO in theory could be
+used for read and write but it is best to think of each BIO
+of this type as either a read or a write BIO, not both.
+
+BIO_METHOD *BIO_s_socket(void);
+BIO_METHOD *BIO_s_fd(void);
+- BIO_sock_should_retry(int i) - the underlying function
+ used to determine if a call should be retried; the
+ argument is the '0' or '-1' returned by the previous BIO
+ operation.
+- BIO_fd_should_retry(int i) - same as the
+- BIO_sock_should_retry() except that it is different internally.
+- BIO_set_fd(BIO *bio, int fd, int close_flag) - set the
+ file descriptor to use
+- BIO_get_fd(BIO *bio, int *fd) - get the file descriptor.
+These two methods are very similar. Gets() is not
+supported, if you want this functionality, put a
+BIO_f_buffer() onto it. This BIO is bi-directional if the
+underlying file descriptor is. This is normally the case
+for sockets but not the case for stdio descriptors.
+
+BIO_METHOD *BIO_s_null(void);
+Read and write as much data as you like, it all disappears
+into this BIO.
+
+BIO_METHOD *BIO_f_buffer(void);
+- BIO_get_buffer_num_lines(BIO *bio) - return the number of
+ complete lines in the buffer.
+- BIO_set_buffer_size(BIO *bio, long size) - set the size of
+ the buffers.
+This type performs input and output buffering. It performs
+both at the same time. The size of the buffer can be set
+via the set buffer size option. Data buffered for output is
+only written when the buffer fills.
+
+BIO_METHOD *BIO_f_ssl(void);
+- BIO_set_ssl(BIO *bio, SSL *ssl, int close_flag) - the SSL
+ structure to use.
+- BIO_get_ssl(BIO *bio, SSL **ssl) - get the SSL structure
+ in use.
+The SSL bio is a little different from normal BIOs because
+the underlying SSL structure is a little different. A SSL
+structure performs IO via a read and write BIO. These can
+be different and are normally set via the
+SSL_set_rbio()/SSL_set_wbio() calls. The SSL_set_fd() calls
+are just wrappers that create socket BIOs and then call
+SSL_set_bio() where the read and write BIOs are the same.
+The BIO_push() operation makes the SSLs IO BIOs the same, so
+make sure the BIO pushed is capable of two directional
+traffic. If it is not, you will have to install the BIOs
+via the more conventional SSL_set_bio() call. BIO_pop() will retrieve
+the 'SSL read' BIO.
+
+BIO_METHOD *BIO_f_md(void);
+- BIO_set_md(BIO *bio, EVP_MD *md) - set the message digest
+ to use.
+- BIO_get_md(BIO *bio, EVP_MD **mdp) - return the digest
+ method in use in mdp, return 0 if not set yet.
+- BIO_reset() reinitializes the digest (EVP_DigestInit())
+ and passes the reset to the underlying BIOs.
+All data read or written via BIO_read() or BIO_write() to
+this BIO will be added to the calculated digest. This
+implies that this BIO is only one directional. If read and
+write operations are performed, two separate BIO_f_md() BIOs
+are reuqired to generate digests on both the input and the
+output. BIO_gets(BIO *bio, char *md, int size) will place the
+generated digest into 'md' and return the number of bytes.
+The EVP_MAX_MD_SIZE should probably be used to size the 'md'
+array. Reading the digest will also reset it.
+
+BIO_METHOD *BIO_f_cipher(void);
+- BIO_reset() reinitializes the cipher.
+- BIO_flush() should be called when the last bytes have been
+ output to flush the final block of block ciphers.
+- BIO_get_cipher_status(BIO *b), when called after the last
+ read from a cipher BIO, returns non-zero if the data
+ decrypted correctly, otherwise, 0.
+- BIO_set_cipher(BIO *b, EVP_CIPHER *c, unsigned char *key,
+ unsigned char *iv, int encrypt) This function is used to
+ setup a cipher BIO. The length of key and iv are
+ specified by the choice of EVP_CIPHER. Encrypt is 1 to
+ encrypt and 0 to decrypt.
+
+BIO_METHOD *BIO_f_base64(void);
+- BIO_flush() should be called when the last bytes have been output.
+This BIO base64 encodes when writing and base64 decodes when
+reading. It will scan the input until a suitable begin line
+is found. After reading data, BIO_reset() will reset the
+BIO to start scanning again. Do not mix reading and writing
+on the same base64 BIO. It is meant as a single stream BIO.
+
+Directions type
+both BIO_s_mem()
+one/both BIO_s_file()
+both BIO_s_fd()
+both BIO_s_socket()
+both BIO_s_null()
+both BIO_f_buffer()
+one BIO_f_md()
+one BIO_f_cipher()
+one BIO_f_base64()
+both BIO_f_ssl()
+
+It is easy to mix one and two directional BIOs, all one has
+to do is to keep two separate BIO pointers for reading and
+writing and be careful about usage of underlying BIOs. The
+SSL bio by it's very nature has to be two directional but
+the BIO_push() command will push the one BIO into the SSL
+BIO for both reading and writing.
+
+The best example program to look at is apps/enc.c and/or perhaps apps/dgst.c.
+
+
+==== blowfish.doc ========================================================
+
+The Blowfish library.
+
+Blowfish is a block cipher that operates on 64bit (8 byte) quantities. It
+uses variable size key, but 128bit (16 byte) key would normally be considered
+good. It can be used in all the modes that DES can be used. This
+library implements the ecb, cbc, cfb64, ofb64 modes.
+
+Blowfish is quite a bit faster that DES, and much faster than IDEA or
+RC2. It is one of the faster block ciphers.
+
+For all calls that have an 'input' and 'output' variables, they can be the
+same.
+
+This library requires the inclusion of 'blowfish.h'.
+
+All of the encryption functions take what is called an BF_KEY as an
+argument. An BF_KEY is an expanded form of the Blowfish key.
+For all modes of the Blowfish algorithm, the BF_KEY used for
+decryption is the same one that was used for encryption.
+
+The define BF_ENCRYPT is passed to specify encryption for the functions
+that require an encryption/decryption flag. BF_DECRYPT is passed to
+specify decryption.
+
+Please note that any of the encryption modes specified in my DES library
+could be used with Blowfish. I have only implemented ecb, cbc, cfb64 and
+ofb64 for the following reasons.
+- ecb is the basic Blowfish encryption.
+- cbc is the normal 'chaining' form for block ciphers.
+- cfb64 can be used to encrypt single characters, therefore input and output
+ do not need to be a multiple of 8.
+- ofb64 is similar to cfb64 but is more like a stream cipher, not as
+ secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
+- If you want triple Blowfish, thats 384 bits of key and you must be totally
+ obsessed with security. Still, if you want it, it is simple enough to
+ copy the function from the DES library and change the des_encrypt to
+ BF_encrypt; an exercise left for the paranoid reader :-).
+
+The functions are as follows:
+
+void BF_set_key(
+BF_KEY *ks;
+int len;
+unsigned char *key;
+ BF_set_key converts an 'len' byte key into a BF_KEY.
+ A 'ks' is an expanded form of the 'key' which is used to
+ perform actual encryption. It can be regenerated from the Blowfish key
+ so it only needs to be kept when encryption or decryption is about
+ to occur. Don't save or pass around BF_KEY's since they
+ are CPU architecture dependent, 'key's are not. Blowfish is an
+ interesting cipher in that it can be used with a variable length
+ key. 'len' is the length of 'key' to be used as the key.
+ A 'len' of 16 is recomended by me, but blowfish can use upto
+ 72 bytes. As a warning, blowfish has a very very slow set_key
+ function, it actually runs BF_encrypt 521 times.
+
+void BF_encrypt(unsigned long *data, BF_KEY *key);
+void BF_decrypt(unsigned long *data, BF_KEY *key);
+ These are the Blowfish encryption function that gets called by just
+ about every other Blowfish routine in the library. You should not
+ use this function except to implement 'modes' of Blowfish.
+ I say this because the
+ functions that call this routine do the conversion from 'char *' to
+ long, and this needs to be done to make sure 'non-aligned' memory
+ access do not occur.
+ Data is a pointer to 2 unsigned long's and key is the
+ BF_KEY to use.
+
+void BF_ecb_encrypt(
+unsigned char *in,
+unsigned char *out,
+BF_KEY *key,
+int encrypt);
+ This is the basic Electronic Code Book form of Blowfish (in DES this
+ mode is called Electronic Code Book so I'm going to use the term
+ for blowfish as well.
+ Input is encrypted into output using the key represented by
+ key. Depending on the encrypt, encryption or
+ decryption occurs. Input is 8 bytes long and output is 8 bytes.
+
+void BF_cbc_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+BF_KEY *ks,
+unsigned char *ivec,
+int encrypt);
+ This routine implements Blowfish in Cipher Block Chaining mode.
+ Input, which should be a multiple of 8 bytes is encrypted
+ (or decrypted) to output which will also be a multiple of 8 bytes.
+ The number of bytes is in length (and from what I've said above,
+ should be a multiple of 8). If length is not a multiple of 8, bad
+ things will probably happen. ivec is the initialisation vector.
+ This function updates iv after each call so that it can be passed to
+ the next call to BF_cbc_encrypt().
+
+void BF_cfb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+BF_KEY *schedule,
+unsigned char *ivec,
+int *num,
+int encrypt);
+ This is one of the more useful functions in this Blowfish library, it
+ implements CFB mode of Blowfish with 64bit feedback.
+ This allows you to encrypt an arbitrary number of bytes,
+ you do not require 8 byte padding. Each call to this
+ routine will encrypt the input bytes to output and then update ivec
+ and num. Num contains 'how far' we are though ivec.
+ 'Encrypt' is used to indicate encryption or decryption.
+ CFB64 mode operates by using the cipher to generate a stream
+ of bytes which is used to encrypt the plain text.
+ The cipher text is then encrypted to generate the next 64 bits to
+ be xored (incrementally) with the next 64 bits of plain
+ text. As can be seen from this, to encrypt or decrypt,
+ the same 'cipher stream' needs to be generated but the way the next
+ block of data is gathered for encryption is different for
+ encryption and decryption.
+
+void BF_ofb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+BF_KEY *schedule,
+unsigned char *ivec,
+int *num);
+ This functions implements OFB mode of Blowfish with 64bit feedback.
+ This allows you to encrypt an arbitrary number of bytes,
+ you do not require 8 byte padding. Each call to this
+ routine will encrypt the input bytes to output and then update ivec
+ and num. Num contains 'how far' we are though ivec.
+ This is in effect a stream cipher, there is no encryption or
+ decryption mode.
+
+For reading passwords, I suggest using des_read_pw_string() from my DES library.
+To generate a password from a text string, I suggest using MD5 (or MD2) to
+produce a 16 byte message digest that can then be passed directly to
+BF_set_key().
+
+=====
+For more information about the specific Blowfish modes in this library
+(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
+documentation on my DES library. What is said about DES is directly
+applicable for Blowfish.
+
+
+==== bn.doc ========================================================
+
+The Big Number library.
+
+#include "bn.h" when using this library.
+
+This big number library was written for use in implementing the RSA and DH
+public key encryption algorithms. As such, features such as negative
+numbers have not been extensively tested but they should work as expected.
+This library uses dynamic memory allocation for storing its data structures
+and so there are no limit on the size of the numbers manipulated by these
+routines but there is always the requirement to check return codes from
+functions just in case a memory allocation error has occurred.
+
+The basic object in this library is a BIGNUM. It is used to hold a single
+large integer. This type should be considered opaque and fields should not
+be modified or accessed directly.
+typedef struct bignum_st
+ {
+ int top; /* Index of last used d. */
+ BN_ULONG *d; /* Pointer to an array of 'BITS2' bit chunks. */
+ int max; /* Size of the d array. */
+ int neg;
+ } BIGNUM;
+The big number is stored in a malloced array of BN_ULONG's. A BN_ULONG can
+be either 16, 32 or 64 bits in size, depending on the 'number of bits'
+specified in bn.h.
+The 'd' field is this array. 'max' is the size of the 'd' array that has
+been allocated. 'top' is the 'last' entry being used, so for a value of 4,
+bn.d[0]=4 and bn.top=1. 'neg' is 1 if the number is negative.
+When a BIGNUM is '0', the 'd' field can be NULL and top == 0.
+
+Various routines in this library require the use of 'temporary' BIGNUM
+variables during their execution. Due to the use of dynamic memory
+allocation to create BIGNUMs being rather expensive when used in
+conjunction with repeated subroutine calls, the BN_CTX structure is
+used. This structure contains BN_CTX BIGNUMs. BN_CTX
+is the maximum number of temporary BIGNUMs any publicly exported
+function will use.
+
+#define BN_CTX 12
+typedef struct bignum_ctx
+ {
+ int tos; /* top of stack */
+ BIGNUM *bn[BN_CTX]; /* The variables */
+ } BN_CTX;
+
+The functions that follow have been grouped according to function. Most
+arithmetic functions return a result in the first argument, sometimes this
+first argument can also be an input parameter, sometimes it cannot. These
+restrictions are documented.
+
+extern BIGNUM *BN_value_one;
+There is one variable defined by this library, a BIGNUM which contains the
+number 1. This variable is useful for use in comparisons and assignment.
+
+Get Size functions.
+
+int BN_num_bits(BIGNUM *a);
+ This function returns the size of 'a' in bits.
+
+int BN_num_bytes(BIGNUM *a);
+ This function (macro) returns the size of 'a' in bytes.
+ For conversion of BIGNUMs to byte streams, this is the number of
+ bytes the output string will occupy. If the output byte
+ format specifies that the 'top' bit indicates if the number is
+ signed, so an extra '0' byte is required if the top bit on a
+ positive number is being written, it is upto the application to
+ make this adjustment. Like I said at the start, I don't
+ really support negative numbers :-).
+
+Creation/Destruction routines.
+
+BIGNUM *BN_new();
+ Return a new BIGNUM object. The number initially has a value of 0. If
+ there is an error, NULL is returned.
+
+void BN_free(BIGNUM *a);
+ Free()s a BIGNUM.
+
+void BN_clear(BIGNUM *a);
+ Sets 'a' to a value of 0 and also zeros all unused allocated
+ memory. This function is used to clear a variable of 'sensitive'
+ data that was held in it.
+
+void BN_clear_free(BIGNUM *a);
+ This function zeros the memory used by 'a' and then free()'s it.
+ This function should be used to BN_free() BIGNUMS that have held
+ sensitive numeric values like RSA private key values. Both this
+ function and BN_clear tend to only be used by RSA and DH routines.
+
+BN_CTX *BN_CTX_new(void);
+ Returns a new BN_CTX. NULL on error.
+
+void BN_CTX_free(BN_CTX *c);
+ Free a BN_CTX structure. The BIGNUMs in 'c' are BN_clear_free()ed.
+
+BIGNUM *bn_expand(BIGNUM *b, int bits);
+ This is an internal function that should not normally be used. It
+ ensures that 'b' has enough room for a 'bits' bit number. It is
+ mostly used by the various BIGNUM routines. If there is an error,
+ NULL is returned. if not, 'b' is returned.
+
+BIGNUM *BN_copy(BIGNUM *to, BIGNUM *from);
+ The 'from' is copied into 'to'. NULL is returned if there is an
+ error, otherwise 'to' is returned.
+
+BIGNUM *BN_dup(BIGNUM *a);
+ A new BIGNUM is created and returned containing the value of 'a'.
+ NULL is returned on error.
+
+Comparison and Test Functions.
+
+int BN_is_zero(BIGNUM *a)
+ Return 1 if 'a' is zero, else 0.
+
+int BN_is_one(a)
+ Return 1 is 'a' is one, else 0.
+
+int BN_is_word(a,w)
+ Return 1 if 'a' == w, else 0. 'w' is a BN_ULONG.
+
+int BN_cmp(BIGNUM *a, BIGNUM *b);
+ Return -1 if 'a' is less than 'b', 0 if 'a' and 'b' are the same
+ and 1 is 'a' is greater than 'b'. This is a signed comparison.
+
+int BN_ucmp(BIGNUM *a, BIGNUM *b);
+ This function is the same as BN_cmp except that the comparison
+ ignores the sign of the numbers.
+
+Arithmetic Functions
+For all of these functions, 0 is returned if there is an error and 1 is
+returned for success. The return value should always be checked. eg.
+if (!BN_add(r,a,b)) goto err;
+Unless explicitly mentioned, the 'return' value can be one of the
+'parameters' to the function.
+
+int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b);
+ Add 'a' and 'b' and return the result in 'r'. This is r=a+b.
+
+int BN_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b);
+ Subtract 'a' from 'b' and put the result in 'r'. This is r=a-b.
+
+int BN_lshift(BIGNUM *r, BIGNUM *a, int n);
+ Shift 'a' left by 'n' bits. This is r=a*(2^n).
+
+int BN_lshift1(BIGNUM *r, BIGNUM *a);
+ Shift 'a' left by 1 bit. This form is more efficient than
+ BN_lshift(r,a,1). This is r=a*2.
+
+int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
+ Shift 'a' right by 'n' bits. This is r=int(a/(2^n)).
+
+int BN_rshift1(BIGNUM *r, BIGNUM *a);
+ Shift 'a' right by 1 bit. This form is more efficient than
+ BN_rshift(r,a,1). This is r=int(a/2).
+
+int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b);
+ Multiply a by b and return the result in 'r'. 'r' must not be
+ either 'a' or 'b'. It has to be a different BIGNUM.
+ This is r=a*b.
+
+int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
+ Multiply a by a and return the result in 'r'. 'r' must not be
+ 'a'. This function is alot faster than BN_mul(r,a,a). This is r=a*a.
+
+int BN_div(BIGNUM *dv, BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx);
+ Divide 'm' by 'd' and return the result in 'dv' and the remainder
+ in 'rem'. Either of 'dv' or 'rem' can be NULL in which case that
+ value is not returned. 'ctx' needs to be passed as a source of
+ temporary BIGNUM variables.
+ This is dv=int(m/d), rem=m%d.
+
+int BN_mod(BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx);
+ Find the remainder of 'm' divided by 'd' and return it in 'rem'.
+ 'ctx' holds the temporary BIGNUMs required by this function.
+ This function is more efficient than BN_div(NULL,rem,m,d,ctx);
+ This is rem=m%d.
+
+int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BIGNUM *m,BN_CTX *ctx);
+ Multiply 'a' by 'b' and return the remainder when divided by 'm'.
+ 'ctx' holds the temporary BIGNUMs required by this function.
+ This is r=(a*b)%m.
+
+int BN_mod_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BIGNUM *m,BN_CTX *ctx);
+ Raise 'a' to the 'p' power and return the remainder when divided by
+ 'm'. 'ctx' holds the temporary BIGNUMs required by this function.
+ This is r=(a^p)%m.
+
+int BN_reciprocal(BIGNUM *r, BIGNUM *m, BN_CTX *ctx);
+ Return the reciprocal of 'm'. 'ctx' holds the temporary variables
+ required. This function returns -1 on error, otherwise it returns
+ the number of bits 'r' is shifted left to make 'r' into an integer.
+ This number of bits shifted is required in BN_mod_mul_reciprocal().
+ This is r=(1/m)<<(BN_num_bits(m)+1).
+
+int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *x, BIGNUM *y, BIGNUM *m,
+ BIGNUM *i, int nb, BN_CTX *ctx);
+ This function is used to perform an efficient BN_mod_mul()
+ operation. If one is going to repeatedly perform BN_mod_mul() with
+ the same modulus is worth calculating the reciprocal of the modulus
+ and then using this function. This operation uses the fact that
+ a/b == a*r where r is the reciprocal of b. On modern computers
+ multiplication is very fast and big number division is very slow.
+ 'x' is multiplied by 'y' and then divided by 'm' and the remainder
+ is returned. 'i' is the reciprocal of 'm' and 'nb' is the number
+ of bits as returned from BN_reciprocal(). Normal usage is as follows.
+ bn=BN_reciprocal(i,m);
+ for (...)
+ { BN_mod_mul_reciprocal(r,x,y,m,i,bn,ctx); }
+ This is r=(x*y)%m. Internally it is approximately
+ r=(x*y)-m*(x*y/m) or r=(x*y)-m*((x*y*i) >> bn)
+ This function is used in BN_mod_exp() and BN_is_prime().
+
+Assignment Operations
+
+int BN_one(BIGNUM *a)
+ Set 'a' to hold the value one.
+ This is a=1.
+
+int BN_zero(BIGNUM *a)
+ Set 'a' to hold the value zero.
+ This is a=0.
+
+int BN_set_word(BIGNUM *a, unsigned long w);
+ Set 'a' to hold the value of 'w'. 'w' is an unsigned long.
+ This is a=w.
+
+unsigned long BN_get_word(BIGNUM *a);
+ Returns 'a' in an unsigned long. Not remarkably, often 'a' will
+ be biger than a word, in which case 0xffffffffL is returned.
+
+Word Operations
+These functions are much more efficient that the normal bignum arithmetic
+operations.
+
+BN_ULONG BN_mod_word(BIGNUM *a, unsigned long w);
+ Return the remainder of 'a' divided by 'w'.
+ This is return(a%w).
+
+int BN_add_word(BIGNUM *a, unsigned long w);
+ Add 'w' to 'a'. This function does not take the sign of 'a' into
+ account. This is a+=w;
+
+Bit operations.
+
+int BN_is_bit_set(BIGNUM *a, int n);
+ This function return 1 if bit 'n' is set in 'a' else 0.
+
+int BN_set_bit(BIGNUM *a, int n);
+ This function sets bit 'n' to 1 in 'a'.
+ This is a&= ~(1<<n);
+
+int BN_clear_bit(BIGNUM *a, int n);
+ This function sets bit 'n' to zero in 'a'. Return 0 if less
+ than 'n' bits in 'a' else 1. This is a&= ~(1<<n);
+
+int BN_mask_bits(BIGNUM *a, int n);
+ Truncate 'a' to n bits long. This is a&= ~((~0)<<n)
+
+Format conversion routines.
+
+BIGNUM *BN_bin2bn(unsigned char *s, int len,BIGNUM *ret);
+ This function converts 'len' bytes in 's' into a BIGNUM which
+ is put in 'ret'. If ret is NULL, a new BIGNUM is created.
+ Either this new BIGNUM or ret is returned. The number is
+ assumed to be in bigendian form in 's'. By this I mean that
+ to 'ret' is created as follows for 'len' == 5.
+ ret = s[0]*2^32 + s[1]*2^24 + s[2]*2^16 + s[3]*2^8 + s[4];
+ This function cannot be used to convert negative numbers. It
+ is always assumed the number is positive. The application
+ needs to diddle the 'neg' field of th BIGNUM its self.
+ The better solution would be to save the numbers in ASN.1 format
+ since this is a defined standard for storing big numbers.
+ Look at the functions
+
+ ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai);
+ BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn);
+ int i2d_ASN1_INTEGER(ASN1_INTEGER *a,unsigned char **pp);
+ ASN1_INTEGER *d2i_ASN1_INTEGER(ASN1_INTEGER **a,unsigned char **pp,
+ long length;
+
+int BN_bn2bin(BIGNUM *a, unsigned char *to);
+ This function converts 'a' to a byte string which is put into
+ 'to'. The representation is big-endian in that the most
+ significant byte of 'a' is put into to[0]. This function
+ returns the number of bytes used to hold 'a'. BN_num_bytes(a)
+ would return the same value and can be used to determine how
+ large 'to' needs to be. If the number is negative, this
+ information is lost. Since this library was written to
+ manipulate large positive integers, the inability to save and
+ restore them is not considered to be a problem by me :-).
+ As for BN_bin2bn(), look at the ASN.1 integer encoding funtions
+ for SSLeay. They use BN_bin2bn() and BN_bn2bin() internally.
+
+char *BN_bn2ascii(BIGNUM *a);
+ This function returns a malloc()ed string that contains the
+ ascii hexadecimal encoding of 'a'. The number is in bigendian
+ format with a '-' in front if the number is negative.
+
+int BN_ascii2bn(BIGNUM **bn, char *a);
+ The inverse of BN_bn2ascii. The function returns the number of
+ characters from 'a' were processed in generating a the bignum.
+ error is inticated by 0 being returned. The number is a
+ hex digit string, optionally with a leading '-'. If *bn
+ is null, a BIGNUM is created and returned via that variable.
+
+int BN_print_fp(FILE *fp, BIGNUM *a);
+ 'a' is printed to file pointer 'fp'. It is in the same format
+ that is output from BN_bn2ascii(). 0 is returned on error,
+ 1 if things are ok.
+
+int BN_print(BIO *bp, BIGNUM *a);
+ Same as BN_print except that the output is done to the SSLeay libraries
+ BIO routines. BN_print_fp() actually calls this function.
+
+Miscellaneous Routines.
+
+int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
+ This function returns in 'rnd' a random BIGNUM that is bits
+ long. If bottom is 1, the number returned is odd. If top is set,
+ the top 2 bits of the number are set. This is useful because if
+ this is set, 2 'n; bit numbers multiplied together will return a 2n
+ bit number. If top was not set, they could produce a 2n-1 bit
+ number.
+
+BIGNUM *BN_mod_inverse(BIGNUM *a, BIGNUM *n,BN_CTX *ctx);
+ This function create a new BIGNUM and returns it. This number
+ is the inverse mod 'n' of 'a'. By this it is meant that the
+ returned value 'r' satisfies (a*r)%n == 1. This function is
+ used in the generation of RSA keys. 'ctx', as per usual,
+ is used to hold temporary variables that are required by the
+ function. NULL is returned on error.
+
+int BN_gcd(BIGNUM *r,BIGNUM *a,BIGNUM *b,BN_CTX *ctx);
+ 'r' has the greatest common divisor of 'a' and 'b'. 'ctx' is
+ used for temporary variables and 0 is returned on error.
+
+int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(),BN_CTX *ctx,
+ char *cb_arg);
+ This function is used to check if a BIGNUM ('p') is prime.
+ It performs this test by using the Miller-Rabin randomised
+ primality test. This is a probalistic test that requires a
+ number of rounds to ensure the number is prime to a high
+ degree of probability. Since this can take quite some time, a
+ callback function can be passed and it will be called each
+ time 'p' passes a round of the prime testing. 'callback' will
+ be called as follows, callback(1,n,cb_arg) where n is the number of
+ the round, just passed. As per usual 'ctx' contains temporary
+ variables used. If ctx is NULL, it does not matter, a local version
+ will be malloced. This parameter is present to save some mallocing
+ inside the function but probably could be removed.
+ 0 is returned on error.
+ 'ncheck' is the number of Miller-Rabin tests to run. It is
+ suggested to use the value 'BN_prime_checks' by default.
+
+BIGNUM *BN_generate_prime(
+int bits,
+int strong,
+BIGNUM *a,
+BIGNUM *rems,
+void (*callback)());
+char *cb_arg
+ This function is used to generate prime numbers. It returns a
+ new BIGNUM that has a high probability of being a prime.
+ 'bits' is the number of bits that
+ are to be in the prime. If 'strong' is true, the returned prime
+ will also be a strong prime ((p-1)/2 is also prime).
+ While searching for the prime ('p'), we
+ can add the requirement that the prime fill the following
+ condition p%a == rem. This can be used to help search for
+ primes with specific features, which is required when looking
+ for primes suitable for use with certain 'g' values in the
+ Diffie-Hellman key exchange algorithm. If 'a' is NULL,
+ this condition is not checked. If rem is NULL, rem is assumed
+ to be 1. Since this search for a prime
+ can take quite some time, if callback is not NULL, it is called
+ in the following situations.
+ We have a suspected prime (from a quick sieve),
+ callback(0,sus_prime++,cb_arg). Each item to be passed to BN_is_prime().
+ callback(1,round++,cb_arg). Each successful 'round' in BN_is_prime().
+ callback(2,round,cb_arg). For each successful BN_is_prime() test.
+
+Hints
+-----
+
+DSA wants 64*32 to use word mont mul, but RSA wants to use full.
+
+==== callback.doc ========================================================
+
+Callback functions used in SSLeay.
+
+--------------------------
+The BIO library.
+
+Each BIO structure can have a callback defined against it. This callback is
+called 2 times for each BIO 'function'. It is passed 6 parameters.
+BIO_debug_callback() is an example callback which is defined in
+crypto/buffer/bio_cb.c and is used in apps/dgst.c This is intended mostly
+for debuging or to notify the application of IO.
+
+long BIO_debug_callback(BIO *bio,int cmd,char *argp,int argi,long argl,
+ long ret);
+bio is the BIO being called, cmd is the type of BIO function being called.
+Look at the BIO_CB_* defines in buffer.h. Argp and argi are the arguments
+passed to BIO_read(), BIO_write, BIO_gets(), BIO_puts(). In the case of
+BIO_ctrl(), argl is also defined. The first time the callback is called,
+before the underlying function has been executed, 0 is passed as 'ret', and
+if the return code from the callback is not > 0, the call is aborted
+and the returned <= 0 value is returned.
+The second time the callback is called, the 'cmd' value also has
+BIO_CB_RETURN logically 'or'ed with it. The 'ret' value is the value returned
+from the actuall function call and whatever the callback returns is returned
+from the BIO function.
+
+BIO_set_callback(b,cb) can be used to set the callback function
+(b is a BIO), and BIO_set_callback_arg(b,arg) can be used to
+set the cb_arg argument in the BIO strucutre. This field is only intended
+to be used by application, primarily in the callback function since it is
+accessable since the BIO is passed.
+
+--------------------------
+The PEM library.
+
+The pem library only really uses one type of callback,
+static int def_callback(char *buf, int num, int verify);
+which is used to return a password string if required.
+'buf' is the buffer to put the string in. 'num' is the size of 'buf'
+and 'verify' is used to indicate that the password should be checked.
+This last flag is mostly used when reading a password for encryption.
+
+For all of these functions, a NULL callback will call the above mentioned
+default callback. This default function does not work under Windows 3.1.
+For other machines, it will use an application defined prompt string
+(EVP_set_pw_prompt(), which defines a library wide prompt string)
+if defined, otherwise it will use it's own PEM password prompt.
+It will then call EVP_read_pw_string() to get a password from the console.
+If your application wishes to use nice fancy windows to retrieve passwords,
+replace this function. The callback should return the number of bytes read
+into 'buf'. If the number of bytes <= 0, it is considered an error.
+
+Functions that take this callback are listed below. For the 'read' type
+functions, the callback will only be required if the PEM data is encrypted.
+
+For the Write functions, normally a password can be passed in 'kstr', of
+'klen' bytes which will be used if the 'enc' cipher is not NULL. If
+'kstr' is NULL, the callback will be used to retrieve a password.
+
+int PEM_do_header (EVP_CIPHER_INFO *cipher, unsigned char *data,long *len,
+ int (*callback)());
+char *PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *bp,char **x,int (*cb)());
+char *PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)());
+int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *bp,char *x,
+ EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
+int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,
+ EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)());
+STACK *PEM_X509_INFO_read(FILE *fp, STACK *sk, int (*cb)());
+STACK *PEM_X509_INFO_read_bio(BIO *fp, STACK *sk, int (*cb)());
+
+#define PEM_write_RSAPrivateKey(fp,x,enc,kstr,klen,cb)
+#define PEM_write_DSAPrivateKey(fp,x,enc,kstr,klen,cb)
+#define PEM_write_bio_RSAPrivateKey(bp,x,enc,kstr,klen,cb)
+#define PEM_write_bio_DSAPrivateKey(bp,x,enc,kstr,klen,cb)
+#define PEM_read_SSL_SESSION(fp,x,cb)
+#define PEM_read_X509(fp,x,cb)
+#define PEM_read_X509_REQ(fp,x,cb)
+#define PEM_read_X509_CRL(fp,x,cb)
+#define PEM_read_RSAPrivateKey(fp,x,cb)
+#define PEM_read_DSAPrivateKey(fp,x,cb)
+#define PEM_read_PrivateKey(fp,x,cb)
+#define PEM_read_PKCS7(fp,x,cb)
+#define PEM_read_DHparams(fp,x,cb)
+#define PEM_read_bio_SSL_SESSION(bp,x,cb)
+#define PEM_read_bio_X509(bp,x,cb)
+#define PEM_read_bio_X509_REQ(bp,x,cb)
+#define PEM_read_bio_X509_CRL(bp,x,cb)
+#define PEM_read_bio_RSAPrivateKey(bp,x,cb)
+#define PEM_read_bio_DSAPrivateKey(bp,x,cb)
+#define PEM_read_bio_PrivateKey(bp,x,cb)
+#define PEM_read_bio_PKCS7(bp,x,cb)
+#define PEM_read_bio_DHparams(bp,x,cb)
+int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
+RSA *d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)());
+
+Now you will notice that macros like
+#define PEM_write_X509(fp,x) \
+ PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \
+ (char *)x, NULL,NULL,0,NULL)
+Don't do encryption normally. If you want to PEM encrypt your X509 structure,
+either just call PEM_ASN1_write directly or just define you own
+macro variant. As you can see, this macro just sets all encryption related
+parameters to NULL.
+
+
+--------------------------
+The SSL library.
+
+#define SSL_set_info_callback(ssl,cb)
+#define SSL_CTX_set_info_callback(ctx,cb)
+void callback(SSL *ssl,int location,int ret)
+This callback is called each time around the SSL_connect()/SSL_accept()
+state machine. So it will be called each time the SSL protocol progresses.
+It is mostly present for use when debugging. When SSL_connect() or
+SSL_accept() return, the location flag is SSL_CB_ACCEPT_EXIT or
+SSL_CB_CONNECT_EXIT and 'ret' is the value about to be returned.
+Have a look at the SSL_CB_* defines in ssl.h. If an info callback is defined
+against the SSL_CTX, it is called unless there is one set against the SSL.
+Have a look at
+void client_info_callback() in apps/s_client() for an example.
+
+Certificate verification.
+void SSL_set_verify(SSL *s, int mode, int (*callback) ());
+void SSL_CTX_set_verify(SSL_CTX *ctx,int mode,int (*callback)());
+This callback is used to help verify client and server X509 certificates.
+It is actually passed to X509_cert_verify(), along with the SSL structure
+so you have to read about X509_cert_verify() :-). The SSL_CTX version is used
+if the SSL version is not defined. X509_cert_verify() is the function used
+by the SSL part of the library to verify certificates. This function is
+nearly always defined by the application.
+
+void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(),char *arg);
+int callback(char *arg,SSL *s,X509 *xs,STACK *cert_chain);
+This call is used to replace the SSLeay certificate verification code.
+The 'arg' is kept in the SSL_CTX and is passed to the callback.
+If the callback returns 0, the certificate is rejected, otherwise it
+is accepted. The callback is replacing the X509_cert_verify() call.
+This feature is not often used, but if you wished to implement
+some totally different certificate authentication system, this 'hook' is
+vital.
+
+SSLeay keeps a cache of session-ids against each SSL_CTX. These callbacks can
+be used to notify the application when a SSL_SESSION is added to the cache
+or to retrieve a SSL_SESSION that is not in the cache from the application.
+#define SSL_CTX_sess_set_get_cb(ctx,cb)
+SSL_SESSION *callback(SSL *s,char *session_id,int session_id_len,int *copy);
+If defined, this callback is called to return the SESSION_ID for the
+session-id in 'session_id', of 'session_id_len' bytes. 'copy' is set to 1
+if the server is to 'take a copy' of the SSL_SESSION structure. It is 0
+if the SSL_SESSION is being 'passed in' so the SSLeay library is now
+responsible for 'free()ing' the structure. Basically it is used to indicate
+if the reference count on the SSL_SESSION structure needs to be incremented.
+
+#define SSL_CTX_sess_set_new_cb(ctx,cb)
+int callback(SSL *s, SSL_SESSION *sess);
+When a new connection is established, if the SSL_SESSION is going to be added
+to the cache, this callback is called. Return 1 if a 'copy' is required,
+otherwise, return 0. This return value just causes the reference count
+to be incremented (on return of a 1), this means the application does
+not need to worry about incrementing the refernece count (and the
+locking that implies in a multi-threaded application).
+
+void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx,int (*cb)());
+This sets the SSL password reading function.
+It is mostly used for windowing applications
+and used by PEM_read_bio_X509() and PEM_read_bio_RSAPrivateKey()
+calls inside the SSL library. The only reason this is present is because the
+calls to PEM_* functions is hidden in the SSLeay library so you have to
+pass in the callback some how.
+
+#define SSL_CTX_set_client_cert_cb(ctx,cb)
+int callback(SSL *s,X509 **x509, EVP_PKEY **pkey);
+Called when a client certificate is requested but there is not one set
+against the SSL_CTX or the SSL. If the callback returns 1, x509 and
+pkey need to point to valid data. The library will free these when
+required so if the application wants to keep these around, increment
+their reference counts. If 0 is returned, no client cert is
+available. If -1 is returned, it is assumed that the callback needs
+to be called again at a later point in time. SSL_connect will return
+-1 and SSL_want_x509_lookup(ssl) returns true. Remember that
+application data can be attached to an SSL structure via the
+SSL_set_app_data(SSL *ssl,char *data) call.
+
+--------------------------
+The X509 library.
+
+int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)(),
+ int *error,char *arg,STACK *cert_chain);
+int verify_callback(int ok,X509 *xs,X509 *xi,int depth,int error,char *arg,
+ STACK *cert_chain);
+
+X509_cert_verify() is used to authenticate X509 certificates. The 'ctx' holds
+the details of the various caches and files used to locate certificates.
+'xs' is the certificate to verify and 'cb' is the application callback (more
+detail later). 'error' will be set to the error code and 'arg' is passed
+to the 'cb' callback. Look at the VERIFY_* defines in crypto/x509/x509.h
+
+When ever X509_cert_verify() makes a 'negative' decision about a
+certitificate, the callback is called. If everything checks out, the
+callback is called with 'VERIFY_OK' or 'VERIFY_ROOT_OK' (for a self
+signed cert that is not the passed certificate).
+
+The callback is passed the X509_cert_verify opinion of the certificate
+in 'ok', the certificate in 'xs', the issuer certificate in 'xi',
+the 'depth' of the certificate in the verification 'chain', the
+VERIFY_* code in 'error' and the argument passed to X509_cert_verify()
+in 'arg'. cert_chain is a list of extra certs to use if they are not
+in the cache.
+
+The callback can be used to look at the error reason, and then return 0
+for an 'error' or '1' for ok. This will override the X509_cert_verify()
+opinion of the certificates validity. Processing will continue depending on
+the return value. If one just wishes to use the callback for informational
+reason, just return the 'ok' parameter.
+
+--------------------------
+The BN and DH library.
+
+BIGNUM *BN_generate_prime(int bits,int strong,BIGNUM *add,
+ BIGNUM *rem,void (*callback)(int,int));
+int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int),
+
+Read doc/bn.doc for the description of these 2.
+
+DH *DH_generate_parameters(int prime_len,int generator,
+ void (*callback)(int,int));
+Read doc/bn.doc for the description of the callback, since it is just passed
+to BN_generate_prime(), except that it is also called as
+callback(3,0) by this function.
+
+--------------------------
+The CRYPTO library.
+
+void CRYPTO_set_locking_callback(void (*func)(int mode,int type,char *file,
+ int line));
+void CRYPTO_set_add_lock_callback(int (*func)(int *num,int mount,
+ int type,char *file, int line));
+void CRYPTO_set_id_callback(unsigned long (*func)(void));
+
+Read threads.doc for info on these ones.
+
+
+==== cipher.doc ========================================================
+
+The Cipher subroutines.
+
+These routines require "evp.h" to be included.
+
+These functions are a higher level interface to the various cipher
+routines found in this library. As such, they allow the same code to be
+used to encrypt and decrypt via different ciphers with only a change
+in an initial parameter. These routines also provide buffering for block
+ciphers.
+
+These routines all take a pointer to the following structure to specify
+which cipher to use. If you wish to use a new cipher with these routines,
+you would probably be best off looking an how an existing cipher is
+implemented and copying it. At this point in time, I'm not going to go
+into many details. This structure should be considered opaque
+
+typedef struct pem_cipher_st
+ {
+ int type;
+ int block_size;
+ int key_len;
+ int iv_len;
+ void (*enc_init)(); /* init for encryption */
+ void (*dec_init)(); /* init for decryption */
+ void (*do_cipher)(); /* encrypt data */
+ } EVP_CIPHER;
+
+The type field is the object NID of the cipher type
+(read the section on Objects for an explanation of what a NID is).
+The cipher block_size is how many bytes need to be passed
+to the cipher at a time. Key_len is the
+length of the key the cipher requires and iv_len is the length of the
+initialisation vector required. enc_init is the function
+called to initialise the ciphers context for encryption and dec_init is the
+function to initialise for decryption (they need to be different, especially
+for the IDEA cipher).
+
+One reason for specifying the Cipher via a pointer to a structure
+is that if you only use des-cbc, only the des-cbc routines will
+be included when you link the program. If you passed an integer
+that specified which cipher to use, the routine that mapped that
+integer to a set of cipher functions would cause all the ciphers
+to be link into the code. This setup also allows new ciphers
+to be added by the application (with some restrictions).
+
+The thirteen ciphers currently defined in this library are
+
+EVP_CIPHER *EVP_des_ecb(); /* DES in ecb mode, iv=0, block=8, key= 8 */
+EVP_CIPHER *EVP_des_ede(); /* DES in ecb ede mode, iv=0, block=8, key=16 */
+EVP_CIPHER *EVP_des_ede3(); /* DES in ecb ede mode, iv=0, block=8, key=24 */
+EVP_CIPHER *EVP_des_cfb(); /* DES in cfb mode, iv=8, block=1, key= 8 */
+EVP_CIPHER *EVP_des_ede_cfb(); /* DES in ede cfb mode, iv=8, block=1, key=16 */
+EVP_CIPHER *EVP_des_ede3_cfb();/* DES in ede cfb mode, iv=8, block=1, key=24 */
+EVP_CIPHER *EVP_des_ofb(); /* DES in ofb mode, iv=8, block=1, key= 8 */
+EVP_CIPHER *EVP_des_ede_ofb(); /* DES in ede ofb mode, iv=8, block=1, key=16 */
+EVP_CIPHER *EVP_des_ede3_ofb();/* DES in ede ofb mode, iv=8, block=1, key=24 */
+EVP_CIPHER *EVP_des_cbc(); /* DES in cbc mode, iv=8, block=8, key= 8 */
+EVP_CIPHER *EVP_des_ede_cbc(); /* DES in cbc ede mode, iv=8, block=8, key=16 */
+EVP_CIPHER *EVP_des_ede3_cbc();/* DES in cbc ede mode, iv=8, block=8, key=24 */
+EVP_CIPHER *EVP_desx_cbc(); /* DES in desx cbc mode,iv=8, block=8, key=24 */
+EVP_CIPHER *EVP_rc4(); /* RC4, iv=0, block=1, key=16 */
+EVP_CIPHER *EVP_idea_ecb(); /* IDEA in ecb mode, iv=0, block=8, key=16 */
+EVP_CIPHER *EVP_idea_cfb(); /* IDEA in cfb mode, iv=8, block=1, key=16 */
+EVP_CIPHER *EVP_idea_ofb(); /* IDEA in ofb mode, iv=8, block=1, key=16 */
+EVP_CIPHER *EVP_idea_cbc(); /* IDEA in cbc mode, iv=8, block=8, key=16 */
+EVP_CIPHER *EVP_rc2_ecb(); /* RC2 in ecb mode, iv=0, block=8, key=16 */
+EVP_CIPHER *EVP_rc2_cfb(); /* RC2 in cfb mode, iv=8, block=1, key=16 */
+EVP_CIPHER *EVP_rc2_ofb(); /* RC2 in ofb mode, iv=8, block=1, key=16 */
+EVP_CIPHER *EVP_rc2_cbc(); /* RC2 in cbc mode, iv=8, block=8, key=16 */
+EVP_CIPHER *EVP_bf_ecb(); /* Blowfish in ecb mode,iv=0, block=8, key=16 */
+EVP_CIPHER *EVP_bf_cfb(); /* Blowfish in cfb mode,iv=8, block=1, key=16 */
+EVP_CIPHER *EVP_bf_ofb(); /* Blowfish in ofb mode,iv=8, block=1, key=16 */
+EVP_CIPHER *EVP_bf_cbc(); /* Blowfish in cbc mode,iv=8, block=8, key=16 */
+
+The meaning of the compound names is as follows.
+des The base cipher is DES.
+idea The base cipher is IDEA
+rc4 The base cipher is RC4-128
+rc2 The base cipher is RC2-128
+ecb Electronic Code Book form of the cipher.
+cbc Cipher Block Chaining form of the cipher.
+cfb 64 bit Cipher Feedback form of the cipher.
+ofb 64 bit Output Feedback form of the cipher.
+ede The cipher is used in Encrypt, Decrypt, Encrypt mode. The first
+ and last keys are the same.
+ede3 The cipher is used in Encrypt, Decrypt, Encrypt mode.
+
+All the Cipher routines take a EVP_CIPHER_CTX pointer as an argument.
+The state of the cipher is kept in this structure.
+
+typedef struct EVP_CIPHER_Ctx_st
+ {
+ EVP_CIPHER *cipher;
+ int encrypt; /* encrypt or decrypt */
+ int buf_len; /* number we have left */
+ unsigned char buf[8];
+ union {
+ .... /* cipher specific stuff */
+ } c;
+ } EVP_CIPHER_CTX;
+
+Cipher is a pointer the the EVP_CIPHER for the current context. The encrypt
+flag indicates encryption or decryption. buf_len is the number of bytes
+currently being held in buf.
+The 'c' union holds the cipher specify context.
+
+The following functions are to be used.
+
+int EVP_read_pw_string(
+char *buf,
+int len,
+char *prompt,
+int verify,
+ This function is the same as des_read_pw_string() (des.doc).
+
+void EVP_set_pw_prompt(char *prompt);
+ This function sets the 'default' prompt to use to use in
+ EVP_read_pw_string when the prompt parameter is NULL. If the
+ prompt parameter is NULL, this 'default prompt' feature is turned
+ off. Be warned, this is a global variable so weird things
+ will happen if it is used under Win16 and care must be taken
+ with a multi-threaded version of the library.
+
+char *EVP_get_pw_prompt();
+ This returns a pointer to the default prompt string. NULL
+ if it is not set.
+
+int EVP_BytesToKey(
+EVP_CIPHER *type,
+EVP_MD *md,
+unsigned char *salt,
+unsigned char *data,
+int datal,
+int count,
+unsigned char *key,
+unsigned char *iv);
+ This function is used to generate a key and an initialisation vector
+ for a specified cipher from a key string and a salt. Type
+ specifies the cipher the 'key' is being generated for. Md is the
+ message digest algorithm to use to generate the key and iv. The salt
+ is an optional 8 byte object that is used to help seed the key
+ generator.
+ If the salt value is NULL, it is just not used. Datal is the
+ number of bytes to use from 'data' in the key generation.
+ This function returns the key size for the specified cipher, if
+ data is NULL, this value is returns and no other
+ computation is performed. Count is
+ the number of times to loop around the key generator. I would
+ suggest leaving it's value as 1. Key and iv are the structures to
+ place the returning iv and key in. If they are NULL, no value is
+ generated for that particular value.
+ The algorithm used is as follows
+
+ /* M[] is an array of message digests
+ * MD() is the message digest function */
+ M[0]=MD(data . salt);
+ for (i=1; i<count; i++) M[0]=MD(M[0]);
+
+ i=1
+ while (data still needed for key and iv)
+ {
+ M[i]=MD(M[i-1] . data . salt);
+ for (i=1; i<count; i++) M[i]=MD(M[i]);
+ i++;
+ }
+
+ If the salt is NULL, it is not used.
+ The digests are concatenated together.
+ M = M[0] . M[1] . M[2] .......
+
+ For key= 8, iv=8 => key=M[0.. 8], iv=M[ 9 .. 16].
+ For key=16, iv=0 => key=M[0..16].
+ For key=16, iv=8 => key=M[0..16], iv=M[17 .. 24].
+ For key=24, iv=8 => key=M[0..24], iv=M[25 .. 32].
+
+ This routine will produce DES-CBC keys and iv that are compatible
+ with the PKCS-5 standard when md2 or md5 are used. If md5 is
+ used, the salt is NULL and count is 1, this routine will produce
+ the password to key mapping normally used with RC4.
+ I have attempted to logically extend the PKCS-5 standard to
+ generate keys and iv for ciphers that require more than 16 bytes,
+ if anyone knows what the correct standard is, please inform me.
+ When using sha or sha1, things are a bit different under this scheme,
+ since sha produces a 20 byte digest. So for ciphers requiring
+ 24 bits of data, 20 will come from the first MD and 4 will
+ come from the second.
+
+ I have considered having a separate function so this 'routine'
+ can be used without the requirement of passing a EVP_CIPHER *,
+ but I have decided to not bother. If you wish to use the
+ function without official EVP_CIPHER structures, just declare
+ a local one and set the key_len and iv_len fields to the
+ length you desire.
+
+The following routines perform encryption and decryption 'by parts'. By
+this I mean that there are groups of 3 routines. An Init function that is
+used to specify a cipher and initialise data structures. An Update routine
+that does encryption/decryption, one 'chunk' at a time. And finally a
+'Final' function that finishes the encryption/decryption process.
+All these functions take a EVP_CIPHER pointer to specify which cipher to
+encrypt/decrypt with. They also take a EVP_CIPHER_CTX object as an
+argument. This structure is used to hold the state information associated
+with the operation in progress.
+
+void EVP_EncryptInit(
+EVP_CIPHER_CTX *ctx,
+EVP_CIPHER *type,
+unsigned char *key,
+unsigned char *iv);
+ This function initialise a EVP_CIPHER_CTX for encryption using the
+ cipher passed in the 'type' field. The cipher is initialised to use
+ 'key' as the key and 'iv' for the initialisation vector (if one is
+ required). If the type, key or iv is NULL, the value currently in the
+ EVP_CIPHER_CTX is reused. So to perform several decrypt
+ using the same cipher, key and iv, initialise with the cipher,
+ key and iv the first time and then for subsequent calls,
+ reuse 'ctx' but pass NULL for type, key and iv. You must make sure
+ to pass a key that is large enough for a particular cipher. I
+ would suggest using the EVP_BytesToKey() function.
+
+void EVP_EncryptUpdate(
+EVP_CIPHER_CTX *ctx,
+unsigned char *out,
+int *outl,
+unsigned char *in,
+int inl);
+ This function takes 'inl' bytes from 'in' and outputs bytes
+ encrypted by the cipher 'ctx' was initialised with into 'out'. The
+ number of bytes written to 'out' is put into outl. If a particular
+ cipher encrypts in blocks, less or more bytes than input may be
+ output. Currently the largest block size used by supported ciphers
+ is 8 bytes, so 'out' should have room for 'inl+7' bytes. Normally
+ EVP_EncryptInit() is called once, followed by lots and lots of
+ calls to EVP_EncryptUpdate, followed by a single EVP_EncryptFinal
+ call.
+
+void EVP_EncryptFinal(
+EVP_CIPHER_CTX *ctx,
+unsigned char *out,
+int *outl);
+ Because quite a large number of ciphers are block ciphers, there is
+ often an incomplete block to write out at the end of the
+ encryption. EVP_EncryptFinal() performs processing on this last
+ block. The last block in encoded in such a way that it is possible
+ to determine how many bytes in the last block are valid. For 8 byte
+ block size ciphers, if only 5 bytes in the last block are valid, the
+ last three bytes will be filled with the value 3. If only 2 were
+ valid, the other 6 would be filled with sixes. If all 8 bytes are
+ valid, a extra 8 bytes are appended to the cipher stream containing
+ nothing but 8 eights. These last bytes are output into 'out' and
+ the number of bytes written is put into 'outl' These last bytes
+ are output into 'out' and the number of bytes written is put into
+ 'outl'. This form of block cipher finalisation is compatible with
+ PKCS-5. Please remember that even if you are using ciphers like
+ RC4 that has no blocking and so the function will not write
+ anything into 'out', it would still be a good idea to pass a
+ variable for 'out' that can hold 8 bytes just in case the cipher is
+ changed some time in the future. It should also be remembered
+ that the EVP_CIPHER_CTX contains the password and so when one has
+ finished encryption with a particular EVP_CIPHER_CTX, it is good
+ practice to zero the structure
+ (ie. memset(ctx,0,sizeof(EVP_CIPHER_CTX)).
+
+void EVP_DecryptInit(
+EVP_CIPHER_CTX *ctx,
+EVP_CIPHER *type,
+unsigned char *key,
+unsigned char *iv);
+ This function is basically the same as EVP_EncryptInit() accept that
+ is prepares the EVP_CIPHER_CTX for decryption.
+
+void EVP_DecryptUpdate(
+EVP_CIPHER_CTX *ctx,
+unsigned char *out,
+int *outl,
+unsigned char *in,
+int inl);
+ This function is basically the same as EVP_EncryptUpdate()
+ except that it performs decryption. There is one
+ fundamental difference though. 'out' can not be the same as
+ 'in' for any ciphers with a block size greater than 1 if more
+ than one call to EVP_DecryptUpdate() will be made. This
+ is because this routine can hold a 'partial' block between
+ calls. When a partial block is decrypted (due to more bytes
+ being passed via this function, they will be written to 'out'
+ overwriting the input bytes in 'in' that have not been read
+ yet. From this it should also be noted that 'out' should
+ be at least one 'block size' larger than 'inl'. This problem
+ only occurs on the second and subsequent call to
+ EVP_DecryptUpdate() when using a block cipher.
+
+int EVP_DecryptFinal(
+EVP_CIPHER_CTX *ctx,
+unsigned char *out,
+int *outl);
+ This function is different to EVP_EncryptFinal in that it 'removes'
+ any padding bytes appended when the data was encrypted. Due to the
+ way in which 1 to 8 bytes may have been appended when encryption
+ using a block cipher, 'out' can end up with 0 to 7 bytes being put
+ into it. When decoding the padding bytes, it is possible to detect
+ an incorrect decryption. If the decryption appears to be wrong, 0
+ is returned. If everything seems ok, 1 is returned. For ciphers
+ with a block size of 1 (RC4), this function would normally not
+ return any bytes and would always return 1. Just because this
+ function returns 1 does not mean the decryption was correct. It
+ would normally be wrong due to either the wrong key/iv or
+ corruption of the cipher data fed to EVP_DecryptUpdate().
+ As for EVP_EncryptFinal, it is a good idea to zero the
+ EVP_CIPHER_CTX after use since the structure contains the key used
+ to decrypt the data.
+
+The following Cipher routines are convenience routines that call either
+EVP_EncryptXxx or EVP_DecryptXxx depending on weather the EVP_CIPHER_CTX
+was setup to encrypt or decrypt.
+
+void EVP_CipherInit(
+EVP_CIPHER_CTX *ctx,
+EVP_CIPHER *type,
+unsigned char *key,
+unsigned char *iv,
+int enc);
+ This function take arguments that are the same as EVP_EncryptInit()
+ and EVP_DecryptInit() except for the extra 'enc' flag. If 1, the
+ EVP_CIPHER_CTX is setup for encryption, if 0, decryption.
+
+void EVP_CipherUpdate(
+EVP_CIPHER_CTX *ctx,
+unsigned char *out,
+int *outl,
+unsigned char *in,
+int inl);
+ Again this function calls either EVP_EncryptUpdate() or
+ EVP_DecryptUpdate() depending on state in the 'ctx' structure.
+ As noted for EVP_DecryptUpdate(), when this routine is used
+ for decryption with block ciphers, 'out' should not be the
+ same as 'in'.
+
+int EVP_CipherFinal(
+EVP_CIPHER_CTX *ctx,
+unsigned char *outm,
+int *outl);
+ This routine call EVP_EncryptFinal() or EVP_DecryptFinal()
+ depending on the state information in 'ctx'. 1 is always returned
+ if the mode is encryption, otherwise the return value is the return
+ value of EVP_DecryptFinal().
+
+==== cipher.m ========================================================
+
+Date: Tue, 15 Oct 1996 08:16:14 +1000 (EST)
+From: Eric Young <eay@mincom.com>
+X-Sender: eay@orb
+To: Roland Haring <rharing@tandem.cl>
+Cc: ssl-users@mincom.com
+Subject: Re: Symmetric encryption with ssleay
+In-Reply-To: <m0vBpyq-00001aC@tandemnet.tandem.cl>
+Message-Id: <Pine.SOL.3.91.961015075623.11394A-100000@orb>
+Mime-Version: 1.0
+Content-Type: TEXT/PLAIN; charset=US-ASCII
+Sender: ssl-lists-owner@mincom.com
+Precedence: bulk
+Status: RO
+X-Status:
+
+On Fri, 11 Oct 1996, Roland Haring wrote:
+> THE_POINT:
+> Would somebody be so kind to give me the minimum basic
+> calls I need to do to libcrypto.a to get some text encrypted
+> and decrypted again? ...hopefully with code included to do
+> base64 encryption and decryption ... e.g. that sign-it.c code
+> posted some while ago was a big help :-) (please, do not point
+> me to apps/enc.c where I suspect my Heissenbug to be hidden :-)
+
+Ok, the base64 encoding stuff in 'enc.c' does the wrong thing sometimes
+when the data is less than a line long (this is for decoding). I'll dig
+up the exact fix today and post it. I am taking longer on 0.6.5 than I
+intended so I'll just post this patch.
+
+The documentation to read is in
+doc/cipher.doc,
+doc/encode.doc (very sparse :-).
+and perhaps
+doc/digest.doc,
+
+The basic calls to encrypt with say triple DES are
+
+Given
+char key[EVP_MAX_KEY_LENGTH];
+char iv[EVP_MAX_IV_LENGTH];
+EVP_CIPHER_CTX ctx;
+unsigned char out[512+8];
+int outl;
+
+/* optional generation of key/iv data from text password using md5
+ * via an upward compatable verson of PKCS#5. */
+EVP_BytesToKey(EVP_des_ede3_cbc,EVP_md5,NULL,passwd,strlen(passwd),
+ key,iv);
+
+/* Initalise the EVP_CIPHER_CTX */
+EVP_EncryptInit(ctx,EVP_des_ede3_cbc,key,iv);
+
+while (....)
+ {
+ /* This is processing 512 bytes at a time, the bytes are being
+ * copied into 'out', outl bytes are output. 'out' should not be the
+ * same as 'in' for reasons mentioned in the documentation. */
+ EVP_EncryptUpdate(ctx,out,&outl,in,512);
+ }
+
+/* Output the last 'block'. If the cipher is a block cipher, the last
+ * block is encoded in such a way so that a wrong decryption will normally be
+ * detected - again, one of the PKCS standards. */
+
+EVP_EncryptFinal(ctx,out,&outl);
+
+To decrypt, use the EVP_DecryptXXXXX functions except that EVP_DecryptFinal()
+will return 0 if the decryption fails (only detectable on block ciphers).
+
+You can also use
+EVP_CipherInit()
+EVP_CipherUpdate()
+EVP_CipherFinal()
+which does either encryption or decryption depending on an extra
+parameter to EVP_CipherInit().
+
+
+To do the base64 encoding,
+EVP_EncodeInit()
+EVP_EncodeUpdate()
+EVP_EncodeFinal()
+
+EVP_DecodeInit()
+EVP_DecodeUpdate()
+EVP_DecodeFinal()
+
+where the encoding is quite simple, but the decoding can be a bit more
+fun (due to dud input).
+
+EVP_DecodeUpdate() returns -1 for an error on an input line, 0 if the
+'last line' was just processed, and 1 if more lines should be submitted.
+
+EVP_DecodeFinal() returns -1 for an error or 1 if things are ok.
+
+So the loop becomes
+EVP_DecodeInit(....)
+for (;;)
+ {
+ i=EVP_DecodeUpdate(....);
+ if (i < 0) goto err;
+
+ /* process the data */
+
+ if (i == 0) break;
+ }
+EVP_DecodeFinal(....);
+/* process the data */
+
+The problem in 'enc.c' is that I was stuff the processing up after the
+EVP_DecodeFinal(...) when the for(..) loop was not being run (one line of
+base64 data) and this was because 'enc.c' tries to scan over a file until
+it hits the first valid base64 encoded line.
+
+hope this helps a bit.
+eric
+--
+Eric Young | BOOL is tri-state according to Bill Gates.
+AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage().
+
+==== conf.doc ========================================================
+
+The CONF library.
+
+The CONF library is a simple set of routines that can be used to configure
+programs. It is a superset of the genenv() function with some extra
+structure.
+
+The library consists of 5 functions.
+
+LHASH *CONF_load(LHASH *config,char *file);
+This function is called to load in a configuration file. Multiple
+configuration files can be loaded, with each subsequent 'load' overwriting
+any already defined 'variables'. If there is an error, NULL is returned.
+If config is NULL, a new LHASH structure is created and returned, otherwise
+the new data in the 'file' is loaded into the 'config' structure.
+
+void CONF_free(LHASH *config);
+This function free()s the data in config.
+
+char *CONF_get_string(LHASH *config,char *section,char *name);
+This function returns the string found in 'config' that corresponds to the
+'section' and 'name' specified. Classes and the naming system used will be
+discussed later in this document. If the variable is not defined, an NULL
+is returned.
+
+long CONF_get_long(LHASH *config,char *section, char *name);
+This function is the same as CONF_get_string() except that it converts the
+string to an long and returns it. If variable is not a number or the
+variable does not exist, 0 is returned. This is a little problematic but I
+don't know of a simple way around it.
+
+STACK *CONF_get_section(LHASH *config, char *section);
+This function returns a 'stack' of CONF_VALUE items that are all the
+items defined in a particular section. DO NOT free() any of the
+variable returned. They will disappear when CONF_free() is called.
+
+The 'lookup' model.
+The configuration file is divided into 'sections'. Each section is started by
+a line of the form '[ section ]'. All subsequent variable definitions are
+of this section. A variable definition is a simple alpha-numeric name
+followed by an '=' and then the data. A section or variable name can be
+described by a regular expression of the following form '[A-Za-z0-9_]+'.
+The value of the variable is the text after the '=' until the end of the
+line, stripped of leading and trailing white space.
+At this point I should mention that a '#' is a comment character, \ is the
+escape character, and all three types of quote can be used to stop any
+special interpretation of the data.
+Now when the data is being loaded, variable expansion can occur. This is
+done by expanding any $NAME sequences into the value represented by the
+variable NAME. If the variable is not in the current section, the different
+section can be specified by using the $SECTION::NAME form. The ${NAME} form
+also works and is very useful for expanding variables inside strings.
+
+When a variable is looked up, there are 2 special section. 'default', which
+is the initial section, and 'ENV' which is the processes environment
+variables (accessed via getenv()). When a variable is looked up, it is
+first 'matched' with it's section (if one was specified), if this fails, the
+'default' section is matched.
+If the 'lhash' variable passed was NULL, the environment is searched.
+
+Now why do we bother with sections? So we can have multiple programs using
+the same configuration file, or multiple instances of the same program
+using different variables. It also provides a nice mechanism to override
+the processes environment variables (eg ENV::HOME=/tmp). If there is a
+program specific variable missing, we can have default values.
+Multiple configuration files can be loaded, with each new value clearing
+any predefined values. A system config file can provide 'default' values,
+and application/usr specific files can provide overriding values.
+
+Examples
+
+# This is a simple example
+SSLEAY_HOME = /usr/local/ssl
+ENV::PATH = $SSLEAY_HOME/bin:$PATH # override my path
+
+[X509]
+cert_dir = $SSLEAY_HOME/certs # /usr/local/ssl/certs
+
+[SSL]
+CIPHER = DES-EDE-MD5:RC4-MD5
+USER_CERT = $HOME/${USER}di'r 5' # /home/eay/eaydir 5
+USER_CERT = $HOME/\${USER}di\'r # /home/eay/${USER}di'r
+USER_CERT = "$HOME/${US"ER}di\'r # $HOME/${USER}di'r
+
+TEST = 1234\
+5678\
+9ab # TEST=123456789ab
+TTT = 1234\n\n # TTT=1234<nl><nl>
+
+
+
+==== des.doc ========================================================
+
+The DES library.
+
+Please note that this library was originally written to operate with
+eBones, a version of Kerberos that had had encryption removed when it left
+the USA and then put back in. As such there are some routines that I will
+advise not using but they are still in the library for historical reasons.
+For all calls that have an 'input' and 'output' variables, they can be the
+same.
+
+This library requires the inclusion of 'des.h'.
+
+All of the encryption functions take what is called a des_key_schedule as an
+argument. A des_key_schedule is an expanded form of the des key.
+A des_key is 8 bytes of odd parity, the type used to hold the key is a
+des_cblock. A des_cblock is an array of 8 bytes, often in this library
+description I will refer to input bytes when the function specifies
+des_cblock's as input or output, this just means that the variable should
+be a multiple of 8 bytes.
+
+The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to
+specify decryption. The functions and global variable are as follows:
+
+int des_check_key;
+ DES keys are supposed to be odd parity. If this variable is set to
+ a non-zero value, des_set_key() will check that the key has odd
+ parity and is not one of the known weak DES keys. By default this
+ variable is turned off;
+
+void des_set_odd_parity(
+des_cblock *key );
+ This function takes a DES key (8 bytes) and sets the parity to odd.
+
+int des_is_weak_key(
+des_cblock *key );
+ This function returns a non-zero value if the DES key passed is a
+ weak, DES key. If it is a weak key, don't use it, try a different
+ one. If you are using 'random' keys, the chances of hitting a weak
+ key are 1/2^52 so it is probably not worth checking for them.
+
+int des_set_key(
+des_cblock *key,
+des_key_schedule schedule);
+ Des_set_key converts an 8 byte DES key into a des_key_schedule.
+ A des_key_schedule is an expanded form of the key which is used to
+ perform actual encryption. It can be regenerated from the DES key
+ so it only needs to be kept when encryption or decryption is about
+ to occur. Don't save or pass around des_key_schedule's since they
+ are CPU architecture dependent, DES keys are not. If des_check_key
+ is non zero, zero is returned if the key has the wrong parity or
+ the key is a weak key, else 1 is returned.
+
+int des_key_sched(
+des_cblock *key,
+des_key_schedule schedule);
+ An alternative name for des_set_key().
+
+int des_rw_mode; /* defaults to DES_PCBC_MODE */
+ This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default).
+ This specifies the function to use in the enc_read() and enc_write()
+ functions.
+
+void des_encrypt(
+unsigned long *data,
+des_key_schedule ks,
+int enc);
+ This is the DES encryption function that gets called by just about
+ every other DES routine in the library. You should not use this
+ function except to implement 'modes' of DES. I say this because the
+ functions that call this routine do the conversion from 'char *' to
+ long, and this needs to be done to make sure 'non-aligned' memory
+ access do not occur. The characters are loaded 'little endian',
+ have a look at my source code for more details on how I use this
+ function.
+ Data is a pointer to 2 unsigned long's and ks is the
+ des_key_schedule to use. enc, is non zero specifies encryption,
+ zero if decryption.
+
+void des_encrypt2(
+unsigned long *data,
+des_key_schedule ks,
+int enc);
+ This functions is the same as des_encrypt() except that the DES
+ initial permutation (IP) and final permutation (FP) have been left
+ out. As for des_encrypt(), you should not use this function.
+ It is used by the routines in my library that implement triple DES.
+ IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same
+ as des_encrypt() des_encrypt() des_encrypt() except faster :-).
+
+void des_ecb_encrypt(
+des_cblock *input,
+des_cblock *output,
+des_key_schedule ks,
+int enc);
+ This is the basic Electronic Code Book form of DES, the most basic
+ form. Input is encrypted into output using the key represented by
+ ks. If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise
+ decryption occurs. Input is 8 bytes long and output is 8 bytes.
+ (the des_cblock structure is 8 chars).
+
+void des_ecb3_encrypt(
+des_cblock *input,
+des_cblock *output,
+des_key_schedule ks1,
+des_key_schedule ks2,
+des_key_schedule ks3,
+int enc);
+ This is the 3 key EDE mode of ECB DES. What this means is that
+ the 8 bytes of input is encrypted with ks1, decrypted with ks2 and
+ then encrypted again with ks3, before being put into output;
+ C=E(ks3,D(ks2,E(ks1,M))). There is a macro, des_ecb2_encrypt()
+ that only takes 2 des_key_schedules that implements,
+ C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1.
+
+void des_cbc_encrypt(
+des_cblock *input,
+des_cblock *output,
+long length,
+des_key_schedule ks,
+des_cblock *ivec,
+int enc);
+ This routine implements DES in Cipher Block Chaining mode.
+ Input, which should be a multiple of 8 bytes is encrypted
+ (or decrypted) to output which will also be a multiple of 8 bytes.
+ The number of bytes is in length (and from what I've said above,
+ should be a multiple of 8). If length is not a multiple of 8, I'm
+ not being held responsible :-). ivec is the initialisation vector.
+ This function does not modify this variable. To correctly implement
+ cbc mode, you need to do one of 2 things; copy the last 8 bytes of
+ cipher text for use as the next ivec in your application,
+ or use des_ncbc_encrypt().
+ Only this routine has this problem with updating the ivec, all
+ other routines that are implementing cbc mode update ivec.
+
+void des_ncbc_encrypt(
+des_cblock *input,
+des_cblock *output,
+long length,
+des_key_schedule sk,
+des_cblock *ivec,
+int enc);
+ For historical reasons, des_cbc_encrypt() did not update the
+ ivec with the value requires so that subsequent calls to
+ des_cbc_encrypt() would 'chain'. This was needed so that the same
+ 'length' values would not need to be used when decrypting.
+ des_ncbc_encrypt() does the right thing. It is the same as
+ des_cbc_encrypt accept that ivec is updates with the correct value
+ to pass in subsequent calls to des_ncbc_encrypt(). I advise using
+ des_ncbc_encrypt() instead of des_cbc_encrypt();
+
+void des_xcbc_encrypt(
+des_cblock *input,
+des_cblock *output,
+long length,
+des_key_schedule sk,
+des_cblock *ivec,
+des_cblock *inw,
+des_cblock *outw,
+int enc);
+ This is RSA's DESX mode of DES. It uses inw and outw to
+ 'whiten' the encryption. inw and outw are secret (unlike the iv)
+ and are as such, part of the key. So the key is sort of 24 bytes.
+ This is much better than cbc des.
+
+void des_3cbc_encrypt(
+des_cblock *input,
+des_cblock *output,
+long length,
+des_key_schedule sk1,
+des_key_schedule sk2,
+des_cblock *ivec1,
+des_cblock *ivec2,
+int enc);
+ This function is flawed, do not use it. I have left it in the
+ library because it is used in my des(1) program and will function
+ correctly when used by des(1). If I removed the function, people
+ could end up unable to decrypt files.
+ This routine implements outer triple cbc encryption using 2 ks and
+ 2 ivec's. Use des_ede2_cbc_encrypt() instead.
+
+void des_ede3_cbc_encrypt(
+des_cblock *input,
+des_cblock *output,
+long length,
+des_key_schedule ks1,
+des_key_schedule ks2,
+des_key_schedule ks3,
+des_cblock *ivec,
+int enc);
+ This function implements outer triple CBC DES encryption with 3
+ keys. What this means is that each 'DES' operation
+ inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))).
+ Again, this is cbc mode so an ivec is requires.
+ This mode is used by SSL.
+ There is also a des_ede2_cbc_encrypt() that only uses 2
+ des_key_schedule's, the first being reused for the final
+ encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of triple DES
+ is used by the RSAref library.
+
+void des_pcbc_encrypt(
+des_cblock *input,
+des_cblock *output,
+long length,
+des_key_schedule ks,
+des_cblock *ivec,
+int enc);
+ This is Propagating Cipher Block Chaining mode of DES. It is used
+ by Kerberos v4. It's parameters are the same as des_ncbc_encrypt().
+
+void des_cfb_encrypt(
+unsigned char *in,
+unsigned char *out,
+int numbits,
+long length,
+des_key_schedule ks,
+des_cblock *ivec,
+int enc);
+ Cipher Feedback Back mode of DES. This implementation 'feeds back'
+ in numbit blocks. The input (and output) is in multiples of numbits
+ bits. numbits should to be a multiple of 8 bits. Length is the
+ number of bytes input. If numbits is not a multiple of 8 bits,
+ the extra bits in the bytes will be considered padding. So if
+ numbits is 12, for each 2 input bytes, the 4 high bits of the
+ second byte will be ignored. So to encode 72 bits when using
+ a numbits of 12 take 12 bytes. To encode 72 bits when using
+ numbits of 9 will take 16 bytes. To encode 80 bits when using
+ numbits of 16 will take 10 bytes. etc, etc. This padding will
+ apply to both input and output.
+
+
+void des_cfb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+des_key_schedule ks,
+des_cblock *ivec,
+int *num,
+int enc);
+ This is one of the more useful functions in this DES library, it
+ implements CFB mode of DES with 64bit feedback. Why is this
+ useful you ask? Because this routine will allow you to encrypt an
+ arbitrary number of bytes, no 8 byte padding. Each call to this
+ routine will encrypt the input bytes to output and then update ivec
+ and num. num contains 'how far' we are though ivec. If this does
+ not make much sense, read more about cfb mode of DES :-).
+
+void des_ede3_cfb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+des_key_schedule ks1,
+des_key_schedule ks2,
+des_key_schedule ks3,
+des_cblock *ivec,
+int *num,
+int enc);
+ Same as des_cfb64_encrypt() accept that the DES operation is
+ triple DES. As usual, there is a macro for
+ des_ede2_cfb64_encrypt() which reuses ks1.
+
+void des_ofb_encrypt(
+unsigned char *in,
+unsigned char *out,
+int numbits,
+long length,
+des_key_schedule ks,
+des_cblock *ivec);
+ This is a implementation of Output Feed Back mode of DES. It is
+ the same as des_cfb_encrypt() in that numbits is the size of the
+ units dealt with during input and output (in bits).
+
+void des_ofb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+des_key_schedule ks,
+des_cblock *ivec,
+int *num);
+ The same as des_cfb64_encrypt() except that it is Output Feed Back
+ mode.
+
+void des_ede3_ofb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+des_key_schedule ks1,
+des_key_schedule ks2,
+des_key_schedule ks3,
+des_cblock *ivec,
+int *num);
+ Same as des_ofb64_encrypt() accept that the DES operation is
+ triple DES. As usual, there is a macro for
+ des_ede2_ofb64_encrypt() which reuses ks1.
+
+int des_read_pw_string(
+char *buf,
+int length,
+char *prompt,
+int verify);
+ This routine is used to get a password from the terminal with echo
+ turned off. Buf is where the string will end up and length is the
+ size of buf. Prompt is a string presented to the 'user' and if
+ verify is set, the key is asked for twice and unless the 2 copies
+ match, an error is returned. A return code of -1 indicates a
+ system error, 1 failure due to use interaction, and 0 is success.
+
+unsigned long des_cbc_cksum(
+des_cblock *input,
+des_cblock *output,
+long length,
+des_key_schedule ks,
+des_cblock *ivec);
+ This function produces an 8 byte checksum from input that it puts in
+ output and returns the last 4 bytes as a long. The checksum is
+ generated via cbc mode of DES in which only the last 8 byes are
+ kept. I would recommend not using this function but instead using
+ the EVP_Digest routines, or at least using MD5 or SHA. This
+ function is used by Kerberos v4 so that is why it stays in the
+ library.
+
+char *des_fcrypt(
+const char *buf,
+const char *salt
+char *ret);
+ This is my fast version of the unix crypt(3) function. This version
+ takes only a small amount of space relative to other fast
+ crypt() implementations. This is different to the normal crypt
+ in that the third parameter is the buffer that the return value
+ is written into. It needs to be at least 14 bytes long. This
+ function is thread safe, unlike the normal crypt.
+
+char *crypt(
+const char *buf,
+const char *salt);
+ This function calls des_fcrypt() with a static array passed as the
+ third parameter. This emulates the normal non-thread safe semantics
+ of crypt(3).
+
+void des_string_to_key(
+char *str,
+des_cblock *key);
+ This function takes str and converts it into a DES key. I would
+ recommend using MD5 instead and use the first 8 bytes of output.
+ When I wrote the first version of these routines back in 1990, MD5
+ did not exist but I feel these routines are still sound. This
+ routines is compatible with the one in MIT's libdes.
+
+void des_string_to_2keys(
+char *str,
+des_cblock *key1,
+des_cblock *key2);
+ This function takes str and converts it into 2 DES keys.
+ I would recommend using MD5 and using the 16 bytes as the 2 keys.
+ I have nothing against these 2 'string_to_key' routines, it's just
+ that if you say that your encryption key is generated by using the
+ 16 bytes of an MD5 hash, every-one knows how you generated your
+ keys.
+
+int des_read_password(
+des_cblock *key,
+char *prompt,
+int verify);
+ This routine combines des_read_pw_string() with des_string_to_key().
+
+int des_read_2passwords(
+des_cblock *key1,
+des_cblock *key2,
+char *prompt,
+int verify);
+ This routine combines des_read_pw_string() with des_string_to_2key().
+
+void des_random_seed(
+des_cblock key);
+ This routine sets a starting point for des_random_key().
+
+void des_random_key(
+des_cblock ret);
+ This function return a random key. Make sure to 'seed' the random
+ number generator (with des_random_seed()) before using this function.
+ I personally now use a MD5 based random number system.
+
+int des_enc_read(
+int fd,
+char *buf,
+int len,
+des_key_schedule ks,
+des_cblock *iv);
+ This function will write to a file descriptor the encrypted data
+ from buf. This data will be preceded by a 4 byte 'byte count' and
+ will be padded out to 8 bytes. The encryption is either CBC of
+ PCBC depending on the value of des_rw_mode. If it is DES_PCBC_MODE,
+ pcbc is used, if DES_CBC_MODE, cbc is used. The default is to use
+ DES_PCBC_MODE.
+
+int des_enc_write(
+int fd,
+char *buf,
+int len,
+des_key_schedule ks,
+des_cblock *iv);
+ This routines read stuff written by des_enc_read() and decrypts it.
+ I have used these routines quite a lot but I don't believe they are
+ suitable for non-blocking io. If you are after a full
+ authentication/encryption over networks, have a look at SSL instead.
+
+unsigned long des_quad_cksum(
+des_cblock *input,
+des_cblock *output,
+long length,
+int out_count,
+des_cblock *seed);
+ This is a function from Kerberos v4 that is not anything to do with
+ DES but was needed. It is a cksum that is quicker to generate than
+ des_cbc_cksum(); I personally would use MD5 routines now.
+=====
+Modes of DES
+Quite a bit of the following information has been taken from
+ AS 2805.5.2
+ Australian Standard
+ Electronic funds transfer - Requirements for interfaces,
+ Part 5.2: Modes of operation for an n-bit block cipher algorithm
+ Appendix A
+
+There are several different modes in which DES can be used, they are
+as follows.
+
+Electronic Codebook Mode (ECB) (des_ecb_encrypt())
+- 64 bits are enciphered at a time.
+- The order of the blocks can be rearranged without detection.
+- The same plaintext block always produces the same ciphertext block
+ (for the same key) making it vulnerable to a 'dictionary attack'.
+- An error will only affect one ciphertext block.
+
+Cipher Block Chaining Mode (CBC) (des_cbc_encrypt())
+- a multiple of 64 bits are enciphered at a time.
+- The CBC mode produces the same ciphertext whenever the same
+ plaintext is encrypted using the same key and starting variable.
+- The chaining operation makes the ciphertext blocks dependent on the
+ current and all preceding plaintext blocks and therefore blocks can not
+ be rearranged.
+- The use of different starting variables prevents the same plaintext
+ enciphering to the same ciphertext.
+- An error will affect the current and the following ciphertext blocks.
+
+Cipher Feedback Mode (CFB) (des_cfb_encrypt())
+- a number of bits (j) <= 64 are enciphered at a time.
+- The CFB mode produces the same ciphertext whenever the same
+ plaintext is encrypted using the same key and starting variable.
+- The chaining operation makes the ciphertext variables dependent on the
+ current and all preceding variables and therefore j-bit variables are
+ chained together and can not be rearranged.
+- The use of different starting variables prevents the same plaintext
+ enciphering to the same ciphertext.
+- The strength of the CFB mode depends on the size of k (maximal if
+ j == k). In my implementation this is always the case.
+- Selection of a small value for j will require more cycles through
+ the encipherment algorithm per unit of plaintext and thus cause
+ greater processing overheads.
+- Only multiples of j bits can be enciphered.
+- An error will affect the current and the following ciphertext variables.
+
+Output Feedback Mode (OFB) (des_ofb_encrypt())
+- a number of bits (j) <= 64 are enciphered at a time.
+- The OFB mode produces the same ciphertext whenever the same
+ plaintext enciphered using the same key and starting variable. More
+ over, in the OFB mode the same key stream is produced when the same
+ key and start variable are used. Consequently, for security reasons
+ a specific start variable should be used only once for a given key.
+- The absence of chaining makes the OFB more vulnerable to specific attacks.
+- The use of different start variables values prevents the same
+ plaintext enciphering to the same ciphertext, by producing different
+ key streams.
+- Selection of a small value for j will require more cycles through
+ the encipherment algorithm per unit of plaintext and thus cause
+ greater processing overheads.
+- Only multiples of j bits can be enciphered.
+- OFB mode of operation does not extend ciphertext errors in the
+ resultant plaintext output. Every bit error in the ciphertext causes
+ only one bit to be in error in the deciphered plaintext.
+- OFB mode is not self-synchronising. If the two operation of
+ encipherment and decipherment get out of synchronism, the system needs
+ to be re-initialised.
+- Each re-initialisation should use a value of the start variable
+ different from the start variable values used before with the same
+ key. The reason for this is that an identical bit stream would be
+ produced each time from the same parameters. This would be
+ susceptible to a ' known plaintext' attack.
+
+Triple ECB Mode (des_ecb3_encrypt())
+- Encrypt with key1, decrypt with key2 and encrypt with key3 again.
+- As for ECB encryption but increases the key length to 168 bits.
+ There are theoretic attacks that can be used that make the effective
+ key length 112 bits, but this attack also requires 2^56 blocks of
+ memory, not very likely, even for the NSA.
+- If both keys are the same it is equivalent to encrypting once with
+ just one key.
+- If the first and last key are the same, the key length is 112 bits.
+ There are attacks that could reduce the key space to 55 bit's but it
+ requires 2^56 blocks of memory.
+- If all 3 keys are the same, this is effectively the same as normal
+ ecb mode.
+
+Triple CBC Mode (des_ede3_cbc_encrypt())
+- Encrypt with key1, decrypt with key2 and then encrypt with key3.
+- As for CBC encryption but increases the key length to 168 bits with
+ the same restrictions as for triple ecb mode.
+
+==== digest.doc ========================================================
+
+
+The Message Digest subroutines.
+
+These routines require "evp.h" to be included.
+
+These functions are a higher level interface to the various message digest
+routines found in this library. As such, they allow the same code to be
+used to digest via different algorithms with only a change in an initial
+parameter. They are basically just a front-end to the MD2, MD5, SHA
+and SHA1
+routines.
+
+These routines all take a pointer to the following structure to specify
+which message digest algorithm to use.
+typedef struct evp_md_st
+ {
+ int type;
+ int pkey_type;
+ int md_size;
+ void (*init)();
+ void (*update)();
+ void (*final)();
+
+ int required_pkey_type; /*EVP_PKEY_xxx */
+ int (*sign)();
+ int (*verify)();
+ } EVP_MD;
+
+If additional message digest algorithms are to be supported, a structure of
+this type needs to be declared and populated and then the Digest routines
+can be used with that algorithm. The type field is the object NID of the
+digest type (read the section on Objects for an explanation). The pkey_type
+is the Object type to use when the a message digest is generated by there
+routines and then is to be signed with the pkey algorithm. Md_size is
+the size of the message digest returned. Init, update
+and final are the relevant functions to perform the message digest function
+by parts. One reason for specifying the message digest to use via this
+mechanism is that if you only use md5, only the md5 routines will
+be included in you linked program. If you passed an integer
+that specified which message digest to use, the routine that mapped that
+integer to a set of message digest functions would cause all the message
+digests functions to be link into the code. This setup also allows new
+message digest functions to be added by the application.
+
+The six message digests defined in this library are
+
+EVP_MD *EVP_md2(void); /* RSA sign/verify */
+EVP_MD *EVP_md5(void); /* RSA sign/verify */
+EVP_MD *EVP_sha(void); /* RSA sign/verify */
+EVP_MD *EVP_sha1(void); /* RSA sign/verify */
+EVP_MD *EVP_dss(void); /* DSA sign/verify */
+EVP_MD *EVP_dss1(void); /* DSA sign/verify */
+
+All the message digest routines take a EVP_MD_CTX pointer as an argument.
+The state of the message digest is kept in this structure.
+
+typedef struct pem_md_ctx_st
+ {
+ EVP_MD *digest;
+ union {
+ unsigned char base[4]; /* this is used in my library as a
+ * 'pointer' to all union elements
+ * structures. */
+ MD2_CTX md2;
+ MD5_CTX md5;
+ SHA_CTX sha;
+ } md;
+ } EVP_MD_CTX;
+
+The Digest functions are as follows.
+
+void EVP_DigestInit(
+EVP_MD_CTX *ctx,
+EVP_MD *type);
+ This function is used to initialise the EVP_MD_CTX. The message
+ digest that will associated with 'ctx' is specified by 'type'.
+
+void EVP_DigestUpdate(
+EVP_MD_CTX *ctx,
+unsigned char *data,
+unsigned int cnt);
+ This function is used to pass more data to the message digest
+ function. 'cnt' bytes are digested from 'data'.
+
+void EVP_DigestFinal(
+EVP_MD_CTX *ctx,
+unsigned char *md,
+unsigned int *len);
+ This function finishes the digestion and puts the message digest
+ into 'md'. The length of the message digest is put into len;
+ EVP_MAX_MD_SIZE is the size of the largest message digest that
+ can be returned from this function. Len can be NULL if the
+ size of the digest is not required.
+
+
+==== encode.doc ========================================================
+
+
+void EVP_EncodeInit(EVP_ENCODE_CTX *ctx);
+void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,
+ int *outl,unsigned char *in,int inl);
+void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl);
+int EVP_EncodeBlock(unsigned char *t, unsigned char *f, int n);
+
+void EVP_DecodeInit(EVP_ENCODE_CTX *ctx);
+int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl,
+ unsigned char *in, int inl);
+int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned
+ char *out, int *outl);
+int EVP_DecodeBlock(unsigned char *t, unsigned
+ char *f, int n);
+
+
+==== envelope.doc ========================================================
+
+The following routines are use to create 'digital' envelopes.
+By this I mean that they perform various 'higher' level cryptographic
+functions. Have a read of 'cipher.doc' and 'digest.doc' since those
+routines are used by these functions.
+cipher.doc contains documentation about the cipher part of the
+envelope library and digest.doc contatins the description of the
+message digests supported.
+
+To 'sign' a document involves generating a message digest and then encrypting
+the digest with an private key.
+
+#define EVP_SignInit(a,b) EVP_DigestInit(a,b)
+#define EVP_SignUpdate(a,b,c) EVP_DigestUpdate(a,b,c)
+Due to the fact this operation is basically just an extended message
+digest, the first 2 functions are macro calls to Digest generating
+functions.
+
+int EVP_SignFinal(
+EVP_MD_CTX *ctx,
+unsigned char *md,
+unsigned int *s,
+EVP_PKEY *pkey);
+ This finalisation function finishes the generation of the message
+digest and then encrypts the digest (with the correct message digest
+object identifier) with the EVP_PKEY private key. 'ctx' is the message digest
+context. 'md' will end up containing the encrypted message digest. This
+array needs to be EVP_PKEY_size(pkey) bytes long. 's' will actually
+contain the exact length. 'pkey' of course is the private key. It is
+one of EVP_PKEY_RSA or EVP_PKEY_DSA type.
+If there is an error, 0 is returned, otherwise 1.
+
+Verify is used to check an signed message digest.
+
+#define EVP_VerifyInit(a,b) EVP_DigestInit(a,b)
+#define EVP_VerifyUpdate(a,b,c) EVP_DigestUpdate(a,b,c)
+Since the first step is to generate a message digest, the first 2 functions
+are macros.
+
+int EVP_VerifyFinal(
+EVP_MD_CTX *ctx,
+unsigned char *md,
+unsigned int s,
+EVP_PKEY *pkey);
+ This function finishes the generation of the message digest and then
+compares it with the supplied encrypted message digest. 'md' contains the
+'s' bytes of encrypted message digest. 'pkey' is used to public key decrypt
+the digest. It is then compared with the message digest just generated.
+If they match, 1 is returned else 0.
+
+int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek,
+ int *ekl, unsigned char *iv, EVP_PKEY **pubk, int npubk);
+Must have at least one public key, error is 0. I should also mention that
+the buffers pointed to by 'ek' need to be EVP_PKEY_size(pubk[n]) is size.
+
+#define EVP_SealUpdate(a,b,c,d,e) EVP_EncryptUpdate(a,b,c,d,e)
+void EVP_SealFinal(EVP_CIPHER_CTX *ctx,unsigned char *out,int *outl);
+
+
+int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek,
+ int ekl,unsigned char *iv,EVP_PKEY *priv);
+0 on failure
+
+#define EVP_OpenUpdate(a,b,c,d,e) EVP_DecryptUpdate(a,b,c,d,e)
+
+int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
+Decrypt final return code
+
+
+==== error.doc ========================================================
+
+The error routines.
+
+The 'error' system I've implemented is intended to server 2 purpose, to
+record the reason why a command failed and to record where in the libraries
+the failure occurred. It is more or less setup to record a 'trace' of which
+library components were being traversed when the error occurred.
+
+When an error is recorded, it is done so a as single unsigned long which is
+composed of three parts. The top byte is the 'library' number, the middle
+12 bytes is the function code, and the bottom 12 bits is the 'reason' code.
+
+Each 'library', or should a say, 'section' of the SSLeay library has a
+different unique 'library' error number. Each function in the library has
+a number that is unique for that library. Each 'library' also has a number
+for each 'error reason' that is only unique for that 'library'.
+
+Due to the way these error routines record a 'error trace', there is an
+array per thread that is used to store the error codes.
+The various functions in this library are used to access
+and manipulate this array.
+
+void ERR_put_error(int lib, int func,int reason);
+ This routine records an error in library 'lib', function 'func'
+and reason 'reason'. As errors get 'put' into the buffer, they wrap
+around and overwrite old errors if too many are written. It is assumed
+that the last errors are the most important.
+
+unsigned long ERR_get_error(void );
+ This function returns the last error added to the error buffer.
+In effect it is popping the value off the buffer so repeated calls will
+continue to return values until there are no more errors to return in which
+case 0 is returned.
+
+unsigned long ERR_peek_error(void );
+ This function returns the value of the last error added to the
+error buffer but does not 'pop' it from the buffer.
+
+void ERR_clear_error(void );
+ This function clears the error buffer, discarding all unread
+errors.
+
+While the above described error system obviously produces lots of different
+error number, a method for 'reporting' these errors in a human readable
+form is required. To achieve this, each library has the option of
+'registering' error strings.
+
+typedef struct ERR_string_data_st
+ {
+ unsigned long error;
+ char *string;
+ } ERR_STRING_DATA;
+
+The 'ERR_STRING_DATA' contains an error code and the corresponding text
+string. To add new function error strings for a library, the
+ERR_STRING_DATA needs to be 'registered' with the library.
+
+void ERR_load_strings(unsigned long lib,ERR_STRING_DATA *err);
+ This function 'registers' the array of ERR_STRING_DATA pointed to by
+'err' as error text strings for the error library 'lib'.
+
+void ERR_free_strings(void);
+ This function free()s all the loaded error strings.
+
+char *ERR_error_string(unsigned long error,char *buf);
+ This function returns a text string that is a human readable
+version of the error represented by 'error'. Buff should be at least 120
+bytes long and if it is NULL, the return value is a pointer to a static
+variable that will contain the error string, otherwise 'buf' is returned.
+If there is not a text string registered for a particular error, a text
+string containing the error number is returned instead.
+
+void ERR_print_errors(BIO *bp);
+void ERR_print_errors_fp(FILE *fp);
+ This function is a convenience routine that prints the error string
+for each error until all errors have been accounted for.
+
+char *ERR_lib_error_string(unsigned long e);
+char *ERR_func_error_string(unsigned long e);
+char *ERR_reason_error_string(unsigned long e);
+The above three functions return the 3 different components strings for the
+error 'e'. ERR_error_string() uses these functions.
+
+void ERR_load_ERR_strings(void );
+ This function 'registers' the error strings for the 'ERR' module.
+
+void ERR_load_crypto_strings(void );
+ This function 'register' the error strings for just about every
+library in the SSLeay package except for the SSL routines. There is no
+need to ever register any error text strings and you will probably save in
+program size. If on the other hand you do 'register' all errors, it is
+quite easy to determine why a particular routine failed.
+
+As a final footnote as to why the error system is designed as it is.
+1) I did not want a single 'global' error code.
+2) I wanted to know which subroutine a failure occurred in.
+3) For Windows NT etc, it should be simple to replace the 'key' routines
+ with code to pass error codes back to the application.
+4) I wanted the option of meaningful error text strings.
+
+Late breaking news - the changes to support threads.
+
+Each 'thread' has an 'ERR_STATE' state associated with it.
+ERR_STATE *ERR_get_state(void ) will return the 'state' for the calling
+thread/process.
+
+ERR_remove_state(unsigned long pid); will 'free()' this state. If pid == 0
+the current 'thread/process' will have it's error state removed.
+If you do not remove the error state of a thread, this could be considered a
+form of memory leak, so just after 'reaping' a thread that has died,
+call ERR_remove_state(pid).
+
+Have a read of thread.doc for more details for what is required for
+multi-threading support. All the other error routines will
+work correctly when using threads.
+
+
+==== idea.doc ========================================================
+
+The IDEA library.
+IDEA is a block cipher that operates on 64bit (8 byte) quantities. It
+uses a 128bit (16 byte) key. It can be used in all the modes that DES can
+be used. This library implements the ecb, cbc, cfb64 and ofb64 modes.
+
+For all calls that have an 'input' and 'output' variables, they can be the
+same.
+
+This library requires the inclusion of 'idea.h'.
+
+All of the encryption functions take what is called an IDEA_KEY_SCHEDULE as an
+argument. An IDEA_KEY_SCHEDULE is an expanded form of the idea key.
+For all modes of the IDEA algorithm, the IDEA_KEY_SCHEDULE used for
+decryption is different to the one used for encryption.
+
+The define IDEA_ENCRYPT is passed to specify encryption for the functions
+that require an encryption/decryption flag. IDEA_DECRYPT is passed to
+specify decryption. For some mode there is no encryption/decryption
+flag since this is determined by the IDEA_KEY_SCHEDULE.
+
+So to encrypt you would do the following
+idea_set_encrypt_key(key,encrypt_ks);
+idea_ecb_encrypt(...,encrypt_ks);
+idea_cbc_encrypt(....,encrypt_ks,...,IDEA_ENCRYPT);
+
+To Decrypt
+idea_set_encrypt_key(key,encrypt_ks);
+idea_set_decrypt_key(encrypt_ks,decrypt_ks);
+idea_ecb_encrypt(...,decrypt_ks);
+idea_cbc_encrypt(....,decrypt_ks,...,IDEA_DECRYPT);
+
+Please note that any of the encryption modes specified in my DES library
+could be used with IDEA. I have only implemented ecb, cbc, cfb64 and
+ofb64 for the following reasons.
+- ecb is the basic IDEA encryption.
+- cbc is the normal 'chaining' form for block ciphers.
+- cfb64 can be used to encrypt single characters, therefore input and output
+ do not need to be a multiple of 8.
+- ofb64 is similar to cfb64 but is more like a stream cipher, not as
+ secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
+- If you want triple IDEA, thats 384 bits of key and you must be totally
+ obsessed with security. Still, if you want it, it is simple enough to
+ copy the function from the DES library and change the des_encrypt to
+ idea_encrypt; an exercise left for the paranoid reader :-).
+
+The functions are as follows:
+
+void idea_set_encrypt_key(
+unsigned char *key;
+IDEA_KEY_SCHEDULE *ks);
+ idea_set_encrypt_key converts a 16 byte IDEA key into an
+ IDEA_KEY_SCHEDULE. The IDEA_KEY_SCHEDULE is an expanded form of
+ the key which can be used to perform IDEA encryption.
+ An IDEA_KEY_SCHEDULE is an expanded form of the key which is used to
+ perform actual encryption. It can be regenerated from the IDEA key
+ so it only needs to be kept when encryption is about
+ to occur. Don't save or pass around IDEA_KEY_SCHEDULE's since they
+ are CPU architecture dependent, IDEA keys are not.
+
+void idea_set_decrypt_key(
+IDEA_KEY_SCHEDULE *encrypt_ks,
+IDEA_KEY_SCHEDULE *decrypt_ks);
+ This functions converts an encryption IDEA_KEY_SCHEDULE into a
+ decryption IDEA_KEY_SCHEDULE. For all decryption, this conversion
+ of the key must be done. In some modes of IDEA, an
+ encryption/decryption flag is also required, this is because these
+ functions involve block chaining and the way this is done changes
+ depending on which of encryption of decryption is being done.
+ Please note that there is no quick way to generate the decryption
+ key schedule other than generating the encryption key schedule and
+ then converting it.
+
+void idea_encrypt(
+unsigned long *data,
+IDEA_KEY_SCHEDULE *ks);
+ This is the IDEA encryption function that gets called by just about
+ every other IDEA routine in the library. You should not use this
+ function except to implement 'modes' of IDEA. I say this because the
+ functions that call this routine do the conversion from 'char *' to
+ long, and this needs to be done to make sure 'non-aligned' memory
+ access do not occur.
+ Data is a pointer to 2 unsigned long's and ks is the
+ IDEA_KEY_SCHEDULE to use. Encryption or decryption depends on the
+ IDEA_KEY_SCHEDULE.
+
+void idea_ecb_encrypt(
+unsigned char *input,
+unsigned char *output,
+IDEA_KEY_SCHEDULE *ks);
+ This is the basic Electronic Code Book form of IDEA (in DES this
+ mode is called Electronic Code Book so I'm going to use the term
+ for idea as well :-).
+ Input is encrypted into output using the key represented by
+ ks. Depending on the IDEA_KEY_SCHEDULE, encryption or
+ decryption occurs. Input is 8 bytes long and output is 8 bytes.
+
+void idea_cbc_encrypt(
+unsigned char *input,
+unsigned char *output,
+long length,
+IDEA_KEY_SCHEDULE *ks,
+unsigned char *ivec,
+int enc);
+ This routine implements IDEA in Cipher Block Chaining mode.
+ Input, which should be a multiple of 8 bytes is encrypted
+ (or decrypted) to output which will also be a multiple of 8 bytes.
+ The number of bytes is in length (and from what I've said above,
+ should be a multiple of 8). If length is not a multiple of 8, bad
+ things will probably happen. ivec is the initialisation vector.
+ This function updates iv after each call so that it can be passed to
+ the next call to idea_cbc_encrypt().
+
+void idea_cfb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+des_key_schedule ks,
+des_cblock *ivec,
+int *num,
+int enc);
+ This is one of the more useful functions in this IDEA library, it
+ implements CFB mode of IDEA with 64bit feedback.
+ This allows you to encrypt an arbitrary number of bytes,
+ you do not require 8 byte padding. Each call to this
+ routine will encrypt the input bytes to output and then update ivec
+ and num. Num contains 'how far' we are though ivec.
+ Enc is used to indicate encryption or decryption.
+ One very important thing to remember is that when decrypting, use
+ the encryption form of the key.
+ CFB64 mode operates by using the cipher to
+ generate a stream of bytes which is used to encrypt the plain text.
+ The cipher text is then encrypted to generate the next 64 bits to
+ be xored (incrementally) with the next 64 bits of plain
+ text. As can be seen from this, to encrypt or decrypt,
+ the same 'cipher stream' needs to be generated but the way the next
+ block of data is gathered for encryption is different for
+ encryption and decryption. What this means is that to encrypt
+ idea_set_encrypt_key(key,ks);
+ idea_cfb64_encrypt(...,ks,..,IDEA_ENCRYPT)
+ do decrypt
+ idea_set_encrypt_key(key,ks)
+ idea_cfb64_encrypt(...,ks,...,IDEA_DECRYPT)
+ Note: The same IDEA_KEY_SCHEDULE but different encryption flags.
+ For idea_cbc or idea_ecb, idea_set_decrypt_key() would need to be
+ used to generate the IDEA_KEY_SCHEDULE for decryption.
+ The reason I'm stressing this point is that I just wasted 3 hours
+ today trying to decrypt using this mode and the decryption form of
+ the key :-(.
+
+void idea_ofb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+des_key_schedule ks,
+des_cblock *ivec,
+int *num);
+ This functions implements OFB mode of IDEA with 64bit feedback.
+ This allows you to encrypt an arbitrary number of bytes,
+ you do not require 8 byte padding. Each call to this
+ routine will encrypt the input bytes to output and then update ivec
+ and num. Num contains 'how far' we are though ivec.
+ This is in effect a stream cipher, there is no encryption or
+ decryption mode. The same key and iv should be used to
+ encrypt and decrypt.
+
+For reading passwords, I suggest using des_read_pw_string() from my DES library.
+To generate a password from a text string, I suggest using MD5 (or MD2) to
+produce a 16 byte message digest that can then be passed directly to
+idea_set_encrypt_key().
+
+=====
+For more information about the specific IDEA modes in this library
+(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
+documentation on my DES library. What is said about DES is directly
+applicable for IDEA.
+
+
+==== legal.doc ========================================================
+
+From eay@mincom.com Thu Jun 27 00:25:45 1996
+Received: by orb.mincom.oz.au id AA15821
+ (5.65c/IDA-1.4.4 for eay); Wed, 26 Jun 1996 14:25:45 +1000
+Date: Wed, 26 Jun 1996 14:25:45 +1000 (EST)
+From: Eric Young <eay@mincom.oz.au>
+X-Sender: eay@orb
+To: Ken Toll <ktoll@ren.digitalage.com>
+Cc: Eric Young <eay@mincom.oz.au>, ssl-talk@netscape.com
+Subject: Re: Unidentified subject!
+In-Reply-To: <9606261950.ZM28943@ren.digitalage.com>
+Message-Id: <Pine.SOL.3.91.960626131156.28573K-100000@orb>
+Mime-Version: 1.0
+Content-Type: TEXT/PLAIN; charset=US-ASCII
+Status: O
+X-Status:
+
+
+This is a little off topic but since SSLeay is a free implementation of
+the SSLv2 protocol, I feel it is worth responding on the topic of if it
+is actually legal for Americans to use free cryptographic software.
+
+On Wed, 26 Jun 1996, Ken Toll wrote:
+> Is the U.S the only country that SSLeay cannot be used commercially
+> (because of RSAref) or is that going to be an issue with every country
+> that a client/server application (non-web browser/server) is deployed
+> and sold?
+
+>From what I understand, the software patents that apply to algorithms
+like RSA and DH only apply in the USA. The IDEA algorithm I believe is
+patened in europe (USA?), but considing how little it is used by other SSL
+implementations, it quite easily be left out of the SSLeay build
+(this can be done with a compile flag).
+
+Actually if the RSA patent did apply outside the USA, it could be rather
+interesting since RSA is not alowed to let RSA toolkits outside of the USA
+[1], and since these are the only forms that they will alow the algorithm
+to be used in, it would mean that non-one outside of the USA could produce
+public key software which would be a very strong statment for
+international patent law to make :-). This logic is a little flawed but
+it still points out some of the more interesting permutations of USA
+patent law and ITAR restrictions.
+
+Inside the USA there is also the unresolved issue of RC4/RC2 which were
+made public on sci.crypt in Sep 1994 (RC4) and Feb 1996 (RC2). I have
+copies of the origional postings if people are interested. RSA I believe
+claim that they were 'trade-secrets' and that some-one broke an NDA in
+revealing them. Other claim they reverse engineered the algorithms from
+compiled binaries. If the algorithms were reverse engineered, I believe
+RSA had no legal leg to stand on. If an NDA was broken, I don't know.
+Regardless, RSA, I believe, is willing to go to court over the issue so
+licencing is probably the best idea, or at least talk to them.
+If there are people who actually know more about this, pease let me know, I
+don't want to vilify or spread miss-information if I can help it.
+
+If you are not producing a web browser, it is easy to build SSLeay with
+RC2/RC4 removed. Since RC4 is the defacto standard cipher in
+all web software (and it is damn fast) it is more or less required for
+www use. For non www use of SSL, especially for an application where
+interoperability with other vendors is not critical just leave it out.
+
+Removing IDEA, RC2 and RC4 would only leave DES and Triple DES but
+they should be ok. Considing that Triple DES can encrypt at rates of
+410k/sec on a pentium 100, and 940k/sec on a P6/200, this is quite
+reasonable performance. Single DES clocks in at 1160k/s and 2467k/s
+respectivly is actually quite fast for those not so paranoid (56 bit key).[1]
+
+> Is it possible to get a certificate for commercial use outside of the U.S.?
+yes.
+
+Thawte Consulting issues certificates (they are the people who sell the
+ Sioux httpd server and are based in South Africa)
+Verisign will issue certificates for Sioux (sold from South Africa), so this
+ proves that they will issue certificate for OS use if they are
+ happy with the quality of the software.
+
+(The above mentioned companies just the ones that I know for sure are issuing
+ certificates outside the USA).
+
+There is always the point that if you are using SSL for an intra net,
+SSLeay provides programs that can be used so you can issue your own
+certificates. They need polishing but at least it is a good starting point.
+
+I am not doing anything outside Australian law by implementing these
+algorithms (to the best of my knowedge). It is another example of how
+the world legal system does not cope with the internet very well.
+
+I may start making shared libraries available (I have now got DLL's for
+Windows). This will mean that distributions into the usa could be
+shipped with a version with a reduced cipher set and the versions outside
+could use the DLL/shared library with all the ciphers (and without RSAref).
+
+This could be completly hidden from the application, so this would not
+even require a re-linking.
+
+This is the reverse of what people were talking about doing to get around
+USA export regulations :-)
+
+eric
+
+[1]: The RSAref2.0 tookit is available on at least 3 ftp sites in Europe
+ and one in South Africa.
+
+[2]: Since I always get questions when I post benchmark numbers :-),
+ DES performace figures are in 1000's of bytes per second in cbc
+ mode using an 8192 byte buffer. The pentium 100 was running Windows NT
+ 3.51 DLLs and the 686/200 was running NextStep.
+ I quote pentium 100 benchmarks because it is basically the
+ 'entry level' computer that most people buy for personal use.
+ Windows 95 is the OS shipping on those boxes, so I'll give
+ NT numbers (the same Win32 runtime environment). The 686
+ numbers are present as an indication of where we will be in a
+ few years.
+--
+Eric Young | BOOL is tri-state according to Bill Gates.
+AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage().
+
+
+
+==== lhash.doc ========================================================
+
+The LHASH library.
+
+I wrote this library in 1991 and have since forgotten why I called it lhash.
+It implements a hash table from an article I read at the
+time from 'Communications of the ACM'. What makes this hash
+table different is that as the table fills, the hash table is
+increased (or decreased) in size via realloc().
+When a 'resize' is done, instead of all hashes being redistributed over
+twice as many 'buckets', one bucket is split. So when an 'expand' is done,
+there is only a minimal cost to redistribute some values. Subsequent
+inserts will cause more single 'bucket' redistributions but there will
+never be a sudden large cost due to redistributing all the 'buckets'.
+
+The state for a particular hash table is kept in the LHASH structure.
+The LHASH structure also records statistics about most aspects of accessing
+the hash table. This is mostly a legacy of my writing this library for
+the reasons of implementing what looked like a nice algorithm rather than
+for a particular software product.
+
+Internal stuff you probably don't want to know about.
+The decision to increase or decrease the hash table size is made depending
+on the 'load' of the hash table. The load is the number of items in the
+hash table divided by the size of the hash table. The default values are
+as follows. If (hash->up_load < load) => expand.
+if (hash->down_load > load) => contract. The 'up_load' has a default value of
+1 and 'down_load' has a default value of 2. These numbers can be modified
+by the application by just playing with the 'up_load' and 'down_load'
+variables. The 'load' is kept in a form which is multiplied by 256. So
+hash->up_load=8*256; will cause a load of 8 to be set.
+
+If you are interested in performance the field to watch is
+num_comp_calls. The hash library keeps track of the 'hash' value for
+each item so when a lookup is done, the 'hashes' are compared, if
+there is a match, then a full compare is done, and
+hash->num_comp_calls is incremented. If num_comp_calls is not equal
+to num_delete plus num_retrieve it means that your hash function is
+generating hashes that are the same for different values. It is
+probably worth changing your hash function if this is the case because
+even if your hash table has 10 items in a 'bucked', it can be searched
+with 10 'unsigned long' compares and 10 linked list traverses. This
+will be much less expensive that 10 calls to you compare function.
+
+LHASH *lh_new(
+unsigned long (*hash)(),
+int (*cmp)());
+ This function is used to create a new LHASH structure. It is passed
+ function pointers that are used to store and retrieve values passed
+ into the hash table. The 'hash'
+ function is a hashing function that will return a hashed value of
+ it's passed structure. 'cmp' is passed 2 parameters, it returns 0
+ is they are equal, otherwise, non zero.
+ If there are any problems (usually malloc failures), NULL is
+ returned, otherwise a new LHASH structure is returned. The
+ hash value is normally truncated to a power of 2, so make sure
+ that your hash function returns well mixed low order bits.
+
+void lh_free(
+LHASH *lh);
+ This function free()s a LHASH structure. If there is malloced
+ data in the hash table, it will not be freed. Consider using the
+ lh_doall function to deallocate any remaining entries in the hash
+ table.
+
+char *lh_insert(
+LHASH *lh,
+char *data);
+ This function inserts the data pointed to by data into the lh hash
+ table. If there is already and entry in the hash table entry, the
+ value being replaced is returned. A NULL is returned if the new
+ entry does not clash with an entry already in the table (the normal
+ case) or on a malloc() failure (perhaps I should change this....).
+ The 'char *data' is exactly what is passed to the hash and
+ comparison functions specified in lh_new().
+
+char *lh_delete(
+LHASH *lh,
+char *data);
+ This routine deletes an entry from the hash table. The value being
+ deleted is returned. NULL is returned if there is no such value in
+ the hash table.
+
+char *lh_retrieve(
+LHASH *lh,
+char *data);
+ If 'data' is in the hash table it is returned, else NULL is
+ returned. The way these routines would normally be uses is that a
+ dummy structure would have key fields populated and then
+ ret=lh_retrieve(hash,&dummy);. Ret would now be a pointer to a fully
+ populated structure.
+
+void lh_doall(
+LHASH *lh,
+void (*func)(char *a));
+ This function will, for every entry in the hash table, call function
+ 'func' with the data item as parameters.
+ This function can be quite useful when used as follows.
+ void cleanup(STUFF *a)
+ { STUFF_free(a); }
+ lh_doall(hash,cleanup);
+ lh_free(hash);
+ This can be used to free all the entries, lh_free() then
+ cleans up the 'buckets' that point to nothing. Be careful
+ when doing this. If you delete entries from the hash table,
+ in the call back function, the table may decrease in size,
+ moving item that you are
+ currently on down lower in the hash table. This could cause
+ some entries to be skipped. The best solution to this problem
+ is to set lh->down_load=0 before you start. This will stop
+ the hash table ever being decreased in size.
+
+void lh_doall_arg(
+LHASH *lh;
+void(*func)(char *a,char *arg));
+char *arg;
+ This function is the same as lh_doall except that the function
+ called will be passed 'arg' as the second argument.
+
+unsigned long lh_strhash(
+char *c);
+ This function is a demo string hashing function. Since the LHASH
+ routines would normally be passed structures, this routine would
+ not normally be passed to lh_new(), rather it would be used in the
+ function passed to lh_new().
+
+The next three routines print out various statistics about the state of the
+passed hash table. These numbers are all kept in the lhash structure.
+
+void lh_stats(
+LHASH *lh,
+FILE *out);
+ This function prints out statistics on the size of the hash table,
+ how many entries are in it, and the number and result of calls to
+ the routines in this library.
+
+void lh_node_stats(
+LHASH *lh,
+FILE *out);
+ For each 'bucket' in the hash table, the number of entries is
+ printed.
+
+void lh_node_usage_stats(
+LHASH *lh,
+FILE *out);
+ This function prints out a short summary of the state of the hash
+ table. It prints what I call the 'load' and the 'actual load'.
+ The load is the average number of data items per 'bucket' in the
+ hash table. The 'actual load' is the average number of items per
+ 'bucket', but only for buckets which contain entries. So the
+ 'actual load' is the average number of searches that will need to
+ find an item in the hash table, while the 'load' is the average number
+ that will be done to record a miss.
+
+==== md2.doc ========================================================
+
+The MD2 library.
+MD2 is a message digest algorithm that can be used to condense an arbitrary
+length message down to a 16 byte hash. The functions all need to be passed
+a MD2_CTX which is used to hold the MD2 context during multiple MD2_Update()
+function calls. The normal method of use for this library is as follows
+
+MD2_Init(...);
+MD2_Update(...);
+...
+MD2_Update(...);
+MD2_Final(...);
+
+This library requires the inclusion of 'md2.h'.
+
+The main negative about MD2 is that it is slow, especially when compared
+to MD5.
+
+The functions are as follows:
+
+void MD2_Init(
+MD2_CTX *c);
+ This function needs to be called to initiate a MD2_CTX structure for
+ use.
+
+void MD2_Update(
+MD2_CTX *c;
+unsigned char *data;
+unsigned long len);
+ This updates the message digest context being generated with 'len'
+ bytes from the 'data' pointer. The number of bytes can be any
+ length.
+
+void MD2_Final(
+unsigned char *md;
+MD2_CTX *c;
+ This function is called when a message digest of the data digested
+ with MD2_Update() is wanted. The message digest is put in the 'md'
+ array and is MD2_DIGEST_LENGTH (16) bytes long.
+
+unsigned char *MD2(
+unsigned long n;
+unsigned char *d;
+unsigned char *md;
+ This function performs a MD2_Init(), followed by a MD2_Update()
+ followed by a MD2_Final() (using a local MD2_CTX).
+ The resulting digest is put into 'md' if it is not NULL.
+ Regardless of the value of 'md', the message
+ digest is returned from the function. If 'md' was NULL, the message
+ digest returned is being stored in a static structure.
+
+==== md5.doc ========================================================
+
+The MD5 library.
+MD5 is a message digest algorithm that can be used to condense an arbitrary
+length message down to a 16 byte hash. The functions all need to be passed
+a MD5_CTX which is used to hold the MD5 context during multiple MD5_Update()
+function calls. This library also contains random number routines that are
+based on MD5
+
+The normal method of use for this library is as follows
+
+MD5_Init(...);
+MD5_Update(...);
+...
+MD5_Update(...);
+MD5_Final(...);
+
+This library requires the inclusion of 'md5.h'.
+
+The functions are as follows:
+
+void MD5_Init(
+MD5_CTX *c);
+ This function needs to be called to initiate a MD5_CTX structure for
+ use.
+
+void MD5_Update(
+MD5_CTX *c;
+unsigned char *data;
+unsigned long len);
+ This updates the message digest context being generated with 'len'
+ bytes from the 'data' pointer. The number of bytes can be any
+ length.
+
+void MD5_Final(
+unsigned char *md;
+MD5_CTX *c;
+ This function is called when a message digest of the data digested
+ with MD5_Update() is wanted. The message digest is put in the 'md'
+ array and is MD5_DIGEST_LENGTH (16) bytes long.
+
+unsigned char *MD5(
+unsigned char *d;
+unsigned long n;
+unsigned char *md;
+ This function performs a MD5_Init(), followed by a MD5_Update()
+ followed by a MD5_Final() (using a local MD5_CTX).
+ The resulting digest is put into 'md' if it is not NULL.
+ Regardless of the value of 'md', the message
+ digest is returned from the function. If 'md' was NULL, the message
+ digest returned is being stored in a static structure.
+
+
+==== memory.doc ========================================================
+
+In the interests of debugging SSLeay, there is an option to compile
+using some simple memory leak checking.
+
+All malloc(), free() and realloc() calls in SSLeay now go via
+Malloc(), Free() and Realloc() (except those in crypto/lhash).
+
+If CRYPTO_MDEBUG is defined, these calls are #defined to
+CRYPTO_malloc(), CRYPTO_free() and CRYPTO_realloc().
+If it is not defined, they are #defined to malloc(), free() and realloc().
+
+the CRYPTO_malloc() routines by default just call the underlying library
+functons.
+
+If CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON) is called, memory leak detection is
+turned on. CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_OFF) turns it off.
+
+When turned on, each Malloc() or Realloc() call is recored along with the file
+and line number from where the call was made. (This is done using the
+lhash library which always uses normal system malloc(3) routines).
+
+void CRYPTO_mem_leaks(BIO *b);
+void CRYPTO_mem_leaks_fp(FILE *fp);
+These both print out the list of memory that has not been free()ed.
+This will probably be rather hard to read, but if you look for the 'top level'
+structure allocation, this will often give an idea as to what is not being
+free()ed. I don't expect people to use this stuff normally.
+
+==== ca.1 ========================================================
+
+From eay@orb.mincom.oz.au Thu Dec 28 23:56:45 1995
+Received: by orb.mincom.oz.au id AA07374
+ (5.65c/IDA-1.4.4 for eay); Thu, 28 Dec 1995 13:56:45 +1000
+Date: Thu, 28 Dec 1995 13:56:45 +1000 (EST)
+From: Eric Young <eay@mincom.oz.au>
+X-Sender: eay@orb
+To: sameer <sameer@c2.org>
+Cc: ssleay@mincom.oz.au
+Subject: Re: 'ca'
+In-Reply-To: <199512230440.UAA23410@infinity.c2.org>
+Message-Id: <Pine.SOL.3.91.951228133525.7269A-100000@orb>
+Mime-Version: 1.0
+Content-Type: TEXT/PLAIN; charset=US-ASCII
+Status: RO
+X-Status:
+
+On Fri, 22 Dec 1995, sameer wrote:
+> I could use documentation on 'ca'. Thanks.
+
+Very quickly.
+The ca program uses the ssleay.conf file for most of its configuration
+
+./ca -help
+
+ -verbose - Talk alot while doing things
+ -config file - A config file. If you don't want to use the
+ default config file
+ -name arg - The particular CA definition to use
+ In the config file, the section to use for parameters. This lets
+ multiple setups to be contained in the one file. By default, the
+ default_ca variable is looked up in the [ ca ] section. So in the
+ shipped ssleay.conf, the CA definition used is CA_default. It could be
+ any other name.
+ -gencrl days - Generate a new CRL, days is when the next CRL is due
+ This will generate a new certificate revocion list.
+ -days arg - number of days to certify the certificate for
+ When certifiying certificates, this is the number of days to use.
+ -md arg - md to use, one of md2, md5, sha or sha1
+ -policy arg - The CA 'policy' to support
+ I'll describe this later, but there are 2 policies definied in the
+ shipped ssleay.conf
+ -keyfile arg - PEM RSA private key file
+ -key arg - key to decode the RSA private key if it is encrypted
+ since we need to keep the CA's RSA key encrypted
+ -cert - The CA certificate
+ -in file - The input PEM encoded certificate request(s)
+ -out file - Where to put the output file(s)
+ -outdir dir - Where to put output certificates
+ The -out options concatinates all the output certificied
+ certificates to one file, -outdir puts them in a directory,
+ named by serial number.
+ -infiles .... - The last argument, requests to process
+ The certificate requests to process, -in is the same.
+
+Just about all the above have default values defined in ssleay.conf.
+
+The key variables in ssleay.conf are (for the pariticular '-name' being
+used, in the default, it is CA_default).
+
+dir is where all the CA database stuff is kept.
+certs is where all the previously issued certificates are kept.
+The database is a simple text database containing the following tab separated
+fields.
+status: a value of 'R' - revoked, 'E' -expired or 'V' valid.
+issued date: When the certificate was certified.
+revoked date: When it was revoked, blank if not revoked.
+serial number: The certificate serial number.
+certificate: Where the certificate is located.
+CN: The name of the certificate.
+
+The demo file has quite a few made up values it it. The last 2 were
+added by the ca program and are acurate.
+The CA program does not update the 'certificate' file correctly right now.
+The serial field should be unique as should the CN/status combination.
+The ca program checks these at startup. What still needs to be
+wrtten is a program to 'regenerate' the data base file from the issued
+certificate list (and a CRL list).
+
+Back to the CA_default variables.
+
+Most of the variables are commented.
+
+policy is the default policy.
+
+Ok for policies, they define the order and which fields must be present
+in the certificate request and what gets filled in.
+
+So a value of
+countryName = match
+means that the country name must match the CA certificate.
+organizationalUnitName = optional
+The org.Unit,Name does not have to be present and
+commonName = supplied
+commonName must be supplied in the certificate request.
+
+For the 'policy_match' polocy, the order of the attributes in the
+generated certiticate would be
+countryName
+stateOrProvinceName
+organizationName
+organizationalUnitName
+commonName
+emailAddress
+
+Have a play, it sort of makes sense. If you think about how the persona
+requests operate, it is similar to the 'policy_match' policy and the
+'policy_anything' is similar to what versign is doing.
+
+I hope this helps a bit. Some backend scripts are definitly needed to
+update the database and to make certificate revocion easy. All
+certificates issued should also be kept forever (or until they expire?)
+
+hope this helps
+eric (who has to run off an buy some cheap knee pads for the caving in 4
+days time :-)
+
+--
+Eric Young | Signature removed since it was generating
+AARNet: eay@mincom.oz.au | more followups than the message contents :-)
+
+
+==== ms3-ca.doc ========================================================
+
+Date: Mon, 9 Jun 97 08:00:33 +0200
+From: Holger.Reif@PrakInf.TU-Ilmenau.DE (Holger Reif)
+Subject: ms3-ca.doc
+Organization: TU Ilmenau, Fak. IA, FG Telematik
+Content-Length: 14575
+Status: RO
+X-Status:
+
+Loading client certs into MSIE 3.01
+===================================
+
+This document contains all the information necessary to successfully set up
+some scripts to issue client certs to Microsoft Internet Explorer. It
+includes the required knowledge about the model MSIE uses for client
+certification and includes complete sample scripts ready to play with. The
+scripts were tested against a modified ca program of SSLeay 0.6.6 and should
+work with the regular ca program that comes with version 0.8.0. I haven't
+tested against MSIE 4.0
+
+You can use the information contained in this document in either way you
+want. However if you feel it saved you a lot of time I ask you to be as fair
+as to mention my name: Holger Reif <reif@prakinf.tu-ilmenau.de>.
+
+1.) The model used by MSIE
+--------------------------
+
+The Internet Explorer doesn't come with a embedded engine for installing
+client certs like Netscape's Navigator. It rather uses the CryptoAPI (CAPI)
+defined by Microsoft. CAPI comes with WindowsNT 4.0 or is installed together
+with Internet Explorer since 3.01. The advantage of this approach is a higher
+flexibility because the certificates in the (per user) system open
+certificate store may be used by other applications as well. The drawback
+however is that you need to do a bit more work to get a client cert issued.
+
+CAPI defines functions which will handle basic cryptographic work, eg.
+generating keys, encrypting some data, signing text or building a certificate
+request. The procedure is as follows: A CAPI function generates you a key
+pair and saves it into the certificate store. After that one builds a
+Distinguished Name. Together with that key pair another CAPI function forms a
+PKCS#10 request which you somehow need to submit to a CA. Finally the issued
+cert is given to a yet another CAPI function which saves it into the
+certificate store.
+
+The certificate store with the user's keys and certs is in the registry. You
+will find it under HKEY_CURRENT_USER/Software/Microsoft/Cryptography/ (I
+leave it to you as a little exercise to figure out what all the entries mean
+;-). Note that the keys are protected only with the user's usual Windows
+login password.
+
+2.) The practical usage
+-----------------------
+
+Unfortunatly since CAPI is a system API you can't access its functions from
+HTML code directly. For this purpose Microsoft provides a wrapper called
+certenr3.dll. This DLL accesses the CAPI functions and provides an interface
+usable from Visual Basic Script. One needs to install that library on the
+computer which wants to have client cert. The easiest way is to load it as an
+ActiveX control (certenr3.dll is properly authenticode signed by MS ;-). If
+you have ever enrolled e cert request at a CA you will have installed it.
+
+At time of writing certenr3.dll is contained in
+http://www.microsoft.com/workshop/prog/security/csa/certenr3.exe. It comes
+with an README file which explains the available functions. It is labeled
+beta but every CA seems to use it anyway. The license.txt allows you the
+usage for your own purposes (as far as I understood) and a somehow limited
+distribution.
+
+The two functions of main interest are GenerateKeyPair and AcceptCredentials.
+For complete explanation of all possible parameters see the README file. Here
+are only minimal required parameters and their values.
+
+GenerateKeyPair(sessionID, FASLE, szName, 0, "ClientAuth", TRUE, FALSE, 1)
+- sessionID is a (locally to that computer) unique string to correlate the
+generated key pair with a cert installed later.
+- szName is the DN of the form "C=DE; S=Thueringen; L=Ilmenau; CN=Holger
+Reif; 1.2.840.113549.1.9.1=reif@prakinf.tu-ilmenau.de". Note that S is the
+abreviation for StateOrProvince. The recognized abreviation include CN, O, C,
+OU, G, I, L, S, T. If the abreviation is unknown (eg. for PKCS#9 email addr)
+you need to use the full object identifier. The starting point for searching
+them could be crypto/objects.h since all OIDs know to SSLeay are listed
+there.
+- note: the possible ninth parameter which should give a default name to the
+certificate storage location doesn't seem to work. Changes to the constant
+values in the call above doesn't seem to make sense. You can't generate
+PKCS#10 extensions with that function.
+
+The result of GenerateKeyPair is the base64 encoded PKCS#10 request. However
+it has a little strange format that SSLeay doesn't accept. (BTW I feel the
+decision of rejecting that format as standard conforming.) It looks like
+follows:
+ 1st line with 76 chars
+ 2nd line with 76 chars
+ ...
+ (n-2)th line with 76 chars
+ (n-1)th line contains a multiple of 4 chars less then 76 (possible
+empty)
+ (n)th line has zero or 4 chars (then with 1 or 2 equal signs - the
+ original text's lenght wasn'T a multiple of 3)
+ The line separator has two chars: 0x0d 0x0a
+
+AcceptCredentials(sessionID, credentials, 0, FALSE)
+- sessionID needs to be the same as while generating the key pair
+- credentials is the base64 encoded PKCS#7 object containing the cert.
+
+CRL's and CA certs are not required simply just the client cert. (It seems to
+me that both are not even checked somehow.) The only format of the base64
+encoded object I succesfully used was all characters in a very long string
+without line feeds or carriage returns. (Hey, it doesn't matter, only a
+computer reads it!)
+
+The result should be S_OK. For error handling see the example that comes with
+certenr3.dll.
+
+A note about ASN.1 character encodings. certenr3.dll seems to know only about
+2 of them: UniversalString and PrintableString. First it is definitely wrong
+for an email address which is IA5STRING (checked by ssleay's ca). Second
+unfortunately MSIE (at least until version 3.02) can't handle UniversalString
+correctly - they just blow up you cert store! Therefore ssleay's ca (starting
+from version 0.8.0) tries to convert the encodings automatically to IA5STRING
+or TeletexString. The beef is it will work only for the latin-1 (western)
+charset. Microsoft still has to do abit of homework...
+
+3.) An example
+--------------
+
+At least you need two steps: generating the key & request and then installing
+the certificate. A real world CA would have some more steps involved, eg.
+accepting some license. Note that both scripts shown below are just
+experimental state without any warrenty!
+
+First how to generate a request. Note that we can't use a static page because
+of the sessionID. I generate it from system time plus pid and hope it is
+unique enough. Your are free to feed it through md5 to get more impressive
+ID's ;-) Then the intended text is read in with sed which inserts the
+sessionID.
+
+-----BEGIN ms-enroll.cgi-----
+#!/bin/sh
+SESSION_ID=`date '+%y%m%d%H%M%S'`$$
+echo Content-type: text/html
+echo
+sed s/template_for_sessId/$SESSION_ID/ <<EOF
+<HTML><HEAD>
+<TITLE>Certificate Enrollment Test Page</TITLE>
+</HEAD><BODY>
+
+<OBJECT
+ classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43"
+ codebase=certenr3.dll
+ id=certHelper
+ >
+</OBJECT>
+
+<CENTER>
+<H2>enrollment for a personal cert</H2>
+<BR><HR WIDTH=50%><BR><P>
+<FORM NAME="MSIE_Enrollment" ACTION="ms-gencert.cgi" ENCTYPE=x-www-form-
+encoded METHOD=POST>
+<TABLE>
+ <TR><TD>Country</TD><TD><INPUT NAME="Country" VALUE=""></TD></TR>
+ <TR><TD>State</TD><TD><INPUT NAME="StateOrProvince" VALUE=""></TD></TR>
+ <TR><TD>Location</TD><TD><INPUT NAME="Location" VALUE=""></TD></TR>
+ <TR><TD>Organization</TD><TD><INPUT NAME="Organization"
+VALUE=""></TD></TR>
+ <TR><TD>Organizational Unit</TD>
+ <TD><INPUT NAME="OrganizationalUnit" VALUE=""></TD></TR>
+ <TR><TD>Name</TD><TD><INPUT NAME="CommonName" VALUE=""></TD></TR>
+ <TR><TD>eMail Address</TD>
+ <TD><INPUT NAME="EmailAddress" VALUE=""></TD></TR>
+ <TR><TD></TD>
+ <TD><INPUT TYPE="BUTTON" NAME="submit" VALUE="Beantragen"></TD></TR>
+</TABLE>
+ <INPUT TYPE="hidden" NAME="SessionId" VALUE="template_for_sessId">
+ <INPUT TYPE="hidden" NAME="Request" VALUE="">
+</FORM>
+<BR><HR WIDTH=50%><BR><P>
+</CENTER>
+
+<SCRIPT LANGUAGE=VBS>
+ Dim DN
+
+ Sub Submit_OnClick
+ Dim TheForm
+ Set TheForm = Document.MSIE_Enrollment
+ sessionId = TheForm.SessionId.value
+ reqHardware = FALSE
+ C = TheForm.Country.value
+ SP = TheForm.StateOrProvince.value
+ L = TheForm.Location.value
+ O = TheForm.Organization.value
+ OU = TheForm.OrganizationalUnit.value
+ CN = TheForm.CommonName.value
+ Email = TheForm.EmailAddress.value
+ szPurpose = "ClientAuth"
+ doAcceptanceUINow = FALSE
+ doOnline = TRUE
+
+ DN = ""
+
+ Call Add_RDN("C", C)
+ Call Add_RDN("S", SP)
+ Call Add_RDN("L", L)
+ Call Add_RDN("O", O)
+ Call Add_RDN("OU", OU)
+ Call Add_RDN("CN", CN)
+ Call Add_RDN("1.2.840.113549.1.9.1", Email)
+ ' rsadsi
+ ' pkcs
+ ' pkcs9
+ ' eMailAddress
+ On Error Resume Next
+ sz10 = certHelper.GenerateKeyPair(sessionId, _
+ FALSE, DN, 0, ClientAuth, FASLE, TRUE, 1)_
+ theError = Err.Number
+ On Error Goto 0
+ if (sz10 = Empty OR theError <> 0) Then
+ sz = "The error '" & Hex(theError) & "' occurred." & chr(13) & _
+ chr(10) & "Your credentials could not be generated."
+ result = MsgBox(sz, 0, "Credentials Enrollment")
+ Exit Sub
+ else
+ TheForm.Request.value = sz10
+ TheForm.Submit
+ end if
+ End Sub
+
+ Sub Add_RDN(sn, value)
+ if (value <> "") then
+ if (DN <> "") then
+ DN = DN & "; "
+ end if
+ DN = DN & sn & "=" & value
+ end if
+ End Sub
+</SCRIPT>
+</BODY>
+</HTML>
+EOF
+-----END ms-enroll.cgi-----
+
+Second, how to extract the request and feed the certificate back? We need to
+"normalize" the base64 encoding of the PKCS#10 format which means
+regenerating the lines and wrapping with BEGIN and END line. This is done by
+gawk. The request is taken by ca the normal way. Then the cert needs to be
+packed into a PKCS#7 structure (note: the use of a CRL is necessary for
+crl2pkcs7 as of version 0.6.6. Starting with 0.8.0 it it might probably be
+ommited). Finally we need to format the PKCS#7 object and generate the HTML
+text. I use two templates to have a clearer script.
+
+1st note: postit2 is slightly modified from a program I found at ncsa's ftp
+site. Grab it from http://www.easterngraphics.com/certs/IX9704/postit2.c. You
+need utils.c from there too.
+
+2nd note: I'm note quite sure wether the gawk script really handles all
+possible inputs for the request right! Today I don't use this construction
+anymore myself.
+
+3d note: the cert must be of version 3! This could be done with the nsComment
+line in ssleay.cnf...
+
+------BEGIN ms-gencert.cgi-----
+#!/bin/sh
+FILE="/tmp/"`date '+%y%m%d%H%M%S'-`$$
+rm -f "$FILE".*
+
+HOME=`pwd`; export HOME # as ssleay.cnf insists on having such an env var
+cd /usr/local/ssl #where demoCA (as named in ssleay.conf) is located
+
+postit2 -s " " -i 0x0d > "$FILE".inp # process the FORM vars
+
+SESSION_ID=`gawk '$1 == "SessionId" { print $2; exit }' "$FILE".inp`
+
+gawk \
+ 'BEGIN { \
+ OFS = ""; \
+ print "-----BEGIN CERTIFICATE REQUEST-----"; \
+ req_seen=0 \
+ } \
+ $1 == "Request" { \
+ req_seen=1; \
+ if (length($2) == 72) print($2); \
+ lastline=$2; \
+ next; \
+ } \
+ { \
+ if (req_seen == 1) { \
+ if (length($1) >= 72) print($1); \
+ else if (length(lastline) < 72) { \
+ req_seen=0; \
+ print (lastline,$1); \
+ } \
+ lastline=$1; \
+ } \
+ } \
+ END { \
+ print "-----END CERTIFICATE REQUEST-----"; \
+ }' > "$FILE".pem < "$FILE".inp
+
+ssleay ca -batch -in "$FILE".pem -key passwd -out "$FILE".out
+ssleay crl2pkcs7 -certfile "$FILE".out -out "$FILE".pkcs7 -in demoCA/crl.pem
+
+sed s/template_for_sessId/$SESSION_ID/ <ms-enroll2a.html >"$FILE".cert
+/usr/local/bin/gawk \
+ 'BEGIN { \
+ OFS = ""; \
+ dq = sprintf("%c",34); \
+ } \
+ $0 ~ "PKCS7" { next; } \
+ { \
+ print dq$0dq" & _"; \
+ }' <"$FILE".pkcs7 >> "$FILE".cert
+cat ms-enroll2b.html >>"$FILE".cert
+
+echo Content-type: text/html
+echo Content-length: `wc -c "$FILE".cert`
+echo
+cat "$FILE".cert
+rm -f "$FILE".*
+-----END ms-gencert.cgi-----
+
+----BEGIN ms-enroll2a.html----
+<HTML><HEAD><TITLE>Certificate Acceptance Test Page</TITLE></HEAD><BODY>
+
+<OBJECT
+ classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43"
+ codebase=certenr3.dll
+ id=certHelper
+ >
+</OBJECT>
+
+<CENTER>
+<H2>Your personal certificate</H2>
+<BR><HR WIDTH=50%><BR><P>
+Press the button!
+<P><INPUT TYPE=BUTTON VALUE="Nimm mich!" NAME="InstallCert">
+</CENTER>
+<BR><HR WIDTH=50%><BR>
+
+<SCRIPT LANGUAGE=VBS>
+ Sub InstallCert_OnClick
+
+ sessionId = "template_for_sessId"
+credentials = "" & _
+----END ms-enroll2a.html----
+
+----BEGIN ms-enroll2b.html----
+""
+ On Error Resume Next
+ result = certHelper.AcceptCredentials(sessionId, credentials, 0,
+FALSE)
+ if (IsEmpty(result)) Then
+ sz = "The error '" & Err.Number & "' occurred." & chr(13) &
+chr(10) & "This Digital ID could not be registered."
+ msgOut = MsgBox(sz, 0, "Credentials Registration Error")
+ navigate "error.html"
+ else
+ sz = "Digital ID successfully registered."
+ msgOut = MsgBox(sz, 0, "Credentials Registration")
+ navigate "success.html"
+ end if
+ Exit Sub
+ End Sub
+</SCRIPT>
+</BODY>
+</HTML>
+----END ms-enroll2b.html----
+
+4.) What do do with the cert?
+-----------------------------
+
+The cert is visible (without restarting MSIE) under the following menu:
+View->Options->Security->Personal certs. You can examine it's contents at
+least partially.
+
+To use it for client authentication you need to use SSL3.0 (fortunately
+SSLeay supports it with 0.8.0). Furthermore MSIE is told to only supports a
+kind of automatic selection of certs (I personally wasn't able to test it
+myself). But there is a requirement that the issuer of the server cert and
+the issuer of the client cert needs to be the same (according to a developer
+from MS). Which means: you need may more then one cert to talk to all
+servers...
+
+I'm sure we will get a bit more experience after ApacheSSL is available for
+SSLeay 0.8.8.
+
+
+I hope you enjoyed reading and that in future questions on this topic will
+rarely appear on ssl-users@moncom.com ;-)
+
+Ilmenau, 9th of June 1997
+Holger Reif <reif@prakinf.tu-ilmenau.de>
+--
+read you later - Holger Reif
+---------------------------------------- Signaturprojekt Deutsche Einheit
+TU Ilmenau - Informatik - Telematik (Verdamp lang her)
+Holger.Reif@PrakInf.TU-Ilmenau.DE Alt wie ein Baum werden, um ueber
+http://Remus.PrakInf.TU-Ilmenau.DE/Reif/ alle 7 Bruecken gehen zu koennen
+
+
+==== ns-ca.doc ========================================================
+
+The following documentation was supplied by Jeff Barber, who provided the
+patch to the CA program to add this functionality.
+
+eric
+--
+Jeff Barber Email: jeffb@issl.atl.hp.com
+
+Hewlett Packard Phone: (404) 648-9503
+Internet and System Security Lab Fax: (404) 648-9516
+
+ oo
+---------------------cut /\ here for ns-ca.doc ------------------------------
+
+This document briefly describes how to use SSLeay to implement a
+certificate authority capable of dynamically serving up client
+certificates for version 3.0 beta 5 (and presumably later) versions of
+the Netscape Navigator. Before describing how this is done, it's
+important to understand a little about how the browser implements its
+client certificate support. This is documented in some detail in the
+URLs based at <URL:http://home.netscape.com/eng/security/certs.html>.
+Here's a brief overview:
+
+- The Navigator supports a new HTML tag "KEYGEN" which will cause
+ the browser to generate an RSA key pair when you submit a form
+ containing the tag. The public key, along with an optional
+ challenge (supposedly provided for use in certificate revocation
+ but I don't use it) is signed, DER-encoded, base-64 encoded
+ and sent to the web server as the value of the variable
+ whose NAME is provided in the KEYGEN tag. The private key is
+ stored by the browser in a local key database.
+
+ This "Signed Public Key And Challenge" (SPKAC) arrives formatted
+ into 64 character lines (which are of course URL-encoded when
+ sent via HTTP -- i.e. spaces, newlines and most punctuatation are
+ encoded as "%HH" where HH is the hex equivalent of the ASCII code).
+ Note that the SPKAC does not contain the other usual attributes
+ of a certificate request, especially the subject name fields.
+ These must be otherwise encoded in the form for submission along
+ with the SPKAC.
+
+- Either immediately (in response to this form submission), or at
+ some later date (a real CA will probably verify your identity in
+ some way before issuing the certificate), a web server can send a
+ certificate based on the public key and other attributes back to
+ the browser by encoding it in DER (the binary form) and sending it
+ to the browser as MIME type:
+ "Content-type: application/x-x509-user-cert"
+
+ The browser uses the public key encoded in the certificate to
+ associate the certificate with the appropriate private key in
+ its local key database. Now, the certificate is "installed".
+
+- When a server wants to require authentication based on client
+ certificates, it uses the right signals via the SSL protocol to
+ trigger the Navigator to ask you which certificate you want to
+ send. Whether the certificate is accepted is dependent on CA
+ certificates and so forth installed in the server and is beyond
+ the scope of this document.
+
+
+Now, here's how the SSLeay package can be used to provide client
+certficates:
+
+- You prepare a file for input to the SSLeay ca application.
+ The file contains a number of "name = value" pairs that identify
+ the subject. The names here are the same subject name component
+ identifiers used in the CA section of the lib/ssleay.conf file,
+ such as "emailAddress", "commonName" "organizationName" and so
+ forth. Both the long version and the short version (e.g. "Email",
+ "CN", "O") can be used.
+
+ One more name is supported: this one is "SPKAC". Its value
+ is simply the value of the base-64 encoded SPKAC sent by the
+ browser (with all the newlines and other space charaters
+ removed -- and newline escapes are NOT supported).
+
+ [ As of SSLeay 0.6.4, multiple lines are supported.
+ Put a \ at the end of each line and it will be joined with the
+ previous line with the '\n' removed - eay ]
+
+ Here's a sample input file:
+
+C = US
+SP = Georgia
+O = Some Organization, Inc.
+OU = Netscape Compatibility Group
+CN = John X. Doe
+Email = jxdoe@someorg.com
+SPKAC = MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAwmk6FMJ4uAVIYbcvIOx5+bDGTfvL8X5gE+R67ccMk6rCSGbVQz2cetyQtnI+VIs0NwdD6wjuSuVtVFbLoHonowIDAQABFgAwDQYJKoZIhvcNAQEEBQADQQBFZDUWFl6BJdomtN1Bi53mwijy1rRgJ4YirF15yBEDM3DjAQkKXHYOIX+qpz4KXKnl6EYxTnGSFL5wWt8X2iyx
+
+- You execute the ca command (either from a CGI program run out of
+ the web server, or as a later manual task) giving it the above
+ file as input. For example, if the file were named /tmp/cert.req,
+ you'd run:
+ $SSLDIR/bin/ca -spkac /tmp/cert.req -out /tmp/cert
+
+ The output is in DER format (binary) if a -out argument is
+ provided, as above; otherwise, it's in the PEM format (base-64
+ encoded DER). Also, the "-batch" switch is implied by the
+ "-spkac" so you don't get asked whether to complete the signing
+ (probably it shouldn't work this way but I was only interested
+ in hacking together an online CA that could be used for issuing
+ test certificates).
+
+ The "-spkac" capability doesn't support multiple files (I think).
+
+ Any CHALLENGE provided in the SPKAC is simply ignored.
+
+ The interactions between the identification fields you provide
+ and those identified in your lib/ssleay.conf are the same as if
+ you did an ordinary "ca -in infile -out outfile" -- that is, if
+ something is marked as required in the ssleay.conf file and it
+ isn't found in the -spkac file, the certificate won't be issued.
+
+- Now, you pick up the output from /tmp/cert and pass it back to
+ the Navigator prepending the Content-type string described earlier.
+
+- In order to run the ca command out of a CGI program, you must
+ provide a password to decrypt the CA's private key. You can
+ do this by using "echo MyKeyPassword | $SSLDIR/bin/ca ..."
+ I think there's a way to not encrypt the key file in the first
+ place, but I didn't see how to do that, so I made a small change
+ to the library that allows the password to be accepted from a pipe.
+ Either way is UTTERLY INSECURE and a real CA would never do that.
+
+ [ You can use the 'ssleay rsa' command to remove the password
+ from the private key, or you can use the '-key' option to the
+ ca command to specify the decryption key on the command line
+ or use the -nodes option when generating the key.
+ ca will try to clear the command line version of the password
+ but for quite a few operating systems, this is not possible.
+ - eric ]
+
+So, what do you have to do to make use of this stuff to create an online
+demo CA capability with SSLeay?
+
+1 Create an HTML form for your users. The form should contain
+ fields for all of the required or optional fields in ssleay.conf.
+ The form must contain a KEYGEN tag somewhere with at least a NAME
+ attribute.
+
+2 Create a CGI program to process the form input submitted by the
+ browser. The CGI program must URL-decode the variables and create
+ the file described above, containing subject identification info
+ as well as the SPKAC block. It should then run the the ca program
+ with the -spkac option. If it works (check the exit status),
+ return the new certificate with the appropriate MIME type. If not,
+ return the output of the ca command with MIME type "text/plain".
+
+3 Set up your web server to accept connections signed by your demo
+ CA. This probably involves obtaining the PEM-encoded CA certificate
+ (ordinarily in $SSLDIR/CA/cacert.pem) and installing it into a
+ server database. See your server manual for instructions.
+
+
+==== obj.doc ========================================================
+
+The Object library.
+
+As part of my Crypto library, I found I required a method of identifying various
+objects. These objects normally had 3 different values associated with
+them, a short text name, a long (or lower case) text name, and an
+ASN.1 Object Identifier (which is a sequence of numbers).
+This library contains a static list of objects and functions to lookup
+according to one type and to return the other types.
+
+To use these routines, 'Object.h' needs to be included.
+
+For each supported object, #define entries are defined as follows
+#define SN_Algorithm "Algorithm"
+#define LN_algorithm "algorithm"
+#define NID_algorithm 38
+#define OBJ_algorithm 1L,3L,14L,3L,2L
+
+SN_ stands for short name.
+LN_ stands for either long name or lowercase name.
+NID_ stands for Numeric ID. I each object has a unique NID and this
+ should be used internally to identify objects.
+OBJ_ stands for ASN.1 Object Identifier or ASN1_OBJECT as defined in the
+ ASN1 routines. These values are used in ASN1 encoding.
+
+The following functions are to be used to return pointers into a static
+definition of these types. What this means is "don't try to free() any
+pointers returned from these functions.
+
+ASN1_OBJECT *OBJ_nid2obj(
+int n);
+ Return the ASN1_OBJECT that corresponds to a NID of n.
+
+char *OBJ_nid2ln(
+int n);
+ Return the long/lower case name of the object represented by the
+ NID of n.
+
+char *OBJ_nid2sn(
+int n);
+ Return the short name for the object represented by the NID of n.
+
+ASN1_OBJECT *OBJ_dup(
+ASN1_OBJECT *o);
+ Duplicate and return a new ASN1_OBJECT that is the same as the
+ passed parameter.
+
+int OBJ_obj2nid(
+ASN1_OBJECT *o);
+ Given ASN1_OBJECT o, return the NID that corresponds.
+
+int OBJ_ln2nid(
+char *s);
+ Given the long/lower case name 's', return the NID of the object.
+
+int OBJ_sn2nid(
+char *s);
+ Given the short name 's', return the NID of the object.
+
+char *OBJ_bsearch(
+char *key,
+char *base,
+int num,
+int size,
+int (*cmp)());
+ Since I have come across a few platforms that do not have the
+ bsearch() function, OBJ_bsearch is my version of that function.
+ Feel free to use this function, but you may as well just use the
+ normal system bsearch(3) if it is present. This version also
+ has tolerance of being passed NULL pointers.
+
+==== keys ===========================================================
+
+EVP_PKEY_DSA
+EVP_PKEY_DSA2
+EVP_PKEY_DSA3
+EVP_PKEY_DSA4
+
+EVP_PKEY_RSA
+EVP_PKEY_RSA2
+
+valid DSA pkey types
+ NID_dsa
+ NID_dsaWithSHA
+ NID_dsaWithSHA1
+ NID_dsaWithSHA1_2
+
+valid RSA pkey types
+ NID_rsaEncryption
+ NID_rsa
+
+NID_dsaWithSHA NID_dsaWithSHA DSA SHA
+NID_dsa NID_dsaWithSHA1 DSA SHA1
+NID_md2 NID_md2WithRSAEncryption RSA-pkcs1 MD2
+NID_md5 NID_md5WithRSAEncryption RSA-pkcs1 MD5
+NID_mdc2 NID_mdc2WithRSA RSA-none MDC2
+NID_ripemd160 NID_ripemd160WithRSA RSA-pkcs1 RIPEMD160
+NID_sha NID_shaWithRSAEncryption RSA-pkcs1 SHA
+NID_sha1 NID_sha1WithRSAEncryption RSA-pkcs1 SHA1
+
+==== rand.doc ========================================================
+
+My Random number library.
+
+These routines can be used to generate pseudo random numbers and can be
+used to 'seed' the pseudo random number generator (RNG). The RNG make no
+effort to reproduce the same random number stream with each execution.
+Various other routines in the SSLeay library 'seed' the RNG when suitable
+'random' input data is available. Read the section at the end for details
+on the design of the RNG.
+
+void RAND_bytes(
+unsigned char *buf,
+int num);
+ This routine puts 'num' random bytes into 'buf'. One should make
+ sure RAND_seed() has been called before using this routine.
+
+void RAND_seed(
+unsigned char *buf,
+int num);
+ This routine adds more 'seed' data the RNG state. 'num' bytes
+ are added to the RNG state, they are taken from 'buf'. This
+ routine can be called with sensitive data such as user entered
+ passwords. This sensitive data is in no way recoverable from
+ the RAND library routines or state. Try to pass as much data
+ from 'random' sources as possible into the RNG via this function.
+ Also strongly consider using the RAND_load_file() and
+ RAND_write_file() routines.
+
+void RAND_cleanup();
+ When a program has finished with the RAND library, if it so
+ desires, it can 'zero' all RNG state.
+
+The following 3 routines are convenience routines that can be used to
+'save' and 'restore' data from/to the RNG and it's state.
+Since the more 'random' data that is feed as seed data the better, why not
+keep it around between executions of the program? Of course the
+application should pass more 'random' data in via RAND_seed() and
+make sure no-one can read the 'random' data file.
+
+char *RAND_file_name(
+char *buf,
+int size);
+ This routine returns a 'default' name for the location of a 'rand'
+ file. The 'rand' file should keep a sequence of random bytes used
+ to initialise the RNG. The filename is put in 'buf'. Buf is 'size'
+ bytes long. Buf is returned if things go well, if they do not,
+ NULL is returned. The 'rand' file name is generated in the
+ following way. First, if there is a 'RANDFILE' environment
+ variable, it is returned. Second, if there is a 'HOME' environment
+ variable, $HOME/.rand is returned. Third, NULL is returned. NULL
+ is also returned if a buf would overflow.
+
+int RAND_load_file(
+char *file,
+long number);
+ This function 'adds' the 'file' into the RNG state. It does this by
+ doing a RAND_seed() on the value returned from a stat() system call
+ on the file and if 'number' is non-zero, upto 'number' bytes read
+ from the file. The number of bytes passed to RAND_seed() is returned.
+
+int RAND_write_file(
+char *file),
+ RAND_write_file() writes N random bytes to the file 'file', where
+ N is the size of the internal RND state (currently 1k).
+ This is a suitable method of saving RNG state for reloading via
+ RAND_load_file().
+
+What follows is a description of this RNG and a description of the rational
+behind it's design.
+
+It should be noted that this RNG is intended to be used to generate
+'random' keys for various ciphers including generation of DH and RSA keys.
+
+It should also be noted that I have just created a system that I am happy with.
+It may be overkill but that does not worry me. I have not spent that much
+time on this algorithm so if there are glaring errors, please let me know.
+Speed has not been a consideration in the design of these routines.
+
+First up I will state the things I believe I need for a good RNG.
+1) A good hashing algorithm to mix things up and to convert the RNG 'state'
+ to random numbers.
+2) An initial source of random 'state'.
+3) The state should be very large. If the RNG is being used to generate
+ 4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum).
+ If your RNG state only has 128 bits, you are obviously limiting the
+ search space to 128 bits, not 2048. I'm probably getting a little
+ carried away on this last point but it does indicate that it may not be
+ a bad idea to keep quite a lot of RNG state. It should be easier to
+ break a cipher than guess the RNG seed data.
+4) Any RNG seed data should influence all subsequent random numbers
+ generated. This implies that any random seed data entered will have
+ an influence on all subsequent random numbers generated.
+5) When using data to seed the RNG state, the data used should not be
+ extractable from the RNG state. I believe this should be a
+ requirement because one possible source of 'secret' semi random
+ data would be a private key or a password. This data must
+ not be disclosed by either subsequent random numbers or a
+ 'core' dump left by a program crash.
+6) Given the same initial 'state', 2 systems should deviate in their RNG state
+ (and hence the random numbers generated) over time if at all possible.
+7) Given the random number output stream, it should not be possible to determine
+ the RNG state or the next random number.
+
+
+The algorithm is as follows.
+
+There is global state made up of a 1023 byte buffer (the 'state'), a
+working message digest ('md') and a counter ('count').
+
+Whenever seed data is added, it is inserted into the 'state' as
+follows.
+ The input is chopped up into units of 16 bytes (or less for
+ the last block). Each of these blocks is run through the MD5
+ message digest. The data passed to the MD5 digest is the
+ current 'md', the same number of bytes from the 'state'
+ (the location determined by in incremented looping index) as
+ the current 'block' and the new key data 'block'. The result
+ of this is kept in 'md' and also xored into the 'state' at the
+ same locations that were used as input into the MD5.
+ I believe this system addresses points 1 (MD5), 3 (the 'state'),
+ 4 (via the 'md'), 5 (by the use of MD5 and xor).
+
+When bytes are extracted from the RNG, the following process is used.
+For each group of 8 bytes (or less), we do the following,
+ Input into MD5, the top 8 bytes from 'md', the byte that are
+ to be overwritten by the random bytes and bytes from the
+ 'state' (incrementing looping index). From this digest output
+ (which is kept in 'md'), the top (upto) 8 bytes are
+ returned to the caller and the bottom (upto) 8 bytes are xored
+ into the 'state'.
+ Finally, after we have finished 'generation' random bytes for the
+ called, 'count' (which is incremented) and 'md' are fed into MD5 and
+ the results are kept in 'md'.
+ I believe the above addressed points 1 (use of MD5), 6 (by
+ hashing into the 'state' the 'old' data from the caller that
+ is about to be overwritten) and 7 (by not using the 8 bytes
+ given to the caller to update the 'state', but they are used
+ to update 'md').
+
+So of the points raised, only 2 is not addressed, but sources of
+random data will always be a problem.
+
+
+==== rc2.doc ========================================================
+
+The RC2 library.
+
+RC2 is a block cipher that operates on 64bit (8 byte) quantities. It
+uses variable size key, but 128bit (16 byte) key would normally be considered
+good. It can be used in all the modes that DES can be used. This
+library implements the ecb, cbc, cfb64, ofb64 modes.
+
+I have implemented this library from an article posted to sci.crypt on
+11-Feb-1996. I personally don't know how far to trust the RC2 cipher.
+While it is capable of having a key of any size, not much reseach has
+publically been done on it at this point in time (Apr-1996)
+since the cipher has only been public for a few months :-)
+It is of a similar speed to DES and IDEA, so unless it is required for
+meeting some standard (SSLv2, perhaps S/MIME), it would probably be advisable
+to stick to IDEA, or for the paranoid, Tripple DES.
+
+Mind you, having said all that, I should mention that I just read alot and
+implement ciphers, I'm a 'babe in the woods' when it comes to evaluating
+ciphers :-).
+
+For all calls that have an 'input' and 'output' variables, they can be the
+same.
+
+This library requires the inclusion of 'rc2.h'.
+
+All of the encryption functions take what is called an RC2_KEY as an
+argument. An RC2_KEY is an expanded form of the RC2 key.
+For all modes of the RC2 algorithm, the RC2_KEY used for
+decryption is the same one that was used for encryption.
+
+The define RC2_ENCRYPT is passed to specify encryption for the functions
+that require an encryption/decryption flag. RC2_DECRYPT is passed to
+specify decryption.
+
+Please note that any of the encryption modes specified in my DES library
+could be used with RC2. I have only implemented ecb, cbc, cfb64 and
+ofb64 for the following reasons.
+- ecb is the basic RC2 encryption.
+- cbc is the normal 'chaining' form for block ciphers.
+- cfb64 can be used to encrypt single characters, therefore input and output
+ do not need to be a multiple of 8.
+- ofb64 is similar to cfb64 but is more like a stream cipher, not as
+ secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
+- If you want triple RC2, thats 384 bits of key and you must be totally
+ obsessed with security. Still, if you want it, it is simple enough to
+ copy the function from the DES library and change the des_encrypt to
+ RC2_encrypt; an exercise left for the paranoid reader :-).
+
+The functions are as follows:
+
+void RC2_set_key(
+RC2_KEY *ks;
+int len;
+unsigned char *key;
+int bits;
+ RC2_set_key converts an 'len' byte key into a RC2_KEY.
+ A 'ks' is an expanded form of the 'key' which is used to
+ perform actual encryption. It can be regenerated from the RC2 key
+ so it only needs to be kept when encryption or decryption is about
+ to occur. Don't save or pass around RC2_KEY's since they
+ are CPU architecture dependent, 'key's are not. RC2 is an
+ interesting cipher in that it can be used with a variable length
+ key. 'len' is the length of 'key' to be used as the key.
+ A 'len' of 16 is recomended. The 'bits' argument is an
+ interesting addition which I only found out about in Aug 96.
+ BSAFE uses this parameter to 'limit' the number of bits used
+ for the key. To use the 'key' unmodified, set bits to 1024.
+ This is what old versions of my RC2 library did (SSLeay 0.6.3).
+ RSAs BSAFE library sets this parameter to be 128 if 128 bit
+ keys are being used. So to be compatable with BSAFE, set it
+ to 128, if you don't want to reduce RC2's key length, leave it
+ at 1024.
+
+void RC2_encrypt(
+unsigned long *data,
+RC2_KEY *key,
+int encrypt);
+ This is the RC2 encryption function that gets called by just about
+ every other RC2 routine in the library. You should not use this
+ function except to implement 'modes' of RC2. I say this because the
+ functions that call this routine do the conversion from 'char *' to
+ long, and this needs to be done to make sure 'non-aligned' memory
+ access do not occur.
+ Data is a pointer to 2 unsigned long's and key is the
+ RC2_KEY to use. Encryption or decryption is indicated by 'encrypt'.
+ which can have the values RC2_ENCRYPT or RC2_DECRYPT.
+
+void RC2_ecb_encrypt(
+unsigned char *in,
+unsigned char *out,
+RC2_KEY *key,
+int encrypt);
+ This is the basic Electronic Code Book form of RC2 (in DES this
+ mode is called Electronic Code Book so I'm going to use the term
+ for rc2 as well.
+ Input is encrypted into output using the key represented by
+ key. Depending on the encrypt, encryption or
+ decryption occurs. Input is 8 bytes long and output is 8 bytes.
+
+void RC2_cbc_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+RC2_KEY *ks,
+unsigned char *ivec,
+int encrypt);
+ This routine implements RC2 in Cipher Block Chaining mode.
+ Input, which should be a multiple of 8 bytes is encrypted
+ (or decrypted) to output which will also be a multiple of 8 bytes.
+ The number of bytes is in length (and from what I've said above,
+ should be a multiple of 8). If length is not a multiple of 8, bad
+ things will probably happen. ivec is the initialisation vector.
+ This function updates iv after each call so that it can be passed to
+ the next call to RC2_cbc_encrypt().
+
+void RC2_cfb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+RC2_KEY *schedule,
+unsigned char *ivec,
+int *num,
+int encrypt);
+ This is one of the more useful functions in this RC2 library, it
+ implements CFB mode of RC2 with 64bit feedback.
+ This allows you to encrypt an arbitrary number of bytes,
+ you do not require 8 byte padding. Each call to this
+ routine will encrypt the input bytes to output and then update ivec
+ and num. Num contains 'how far' we are though ivec.
+ 'Encrypt' is used to indicate encryption or decryption.
+ CFB64 mode operates by using the cipher to generate a stream
+ of bytes which is used to encrypt the plain text.
+ The cipher text is then encrypted to generate the next 64 bits to
+ be xored (incrementally) with the next 64 bits of plain
+ text. As can be seen from this, to encrypt or decrypt,
+ the same 'cipher stream' needs to be generated but the way the next
+ block of data is gathered for encryption is different for
+ encryption and decryption.
+
+void RC2_ofb64_encrypt(
+unsigned char *in,
+unsigned char *out,
+long length,
+RC2_KEY *schedule,
+unsigned char *ivec,
+int *num);
+ This functions implements OFB mode of RC2 with 64bit feedback.
+ This allows you to encrypt an arbitrary number of bytes,
+ you do not require 8 byte padding. Each call to this
+ routine will encrypt the input bytes to output and then update ivec
+ and num. Num contains 'how far' we are though ivec.
+ This is in effect a stream cipher, there is no encryption or
+ decryption mode.
+
+For reading passwords, I suggest using des_read_pw_string() from my DES library.
+To generate a password from a text string, I suggest using MD5 (or MD2) to
+produce a 16 byte message digest that can then be passed directly to
+RC2_set_key().
+
+=====
+For more information about the specific RC2 modes in this library
+(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
+documentation on my DES library. What is said about DES is directly
+applicable for RC2.
+
+
+==== rc4.doc ========================================================
+
+The RC4 library.
+RC4 is a stream cipher that operates on a byte stream. It can be used with
+any length key but I would recommend normally using 16 bytes.
+
+This library requires the inclusion of 'rc4.h'.
+
+The RC4 encryption function takes what is called an RC4_KEY as an argument.
+The RC4_KEY is generated by the RC4_set_key function from the key bytes.
+
+RC4, being a stream cipher, does not have an encryption or decryption mode.
+It produces a stream of bytes that the input stream is xor'ed against and
+so decryption is just a case of 'encrypting' again with the same key.
+
+I have only put in one 'mode' for RC4 which is the normal one. This means
+there is no initialisation vector and there is no feedback of the cipher
+text into the cipher. This implies that you should not ever use the
+same key twice if you can help it. If you do, you leave yourself open to
+known plain text attacks; if you know the plain text and
+corresponding cipher text in one message, all messages that used the same
+key can have the cipher text decoded for the corresponding positions in the
+cipher stream.
+
+The main positive feature of RC4 is that it is a very fast cipher; about 4
+times faster that DES. This makes it ideally suited to protocols where the
+key is randomly chosen, like SSL.
+
+The functions are as follows:
+
+void RC4_set_key(
+RC4_KEY *key;
+int len;
+unsigned char *data);
+ This function initialises the RC4_KEY structure with the key passed
+ in 'data', which is 'len' bytes long. The key data can be any
+ length but 16 bytes seems to be a good number.
+
+void RC4(
+RC4_KEY *key;
+unsigned long len;
+unsigned char *in;
+unsigned char *out);
+ Do the actual RC4 encryption/decryption. Using the 'key', 'len'
+ bytes are transformed from 'in' to 'out'. As mentioned above,
+ decryption is the operation as encryption.
+
+==== ref.doc ========================================================
+
+I have lots more references etc, and will update this list in the future,
+30 Aug 1996 - eay
+
+
+SSL The SSL Protocol - from Netscapes.
+
+RC4 Newsgroups: sci.crypt
+ From: sterndark@netcom.com (David Sterndark)
+ Subject: RC4 Algorithm revealed.
+ Message-ID: <sternCvKL4B.Hyy@netcom.com>
+
+RC2 Newsgroups: sci.crypt
+ From: pgut01@cs.auckland.ac.nz (Peter Gutmann)
+ Subject: Specification for Ron Rivests Cipher No.2
+ Message-ID: <4fk39f$f70@net.auckland.ac.nz>
+
+MD2 RFC1319 The MD2 Message-Digest Algorithm
+MD5 RFC1321 The MD5 Message-Digest Algorithm
+
+X509 Certificates
+ RFC1421 Privacy Enhancement for Internet Electronic Mail: Part I
+ RFC1422 Privacy Enhancement for Internet Electronic Mail: Part II
+ RFC1423 Privacy Enhancement for Internet Electronic Mail: Part III
+ RFC1424 Privacy Enhancement for Internet Electronic Mail: Part IV
+
+RSA and various standard encoding
+ PKCS#1 RSA Encryption Standard
+ PKCS#5 Password-Based Encryption Standard
+ PKCS#7 Cryptographic Message Syntax Standard
+ A Layman's Guide to a Subset of ASN.1, BER, and DER
+ An Overview of the PKCS Standards
+ Some Examples of the PKCS Standards
+
+IDEA Chapter 3 The Block Cipher IDEA
+
+RSA, prime number generation and bignum algorithms
+ Introduction To Algorithms,
+ Thomas Cormen, Charles Leiserson, Ronald Rivest,
+ Section 29 Arithmetic Circuits
+ Section 33 Number-Theoretic Algorithms
+
+Fast Private Key algorithm
+ Fast Decipherment Algorithm for RSA Public-Key Cryptosystem
+ J.-J. Quisquater and C. Couvreur, Electronics Letters,
+ 14th October 1982, Vol. 18 No. 21
+
+Prime number generation and bignum algorithms.
+ PGP-2.3a
+
+==== rsa.doc ========================================================
+
+The RSA encryption and utility routines.
+
+The RSA routines are built on top of a big number library (the BN library).
+There are support routines in the X509 library for loading and manipulating
+the various objects in the RSA library. When errors are returned, read
+about the ERR library for how to access the error codes.
+
+All RSA encryption is done according to the PKCS-1 standard which is
+compatible with PEM and RSAref. This means that any values being encrypted
+must be less than the size of the modulus in bytes, minus 10, bytes long.
+
+This library uses RAND_bytes()() for it's random data, make sure to feed
+RAND_seed() with lots of interesting and varied data before using these
+routines.
+
+The RSA library has one specific data type, the RSA structure.
+It is composed of 8 BIGNUM variables (see the BN library for details) and
+can hold either a private RSA key or a public RSA key.
+Some RSA libraries have different structures for public and private keys, I
+don't. For my libraries, a public key is determined by the fact that the
+RSA->d value is NULL. These routines will operate on any size RSA keys.
+While I'm sure 4096 bit keys are very very secure, they take a lot longer
+to process that 1024 bit keys :-).
+
+The function in the RSA library are as follows.
+
+RSA *RSA_new();
+ This function creates a new RSA object. The sub-fields of the RSA
+ type are also malloced so you should always use this routine to
+ create RSA variables.
+
+void RSA_free(
+RSA *rsa);
+ This function 'frees' an RSA structure. This routine should always
+ be used to free the RSA structure since it will also 'free' any
+ sub-fields of the RSA type that need freeing.
+
+int RSA_size(
+RSA *rsa);
+ This function returns the size of the RSA modulus in bytes. Why do
+ I need this you may ask, well the reason is that when you encrypt
+ with RSA, the output string will be the size of the RSA modulus.
+ So the output for the RSA_encrypt and the input for the RSA_decrypt
+ routines need to be RSA_size() bytes long, because this is how many
+ bytes are expected.
+
+For the following 4 RSA encryption routines, it should be noted that
+RSA_private_decrypt() should be used on the output from
+RSA_public_encrypt() and RSA_public_decrypt() should be used on
+the output from RSA_private_encrypt().
+
+int RSA_public_encrypt(
+int from_len;
+unsigned char *from
+unsigned char *to
+RSA *rsa);
+ This function implements RSA public encryption, the rsa variable
+ should be a public key (but can be a private key). 'from_len'
+ bytes taken from 'from' and encrypted and put into 'to'. 'to' needs
+ to be at least RSA_size(rsa) bytes long. The number of bytes
+ written into 'to' is returned. -1 is returned on an error. The
+ operation performed is
+ to = from^rsa->e mod rsa->n.
+
+int RSA_private_encrypt(
+int from_len;
+unsigned char *from
+unsigned char *to
+RSA *rsa);
+ This function implements RSA private encryption, the rsa variable
+ should be a private key. 'from_len' bytes taken from
+ 'from' and encrypted and put into 'to'. 'to' needs
+ to be at least RSA_size(rsa) bytes long. The number of bytes
+ written into 'to' is returned. -1 is returned on an error. The
+ operation performed is
+ to = from^rsa->d mod rsa->n.
+
+int RSA_public_decrypt(
+int from_len;
+unsigned char *from
+unsigned char *to
+RSA *rsa);
+ This function implements RSA public decryption, the rsa variable
+ should be a public key (but can be a private key). 'from_len'
+ bytes are taken from 'from' and decrypted. The decrypted data is
+ put into 'to'. The number of bytes encrypted is returned. -1 is
+ returned to indicate an error. The operation performed is
+ to = from^rsa->e mod rsa->n.
+
+int RSA_private_decrypt(
+int from_len;
+unsigned char *from
+unsigned char *to
+RSA *rsa);
+ This function implements RSA private decryption, the rsa variable
+ should be a private key. 'from_len' bytes are taken
+ from 'from' and decrypted. The decrypted data is
+ put into 'to'. The number of bytes encrypted is returned. -1 is
+ returned to indicate an error. The operation performed is
+ to = from^rsa->d mod rsa->n.
+
+int RSA_mod_exp(
+BIGNUM *n;
+BIGNUM *p;
+RSA *rsa);
+ Normally you will never use this routine.
+ This is really an internal function which is called by
+ RSA_private_encrypt() and RSA_private_decrypt(). It performs
+ n=n^p mod rsa->n except that it uses the 5 extra variables in the
+ RSA structure to make this more efficient.
+
+RSA *RSA_generate_key(
+int bits;
+unsigned long e;
+void (*callback)();
+char *cb_arg;
+ This routine is used to generate RSA private keys. It takes
+ quite a period of time to run and should only be used to
+ generate initial private keys that should then be stored
+ for later use. The passed callback function
+ will be called periodically so that feedback can be given
+ as to how this function is progressing.
+ 'bits' is the length desired for the modulus, so it would be 1024
+ to generate a 1024 bit private key.
+ 'e' is the value to use for the public exponent 'e'. Traditionally
+ it is set to either 3 or 0x10001.
+ The callback function (if not NULL) is called in the following
+ situations.
+ when we have generated a suspected prime number to test,
+ callback(0,num1++,cb_arg). When it passes a prime number test,
+ callback(1,num2++,cb_arg). When it is rejected as one of
+ the 2 primes required due to gcd(prime,e value) != 0,
+ callback(2,num3++,cb_arg). When finally accepted as one
+ of the 2 primes, callback(3,num4++,cb_arg).
+
+
+==== rsaref.doc ========================================================
+
+This package can be compiled to use the RSAref library.
+This library is not allowed outside of the USA but inside the USA it is
+claimed by RSA to be the only RSA public key library that can be used
+besides BSAFE..
+
+There are 2 files, rsaref/rsaref.c and rsaref/rsaref.h that contain the glue
+code to use RSAref. These files were written by looking at the PGP
+source code and seeing which routines it used to access RSAref.
+I have also been sent by some-one a copy of the RSAref header file that
+contains the library error codes.
+
+[ Jun 1996 update - I have recently gotten hold of RSAref 2.0 from
+ South Africa and have been doing some performace tests. ]
+
+They have now been tested against the recently announced RSAEURO
+library.
+
+There are 2 ways to use SSLeay and RSAref. First, to build so that
+the programs must be linked with RSAref, add '-DRSAref' to CFLAG in the top
+level makefile and -lrsaref (or where ever you are keeping RSAref) to
+EX_LIBS.
+
+To build a makefile via util/mk1mf.pl to do this, use the 'rsaref' option.
+
+The second method is to build as per normal and link applications with
+the RSAglue library. The correct library order would be
+cc -o cmd cmd.o -lssl -lRSAglue -lcrypto -lrsaref -ldes
+The RSAglue library is built in the rsa directory and is NOT
+automatically installed.
+
+Be warned that the RSAEURO library, that is claimed to be compatible
+with RSAref contains a different value for the maximum number of bits
+supported. This changes structure sizes and so if you are using
+RSAEURO, change the value of RSAref_MAX_BITS in rsa/rsaref.h
+
+
+==== s_mult.doc ========================================================
+
+s_mult is a test program I hacked up on a Sunday for testing non-blocking
+IO. It has a select loop at it's centre that handles multiple readers
+and writers.
+
+Try the following command
+ssleay s_mult -echo -nbio -ssl -v
+echo - sends any sent text back to the sender
+nbio - turns on non-blocking IO
+ssl - accept SSL connections, default is normal text
+v - print lots
+ type Q<cr> to quit
+
+In another window, run the following
+ssleay s_client -pause </etc/termcap
+
+The pause option puts in a 1 second pause in each read(2)/write(2) call
+so the other end will have read()s fail.
+
+==== session.doc ========================================================
+
+I have just checked over and re-worked the session stuff.
+The following brief example will ignore all setup information to do with
+authentication.
+
+Things operate as follows.
+
+The SSL environment has a 'context', a SSL_CTX structure. This holds the
+cached SSL_SESSIONS (which can be reused) and the certificate lookup
+information. Each SSL structure needs to be associated with a SSL_CTX.
+Normally only one SSL_CTX structure is needed per program.
+
+SSL_CTX *SSL_CTX_new(void );
+void SSL_CTX_free(SSL_CTX *);
+These 2 functions create and destroy SSL_CTX structures
+
+The SSL_CTX has a session_cache_mode which is by default,
+in SSL_SESS_CACHE_SERVER mode. What this means is that the library
+will automatically add new session-id's to the cache apon sucsessful
+SSL_accept() calls.
+If SSL_SESS_CACHE_CLIENT is set, then client certificates are also added
+to the cache.
+SSL_set_session_cache_mode(ctx,mode) will set the 'mode' and
+SSL_get_session_cache_mode(ctx) will get the cache 'mode'.
+The modes can be
+SSL_SESS_CACHE_OFF - no caching
+SSL_SESS_CACHE_CLIENT - only SSL_connect()
+SSL_SESS_CACHE_SERVER - only SSL_accept()
+SSL_SESS_NO_CACHE_BOTH - Either SSL_accept() or SSL_connect().
+If SSL_SESS_CACHE_NO_AUTO_CLEAR is set, old timed out sessions are
+not automatically removed each 255, SSL_connect()s or SSL_accept()s.
+
+By default, apon every 255 successful SSL_connect() or SSL_accept()s,
+the cache is flush. Please note that this could be expensive on
+a heavily loaded SSL server, in which case, turn this off and
+clear the cache of old entries 'manually' (with one of the functions
+listed below) every few hours. Perhaps I should up this number, it is hard
+to say. Remember, the '255' new calls is just a mechanims to get called
+every now and then, in theory at most 255 new session-id's will have been
+added but if 100 are added every minute, you would still have
+500 in the cache before any would start being flushed (assuming a 3 minute
+timeout)..
+
+int SSL_CTX_sess_hits(SSL_CTX *ctx);
+int SSL_CTX_sess_misses(SSL_CTX *ctx);
+int SSL_CTX_sess_timeouts(SSL_CTX *ctx);
+These 3 functions return statistics about the SSL_CTX. These 3 are the
+number of session id reuses. hits is the number of reuses, misses are the
+number of lookups that failed, and timeouts is the number of cached
+entries ignored because they had timeouted.
+
+ctx->new_session_cb is a function pointer to a function of type
+int new_session_callback(SSL *ssl,SSL_SESSION *new);
+This function, if set in the SSL_CTX structure is called whenever a new
+SSL_SESSION is added to the cache. If the callback returns non-zero, it
+means that the application will have to do a SSL_SESSION_free()
+on the structure (this is
+to do with the cache keeping the reference counts correct, without the
+application needing to know about it.
+The 'active' parameter is the current SSL session for which this connection
+was created.
+
+void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,int (*cb)());
+to set the callback,
+int (*cb)() SSL_CTX_sess_get_new_cb(SSL_CTX *ctx)
+to get the callback.
+
+If the 'get session' callback is set, when a session id is looked up and
+it is not in the session-id cache, this callback is called. The callback is
+of the form
+SSL_SESSION *get_session_callback(unsigned char *sess_id,int sess_id_len,
+ int *copy);
+
+The get_session_callback is intended to return null if no session id is found.
+The reference count on the SSL_SESSION in incremented by the SSL library,
+if copy is 1. Otherwise, the reference count is not modified.
+
+void SSL_CTX_sess_set_get_cb(ctx,cb) sets the callback and
+int (*cb)()SSL_CTX_sess_get_get_cb(ctx) returns the callback.
+
+These callbacks are basically indended to be used by processes to
+send their session-id's to other processes. I currently have not implemented
+non-blocking semantics for these callbacks, it is upto the appication
+to make the callbacks effiecent if they require blocking (perhaps
+by 'saving' them and then 'posting them' when control returns from
+the SSL_accept().
+
+LHASH *SSL_CTX_sessions(SSL_CTX *ctx)
+This returns the session cache. The lhash strucutre can be accessed for
+statistics about the cache.
+
+void lh_stats(LHASH *lh, FILE *out);
+void lh_node_stats(LHASH *lh, FILE *out);
+void lh_node_usage_stats(LHASH *lh, FILE *out);
+
+can be used to print details about it's activity and current state.
+You can also delve directly into the lhash structure for 14 different
+counters that are kept against the structure. When I wrote the lhash library,
+I was interested in gathering statistics :-).
+Have a read of doc/lhash.doc in the SSLeay distribution area for more details
+on the lhash library.
+
+Now as mentioned ealier, when a SSL is created, it needs a SSL_CTX.
+SSL * SSL_new(SSL_CTX *);
+
+This stores a session. A session is secret information shared between 2
+SSL contexts. It will only be created if both ends of the connection have
+authenticated their peer to their satisfaction. It basically contains
+the information required to use a particular secret key cipher.
+
+To retrieve the SSL_CTX being used by a SSL,
+SSL_CTX *SSL_get_SSL_CTX(SSL *s);
+
+Now when a SSL session is established between to programs, the 'session'
+information that is cached in the SSL_CTX can me manipulated by the
+following functions.
+int SSL_set_session(SSL *s, SSL_SESSION *session);
+This will set the SSL_SESSION to use for the next SSL_connect(). If you use
+this function on an already 'open' established SSL connection, 'bad things
+will happen'. This function is meaning-less when used on a ssl strucutre
+that is just about to be used in a SSL_accept() call since the
+SSL_accept() will either create a new session or retrieve one from the
+cache.
+
+SSL_SESSION *SSL_get_session(SSL *s);
+This will return the SSL_SESSION for the current SSL, NULL if there is
+no session associated with the SSL structure.
+
+The SSL sessions are kept in the SSL_CTX in a hash table, to remove a
+session
+void SSL_CTX_remove_session(SSL_CTX *,SSL_SESSION *c);
+and to add one
+int SSL_CTX_add_session(SSL_CTX *s, SSL_SESSION *c);
+SSL_CTX_add_session() returns 1 if the session was already in the cache (so it
+was not added).
+Whenever a new session is created via SSL_connect()/SSL_accept(),
+they are automatically added to the cache, depending on the session_cache_mode
+settings. SSL_set_session()
+does not add it to the cache. Just call SSL_CTX_add_session() if you do want the
+session added. For a 'client' this would not normally be the case.
+SSL_CTX_add_session() is not normally ever used, except for doing 'evil' things
+which the next 2 funtions help you do.
+
+int i2d_SSL_SESSION(SSL_SESSION *in,unsigned char **pp);
+SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a,unsigned char **pp,long length);
+These 2 functions are in the standard ASN1 library form and can be used to
+load and save to a byte format, the SSL_SESSION structure.
+With these functions, you can save and read these structures to a files or
+arbitary byte string.
+The PEM_write_SSL_SESSION(fp,x) and PEM_read_SSL_SESSION(fp,x,cb) will
+write to a file pointer in base64 encoding.
+
+What you can do with this, is pass session information between separate
+processes. Please note, that you will probably also need to modify the
+timeout information on the SSL_SESSIONs.
+
+long SSL_get_time(SSL_SESSION *s)
+will return the 'time' that the session
+was loaded. The timeout is relative to this time. This information is
+saved when the SSL_SESSION is converted to binarary but it is stored
+in as a unix long, which is rather OS dependant, but easy to convert back.
+
+long SSL_set_time(SSL_SESSION *s,long t) will set the above mentioned time.
+The time value is just the value returned from time(3), and should really
+be defined by be to be time_t.
+
+long SSL_get_timeout(SSL_SESSION *s);
+long SSL_set_timeout(SSL_SESSION *s,long t);
+These 2 retrieve and set the timeout which is just a number of secconds
+from the 'SSL_get_time()' value. When this time period has elapesed,
+the session will no longer be in the cache (well it will actually be removed
+the next time it is attempted to be retrieved, so you could 'bump'
+the timeout so it remains valid).
+The 'time' and 'timeout' are set on a session when it is created, not reset
+each time it is reused. If you did wish to 'bump it', just after establishing
+a connection, do a
+SSL_set_time(ssl,time(NULL));
+
+You can also use
+SSL_CTX_set_timeout(SSL_CTX *ctx,unsigned long t) and
+SSL_CTX_get_timeout(SSL_CTX *ctx) to manipulate the default timeouts for
+all SSL connections created against a SSL_CTX. If you set a timeout in
+an SSL_CTX, all new SSL's created will inherit the timeout. It can be over
+written by the SSL_set_timeout(SSL *s,unsigned long t) function call.
+If you 'set' the timeout back to 0, the system default will be used.
+
+SSL_SESSION *SSL_SESSION_new();
+void SSL_SESSION_free(SSL_SESSION *ses);
+These 2 functions are used to create and dispose of SSL_SESSION functions.
+You should not ever normally need to use them unless you are using
+i2d_SSL_SESSION() and/or d2i_SSL_SESSION(). If you 'load' a SSL_SESSION
+via d2i_SSL_SESSION(), you will need to SSL_SESSION_free() it.
+Both SSL_set_session() and SSL_CTX_add_session() will 'take copies' of the
+structure (via reference counts) when it is passed to them.
+
+SSL_CTX_flush_sessions(ctx,time);
+The first function will clear all sessions from the cache, which have expired
+relative to 'time' (which could just be time(NULL)).
+
+SSL_CTX_flush_sessions(ctx,0);
+This is a special case that clears everything.
+
+As a final comment, a 'session' is not enough to establish a new
+connection. If a session has timed out, a certificate and private key
+need to have been associated with the SSL structure.
+SSL_copy_session_id(SSL *to,SSL *from); will copy not only the session
+strucutre but also the private key and certificate associated with
+'from'.
+
+EXAMPLES.
+
+So lets play at being a weird SSL server.
+
+/* setup a context */
+ctx=SSL_CTX_new();
+
+/* Lets load some session from binary into the cache, why one would do
+ * this is not toally clear, but passing between programs does make sense
+ * Perhaps you are using 4096 bit keys and are happy to keep them
+ * valid for a week, to avoid the RSA overhead of 15 seconds, I'm not toally
+ * sure, perhaps this is a process called from an SSL inetd and this is being
+ * passed to the application. */
+session=d2i_SSL_SESSION(....)
+SSL_CTX_add_session(ctx,session);
+
+/* Lets even add a session from a file */
+session=PEM_read_SSL_SESSION(....)
+SSL_CTX_add_session(ctx,session);
+
+/* create a new SSL structure */
+ssl=SSL_new(ctx);
+
+/* At this point we want to be able to 'create' new session if
+ * required, so we need a certificate and RSAkey. */
+SSL_use_RSAPrivateKey_file(ssl,...)
+SSL_use_certificate_file(ssl,...)
+
+/* Now since we are a server, it make little sence to load a session against
+ * the ssl strucutre since a SSL_accept() will either create a new session or
+ * grab an existing one from the cache. */
+
+/* grab a socket descriptor */
+fd=accept(...);
+
+/* associated it with the ssl strucutre */
+SSL_set_fd(ssl,fd);
+
+SSL_accept(ssl); /* 'do' SSL using out cert and RSA key */
+
+/* Lets print out the session details or lets save it to a file,
+ * perhaps with a secret key cipher, so that we can pass it to the FBI
+ * when they want to decode the session :-). While we have RSA
+ * this does not matter much but when I do SSLv3, this will allow a mechanism
+ * for the server/client to record the information needed to decode
+ * the traffic that went over the wire, even when using Diffie-Hellman */
+PEM_write_SSL_SESSION(SSL_get_session(ssl),stdout,....)
+
+Lets 'connect' back to the caller using the same session id.
+
+ssl2=SSL_new(ctx);
+fd2=connect(them);
+SSL_set_fd(ssl2,fd2);
+SSL_set_session(ssl2,SSL_get_session(ssl));
+SSL_connect(ssl2);
+
+/* what the hell, lets accept no more connections using this session */
+SSL_CTX_remove_session(SSL_get_SSL_CTX(ssl),SSL_get_session(ssl));
+
+/* we could have just as easily used ssl2 since they both are using the
+ * same session.
+ * You will note that both ssl and ssl2 are still using the session, and
+ * the SSL_SESSION structure will be free()ed when both ssl and ssl2
+ * finish using the session. Also note that you could continue to initiate
+ * connections using this session by doing SSL_get_session(ssl) to get the
+ * existing session, but SSL_accept() will not be able to find it to
+ * use for incoming connections.
+ * Of corse, the session will timeout at the far end and it will no
+ * longer be accepted after a while. The time and timeout are ignored except
+ * by SSL_accept(). */
+
+/* Since we have had our server running for 10 weeks, and memory is getting
+ * short, perhaps we should clear the session cache to remove those
+ * 100000 session entries that have expired. Some may consider this
+ * a memory leak :-) */
+
+SSL_CTX_flush_sessions(ctx,time(NULL));
+
+/* Ok, after a bit more time we wish to flush all sessions from the cache
+ * so that all new connections will be authenticated and incure the
+ * public key operation overhead */
+
+SSL_CTX_flush_sessions(ctx,0);
+
+/* As a final note, to copy everything to do with a SSL, use */
+SSL_copy_session_id(SSL *to,SSL *from);
+/* as this also copies the certificate and RSA key so new session can
+ * be established using the same details */
+
+
+==== sha.doc ========================================================
+
+The SHA (Secure Hash Algorithm) library.
+SHA is a message digest algorithm that can be used to condense an arbitrary
+length message down to a 20 byte hash. The functions all need to be passed
+a SHA_CTX which is used to hold the SHA context during multiple SHA_Update()
+function calls. The normal method of use for this library is as follows
+This library contains both SHA and SHA-1 digest algorithms. SHA-1 is
+an update to SHA (which should really be called SHA-0 now) which
+tweaks the algorithm slightly. The SHA-1 algorithm is used by simply
+using SHA1_Init(), SHA1_Update(), SHA1_Final() and SHA1() instead of the
+SHA*() calls
+
+SHA_Init(...);
+SHA_Update(...);
+...
+SHA_Update(...);
+SHA_Final(...);
+
+This library requires the inclusion of 'sha.h'.
+
+The functions are as follows:
+
+void SHA_Init(
+SHA_CTX *c);
+ This function needs to be called to initiate a SHA_CTX structure for
+ use.
+
+void SHA_Update(
+SHA_CTX *c;
+unsigned char *data;
+unsigned long len);
+ This updates the message digest context being generated with 'len'
+ bytes from the 'data' pointer. The number of bytes can be any
+ length.
+
+void SHA_Final(
+unsigned char *md;
+SHA_CTX *c;
+ This function is called when a message digest of the data digested
+ with SHA_Update() is wanted. The message digest is put in the 'md'
+ array and is SHA_DIGEST_LENGTH (20) bytes long.
+
+unsigned char *SHA(
+unsigned char *d;
+unsigned long n;
+unsigned char *md;
+ This function performs a SHA_Init(), followed by a SHA_Update()
+ followed by a SHA_Final() (using a local SHA_CTX).
+ The resulting digest is put into 'md' if it is not NULL.
+ Regardless of the value of 'md', the message
+ digest is returned from the function. If 'md' was NULL, the message
+ digest returned is being stored in a static structure.
+
+
+==== speed.doc ========================================================
+
+To get an idea of the performance of this library, use
+ssleay speed
+
+perl util/sp-diff.pl file1 file2
+
+will print out the relative differences between the 2 files which are
+expected to be the output from the speed program.
+
+The performace of the library is very dependant on the Compiler
+quality and various flags used to build.
+
+---
+
+These are some numbers I did comparing RSAref and SSLeay on a Pentium 100.
+[ These numbers are all out of date, as of SSL - 0.6.1 the RSA
+operations are about 2 times faster, so check the version number ]
+
+RSA performance.
+
+SSLeay 0.6.0
+Pentium 100, 32meg, Windows NT Workstation 3.51
+linux - gcc v 2.7.0 -O3 -fomit-frame-pointer -m486
+and
+Windows NT - Windows NT 3.51 - Visual C++ 4.1 - 586 code + 32bit assember
+Windows 3.1 - Windows NT 3.51 - Visual C++ 1.52c - 286 code + 32bit assember
+NT Dos Shell- Windows NT 3.51 - Visual C++ 1.52c - 286 code + 16bit assember
+
+Times are how long it takes to do an RSA private key operation.
+
+ 512bits 1024bits
+-------------------------------
+SSLeay NT dll 0.042s 0.202s see above
+SSLeay linux 0.046s 0.218s Assember inner loops (normal build)
+SSLeay linux 0.067s 0.380s Pure C code with BN_LLONG defined
+SSLeay W3.1 dll 0.108s 0.478s see above
+SSLeay linux 0.109s 0.713s C without BN_LLONG.
+RSAref2.0 linux 0.149s 0.936s
+SSLeay MS-DOS 0.197s 1.049s see above
+
+486DX66, 32meg, Windows NT Server 3.51
+ 512bits 1024bits
+-------------------------------
+SSLeay NT dll 0.084s 0.495s <- SSLeay 0.6.3
+SSLeay NT dll 0.154s 0.882s
+SSLeay W3.1 dll 0.335s 1.538s
+SSLeay MS-DOS 0.490s 2.790s
+
+What I find cute is that I'm still faster than RSAref when using standard C,
+without using the 'long long' data type :-), %35 faster for 512bit and we
+scale up to 3.2 times faster for the 'default linux' build. I should mention
+that people should 'try' to use either x86-lnx.s (elf), x86-lnxa.s or
+x86-sol.s for any x86 based unix they are building on. The only problems
+with be with syntax but the performance gain is quite large, especially for
+servers. The code is very simple, you just need to modify the 'header'.
+
+The message is, if you are stuck using RSAref, the RSA performance will be
+bad. Considering the code was compiled for a pentium, the 486DX66 number
+would indicate 'Use RSAref and turn you Pentium 100 into a 486DX66' :-).
+[ As of verson 0.6.1, it would be correct to say 'turn you pentium 100
+ into a 486DX33' :-) ]
+
+I won't tell people if the DLL's are using RSAref or my stuff if no-one
+asks :-).
+
+eric
+
+PS while I know I could speed things up further, I will probably not do
+ so due to the effort involved. I did do some timings on the
+ SSLeay bignum format -> RSAref number format conversion that occurs
+ each time RSAref is used by SSLeay, and the numbers are trivial.
+ 0.00012s a call for 512bit vs 0.149s for the time spent in the function.
+ 0.00018s for 1024bit vs 0.938s. Insignificant.
+ So the 'way to go', to support faster RSA libraries, if people are keen,
+ is to write 'glue' code in a similar way that I do for RSAref and send it
+ to me :-).
+ My base library still has the advantage of being able to operate on
+ any size numbers, and is not that far from the performance from the
+ leaders in the field. (-%30?)
+ [ Well as of 0.6.1 I am now the leader in the filed on x86 (we at
+ least very close :-) ]
+
+ I suppose I should also mention some other numbers RSAref numbers, again
+ on my Pentium.
+ DES CBC EDE-DES MD5
+ RSAref linux 830k/s 302k/s 4390k/s
+ SSLeay linux 855k/s 319k/s 10025k/s
+ SSLeay NT 1158k/s 410k/s 10470k/s
+ SSLeay w31 378k/s 143k/s 2383k/s (fully 16bit)
+
+ Got to admit that Visual C++ 4.[01] is a damn fine compiler :-)
+--
+Eric Young | BOOL is tri-state according to Bill Gates.
+AARNet: eay@cryptsoft.com | RTFM Win32 GetMessage().
+
+
+
+
+==== ssl-ciph.doc ========================================================
+
+This is a quick high level summery of how things work now.
+
+Each SSLv2 and SSLv3 cipher is composed of 4 major attributes plus a few extra
+minor ones.
+
+They are 'The key exchange algorithm', which is RSA for SSLv2 but can also
+be Diffle-Hellman for SSLv3.
+
+An 'Authenticion algorithm', which can be RSA, Diffle-Helman, DSS or
+none.
+
+The cipher
+
+The MAC digest.
+
+A cipher can also be an export cipher and is either an SSLv2 or a
+SSLv3 ciphers.
+
+To specify which ciphers to use, one can either specify all the ciphers,
+one at a time, or use 'aliases' to specify the preference and order for
+the ciphers.
+
+There are a large number of aliases, but the most importaint are
+kRSA, kDHr, kDHd and kEDH for key exchange types.
+
+aRSA, aDSS, aNULL and aDH for authentication
+DES, 3DES, RC4, RC2, IDEA and eNULL for ciphers
+MD5, SHA0 and SHA1 digests
+
+Now where this becomes interesting is that these can be put together to
+specify the order and ciphers you wish to use.
+
+To speed this up there are also aliases for certian groups of ciphers.
+The main ones are
+SSLv2 - all SSLv2 ciphers
+SSLv3 - all SSLv3 ciphers
+EXP - all export ciphers
+LOW - all low strngth ciphers (no export ciphers, normally single DES)
+MEDIUM - 128 bit encryption
+HIGH - Triple DES
+
+These aliases can be joined in a : separated list which specifies to
+add ciphers, move them to the current location and delete them.
+
+A simpler way to look at all of this is to use the 'ssleay ciphers -v' command.
+The default library cipher spec is
+!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP
+which means, first, remove from consideration any ciphers that do not
+authenticate. Next up, use ciphers using RC4 and RSA. Next include the HIGH,
+MEDIUM and the LOW security ciphers. Finish up by adding all the export
+ciphers on the end, then 'pull' all the SSLv2 and export ciphers to
+the end of the list.
+
+The results are
+$ ssleay ciphers -v '!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP'
+
+RC4-SHA SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=SHA1
+RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5
+EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
+EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1
+DES-CBC3-SHA SSLv3 Kx=RSA Au=RSA Enc=3DES(168) Mac=SHA1
+IDEA-CBC-MD5 SSLv3 Kx=RSA Au=RSA Enc=IDEA(128) Mac=SHA1
+EDH-RSA-DES-CBC-SHA SSLv3 Kx=DH Au=RSA Enc=DES(56) Mac=SHA1
+EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH Au=DSS Enc=DES(56) Mac=SHA1
+DES-CBC-SHA SSLv3 Kx=RSA Au=RSA Enc=DES(56) Mac=SHA1
+DES-CBC3-MD5 SSLv2 Kx=RSA Au=RSA Enc=3DES(168) Mac=MD5
+DES-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=DES(56) Mac=MD5
+IDEA-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=IDEA(128) Mac=MD5
+RC2-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC2(128) Mac=MD5
+RC4-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5
+EXP-EDH-RSA-DES-CBC SSLv3 Kx=DH(512) Au=RSA Enc=DES(40) Mac=SHA1 export
+EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512) Au=DSS Enc=DES(40) Mac=SHA1 export
+EXP-DES-CBC-SHA SSLv3 Kx=RSA(512) Au=RSA Enc=DES(40) Mac=SHA1 export
+EXP-RC2-CBC-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export
+EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
+EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export
+EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
+
+I would recoment people use the 'ssleay ciphers -v "text"'
+command to check what they are going to use.
+
+Anyway, I'm falling asleep here so I'll do some more tomorrow.
+
+eric
+
+==== ssl.doc ========================================================
+
+SSL_CTX_sessions(SSL_CTX *ctx) - the session-id hash table.
+
+/* Session-id cache stats */
+SSL_CTX_sess_number
+SSL_CTX_sess_connect
+SSL_CTX_sess_connect_good
+SSL_CTX_sess_accept
+SSL_CTX_sess_accept_good
+SSL_CTX_sess_hits
+SSL_CTX_sess_cb_hits
+SSL_CTX_sess_misses
+SSL_CTX_sess_timeouts
+
+/* Session-id application notification callbacks */
+SSL_CTX_sess_set_new_cb
+SSL_CTX_sess_get_new_cb
+SSL_CTX_sess_set_get_cb
+SSL_CTX_sess_get_get_cb
+
+/* Session-id cache operation mode */
+SSL_CTX_set_session_cache_mode
+SSL_CTX_get_session_cache_mode
+
+/* Set default timeout values to use. */
+SSL_CTX_set_timeout
+SSL_CTX_get_timeout
+
+/* Global SSL initalisation informational callback */
+SSL_CTX_set_info_callback
+SSL_CTX_get_info_callback
+SSL_set_info_callback
+SSL_get_info_callback
+
+/* If the SSL_accept/SSL_connect returned with -1, these indicate when
+ * we should re-call *.
+SSL_want
+SSL_want_nothing
+SSL_want_read
+SSL_want_write
+SSL_want_x509_lookup
+
+/* Where we are in SSL initalisation, used in non-blocking, perhaps
+ * have a look at ssl/bio_ssl.c */
+SSL_state
+SSL_is_init_finished
+SSL_in_init
+SSL_in_connect_init
+SSL_in_accept_init
+
+/* Used to set the 'inital' state so SSL_in_connect_init and SSL_in_accept_init
+ * can be used to work out which function to call. */
+SSL_set_connect_state
+SSL_set_accept_state
+
+/* Where to look for certificates for authentication */
+SSL_set_default_verify_paths /* calles SSL_load_verify_locations */
+SSL_load_verify_locations
+
+/* get info from an established connection */
+SSL_get_session
+SSL_get_certificate
+SSL_get_SSL_CTX
+
+SSL_CTX_new
+SSL_CTX_free
+SSL_new
+SSL_clear
+SSL_free
+
+SSL_CTX_set_cipher_list
+SSL_get_cipher
+SSL_set_cipher_list
+SSL_get_cipher_list
+SSL_get_shared_ciphers
+
+SSL_accept
+SSL_connect
+SSL_read
+SSL_write
+
+SSL_debug
+
+SSL_get_read_ahead
+SSL_set_read_ahead
+SSL_set_verify
+
+SSL_pending
+
+SSL_set_fd
+SSL_set_rfd
+SSL_set_wfd
+SSL_set_bio
+SSL_get_fd
+SSL_get_rbio
+SSL_get_wbio
+
+SSL_use_RSAPrivateKey
+SSL_use_RSAPrivateKey_ASN1
+SSL_use_RSAPrivateKey_file
+SSL_use_PrivateKey
+SSL_use_PrivateKey_ASN1
+SSL_use_PrivateKey_file
+SSL_use_certificate
+SSL_use_certificate_ASN1
+SSL_use_certificate_file
+
+ERR_load_SSL_strings
+SSL_load_error_strings
+
+/* human readable version of the 'state' of the SSL connection. */
+SSL_state_string
+SSL_state_string_long
+/* These 2 report what kind of IO operation the library was trying to
+ * perform last. Probably not very usefull. */
+SSL_rstate_string
+SSL_rstate_string_long
+
+SSL_get_peer_certificate
+
+SSL_SESSION_new
+SSL_SESSION_print_fp
+SSL_SESSION_print
+SSL_SESSION_free
+i2d_SSL_SESSION
+d2i_SSL_SESSION
+
+SSL_get_time
+SSL_set_time
+SSL_get_timeout
+SSL_set_timeout
+SSL_copy_session_id
+SSL_set_session
+SSL_CTX_add_session
+SSL_CTX_remove_session
+SSL_CTX_flush_sessions
+
+BIO_f_ssl
+
+/* used to hold information as to why a certificate verification failed */
+SSL_set_verify_result
+SSL_get_verify_result
+
+/* can be used by the application to associate data with an SSL structure.
+ * It needs to be 'free()ed' by the application */
+SSL_set_app_data
+SSL_get_app_data
+
+/* The following all set values that are kept in the SSL_CTX but
+ * are used as the default values when an SSL session is created.
+ * They are over writen by the relevent SSL_xxxx functions */
+
+/* SSL_set_verify */
+void SSL_CTX_set_default_verify
+
+/* This callback, if set, totaly overrides the normal SSLeay verification
+ * functions and should return 1 on success and 0 on failure */
+void SSL_CTX_set_cert_verify_callback
+
+/* The following are the same as the equivilent SSL_xxx functions.
+ * Only one copy of this information is kept and if a particular
+ * SSL structure has a local override, it is totally separate structure.
+ */
+int SSL_CTX_use_RSAPrivateKey
+int SSL_CTX_use_RSAPrivateKey_ASN1
+int SSL_CTX_use_RSAPrivateKey_file
+int SSL_CTX_use_PrivateKey
+int SSL_CTX_use_PrivateKey_ASN1
+int SSL_CTX_use_PrivateKey_file
+int SSL_CTX_use_certificate
+int SSL_CTX_use_certificate_ASN1
+int SSL_CTX_use_certificate_file
+
+
+==== ssl_ctx.doc ========================================================
+
+This is now a bit dated, quite a few of the SSL_ functions could be
+SSL_CTX_ functions. I will update this in the future. 30 Aug 1996
+
+From eay@orb.mincom.oz.au Mon Dec 11 21:37:08 1995
+Received: by orb.mincom.oz.au id AA00696
+ (5.65c/IDA-1.4.4 for eay); Mon, 11 Dec 1995 11:37:08 +1000
+Date: Mon, 11 Dec 1995 11:37:08 +1000 (EST)
+From: Eric Young <eay@mincom.oz.au>
+X-Sender: eay@orb
+To: sameer <sameer@c2.org>
+Cc: Eric Young <eay@mincom.oz.au>
+Subject: Re: PEM_readX509 oesn't seem to be working
+In-Reply-To: <199512110102.RAA12521@infinity.c2.org>
+Message-Id: <Pine.SOL.3.91.951211112115.28608D-100000@orb>
+Mime-Version: 1.0
+Content-Type: TEXT/PLAIN; charset=US-ASCII
+Status: RO
+X-Status:
+
+On Sun, 10 Dec 1995, sameer wrote:
+> OK, that's solved. I've found out that it is saying "no
+> certificate set" in SSL_accept because s->conn == NULL
+> so there is some place I need to initialize s->conn that I am
+> not initializing it.
+
+The full order of things for a server should be.
+
+ctx=SSL_CTX_new();
+
+/* The next line should not really be using ctx->cert but I'll leave it
+ * this way right now... I don't want a X509_ routine to know about an SSL
+ * structure, there should be an SSL_load_verify_locations... hmm, I may
+ * add it tonight.
+ */
+X509_load_verify_locations(ctx->cert,CAfile,CApath);
+
+/* Ok now for each new connection we do the following */
+con=SSL_new(ctx);
+SSL_set_fd(con,s);
+SSL_set_verify(con,verify,verify_callback);
+
+/* set the certificate and private key to use. */
+SSL_use_certificate_ASN1(con,X509_certificate);
+SSL_use_RSAPrivateKey_ASN1(con,RSA_private_key);
+
+SSL_accept(con);
+
+SSL_read(con)/SSL_write(con);
+
+There is a bit more than that but that is basically the structure.
+
+Create a context and specify where to lookup certificates.
+
+foreach connection
+ {
+ create a SSL structure
+ set the certificate and private key
+ do a SSL_accept
+
+ we should now be ok
+ }
+
+eric
+--
+Eric Young | Signature removed since it was generating
+AARNet: eay@mincom.oz.au | more followups than the message contents :-)
+
+
+
+==== ssleay.doc ========================================================
+
+SSLeay: a cryptographic kitchen sink.
+
+1st December 1995
+Way back at the start of April 1995, I was looking for a mindless
+programming project. A friend of mine (Tim Hudson) said "why don't you do SSL,
+it has DES encryption in it and I would not mind using it in a SSL telnet".
+While it was true I had written a DES library in previous years, litle
+did I know what an expansive task SSL would turn into.
+
+First of all, the SSL protocol contains DES encryption. Well and good. My
+DES library was fast and portable. It also contained the RSA's RC4 stream
+cipher. Again, not a problem, some-one had just posted to sci.crypt
+something that was claimed to be RC4. It also contained IDEA, I had the
+specifications, not a problem to implement. MD5, an RFC, trivial, at most
+I could spend a week or so trying to see if I could speed up the
+implementation. All in all a nice set of ciphers.
+Then the first 'expantion of the scope', RSA public key
+encryption. Since I did not knowing a thing about public key encryption
+or number theory, this appeared quite a daunting task. Just writing a
+big number library would be problomatic in itself, let alone making it fast.
+At this point the scope of 'implementing SSL' expands eponentialy.
+First of all, the RSA private keys were being kept in ASN.1 format.
+Thankfully the RSA PKCS series of documents explains this format. So I now
+needed to be able to encode and decode arbitary ASN.1 objects. The Public
+keys were embeded in X509 certificates. Hmm... these are not only
+ASN.1 objects but they make up a heirachy of authentication. To
+authenticate a X509 certificate one needs to retrieve it's issuers
+certificate etc etc. Hmm..., so I also need to implement some kind
+of certificate management software. I would also have to implement
+software to authenticate certificates. At this point the support code made
+the SSL part of my library look quite small.
+Around this time, the first version of SSLeay was released.
+
+Ah, but here was the problem, I was not happy with the code so far. As may
+have become obvious, I had been treating all of this as a learning
+exersize, so I have completely written the library myself. As such, due
+to the way it had grown like a fungus, much of the library was not
+'elagent' or neat. There were global and static variables all over the
+place, the SSL part did not even handle non-blocking IO.
+The Great rewrite began.
+
+As of this point in time, the 'Great rewrite' has almost finished. So what
+follows is an approximate list of what is actually SSLeay 0.5.0
+
+/********* This needs to be updated for 0.6.0+ *************/
+
+---
+The library contains the following routines. Please note that most of these
+functions are not specfic for SSL or any other particular cipher
+implementation. I have tried to make all the routines as general purpose
+as possible. So you should not think of this library as an SSL
+implemtation, but rather as a library of cryptographic functions
+that also contains SSL. I refer to each of these function groupings as
+libraries since they are often capable of functioning as independant
+libraries
+
+First up, the general ciphers and message digests supported by the library.
+
+MD2 rfc???, a standard 'by parts' interface to this algorithm.
+MD5 rfc???, the same type of interface as for the MD2 library except a
+ different algorithm.
+SHA THe Secure Hash Algorithm. Again the same type of interface as
+ MD2/MD5 except the digest is 20 bytes.
+SHA1 The 'revised' version of SHA. Just about identical to SHA except
+ for one tweak of an inner loop.
+DES This is my libdes library that has been floating around for the last
+ few years. It has been enhanced for no other reason than completeness.
+ It now supports ecb, cbc, cfb, ofb, cfb64, ofb64 in normal mode and
+ triple DES modes of ecb, cbc, cfb64 and ofb64. cfb64 and ofb64 are
+ functional interfaces to the 64 bit modes of cfb and ofb used in
+ such a way thay they function as single character interfaces.
+RC4 The RSA Inc. stream cipher.
+RC2 The RSA Inc. block cipher.
+IDEA An implmentation of the IDEA cipher, the library supports ecb, cbc,
+ cfb64 and ofb64 modes of operation.
+
+Now all the above mentioned ciphers and digests libraries support high
+speed, minimal 'crap in the way' type interfaces. For fastest and
+lowest level access, these routines should be used directly.
+
+Now there was also the matter of public key crypto systems. These are
+based on large integer arithmatic.
+
+BN This is my large integer library. It supports all the normal
+ arithmentic operations. It uses malloc extensivly and as such has
+ no limits of the size of the numbers being manipulated. If you
+ wish to use 4000 bit RSA moduli, these routines will handle it.
+ This library also contains routines to 'generate' prime numbers and
+ to test for primality. The RSA and DH libraries sit on top of this
+ library. As of this point in time, I don't support SHA, but
+ when I do add it, it will just sit on top of the routines contained
+ in this library.
+RSA This implements the RSA public key algorithm. It also contains
+ routines that will generate a new private/public key pair.
+ All the RSA functions conform to the PKCS#1 standard.
+DH This is an implementation of the
+ Diffie-Hellman protocol. There are all the require routines for
+ the protocol, plus extra routines that can be used to generate a
+ strong prime for use with a specified generator. While this last
+ routine is not generally required by applications implementing DH,
+ It is present for completeness and because I thing it is much
+ better to be able to 'generate' your own 'magic' numbers as oposed
+ to using numbers suplied by others. I conform to the PKCS#3
+ standard where required.
+
+You may have noticed the preceeding section mentions the 'generation' of
+prime numbers. Now this requries the use of 'random numbers'.
+
+RAND This psuedo-random number library is based on MD5 at it's core
+ and a large internal state (2k bytes). Once you have entered enough
+ seed data into this random number algorithm I don't feel
+ you will ever need to worry about it generating predictable output.
+ Due to the way I am writing a portable library, I have left the
+ issue of how to get good initial random seed data upto the
+ application but I do have support routines for saving and loading a
+ persistant random number state for use between program runs.
+
+Now to make all these ciphers easier to use, a higher level
+interface was required. In this form, the same function would be used to
+encrypt 'by parts', via any one of the above mentioned ciphers.
+
+EVP The Digital EnVeloPe library is quite large. At it's core are
+ function to perform encryption and decryption by parts while using
+ an initial parameter to specify which of the 17 different ciphers
+ or 4 different message digests to use. On top of these are implmented
+ the digital signature functions, sign, verify, seal and open.
+ Base64 encoding of binary data is also done in this library.
+
+PEM rfc???? describe the format for Privacy Enhanced eMail.
+ As part of this standard, methods of encoding digital enveloped
+ data is an ascii format are defined. As such, I use a form of these
+ to encode enveloped data. While at this point in time full support
+ for PEM has not been built into the library, a minimal subset of
+ the secret key and Base64 encoding is present. These reoutines are
+ mostly used to Ascii encode binary data with a 'type' associated
+ with it and perhaps details of private key encryption used to
+ encrypt the data.
+
+PKCS7 This is another Digital Envelope encoding standard which uses ASN.1
+ to encode the data. At this point in time, while there are some
+ routines to encode and decode this binary format, full support is
+ not present.
+
+As Mentioned, above, there are several different ways to encode
+data structures.
+
+ASN1 This library is more a set of primatives used to encode the packing
+ and unpacking of data structures. It is used by the X509
+ certificate standard and by the PKCS standards which are used by
+ this library. It also contains routines for duplicating and signing
+ the structures asocisated with X509.
+
+X509 The X509 library contains routines for packing and unpacking,
+ verifying and just about every thing else you would want to do with
+ X509 certificates.
+
+PKCS7 PKCS-7 is a standard for encoding digital envelope data
+ structures. At this point in time the routines will load and save
+ DER forms of these structees. They need to be re-worked to support
+ the BER form which is the normal way PKCS-7 is encoded. If the
+ previous 2 sentances don't make much sense, don't worry, this
+ library is not used by this version of SSLeay anyway.
+
+OBJ ASN.1 uses 'object identifiers' to identify objects. A set of
+ functions were requred to translate from ASN.1 to an intenger, to a
+ character string. This library provieds these translations
+
+Now I mentioned an X509 library. X509 specified a hieachy of certificates
+which needs to be traversed to authenticate particular certificates.
+
+METH This library is used to push 'methods' of retrieving certificates
+ into the library. There are some supplied 'methods' with SSLeay
+ but applications can add new methods if they so desire.
+ This library has not been finished and is not being used in this
+ version.
+
+Now all the above are required for use in the initial point of this project.
+
+SSL The SSL protocol. This is a full implmentation of SSL v 2. It
+ support both server and client authentication. SSL v 3 support
+ will be added when the SSL v 3 specification is released in it's
+ final form.
+
+Now quite a few of the above mentioned libraries rely on a few 'complex'
+data structures. For each of these I have a library.
+
+Lhash This is a hash table library which is used extensivly.
+
+STACK An implemetation of a Stack data structure.
+
+BUF A simple character array structure that also support a function to
+ check that the array is greater that a certain size, if it is not,
+ it is realloced so that is it.
+
+TXT_DB A simple memory based text file data base. The application can specify
+ unique indexes that will be enforced at update time.
+
+CONF Most of the programs written for this library require a configuration
+ file. Instead of letting programs constantly re-implment this
+ subsystem, the CONF library provides a consistant and flexable
+ interface to not only configuration files but also environment
+ variables.
+
+But what about when something goes wrong?
+The one advantage (and perhaps disadvantage) of all of these
+functions being in one library was the ability to implement a
+single error reporting system.
+
+ERR This library is used to report errors. The error system records
+ library number, function number (in the library) and reason
+ number. Multiple errors can be reported so that an 'error' trace
+ is created. The errors can be printed in numeric or textual form.
+
+
+==== ssluse.doc ========================================================
+
+We have an SSL_CTX which contains global information for lots of
+SSL connections. The session-id cache and the certificate verificate cache.
+It also contains default values for use when certificates are used.
+
+SSL_CTX
+ default cipher list
+ session-id cache
+ certificate cache
+ default session-id timeout period
+ New session-id callback
+ Required session-id callback
+ session-id stats
+ Informational callback
+ Callback that is set, overrides the SSLeay X509 certificate
+ verification
+ The default Certificate/Private Key pair
+ Default read ahead mode.
+ Default verify mode and verify callback. These are not used
+ if the over ride callback mentioned above is used.
+
+Each SSL can have the following defined for it before a connection is made.
+
+Certificate
+Private key
+Ciphers to use
+Certificate verify mode and callback
+IO object to use in the comunication.
+Some 'read-ahead' mode information.
+A previous session-id to re-use.
+
+A connection is made by using SSL_connect or SSL_accept.
+When non-blocking IO is being used, there are functions that can be used
+to determin where and why the SSL_connect or SSL_accept did not complete.
+This information can be used to recall the functions when the 'error'
+condition has dissapeared.
+
+After the connection has been made, information can be retrived about the
+SSL session and the session-id values that have been decided apon.
+The 'peer' certificate can be retrieved.
+
+The session-id values include
+'start time'
+'timeout length'
+
+
+
+==== stack.doc ========================================================
+
+The stack data structure is used to store an ordered list of objects.
+It is basically misnamed to call it a stack but it can function that way
+and that is what I originally used it for. Due to the way element
+pointers are kept in a malloc()ed array, the most efficient way to use this
+structure is to add and delete elements from the end via sk_pop() and
+sk_push(). If you wish to do 'lookups' sk_find() is quite efficient since
+it will sort the stack (if required) and then do a binary search to lookup
+the requested item. This sorting occurs automatically so just sk_push()
+elements on the stack and don't worry about the order. Do remember that if
+you do a sk_find(), the order of the elements will change.
+
+You should never need to 'touch' this structure directly.
+typedef struct stack_st
+ {
+ unsigned int num;
+ char **data;
+ int sorted;
+
+ unsigned int num_alloc;
+ int (*comp)();
+ } STACK;
+
+'num' holds the number of elements in the stack, 'data' is the array of
+elements. 'sorted' is 1 is the list has been sorted, 0 if not.
+
+num_alloc is the number of 'nodes' allocated in 'data'. When num becomes
+larger than num_alloc, data is realloced to a larger size.
+If 'comp' is set, it is a function that is used to compare 2 of the items
+in the stack. The function should return -1, 0 or 1, depending on the
+ordering.
+
+#define sk_num(sk) ((sk)->num)
+#define sk_value(sk,n) ((sk)->data[n])
+
+These 2 macros should be used to access the number of elements in the
+'stack' and to access a pointer to one of the values.
+
+STACK *sk_new(int (*c)());
+ This creates a new stack. If 'c', the comparison function, is not
+specified, the various functions that operate on a sorted 'stack' will not
+work (sk_find()). NULL is returned on failure.
+
+void sk_free(STACK *);
+ This function free()'s a stack structure. The elements in the
+stack will not be freed so one should 'pop' and free all elements from the
+stack before calling this function or call sk_pop_free() instead.
+
+void sk_pop_free(STACK *st; void (*func)());
+ This function calls 'func' for each element on the stack, passing
+the element as the argument. sk_free() is then called to free the 'stack'
+structure.
+
+int sk_insert(STACK *sk,char *data,int where);
+ This function inserts 'data' into stack 'sk' at location 'where'.
+If 'where' is larger that the number of elements in the stack, the element
+is put at the end. This function tends to be used by other 'stack'
+functions. Returns 0 on failure, otherwise the number of elements in the
+new stack.
+
+char *sk_delete(STACK *st,int loc);
+ Remove the item a location 'loc' from the stack and returns it.
+Returns NULL if the 'loc' is out of range.
+
+char *sk_delete_ptr(STACK *st, char *p);
+ If the data item pointed to by 'p' is in the stack, it is deleted
+from the stack and returned. NULL is returned if the element is not in the
+stack.
+
+int sk_find(STACK *st,char *data);
+ Returns the location that contains a value that is equal to
+the 'data' item. If the comparison function was not set, this function
+does a linear search. This function actually qsort()s the stack if it is not
+in order and then uses bsearch() to do the initial search. If the
+search fails,, -1 is returned. For mutliple items with the same
+value, the index of the first in the array is returned.
+
+int sk_push(STACK *st,char *data);
+ Append 'data' to the stack. 0 is returned if there is a failure
+(due to a malloc failure), else 1. This is
+sk_insert(st,data,sk_num(st));
+
+int sk_unshift(STACK *st,char *data);
+ Prepend 'data' to the front (location 0) of the stack. This is
+sk_insert(st,data,0);
+
+char *sk_shift(STACK *st);
+ Return and delete from the stack the first element in the stack.
+This is sk_delete(st,0);
+
+char *sk_pop(STACK *st);
+ Return and delete the last element on the stack. This is
+sk_delete(st,sk_num(sk)-1);
+
+void sk_zero(STACK *st);
+ Removes all items from the stack. It does not 'free'
+pointers but is a quick way to clear a 'stack of references'.
+
+==== threads.doc ========================================================
+
+How to compile SSLeay for multi-threading.
+
+Well basically it is quite simple, set the compiler flags and build.
+I have only really done much testing under Solaris and Windows NT.
+If you library supports localtime_r() and gmtime_r() add,
+-DTHREADS to the makefile parameters. You can probably survive with out
+this define unless you are going to have multiple threads generating
+certificates at once. It will not affect the SSL side of things.
+
+The approach I have taken to doing locking is to make the application provide
+callbacks to perform locking and so that the SSLeay library can distinguish
+between threads (for the error state).
+
+To have a look at an example program, 'cd mt; vi mttest.c'.
+To build under solaris, sh solaris.sh, for Windows NT or Windows 95,
+win32.bat
+
+This will build mttest which will fire up 10 threads that talk SSL
+to each other 10 times.
+To enable everything to work, the application needs to call
+
+CRYPTO_set_id_callback(id_function);
+CRYPTO_set_locking_callback(locking_function);
+
+before any multithreading is started.
+id_function does not need to be defined under Windows NT or 95, the
+correct function will be called if it is not. Under unix, getpid()
+is call if the id_callback is not defined, for Solaris this is wrong
+(since threads id's are not pid's) but under Linux it is correct
+(threads are just processes sharing the data segement).
+
+The locking_callback is used to perform locking by the SSLeay library.
+eg.
+
+void solaris_locking_callback(mode,type,file,line)
+int mode;
+int type;
+char *file;
+int line;
+ {
+ if (mode & CRYPTO_LOCK)
+ mutex_lock(&(lock_cs[type]));
+ else
+ mutex_unlock(&(lock_cs[type]));
+ }
+
+Now in this case I have used mutexes instead of read/write locks, since they
+are faster and there are not many read locks in SSLeay, you may as well
+always use write locks. file and line are __FILE__ and __LINE__ from
+the compile and can be usefull when debugging.
+
+Now as you can see, 'type' can be one of a range of values, these values are
+defined in crypto/crypto.h
+CRYPTO_get_lock_name(type) will return a text version of what the lock is.
+There are CRYPTO_NUM_LOCKS locks required, so under solaris, the setup
+for multi-threading can be
+
+static mutex_t lock_cs[CRYPTO_NUM_LOCKS];
+
+void thread_setup()
+ {
+ int i;
+
+ for (i=0; i<CRYPTO_NUM_LOCKS; i++)
+ mutex_init(&(lock_cs[i]),USYNC_THREAD,NULL);
+ CRYPTO_set_id_callback((unsigned long (*)())solaris_thread_id);
+ CRYPTO_set_locking_callback((void (*)())solaris_locking_callback);
+ }
+
+As a final note, under Windows NT or Windows 95, you have to be careful
+not to mix the various threaded, unthreaded and debug libraries.
+Normally if they are mixed incorrectly, mttest will crash just after printing
+out some usage statistics at the end. This is because the
+different system libraries use different malloc routines and if
+data is malloc()ed inside crypt32.dll or ssl32.dll and then free()ed by a
+different library malloc, things get very confused.
+
+The default SSLeay DLL builds use /MD, so if you use this on your
+application, things will work as expected. If you use /MDd,
+you will probably have to rebuild SSLeay using this flag.
+I should modify util/mk1mf.pl so it does all this correctly, but
+this has not been done yet.
+
+One last warning. Because locking overheads are actually quite large, the
+statistics collected against the SSL_CTX for successfull connections etc
+are not locked when updated. This does make it possible for these
+values to be slightly lower than they should be, if you are
+running multithreaded on a multi-processor box, but this does not really
+matter much.
+
+
+==== txt_db.doc ========================================================
+
+TXT_DB, a simple text based in memory database.
+
+It holds rows of ascii data, for which the only special character is '\0'.
+The rows can be of an unlimited length.
+
+==== why.doc ========================================================
+
+This file is more of a note for other people who wish to understand why
+the build environment is the way it is :-).
+
+The include files 'depend' as follows.
+Each of
+crypto/*/*.c includes crypto/cryptlib.h
+ssl/*.c include ssl/ssl_locl.h
+apps/*.c include apps/apps.h
+crypto/cryptlib.h, ssl/ssl_locl.h and apps/apps.h
+all include e_os.h which contains OS/environment specific information.
+If you need to add something todo with a particular environment,
+add it to this file. It is worth remembering that quite a few libraries,
+like lhash, des, md, sha etc etc do not include crypto/cryptlib.h. This
+is because these libraries should be 'independantly compilable' and so I
+try to keep them this way.
+e_os.h is not so much a part of SSLeay, as the placing in one spot all the
+evil OS dependant muck.
+
+I wanted to automate as many things as possible. This includes
+error number generation. A
+make errors
+will scan the source files for error codes, append them to the correct
+header files, and generate the functions to print the text version
+of the error numbers. So don't even think about adding error numbers by
+hand, put them in the form
+XXXerr(XXXX_F_XXXX,YYYY_R_YYYY);
+on line and it will be automatically picked up my a make errors.
+
+In a similar vein, programs to be added into ssleay in the apps directory
+just need to have an entry added to E_EXE in makefile.ssl and
+everthing will work as expected. Don't edit progs.h by hand.
+
+make links re-generates the symbolic links that are used. The reason why
+I keep everything in its own directory, and don't put all the
+test programs and header files in 'test' and 'include' is because I want
+to keep the 'sub-libraries' independant. I still 'pull' out
+indervidual libraries for use in specific projects where the code is
+required. I have used the 'lhash' library in just about every software
+project I have worked on :-).
+
+make depend generates dependancies and
+make dclean removes them.
+
+You will notice that I use perl quite a bit when I could be using 'sed'.
+The reason I decided to do this was to just stick to one 'extra' program.
+For Windows NT, I have perl and no sed.
+
+The util/mk1mf.pl program can be used to generate a single makefile.
+I use this because makefiles under Microsoft are horrific.
+Each C compiler seems to have different linker formats, which have
+to be used because the retarted C compilers explode when you do
+cl -o file *.o.
+
+Now some would argue that I should just use the single makefile. I don't
+like it during develoment for 2 reasons. First, the actuall make
+command takes a long time. For my current setup, if I'm in
+crypto/bn and I type make, only the crypto/bn directory gets rebuilt,
+which is nice when you are modifying prototypes in bn.h which
+half the SSLeay depends on. The second is that to add a new souce file
+I just plonk it in at the required spot in the local makefile. This
+then alows me to keep things local, I don't need to modify a 'global'
+tables (the make for unix, the make for NT, the make for w31...).
+When I am ripping apart a library structure, it is nice to only
+have to worry about one directory :-).
+
+Having said all this, for the hell of it I put together 2 files that
+#include all the souce code (generated by doing a ls */*.o after a build).
+crypto.c takes only 30 seconds to build under NT and 2 minutes under linux
+for my pentium100. Much faster that the normal build :-).
+Again, the problem is that when using libraries, every program linked
+to libcrypto.a would suddenly get 330k of library when it may only need
+1k. This technique does look like a nice way to do shared libraries though.
+
+Oh yes, as a final note, to 'build' a distribution, I just type
+make dist.
+This cleans and packages everything. The directory needs to be called
+SSLeay since the make does a 'cd ..' and renames and tars things up.
+
+==== req.1 ========================================================
+
+The 'req' command is used to manipulate and deal with pkcs#10
+certificate requests.
+
+It's default mode of operation is to load a certificate and then
+write it out again.
+
+By default the 'req' is read from stdin in 'PEM' format.
+The -inform option can be used to specify 'pem' format or 'der'
+format. PEM format is the base64 encoding of the DER format.
+
+By default 'req' then writes the request back out. -outform can be used
+to indicate the desired output format, be it 'pem' or 'der'.
+
+To specify an input file, use the '-in' option and the '-out' option
+can be used to specify the output file.
+
+If you wish to perform a command and not output the certificate
+request afterwards, use the '-noout' option.
+
+When a certificate is loaded, it can be printed in a human readable
+ascii format via the '-text' option.
+
+To check that the signature on a certificate request is correct, use
+the '-verify' option to make sure that the private key contained in the
+certificate request corresponds to the signature.
+
+Besides the default mode, there is also the 'generate a certificate
+request' mode. There are several flags that trigger this mode.
+
+-new will generate a new RSA key (if required) and then prompts
+the user for details for the certificate request.
+-newkey has an argument that is the number of bits to make the new
+key. This function also triggers '-new'.
+
+The '-new' option can have a key to use specified instead of having to
+load one, '-key' is used to specify the file containg the key.
+-keyform can be used to specify the format of the key. Only
+'pem' and 'der' formats are supported, later, 'netscape' format may be added.
+
+Finally there is the '-x509' options which makes req output a self
+signed x509 certificate instead of a certificate request.
+
+Now as you may have noticed, there are lots of default options that
+cannot be specified via the command line. They are held in a 'template'
+or 'configuration file'. The -config option specifies which configuration
+file to use. See conf.doc for details on the syntax of this file.
+
+The req command uses the 'req' section of the config file.
+
+---
+# The following variables are defined. For this example I will populate
+# the various values
+[ req ]
+default_bits = 512 # default number of bits to use.
+default_keyfile = testkey.pem # Where to write the generated keyfile
+ # if not specified.
+distinguished_name= req_dn # The section that contains the
+ # information about which 'object' we
+ # want to put in the DN.
+attributes = req_attr # The objects we want for the
+ # attributes field.
+encrypt_rsa_key = no # Should we encrypt newly generated
+ # keys. I strongly recommend 'yes'.
+
+# The distinguished name section. For the following entries, the
+# object names must exist in the SSLeay header file objects.h. If they
+# do not, they will be silently ignored. The entries have the following
+# format.
+# <object_name> => string to prompt with
+# <object_name>_default => default value for people
+# <object_name>_value => Automatically use this value for this field.
+# <object_name>_min => minimum number of characters for data (def. 0)
+# <object_name>_max => maximum number of characters for data (def. inf.)
+# All of these entries are optional except for the first one.
+[ req_dn ]
+countryName = Country Name (2 letter code)
+countryName_default = AU
+
+stateOrProvinceName = State or Province Name (full name)
+stateOrProvinceName_default = Queensland
+
+localityName = Locality Name (eg, city)
+
+organizationName = Organization Name (eg, company)
+organizationName_default = Mincom Pty Ltd
+
+organizationalUnitName = Organizational Unit Name (eg, section)
+organizationalUnitName_default = MTR
+
+commonName = Common Name (eg, YOUR name)
+commonName_max = 64
+
+emailAddress = Email Address
+emailAddress_max = 40
+
+# The next section is the attributes section. This is exactly the
+# same as for the previous section except that the resulting objects are
+# put in the attributes field.
+[ req_attr ]
+challengePassword = A challenge password
+challengePassword_min = 4
+challengePassword_max = 20
+
+unstructuredName = An optional company name
+
+----
+Also note that the order that attributes appear in this file is the
+order they will be put into the distinguished name.
+
+Once this request has been generated, it can be sent to a CA for
+certifying.
+
+----
+A few quick examples....
+
+To generate a new request and a new key
+req -new
+
+To generate a new request and a 1058 bit key
+req -newkey 1058
+
+To generate a new request using a pre-existing key
+req -new -key key.pem
+
+To generate a self signed x509 certificate from a certificate
+request using a supplied key, and we want to see the text form of the
+output certificate (which we will put in the file selfSign.pem
+req -x509 -in req.pem -key key.pem -text -out selfSign.pem
+
+Verify that the signature is correct on a certificate request.
+req -verify -in req.pem
+
+Verify that the signature was made using a specified public key.
+req -verify -in req.pem -key key.pem
+
+Print the contents of a certificate request
+req -text -in req.pem
+
+==== danger ========================================================
+
+If you specify a SSLv2 cipher, and the mode is SSLv23 and the server
+can talk SSLv3, it will claim there is no cipher since you should be
+using SSLv3.
+
+When tracing debug stuff, remember BIO_s_socket() is different to
+BIO_s_connect().
+
+BSD/OS assember is not working
+
diff --git a/openssl/doc/standards.txt b/openssl/doc/standards.txt
new file mode 100644
index 000000000..a5ce778f8
--- /dev/null
+++ b/openssl/doc/standards.txt
@@ -0,0 +1,281 @@
+Standards related to OpenSSL
+============================
+
+[Please, this is currently a draft. I made a first try at finding
+ documents that describe parts of what OpenSSL implements. There are
+ big gaps, and I've most certainly done something wrong. Please
+ correct whatever is... Also, this note should be removed when this
+ file is reaching a somewhat correct state. -- Richard Levitte]
+
+
+All pointers in here will be either URL's or blobs of text borrowed
+from miscellaneous indexes, like rfc-index.txt (index of RFCs),
+1id-index.txt (index of Internet drafts) and the like.
+
+To find the latest possible RFCs, it's recommended to either browse
+ftp://ftp.isi.edu/in-notes/ or go to http://www.rfc-editor.org/ and
+use the search mechanism found there.
+To find the latest possible Internet drafts, it's recommended to
+browse ftp://ftp.isi.edu/internet-drafts/.
+To find the latest possible PKCS, it's recommended to browse
+http://www.rsasecurity.com/rsalabs/pkcs/.
+
+
+Implemented:
+------------
+
+These are documents that describe things that are implemented (in
+whole or at least great parts) in OpenSSL.
+
+1319 The MD2 Message-Digest Algorithm. B. Kaliski. April 1992.
+ (Format: TXT=25661 bytes) (Status: INFORMATIONAL)
+
+1320 The MD4 Message-Digest Algorithm. R. Rivest. April 1992. (Format:
+ TXT=32407 bytes) (Status: INFORMATIONAL)
+
+1321 The MD5 Message-Digest Algorithm. R. Rivest. April 1992. (Format:
+ TXT=35222 bytes) (Status: INFORMATIONAL)
+
+2246 The TLS Protocol Version 1.0. T. Dierks, C. Allen. January 1999.
+ (Format: TXT=170401 bytes) (Status: PROPOSED STANDARD)
+
+2268 A Description of the RC2(r) Encryption Algorithm. R. Rivest.
+ January 1998. (Format: TXT=19048 bytes) (Status: INFORMATIONAL)
+
+2315 PKCS 7: Cryptographic Message Syntax Version 1.5. B. Kaliski.
+ March 1998. (Format: TXT=69679 bytes) (Status: INFORMATIONAL)
+
+PKCS#8: Private-Key Information Syntax Standard
+
+PKCS#12: Personal Information Exchange Syntax Standard, version 1.0.
+
+2560 X.509 Internet Public Key Infrastructure Online Certificate
+ Status Protocol - OCSP. M. Myers, R. Ankney, A. Malpani, S. Galperin,
+ C. Adams. June 1999. (Format: TXT=43243 bytes) (Status: PROPOSED
+ STANDARD)
+
+2712 Addition of Kerberos Cipher Suites to Transport Layer Security
+ (TLS). A. Medvinsky, M. Hur. October 1999. (Format: TXT=13763 bytes)
+ (Status: PROPOSED STANDARD)
+
+2898 PKCS #5: Password-Based Cryptography Specification Version 2.0.
+ B. Kaliski. September 2000. (Format: TXT=68692 bytes) (Status:
+ INFORMATIONAL)
+
+2986 PKCS #10: Certification Request Syntax Specification Version 1.7.
+ M. Nystrom, B. Kaliski. November 2000. (Format: TXT=27794 bytes)
+ (Obsoletes RFC2314) (Status: INFORMATIONAL)
+
+3174 US Secure Hash Algorithm 1 (SHA1). D. Eastlake 3rd, P. Jones.
+ September 2001. (Format: TXT=35525 bytes) (Status: INFORMATIONAL)
+
+3268 Advanced Encryption Standard (AES) Ciphersuites for Transport
+ Layer Security (TLS). P. Chown. June 2002. (Format: TXT=13530 bytes)
+ (Status: PROPOSED STANDARD)
+
+3279 Algorithms and Identifiers for the Internet X.509 Public Key
+ Infrastructure Certificate and Certificate Revocation List (CRL)
+ Profile. L. Bassham, W. Polk, R. Housley. April 2002. (Format:
+ TXT=53833 bytes) (Status: PROPOSED STANDARD)
+
+3280 Internet X.509 Public Key Infrastructure Certificate and
+ Certificate Revocation List (CRL) Profile. R. Housley, W. Polk, W.
+ Ford, D. Solo. April 2002. (Format: TXT=295556 bytes) (Obsoletes
+ RFC2459) (Status: PROPOSED STANDARD)
+
+3447 Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography
+ Specifications Version 2.1. J. Jonsson, B. Kaliski. February 2003.
+ (Format: TXT=143173 bytes) (Obsoletes RFC2437) (Status:
+ INFORMATIONAL)
+
+3713 A Description of the Camellia Encryption Algorithm. M. Matsui,
+ J. Nakajima, S. Moriai. April 2004. (Format: TXT=25031 bytes)
+ (Status: INFORMATIONAL)
+
+3820 Internet X.509 Public Key Infrastructure (PKI) Proxy Certificate
+ Profile. S. Tuecke, V. Welch, D. Engert, L. Pearlman, M. Thompson.
+ June 2004. (Format: TXT=86374 bytes) (Status: PROPOSED STANDARD)
+
+4132 Addition of Camellia Cipher Suites to Transport Layer Security
+ (TLS). S. Moriai, A. Kato, M. Kanda. July 2005. (Format: TXT=13590
+ bytes) (Status: PROPOSED STANDARD)
+
+4162 Addition of SEED Cipher Suites to Transport Layer Security (TLS).
+ H.J. Lee, J.H. Yoon, J.I. Lee. August 2005. (Format: TXT=10578 bytes)
+ (Status: PROPOSED STANDARD)
+
+4269 The SEED Encryption Algorithm. H.J. Lee, S.J. Lee, J.H. Yoon,
+ D.H. Cheon, J.I. Lee. December 2005. (Format: TXT=34390 bytes)
+ (Obsoletes RFC4009) (Status: INFORMATIONAL)
+
+
+Related:
+--------
+
+These are documents that are close to OpenSSL, for example the
+STARTTLS documents.
+
+1421 Privacy Enhancement for Internet Electronic Mail: Part I: Message
+ Encryption and Authentication Procedures. J. Linn. February 1993.
+ (Format: TXT=103894 bytes) (Obsoletes RFC1113) (Status: PROPOSED
+ STANDARD)
+
+1422 Privacy Enhancement for Internet Electronic Mail: Part II:
+ Certificate-Based Key Management. S. Kent. February 1993. (Format:
+ TXT=86085 bytes) (Obsoletes RFC1114) (Status: PROPOSED STANDARD)
+
+1423 Privacy Enhancement for Internet Electronic Mail: Part III:
+ Algorithms, Modes, and Identifiers. D. Balenson. February 1993.
+ (Format: TXT=33277 bytes) (Obsoletes RFC1115) (Status: PROPOSED
+ STANDARD)
+
+1424 Privacy Enhancement for Internet Electronic Mail: Part IV: Key
+ Certification and Related Services. B. Kaliski. February 1993.
+ (Format: TXT=17537 bytes) (Status: PROPOSED STANDARD)
+
+2025 The Simple Public-Key GSS-API Mechanism (SPKM). C. Adams. October
+ 1996. (Format: TXT=101692 bytes) (Status: PROPOSED STANDARD)
+
+2510 Internet X.509 Public Key Infrastructure Certificate Management
+ Protocols. C. Adams, S. Farrell. March 1999. (Format: TXT=158178
+ bytes) (Status: PROPOSED STANDARD)
+
+2511 Internet X.509 Certificate Request Message Format. M. Myers, C.
+ Adams, D. Solo, D. Kemp. March 1999. (Format: TXT=48278 bytes)
+ (Status: PROPOSED STANDARD)
+
+2527 Internet X.509 Public Key Infrastructure Certificate Policy and
+ Certification Practices Framework. S. Chokhani, W. Ford. March 1999.
+ (Format: TXT=91860 bytes) (Status: INFORMATIONAL)
+
+2538 Storing Certificates in the Domain Name System (DNS). D. Eastlake
+ 3rd, O. Gudmundsson. March 1999. (Format: TXT=19857 bytes) (Status:
+ PROPOSED STANDARD)
+
+2539 Storage of Diffie-Hellman Keys in the Domain Name System (DNS).
+ D. Eastlake 3rd. March 1999. (Format: TXT=21049 bytes) (Status:
+ PROPOSED STANDARD)
+
+2559 Internet X.509 Public Key Infrastructure Operational Protocols -
+ LDAPv2. S. Boeyen, T. Howes, P. Richard. April 1999. (Format:
+ TXT=22889 bytes) (Updates RFC1778) (Status: PROPOSED STANDARD)
+
+2585 Internet X.509 Public Key Infrastructure Operational Protocols:
+ FTP and HTTP. R. Housley, P. Hoffman. May 1999. (Format: TXT=14813
+ bytes) (Status: PROPOSED STANDARD)
+
+2587 Internet X.509 Public Key Infrastructure LDAPv2 Schema. S.
+ Boeyen, T. Howes, P. Richard. June 1999. (Format: TXT=15102 bytes)
+ (Status: PROPOSED STANDARD)
+
+2595 Using TLS with IMAP, POP3 and ACAP. C. Newman. June 1999.
+ (Format: TXT=32440 bytes) (Status: PROPOSED STANDARD)
+
+2631 Diffie-Hellman Key Agreement Method. E. Rescorla. June 1999.
+ (Format: TXT=25932 bytes) (Status: PROPOSED STANDARD)
+
+2632 S/MIME Version 3 Certificate Handling. B. Ramsdell, Ed.. June
+ 1999. (Format: TXT=27925 bytes) (Status: PROPOSED STANDARD)
+
+2716 PPP EAP TLS Authentication Protocol. B. Aboba, D. Simon. October
+ 1999. (Format: TXT=50108 bytes) (Status: EXPERIMENTAL)
+
+2773 Encryption using KEA and SKIPJACK. R. Housley, P. Yee, W. Nace.
+ February 2000. (Format: TXT=20008 bytes) (Updates RFC0959) (Status:
+ EXPERIMENTAL)
+
+2797 Certificate Management Messages over CMS. M. Myers, X. Liu, J.
+ Schaad, J. Weinstein. April 2000. (Format: TXT=103357 bytes) (Status:
+ PROPOSED STANDARD)
+
+2817 Upgrading to TLS Within HTTP/1.1. R. Khare, S. Lawrence. May
+ 2000. (Format: TXT=27598 bytes) (Updates RFC2616) (Status: PROPOSED
+ STANDARD)
+
+2818 HTTP Over TLS. E. Rescorla. May 2000. (Format: TXT=15170 bytes)
+ (Status: INFORMATIONAL)
+
+2876 Use of the KEA and SKIPJACK Algorithms in CMS. J. Pawling. July
+ 2000. (Format: TXT=29265 bytes) (Status: INFORMATIONAL)
+
+2984 Use of the CAST-128 Encryption Algorithm in CMS. C. Adams.
+ October 2000. (Format: TXT=11591 bytes) (Status: PROPOSED STANDARD)
+
+2985 PKCS #9: Selected Object Classes and Attribute Types Version 2.0.
+ M. Nystrom, B. Kaliski. November 2000. (Format: TXT=70703 bytes)
+ (Status: INFORMATIONAL)
+
+3029 Internet X.509 Public Key Infrastructure Data Validation and
+ Certification Server Protocols. C. Adams, P. Sylvester, M. Zolotarev,
+ R. Zuccherato. February 2001. (Format: TXT=107347 bytes) (Status:
+ EXPERIMENTAL)
+
+3039 Internet X.509 Public Key Infrastructure Qualified Certificates
+ Profile. S. Santesson, W. Polk, P. Barzin, M. Nystrom. January 2001.
+ (Format: TXT=67619 bytes) (Status: PROPOSED STANDARD)
+
+3058 Use of the IDEA Encryption Algorithm in CMS. S. Teiwes, P.
+ Hartmann, D. Kuenzi. February 2001. (Format: TXT=17257 bytes)
+ (Status: INFORMATIONAL)
+
+3161 Internet X.509 Public Key Infrastructure Time-Stamp Protocol
+ (TSP). C. Adams, P. Cain, D. Pinkas, R. Zuccherato. August 2001.
+ (Format: TXT=54585 bytes) (Status: PROPOSED STANDARD)
+
+3185 Reuse of CMS Content Encryption Keys. S. Farrell, S. Turner.
+ October 2001. (Format: TXT=20404 bytes) (Status: PROPOSED STANDARD)
+
+3207 SMTP Service Extension for Secure SMTP over Transport Layer
+ Security. P. Hoffman. February 2002. (Format: TXT=18679 bytes)
+ (Obsoletes RFC2487) (Status: PROPOSED STANDARD)
+
+3217 Triple-DES and RC2 Key Wrapping. R. Housley. December 2001.
+ (Format: TXT=19855 bytes) (Status: INFORMATIONAL)
+
+3274 Compressed Data Content Type for Cryptographic Message Syntax
+ (CMS). P. Gutmann. June 2002. (Format: TXT=11276 bytes) (Status:
+ PROPOSED STANDARD)
+
+3278 Use of Elliptic Curve Cryptography (ECC) Algorithms in
+ Cryptographic Message Syntax (CMS). S. Blake-Wilson, D. Brown, P.
+ Lambert. April 2002. (Format: TXT=33779 bytes) (Status:
+ INFORMATIONAL)
+
+3281 An Internet Attribute Certificate Profile for Authorization. S.
+ Farrell, R. Housley. April 2002. (Format: TXT=90580 bytes) (Status:
+ PROPOSED STANDARD)
+
+3369 Cryptographic Message Syntax (CMS). R. Housley. August 2002.
+ (Format: TXT=113975 bytes) (Obsoletes RFC2630, RFC3211) (Status:
+ PROPOSED STANDARD)
+
+3370 Cryptographic Message Syntax (CMS) Algorithms. R. Housley. August
+ 2002. (Format: TXT=51001 bytes) (Obsoletes RFC2630, RFC3211) (Status:
+ PROPOSED STANDARD)
+
+3377 Lightweight Directory Access Protocol (v3): Technical
+ Specification. J. Hodges, R. Morgan. September 2002. (Format:
+ TXT=9981 bytes) (Updates RFC2251, RFC2252, RFC2253, RFC2254, RFC2255,
+ RFC2256, RFC2829, RFC2830) (Status: PROPOSED STANDARD)
+
+3394 Advanced Encryption Standard (AES) Key Wrap Algorithm. J. Schaad,
+ R. Housley. September 2002. (Format: TXT=73072 bytes) (Status:
+ INFORMATIONAL)
+
+3436 Transport Layer Security over Stream Control Transmission
+ Protocol. A. Jungmaier, E. Rescorla, M. Tuexen. December 2002.
+ (Format: TXT=16333 bytes) (Status: PROPOSED STANDARD)
+
+3657 Use of the Camellia Encryption Algorithm in Cryptographic
+ Message Syntax (CMS). S. Moriai, A. Kato. January 2004.
+ (Format: TXT=26282 bytes) (Status: PROPOSED STANDARD)
+
+"Securing FTP with TLS", 01/27/2000, <draft-murray-auth-ftp-ssl-05.txt>
+
+
+To be implemented:
+------------------
+
+These are documents that describe things that are planed to be
+implemented in the hopefully short future.
+