From df29c0dcb6cce6a215dee9dc4e17aff59ae67c5b Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Mon, 11 Mar 2013 10:56:07 +0100 Subject: doc: Move manual into doc/manual subdirectory --- doc/manual/Makefile.am | 132 ++++++++++++++++ doc/manual/annotation-glossary.xml | 67 +++++++++ doc/manual/docbook-params.xsl | 39 +++++ doc/manual/p11-kit-config.xml | 90 +++++++++++ doc/manual/p11-kit-devel.xml | 299 +++++++++++++++++++++++++++++++++++++ doc/manual/p11-kit-docs.sgml | 42 ++++++ doc/manual/p11-kit-overrides.txt | 0 doc/manual/p11-kit-sections.txt | 106 +++++++++++++ doc/manual/p11-kit-sharing.xml | 92 ++++++++++++ doc/manual/p11-kit-trust.xml | 112 ++++++++++++++ doc/manual/p11-kit.xml | 229 ++++++++++++++++++++++++++++ doc/manual/pkcs11.conf.xml | 207 +++++++++++++++++++++++++ doc/manual/style.css | 116 ++++++++++++++ doc/manual/version.xml.in | 1 + 14 files changed, 1532 insertions(+) create mode 100644 doc/manual/Makefile.am create mode 100644 doc/manual/annotation-glossary.xml create mode 100644 doc/manual/docbook-params.xsl create mode 100644 doc/manual/p11-kit-config.xml create mode 100644 doc/manual/p11-kit-devel.xml create mode 100644 doc/manual/p11-kit-docs.sgml create mode 100644 doc/manual/p11-kit-overrides.txt create mode 100644 doc/manual/p11-kit-sections.txt create mode 100644 doc/manual/p11-kit-sharing.xml create mode 100644 doc/manual/p11-kit-trust.xml create mode 100644 doc/manual/p11-kit.xml create mode 100644 doc/manual/pkcs11.conf.xml create mode 100644 doc/manual/style.css create mode 100644 doc/manual/version.xml.in (limited to 'doc/manual') diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am new file mode 100644 index 0000000..59c8624 --- /dev/null +++ b/doc/manual/Makefile.am @@ -0,0 +1,132 @@ +abs_top_builddir = @abs_top_builddir@ + +NULL = + +# We require automake 1.6 at least. +AUTOMAKE_OPTIONS = 1.6 + +# The name of the module, e.g. 'glib'. +DOC_MODULE=p11-kit + +# The top-level SGML file. You can change this if you want to. +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml + +# The directory containing the source code. Relative to $(srcdir). +# gtk-doc will search all .c & .h files beneath here for inline comments +# documenting the functions and macros. +# e.g. DOC_SOURCE_DIR=../../../gtk +DOC_SOURCE_DIR=../../p11-kit + +# Extra options to pass to gtkdoc-scangobj. Not normally needed. +SCANGOBJ_OPTIONS= --version + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS= --rebuild-types --deprecated-guards="P11_KIT_DISABLE_DEPRECATED" + +# Extra options to supply to gtkdoc-mkdb. +# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml +MKDB_OPTIONS=--sgml-mode --output-format=xml + +# Extra options to supply to gtkdoc-mktmpl +# e.g. MKTMPL_OPTIONS=--only-section-tmpl +MKTMPL_OPTIONS= + +# Extra options to supply to gtkdoc-fixref. Not normally needed. +# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +FIXXREF_OPTIONS= + +# Used for dependencies. The docs will be rebuilt if any of these change. +# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h +# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c +HFILE_GLOB=$(top_srcdir)/p11-kit/*.h +CFILE_GLOB=$(top_srcdir)/p11-kit/*.c + +# Header files to ignore when scanning. +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h +IGNORE_HFILES= \ + private.h \ + pkcs11.h \ + conf.h \ + debug.h \ + dict.h \ + mock-module.h \ + pkcs11.h \ + pkcs11x.h \ + private.h \ + util.h \ + array.h \ + compat.h \ + mock-module.h + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +HTML_IMAGES= + +# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). +# e.g. content_files=running.sgml building.sgml changes-2.0.sgml +content_files=p11-kit-config.xml p11-kit-sharing.xml \ + p11-kit-devel.xml \ + p11-kit-trust.xml \ + p11-kit.xml \ + annotation-glossary.xml \ + $(NULL) + +# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded +# These files must be listed here *and* in content_files +# e.g. expand_content_files=running.sgml +expand_content_files= + +# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. +# Only needed if you are using gtkdoc-scangobj to dynamically query widget +# signals and properties. +# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +INCLUDES= +GTKDOC_LIBS= + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/gtk-doc.make + +if ENABLE_GTK_DOC +man8_MANS = p11-kit.8 +man5_MANS = pkcs11.conf.5 + +XSLTPROC_FLAGS = \ + --nonet \ + --stringparam man.output.quietly 1 \ + --stringparam funcsynopsis.style ansi \ + --stringparam man.th.extra1.suppress 1 \ + --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_MAN) $< + +else # ENABLE_GTK_DOC + +man5_MANS = +man8_MANS = + +endif # ENABLE_GTK_DOC + +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/manual/annotation-glossary.xml b/doc/manual/annotation-glossary.xml new file mode 100644 index 0000000..4a0f8a6 --- /dev/null +++ b/doc/manual/annotation-glossary.xml @@ -0,0 +1,67 @@ + + +]> + + +Annotation Glossary +A + + allow-none + + NULL is ok, both for passing and for returning. + + + + array + + Parameter points to an array of items. + + + +E + + element-type + + Generics and defining elements of containers and arrays. + + + +I + + inout + + Parameter for input and for returning results. Default is transfer full. + + + +O + + out + + Parameter for returning results. Default is transfer full. + + + +T + + transfer full + + Free data after the code is done. + + + + type + + Override the parsed C type with given type + + + + transfer none + + Don't free data after the code is done. + + + + \ No newline at end of file diff --git a/doc/manual/docbook-params.xsl b/doc/manual/docbook-params.xsl new file mode 100644 index 0000000..5d8591a --- /dev/null +++ b/doc/manual/docbook-params.xsl @@ -0,0 +1,39 @@ + + + + + + + + 3 + 0 + + book toc + part nop + chapter toc + + style.css + ansi + 1 + 0 + 1 + + diff --git a/doc/manual/p11-kit-config.xml b/doc/manual/p11-kit-config.xml new file mode 100644 index 0000000..ca07769 --- /dev/null +++ b/doc/manual/p11-kit-config.xml @@ -0,0 +1,90 @@ + + + + PKCS#11 Configuration + +
+ Consistent configuration + + In order for multiple applications on the user's desktop to use + PKCS#11 modules in a consistent manner, there must be a configuration + or registry to specify which modules to load and how to use them. The + PKCS#11 specification does not specify such a configuration standard. + + + Because of the multi-library module initialization problem, use of + PKCS#11 modules must be coordinated within an application. p11-kit + provides that coordination. Since coordination is required, it follows + that p11-kit can also implement a consistent module configuration. + +
+ +
+ Example + + The following sections describe the config format in detail. But first + an example which shows the various features. The configuration below, loads + two modules called 'my-module' and 'nss'. The user settings override some + aspects of the system settings. + +Global configuration file: /etc/pkcs11/pkcs11.conf + +# This setting controls whether to load user configuration from the +# ~/.pkcs11 directory. Possible values: +# none: No user configuration +# merge: Merge the user config over the system configuration (default) +# only: Only user configuration, ignore system configuration +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. 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. +critical: no + + +User configuration file: ~/.pkcs11/pkcs11.conf + +# This is an empty file. Files that do not exist are treated as empty. + + +User configuration file: ~/.pkcs11/modules/my-module + +# Merge with the settings in the system my-module config file. In this case +# a developer has overridden to load a different module for my-module instead. +module: /home/user/src/custom-module/my-module.so + + +User configuration file: ~/.pkcs11/modules/nss + +# Load the NSS libsoftokn.so.3 PKCS#11 library as a module. Note that we pass +# some custom non-standard initialization arguments, as NSS expects. +module: /usr/lib/libsoftokn3.so +x-init-reserved: configdir='sql:/home/test/.pki/nssdb' certPrefix='' keyPrefix='' secmod='socmod.db' +critical: yes + + + +
+ +
+ 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. + + See the manual page for more details + on the format and available options. +
+ diff --git a/doc/manual/p11-kit-devel.xml b/doc/manual/p11-kit-devel.xml new file mode 100644 index 0000000..bbe6c0a --- /dev/null +++ b/doc/manual/p11-kit-devel.xml @@ -0,0 +1,299 @@ + + + + Building, Packaging, and Contributing to p11-kit + + + +
+ Packaging PKCS#11 module configs + + 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_module_configs +/usr/share/p11-kit/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 +
+ +
+ +
+ Customizing installed commands + + The p11-kit tool provides a + extract-trust command which extracts trust + policy information such as certificate anchors and so on + into files for use with libraries that cannot read this trust + information directly. + + In order to be useful the extract-trust + command needs to be customized per distribution or site. You can + find this file in at tools/p11-kit-trust-extract.in + in the p11-kit source code. + + The command is implemented as a simple script which + performs the various p11-kit extract commands + necessary to extract the information. + + Using this script as a standard way to extract this + information allows for consistency between distributions and ease + of system administration. +
+ +
+ Compiling p11-kit from Source + This describes how to compiling the p11-kit package from + source code. This is normally only necessary for those wishing to + contribute to the project or package p11-kit. + + You can download + tarballs + of the releases of p11-kit or + check + out the source code from git. This documentation will not + go into all the details of how to get your development environment + set up and instead focus on the what's unique to compiling p11-kit. + +
+ Building on UNIX + p11-kit uses the standard GNU build system, using autoconf for package + configuration and resolving portability issues, automake for building makefiles + that comply with the GNU Coding Standards, and libtool for building shared + libraries on multiple platforms. The normal sequence for compiling and + installing the p11-kit library is thus: + + +$ ./configure --prefix=/path/to/prefix ... +$ make +$ make install + + + If you've checked out the source code from git, then the + configure script does not yet exist. So use + the following instead: + + +$ ./autogen.sh --prefix=/path/to/prefix ... +$ make +$ make install + + + The standard options provided by GNU autoconf may be passed to the configure + script. Please see the autoconf documentation or run ./configure --help + for information about the standard options. In particular you probably want to adjust + the --prefix=/xxx argument depending on your system and development + environment. +
+ +
+ Optional Dependencies + + On a modern GNU Linux system, p11-kit has no required dependencies other + than the standard C library. However on older UNIX systems, some of the following + may be required. + + + gettext is required if your system doesn't + have the gettext() functionality for handling message + translation databases. This can be provided by the libintl library from + the GNU gettext + package. + pthread is required if your (ancient) system + doesn't have this included in the base system. How this is provided is platform + specific. + + + In addition p11-kit has several optional dependencies. If these are not available + during the build, then certain features will be disabled. + + + gtk-doc is required to build the reference + manual. Use --enable-doc to control this + dependency. + xsltproc is required to build the command + manual pages. Use --enable-doc to control this + dependency. + libtasn1 is required to build the trust + module and code that interacts with certificates. + + +
+ +
+ Extra Configuration Options + + In addition to the normal options, the configure script in the p11-kit library + supports these additional arguments: + + + + + Disables building of the trust policy module. + + + , + By default p11-kit is built with debug symbols assertions and + and precondition checks. Enabling the debug option configures even more + detailed debug build, including disabling optimization. Disabling the debug + option is not recommended, as it disables all assertions, preconditions and + internal consistency checks, although it may result it a slightly faster + library. + + + + Enables building of the documentation and command line manual. + The documentation is built in the doc/html/ directory of + the build. Requires the gtk-doc and xsltproc + dependencies. + + + + Enables strict checks during building of p11-kit. All + compiler warnings become errors. + + + , + Build with a dependency on the libtasn1 library. This dependency + allows the trust policy module to be built as well as other code that interacts with + certificates. + + + + Specify the path to look for PKCS#11 modules which were + listed in a module config file with a relative path. + + + + Specify the files or directories to look for system + certificate anchors. Multiple files and/or directories are specified with + a : in between them. + + + + Specify the files or directories to look for other + non-anchor system certificates. Multiple files and/or directories are + specified with a : in between them. + + + + Specify the path to look for p11-kit config files. This + usually defaults to something like /etc/pkcs11 + + + +
+
+ +
+ Coding Style + + We use a code style similar to the linux kernel. Use tabs + to indent and spaces to align/wrap beyond the indentation level. + + We don't try to guarantee completely robust and problem free + behavior in cases where the caller or system isn't behaving. We + consider these to be outside of our control: + + + Broken input from callers. We use preconditions + to check input and immediately return. We don't try to provide + error codes for all the various ways callers can screw + around. + + + Out of memory. It is pretty much impossible to handle out + of memory errors correctly. Handling them alongside other errors + is naive and broken. We don't try to guarantee library state + (such as locks or memory leaks) when memory allocation fails. + We do check the results from all memory allocations, but + treat them as unexpected conditions. As a nod to the behavior + of callers of this library, we don't abort on memory allocation + failures. We use preconditions with somewhat sane results. + Exception: when reading files or allocating potentially + unbounded amounts of memory, we should respond robustly to memory + allocation failures. + + + + These unexpected conditions indicate a bug either in p11-kit or + in the system. All bets are off once this occurs. + + Use the return_val_xxx() precondition macros to + check for unexpected conditions. +
+ +
+ Testing and Code Coverage + + As a general rule changes to p11-kit should have a tests exercising + that change. Use the make check command to run all + the tests. If you run it from a subdirectory only the tests in that + directory will be run. + + Build p11-kit with the configure + option to build code coverage support. + + Once you've done that you can either use make coverage + to build code coverage information. Alternatively (and this is usually + easier) you can use + + git coverage to easily check whether + you've tested the lines changed by a patch. + + A code coverage report is + available online. +
+ +
+ Debugging Tips + + Unexpected conditions will produce critical warnings by p11-kit. + These are often failed internal preconditions, and usually indicate a + bug either in p11-kit or the software calling it. + + You can use the environment variable P11_KIT_STRICT=yes + to make p11-kit do an abort() (and core dump depending on + your configuration) when a critical warning occurs. +
+ diff --git a/doc/manual/p11-kit-docs.sgml b/doc/manual/p11-kit-docs.sgml new file mode 100644 index 0000000..0397169 --- /dev/null +++ b/doc/manual/p11-kit-docs.sgml @@ -0,0 +1,42 @@ + + + +]> + + + p11-kit + for p11-kit &version; + + + + + + + + Manual Pages + + + + + + API Reference + + + + + + + + API Index + + + + + + + + + diff --git a/doc/manual/p11-kit-overrides.txt b/doc/manual/p11-kit-overrides.txt new file mode 100644 index 0000000..e69de29 diff --git a/doc/manual/p11-kit-sections.txt b/doc/manual/p11-kit-sections.txt new file mode 100644 index 0000000..dc85f2d --- /dev/null +++ b/doc/manual/p11-kit-sections.txt @@ -0,0 +1,106 @@ +
+p11-kit-uri +P11_KIT_URI_SCHEME +P11_KIT_URI_SCHEME_LEN +P11KitUriType +P11KitUriResult +P11KitUri +p11_kit_uri_new +p11_kit_uri_get_module_info +p11_kit_uri_match_module_info +p11_kit_uri_get_token_info +p11_kit_uri_match_token_info +p11_kit_uri_get_attributes +p11_kit_uri_set_attributes +p11_kit_uri_clear_attributes +p11_kit_uri_match_attributes +p11_kit_uri_get_attribute +p11_kit_uri_set_attribute +p11_kit_uri_clear_attribute +p11_kit_uri_set_unrecognized +p11_kit_uri_any_unrecognized +p11_kit_uri_get_pin_source +p11_kit_uri_set_pin_source +p11_kit_uri_get_pinfile +p11_kit_uri_set_pinfile +p11_kit_uri_format +p11_kit_uri_parse +p11_kit_uri_free +p11_kit_uri_message +P11_KIT_URI_NO_MEMORY +
+ +
+p11-kit-pin +P11KitPin +p11_kit_pin_new +p11_kit_pin_new_for_buffer +p11_kit_pin_new_for_string +p11_kit_pin_get_value +p11_kit_pin_get_length +p11_kit_pin_ref +p11_kit_pin_unref +P11KitPinFlags +P11_KIT_PIN_FALLBACK +p11_kit_pin_register_callback +p11_kit_pin_unregister_callback +p11_kit_pin_callback +p11_kit_pin_request +p11_kit_pin_destroy_func +p11_kit_pin_file_callback +
+ +
+p11-kit +p11_kit_initialize_registered +p11_kit_finalize_registered +p11_kit_registered_modules +p11_kit_registered_module_to_name +p11_kit_registered_name_to_module +p11_kit_registered_option +p11_kit_initialize_module +p11_kit_load_initialize_module +p11_kit_finalize_module +
+ +
+p11-kit-util +p11_kit_strerror +p11_kit_space_strdup +p11_kit_space_strlen + +CK_FUNCTION_LIST_PTR +CK_RV +CK_ATTRIBUTE_PTR +CK_ATTRIBUTE_TYPE +CK_INFO_PTR +CK_TOKEN_INFO_PTR +CK_ULONG +p11_kit_uri_result_t +p11_kit_uri_type_t +
+ +
+p11-kit-future +p11_kit_set_progname +p11_kit_be_quiet +p11_kit_be_loud +p11_kit_message +p11_kit_destroyer +P11KitIter +p11_kit_iter_new +p11_kit_iter_set_session_flags +p11_kit_iter_add_callback +p11_kit_iter_callback +p11_kit_iter_add_filter +p11_kit_iter_begin +p11_kit_iter_begin_with +p11_kit_iter_next +p11_kit_iter_get_module +p11_kit_iter_get_slot +p11_kit_iter_get_session +p11_kit_iter_keep_session +p11_kit_iter_get_object +p11_kit_iter_load_attributes +p11_kit_iter_free +
diff --git a/doc/manual/p11-kit-sharing.xml b/doc/manual/p11-kit-sharing.xml new file mode 100644 index 0000000..a1c19a7 --- /dev/null +++ b/doc/manual/p11-kit-sharing.xml @@ -0,0 +1,92 @@ + + + + Sharing PKCS#11 modules + +
+ Multiple consumers of PKCS#11 in a process + + As more and more applications and libraries use PKCS#11 we run + into a very basic problem. The PKCS#11 modules cannot be initialized and + finalized properly without coordination between the various consumers. + + + An example: An application might use GnuTLS for + TLS connections, and use libgcr for display of certificates. Both of + these want to load (and initialze) the same PKCS#11 modules. There are + many places where this situation occurs, including large applications + like Evolution which due to their dependencies end up using both NSS and + GnuTLS. + + Consumer A loads a PKCS#11 module and uses the module's + C_Initialize function to initialize it, which works as expected. + When consumer B initializes the module (also using C_Initialize), + the error code CKR_CRYPTOKI_ALREADY_INITIALIZED + is correctly returned. This is normal PKCS#11 specification + defined behavior for when a module is initalized twice in the + same process. If consumer B is aware of this situation they may + choose to ignore this error code. + + However when the consumer A is done with its use of the + PKCS#11 module it finalizes the module using the module's + C_Finalize function. This is expected of a well behaved PKCS#11 + consumer. This then causes errors and/or crashes for consumer B, + which cannot know that the module has now been finalized out + from underneath it. + + It is necessary for the two consumers to coordinate their + initialization and finalization in some fashion. In + p11-kit we provide this coordination in a + loosely coupled, backwards compatible, and flexible way. +
+ +
+ Solution: p11-kit + + p11-kit provides functions to + coordinate initialization and finalization of any PKCS#11 + module. A module may be initialized any number of times using + the p11_kit_initialize_module() function. The first time that + p11_kit_initialize_module() is called for a module, that module's + C_Initialize function is used. Later invocations for the same + module cause p11-kit to increment an internal initialization + count, rather than calling C_Initialize again. + + The p11_kit_finalize_module() is used to finalize a module. + Each time it is called it decrements the internal initialization + count for that module. When the internal initialization count + reaches zero, the module's C_Finalize function is called. + + This is done in a thread-safe manner. These functions can + be used on modules that the consumer loads themselves. +
+ +
+ Solution: proxy module + + When an application is aware of the fact that coordination + is necessary between multiple consumers of a PKCS#11 module, it + can link to p11-kit and use the functions there to provide + this coordination. + + However most current consumers of PKCS#11 are ignorant of + this problem, and do not link to p11-kit. In order to solve this + multiple initialization problem for all applications, + p11-kit provides a proxy compatibility + module. + + This proxy module acts like a normal PKCS#11 module, but + internally loads a preconfigured set of PKCS#11 modules and + coordinates their initialization and finalization. Each slot + in the configured modules is exposed as a slot of the + p11-kit proxy module. The proxy module is + then used as a normal PKCS#11 module would be. It can be loaded by + crypto libraries like NSS and behaves as expected. + + The proxy module bends the PKCS#11 rules slightly. It does + not return the CKR_CRYPTOKI_ALREADY_INITIALIZED + error code as specified in PKCS#11. However this is a small + price to pay for this compatibility. +
+ diff --git a/doc/manual/p11-kit-trust.xml b/doc/manual/p11-kit-trust.xml new file mode 100644 index 0000000..0e06446 --- /dev/null +++ b/doc/manual/p11-kit-trust.xml @@ -0,0 +1,112 @@ + + + +Trust Policy Module + + The trust module provides system certificate anchors, blacklists + and other trust policy to crypto libraries applications. This + information is exposed as PKCS#11 objects. + +
+ Files loaded by the Module + + The trust module loads certificates and trust policy information + from preconfigured directories and allows them to be looked up via + PKCS#11. The directories can be determined with using the following + commands: + + + + System Anchors: certificates in these locations + are automatically treated as certificate authority anchors + unless they contain information that prevents that. To check + which locations are being used, run the following command: + +$ pkg-config --variable p11_system_anchors p11-kit-1 +/etc/pki/tls/certs/ca-bundle.trust.crt:/etc/pki/tls/anchors + + + + System Certificates: certificates in these locations + are not treated as anchors, but simply made available through + the module. To find out which directory is used, run the + following command: + +$ pkg-config --variable p11_system_certificates p11-kit-1 +/etc/pki/tls/other-certs + + + + + Files in the following formats are supported for loading by the + trust policy module: + + + + X.509 certificates + X.509 certificates in raw DER format. + + + OpenSSL trust certificates + OpenSSL specific certificates in PEM format + that contain trust information. These have a + TRUSTED CERTIFICATE PEM header. Both + trust policy and blacklist information can be loaded + from these files. + + +
+ +
+ Using the Trust Policy Module with NSS + + The trust policy module is a drop in replacement for the + libnssckbi.so module and thus works out of + the box with NSS. The trust policy module provides NSS style + PKCS#11 trust objects for NSS to retrieve. + + The module may be used to replace the + libnssckbi.so file via an distribution + specific alternatives mechanism or otherwise. + + Alternatively NSS applications like Firefox or Thunderbird + may be configured to use the trust policy module by adding + the p11-kit-trust.so PKCS#11 module via their + GUI or command line configuration. +
+ +
+ Using the Trust Policy Module with glib-networking + + The trust policy module can be used as a source of trust + information for glib-networking's gnutls-pkcs11 backend. + The module provides PKCS#11 trust assertion objects as expected. + + The module should work by default if the gnutls-pkcs11 + backend is selected as the glib-networking TLS backend. +
+ +
+ Disabling the Trust Policy Module + + This module is installed and enabled by default. It may + be disabled in the following ways: + + + Use the + during the p11-kit + build. + Disable loading trust policy information + from this module by adding a file to /etc/pkcs11/modules + called p11-kit-trust.module containing a + trust-policy: line. + Disable this module completely by + adding a file to /etc/pkcs11/modules + called p11-kit-trust.module containing a + enable-in: line. + + +
+ + diff --git a/doc/manual/p11-kit.xml b/doc/manual/p11-kit.xml new file mode 100644 index 0000000..5242b1a --- /dev/null +++ b/doc/manual/p11-kit.xml @@ -0,0 +1,229 @@ + + + + + + + p11-kit + p11-kit + + + Maintainer + Stef + Walter + stef@thewalter.net + + + + + + p11-kit + 8 + System Commands + + + + p11-kit + Tool for operating on configured PKCS#11 modules + + + + + p11-kit list-modules + + + p11-kit extract --filter=<what> + --format=<type> /path/to/destination + + + + + Description + p11-kit is a command line tool that + can be used to perform operations on PKCS#11 modules configured on the + system. + + See the various sub commands below. The following global options + can be used: + + + + + Run in verbose mode with debug + output. + + + + Run in quiet mode without warning or + failure messages. + + + + + + + List Modules + + List system configured PKCS#11 modules. + + +$ p11-kit list-modules + + + The modules, information about them and the tokens present in + the PKCS#11 modules will be displayed. + + + + + Extract + + Extract certificates from configured PKCS#11 modules. + + +$ p11-kit extract --format=x509-directory --filter=ca-certificates /path/to/directory + + + You can specify the following options to control what to extract. + The and arguments + should be specified. By default this command will not overwrite the + destination file or directory. + + + + + Specifies what certificates to export. + You can specify the following values: + + + + Certificate anchors (default) + + + + Blacklisted certificates + + + + All certificates + + + + A PKCS#11 URI + + + + + + + The format of the destination file or directory. + You can specify one of the following values: + + + + DER X.509 certificate file + + + + directory of X.509 certificates + + + + File containing one or more certificate PEM blocks + + + + Directory PEM files each containing one certifiacte + + + + OpenSSL specific PEM bundle of certificates + + + + Directory of OpenSSL specific PEM files + + + + Java keystore 'cacerts' certificate bundle + + + + + + + Overwrite output file or directory. + + + + Limit to certificates usable for the given purpose + You can specify one of the following values: + + + + For authenticating servers + + + + For authenticating clients + + + + For email protection + + + + For authenticated signed code + + + + An arbitrary purpose OID + + + + + + + + + + Extract Trust + + Extract standard trust information files. + + +$ p11-kit extract-trust + + + OpenSSL, GnuTLS and Java cannot currently read trust information + directly from the trust policy module. This command extracts trust + information such as certificate anchors for use by these libraries. + + What this command does, and where it extracts the files is + distribution or site specific. Packagers or administrators are expected + customize this command. + + + + + Bugs + + Please send bug reports to either the distribution bug tracker + or the upstream bug tracker at + https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&component=p11-kit. + + + + + 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/manual/pkcs11.conf.xml b/doc/manual/pkcs11.conf.xml new file mode 100644 index 0000000..3146f60 --- /dev/null +++ b/doc/manual/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: + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + 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: + + + + + 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/. + + + + diff --git a/doc/manual/style.css b/doc/manual/style.css new file mode 100644 index 0000000..3d0f951 --- /dev/null +++ b/doc/manual/style.css @@ -0,0 +1,116 @@ +@import url("gtk-doc.css"); + +TABLE.navigation { + background-color: #f9b631 !important; + border-width: 0 !important; + color: white; + font-family: Georgia, "Times New Roman", Times, serif; + height: 4em !important; +} + +TABLE.navigation TH { + font-size: 30pt !important; + font-weight: normal; + text-align: left !important; + padding-left: 10pt; +} + +TABLE.navigation TH:first-child { + padding-left: 40pt; +} + +.shortcuts { + color: white !important; +} + +.shortcuts a { + color: white !important; + font-family: Verdana, Arial, 'Bitstream Vera Sans', Helvetica, sans-serif; +} + +P.title { + font-size: 30pt !important; +} + +BODY { + padding-top: 5.5em !important; +} + +DIV.book, +DIV.refentry, +DIV.chapter, +DIV.index, +DIV.footer, +DIV.section { + font-family: Verdana, Arial, 'Bitstream Vera Sans', Helvetica, sans-serif; + font-size: 9.5pt; + line-height: 150%; +} + +BODY > DIV.book, +BODY > DIV.footer { + margin-left: 1em; + margin-right: 1em; +} + +BODY > DIV.refentry, +BODY > DIV.chapter, +BODY > DIV.index, +BODY > DIV.section { + margin-left: 3em; + margin-right: 1em; +} + +DIV.variablelist TABLE { + font-size: 9.5pt; + line-height: 150%; +} + +DIV.refsect1, +DIV.refsect2, +DIV.refsynopsisdiv { + margin-bottom: 3em !important; +} + +H1 { + position: relative; + left: -1em; + font-weight: normal !important; +} + +H2 { + position: relative; + left: -1em; + font-weight: normal !important; +} + +H3 { + position: relative; + left: -1em; + font-weight: normal !important; +} + +CODE.option { + white-space: nowrap; +} + +DIV.toc DL { + margin-top: 0; + margin-bottom: 0; +} + +DIV.book > DIV.toc > DL > DT { + margin-top: 1em; +} + +DIV.toc DT { + margin-bottom: 0.3em; +} + +TABLE.variablelist SPAN.term { + padding-right: 1em; +} + +DIV.cmdsynopsis { + font-family: monospace; +} diff --git a/doc/manual/version.xml.in b/doc/manual/version.xml.in new file mode 100644 index 0000000..27323da --- /dev/null +++ b/doc/manual/version.xml.in @@ -0,0 +1 @@ +@VERSION@ \ No newline at end of file -- cgit v1.1