16 files changed, 188 insertions, 38 deletions
diff --git a/crypto/openssl/doc/HOWTO/certificates.txt b/crypto/openssl/doc/HOWTO/certificates.txt
index 82166e0dc23e..d3a62545adf3 100644
--- a/crypto/openssl/doc/HOWTO/certificates.txt
+++ b/crypto/openssl/doc/HOWTO/certificates.txt
@@ -48,7 +48,7 @@ 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 is created like this:
+The certificate request is created like this:
 
   openssl req -new -key privkey.pem -out cert.csr
 
@@ -71,13 +71,11 @@ received.
 If you don't want to deal with another certificate authority, or just
 want to create a test certificate for yourself, or are setting up a
 certificate authority of your own, you may want to make the requested
-certificate a self-signed one.  If you have created a certificate
-request as shown above, you can sign it using the 'openssl x509'
-command, for example like this (to create a self-signed CA
-certificate):
+certificate a self-signed one.  This is similar to creating a
+certificate request, but creates a certificate instead of a
+certificate request (1095 is 3 years):
 
-  openssl x509 -req -in cert.csr -extfile openssl.cnf -extensions v3_ca \
-	  -signkey privkey.pem -out cacert.pem -trustout
+  openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095
 
 
 5. What to do with the certificate
diff --git a/crypto/openssl/doc/HOWTO/keys.txt b/crypto/openssl/doc/HOWTO/keys.txt
new file mode 100644
index 000000000000..45f42eaaf1b7
--- /dev/null
+++ b/crypto/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 both 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/crypto/openssl/doc/apps/ca.pod b/crypto/openssl/doc/apps/ca.pod
index de66c534b5cc..74f45ca2f90e 100644
--- a/crypto/openssl/doc/apps/ca.pod
+++ b/crypto/openssl/doc/apps/ca.pod
@@ -359,7 +359,7 @@ the same as the B<-md> option. The message digest to use. Mandatory.
 the text database file to use. Mandatory. This file must be present
 though initially it will be empty.
 
-=item B<serialfile>
+=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.
@@ -400,7 +400,7 @@ 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<default_ca> are accepted by both to produce
+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
@@ -513,8 +513,8 @@ A sample configuration file with the relevant sections for B<ca>:
  policy         = policy_any            # default policy
  email_in_dn    = no                    # Don't add the email into cert DN
 
- nameopt	= default_ca		# Subject name display option
- certopt	= default_ca		# Certificate display option
+ nameopt	= ca_default		# Subject name display option
+ certopt	= ca_default		# Certificate display option
  copy_extensions = none			# Don't copy extensions from request
 
  [ policy_any ]
diff --git a/crypto/openssl/doc/apps/ocsp.pod b/crypto/openssl/doc/apps/ocsp.pod
index da201b95e64f..4f266058e536 100644
--- a/crypto/openssl/doc/apps/ocsp.pod
+++ b/crypto/openssl/doc/apps/ocsp.pod
@@ -11,6 +11,10 @@ B<openssl> B<ocsp>
 [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>]
@@ -20,27 +24,36 @@ B<openssl> B<ocsp>
 [B<-respin file>]
 [B<-nonce>]
 [B<-no_nonce>]
-[B<-url responder_url>]
+[B<-url URL>]
 [B<-host host:n>]
 [B<-path>]
-[B<-CApath file>]
+[B<-CApath dir>]
 [B<-CAfile file>]
 [B<-VAfile file>]
-[B<-verify_certs file>]
+[B<-validity_period n>]
+[B<-status_age n>]
 [B<-noverify>]
+[B<-verify_other file>]
 [B<-trust_other>]
 [B<-no_intern>]
-[B<-no_sig_verify>]
+[B<-no_signature_verify>]
 [B<-no_cert_verify>]
 [B<-no_chain>]
 [B<-no_cert_checks>]
-[B<-validity_period nsec>]
-[B<-status_age nsec>]
+[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
 
-B<WARNING: this documentation is preliminary and subject to change.>
-
 The Online Certificate Status Protocol (OCSP) enables applications to
 determine the (revocation) state of an identified certificate (RFC 2560).
 
@@ -83,6 +96,10 @@ 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.
@@ -120,7 +137,7 @@ or "/" by default.
 file or pathname containing trusted CA certificates. These are used to verify
 the signature on the OCSP response.
 
-=item B<-verify_certs file>
+=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
@@ -151,7 +168,7 @@ ignore certificates contained in the OCSP response when searching for the
 signers certificate. With this option the signers certificate must be specified
 with either the B<-verify_certs> or B<-VAfile> options.
 
-=item B<-no_sig_verify>
+=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.
diff --git a/crypto/openssl/doc/apps/s_client.pod b/crypto/openssl/doc/apps/s_client.pod
index 7fca9cbdbd68..d061326c1fca 100644
--- a/crypto/openssl/doc/apps/s_client.pod
+++ b/crypto/openssl/doc/apps/s_client.pod
@@ -33,6 +33,7 @@ B<openssl> B<s_client>
 [B<-no_tls1>]
 [B<-bugs>]
 [B<-cipher cipherlist>]
+[B<-starttls protocol>]
 [B<-engine id>]
 [B<-rand file(s)>]
 
@@ -163,6 +164,12 @@ 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" and "pop3".
+
 =item B<-engine id>
 
 specifying an engine (by it's unique B<id> string) will cause B<s_client>
diff --git a/crypto/openssl/doc/apps/s_server.pod b/crypto/openssl/doc/apps/s_server.pod
index 4b1e4260ef1e..1d21921e47d1 100644
--- a/crypto/openssl/doc/apps/s_server.pod
+++ b/crypto/openssl/doc/apps/s_server.pod
@@ -42,6 +42,7 @@ B<openssl> B<s_server>
 [B<-WWW>]
 [B<-HTTP>]
 [B<-engine id>]
+[B<-id_prefix arg>]
 [B<-rand file(s)>]
 
 =head1 DESCRIPTION
@@ -209,6 +210,13 @@ 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
diff --git a/crypto/openssl/doc/crypto/BIO_f_base64.pod b/crypto/openssl/doc/crypto/BIO_f_base64.pod
index fdb603b38e30..929557d22f02 100644
--- a/crypto/openssl/doc/crypto/BIO_f_base64.pod
+++ b/crypto/openssl/doc/crypto/BIO_f_base64.pod
@@ -55,16 +55,15 @@ to standard output:
 Read Base64 encoded data from standard input and write the decoded
 data to standard output:
 
- BIO *bio, *b64, bio_out;
+ BIO *bio, *b64, *bio_out;
  char inbuf[512];
  int inlen;
- char message[] = "Hello World \n";
 
  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, strlen(message))) > 0) 
