[openssl-commits] [openssl] master update

Rich Salz rsalz at openssl.org
Thu Aug 27 18:28:02 UTC 2015

The branch master has been updated
       via  c03726ca4153fca8d66185837008aa078969d386 (commit)
      from  ad775e04f6dab51b7f929b54f5aa3c2393f957c5 (commit)

- Log -----------------------------------------------------------------
commit c03726ca4153fca8d66185837008aa078969d386
Author: Rich Salz <rsalz at akamai.com>
Date:   Thu Aug 27 12:28:08 2015 -0400

    Various doc fixes.
    Make all mention of digest algorithm use "any supported algorithm"
    RT2071, some new manpages from Victor B. Wagner <vitus at cryptocom.ru>:
    RT 1600:
        Remove references to non-existant objects(3)
        Add RETURN VALUES to BIO_do_accept page.
        RSA_sign Can return values other than 0 on failure.
        Fix AES CBC aliases (Steffen Nurpmeso <sdaoden at yandex.com>)
        Some clarifications to BIO_new_pair
        (Devchandra L Meetei <dlmeetei at gmail.com>)
        Fix some EVP_ function return values
        (Laetitia Baudoin <lbaudoin at google.com>)
    Reviewed-by: Tim Hudson <tjh at openssl.org>


Summary of changes:
 doc/apps/ca.pod                           |   5 +-
 doc/apps/dgst.pod                         |   4 ++
 doc/apps/enc.pod                          |   2 +-
 doc/apps/ocsp.pod                         |   6 +-
 doc/apps/openssl.pod                      |  16 ++---
 doc/apps/req.pod                          |  19 ++---
 doc/apps/ts.pod                           |   8 +--
 doc/apps/x509.pod                         |  15 ++--
 doc/crypto/BIO_s_accept.pod               |  10 ++-
 doc/crypto/BIO_s_bio.pod                  |  12 ++--
 doc/crypto/EVP_DigestVerifyInit.pod       |   3 +-
 doc/crypto/EVP_EncryptInit.pod            |   4 +-
 doc/crypto/RSA_sign.pod                   |  10 +--
 doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod |   2 +-
 doc/crypto/X509_LOOKUP_hash_dir.pod       | 114 ++++++++++++++++++++++++++++++
 doc/crypto/X509_check_ca.pod              |  36 ++++++++++
 doc/crypto/X509_check_issued.pod          |  36 ++++++++++
 doc/crypto/crypto.pod                     |   2 +-
 18 files changed, 253 insertions(+), 51 deletions(-)
 create mode 100644 doc/crypto/X509_LOOKUP_hash_dir.pod
 create mode 100644 doc/crypto/X509_check_ca.pod
 create mode 100644 doc/crypto/X509_check_issued.pod

diff --git a/doc/apps/ca.pod b/doc/apps/ca.pod
index be0153a..3a3d1b6 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<dgst> 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<default_md>
-the same as the B<-md> option. The message digest to use. Mandatory.
+the same as the B<-md> option. Mandatory.
 =item B<database>
diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod
index 96d3cc0..1b1a7e1 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<list digest-commands> 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 1d25cf3..26e678c 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 a9b29b0..2566966 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<notBefore> f
 is checked to see it is not older than B<age> 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<dgst> command can be used.
+The default is SHA-1.
diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod
index d996eda..30ea9bd 100644
--- a/doc/apps/openssl.pod
+++ b/doc/apps/openssl.pod
@@ -12,7 +12,7 @@ I<command>
 [ I<command_opts> ]
 [ I<command_args> ]
-B<openssl> [ B<list-standard-commands> | B<list-message-digest-commands> | B<list-cipher-commands> | B<list-cipher-algorithms> | B<list-message-digest-algorithms> | B<list-public-key-algorithms>]
+B<openssl> B<list> [ B<standard-commands> | B<digest-commands> | B<cipher-commands> | B<cipher-algorithms> | B<digest-algorithms> | B<public-key-algorithms>]
 B<openssl> B<no->I<XXX> [ I<arbitrary options> ]
