10 files changed, 307 insertions, 16 deletions

diff --git a/src/lib/libcrypto/doc/DH_set_method.pod b/src/lib/libcrypto/doc/DH_set_method.pod
index dca41d8dbc..a8f75bdd9d 100644
--- a/src/lib/libcrypto/doc/DH_set_method.pod
+++ b/src/lib/libcrypto/doc/DH_set_method.pod
@@ -56,7 +56,7 @@ the default method is used.
      /* compute shared secret */
         int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh);
 
-     /* compute r = a ^ p mod m. May be NULL */
+     /* 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);
diff --git a/src/lib/libcrypto/doc/DSA_set_method.pod b/src/lib/libcrypto/doc/DSA_set_method.pod
index 0b13ec9237..edec46413d 100644
--- a/src/lib/libcrypto/doc/DSA_set_method.pod
+++ b/src/lib/libcrypto/doc/DSA_set_method.pod
@@ -62,12 +62,13 @@ struct
         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 */
+     /* 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 */
+     /* 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);
diff --git a/src/lib/libcrypto/doc/EVP_OpenInit.pod b/src/lib/libcrypto/doc/EVP_OpenInit.pod
new file mode 100644
index 0000000000..9707a4b399
--- /dev/null
+++ b/src/lib/libcrypto/doc/EVP_OpenInit.pod
@@ -0,0 +1,51 @@
+=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);
+ void EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+         int *outl, unsigned char *in, int inl);
+ void 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() initialises 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 RETURN VALUES
+
+EVP_OpenInit() returns -1 on error or an non zero integer (actually the
+recovered secret key size) if successful.
+
+EVP_SealUpdate() does not return a value.
+
+EVP_SealFinal() 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/src/lib/libcrypto/doc/EVP_SealInit.pod b/src/lib/libcrypto/doc/EVP_SealInit.pod
new file mode 100644
index 0000000000..1579d110fa
--- /dev/null
+++ b/src/lib/libcrypto/doc/EVP_SealInit.pod
@@ -0,0 +1,70 @@
+=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, EVP_CIPHER *type, unsigned char **ek,
+                int *ekl, unsigned char *iv,EVP_PKEY **pubk, int npubk);
+ void EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+         int *outl, unsigned char *in, int inl);
+ void 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 then "envelope" it by
+using public key encryption. Data can then be encrypted using this
+key.
+
+EVP_SealInit() initialises a cipher context B<ctx> for encryption
+with cipher B<type> using a random secret key and IV supplied in
+the B<iv> parameter. 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.
+
+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 -1 on error or B<npubk> if successful.
+
+EVP_SealUpdate() and EVP_SealFinal() do not return values.
+
+=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.
+
+=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
+
+=cut
diff --git a/src/lib/libcrypto/doc/EVP_SignInit.pod b/src/lib/libcrypto/doc/EVP_SignInit.pod
new file mode 100644
index 0000000000..bbc9203c9c
--- /dev/null
+++ b/src/lib/libcrypto/doc/EVP_SignInit.pod
@@ -0,0 +1,85 @@
+=pod
+
+=head1 NAME
+
+EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
+ void 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);
+
+ int EVP_PKEY_size(EVP_PKEY *pkey);
+
+=head1 DESCRIPTION
+
+The EVP signature routines are a high level interface to digital
+signatures.
+
+EVP_SignInit() initialises a signing context B<ctx> to using digest
+B<type>: this will typically be supplied by a function such as
+EVP_sha1().
+
+EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the
+signature context B<ctx>. This funtion 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>. If the B<s> parameter is not NULL
+then 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.  After calling EVP_SignFinal() no additional calls to
+EVP_SignUpdate() can be made, but EVP_SignInit() can be called to initialiase
+a new signature operation.
+
+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() and EVP_SignUpdate() do not return values.
+
+EVP_SignFinal() returns 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.
+
+=head1 BUGS
+
+Several of the functions do not return values: maybe they should. Although the
+internal digest operations will never fail some future hardware based operations
+might.
+
+=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<digest(1)|digest(1)>
+
+=head1 HISTORY
+
+EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are
+available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/src/lib/libcrypto/doc/EVP_VerifyInit.pod b/src/lib/libcrypto/doc/EVP_VerifyInit.pod
new file mode 100644
index 0000000000..3b5e07f4ad
--- /dev/null
+++ b/src/lib/libcrypto/doc/EVP_VerifyInit.pod
@@ -0,0 +1,71 @@
+=pod
+
+=head1 NAME
+
+EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ void EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);
+ void 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);
+
+=head1 DESCRIPTION
+
+The EVP signature verification routines are a high level interface to digital
+signatures.
+
+EVP_VerifyInit() initialises a verification context B<ctx> to using digest
+B<type>: this will typically be supplied by a function such as EVP_sha1().
+
+EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
+verification context B<ctx>. This funtion 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>. After calling EVP_VerifyFinal()
+no additional calls to EVP_VerifyUpdate() can be made, but EVP_VerifyInit()
+can be called to initialiase a new verification operation.
+
+=head1 RETURN VALUES
+
+EVP_VerifyInit() and EVP_VerifyUpdate() do not return values.
+
+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)>.
+
+=head1 BUGS
+
+Several of the functions do not return values: maybe they should. Although the
+internal digest operations will never fail some future hardware based operations
+might.
+
+=head1 SEE ALSO
+
+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<digest(1)|digest(1)>
+
+=head1 HISTORY
+
+EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are
+available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/src/lib/libcrypto/doc/RAND_add.pod b/src/lib/libcrypto/doc/RAND_add.pod
index 0a13ec2a92..67c66f3e0c 100644
--- a/src/lib/libcrypto/doc/RAND_add.pod
+++ b/src/lib/libcrypto/doc/RAND_add.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-RAND_add, RAND_seed, RAND_screen - add entropy to the PRNG
+RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add
+entropy to the PRNG
 
 =head1 SYNOPSIS
 
@@ -14,6 +15,7 @@ RAND_add, RAND_seed, RAND_screen - add entropy to the PRNG
 
  int  RAND_status(void);
 
+ int  RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam);
  void RAND_screen(void);
 
 =head1 DESCRIPTION
@@ -40,17 +42,24 @@ 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 with
-the parameters of B<WM_MOUSEMOVE> events is a significantly better
-source of randomness. It should be noted that both methods cannot be
-used on servers that run without user interaction.
+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() returns 1 if the PRNG has been seeded with enough data,
-0 otherwise.
+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.
 
@@ -63,6 +72,6 @@ L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)>
 
 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.
+0.9.5, RAND_event() in OpenSSL 0.9.5a.
 
 =cut
diff --git a/src/lib/libcrypto/doc/RAND_set_rand_method.pod b/src/lib/libcrypto/doc/RAND_set_rand_method.pod
index 466e9b8767..464eba416d 100644
--- a/src/lib/libcrypto/doc/RAND_set_rand_method.pod
+++ b/src/lib/libcrypto/doc/RAND_set_rand_method.pod
@@ -34,10 +34,12 @@ RAND_get_rand_method() returns a pointer to the current method.
         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() and RAND_pseudo_rand().
+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
diff --git a/src/lib/libcrypto/doc/RSA_set_method.pod b/src/lib/libcrypto/doc/RSA_set_method.pod
index deb1183a23..14b0b4cf35 100644
--- a/src/lib/libcrypto/doc/RSA_set_method.pod
+++ b/src/lib/libcrypto/doc/RSA_set_method.pod
@@ -87,10 +87,11 @@ the default method is used.
         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 */
+     /* 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 */
+     /* 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);
 
diff --git a/src/lib/libcrypto/doc/rsa.pod b/src/lib/libcrypto/doc/rsa.pod
index 0486c044a6..eb8ba612c4 100644
--- a/src/lib/libcrypto/doc/rsa.pod
+++ b/src/lib/libcrypto/doc/rsa.pod
@@ -86,8 +86,9 @@ contain public as well as private RSA keys:
 In public keys, the private exponent and the related secret values are
 B<NULL>.
 
-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.
+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.
 
 =head1 CONFORMING TO