From c6ebe7eb68e07e4f22c7b7ede14a1e4f04e893b7 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Fri, 15 Feb 2013 20:56:11 +0100 Subject: Move pkcs11.conf and module documentation to a manual page --- .gitignore | 1 + doc/Makefile.am | 19 ++++- doc/p11-kit-config.xml | 166 +++------------------------------------ doc/p11-kit-docs.sgml | 3 +- doc/p11-kit.xml | 5 +- doc/pkcs11.conf.xml | 207 +++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 239 insertions(+), 162 deletions(-) create mode 100644 doc/pkcs11.conf.xml diff --git a/.gitignore b/.gitignore index d0abc67..ee5c6b3 100644 --- a/.gitignore +++ b/.gitignore @@ -73,6 +73,7 @@ temp.txt /doc/tmpl/ /doc/version.xml /doc/xml/ +/doc/*.5 /doc/*.8 /p11-kit/p11-kit.pc diff --git a/doc/Makefile.am b/doc/Makefile.am index 4fd8d54..b27980e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -89,8 +89,8 @@ GTKDOC_LIBS= include $(top_srcdir)/gtk-doc.make if ENABLE_GTK_DOC -man8_MANS = \ - p11-kit.8 +man8_MANS = p11-kit.8 +man5_MANS = pkcs11.conf.5 XSLTPROC_FLAGS = \ --nonet \ @@ -100,22 +100,33 @@ XSLTPROC_FLAGS = \ --stringparam man.authors.section.enabled 0 \ --stringparam man.copyright.section.enabled 0 +XSLTPROC_MAN = \ + $(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl + +.xml.5: + $(AM_V_GEN) $(XSLTPROC_MAN) $< .xml.8: - $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< + $(AM_V_GEN) $(XSLTPROC_MAN) $< else # ENABLE_GTK_DOC +man5_MANS = man8_MANS = endif # ENABLE_GTK_DOC -MAN_IN_FILES = $(man8_MANS:.8=.xml) +MAN_IN_FILES = \ + $(man8_MANS:.8=.xml) \ + $(man5_MANS:.5=.xml) \ + $(NULL) CLEANFILES += \ + $(man5_MANS) \ $(man8_MANS) \ $(NULL) EXTRA_DIST += \ + $(MAN_IN_FILES) \ version.xml.in \ version.xml \ $(NULL) diff --git a/doc/p11-kit-config.xml b/doc/p11-kit-config.xml index da413e0..ca07769 100644 --- a/doc/p11-kit-config.xml +++ b/doc/p11-kit-config.xml @@ -75,162 +75,16 @@ critical: yes -
- File format +
+ Configuration Files - A complete configuration consists of several files. These files are - text files. Since p11-kit is built to be used in all - sorts of environments and at very low levels of the software stack, we - cannot make use of high level configuration APIs that you may find on a - modern desktop. + A complete configuration consists of several files. These files are + text files. Since p11-kit is built to be used in all + sorts of environments and at very low levels of the software stack, we + cannot make use of high level configuration APIs that you may find on a + modern desktop. - Each setting in the config file is specified consists of a name and - a value. The name is a simple string consisting of characters and dashes. - The name consists of alpha numeric characters, dot, hyphen and - underscore. - - The value is specified after the name on the same line, separated - from it by a : (colon). White space between the - name and value is ignored. - - Blank lines are ignored. White space at the beginning or end of - lines is stripped. Lines that begin with a # character - are ignored as comments. Comments are not recognized when they come after - a value on a line. - - A fictitious sample configuration file might look like: - - - name:value - # Here is a comment - - setting.2: A long value with text. - x-custom : text - -
- -
- Module Configuration - - Each configured PKCS#11 module has its own config file. These files - can be placed in various locations. - The filename of the configuration file may consist of upper and lowercase letters - underscore, comma, dash and dots. The first characters needs to be an alphanumeric, - the filename should end with a .module extension. - 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 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. - - - - critical: - - Set to yes if the module is critical and - required to load. If a critical module fails to load or initialize, - then the loading process for all registered modules will abort and - return an error code. - This argument is optional and defaults to no. - - - - enable-in: - - A comma and/or space separated list of names of programs that - this module should only be loaded in. The module will not be loaded - for other programs using p11-kit. The base name of the process executable - should be used here, for example - seahorse, ssh. - This is not a security feature. The argument is optional. If - not present, then any process will load the module. - - - - disable-in: - - A comma and/or space separated list of names of programs that - this module should not be loaded in. The module will be loaded for any - other programs using p11-kit. The base name of the process - executable should be used here, for example - firefox, thunderbird-bin. - This is not a security feature. The argument is optional. If - not present, then any process will load the module. - - - - trust-policy - - If this setting is present then this module is used to load - trust policy information such as certificate anchors and black lists. - The value should be an integer. Modules with a lower number are loaded - first. Trust policy information in modules loaded later overrides - those loaded first. - - - - - Do not specify both enable-in and disable-in - for the same module. - - Other fields may be present, but it is recommended that field names - that are not specified in this document start with a x- - prefix. -
- -
- Global Configuration - - A global configuration is also present. This file contains settings - that are not related to a single PKCS#11 module. The location(s) of the - global configuration are described below. The global configuration file - can contain the following fields: - - - - user-config: - This will be equal to one of the following values: - none, merge, - only. - - - - Other fields may be present, but it is recommended that field names - that are not specified in this document start with a x- - prefix. -
- -
- Configuration Files - - Each configured PKCS#11 module is has its own config file. These - files are placed in a directory. In addition a global config file exists. - There is a system configuration consisting of the various module config - 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 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 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. -
+ See the manual page for more details + on the format and available options. +
diff --git a/doc/p11-kit-docs.sgml b/doc/p11-kit-docs.sgml index 7138690..0397169 100644 --- a/doc/p11-kit-docs.sgml +++ b/doc/p11-kit-docs.sgml @@ -16,8 +16,9 @@ - Command Line Tools + Manual Pages + diff --git a/doc/p11-kit.xml b/doc/p11-kit.xml index 98f5da5..95b1c3e 100644 --- a/doc/p11-kit.xml +++ b/doc/p11-kit.xml @@ -217,7 +217,10 @@ $ p11-kit extract-trust See also - + + pkcs11.conf5 + + Further details available in the p11-kit online documentation at http://p11-glue.freedesktop.org/doc/p11-kit/. diff --git a/doc/pkcs11.conf.xml b/doc/pkcs11.conf.xml new file mode 100644 index 0000000..974cdf6 --- /dev/null +++ b/doc/pkcs11.conf.xml @@ -0,0 +1,207 @@ + + + + + + + pkcs11.conf + p11-kit + + + Maintainer + Stef + Walter + stef@thewalter.net + + + + + + pkcs11.conf + 5 + System Files + + + + pkcs11.conf + Configuration files for PKCS#11 modules + + + + Description + The pkcs11.conf configuration files are a standard + way to configure PKCS#11 modules. + + + + File format + A complete configuration consists of several files. These files are + text files. Since p11-kit is built to be used in all + sorts of environments and at very low levels of the software stack, we + cannot make use of high level configuration APIs that you may find on a + modern desktop. + + Each setting in the config file is specified consists of a name and + a value. The name is a simple string consisting of characters and dashes. + The name consists of alpha numeric characters, dot, hyphen and + underscore. + + The value is specified after the name on the same line, separated + from it by a : (colon). White space between the + name and value is ignored. + + Blank lines are ignored. White space at the beginning or end of + lines is stripped. Lines that begin with a # character + are ignored as comments. Comments are not recognized when they come after + a value on a line. + + A fictitious module configuration file might look like: + +module: module.so +# Here is a comment + +managed: true +setting.2: A long value with text. +x-custom : text + + + + + Module Configuration + + Each configured PKCS#11 module has its own config file. These files + can be placed in various locations. + The filename of the configuration file may consist of upper and lowercase letters + underscore, comma, dash and dots. The first characters needs to be an alphanumeric, + the filename should end with a .module extension. + 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 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. + + + + critical: + + Set to yes if the module is critical and + required to load. If a critical module fails to load or initialize, + then the loading process for all registered modules will abort and + return an error code. + + This argument is optional and defaults to no. + + + + enable-in: + + A comma and/or space separated list of names of programs that + this module should only be loaded in. The module will not be loaded + for other programs using p11-kit. The base name of the process executable + should be used here, for example + seahorse, ssh. + This is not a security feature. The argument is optional. If + not present, then any process will load the module. + + + + disable-in: + + A comma and/or space separated list of names of programs that + this module should not be loaded in. The module will be loaded for any + other programs using p11-kit. The base name of the process + executable should be used here, for example + firefox, thunderbird-bin. + This is not a security feature. The argument is optional. If + not present, then any process will load the module. + + + + trust-policy + + If this setting is present then this module is used to load + trust policy information such as certificate anchors and black lists. + The value should be an integer. Modules with a lower number are loaded + first. Trust policy information in modules loaded later overrides + those loaded first. + + + + + Do not specify both enable-in and disable-in + for the same module. + + Other fields may be present, but it is recommended that field names + that are not specified in this document start with a x- + prefix. + + + + Global Configuration + + A global configuration may also be present. This file contains settings + that are not related to a single PKCS#11 module. The location(s) of the + global configuration are described below. The global configuration file + can contain the following fields: + + + + user-config: + This will be equal to one of the following values: + none, merge, + only. + + + + Other fields may be present, but it is recommended that field names + that are not specified in this document start with a x- + prefix. + + + + Configuration Files + + Each configured PKCS#11 module is has its own config file. These + files are placed in a directory. In addition a global config file exists. + There is a system configuration consisting of the various module config + 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 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 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. + + + + See also + + p11-kit8 + + Further details available in the p11-kit online documentation at + http://p11-glue.freedesktop.org/doc/p11-kit/. + + + + -- cgit v1.1