Various doc fixes.
authorRich Salz <rsalz@akamai.com>
Thu, 27 Aug 2015 16:28:08 +0000 (12:28 -0400)
committerRich Salz <rsalz@openssl.org>
Thu, 27 Aug 2015 18:27:28 +0000 (14:27 -0400)
Make all mention of digest algorithm use "any supported algorithm"

RT2071, some new manpages from Victor B. Wagner <vitus@cryptocom.ru>:
    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 <sdaoden@yandex.com>)

RT3678:
    Some clarifications to BIO_new_pair
    (Devchandra L Meetei <dlmeetei@gmail.com>)

RT3787:
    Fix some EVP_ function return values
    (Laetitia Baudoin <lbaudoin@google.com>)

Reviewed-by: Tim Hudson <tjh@openssl.org>
18 files changed:
doc/apps/ca.pod
doc/apps/dgst.pod
doc/apps/enc.pod
doc/apps/ocsp.pod
doc/apps/openssl.pod
doc/apps/req.pod
doc/apps/ts.pod
doc/apps/x509.pod
doc/crypto/BIO_s_accept.pod
doc/crypto/BIO_s_bio.pod
doc/crypto/EVP_DigestVerifyInit.pod
doc/crypto/EVP_EncryptInit.pod
doc/crypto/RSA_sign.pod
doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod
doc/crypto/X509_LOOKUP_hash_dir.pod [new file with mode: 0644]
doc/crypto/X509_check_ca.pod [new file with mode: 0644]
doc/crypto/X509_check_issued.pod [new file with mode: 0644]
doc/crypto/crypto.pod

index be0153a..3a3d1b6 100644 (file)
@@ -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>
 
index 96d3cc0..1b1a7e1 100644 (file)
@@ -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.
index 1d25cf3..26e678c 100644 (file)
@@ -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
index a9b29b0..2566966 100644 (file)
@@ -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.
 
 =back
 
index d996eda..30ea9bd 100644 (file)
@@ -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.)
 
 =head2 STANDARD COMMANDS
 
index 3cbabb7..46bbfe6 100644 (file)
@@ -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</type0=value0/type1=value1/type2=...>,
-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>
 
index ff086d8..7a55b61 100644 (file)
@@ -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<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
index 0c6aaef..a06393d 100644 (file)
@@ -55,7 +55,7 @@ B<openssl> B<x509>
 [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<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>
 
index 8a23d42..80a8348 100644 (file)
@@ -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<BIO_BIND> flags, or -1 on failure.
+
+BIO_new_accept() returns a BIO or NULL on error.
 
 =head1 EXAMPLE
 
index 998796b..0daa518 100644 (file)
@@ -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 */
index 2068ce7..44d3cdb 100644 (file)
@@ -34,8 +34,7 @@ B<sig> of length B<siglen>.
 =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
index 4a31686..9a1bdef 100644 (file)
@@ -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.
 
 =head1 CIPHER LISTING
 
index 4e98925..a526eaf 100644 (file)
@@ -26,8 +26,8 @@ See L<RSA_private_encrypt(3)> for lower-level
 operations.
 
 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>,
+B<m>.
+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.
 
 =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<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<ERR_get_error(3)>,
 L<rsa(3)>, L<RSA_private_encrypt(3)>,
 L<RSA_public_decrypt(3)> 
 
index f505ddb..7b9ecfc 100644 (file)
@@ -47,7 +47,7 @@ These functions serve no recognizable purpose.
 
 =head1 SEE ALSO
 
-L<ERR_get_error(3)>, L<objects(3)>,
+L<ERR_get_error(3)>,
 L<rand(3)>, L<rsa(3)>, L<RSA_sign(3)>,
 L<RSA_verify(3)>
 
diff --git a/doc/crypto/X509_LOOKUP_hash_dir.pod b/doc/crypto/X509_LOOKUP_hash_dir.pod
new file mode 100644 (file)
index 0000000..680a9fd
--- /dev/null
@@ -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 <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);
+
+=head1 DESCRIPTION
+
+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
+L<SSL_CTX_load_verify_locations(3)>
+functions.
+
+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
+B<X509_load_cert_file>.
+
+Constant B<FILETYPE_DEFAULT> with NULL filename causes these functions
+to load default certificate store file (see
+L<X509_STORE_set_default_paths>.
+
+
+Functions return number of objects loaded from file or 0 in case of
+error. 
+
+Both methods support adding several certificate locations into one
+B<X509_STORE>.
+
+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.
+
+
+=head2 HASHED DIR METHOD
+
+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)>,
+L<X509_STORE_load_locations(3)>,
+L<X609_store_add_lookup(3)>,
+L<SSL_CTX_load_verify_locations(3)>,
+
+=cut
+
diff --git a/doc/crypto/X509_check_ca.pod b/doc/crypto/X509_check_ca.pod
new file mode 100644 (file)
index 0000000..87b6c26
--- /dev/null
@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+X509_check_ca - check if given certificate is CA certificate
+
+=head1 SYNOPSIS
+
+   #include <openssl/x509v3.h>
+
+   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<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
+
+L<X509_verify_cert(3)>,
+L<X509_check_issued(3)>,
+L<X509_check_purpose(3)>
+
+=cut
diff --git a/doc/crypto/X509_check_issued.pod b/doc/crypto/X509_check_issued.pod
new file mode 100644 (file)
index 0000000..0830e82
--- /dev/null
@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+X509_check_issued - checks if certificate is issued by another
+certificate
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509v3.h>
+
+ int X509_check_issued(X509 *issuer, X509 *subject);
+
+
+=head1 DESCRIPTION
+
+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
+I<issuer>.
+
+=head1 RETURN VALUE
+
+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
+
+L<X509_verify_cert(3)>,
+L<X509_check_ca(3)>,
+L<verify(1)>
+
+=cut
index 45887a6..aad75af 100644 (file)
@@ -57,7 +57,7 @@ L<pkcs7(3)>, L<pkcs12(3)>
 =item UTILITY FUNCTIONS
 
 L<bn(3)>, L<buffer(3)>, L<lhash(3)>,
-L<objects(3)>, L<stack(3)>,
+L<stack(3)>,
 L<txt_db(3)> 
 
 =back