Commit a0474357 authored by Rich Salz's avatar Rich Salz Committed by Rich Salz
Browse files

Various RT doc fixes 



RT1556: doc/crypto/threads.pod
RT2024: Missing pages mentioned in crypto.pod
RT2890: Wrong size in ERR_string_error description.
RT3461: Better description of PEM Encryption
        (Jeffrey Walton <noloader@gmail.com>)
        Also, fix up formatting and removed some code examples
        that encourage unsafe patterns, like unencrypted private
        keys (Rich Salz)
RT4240: Document some speed flags (Tomas Mraz <tmraz@redhat.com>)
RT4260: Fix return value doc for X509_REQ_sign and X509_sign
        (Laetitia Baudoin <lbaudoin@google.com>)

Reviewed-by: default avatarEmilia Käsper <emilia@openssl.org>
parent e51511ce

doc/apps/speed.pod

+16 −0
Original line number Diff line number Diff line
@@ -8,6 +8,9 @@ speed - test library performance 


B<openssl speed>

[B<-engine id>]

[B<-elapsed>]

[B<-evp algo>]

[B<-decrypt>]

[B<md2>]

[B<mdc2>]

[B<md5>]
@@ -49,6 +52,19 @@ 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<-elapsed>



Measure time in real time instead of CPU time. It can be useful when testing

speed of hardware engines.



=item B<-evp algo>



Use the specified cipher or message digest algorithm via the EVP interface.



=item B<-decrypt>



Time the decryption instead of encryption. Affects only the EVP testing.



=item B<[zero or more test algorithms]>



If any options are given, B<speed> tests those algorithms, otherwise all of

doc/crypto/ERR_error_string.pod

+4 −1
Original line number Diff line number Diff line
@@ -20,9 +20,12 @@ error message 
=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

error code I<e>, and places it at I<buf>. I<buf> must be at least 256

bytes long. If I<buf> is B<NULL>, the error string is placed in a

static buffer.

Note that this function is not thread-safe and does no checks on the size

of the buffer; use ERR_error_string_n() instead.



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.

doc/crypto/X509_sign.pod

+2 −2
Original line number Diff line number Diff line
@@ -52,8 +52,8 @@ signature and signing will always update the encoding. 
=head1 RETURN VALUES



X509_sign(), X509_sign_ctx(), X509_REQ_sign(), X509_REQ_sign_ctx(),

X509_CRL_sign() and X509_CRL_sign_ctx() return 1 for success and 0

for failure.

X509_CRL_sign() and X509_CRL_sign_ctx() return the size of the signature

in bytes for success and zero for failure.



X509_verify(), X509_REQ_verify() and X509_CRL_verify() return 1 if the

signature is valid and 0 if the signature check fails. If the signature

doc/crypto/crypto.pod

+3 −39
Original line number Diff line number Diff line
@@ -21,46 +21,10 @@ 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.

hash functions, cryptographic pseudo-random number generator, and

various utilities.



=over 4



=item SYMMETRIC CIPHERS



L<blowfish(3)>, L<cast(3)>, L<des(3)>,

L<idea(3)>, L<rc2(3)>, L<rc4(3)>, L<rc5(3)> 



=item PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT



L<dsa(3)>, L<dh(3)>, L<ec(3)>, L<rsa(3)>



=item CERTIFICATES



L<x509(3)>, L<x509v3(3)>



=item AUTHENTICATION CODES, HASH FUNCTIONS



L<hmac(3)>, L<md2(3)>, L<md4(3)>,

L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>,

L<sha(3)>



=item AUXILIARY FUNCTIONS



L<err(3)>, L<threads(3)>, L<rand(3)>,

L<OPENSSL_VERSION_NUMBER(3)>



=item INPUT/OUTPUT, DATA ENCODING



L<asn1(3)>, L<bio(3)>, L<evp(3)>, L<pem(3)>,

L<pkcs7(3)>, L<pkcs12(3)> 



=item UTILITY FUNCTIONS



L<bn(3)>, L<buffer(3)>, L<lhash(3)>,

L<stack(3)>,