@@ -41,20 +41,20 @@ 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
+The list parameters B<standard-commands>, B<digest-commands>,
+and B<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-commands B<list-cipher-algorithms> and
-B<list-message-digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as:
+The list parameters B<cipher-algorithms> and
+B<digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as:
  from => to
-The pseudo-command B<list-public-key-algorithms> lists all supported public
+The list parameter B<public-key-algorithms> lists all supported public
 key algorithms.
-The pseudo-command B<no->I<XXX> tests whether a command of the
+The 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
@@ -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<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.)
+B<list>, or B<no->I<XXX> itself.)
diff --git a/doc/apps/req.pod b/doc/apps/req.pod
index 3cbabb7..46bbfe6 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
-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<dgst> 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<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.
+This option specifies the digest algorithm to use.
+Any digest supported by the OpenSSL B<dgst> command can be used.
+If not present then MD5 is used.
+This option can be overridden on the command line.
 =item B<string_mask>
diff --git a/doc/apps/ts.pod b/doc/apps/ts.pod
index ff086d8..7a55b61 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<-policy> object_id]
@@ -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<dgst> command.
+The message digest to apply to the data file.
+Any digest supported by the OpenSSL B<dgst> 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 0c6aaef..a06393d 100644
--- a/doc/apps/x509.pod
+++ b/doc/apps/x509.pod
@@ -55,7 +55,7 @@ B<openssl> B<x509>
 [B<-certopt option>]
 [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
-=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<dgst> 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 8a23d42..80a8348 100644
--- a/doc/crypto/BIO_s_accept.pod
+++ b/doc/crypto/BIO_s_accept.pod
@@ -143,7 +143,15 @@ BIO_do_accept() are macros.
+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<BIO_BIND> 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 998796b..0daa518 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 2068ce7..44d3cdb 100644
--- a/doc/crypto/EVP_DigestVerifyInit.pod
+++ b/doc/crypto/EVP_DigestVerifyInit.pod
@@ -34,8 +34,7 @@ B<sig> of length B<siglen>.
 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 4a31686..9a1bdef 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<EVP_CIPHER> 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.
diff --git a/doc/crypto/RSA_sign.pod b/doc/crypto/RSA_sign.pod
index 4e98925..a526eaf 100644
--- a/doc/crypto/RSA_sign.pod
+++ b/doc/crypto/RSA_sign.pod
@@ -26,8 +26,8 @@ See L<RSA_private_encrypt(3)> for lower-level
 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)> for details. If B<type> is B<NID_md5_sha1>,
+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.
@@ -38,8 +38,8 @@ B<rsa> is the signer's public key.
-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<ERR_get_error(3)>.
@@ -54,7 +54,7 @@ SSL, PKCS #1 v2.0
 =head1 SEE ALSO
-L<ERR_get_error(3)>, L<objects(3)>,
 L<rsa(3)>, L<RSA_private_encrypt(3)>,
diff --git a/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod
index f505ddb..7b9ecfc 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<ERR_get_error(3)>, L<objects(3)>,
 L<rand(3)>, L<rsa(3)>, L<RSA_sign(3)>,
