The branch master has been updated via 2b9bafe607421e394265dcbaad6234b4efee19e8 (commit) via c16aec524626a20e3187a3ad61a4898a1801177a (commit) from 713fc10f83a4d5cac4153a98374be8cac6af1771 (commit)
- Log ----------------------------------------------------------------- commit 2b9bafe607421e394265dcbaad6234b4efee19e8 Author: Rich Salz <rs...@akamai.com> Date: Sat Mar 28 12:51:05 2020 -0400 Rewrite man5/config.pod and related conf code cleanup The manpage is basically rewritten. Use consistent name/value terminology. Use consistent phraseology to refer to section pointers and lists of section pointers. Add more cross-references. Also found a bunch of trivial style things in conf_api.c while investigating how config works. Reviewed-by: Nicola Tuveri <nic....@gmail.com> Reviewed-by: Tomas Mraz <tm...@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/11431) commit c16aec524626a20e3187a3ad61a4898a1801177a Author: Rich Salz <rs...@akamai.com> Date: Sat Mar 28 12:50:49 2020 -0400 SSL_CTX_config.pod: Remove needless "NOTE" heading Reviewed-by: Nicola Tuveri <nic....@gmail.com> Reviewed-by: Tomas Mraz <tm...@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/11431) ----------------------------------------------------------------------- Summary of changes: crypto/conf/conf_api.c | 67 ++--- doc/man3/SSL_CTX_config.pod | 2 - doc/man5/config.pod | 696 +++++++++++++++++++------------------------- 3 files changed, 329 insertions(+), 436 deletions(-) diff --git a/crypto/conf/conf_api.c b/crypto/conf/conf_api.c index 4248de60e1..4c7349a305 100644 --- a/crypto/conf/conf_api.c +++ b/crypto/conf/conf_api.c @@ -19,30 +19,26 @@ static void value_free_hash(const CONF_VALUE *a, LHASH_OF(CONF_VALUE) *conf); static void value_free_stack_doall(CONF_VALUE *a); -/* Up until OpenSSL 0.9.5a, this was get_section */ CONF_VALUE *_CONF_get_section(const CONF *conf, const char *section) { - CONF_VALUE *v, vv; + CONF_VALUE vv; - if ((conf == NULL) || (section == NULL)) + if (conf == NULL || section == NULL) return NULL; vv.name = NULL; vv.section = (char *)section; - v = lh_CONF_VALUE_retrieve(conf->data, &vv); - return v; + return lh_CONF_VALUE_retrieve(conf->data, &vv); } -/* Up until OpenSSL 0.9.5a, this was CONF_get_section */ STACK_OF(CONF_VALUE) *_CONF_get_section_values(const CONF *conf, const char *section) { CONF_VALUE *v; v = _CONF_get_section(conf, section); - if (v != NULL) - return ((STACK_OF(CONF_VALUE) *)v->value); - else + if (v == NULL) return NULL; + return ((STACK_OF(CONF_VALUE) *)v->value); } int _CONF_add_string(CONF *conf, CONF_VALUE *section, CONF_VALUE *value) @@ -53,9 +49,8 @@ int _CONF_add_string(CONF *conf, CONF_VALUE *section, CONF_VALUE *value) ts = (STACK_OF(CONF_VALUE) *)section->value; value->section = section->section; - if (!sk_CONF_VALUE_push(ts, value)) { + if (!sk_CONF_VALUE_push(ts, value)) return 0; - } v = lh_CONF_VALUE_insert(conf->data, value); if (v != NULL) { @@ -75,28 +70,26 @@ char *_CONF_get_string(const CONF *conf, const char *section, if (name == NULL) return NULL; - if (conf != NULL) { - if (section != NULL) { - vv.name = (char *)name; - vv.section = (char *)section; - v = lh_CONF_VALUE_retrieve(conf->data, &vv); - if (v != NULL) - return v->value; - if (strcmp(section, "ENV") == 0) { - p = ossl_safe_getenv(name); - if (p != NULL) - return p; - } - } - vv.section = "default"; + if (conf == NULL) + return ossl_safe_getenv(name); + if (section != NULL) { vv.name = (char *)name; + vv.section = (char *)section; v = lh_CONF_VALUE_retrieve(conf->data, &vv); if (v != NULL) return v->value; - else - return NULL; - } else - return ossl_safe_getenv(name); + if (strcmp(section, "ENV") == 0) { + p = ossl_safe_getenv(name); + if (p != NULL) + return p; + } + } + vv.section = "default"; + vv.name = (char *)name; + v = lh_CONF_VALUE_retrieve(conf->data, &vv); + if (v == NULL) + return NULL; + return v->value; } static unsigned long conf_value_hash(const CONF_VALUE *v) @@ -110,24 +103,21 @@ static int conf_value_cmp(const CONF_VALUE *a, const CONF_VALUE *b) if (a->section != b->section) { i = strcmp(a->section, b->section); - if (i) + if (i != 0) return i; } - if ((a->name != NULL) && (b->name != NULL)) { - i = strcmp(a->name, b->name); - return i; - } else if (a->name == b->name) + if (a->name != NULL && b->name != NULL) + return strcmp(a->name, b->name); + if (a->name == b->name) return 0; - else - return ((a->name == NULL) ? -1 : 1); + return (a->name == NULL) ? -1 : 1; } int _CONF_new_data(CONF *conf) { - if (conf == NULL) { + if (conf == NULL) return 0; - } if (conf->data == NULL) { conf->data = lh_CONF_VALUE_new(conf_value_hash, conf_value_cmp); if (conf->data == NULL) @@ -185,7 +175,6 @@ static void value_free_stack_doall(CONF_VALUE *a) OPENSSL_free(a); } -/* Up until OpenSSL 0.9.5a, this was new_section */ CONF_VALUE *_CONF_new_section(CONF *conf, const char *section) { STACK_OF(CONF_VALUE) *sk = NULL; diff --git a/doc/man3/SSL_CTX_config.pod b/doc/man3/SSL_CTX_config.pod index 6cab5f9ffa..7aba58f826 100644 --- a/doc/man3/SSL_CTX_config.pod +++ b/doc/man3/SSL_CTX_config.pod @@ -16,8 +16,6 @@ SSL_CTX_config, SSL_config - configure SSL_CTX or SSL structure The functions SSL_CTX_config() and SSL_config() configure an B<SSL_CTX> or B<SSL> structure using the configuration B<name>. -=head1 NOTES - By calling SSL_CTX_config() or SSL_config() an application can perform many complex tasks based on the contents of the configuration file: greatly simplifying application configuration code. A degree of future proofing diff --git a/doc/man5/config.pod b/doc/man5/config.pod index 98b8cd3317..14b80e0b31 100644 --- a/doc/man5/config.pod +++ b/doc/man5/config.pod @@ -6,316 +6,259 @@ config - OpenSSL CONF library configuration files =head1 DESCRIPTION -The OpenSSL CONF library can be used to read configuration files. -It is used for the OpenSSL master configuration file B<openssl.cnf> -and in a few other places like B<SPKAC> files and certificate extension -files for the B<x509> utility. OpenSSL applications can also use the -CONF library for their own purposes. - -A configuration file is divided into a number of sections. Each section -starts with a line C<[section_name]> and ends when a new section is -started or end of file is reached. A section name can consist of -alphanumeric characters and underscores. The brackets are required. - -The first section of a configuration file is special and is referred -to as the B<default> section. This section is usually unnamed and spans from the -start of file until the first named section. When a name is being looked up -it is first looked up in a named section (if any) and then the -default section. +This page documents the syntax of OpenSSL configuration files, +as parsed by L<NCONF_load(3)> and related functions. +This format is used by many of the OpenSSL commands, and to +initialize the libraries when used by any application. -The environment is mapped onto a section called B<ENV>. +The first part describes the general syntax of the configuration +files, and subsequent sections describe the semantics of individual +modules. Other modules are described in L<fips_config(5)> and +L<x509v3_config(5)>. +The syntax for defining ASN.1 values is described in +L<ASN1_generate_nconf(3)>. -Comments can be included by preceding them with the B<#> character - -Other files can be included using the B<.include> directive followed -by a path. If the path points to a directory all files with -names ending with B<.cnf> or B<.conf> are included from the directory. -Recursive inclusion of directories from files in such directory is not -supported. That means the files in the included directory can also contain -B<.include> directives but only inclusion of regular files is supported -there. The inclusion of directories is not supported on systems without -POSIX IO support. - -It is strongly recommended to use absolute paths with the B<.include> -directive. Relative paths are evaluated based on the application current -working directory so unless the configuration file containing the -B<.include> directive is application specific the inclusion will not -work as expected. The environment variable B<OPENSSL_CONF_INCLUDE> can also be -used to specify the path to prepend to all .include paths. - -There can be optional B<=> character and whitespace characters between -B<.include> directive and the path which can be useful in cases the -configuration file needs to be loaded by old OpenSSL versions which do -not support the B<.include> syntax. They would bail out with error -if the B<=> character is not present but with it they just ignore -the include. - -Pragmas can be specified with the B<.pragma> directive. -See L</PRAGMAS> for more information. - -Each section in a configuration file consists of a number of name and -value pairs of the form B<name=value> - -The B<name> string can contain any alphanumeric characters as well as -a few punctuation symbols such as B<.> B<,> B<;> and B<_>. - -The B<value> string consists of the string following the B<=> character -until end of line with any leading and trailing white space removed. - -The value string undergoes variable expansion. This can be done by -including the form B<$var> or B<${var}>: this will substitute the value -of the named variable in the current section. It is also possible to -substitute a value from another section using the syntax B<$section::name> -or B<${section::name}>. By using the form B<$ENV::name> environment -variables can be substituted. It is also possible to assign values to -environment variables by using the name B<ENV::name>, this will work -if the program looks up environment variables using the B<CONF> library -instead of calling getenv() directly. The value string must not exceed 64k in -length after variable expansion. Otherwise an error will occur. - -It is possible to escape certain characters by using any kind of quote -or the B<\> character. By making the last character of a line a B<\> -a B<value> string can be spread across multiple lines. In addition -the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized. +=head1 SYNTAX -All expansion and escape rules as described above that apply to B<value> -also apply to the path of the B<.include> directive. +A configuration file is a series of lines. Blank lines, and whitespace +between the elements of a line, have no significance. A comment starts +with a B<#> character; the rest of the line is ignored. If the B<#> +is the first non-space character in a line, the entire line is ignored. -=head1 PRAGMAS +=head2 Directives -Pragmas can be used to change the behavior of the configuration file -parser, among others. Currently supported pragmas are: +Two directives can be used to control the parsing of configuration files: +B<.include> and B<.pragma>. -=over 4 +For compatibility with older versions of OpenSSL, an equal sign after the +directive will be ignored. Older versions will treat it as an assignment, +so care should be taken if the difference in semantics is important. -=item B<.pragma> B<dollarid>:I<value> - -I<value> can be one of: - -=over 4 +A file can include other files using the include syntax: -=item B<"on"> or B<"true"> + .include [=] pathname -this signifies that dollar signs are considered an identity character -from this point on and that variable expansion requires the use of -braces or parentheses. In other words, C<foo$bar> will be considered -a name instead of C<foo> followed by the expansion of the variable -C<bar>. -This is suitable for platforms where the dollar sign is commonly used -as part of names. +If B<pathname> is a simple filename, that file is included directly at +that point. Included files can have B<.include> statements that specify +other files. If B<pathname> is a directory, all files within that directory +that have a C<.cnf> or C<.conf> extension will be included. (This is only +available on systems with POSIX IO support.) Any sub-directories found +inside the B<pathname> are B<ignored>. Similarly, if a file is opened +while scanning a directory, and that file has an B<.include> directive +that specifies a directory, that is also ignored. -=item B<"off"> or B<"false"> +As a general rule, the B<pathname> should be an absolute path. Relative +paths are evaluated based on the current working directory, so unless the +file with the B<.include> directive is application-specific, the inclusion +will not work as expected. The environment variable B<OPENSSL_CONF_INCLUDE>, +if it exists, will be prepended to all B<.include> B<pathname>'s. -Turns this pragma off, i.e. C<foo$bar> will be interpreted as C<foo> -followed by the expansion of the variable C<bar>. +In these files, the dollar sign, B<$>, is used to reference a variable, as +described below. On some platforms, however, it is common to treat B<$> +as a regular character in symbol names. Supporting this behavior can be +done with the following directive: -=back - -By default, this pragma is turned off. - -=back - -=head1 OPENSSL LIBRARY CONFIGURATION + .pragma [=] dollarid:value -Applications can automatically configure certain -aspects of OpenSSL using the master OpenSSL configuration file, or optionally -an alternative configuration file. The B<openssl> utility includes this -functionality: any sub command uses the master OpenSSL configuration file -unless an option is used in the sub command to use an alternative configuration -file. - -To enable library configuration the default section needs to contain an -appropriate line which points to the main configuration section. The default -name is B<openssl_conf> which is used by the B<openssl> utility. Other -applications may use an alternative name such as B<myapplication_conf>. -All library configuration lines appear in the default section at the start -of the configuration file. - -The configuration section should consist of a set of name value pairs which -contain specific module configuration information. The B<name> represents -the name of the I<configuration module>. The meaning of the B<value> is -module specific: it may, for example, represent a further configuration -section containing configuration module specific information. E.g.: +Where B<value> is one of the following: - # This must be in the default section - openssl_conf = openssl_init - - [openssl_init] - - oid_section = new_oids - engines = engine_section - providers = provider_section - - [new_oids] - - ... new oids here ... - - [engine_section] - - ... engine stuff here ... +=over 4 - [provider_section] +=item B<off> or B<false> - ... provider stuff here ... +This is the default behavior. For example, C<foo$bar> is interpreted as +C<foo> followed by the expansion of the variable C<bar>. -The features of each configuration module are described below. +=item B<on> or B<true> -=head2 ASN1 Object Configuration Module +This specifies that dollar signs are part of the symbol name and +variable expansions must be specified using braces or parentheses. +For example, C<foo$bar> is treated as a single seven-character name. -This module has the name B<oid_section>. The value of this variable points -to a section containing name value pairs of OIDs: the name is the OID short -and long name, the value is the numerical form of the OID. Although some of -the B<openssl> utility sub commands already have their own ASN1 OBJECT section -functionality not all do. By using the ASN1 OBJECT configuration module -B<all> the B<openssl> utility sub commands can see the new objects as well -as any compliant applications. For example: - - [new_oids] +=back - some_new_oid = 1.2.3.4 - some_other_oid = 1.2.3.5 +=head2 Settings -It is also possible to set the value to the long name followed -by a comma and the numerical OID form. For example: +A configuration file is divided into a number of I<sections>. A section +begins with the section name in square brackets, and ends when a new +section starts, or at the end of the file. The section name can consist +of alphanumeric characters and underscores. +Whitespace between the name and the brackets is removed. - shortName = some object long name, 1.2.3.4 +The first section of a configuration file is special and is referred to +as the B<default> section. This section is usually unnamed and spans from +the start of file until the first named section. When a name is being +looked up, it is first looked up in the current or named section, +and then the default section if necessary. -=head2 Engine Configuration Module +The environment is mapped onto a section called B<ENV>. -This ENGINE configuration module has the name B<engines>. The value of this -variable points to a section containing further ENGINE configuration -information. +Within a section are a series of name/value assignments, described in more +detail below. As a reminder, the square brackets shown in this example +are required, not optional: + + [ section ] + name1 = This is value1 + name2 = Another value + ... + [ newsection ] + name1 = New value1 + name3 = Value 3 + +The B<name> can contain any alphanumeric characters as well as a few +punctuation symbols such as B<.> B<,> B<;> and B<_>. +Whitespace after the name and before the equal sign is ignored. + +If a name is repeated in the same section, then all but the last +value are ignored. In certain circumstances, such as with +Certificate DNs, the same field may occur multiple times. +In order to support this, commands like L<openssl-req(1)> ignore any +leading text that is preceeded with a period. For example: + + 1.OU = First OU + 2.OU = Second OU + +The B<value> consists of the string following the B<=> character until end +of line with any leading and trailing white space removed. + +The value string undergoes variable expansion. The text C<$var> or C<${var}> +inserts the value of the named variable from the current section. +To use a value from another section use C<$section::name> +or C<${section::name}>. +By using C<$ENV::name>, the value of the specified environment +variable will be substituted. + +Variables must be defined before their value is referenced, otherwise +an error is flagged and the file will not load. +This can be worked around by specifying a default value in the B<default> +section before the variable is used. + +Any name/value settings in an B<ENV> section are available +to the configuration file, but are not propagated to the environment. + +It is an error if the value ends up longer than 64k. + +It is possible to escape certain characters by using a single B<'> or +double B<"> quote around the value, or using a backslash B<\> before the +character, +By making the last character of a line a B<\> +a B<value> string can be spread across multiple lines. In addition +the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized. -The section pointed to by B<engines> is a table of engine names (though see -B<engine_id> below) and further sections containing configuration information -specific to each ENGINE. +The expansion and escape rules as described above that apply to B<value> +also apply to the pathname of the B<.include> directive. -Each ENGINE specific section is used to set default algorithms, load -dynamic, perform initialization and send ctrls. The actual operation performed -depends on the I<command> name which is the name of the name value pair. The -currently supported commands are listed below. +=head1 OPENSSL LIBRARY CONFIGURATION -For example: +The sections below use the informal term I<module> to refer to a part +of the OpenSSL functionality. This is not the same as the formal term +I<FIPS module>, for example. - [engine_section] +The OpenSSL configuration looks up the value of B<openssl_conf> +in the default section and takes that as the name of a section that specifies +how to configure any modules in the library. It is not an error to leave +any module in its default configuration. An application can specify a +different name by calling CONF_modules_load_file(), for example, directly. - # Configure ENGINE named "foo" - foo = foo_section - # Configure ENGINE named "bar" - bar = bar_section + # This must be in the default section + openssl_conf = openssl_init - [foo_section] - ... foo ENGINE specific commands ... + [openssl_init] + oid_section = oids + providers = providers + alg_section = evp_properties + ssl_conf = ssl_configuration + engines = engines - [bar_section] - ... "bar" ENGINE specific commands ... + [oids] + ... new oids here ... -The command B<engine_id> is used to give the ENGINE name. If used this -command must be first. For example: + [providers] + ... provider stuff here ... - [engine_section] - # This would normally handle an ENGINE named "foo" - foo = foo_section + [evp_properties] + ... EVP properties here ... - [foo_section] - # Override default name and use "myfoo" instead. - engine_id = myfoo + [ssl_configuration] + ... SSL/TLS configuration properties here ... -The command B<dynamic_path> loads and adds an ENGINE from the given path. It -is equivalent to sending the ctrls B<SO_PATH> with the path argument followed -by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is -not the required behaviour then alternative ctrls can be sent directly -to the dynamic ENGINE using ctrl commands. + [engines] + ... engine properties here ... -The command B<init> determines whether to initialize the ENGINE. If the value -is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to -initialized the ENGINE immediately. If the B<init> command is not present -then an attempt will be made to initialize the ENGINE after all commands in -its section have been processed. +The semantics of each module are described below. The phrase "in the +initialization section" refers to the section identified by the +B<openssl_conf> or other name (given as B<openssl_init> in the +example above). The examples below assume the configuration above +is used to specify the individual sections. -The command B<default_algorithms> sets the default algorithms an ENGINE will -supply using the functions ENGINE_set_default_string(). +=head2 ASN.1 Object Identifier Configuration -If the name matches none of the above command names it is assumed to be a -ctrl command which is sent to the ENGINE. The value of the command is the -argument to the ctrl command. If the value is the string B<EMPTY> then no -value is sent to the command. +The name B<oid_section> in the initialization section names the section +containing name/value pairs of OID's. +The name is the short name; the value is an optional long name followed +by a comma, and the numeric value. +While some OpenSSL commands have their own section for specifying OID's, +this section makes them avilable to all commands and applications. -For example: + [oids] + shortName = a very long OID name, 1.2.3.4 + newoid1 = 1.2.3.4.1 + some_other_oid = 1.2.3.5 +If a full configuration with the above fragment is in the file +F<example.cnf>, then the following command line: - [engine_section] + OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1 - # Configure ENGINE named "foo" - foo = foo_section +will output: - [foo_section] - # Load engine from DSO - dynamic_path = /some/path/fooengine.so - # A foo specific ctrl. - some_ctrl = some_value - # Another ctrl that doesn't take a value. - other_ctrl = EMPTY - # Supply all default algorithms - default_algorithms = ALL + 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1 -=head2 Provider Configuration Module +showing that the OID "newoid1" has been added as "1.2.3.4.1". -This provider configuration module has the name B<providers>. The -value of this variable points to a section containing further provider -configuration information. +=head2 Provider Configuration -The section pointed to by B<providers> is a table of provider names -(though see B<identity> below) and further sections containing -configuration information specific to each provider module. +The name B<providers> in the initialization section names the section +containing cryptographic provider configuration. The name/value assignments +in this section each name a provider, and point to the configuration section +for that provider. The provider-specific section is used to specify how +to load the module, activate it, and set other parameters. -Each provider specific section is used to load its module, perform -activation and set parameters to pass to the provider on demand. The -actual operation performed depends on the name of the name value pair. -The currently supported commands are listed below. +Within a provider section, the following names have meaning: -For example: +=over 4 - [provider_section] +=item B<identity> - # Configure provider named "foo" - foo = foo_section - # Configure provider named "bar" - bar = bar_section +This is used to specify an alternate name, overriding the default name +specified in the list of providers. For example: - [foo_section] - ... "foo" provider specific parameters ... + [providers] + foo = foo_provider - [bar_section] - ... "bar" provider specific parameters ... + [foo_provider] + identity = my_fips_module -The command B<identity> is used to give the provider name. For example: +=item B<module> - [provider_section] - # This would normally handle a provider named "foo" - foo = foo_section +Specifies the pathname of the module (typically a shared library) to load. - [foo_section] - # Override default name and use "myfoo" instead. - identity = myfoo +=item B<activate> -The parameter B<module> loads and adds a provider module from the -given module path. That path may be a simple filename, a relative -path or an absolute path. +If present, the module is activated. The value assigned to this name is not +significant. -The parameter B<activate> determines whether to activate the -provider. The value has no importance, the presence of the parameter -is enough for activation to take place. +=back All parameters in the section as well as sub-sections are made available to the provider. -=head2 EVP Configuration Module +=head2 EVP Configuration -This module has the name B<alg_section> which points to a section containing -algorithm commands. +The name B<alg_section> in the initialization section names the section +containing algorithmic properties when using the B<EVP> API. -The supported algorithm commands are: +Within the algorithm properties section, the following names have meaning: =over 4 @@ -329,197 +272,157 @@ string for EVP_set_default_properties(). The value is a boolean that can be B<yes> or B<no>. If the value is B<yes>, this is exactly equivalent to: - default_properties = fips=yes + default_properties = fips=yes -If the value is B<no>, nothing happens. +If the value is B<no>, nothing happens. Using this name is deprecated, and +if used, it must be the only name in the section. =back -These two commands should not be used together, as there is no control -over how they affect each other. -The use of B<fips_mode> is strongly discouraged and is only present -for backward compatibility with earlier OpenSSL FIPS modules. +=head2 SSL Configuration -=head2 SSL Configuration Module +The name B<ssl_conf> in the initialization section names the section +containing the list of SSL/TLS configurations. +As with the providers, each name in this section identifies a +section with the configuration for that name. For example: -This module has the name B<ssl_conf> which points to a section containing -SSL configurations. + [ssl_configuration] + server = server_tls_config + client = client_tls_config + system_default = tls_system_default -Each line in the SSL configuration section contains the name of the -configuration and the section containing it. + [server_tls_config] + ... configuration for SSL/TLS servers ... -Each configuration section consists of command value pairs for B<SSL_CONF>. -Each pair will be passed to a B<SSL_CTX> or B<SSL> structure if it calls -SSL_CTX_config() or SSL_config() with the appropriate configuration name. + [client_tls_config] + ... configuration for SSL/TLS clients ... -Note: any characters before an initial dot in the configuration section are -ignored so the same command can be used multiple times. +The configuration name B<system_default> has a special meaning. If it +exists, it is applied whenever an B<SSL_CTX> object is created. For example, +to impose a system-wide minimum on protocol version: -For example: + [tls_system_default] + MinProtocol = TLSv1.2 + +Each configuration section consists of name/value pairs that are parsed +by B<SSL_CONF_cmd(3)>, which will be called by SSL_CTX_config() or +SSL_config(), appropriately. Note that any characters before an initial +dot in the configuration section are ignored, so that the same command can +be used multiple times. This probably is most useful for loading different +key types, as shown here: - ssl_conf = ssl_sect + [server_tls_config] + RSA.Certificate = server-rsa.pem + ECDSA.Certificate = server-ecdsa.pem - [ssl_sect] +=head2 Engine Configuration - server = server_section +The name B<engines> in the initialization section names the section +containing the list of ENGINE configurations. +As with the providers, each name in this section identifies an engine +with the configuration for that engine. +The engine-specific section is used to specify how to load the engine, +activate it, and set other parameters. - [server_section] +Within an engine section, the following names have meaning: - RSA.Certificate = server-rsa.pem - ECDSA.Certificate = server-ecdsa.pem - Ciphers = ALL:!RC4 +=over 4 + +=item B<engine_id> -The system default configuration with name B<system_default> if present will -be applied during any creation of the B<SSL_CTX> structure. +This is used to specify an alternate name, overriding the default name +specified in the list of engines. If present, it must be first. +For example: -Example of a configuration with the system default: + [engines] + foo = foo_engine - ssl_conf = ssl_sect + [foo_engine] + engine_id = myfoo - [ssl_sect] +=item B<dynamic_path> - system_default = system_default_sect +This loads and adds an ENGINE from the given path. It is equivalent to +sending the ctrls B<SO_PATH> with the path argument followed by B<LIST_ADD> +with value B<2> and B<LOAD> to the dynamic ENGINE. If this is not the +required behaviour then alternative ctrls can be sent directly to the +dynamic ENGINE using ctrl commands. - [system_default_sect] +=item B<init> - MinProtocol = TLSv1.2 +This specifies whether to initialize the ENGINE. If the value is B<0> the +ENGINE will not be initialized, if the value is B<1> an attempt is made +to initialize +the ENGINE immediately. If the B<init> command is not present then an +attempt will be made to initialize the ENGINE after all commands in its +section have been processed. +=item B<default_algorithms> -=head1 NOTES +This sets the default algorithms an ENGINE will supply using the function +ENGINE_set_default_string(). -If a configuration file attempts to expand a variable that doesn't exist -then an error is flagged and the file will not load. This can happen -if an attempt is made to expand an environment variable that doesn't -exist. For example in a previous version of OpenSSL the default OpenSSL -master configuration file used the value of B<HOME> which may not be -defined on non Unix systems and would cause an error. +=back -This can be worked around by including a B<default> section to provide -a default value: then if the environment lookup fails the default value -will be used instead. For this to work properly the default value must -be defined earlier in the configuration file than the expansion. See -the B<EXAMPLES> section for an example of how to do this. +All other names are taken to be the name of a ctrl command that is +sent to the ENGINE, and the value is the argument passed with the command. +The special value B<EMPTY> means no value is sent with the command. +For example: -If the same variable exists in the same section then all but the last -value will be silently ignored. In certain circumstances such as with -DNs the same field may occur multiple times. This is usually worked -around by ignoring any characters before an initial B<.> e.g. + [engines] + foo = foo_engine - 1.OU="My first OU" - 2.OU="My Second OU" + [foo_engine] + dynamic_path = /some/path/fooengine.so + some_ctrl = some_value + default_algorithms = ALL + other_ctrl = EMPTY =head1 EXAMPLES -Here is a sample configuration file using some of the features -mentioned above. +This example shows how to use quoting and escaping. # This is the default section. - - HOME=/temp - configdir=$ENV::HOME/config + HOME = /temp + configdir = $ENV::HOME/config [ section_one ] - - # We are now in section one. - # Quotes permit leading and trailing whitespace any = " any variable name " - other = A string that can \ cover several lines \ by including \\ characters - message = Hello World\n [ section_two ] - greeting = $section_one::message -This next example shows how to expand environment variables safely. - -Suppose you want a variable called B<tmpfile> to refer to a -temporary filename. The directory it is placed in can determined by -the B<TEMP> or B<TMP> environment variables but they may not be -set to any value at all. If you just include the environment variable -names and the variable doesn't exist then this will cause an error when -an attempt is made to load the configuration file. By making use of the -default section both values can be looked up with B<TEMP> taking -priority and B</tmp> used if neither is defined: - - TMP=/tmp - # The above value is used if TMP isn't in the environment - TEMP=$ENV::TMP - # The above value is used if TEMP isn't in the environment - tmpfile=${ENV::TEMP}/tmp.filename - -Simple OpenSSL library configuration example to enter FIPS mode: - - # Default appname: should match "appname" parameter (if any) - # supplied to CONF_modules_load_file_with_libctx et al. - openssl_conf = openssl_conf_section - - [openssl_conf_section] - # Configuration module list - alg_section = evp_sect - - [evp_sect] - # Set to "yes" to enter FIPS mode if supported - fips_mode = yes - -Note: in the above example you will get an error in non FIPS capable versions -of OpenSSL. - -Simple OpenSSL library configuration to make TLS 1.3 the system-default -minimum TLS version: - - # Toplevel section for openssl (including libssl) - openssl_conf = default_conf_section +This example shows how to expand environment variables safely. +In this example, the variable B<tempfile> is intended to refer +to a temporary file, and the environment variable B<TEMP> or +B<TMP>, if present, specify the directory where the file +should be put. +Since the default section is checked if a variable does not +exist, it is possible to set B<TMP> to default to F</tmp>, and +B<TEMP> to default to B<TMP>. - [default_conf_section] - # We only specify configuration for the "ssl module" - ssl_conf = ssl_section + # These two lines must be in the default section. + TMP = /tmp + TEMP = $ENV::TMP - [ssl_section] - system_default = system_default_section + # This can be used anywhere + tmpfile = ${ENV::TEMP}/tmp.filename - [system_default_section] - MinProtocol = TLSv1.3 +This example shows how to enforce FIPS mode for the application +F<sample>. -More complex OpenSSL library configuration. Add OID and don't enter FIPS mode: + sample = fips_config - # Default appname: should match "appname" parameter (if any) - # supplied to CONF_modules_load_file_with_libctx et al. - openssl_conf = openssl_conf_section + [fips_config] + alg_section = evp_properties - [openssl_conf_section] - # Configuration module list - alg_section = evp_sect - oid_section = new_oids - - [evp_sect] - # This will have no effect as FIPS mode is off by default. - # Set to "yes" to enter FIPS mode, if supported - fips_mode = no - - [new_oids] - # New OID, just short name - newoid1 = 1.2.3.4.1 - # New OID shortname and long name - newoid2 = New OID 2 long name, 1.2.3.4.2 - -The above examples can be used with any application supporting library -configuration if "openssl_conf" is modified to match the appropriate "appname". - -For example if the second sample file above is saved to "example.cnf" then -the command line: - - OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1 - -will output: - - 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1 - -showing that the OID "newoid1" has been added as "1.2.3.4.1". + [evp_properties] + default_properties = "fips=yes" =head1 ENVIRONMENT @@ -542,22 +445,20 @@ Ignored in set-user-ID and set-group-ID programs. =item B<OPENSSL_CONF_INCLUDE> -The optional path to prepend to all .include paths. +The optional path to prepend to all B<.include> paths. =back =head1 BUGS -Currently there is no way to include characters using the octal B<\nnn> -form. Strings are all null terminated so nulls cannot form part of -the value. +There is no way to include characters using the octal B<\nnn> form. Strings +are all null terminated so nulls cannot form part of the value. The escaping isn't quite right: if you want to use sequences like B<\n> you can't use any quote escaping on the same line. -Files are loaded in a single pass. This means that an variable expansion -will only work if the variables referenced are defined earlier in the -file. +The limit that only one directory can be opened and read at a time +can be considered a bug and should be fixed. =head1 HISTORY @@ -572,7 +473,12 @@ configuration files using that syntax will have to be modified. =head1 SEE ALSO -L<openssl-x509(1)>, L<openssl-req(1)>, L<openssl-ca(1)>, L<fips_config(5)> +L<openssl-x509(1)>, L<openssl-req(1)>, L<openssl-ca(1)>, +L<ASN1_generate_nconf(3)>, +L<EVP_set_default_properties(3)>, +L<CONF_modules_load_file(3)>, +L<fips_config(5)>, and +L<x509v3_config(5)>. =head1 COPYRIGHT