+ while((inlen = BIO_read(bio, inbuf, 512) > 0) 
 	BIO_write(bio_out, inbuf, inlen);
 
  BIO_free_all(bio);
diff --git a/crypto/openssl/doc/crypto/BIO_f_cipher.pod b/crypto/openssl/doc/crypto/BIO_f_cipher.pod
index 4182f2c30903..02439cea94a0 100644
--- a/crypto/openssl/doc/crypto/BIO_f_cipher.pod
+++ b/crypto/openssl/doc/crypto/BIO_f_cipher.pod
@@ -28,7 +28,7 @@ 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> to B<cipher> using key B<key>
+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.
 
diff --git a/crypto/openssl/doc/openssl-shared.txt b/crypto/openssl/doc/openssl-shared.txt
new file mode 100644
index 000000000000..5cf84a054ff3
--- /dev/null
+++ b/crypto/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/crypto/openssl/doc/ssl/SSL_CTX_free.pod b/crypto/openssl/doc/ssl/SSL_CTX_free.pod
index 55e592f5f826..51d86769682f 100644
--- a/crypto/openssl/doc/ssl/SSL_CTX_free.pod
+++ b/crypto/openssl/doc/ssl/SSL_CTX_free.pod
@@ -20,12 +20,22 @@ 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_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/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod
index 7c0b2baf6c5e..b9d54a40a193 100644
--- a/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod
+++ b/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod
@@ -60,10 +60,11 @@ 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 if the session is removed because
-it is expired or when a connection was not shutdown cleanly. The
-remove_session_cb() is passed the B<ctx> and the ssl session B<sess>.
-It does not provide any feedback.
+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
@@ -80,6 +81,7 @@ L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>.
 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_SESSION_free(3)|SSL_SESSION_free(3)>,
+L<SSL_CTX_free(3)|SSL_CTX_free(3)>
 
 =cut
diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod
index f5e2ec355508..766f0c920070 100644
--- a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod
+++ b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod
@@ -176,7 +176,7 @@ will send his list of preferences to the client and the client chooses.
 =item SSL_OP_NETSCAPE_CA_DN_BUG
 
 If we accept a netscape connection, demand a client cert, have a
-non-self-sighed CA which does not have it's CA in netscape, and the
+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
diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod
index d15b2a3a1a5b..ca8d81b82c81 100644
--- a/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod
+++ b/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod
@@ -135,9 +135,9 @@ 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 never be terminated because of this application
-experiencing a verification failure. The calling process can however
-retrieve the error code of the last verification error using
+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>.
 
diff --git a/crypto/openssl/doc/ssl/SSL_CTX_use_certificate.pod b/crypto/openssl/doc/ssl/SSL_CTX_use_certificate.pod
index b8868f18bfc1..ea2faba3ecca 100644
--- a/crypto/openssl/doc/ssl/SSL_CTX_use_certificate.pod
+++ b/crypto/openssl/doc/ssl/SSL_CTX_use_certificate.pod
@@ -68,7 +68,9 @@ 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 certificate to the highest level (root CA).
+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>.
diff --git a/crypto/openssl/doc/ssl/SSL_accept.pod b/crypto/openssl/doc/ssl/SSL_accept.pod
index a673edba8532..cc724c0d561a 100644
--- a/crypto/openssl/doc/ssl/SSL_accept.pod
+++ b/crypto/openssl/doc/ssl/SSL_accept.pod
@@ -28,7 +28,8 @@ 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. In this case a call to SSL_get_error() with the
+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().
diff --git a/crypto/openssl/doc/ssl/SSL_connect.pod b/crypto/openssl/doc/ssl/SSL_connect.pod
index 8426310c0d26..cc56ebb75f3f 100644
--- a/crypto/openssl/doc/ssl/SSL_connect.pod
+++ b/crypto/openssl/doc/ssl/SSL_connect.pod
@@ -25,7 +25,8 @@ 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. In this case a call to SSL_get_error() with the
+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().