diff --git a/doc/crypto/X509_LOOKUP_hash_dir.pod b/doc/crypto/X509_LOOKUP_hash_dir.pod
new file mode 100644
index 0000000..680a9fd
--- /dev/null
+++ b/doc/crypto/X509_LOOKUP_hash_dir.pod
@@ -0,0 +1,114 @@
+=head1 NAME
+X509_LOOKUP_hash_dir, X509_LOOKUP_file,
+X509_load_cert_crl_file - Default OpenSSL certificate
+lookup methods
+=head1 SYNOPSIS
+  #include <openssl/x509_vfy.h>
+  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);
+B<X509_LOOKUP_hash_dir> and B<X509_LOOKUP_file> are two certificate
+lookup methods to use with B<X509_STORE>, 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<X509_STORE_load_locations(3)> or
+Internally loading of certificates and CRLs is implemented via functions
+B<X509_load_cert_crl_file>, B<X509_load_cert_file> and
+B<X509_load_crl_file>. These functions support parameter I<type>, which
+can be one of constants B<FILETYPE_PEM>, B<FILETYPE_ASN1> and
+B<FILETYPE_DEFAULT>. They load certificates and/or CRLs from specified
+file into memory cache of B<X509_STORE> objects which given B<ctx>
+parameter is associated with.
+Functions B<X509_load_cert_file> and
+B<X509_load_crl_file> 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<X509_load_cert_crl_file> with B<FILETYPE_ASN1> is equivalent to
+Constant B<FILETYPE_DEFAULT> with NULL filename causes these functions
+to load default certificate store file (see
+Functions return number of objects loaded from file or 0 in case of
+Both methods support adding several certificate locations into one
+This page documents certificate store formats used by these methods and
+caching policy.
+=head2  FILE METHOD
+B<X509_LOOKUP_file> 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.
+B<X509_LOOKUP_hash_dir> 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<X509_NAME_hash(3)>
+function of with option B<-hash> of L<x509(1)> or
+L<crl(1)> command.
+This hash value is appended by suffix .I<N> for certificates and
+B<.r>I<N> for CRLs where I<N> 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<c_rehash(1)> which creates
+symlinks with correct hashed names for all files with .pem suffix in the
+given directory.
+=head1 SEE ALSO
+L<pem(3)>, L<d2i_X509_bio(3)>,
diff --git a/doc/crypto/X509_check_ca.pod b/doc/crypto/X509_check_ca.pod
new file mode 100644
index 0000000..87b6c26
--- /dev/null
+++ b/doc/crypto/X509_check_ca.pod
@@ -0,0 +1,36 @@
+=head1 NAME
+X509_check_ca - check if given certificate is CA certificate
+=head1 SYNOPSIS
+   #include <openssl/x509v3.h>
+   int X509_check_ca(X509 *cert);
+This function checks if given certificate is CA certificate (can be used
+to sign other certificates).
+Function return 0, if it is not CA certificate, 1 if it is proper X509v3
+CA certificate with B<basicConstraints> extension CA:TRUE,
+3, if it is selfsigned X509 v1 certificate, 4, if it is certificate with
+B<keyUsage> extension with bit B<keyCertSign> set, but without
+B<basicConstraints>, 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
diff --git a/doc/crypto/X509_check_issued.pod b/doc/crypto/X509_check_issued.pod
new file mode 100644
index 0000000..0830e82
--- /dev/null
+++ b/doc/crypto/X509_check_issued.pod
@@ -0,0 +1,36 @@
+=head1 NAME
+X509_check_issued - checks if certificate is issued by another
+=head1 SYNOPSIS
+ #include <openssl/x509v3.h>
+ int X509_check_issued(X509 *issuer, X509 *subject);
+This function checks if certificate I<subject> was issued using CA
+certificate I<issuer>. This function takes into account not only 
+matching of issuer field of I<subject> with subject field of I<issuer>,
+but also compares B<authorityKeyIdentifier> extension of I<subject> with
+B<subjectKeyIdentifier> of I<issuer> if B<authorityKeyIdentifier>
+present in the I<subject> certificate and checks B<keyUsage> field of
+Function return B<X509_V_OK> if certificate I<subject> is issued by
+I<issuer> or some B<X509_V_ERR*> constant to indicate an error.
+=head1 SEE ALSO
diff --git a/doc/crypto/crypto.pod b/doc/crypto/crypto.pod
index 45887a6..aad75af 100644
--- a/doc/crypto/crypto.pod
+++ b/doc/crypto/crypto.pod
@@ -57,7 +57,7 @@ L<pkcs7(3)>, L<pkcs12(3)>
 L<bn(3)>, L<buffer(3)>, L<lhash(3)>,
-L<objects(3)>, L<stack(3)>,

More information about the openssl-commits mailing list