Configuration file

Updated: May 06, 2022

The qcrypto library configuration file allows the system integrator to define which cryptography providers are supported and available to the system.

Configuration file location

The system first searches for the configuration file qcrypto.conf in the path specified by the _CS_CONFIG_PATH configuration string (see the confstr() entry in the C Library Reference), if it is defined. Otherwise, it looks in default location /etc/qcrypto.conf. You can use qcrypto_set_config_path() to change this location before the library is initialized.

Format

The lines in the configuration file use the following format:

plugin tags=tag[,tag...]
where:
plugin
The name of the plugin DLL (qcrypto-plugin.so) without the .so extension.
tag
A comma-separated list of tags (keywords) that identify the library.
For example, the following example entry configures the qcrypto library to use the certicom plugin for requests that use the devb-eide tag:
certicom    tags=devb-eide

The qcrypto library ignores both empty lines and lines where the first character that is not a space is a pound sign (#).

You can use spaces and tabs as separators between parts, but don't use them in the tag definitions.

To avoid returning an error because no matching plugin is found, include a plugin with a tags value of * to handle all requests that would not otherwise find a matching tag. If you specify only one plugin, set the tags value to *.

If you don't define tags for a plugin, it cannot be matched and is never used to provide algorithms.

Tags

Tags redirect system components to use the cryptography plugin chosen by the system integrator. If a process doesn’t specify a tag value in a qcrypto_*_request() function, then the tag value used internally is __progname.

When the qcrypto_init() call specifies a plugin name, it creates an internal plugin entry with the tag __progname. When the qcrypto library searches for plugins with matching tags, it tries to match this entry before it tries to match any plugins in the configuration file.

Example

A system integrator creates the following configuration file:

plugin1    tags=foo,bar
plugin2    tags=myexe
plugin3    tags=*
In addition to this configuration, the system has an executable myexe that contains the following qcrypto_init() call. This call generates an additional plugin entry with the name of the executable as its tag:
qcrypto_init(flags, “plugin4”)
This call creates the following internal configuration:
plugin4    tags=myexe
plugin1    tags=foo,bar
plugin2    tags=myexe
plugin3    tags=*

When a qcrypto_*_request() function requests an algorithm with a tag value of NULL, it defaults to a tag of myexe (the value of __progname in this example). The qcrypto library searches for a matching algorithm in the plugins that match the tag in this order: plugin4, plugin2, plugin3. (The tag for plugin1 does not match.) It searches until it either finds a match that contains the algorithm, or reaches the end of the list and generates an error.