Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OPENSSL.CNF(5)		  FreeBSD File Formats Manual		OPENSSL.CNF(5)

NAME
     openssl.cnf -- OpenSSL configuration files

DESCRIPTION
     The OpenSSL CONF library can be used to read configuration	files; see
     CONF_modules_load_file(3).	 It is used for	the OpenSSL master configura-
     tion file /etc/ssl/openssl.cnf and	in a few other places like SPKAC files
     and certificate extension files for the openssl(1)	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	[section_name] and ends	when a new section is started
     or	the end	of the file is reached.	 A section name	can consist of al-
     phanumeric	characters and underscores.

     The first section of a configuration file is special and is referred to
     as	the "default section".	It is usually unnamed and extends from the
     start of file to the first	named section.	When a name is being looked
     up, it is first looked up in a named section (if any) and then in the de-
     fault section.

     The environment is	mapped onto a section called ENV.

     Comments can be included by preceding them	with the `#' character.

     Each section in a configuration file consists of a	number of name and
     value pairs of the	form name=value.

     The name string can contain any alphanumeric characters as	well as	a few
     punctuation symbols such as `.' `,' `;' and `_'.

     The value string consists of the string following the `=' character until
     the end of	the line with any leading and trailing whitespace removed.

     The value string undergoes	variable expansion.  This can be done by in-
     cluding substrings	of the form $name or ${name}: 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
     $section::name or ${section::name}.  By using the form $ENV::name,	envi-
     ronment variables can be substituted.  It is also possible	to assign val-
     ues to environment	variables by using the name ENV::name.	This will work
     if	the program looks up environment variables using the CONF library in-
     stead of calling getenv(3)	directly.  The value string must not exceed
     64k in length after variable expansion or an error	will occur.

     It	is possible to escape certain characters by using any kind of quote or
     the `\' character.	 By making the last character of a line	a `\', a value
     string can	be spread across multiple lines.  In addition the sequences
     `\n', `\r', `\b', and `\t'	are recognized.

OPENSSL	LIBRARY	CONFIGURATION
     Applications can automatically configure certain aspects of OpenSSL using
     the master	OpenSSL	configuration file, or optionally an alternative con-
     figuration	file.  The openssl(1) 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 de-
     fault name	is openssl_conf, which is used by the openssl(1) utility.
     Other applications	may use	an alternative name such as
     myapplication_conf.  All library configuration lines appear in the	de-
     fault 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 name	repre-
     sents the name of the configuration module.  The meaning of the value is
     module specific: it may, for example, represent a further configuration
     section containing	configuration module specific information.  For	exam-
     ple:

	   # The following line	must be	in the default section.
	   openssl_conf	= openssl_init

	   [openssl_init]
	   oid_section = new_oids
	   engines = engine_section

	   [new_oids]
	   ... new oids	here ...

	   [engine_section]
	   ... engine stuff here ...

     The features of each configuration	module are described below.

   ASN1	Object Configuration Module
     This module has the name 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, and the value	is the numerical form of the OID.  Al-
     though some of the	openssl(1) utility subcommands already have their own
     ASN1 OBJECT section functionality,	not all	do.  By	using the ASN1 OBJECT
     configuration module, all the openssl(1) utility subcommands can see the
     new objects as well as any	compliant applications.	 For example:

	   [new_oids]
	   some_new_oid	= 1.2.3.4
	   some_other_oid = 1.2.3.5

     It	is also	possible to set	the value to the long name followed by a comma
     and the numerical OID form.  For example:

	   shortName = some object long	name, 1.2.3.4

   Engine Configuration	Module
     This ENGINE configuration module has the name engines.  The value of this
     variable points to	a section containing further ENGINE configuration in-
     formation.

     The section pointed to by engines is a table of engine names (though see
     engine_id below) and further sections containing configuration informa-
     tion specific to each ENGINE.

     Each ENGINE specific section is used to set default algorithms, load dy-
     namic ENGINEs, perform initialization and send ctrls.  The	actual opera-
     tion performed depends on the command name	which is the name of the name
     value pair.  The currently	supported commands are listed below.

     For example:

	   [engine_section]
	   # Configure ENGINE named "foo"
	   foo = foo_section
	   # Configure ENGINE named "bar"
	   bar = bar_section

	   [foo_section]
	   ... foo ENGINE specific commands ...

	   [bar_section]
	   ... "bar" ENGINE specific commands ...

     The command engine_id is used to give the ENGINE name.  If	used this com-
     mand must be first.  For example:

	   [engine_section]
	   # This would	normally handle	an ENGINE named	"foo"
	   foo = foo_section

	   [foo_section]
	   # Override default name and use "myfoo" instead.
	   engine_id = myfoo

     The command dynamic_path loads and	adds an	ENGINE from the	given path.
     It	is equivalent to sending the ctrls SO_PATH with	the path argument fol-
     lowed by LIST_ADD with value 2 and	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.

     The command init determines whether to initialize the ENGINE.  If the
     value is 0, the ENGINE will not be	initialized.  If it is 1, an attempt
     is	made to	initialized the	ENGINE immediately.  If	the 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 command default_algorithms sets the default algorithms	an ENGINE will
     supply using the functions	ENGINE_set_default_string(3).

     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 EMPTY, then
     no	value is sent to the command.

     For example:

	   [engine_section]
	   # Configure ENGINE named "foo"
	   foo = foo_section

	   [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

FILES
     /etc/ssl/openssl.cnf  standard configuration file

EXAMPLES
     Here is a sample configuration file using some of the features mentioned
     above:

	   # This is the default section.
	   HOME=/temp
	   RANDFILE= ${ENV::HOME}/.rnd
	   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	tmpfile	to refer to a temporary	file-
     name.  The	directory it is	placed in can determined by the	TEMP or	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 TEMP taking priority and	/tmp used if neither is	de-
     fined:

	   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

     More complex OpenSSL library configuration.  Add OID:

	   # Default appname: should match "appname" parameter (if any)
	   # supplied to CONF_modules_load_file	et al.
	   openssl_conf	= openssl_conf_section

	   [openssl_conf_section]
	   # Configuration module list
	   alg_section = evp_sect
	   oid_section = new_oids

	   [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".

SEE ALSO
     openssl(1), CONF_modules_load_file(3), OPENSSL_config(3), x509v3.cnf(5)

CAVEATS
     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 also hap-
     pen 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 HOME which may	not be defined
     on	non Unix systems and would cause an error.

     This can be worked	around by including a default section to provide a de-
     fault 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
     EXAMPLES section for an example of	how to do this.

     If	the same variable is defined more than once in the same	section, then
     all but the last value will be silently ignored.  In certain circum-
     stances such as with DNs, the same	field may occur	multiple times.	 This
     is	usually	worked around by ignoring any characters before	an initial
     `.', for example:

	   1.OU="My first OU"
	   2.OU="My Second OU"

BUGS
     Currently there is	no way to include characters using the octal \nnn
     form.  Strings are	all NUL	terminated, so NUL bytes cannot	form part of
     the value.

     The escaping isn't	quite right: if	you want to use	sequences like `\n',
     you can't use any quote escaping on the same line.

     Files are loaded in a single pass.	 This means that a variable expansion
     will only work if the variables referenced	are defined earlier in the
     file.

FreeBSD	13.0		       February	17, 2020		  FreeBSD 13.0

NAME | DESCRIPTION | OPENSSL LIBRARY CONFIGURATION | FILES | EXAMPLES | SEE ALSO | CAVEATS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=openssl.cnf&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help