From 3562e78743202e43aec8727005182a2558117eca Mon Sep 17 00:00:00 2001 From: marha Date: Sun, 28 Jun 2009 22:07:26 +0000 Subject: Checked in the following released items: xkeyboard-config-1.4.tar.gz ttf-bitstream-vera-1.10.tar.gz font-alias-1.0.1.tar.gz font-sun-misc-1.0.0.tar.gz font-sun-misc-1.0.0.tar.gz font-sony-misc-1.0.0.tar.gz font-schumacher-misc-1.0.0.tar.gz font-mutt-misc-1.0.0.tar.gz font-misc-misc-1.0.0.tar.gz font-misc-meltho-1.0.0.tar.gz font-micro-misc-1.0.0.tar.gz font-jis-misc-1.0.0.tar.gz font-isas-misc-1.0.0.tar.gz font-dec-misc-1.0.0.tar.gz font-daewoo-misc-1.0.0.tar.gz font-cursor-misc-1.0.0.tar.gz font-arabic-misc-1.0.0.tar.gz font-winitzki-cyrillic-1.0.0.tar.gz font-misc-cyrillic-1.0.0.tar.gz font-cronyx-cyrillic-1.0.0.tar.gz font-screen-cyrillic-1.0.1.tar.gz font-xfree86-type1-1.0.1.tar.gz font-adobe-utopia-type1-1.0.1.tar.gz font-ibm-type1-1.0.0.tar.gz font-bitstream-type1-1.0.0.tar.gz font-bitstream-speedo-1.0.0.tar.gz font-bh-ttf-1.0.0.tar.gz font-bh-type1-1.0.0.tar.gz font-bitstream-100dpi-1.0.0.tar.gz font-bh-lucidatypewriter-100dpi-1.0.0.tar.gz font-bh-100dpi-1.0.0.tar.gz font-adobe-utopia-100dpi-1.0.1.tar.gz font-adobe-100dpi-1.0.0.tar.gz font-util-1.0.1.tar.gz font-bitstream-75dpi-1.0.0.tar.gz font-bh-lucidatypewriter-75dpi-1.0.0.tar.gz font-adobe-utopia-75dpi-1.0.1.tar.gz font-bh-75dpi-1.0.0.tar.gz bdftopcf-1.0.1.tar.gz font-adobe-75dpi-1.0.0.tar.gz mkfontscale-1.0.6.tar.gz openssl-0.9.8k.tar.gz bigreqsproto-1.0.2.tar.gz xtrans-1.2.2.tar.gz resourceproto-1.0.2.tar.gz inputproto-1.4.4.tar.gz compositeproto-0.4.tar.gz damageproto-1.1.0.tar.gz zlib-1.2.3.tar.gz xkbcomp-1.0.5.tar.gz freetype-2.3.9.tar.gz pthreads-w32-2-8-0-release.tar.gz pixman-0.12.0.tar.gz kbproto-1.0.3.tar.gz evieext-1.0.2.tar.gz fixesproto-4.0.tar.gz recordproto-1.13.2.tar.gz randrproto-1.2.2.tar.gz scrnsaverproto-1.1.0.tar.gz renderproto-0.9.3.tar.gz xcmiscproto-1.1.2.tar.gz fontsproto-2.0.2.tar.gz xextproto-7.0.3.tar.gz xproto-7.0.14.tar.gz libXdmcp-1.0.2.tar.gz libxkbfile-1.0.5.tar.gz libfontenc-1.0.4.tar.gz libXfont-1.3.4.tar.gz libX11-1.1.5.tar.gz libXau-1.0.4.tar.gz libxcb-1.1.tar.gz xorg-server-1.5.3.tar.gz --- openssl/doc/apps/config.pod | 279 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 openssl/doc/apps/config.pod (limited to 'openssl/doc/apps/config.pod') diff --git a/openssl/doc/apps/config.pod b/openssl/doc/apps/config.pod new file mode 100644 index 000000000..ace34b62b --- /dev/null +++ b/openssl/doc/apps/config.pod @@ -0,0 +1,279 @@ + +=pod + +=for comment openssl_manual_section:5 + +=head1 NAME + +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 +and in a few other places like B files and certificate extension +files for the B 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 B<[ 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 first section of a configuration file is special and is referred +to as the B section this is usually unnamed and is 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. + +The environment is mapped onto a section called B. + +Comments can be included by preceding them with the B<#> character + +Each section in a configuration file consists of a number of name and +value pairs of the form B + +The B string can contain any alphanumeric characters as well as +a few punctuation symbols such as B<.> B<,> B<;> and B<_>. + +The B 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, this will work +if the program looks up environment variables using the B library +instead of calling B directly. + +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 string can be spread across multiple lines. In addition +the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized. + +=head1 OPENSSL LIBRARY CONFIGURATION + +In OpenSSL 0.9.7 and later applications can automatically configure certain +aspects of OpenSSL using the master OpenSSL configuration file, or optionally +an alternative configuration file. The B 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 which is used by the B utility. Other +applications may use an alternative name such as B. + +The configuration section should consist of a set of name value pairs which +contain specific module configuration information. The B represents +the name of the I the meaning of the B is +module specific: it may, for example, represent a further configuration +section containing configuration module specific information. E.g. + + openssl_conf = openssl_init + + [openssl_init] + + oid_section = new_oids + engines = engine_section + + [new_oids] + + ... new oids here ... + + [engine_section] + + ... engine stuff here ... + +Currently there are two configuration modules. One for ASN1 objects another +for ENGINE configuration. + +=head2 ASN1 OBJECT CONFIGURATION MODULE + +This module has the name B. 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 utility sub commands already have their own ASN1 OBJECT section +functionality not all do. By using the ASN1 OBJECT configuration module +B the B utility sub commands 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 + +In OpenSSL 0.9.8 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 + +=head2 ENGINE CONFIGURATION MODULE + +This ENGINE configuration module has the name B. The value of this +variable points to a section containing further ENGINE configuration +information. + +The section pointed to by B is a table of engine names (though see +B below) and further sections containing configuration informations +specific to each ENGINE. + +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 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 B is used to give the ENGINE name. If used this +command 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 B loads and adds an ENGINE from the given path. It +is equivalent to sending the ctrls B with the path argument followed +by B with value 2 and B 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 B 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 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 B sets the default algorithms an ENGINE will +supply using the functions B + +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 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 + +=head1 NOTES + +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 which may not be +defined on non Unix systems and would cause an error. + +This can be worked around by including a B 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 section for an example of how to do this. + +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. + + 1.OU="My first OU" + 2.OU="My Second OU" + +=head1 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 B to refer to a +temporary filename. The directory it is placed in can determined by +the the B or B 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 taking +priority and B 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 + +=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. + +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. + +=head1 SEE ALSO + +L, L, L + +=cut -- cgit v1.2.3