From 11f3f0effb14be788e320d2f75b0d2d769058966 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Wed, 14 Sep 2011 13:45:03 +0200 Subject: Add documentation about the configuration paths * Default module path * How to lookup paths using pkg-config --- doc/p11-kit-config.xml | 37 ++++++++++++++++++++++--------------- doc/p11-kit-docs.sgml | 1 + doc/p11-kit-notes.xml | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/p11-kit.xml | 3 +++ doc/style.css | 2 ++ 5 files changed, 76 insertions(+), 15 deletions(-) create mode 100644 doc/p11-kit-notes.xml diff --git a/doc/p11-kit-config.xml b/doc/p11-kit-config.xml index 76b3fa2..7c28f86 100644 --- a/doc/p11-kit-config.xml +++ b/doc/p11-kit-config.xml @@ -40,9 +40,11 @@ user-config: merge One module configuration file per module: /etc/pkcs11/modules/my-module -# This setting controls the actual module library to load. This config file might -# be installed by the package that installs this module library. -module: /usr/lib/my-pkcs11-module.so +# This setting controls the actual module library to load. This config file +# might be installed by the package that installs this module library. This +# is not an absolute path name. Relative path names are loaded from the +# $(libdir)/pkcs11 directory by default. +module: my-pkcs11-module.so # This controls whether the module is required to successfully initialize. If 'yes', then # a failure to load or initialize this module will result in a p11-kit system failure. @@ -110,20 +112,22 @@ critical: yes
Module Configuration - Each configured PKCS#11 module has its own config file. The - location(s) of these files are described below. Most importantly each - config file specifies the location of the PKCS#11 module to load. Each - module config file has the following fields: + Each configured PKCS#11 module has its own config file. These files + can be placed in various locations. + Most importantly each config file specifies the path of the PKCS#11 module to + load. A module config file has the following fields: module: - The absolute path to the PKCS#11 module to load. + The filename of the PKCS#11 module to load. This should include an extension like .so If this value is blank, then the module will be ignored. This can be used in the user configs to override loading of a module specified in the system configuration. + If this is a relative path, then the module will be loaded + from the default module directory. @@ -174,16 +178,19 @@ critical: yes files and a file for global configuration. Optionally each user can provide additional configuration or override the system configuration. - The system global configuration file is in + The system global configuration file is usually in /etc/pkcs11/pkcs11.conf and the user global configuration file is in ~/.pkcs11/pkcs11.conf in the user's home directory. - - The module config files are located in the - /etc/pkcs11/modules directory, with one configuration - file per module. In addition the ~/.pkcs11/modules - directory can be used for modules installed by the user. - + The module config files are usually located in the + /etc/pkcs11/modules directory, with one configuration + file per module. In addition the ~/.pkcs11/modules directory + can be used for modules installed by the user. + + The default system config file and module directory can be changed + when building p11-kit. Always + lookup these paths using + pkg-config.
diff --git a/doc/p11-kit-docs.sgml b/doc/p11-kit-docs.sgml index 1bfb571..8e8c933 100644 --- a/doc/p11-kit-docs.sgml +++ b/doc/p11-kit-docs.sgml @@ -13,6 +13,7 @@ + Reference diff --git a/doc/p11-kit-notes.xml b/doc/p11-kit-notes.xml new file mode 100644 index 0000000..e030824 --- /dev/null +++ b/doc/p11-kit-notes.xml @@ -0,0 +1,48 @@ + + + + Developer and Packager Notes + +
+ Using pkg-config to determine paths + + Developers or packagers of PKCS#11 modules need to install various + files into specific locations so that p11-kit will recognize and load the + module correctly. + + You should use pkg-config as described below + to determine configuration paths. p11-kit installs a + pkg-config file called p11-kit-1.pc. + This file contains all the information about the various paths that p11-kit + looks for files at. + +
+ Path to place module configuration + + As described in the module configuration + documentation, each PKCS#11 module should install a config file describing + that module. These config files should be installed to a specific directory which + can be determined by running: + + +$ pkg-config p11-kit-1 --variable p11_system_config_modules +/etc/pkcs11/modules +
+ +
+ Default path for modules with relative paths + + If a module configuration + contains a relative path in its module: setting, + then that module will be loaded from the default module path. This + path can be determined by running: + + +$ pkg-config p11-kit-1 --variable p11_module_path +/usr/lib64/pkcs11 +
+ +
+ + diff --git a/doc/p11-kit.xml b/doc/p11-kit.xml index a040da8..3c8a318 100644 --- a/doc/p11-kit.xml +++ b/doc/p11-kit.xml @@ -33,5 +33,8 @@ + + + diff --git a/doc/style.css b/doc/style.css index 67ffff3..a4aa19e 100644 --- a/doc/style.css +++ b/doc/style.css @@ -79,5 +79,7 @@ H2 { } H3 { + position: relative; + left: -1em; font-weight: normal !important; } -- cgit v1.1