From: Rich Salz Date: Thu, 27 Aug 2015 16:28:08 +0000 (-0400) Subject: Various doc fixes. X-Git-Tag: OpenSSL_1_1_0-pre1~771 X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=c03726ca4153fca8d66185837008aa078969d386 Various doc fixes. Make all mention of digest algorithm use "any supported algorithm" RT2071, some new manpages from Victor B. Wagner : X509_LOOKUP_hash_dir.pod X509_check_ca.pod X509_check_issued.pod RT 1600: Remove references to non-existant objects(3) Add RETURN VALUES to BIO_do_accept page. RT1818: RSA_sign Can return values other than 0 on failure. RT3634: Fix AES CBC aliases (Steffen Nurpmeso ) RT3678: Some clarifications to BIO_new_pair (Devchandra L Meetei ) RT3787: Fix some EVP_ function return values (Laetitia Baudoin ) Reviewed-by: Tim Hudson --- diff --git a/doc/apps/ca.pod b/doc/apps/ca.pod index be0153a4b0..3a3d1b6eac 100644 --- a/doc/apps/ca.pod +++ b/doc/apps/ca.pod @@ -167,7 +167,8 @@ 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. +the message digest to use. +Any digest supported by the OpenSSL B command can be used. This option also applies to CRLs. =item B<-policy arg> @@ -406,7 +407,7 @@ least one of these must be present to generate a CRL. =item B -the same as the B<-md> option. The message digest to use. Mandatory. +the same as the B<-md> option. Mandatory. =item B diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod index 96d3cc0f75..1b1a7e17fd 100644 --- a/doc/apps/dgst.pod +++ b/doc/apps/dgst.pod @@ -185,6 +185,10 @@ To verify a signature: =head1 NOTES +The digest mechanisms that are available will depend on the options +used when building OpenSSL. +The B command can be used to list them. + New or agile applications should use probably use SHA-256. Other digests, particularly SHA-1 and MD5, are still widely used for interoperating with existing formats and protocols. diff --git a/doc/apps/enc.pod b/doc/apps/enc.pod index 1d25cf3dfc..26e678ca1b 100644 --- a/doc/apps/enc.pod +++ b/doc/apps/enc.pod @@ -282,7 +282,7 @@ authentication tag. 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] 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 diff --git a/doc/apps/ocsp.pod b/doc/apps/ocsp.pod index a9b29b0b49..256696665a 100644 --- a/doc/apps/ocsp.pod +++ b/doc/apps/ocsp.pod @@ -261,10 +261,12 @@ information is immediately available. In this case the age of the B f is checked to see it is not older than B seconds old. By default this additional check is not performed. -=item B<-md5|-sha1|-sha256|-ripemod160|...> +=item B<-[digest]> this option sets digest algorithm to use for certificate identification -in the OCSP request. By default SHA-1 is used. +in the OCSP request. +Any digest supported by the OpenSSL B command can be used. +The default is SHA-1. =back diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod index d996edaed8..30ea9bd67d 100644 --- a/doc/apps/openssl.pod +++ b/doc/apps/openssl.pod @@ -12,7 +12,7 @@ I [ I ] [ I ] -B [ B | B | B | B | B | B] +B B [ B | B | B | B | B | B] B BI [ I ] @@ -41,20 +41,20 @@ The B program provides a rich variety of commands (I in the SYNOPSIS above), each of which often has a wealth of options and arguments (I and I in the SYNOPSIS). -The pseudo-commands B, B, -and B output a list (one entry per line) of the names +The list parameters B, B, +and B 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 utility. -The pseudo-commands B and -B list all cipher and message digest names, one entry per line. Aliases are listed as: +The list parameters B and +B list all cipher and message digest names, one entry per line. Aliases are listed as: from => to -The pseudo-command B lists all supported public +The list parameter B lists all supported public key algorithms. -The pseudo-command BI tests whether a command of the +The command BI tests whether a command of the specified name is available. If no command named I exists, it returns 0 (success) and prints BI; otherwise it returns 1 and prints I. In both cases, the output goes to B and @@ -63,7 +63,7 @@ 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 program. (BI is not able to detect pseudo-commands such as B, -BI<...>B<-commands>, or BI itself.) +B, or BI itself.) =head2 STANDARD COMMANDS diff --git a/doc/apps/req.pod b/doc/apps/req.pod index 3cbabb7c30..46bbfe614e 100644 --- a/doc/apps/req.pod +++ b/doc/apps/req.pod @@ -127,13 +127,6 @@ 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<-subj arg> - -Replaces subject field of input request with specified data and outputs -modified request. The arg must be formatted as -I, -characters may be escaped by \ (backslash), no spaces are skipped. - =item B<-rand file(s)> a file or files containing random data used to seed the random number @@ -198,8 +191,9 @@ will not be encrypted. =item B<-[digest]> -this specifies the message digest to sign the request with (such as -B<-md5>, B<-sha1>). This overrides the digest algorithm specified in +this specifies the message digest to sign the request. +Any digest supported by the OpenSSL B command can be used. +This overrides the digest algorithm specified in the configuration file. Some public key algorithms may override this choice. For instance, DSA @@ -385,9 +379,10 @@ option. For compatibility B is an equivalent option. =item B -This option specifies the digest algorithm to use. Possible values -include B. If not present then MD5 is used. This -option can be overridden on the command line. +This option specifies the digest algorithm to use. +Any digest supported by the OpenSSL B command can be used. +If not present then MD5 is used. +This option can be overridden on the command line. =item B diff --git a/doc/apps/ts.pod b/doc/apps/ts.pod index ff086d8b2a..7a55b61643 100644 --- a/doc/apps/ts.pod +++ b/doc/apps/ts.pod @@ -12,7 +12,7 @@ B<-query> [B<-config> configfile] [B<-data> file_to_hash] [B<-digest> digest_bytes] -[B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...>] +[B<-[digest]>] [B<-policy> object_id] [B<-no_nonce>] [B<-cert>] @@ -124,10 +124,10 @@ per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or 1AF601...). The number of bytes must match the message digest algorithm in use. (Optional) -=item B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...> +=item B<-[digest]> -The message digest to apply to the data file, it supports all the message -digest algorithms that are supported by the openssl B command. +The message digest to apply to the data file. +Any digest supported by the OpenSSL B command can be used. The default is SHA-1. (Optional) =item B<-policy> object_id diff --git a/doc/apps/x509.pod b/doc/apps/x509.pod index 0c6aaeffa5..a06393defb 100644 --- a/doc/apps/x509.pod +++ b/doc/apps/x509.pod @@ -55,7 +55,7 @@ B B [B<-text>] [B<-certopt option>] [B<-C>] -[B<-md2|-md5|-sha1|-mdc2>] +[B<-[digest]>] [B<-clrext>] [B<-extfile filename>] [B<-extensions section>] @@ -101,12 +101,15 @@ if this option is not specified. This specifies the output filename to write to or standard output by default. -=item B<-md2|-md5|-sha1|-mdc2> +=item B<-[digest]> -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. +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. +Any digest supported by the OpenSSL B command can be used. +If not specified then SHA1 is used. +Note that if a DSA key is used for signing, then this flag is ignored +and SHA1 is used. =item B<-engine id> diff --git a/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod index 8a23d42657..80a83485ad 100644 --- a/doc/crypto/BIO_s_accept.pod +++ b/doc/crypto/BIO_s_accept.pod @@ -143,7 +143,15 @@ BIO_do_accept() are macros. =head1 RETURN VALUES -TBA +BIO_do_accept(), +BIO_set_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(), +and BIO_set_bind_mode(), return 1 for success and 0 or -1 for failure. + +BIO_get_accept_port() returns the port name or NULL on error. + +BIO_get_bind_mode() returns the set of B flags, or -1 on failure. + +BIO_new_accept() returns a BIO or NULL on error. =head1 EXAMPLE diff --git a/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod index 998796b138..0daa518a15 100644 --- a/doc/crypto/BIO_s_bio.pod +++ b/doc/crypto/BIO_s_bio.pod @@ -136,9 +136,9 @@ without having to go through the SSL-interface. BIO *internal_bio, *network_bio; ... - BIO_new_bio_pair(internal_bio, 0, network_bio, 0); + BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0); SSL_set_bio(ssl, internal_bio, internal_bio); - SSL_operations(); + SSL_operations(); //e.g SSL_read and SSL_write ... application | TLS-engine @@ -147,9 +147,13 @@ without having to go through the SSL-interface. | /\ || | || \/ | BIO-pair (internal_bio) - +----------< BIO-pair (network_bio) + | BIO-pair (network_bio) + | || /\ + | \/ || + +-----------< BIO_operations() | | - socket | + | | + socket ... SSL_free(ssl); /* implicitly frees internal_bio */ diff --git a/doc/crypto/EVP_DigestVerifyInit.pod b/doc/crypto/EVP_DigestVerifyInit.pod index 2068ce71ef..44d3cdbb0d 100644 --- a/doc/crypto/EVP_DigestVerifyInit.pod +++ b/doc/crypto/EVP_DigestVerifyInit.pod @@ -34,8 +34,7 @@ B of length B. =head1 RETURN VALUES EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0 -or a negative value for failure. In particular a return value of -2 indicates -the operation is not supported by the public key algorithm. +for failure. Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only indicates that the signature did not verify successfully (that is tbs did diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod index 4a31686c3d..9a1bdefcde 100644 --- a/doc/crypto/EVP_EncryptInit.pod +++ b/doc/crypto/EVP_EncryptInit.pod @@ -282,8 +282,8 @@ OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER. EVP_CIPHER_CTX_cipher() returns an B structure. -EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for -success or zero for failure. +EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater +than zero for success and zero or a negative number. =head1 CIPHER LISTING diff --git a/doc/crypto/RSA_sign.pod b/doc/crypto/RSA_sign.pod index 4e9892587c..a526eaf8b9 100644 --- a/doc/crypto/RSA_sign.pod +++ b/doc/crypto/RSA_sign.pod @@ -26,8 +26,8 @@ See L for lower-level operations. B denotes the message digest algorithm that was used to generate -B. It usually is one of B, B and B; -see L for details. If B is B, +B. +If B is B, an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding and no algorithm identifier) is created. @@ -38,8 +38,8 @@ B 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. +RSA_sign() returns 1 on success. +RSA_verify() returns 1 on successful verification. The error codes can be obtained by L. @@ -54,7 +54,7 @@ SSL, PKCS #1 v2.0 =head1 SEE ALSO -L, L, +L, L, L, L diff --git a/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod index f505ddb590..7b9ecfc714 100644 --- a/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod +++ b/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod @@ -47,7 +47,7 @@ These functions serve no recognizable purpose. =head1 SEE ALSO -L, L, +L, L, L, L, L diff --git a/doc/crypto/X509_LOOKUP_hash_dir.pod b/doc/crypto/X509_LOOKUP_hash_dir.pod new file mode 100644 index 0000000000..680a9fd043 --- /dev/null +++ b/doc/crypto/X509_LOOKUP_hash_dir.pod @@ -0,0 +1,114 @@ +=pod + +=head1 NAME + +X509_LOOKUP_hash_dir, X509_LOOKUP_file, +X509_load_cert_file, +X509_load_crl_file, +X509_load_cert_crl_file - Default OpenSSL certificate +lookup methods + +=head1 SYNOPSIS + + #include + + X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void); + X509_LOOKUP_METHOD *X509_LOOKUP_file(void); + + int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type); + int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type); + int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type); + +=head1 DESCRIPTION + +B and B are two certificate +lookup methods to use with B, provided by OpenSSL library. + +Users of the library typically do not need to create instanses of these +methods manually, they would be created automatically by +L or +L +functions. + +Internally loading of certificates and CRLs is implemented via functions +B, B and +B. These functions support parameter I, which +can be one of constants B, B and +B. They load certificates and/or CRLs from specified +file into memory cache of B objects which given B +parameter is associated with. + +Functions B and +B can load both PEM and DER formats depending of +type value. Because DER format cannot contain more than one certificate +or CRL object (while PEM can contain several concatenated PEM objects) +B with B is equivalent to +B. + +Constant B with NULL filename causes these functions +to load default certificate store file (see +L. + + +Functions return number of objects loaded from file or 0 in case of +error. + +Both methods support adding several certificate locations into one +B. + +This page documents certificate store formats used by these methods and +caching policy. + +=head2 FILE METHOD + +B method loads entire set of certificates and CRLs +into memory immediately when file name is passed to it. + +File format is ASCII text which contains concatenated PEM certificates +and CRLs. + +This method should be used by applications which work with limited set +of CAs. + + +=head2 HASHED DIR METHOD + +B is more sophisticated method, which loads +certificates and CRLs on demand, but caches them in the memory once they +are loaded. However, since OpenSSL 1.0.0beta1 it checks for newer CRLs +upon each lookup, so if newer CRL would appear in the directory, it +would be loaded. + +Directory should contain each certificate and CRL in the separate file +in the PEM format, with file name derived from certificate subject (or CRL +issuer) hash, as returned by L +function of with option B<-hash> of L or +L command. + +This hash value is appended by suffix .I for certificates and +B<.r>I for CRLs where I is sequentual +number among certificates with same hash value, so it is possible to +have in the store several certificates with same subject or several CRLs +with same issuer (and, for example, different validity period). + +When checking for new CRLs once one CRL for given hash value is loaded, +hash_dir lookup method checks only for certificates with sequentual +number greater than one of already cached CRL. + +Note that hash algorithm used for subject hashing is changed in OpenSSL +1.0, so all certificate stores have to be rehashed upon transitopn from +0.9.8 to 1.0.0. + +OpenSSL includes utility L which creates +symlinks with correct hashed names for all files with .pem suffix in the +given directory. + +=head1 SEE ALSO + +L, L, +L, +L, +L, + +=cut + diff --git a/doc/crypto/X509_check_ca.pod b/doc/crypto/X509_check_ca.pod new file mode 100644 index 0000000000..87b6c26d55 --- /dev/null +++ b/doc/crypto/X509_check_ca.pod @@ -0,0 +1,36 @@ +=pod + +=head1 NAME + +X509_check_ca - check if given certificate is CA certificate + +=head1 SYNOPSIS + + #include + + int X509_check_ca(X509 *cert); + +=head1 DESCRIPTION + +This function checks if given certificate is CA certificate (can be used +to sign other certificates). + +=head1 RETURN VALUE + +Function return 0, if it is not CA certificate, 1 if it is proper X509v3 +CA certificate with B extension CA:TRUE, +3, if it is selfsigned X509 v1 certificate, 4, if it is certificate with +B extension with bit B set, but without +B, and 5 if it has outdated Netscape Certificate Type +extension telling that it is CA certificate. + +Actually, any non-zero value means that this certificate could have been +used to sign other certificates. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/crypto/X509_check_issued.pod b/doc/crypto/X509_check_issued.pod new file mode 100644 index 0000000000..0830e82d70 --- /dev/null +++ b/doc/crypto/X509_check_issued.pod @@ -0,0 +1,36 @@ +=pod + +=head1 NAME + +X509_check_issued - checks if certificate is issued by another +certificate + +=head1 SYNOPSIS + + #include + + int X509_check_issued(X509 *issuer, X509 *subject); + + +=head1 DESCRIPTION + +This function checks if certificate I was issued using CA +certificate I. This function takes into account not only +matching of issuer field of I with subject field of I, +but also compares B extension of I with +B of I if B +present in the I certificate and checks B field of +I. + +=head1 RETURN VALUE + +Function return B if certificate I is issued by +I or some B constant to indicate an error. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/crypto/crypto.pod b/doc/crypto/crypto.pod index 45887a69af..aad75af0df 100644 --- a/doc/crypto/crypto.pod +++ b/doc/crypto/crypto.pod @@ -57,7 +57,7 @@ L, L =item UTILITY FUNCTIONS L, L, L, -L, L, +L, L =back