L<txt_db(3)> 



=back

See the individual manual pages for details.



=head1 NOTES

doc/crypto/pem.pod

+117 −162
Original line number Diff line number Diff line
@@ -22,9 +22,7 @@ PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, 
PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW,

PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL,

PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7,

PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE,

PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE,

PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines

PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines



=head1 SYNOPSIS
@@ -32,14 +30,11 @@ PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines 


 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);
@@ -47,130 +42,93 @@ PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines 
 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,
@@ -181,25 +139,10 @@ PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines 
 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
@@ -288,9 +231,6 @@ 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.
@@ -354,81 +294,62 @@ Read a certificate in PEM format from a BIO: 


 X509 *x;

 x = PEM_read_bio_X509(bp, NULL, 0, NULL);

 if (x == NULL)

	{

 if (x == NULL) {

     /* Error */

 }



Alternative method:



 X509 *x = NULL;

 if (!PEM_read_bio_X509(bp, &x, 0, 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))

	{

 if (!PEM_write_bio_X509(bp, x)) {

     /* 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))

	{

 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)

	{

 if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) {

     /* 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)

	{

 if (key == NULL) {

     /* Error */

 }



Skeleton pass phrase callback:



 int pass_cb(char *buf, int size, int rwflag, void *u);

 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);

     printf("Enter pass phrase for \"%s\"\n", (char *)u); 



     /* get pass phrase, length 'len' into 'tmp' */

     tmp = "hello";

     len = strlen(tmp);

     if (len <= 0)

         return 0;



	if (len <= 0) return 0;

	/* if too long, truncate */

	if (len > size) len = size;

     if (len > size)

         len = size;

     memcpy(buf, tmp, len);

     return len;

 }
@@ -456,7 +377,7 @@ which is an uninitialised pointer. 


=head1 PEM ENCRYPTION FORMAT



This old B<PrivateKey> routines use a non standard technique for encryption.

These old B<PrivateKey> routines use a non standard technique for encryption.



The private key (or other data) takes the following form:
@@ -467,15 +388,43 @@ The private key (or other data) takes the following form: 
 ...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 line beginning with I<Proc-Type> contains the version and the

protection on the encapsulated data. The line beginning I<DEK-Info>

contains two comma separated values: the encryption algorithm name as

used by EVP_get_cipherbyname() and an initialization vector used by the

cipher encoded as a set of hexadecimal digits. After those two lines is

the base64-encoded encrypted data.



The encryption key is derived using EVP_BytesToKey(). The cipher's

initialization vector is passed to EVP_BytesToKey() as the B<salt>

parameter. Internally, B<PKCS5_SALT_LEN> bytes of the salt are used

(regardless of the size of the initialization vector). The user's

password is passed to to EVP_BytesToKey() using the B<data> and B<datal>

parameters. Finally, the library uses an iteration count of 1 for

EVP_BytesToKey().



he B<key> derived by EVP_BytesToKey() along with the original initialization

vector is then used to decrypt the encrypted data. The B<iv> produced by

EVP_BytesToKey() is not utilized or needed, and NULL should be passed to

the function.



The pseudo code to derive the key would look similar to:



 EVP_CIPHER* cipher = EVP_des_ede3_cbc();

 EVP_MD* md = EVP_md5();



 unsigned int nkey = EVP_CIPHER_key_length(cipher);

 unsigned int niv = EVP_CIPHER_iv_length(cipher);

 unsigned char key[nkey];

 unsigned char iv[niv];



 memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv);

 rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/);

 if (rc != nkey) {

     /* Error */

 }



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().

 /* On success, use key and iv to initialize the cipher */



=head1 BUGS
@@ -498,6 +447,12 @@ if an error occurred. 


The write routines return 1 for success or 0 for failure.



=head1 HISTORY



The old Netscape certificate sequences were no longer documented

in OpenSSL 1.1; applications should use the PKCS7 standard instead

as they will be formally deprecated in a future releases.



=head1 SEE ALSO



L<EVP_get_cipherbyname(3)|EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)|EVP_BytesToKey(3)>
 
L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)>