=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>
=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>
=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.
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
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
[ 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> ]
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
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
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
=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
=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>
[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>]
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
[B<-text>]
[B<-certopt option>]
[B<-C>]
-[B<-md2|-md5|-sha1|-mdc2>]
+[B<-[digest]>]
[B<-clrext>]
[B<-extfile filename>]
[B<-extensions section>]
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>
=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
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
| /\ ||
| || \/
| BIO-pair (internal_bio)
- +----------< BIO-pair (network_bio)
+ | BIO-pair (network_bio)
+ | || /\
+ | \/ ||
+ +-----------< BIO_operations()
| |
- socket |
+ | |
+ socket
...
SSL_free(ssl); /* implicitly frees internal_bio */
=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
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
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.
=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)>.
=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)>
=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)>
--- /dev/null
+=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
+
--- /dev/null
+=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
--- /dev/null
+=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
=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
projects / oweals / openssl.git / commitdiff