NAME
crlpublish - CRL publisher configuration syntax
DESCRIPTION
crlpublish is a utility for pushing CRL updates to one or more target servers where other applications and processes pick them up. These are commonly referred to as Issuing Distribution Points and should ideally be encoded into the CRLs and CA certificates themselves.
Often, there is not enough information encoded in the CRL and in the operating environment to deduce how this publishing should be accomplished. In those cases, details must be provided through configuration files. Their format, syntax, and usage are documented here.
CONFIG FILE LOCATIONS
Configuration files should be placed in one of these directories:
/etc/crlpublish/*.cfg
$HOME/.crlpublish/*.cfg
Additionally, as in-situ compatibility with the older crlpublisher.sh script is supported, the following directories are scanned for legacy config files:
/etc/crlpublisher/*.conf
$HOME/.crlpublisher/*.conf
There is no particular naming convention required, nor even a need to use more than one file. Any file with the proper extension will be imported, in directory order.
CONFIG FILE FORMAT
Although there is a notion of an old and a new file format, they are read in by the same parser. Using "newness" in an old-style .conf file will generate a runtime error.
Both file formats use a namedAttribute="value" basic syntax.
There the similarity ends. The old version was parsed by the shell, and so was intolerant of whitespace and liberal about quoting and content. Backticks and other shell language were legal, although it is not known if anyone ever used such. crlpublish does not support this usage.
The new format is parsed by Perl, and so backticks are not permitted. Quotes are optional, and whitespace is tolerated at the beginning and end of any line, and between the variable, equals, and value. Extra space is dropped; if you need control, use single or double quotes around the value.
Also, the new format supports sections using the ini style [sectionName] syntax. The brackets are treated as quotes, and whitespace within is not dropped.
CONFIG FILE EXAMPLES
An example of the old syntax follows:
publisher=scp
remoteUser=crlowner
remoteHost=my.target.server.com
remoteLocation=crl/thisca.crl
privateKey=/path/to/ssh/privateKeyFile
issuerDn="CN=My CA,O=Example Inc.,C=ME"
A roughly equivalent example of the new syntax follows:
[defaults]
publishMethod=scp
remoteUser=crlowner
[CN=My CA,O=Example Inc.,C=ME]
remotePath=crl
remoteFile=thisca.crl
remoteHost=crl.target.server.com
[crl.target.server.com]
remoteHost=crl-1.target.server.com,crl-2.target.server.com
Note that such verbosity is not generally required, as will be explained below, and there is some redundancy to illustrate capabilities. The section for my.target.server.com needn't exist; the comma-separated list could have been specified above in the defaults, or in the issuerDn section.
RUNTIME CONFIG RESOLVING ORDER
In point of fact, any of those variables could have appeared in any of those sections, and the configuration parser would happily import and supply them at the appropriate point in the resolution order; see below.
Cascaded defaults are supported by creating a container object and copying the configuration name-value pairs into that container in a particular order, allowing attributes of the same name to overwrite earlier values.
First, fixed defaults are applied. At present, this is only publishMethod=scp. Next, the parsed parts of the Issuing Distribution Point URL, if any, are copied in, followed by all values in the [defaults] section. Then, the values from the issuerDn section are copied the Issuer Distribution Point URL. Finally, values from the remoteHost section are copied in.
In this way, it is often unnecessary to supply any configuration at all, if the Issuing Distribution Point is supplied in the CRL. See below for defaults.
It is also worth noting that attributes can be named anything and will be passed into the container object. No core code changes will be required to support new attributes for new publishing methods. It is up to the publishMethod implementation to make meaning of them.
ATTRIBUTE NAMES AND AND MEANINGS
Additional publishMethods may require their own attributes.
publishMethod
Specify the publishing method to use. Currently, only scp is supported.
publisher
Equivalent to publishMethod; kept for legacy compatibility.
issuerDn
Only meaningful in a legacy style config file; specifies the issuerDn to which that config file refers. The new config syntax specifies this in a section name.
remoteUser
Specify the remote username to connect as. If not specified, none will be specified on the command line, and scp will default to the current user on the originating host.
remoteHost
Specify the remote host to connect to. It can be a hostname, short or long, or an address, IPv4 or IPv6. It will be passed verbatim to scp. If not specified, it will be parsed from the CRL if available.
Multiple targets are supported by supplying a comma-separated list. Whitespace around the commas is tolerated.
remoteFile
Specify the filename to publish the CRL as, since crlpublish was probably invoked using a temporary file with a randomized name. If not specified, it will be parsed from the CRL if available.
remotePath
Specify the subdirectory to place the remoteFile in. Relative paths are relative to the remoteUser's home directory on the remoteHost. It must exist. If not specified, it will be parsed from the CRL if available.
remoteLocation
Combines remotePath and remoteFile into a single directive. Kept for legacy compatibility; stored internally as remotePath and remoteFile.
AUTHOR
Kevin Cody-Little <kcody@cpan.org>