1: 
    2: =pod
    3: 
    4: =for comment openssl_manual_section:5
    5: 
    6: =head1 NAME
    7: 
    8: config - OpenSSL CONF library configuration files
    9: 
   10: =head1 DESCRIPTION
   11: 
   12: The OpenSSL CONF library can be used to read configuration files.
   13: It is used for the OpenSSL master configuration file B<openssl.cnf>
   14: and in a few other places like B<SPKAC> files and certificate extension
   15: files for the B<x509> utility. OpenSSL applications can also use the
   16: CONF library for their own purposes.
   17: 
   18: A configuration file is divided into a number of sections. Each section
   19: starts with a line B<[ section_name ]> and ends when a new section is
   20: started or end of file is reached. A section name can consist of
   21: alphanumeric characters and underscores.
   22: 
   23: The first section of a configuration file is special and is referred
   24: to as the B<default> section this is usually unnamed and is from the
   25: start of file until the first named section. When a name is being looked up
   26: it is first looked up in a named section (if any) and then the
   27: default section.
   28: 
   29: The environment is mapped onto a section called B<ENV>.
   30: 
   31: Comments can be included by preceding them with the B<#> character
   32: 
   33: Each section in a configuration file consists of a number of name and
   34: value pairs of the form B<name=value>
   35: 
   36: The B<name> string can contain any alphanumeric characters as well as
   37: a few punctuation symbols such as B<.> B<,> B<;> and B<_>.
   38: 
   39: The B<value> string consists of the string following the B<=> character
   40: until end of line with any leading and trailing white space removed.
   41: 
   42: The value string undergoes variable expansion. This can be done by
   43: including the form B<$var> or B<${var}>: this will substitute the value
   44: of the named variable in the current section. It is also possible to
   45: substitute a value from another section using the syntax B<$section::name>
   46: or B<${section::name}>. By using the form B<$ENV::name> environment
   47: variables can be substituted. It is also possible to assign values to
   48: environment variables by using the name B<ENV::name>, this will work
   49: if the program looks up environment variables using the B<CONF> library
   50: instead of calling B<getenv()> directly.
   51: 
   52: It is possible to escape certain characters by using any kind of quote
   53: or the B<\> character. By making the last character of a line a B<\>
   54: a B<value> string can be spread across multiple lines. In addition
   55: the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
   56: 
   57: =head1 OPENSSL LIBRARY CONFIGURATION
   58: 
   59: In OpenSSL 0.9.7 and later applications can automatically configure certain
   60: aspects of OpenSSL using the master OpenSSL configuration file, or optionally
   61: an alternative configuration file. The B<openssl> utility includes this
   62: functionality: any sub command uses the master OpenSSL configuration file
   63: unless an option is used in the sub command to use an alternative configuration
   64: file.
   65: 
   66: To enable library configuration the default section needs to contain an 
   67: appropriate line which points to the main configuration section. The default
   68: name is B<openssl_conf> which is used by the B<openssl> utility. Other
   69: applications may use an alternative name such as B<myapplicaton_conf>.
   70: 
   71: The configuration section should consist of a set of name value pairs which
   72: contain specific module configuration information. The B<name> represents
   73: the name of the I<configuration module> the meaning of the B<value> is 
   74: module specific: it may, for example, represent a further configuration
   75: section containing configuration module specific information. E.g.
   76: 
   77:  openssl_conf = openssl_init
   78: 
   79:  [openssl_init]
   80: 
   81:  oid_section = new_oids
   82:  engines = engine_section
   83: 
   84:  [new_oids]
   85: 
   86:  ... new oids here ...
   87: 
   88:  [engine_section]
   89: 
   90:  ... engine stuff here ...
   91: 
   92: Currently there are two configuration modules. One for ASN1 objects another
   93: for ENGINE configuration.
   94: 
   95: =head2 ASN1 OBJECT CONFIGURATION MODULE
   96: 
   97: This module has the name B<oid_section>. The value of this variable points
   98: to a section containing name value pairs of OIDs: the name is the OID short
   99: and long name, the value is the numerical form of the OID. Although some of
  100: the B<openssl> utility sub commands already have their own ASN1 OBJECT section
  101: functionality not all do. By using the ASN1 OBJECT configuration module
  102: B<all> the B<openssl> utility sub commands can see the new objects as well
  103: as any compliant applications. For example:
  104: 
  105:  [new_oids]
  106:  
  107:  some_new_oid = 1.2.3.4
  108:  some_other_oid = 1.2.3.5
  109: 
  110: In OpenSSL 0.9.8 it is also possible to set the value to the long name followed
  111: by a comma and the numerical OID form. For example:
  112: 
  113:  shortName = some object long name, 1.2.3.4
  114: 
  115: =head2 ENGINE CONFIGURATION MODULE
  116: 
  117: This ENGINE configuration module has the name B<engines>. The value of this
  118: variable points to a section containing further ENGINE configuration
  119: information.
  120: 
  121: The section pointed to by B<engines> is a table of engine names (though see
  122: B<engine_id> below) and further sections containing configuration informations
  123: specific to each ENGINE.
  124: 
  125: Each ENGINE specific section is used to set default algorithms, load
  126: dynamic, perform initialization and send ctrls. The actual operation performed
  127: depends on the I<command> name which is the name of the name value pair. The
  128: currently supported commands are listed below.
  129: 
  130: For example:
  131: 
  132:  [engine_section]
  133: 
  134:  # Configure ENGINE named "foo"
  135:  foo = foo_section
  136:  # Configure ENGINE named "bar"
  137:  bar = bar_section
  138: 
  139:  [foo_section]
  140:  ... foo ENGINE specific commands ...
  141: 
  142:  [bar_section]
  143:  ... "bar" ENGINE specific commands ...
  144: 
  145: The command B<engine_id> is used to give the ENGINE name. If used this 
  146: command must be first. For example:
  147: 
  148:  [engine_section]
  149:  # This would normally handle an ENGINE named "foo"
  150:  foo = foo_section
  151: 
  152:  [foo_section]
  153:  # Override default name and use "myfoo" instead.
  154:  engine_id = myfoo
  155: 
  156: The command B<dynamic_path> loads and adds an ENGINE from the given path. It
  157: is equivalent to sending the ctrls B<SO_PATH> with the path argument followed
  158: by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is
  159: not the required behaviour then alternative ctrls can be sent directly
  160: to the dynamic ENGINE using ctrl commands.
  161: 
  162: The command B<init> determines whether to initialize the ENGINE. If the value
  163: is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to
  164: initialized the ENGINE immediately. If the B<init> command is not present
  165: then an attempt will be made to initialize the ENGINE after all commands in
  166: its section have been processed.
  167: 
  168: The command B<default_algorithms> sets the default algorithms an ENGINE will
  169: supply using the functions B<ENGINE_set_default_string()>
  170: 
  171: If the name matches none of the above command names it is assumed to be a
  172: ctrl command which is sent to the ENGINE. The value of the command is the 
  173: argument to the ctrl command. If the value is the string B<EMPTY> then no
  174: value is sent to the command.
  175: 
  176: For example:
  177: 
  178: 
  179:  [engine_section]
  180: 
  181:  # Configure ENGINE named "foo"
  182:  foo = foo_section
  183: 
  184:  [foo_section]
  185:  # Load engine from DSO
  186:  dynamic_path = /some/path/fooengine.so
  187:  # A foo specific ctrl.
  188:  some_ctrl = some_value
  189:  # Another ctrl that doesn't take a value.
  190:  other_ctrl = EMPTY
  191:  # Supply all default algorithms
  192:  default_algorithms = ALL
  193: 
  194: =head1 NOTES
  195: 
  196: If a configuration file attempts to expand a variable that doesn't exist
  197: then an error is flagged and the file will not load. This can happen
  198: if an attempt is made to expand an environment variable that doesn't
  199: exist. For example in a previous version of OpenSSL the default OpenSSL
  200: master configuration file used the value of B<HOME> which may not be
  201: defined on non Unix systems and would cause an error.
  202: 
  203: This can be worked around by including a B<default> section to provide
  204: a default value: then if the environment lookup fails the default value
  205: will be used instead. For this to work properly the default value must
  206: be defined earlier in the configuration file than the expansion. See
  207: the B<EXAMPLES> section for an example of how to do this.
  208: 
  209: If the same variable exists in the same section then all but the last
  210: value will be silently ignored. In certain circumstances such as with
  211: DNs the same field may occur multiple times. This is usually worked
  212: around by ignoring any characters before an initial B<.> e.g.
  213: 
  214:  1.OU="My first OU"
  215:  2.OU="My Second OU"
  216: 
  217: =head1 EXAMPLES
  218: 
  219: Here is a sample configuration file using some of the features
  220: mentioned above.
  221: 
  222:  # This is the default section.
  223:  
  224:  HOME=/temp
  225:  RANDFILE= ${ENV::HOME}/.rnd
  226:  configdir=$ENV::HOME/config
  227: 
  228:  [ section_one ]
  229: 
  230:  # We are now in section one.
  231: 
  232:  # Quotes permit leading and trailing whitespace
  233:  any = " any variable name "
  234: 
  235:  other = A string that can \
  236:  cover several lines \
  237:  by including \\ characters
  238: 
  239:  message = Hello World\n
  240: 
  241:  [ section_two ]
  242: 
  243:  greeting = $section_one::message
  244: 
  245: This next example shows how to expand environment variables safely.
  246: 
  247: Suppose you want a variable called B<tmpfile> to refer to a
  248: temporary filename. The directory it is placed in can determined by
  249: the the B<TEMP> or B<TMP> environment variables but they may not be
  250: set to any value at all. If you just include the environment variable
  251: names and the variable doesn't exist then this will cause an error when
  252: an attempt is made to load the configuration file. By making use of the
  253: default section both values can be looked up with B<TEMP> taking 
  254: priority and B</tmp> used if neither is defined:
  255: 
  256:  TMP=/tmp
  257:  # The above value is used if TMP isn't in the environment
  258:  TEMP=$ENV::TMP
  259:  # The above value is used if TEMP isn't in the environment
  260:  tmpfile=${ENV::TEMP}/tmp.filename
  261: 
  262: =head1 BUGS
  263: 
  264: Currently there is no way to include characters using the octal B<\nnn>
  265: form. Strings are all null terminated so nulls cannot form part of
  266: the value.
  267: 
  268: The escaping isn't quite right: if you want to use sequences like B<\n>
  269: you can't use any quote escaping on the same line.
  270: 
  271: Files are loaded in a single pass. This means that an variable expansion
  272: will only work if the variables referenced are defined earlier in the
  273: file.
  274: 
  275: =head1 SEE ALSO
  276: 
  277: L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)>
  278: 
  279: =cut