path: root/doc
diff options
Diffstat (limited to 'doc')
12 files changed, 310 insertions, 40 deletions
diff --git a/doc/apps/ciphers.pod b/doc/apps/ciphers.pod
index 6086d0a7154f..0aa1bad111c5 100644
--- a/doc/apps/ciphers.pod
+++ b/doc/apps/ciphers.pod
@@ -109,8 +109,8 @@ The following is a list of all permitted cipher strings and their meanings.
=item B<DEFAULT>
-the default cipher list. This is determined at compile time and, as of OpenSSL
-1.0.0, is normally B<ALL:!aNULL:!eNULL>. This must be the first cipher string
+the default cipher list. This is determined at compile time and
+is normally B<ALL:!EXPORT:!aNULL:!eNULL:!SSLv2>. This must be the firstcipher string
diff --git a/doc/apps/config.pod b/doc/apps/config.pod
index 25c5381b9d6b..d5cce54f44a8 100644
--- a/doc/apps/config.pod
+++ b/doc/apps/config.pod
@@ -89,8 +89,7 @@ section containing configuration module specific information. E.g.
... engine stuff here ...
-Currently there are two configuration modules. One for ASN1 objects another
-for ENGINE configuration.
+The features of each configuration module are described below.
@@ -191,6 +190,25 @@ For example:
# Supply all default algorithms
default_algorithms = ALL
+This modules has the name B<alg_section> which points to a section containing
+algorithm commands.
+Currently the only algorithm command supported is B<fips_mode> whose
+value should be a boolean string such as B<on> or B<off>. If the value is
+B<on> this attempt to enter FIPS mode. If the call fails or the library is
+not FIPS capable then an error occurs.
+For example:
+ alg_section = evp_settings
+ [evp_settings]
+ fips_mode = on
=head1 NOTES
If a configuration file attempts to expand a variable that doesn't exist
diff --git a/doc/apps/ocsp.pod b/doc/apps/ocsp.pod
index 38f026afc1b6..2372b373cdc1 100644
--- a/doc/apps/ocsp.pod
+++ b/doc/apps/ocsp.pod
@@ -40,6 +40,7 @@ B<openssl> B<ocsp>
[B<-port num>]
[B<-index file>]
[B<-CA file>]
@@ -189,6 +190,10 @@ testing purposes.
do not use certificates in the response as additional untrusted CA
+=item B<-no_explicit>
+do not explicitly trust the root CA if it is set to be trusted for OCSP signing.
=item B<-no_cert_checks>
don't perform any additional checks on the OCSP response signers certificate.
@@ -301,8 +306,9 @@ CA certificate in the request. If there is a match and the OCSPSigning
extended key usage is present in the OCSP responder certificate then the
OCSP verify succeeds.
-Otherwise the root CA of the OCSP responders CA is checked to see if it
-is trusted for OCSP signing. If it is the OCSP verify succeeds.
+Otherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders
+CA is checked to see if it is trusted for OCSP signing. If it is the OCSP
+verify succeeds.
If none of these checks is successful then the OCSP verify fails.
diff --git a/doc/crypto/CMS_get0_type.pod b/doc/crypto/CMS_get0_type.pod
index 8ff1c3115cd4..3ed92bdbbe93 100644
--- a/doc/crypto/CMS_get0_type.pod
+++ b/doc/crypto/CMS_get0_type.pod
@@ -2,7 +2,7 @@
=head1 NAME
- CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType - get and set CMS content types
+ CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content
@@ -11,6 +11,7 @@
const ASN1_OBJECT *CMS_get0_type(CMS_ContentInfo *cms);
int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);
const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);
+ ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms);
@@ -26,11 +27,15 @@ undefined.
ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded
content type.
+CMS_get0_content() returns a pointer to the B<ASN1_OCTET_STRING> pointer
+containing the embedded content.
=head1 NOTES
-As the B<0> implies CMS_get0_type() and CMS_get0_eContentType() return internal
-pointers which should B<not> be freed up. CMS_set1_eContentType() copies the
-supplied OID and it B<should> be freed up after use.
+As the B<0> implies CMS_get0_type(), CMS_get0_eContentType() and
+CMS_get0_content() return internal pointers which should B<not> be freed up.
+CMS_set1_eContentType() copies the supplied OID and it B<should> be freed up
+after use.
The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value
using OBJ_obj2nid(). For the currently supported content types the following
@@ -43,6 +48,15 @@ values are returned:
+The return value of CMS_get0_content() is a pointer to the B<ASN1_OCTET_STRING>
+content pointer. That means that for example:
+ ASN1_OCTET_STRING **pconf = CMS_get0_content(cms);
+B<*pconf> could be NULL if there is no embedded content. Applications can
+access, modify or create the embedded content in a B<CMS_ContentInfo> structure
+using this function. Applications usually will not need to modify the
+embedded content as it is normally set by higher level functions.
diff --git a/doc/crypto/CONF_modules_load_file.pod b/doc/crypto/CONF_modules_load_file.pod
index 0c4d926858fb..cc0b537b8ea5 100644
--- a/doc/crypto/CONF_modules_load_file.pod
+++ b/doc/crypto/CONF_modules_load_file.pod
@@ -9,9 +9,9 @@
#include <openssl/conf.h>
int CONF_modules_load_file(const char *filename, const char *appname,
- unsigned long flags);
+ unsigned long flags);
int CONF_modules_load(const CONF *cnf, const char *appname,
- unsigned long flags);
+ unsigned long flags);
@@ -22,7 +22,7 @@ NULL the standard OpenSSL application name B<openssl_conf> is used.
The behaviour can be cutomized using B<flags>.
CONF_modules_load() is idential to CONF_modules_load_file() except it
-read configuration information from B<cnf>.
+reads configuration information from B<cnf>.
=head1 NOTES
@@ -30,7 +30,7 @@ The following B<flags> are currently recognized:
B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual
configuration modules are ignored. If not set the first module error is
-considered fatal and no further modules are loads.
+considered fatal and no further modules are loaded.
Normally any modules errors will add error information to the error queue. If
B<CONF_MFLAGS_SILENT> is set no error information is added.
@@ -42,7 +42,84 @@ B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file()
ignore missing configuration files. Normally a missing configuration file
return an error.
+B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the
+default section pointed to by B<openssl_conf> if B<appname> does not exist.
+Applications should call these functions after loading builtin modules using
+OPENSSL_load_builtin_modules(), any ENGINEs for example using
+ENGINE_load_builtin_engines(), any algorithms for example
+OPENSSL_add_all_algorithms() and (if the application uses libssl)
+By using CONF_modules_load_file() with appropriate flags an application can
+customise application configuration to best suit its needs. In some cases the
+use of a configuration file is optional and its absence is not an error: in
+this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set.
+Errors during configuration may also be handled differently by different
+applications. For example in some cases an error may simply print out a warning
+message and the application continue. In other cases an application might
+consider a configuration file error as fatal and exit immediately.
+Applications can use the CONF_modules_load() function if they wish to load a
+configuration file themselves and have finer control over how errors are
+=head1 EXAMPLES
+Load a configuration file and print out any errors and exit (missing file
+considered fatal):
+ if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
+ fprintf(stderr, "FATAL: error loading configuration file\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+Load default configuration file using the section indicated by "myapp",
+tolerate missing files, but exit on other errors:
+ if (CONF_modules_load_file(NULL, "myapp",
+ fprintf(stderr, "FATAL: error loading configuration file\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+Load custom configuration file and section, only print warnings on error,
+missing configuration file ignored:
+ if (CONF_modules_load_file("/something/app.cnf", "myapp",
+ fprintf(stderr, "WARNING: error loading configuration file\n");
+ ERR_print_errors_fp(stderr);
+ }
+Load and parse configuration file manually, custom error handling:
+ FILE *fp;
+ CONF *cnf = NULL;
+ long eline;
+ fp = fopen("/somepath/app.cnf", "r");
+ if (fp == NULL) {
+ fprintf(stderr, "Error opening configuration file\n");
+ /* Other missing configuration file behaviour */
+ } else {
+ cnf = NCONF_new(NULL);
+ if (NCONF_load_fp(cnf, fp, &eline) == 0) {
+ fprintf(stderr, "Error on line %ld of configuration file\n", eline);
+ ERR_print_errors_fp(stderr);
+ /* Other malformed configuration file behaviour */
+ } else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
+ fprintf(stderr, "Error configuring application\n");
+ ERR_print_errors_fp(stderr);
+ /* Other configuration error behaviour */
+ }
+ fclose(fp);
+ NCONF_free(cnf);
+ }
These functions return 1 for success and a zero or negative value for
failure. If module errors are not ignored the return code will reflect the
diff --git a/doc/crypto/OPENSSL_config.pod b/doc/crypto/OPENSSL_config.pod
index 888de88f6bbf..5096faca04fc 100644
--- a/doc/crypto/OPENSSL_config.pod
+++ b/doc/crypto/OPENSSL_config.pod
@@ -15,31 +15,24 @@ OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions
OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf>
configuration file name using B<config_name>. If B<config_name> is NULL then
-the default name B<openssl_conf> will be used. Any errors are ignored. Further
-calls to OPENSSL_config() will have no effect. The configuration file format
-is documented in the L<conf(5)|conf(5)> manual page.
+the file specified in the environment variable B<OPENSSL_CONF> will be used,
+and if that is not set then a system default location is used.
+Errors are silently ignored.
+Multiple calls have no effect.
OPENSSL_no_config() disables configuration. If called before OPENSSL_config()
no configuration takes place.
=head1 NOTES
-It is B<strongly> recommended that B<all> new applications call OPENSSL_config()
-or the more sophisticated functions such as CONF_modules_load() during
-initialization (that is before starting any threads). By doing this
-an application does not need to keep track of all configuration options
-and some new functionality can be supported automatically.
-It is also possible to automatically call OPENSSL_config() when an application
-calls OPENSSL_add_all_algorithms() by compiling an application with the
-preprocessor symbol B<OPENSSL_LOAD_CONF> #define'd. In this way configuration
-can be added without source changes.
-The environment variable B<OPENSSL_CONF> can be set to specify the location
-of the configuration file.
-Currently ASN1 OBJECTs and ENGINE configuration can be performed future
-versions of OpenSSL will add new configuration options.
+The OPENSSL_config() function is designed to be a very simple "call it and
+forget it" function.
+It is however B<much> better than nothing. Applications which need finer
+control over their configuration functionality should use the configuration
+functions such as CONF_modules_load() directly. This function is deprecated
+and its use should be avoided.
+Applications should instead call CONF_modules_load() during
+initialization (that is before starting any threads).
There are several reasons why calling the OpenSSL configuration routines is
advisable. For example new ENGINE functionality was added to OpenSSL 0.9.7.
diff --git a/doc/crypto/d2i_CMS_ContentInfo.pod b/doc/crypto/d2i_CMS_ContentInfo.pod
new file mode 100644
index 000000000000..6ddb2f6d0583
--- /dev/null
+++ b/doc/crypto/d2i_CMS_ContentInfo.pod
@@ -0,0 +1,29 @@
+=head1 NAME
+d2i_CMS_ContentInfo, i2d_CMS_ContentInfo - CMS ContentInfo functions
+=head1 SYNOPSIS
+ #include <openssl/cms.h>
+ CMS_ContentInfo *d2i_CMS_ContentInfo(CMS_ContentInfo **a, unsigned char **pp, long length);
+ int i2d_CMS_ContentInfo(CMS_ContentInfo *a, unsigned char **pp);
+These functions decode and encode an CMS ContentInfo structure.
+Otherwise they behave in a similar way to d2i_X509() and i2d_X509()
+described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
+=head1 SEE ALSO
+=head1 HISTORY
+These functions were first added to OpenSSL 0.9.8
diff --git a/doc/crypto/d2i_ECPrivateKey.pod b/doc/crypto/d2i_ECPrivateKey.pod
new file mode 100644
index 000000000000..adeffe643c84
--- /dev/null
+++ b/doc/crypto/d2i_ECPrivateKey.pod
@@ -0,0 +1,67 @@
+=head1 NAME
+i2d_ECPrivateKey, d2i_ECPrivate_key - Encode and decode functions for saving and
+reading EC_KEY structures
+=head1 SYNOPSIS
+ #include <openssl/ec.h>
+ EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len);
+ int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out);
+ unsigned int EC_KEY_get_enc_flags(const EC_KEY *key);
+ void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags);
+The ECPrivateKey encode and decode routines encode and parse an
+B<EC_KEY> structure into a binary format (ASN.1 DER) and back again.
+These functions are similar to the d2i_X509() functions, and you should refer to
+that page for a detailed description (see L<d2i_X509(3)|d2i_X509(3)>).
+The format of the external representation of the public key written by
+i2d_ECPrivateKey (such as whether it is stored in a compressed form or not) is
+described by the point_conversion_form. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>
+for a description of point_conversion_form.
+When reading a private key encoded without an associated public key (e.g. if
+EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey generates
+the missing public key automatically. Private keys encoded without parameters
+(e.g. if EC_PKEY_NO_PARAMETERS has been used - see below) cannot be loaded using
+The functions EC_KEY_get_enc_flags and EC_KEY_set_enc_flags get and set the
+value of the encoding flags for the B<key>. There are two encoding flags
+currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags
+define the behaviour of how the B<key> is converted into ASN1 in a call to
+i2d_ECPrivateKey. If EC_PKEY_NO_PARAMETERS is set then the public parameters for
+the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is
+set then the public key is not encoded along with the private key.
+d2i_ECPrivateKey() returns a valid B<EC_KEY> structure or B<NULL> if an error
+occurs. The error code that can be obtained by
+i2d_ECPrivateKey() returns the number of bytes successfully encoded or a
+negative value if an error occurs. The error code can be obtained by
+EC_KEY_get_enc_flags returns the value of the current encoding flags for the
+=head1 SEE ALSO
+L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>,
+L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, L<EC_POINT_new(3)|EC_POINT_new(3)>,
diff --git a/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod
index 298ec54a4c3b..e3dc2381966b 100644
--- a/doc/crypto/d2i_X509.pod
+++ b/doc/crypto/d2i_X509.pod
@@ -28,8 +28,11 @@ successful a pointer to the B<X509> structure is returned. If an error
occurred then B<NULL> is returned. If B<px> is not B<NULL> then the
returned structure is written to B<*px>. If B<*px> is not B<NULL>
then it is assumed that B<*px> contains a valid B<X509>
-structure and an attempt is made to reuse it. If the call is
-successful B<*in> is incremented to the byte following the
+structure and an attempt is made to reuse it. This "reuse" capability is present
+for historical compatibility but its use is B<strongly discouraged> (see BUGS
+below, and the discussion in the RETURN VALUES section).
+If the call is successful B<*in> is incremented to the byte following the
parsed data.
i2d_X509() encodes the structure pointed to by B<x> into DER format.
@@ -210,7 +213,10 @@ always succeed.
d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure
or B<NULL> if an error occurs. The error code that can be obtained by
+L<ERR_get_error(3)|ERR_get_error(3)>. If the "reuse" capability has been used
+with a valid X509 structure being passed in via B<px> then the object is not
+freed in the event of error but may be in a potentially invalid or inconsistent
i2d_X509() returns the number of bytes successfully encoded or a negative
value if an error occurs. The error code can be obtained by
diff --git a/doc/ssl/SSL_CTX_set_read_ahead.pod b/doc/ssl/SSL_CTX_set_read_ahead.pod
new file mode 100644
index 000000000000..527164b0723f
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_read_ahead.pod
@@ -0,0 +1,51 @@
+=head1 NAME
+SSL_CTX_set_read_ahead, SSL_CTX_set_default_read_ahead, SSL_CTX_get_read_ahead,
+SSL_CTX_get_default_read_ahead, SSL_set_read_ahead, SSL_get_read_ahead
+- manage whether to read as many input bytes as possible
+=head1 SYNOPSIS
+ #include <openssl/ssl.h>
+ int SSL_get_read_ahead(const SSL *s);
+ void SSL_set_read_ahead(SSL *s, int yes);
+ #define SSL_CTX_get_default_read_ahead(ctx)
+ #define SSL_CTX_set_default_read_ahead(ctx,m)
+ #define SSL_CTX_get_read_ahead(ctx)
+ #define SSL_CTX_set_read_ahead(ctx,m)
+SSL_CTX_set_read_ahead() and SSL_set_read_ahead() set whether we should read as
+many input bytes as possible (for non-blocking reads) or not. For example if
+B<x> bytes are currently required by OpenSSL, but B<y> bytes are available from
+the underlying BIO (where B<y> > B<x>), then OpenSSL will read all B<y> bytes
+into its buffer (providing that the buffer is large enough) if reading ahead is
+on, or B<x> bytes otherwise. The parameter B<yes> or B<m> should be 0 to ensure
+reading ahead is off, or non zero otherwise.
+SSL_CTX_set_default_read_ahead is a synonym for SSL_CTX_set_read_ahead, and
+SSL_CTX_get_default_read_ahead is a synonym for SSL_CTX_get_read_ahead.
+SSL_CTX_get_read_ahead() and SSL_get_read_ahead() indicate whether reading
+ahead has been set or not.
+=head1 NOTES
+These functions have no impact when used with DTLS. The return values for
+SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS.
+SSL_get_read_ahead and SSL_CTX_get_read_ahead return 0 if reading ahead is off,
+and non zero otherwise.
+=head1 SEE ALSO
diff --git a/doc/ssl/SSL_pending.pod b/doc/ssl/SSL_pending.pod
index 43f2874e8b6a..9dd071b62567 100644
--- a/doc/ssl/SSL_pending.pod
+++ b/doc/ssl/SSL_pending.pod
@@ -29,8 +29,9 @@ The number of bytes pending is returned.
SSL_pending() takes into account only bytes from the TLS/SSL record
that is currently being processed (if any). If the B<SSL> object's
-I<read_ahead> flag is set, additional protocol bytes may have been
-read containing more TLS/SSL records; these are ignored by
+I<read_ahead> flag is set (see
+L<SSL_CTX_set_read_ahead(3)|SSL_CTX_set_read_ahead(3)>), additional protocol
+bytes may have been read containing more TLS/SSL records; these are ignored by
Up to OpenSSL 0.9.6, SSL_pending() does not check if the record type
@@ -38,6 +39,7 @@ of pending data is application data.
=head1 SEE ALSO
-L<SSL_read(3)|SSL_read(3)>, L<ssl(3)|ssl(3)>
+L<SSL_CTX_set_read_ahead(3)|SSL_CTX_set_read_ahead(3)>, L<ssl(3)|ssl(3)>
diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index 6d3ee24e4e47..660489a22243 100644
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -229,6 +229,8 @@ protocol context defined in the B<SSL_CTX> structure.
=item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
+=item void B<SSL_CTX_get_default_read_ahead>(SSL_CTX *ctx);
=item char *B<SSL_CTX_get_ex_data>(const SSL_CTX *s, int idx);
=item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
@@ -237,6 +239,8 @@ protocol context defined in the B<SSL_CTX> structure.
=item int B<SSL_CTX_get_quiet_shutdown>(const SSL_CTX *ctx);
+=item void B<SSL_CTX_get_read_ahead>(SSL_CTX *ctx);
=item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx);
=item long B<SSL_CTX_get_timeout>(const SSL_CTX *ctx);
@@ -325,6 +329,8 @@ protocol context defined in the B<SSL_CTX> structure.
=item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode);
+=item void B<SSL_CTX_set_read_ahead>(SSL_CTX *ctx, int m);
=item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode);
=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, const SSL_METHOD *meth);
@@ -703,6 +709,7 @@ L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>,