diff options
Diffstat (limited to 'doc/manual')
-rw-r--r-- | doc/manual/Makefile.am | 169 | ||||
-rw-r--r-- | doc/manual/annotation-glossary.xml | 67 | ||||
-rw-r--r-- | doc/manual/docbook-params.xsl | 39 | ||||
-rw-r--r-- | doc/manual/p11-kit-config.xml | 98 | ||||
-rw-r--r-- | doc/manual/p11-kit-devel.xml | 323 | ||||
-rw-r--r-- | doc/manual/p11-kit-docs.xml | 45 | ||||
-rw-r--r-- | doc/manual/p11-kit-overrides.txt | 0 | ||||
-rw-r--r-- | doc/manual/p11-kit-proxy.xml | 29 | ||||
-rw-r--r-- | doc/manual/p11-kit-sections.txt | 136 | ||||
-rw-r--r-- | doc/manual/p11-kit-sharing.xml | 110 | ||||
-rw-r--r-- | doc/manual/p11-kit-trust.xml | 128 | ||||
-rw-r--r-- | doc/manual/p11-kit.xml | 131 | ||||
-rw-r--r-- | doc/manual/pkcs11.conf.xml | 281 | ||||
-rw-r--r-- | doc/manual/style.css | 116 | ||||
-rw-r--r-- | doc/manual/trust.xml | 372 |
15 files changed, 0 insertions, 2044 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am deleted file mode 100644 index c161b19..0000000 --- a/doc/manual/Makefile.am +++ /dev/null @@ -1,169 +0,0 @@ -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.xml - -# 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=$(top_srcdir)/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= - -# MKHTML_OPTIONS=--path="$(builddir)/html $(srcdir)/html" - -# 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 \ - log.h \ - mock.h \ - modules.h \ - pkcs11.h \ - pkcs11i.h \ - pkcs11x.h \ - private.h \ - proxy.h \ - rpc.h \ - rpc-message.h \ - util.h \ - virtual.h \ - array.h \ - compat.h \ - $(NULL) - -# Images to copy into HTML directory. -# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png -HTML_IMAGES= - -generate_files= \ - version.xml \ - userdir.xml \ - sysdir.xml \ - $(NULL) - -# 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-proxy.xml \ - p11-kit-trust.xml \ - p11-kit.xml \ - pkcs11.conf.xml \ - trust.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= $(generate_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) -GTKDOC_LIBS= - -# Hacks around gtk-doc brokenness for out of tree builds -$(builddir)/p11-kit-sections.txt: $(srcdir)/p11-kit-sections.txt - cp $(srcdir)/p11-kit-sections.txt $(builddir)/p11-kit-sections.txt -$(builddir)/p11-kit-overrides.txt: $(srcdir)/p11-kit-overrides.txt - cp $(srcdir)/p11-kit-overrides.txt $(builddir)/p11-kit-overrides.txt - -# Generate our files with variables -sysdir.xml: - $(AM_V_GEN) echo -n '$(p11_system_config)' > "$@" -userdir.xml: - $(AM_V_GEN) echo -n '$(p11_user_config)' > "$@" -version.xml: - $(AM_V_GEN) echo -n '$(VERSION)' > "$@" - -# This includes the standard gtk-doc make rules, copied by gtkdocize. -include $(top_srcdir)/build/gtk-doc.make - -if ENABLE_GTK_DOC -man1_MANS = trust.1 -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) --path $(builddir) \ - http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl - -trust.1: trust.xml $(generate_files) - $(AM_V_GEN) $(XSLTPROC_MAN) $< -pkcs11.conf.5: pkcs11.conf.xml $(generate_files) - $(AM_V_GEN) $(XSLTPROC_MAN) $< -p11-kit.8: p11-kit.xml $(generate_files) - $(AM_V_GEN) $(XSLTPROC_MAN) $< - -else # ENABLE_GTK_DOC - -man1_MANS = -man5_MANS = -man8_MANS = - -endif # ENABLE_GTK_DOC - -MAN_IN_FILES = \ - $(man8_MANS:.8=.xml) \ - $(man5_MANS:.5=.xml) \ - $(man1_MANS:.1=.xml) \ - $(NULL) - -CLEANFILES += \ - $(generate_files) \ - $(man1_MANS) \ - $(man5_MANS) \ - $(man8_MANS) \ - $(NULL) - -EXTRA_DIST += \ - $(MAN_IN_FILES) \ - $(NULL) diff --git a/doc/manual/annotation-glossary.xml b/doc/manual/annotation-glossary.xml deleted file mode 100644 index 4a0f8a6..0000000 --- a/doc/manual/annotation-glossary.xml +++ /dev/null @@ -1,67 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -<!ENTITY version SYSTEM "version.xml"> -]> - -<glossary id="annotation-glossary"> -<title>Annotation Glossary</title> -<glossdiv><title>A</title> - <glossentry> - <glossterm><anchor id="annotation-glossterm-allow-none"/>allow-none</glossterm> - <glossdef> - <para>NULL is ok, both for passing and for returning.</para> - </glossdef> - </glossentry> - <glossentry> - <glossterm><anchor id="annotation-glossterm-array"/>array</glossterm> - <glossdef> - <para>Parameter points to an array of items.</para> - </glossdef> - </glossentry> -</glossdiv> -<glossdiv><title>E</title> - <glossentry> - <glossterm><anchor id="annotation-glossterm-element-type"/>element-type</glossterm> - <glossdef> - <para>Generics and defining elements of containers and arrays.</para> - </glossdef> - </glossentry> -</glossdiv> -<glossdiv><title>I</title> - <glossentry> - <glossterm><anchor id="annotation-glossterm-inout"/>inout</glossterm> - <glossdef> - <para>Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.</para> - </glossdef> - </glossentry> -</glossdiv> -<glossdiv><title>O</title> - <glossentry> - <glossterm><anchor id="annotation-glossterm-out"/>out</glossterm> - <glossdef> - <para>Parameter for returning results. Default is <acronym>transfer full</acronym>.</para> - </glossdef> - </glossentry> -</glossdiv> -<glossdiv><title>T</title> - <glossentry> - <glossterm><anchor id="annotation-glossterm-transfer full"/>transfer full</glossterm> - <glossdef> - <para>Free data after the code is done.</para> - </glossdef> - </glossentry> - <glossentry> - <glossterm><anchor id="annotation-glossterm-type"/>type</glossterm> - <glossdef> - <para>Override the parsed C type with given type</para> - </glossdef> - </glossentry> - <glossentry> - <glossterm><anchor id="annotation-glossterm-transfer none"/>transfer none</glossterm> - <glossdef> - <para>Don't free data after the code is done.</para> - </glossdef> - </glossentry> -</glossdiv> -</glossary>
\ No newline at end of file diff --git a/doc/manual/docbook-params.xsl b/doc/manual/docbook-params.xsl deleted file mode 100644 index 5d8591a..0000000 --- a/doc/manual/docbook-params.xsl +++ /dev/null @@ -1,39 +0,0 @@ -<?xml version="1.0"?> -<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> - -<!-- - Parameters for DocBook transformation. - - Copyright (C) 2009 Michael Leupold <lemma@confuego.org> - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA ---> - - <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/> - - <xsl:param name="toc.max.depth">3</xsl:param> - <xsl:param name="generate.section.toc.level">0</xsl:param> - <xsl:param name="generate.toc"> - book toc - part nop - chapter toc - </xsl:param> - <xsl:param name="html.stylesheet">style.css</xsl:param> - <xsl:param name="funcsynopsis.style">ansi</xsl:param> - <xsl:param name="funcsynopsis.decoration">1</xsl:param> - <xsl:param name="refentry.generate.name">0</xsl:param> - <xsl:param name="refentry.generate.title">1</xsl:param> - -</xsl:stylesheet> diff --git a/doc/manual/p11-kit-config.xml b/doc/manual/p11-kit-config.xml deleted file mode 100644 index c580445..0000000 --- a/doc/manual/p11-kit-config.xml +++ /dev/null @@ -1,98 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" -[ - <!ENTITY sysdir SYSTEM "sysdir.xml"> - <!ENTITY userdir SYSTEM "userdir.xml"> -]> - -<chapter xml:id="config"> - <title>PKCS#11 Configuration</title> - - <section id="config-introduction"> - <title>Consistent configuration</title> - - <para>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. - </para> - - <para>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. - </para> - </section> - - <section id="config-example"> - <title>Example</title> - - <para>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.</para> - -<para>Global configuration file: <literal>&sysdir;/pkcs11.conf</literal></para> -<programlisting> -# This setting controls whether to load user configuration from the -# &userdir; 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 -</programlisting> - -<para>One module configuration file per module: <literal>&sysdir;/modules/my-module</literal></para> -<programlisting> -# 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 -</programlisting> - -<para>User configuration file: <literal>&userdir;/pkcs11.conf</literal></para> -<programlisting> -# This is an empty file. Files that do not exist are treated as empty. -</programlisting> - -<para>User configuration file: <literal>&userdir;/modules/my-module</literal></para> -<programlisting> -# 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 -</programlisting> - -<para>User configuration file: <literal>&userdir;/modules/nss</literal></para> -<programlisting> -# 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 -</programlisting> - - -</section> - -<section id="config-files"> - <title>Configuration Files</title> - - <para>A complete configuration consists of several files. These files are - text files. Since <literal>p11-kit</literal> 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.</para> - - <para><link linkend="pkcs11-conf">See the manual page</link> for more details - on the format and available options.</para> - - <para>Note that user configuration files are not loaded from the home - directory if running inside a setuid or setgid program.</para> -</section> -</chapter> diff --git a/doc/manual/p11-kit-devel.xml b/doc/manual/p11-kit-devel.xml deleted file mode 100644 index 2ce3f0c..0000000 --- a/doc/manual/p11-kit-devel.xml +++ /dev/null @@ -1,323 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> - -<chapter xml:id="devel"> - <title>Building, Packaging, and Contributing to p11-kit</title> - - <section id="devel-links"> - <title>Helpful Resources</title> - - <para>Use the following to find more information about - contributing to p11-kit beyond what's in this manual:</para> - - <itemizedlist> - <listitem><para><ulink url="http://p11-glue.freedesktop.org/p11-kit.html">Website</ulink></para></listitem> - <listitem><para><ulink url="mail:p11-glue@lists.freedesktop.org">Mailing list</ulink></para></listitem> - <listitem><para><ulink url="https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&component=p11-kit">Bugzilla</ulink></para></listitem> - </itemizedlist> - </section> - - <section id="devel-paths"> - <title>Packaging PKCS#11 module configs</title> - - <para>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.</para> - - <para>You should use <literal>pkg-config</literal> as described below - to determine configuration paths. p11-kit installs a - <literal>pkg-config</literal> file called <literal>p11-kit-1.pc</literal>. - This file contains all the information about the various paths that p11-kit - looks for files at.</para> - - <section id="devel-paths-config"> - <title>Path to place module configuration</title> - - <para>As described in the <link linkend="config-module">module configuration</link> - 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:</para> - - <programlisting> -$ <command>pkg-config p11-kit-1 --variable p11_module_configs</command> -/usr/share/p11-kit/modules</programlisting> - </section> - - <section id="devel-paths-modules"> - <title>Default path for modules with relative paths</title> - - <para>If a <link linkend="config-module">module configuration</link> - contains a relative path in its <literal>module:</literal> setting, - then that module will be loaded from the default module path. This - path can be determined by running:</para> - - <programlisting> -$ <command>pkg-config p11-kit-1 --variable p11_module_path</command> -/usr/lib64/pkcs11</programlisting> - </section> - - </section> - - <section id="devel-commands"> - <title>Customizing installed commands</title> - - <para>The <literal>p11-kit</literal> tool provides a - <literal>extract-trust</literal> 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.</para> - - <para>In order to be useful the <literal>extract-trust</literal> - command needs to be customized per distribution or site. You can - find this file in at <literal>tools/p11-kit-trust-extract.in</literal> - in the p11-kit source code.</para> - - <para>The command is implemented as a simple script which - performs the various <literal>p11-kit extract</literal> commands - necessary to extract the information.</para> - - <para>Using this script as a standard way to extract this - information allows for consistency between distributions and ease - of system administration.</para> - </section> - - <section id="devel-building"> - <title>Compiling p11-kit from Source</title> - <para>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.</para> - - <para>You can download - <ulink url="http://p11-glue.freedesktop.org/releases/">tarballs - of the releases</ulink> of p11-kit or - <ulink url="http://cgit.freedesktop.org/p11-glue/p11-kit/">check - out the source code from git</ulink>. 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.</para> - - <section id="devel-building-unix"> - <title>Building on UNIX</title> - <para>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:</para> - -<programlisting> -$ ./configure --prefix=/path/to/prefix ... -$ make -$ make install -</programlisting> - - <para>If you've checked out the source code from git, then the - <command>configure</command> script does not yet exist. So use - the following instead:</para> - -<programlisting> -$ ./autogen.sh --prefix=/path/to/prefix ... -$ make -$ make install -</programlisting> - - <para>The standard options provided by GNU autoconf may be passed to the configure - script. Please see the autoconf documentation or run <literal>./configure --help</literal> - for information about the standard options. In particular you probably want to adjust - the <literal>--prefix=/xxx</literal> argument depending on your system and development - environment.</para> - </section> - - <section id="devel-building-dependencies"> - <title>Optional Dependencies</title> - - <para>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.</para> - - <itemizedlist> - <listitem><para><command>gettext</command> is required if your system doesn't - have the <literal>gettext()</literal> functionality for handling message - translation databases. This can be provided by the libintl library from - the <ulink url="http://www.gnu.org/software/gettext">GNU gettext - package</ulink>.</para></listitem> - <listitem><para><command>pthread</command> is required if your (ancient) system - doesn't have this included in the base system. How this is provided is platform - specific.</para></listitem> - </itemizedlist> - - <para>In addition p11-kit has several optional dependencies. If these are not available - during the build, then certain features will be disabled.</para> - - <itemizedlist> - <listitem><para><command>libffi</command> for sharing of PKCS#11 modules - between multiple callers in the same process. It is highly recommended that - this dependency be treated as a required dependency.</para></listitem> - <listitem><para><command>gtk-doc</command> is required to build the reference - manual. Use <literal>--enable-doc</literal> to control this - dependency.</para></listitem> - <listitem><para><command>xsltproc</command> is required to build the command - manual pages. Use <literal>--enable-doc</literal> to control this - dependency.</para></listitem> - <listitem><para><command>libtasn1</command> is required to build the trust - module and code that interacts with certificates.</para></listitem> - <listitem><para><command>freebl3</command> (developed as part of the NSS - code base) is an optional dependency that may be used to meet policy - requirements of system builders. Enabling this dependency provides no other - advantage.</para></listitem> - </itemizedlist> - - </section> - - <section id="devel-building-configure"> - <title>Extra Configuration Options</title> - - <para>In addition to the normal options, the configure script in the p11-kit library - supports these additional arguments:</para> - - <variablelist> - <varlistentry> - <term><option>--disable-trust-module</option></term> - <listitem><para>Disables building of the trust policy module.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--disable-debug</option>, <option>--enable-debug</option></term> - <listitem><para>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.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--enable-doc</option></term> - <listitem><para>Enables building of the documentation and command line manual. - The documentation is built in the <literal>doc/html/</literal> directory of - the build. Requires the <literal>gtk-doc</literal> and <literal>xsltproc</literal> - dependencies.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--enable-strict</option></term> - <listitem><para>Enables strict checks during building of p11-kit. All - compiler warnings become errors.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--with-hash-impl=freebl</option></term> - <listitem><para>Instead of using internal hash code, link to the freebl3 - library and use its hash implementations. The only advantage this brings is to - meet the policy requirements of system builders.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--with-libtasn1</option>, <option>--without-libtasn1</option></term> - <listitem><para>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.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--with-module-path</option></term> - <listitem><para>Specify the path to look for PKCS#11 modules which were - listed in a module config file with a relative path.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--with-trust-paths</option></term> - <listitem><para>Specify the files or directories to look for certificate - anchors and blacklists. Multiple files and/or directories are specified with - a <literal>:</literal> in between them. The first path has the highest - priority when searching for certificates.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--with-system-config</option></term> - <listitem><para>Specify the path to look for p11-kit config files. This - usually defaults to something like <literal>/etc/pkcs11</literal></para></listitem> - </varlistentry> - <varlistentry> - <term><option>--with-user-config</option></term> - <listitem><para>Specify the path to look for user specific p11-kit config files. If - specify a path that begins with <literal>~/</literal> then this is expanded to the - home directory of the user running p11-kit. If you specify a path that begins with - <literal>~/.config/</literal> then this is expanded to the $XDG_CONFIG_HOME directory, - as outlined in the - <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html#variables">XDG Base Dir specification</ulink>. - This option defaults to <literal>~/.pkcs11</literal></para></listitem> - </varlistentry> - </variablelist> - <para></para> - </section> - </section> - - <section id="devel-building-style"> - <title>Coding Style</title> - - <para>We use a code style similar to the linux kernel. Use tabs - to indent and spaces to align/wrap beyond the indentation level.</para> - - <para>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:</para> - - <itemizedlist> - <listitem><para>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.</para></listitem> - - <listitem> - <para>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.</para> - <para>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.</para> - <para>Exception: when reading files or allocating potentially - unbounded amounts of memory, we should respond robustly to memory - allocation failures.</para> - </listitem> - </itemizedlist> - - <para>These unexpected conditions indicate a bug either in p11-kit or - in the system. All bets are off once this occurs.</para> - - <para>Use the <literal>return_val_xxx()</literal> precondition macros to - check for unexpected conditions.</para> - </section> - - <section id="devel-testing"> - <title>Testing and Code Coverage</title> - - <para>As a general rule changes to p11-kit should have a tests exercising - that change. Use the <literal>make check</literal> command to run all - the tests. If you run it from a subdirectory only the tests in that - directory will be run.</para> - - <para>To check for memory errors or memory leaks, run <literal>make memcheck</literal> - or <literal>make leakcheck</literal> respectively. This requires valgrind - be installed.</para> - - <para>Build p11-kit with the <option>--enable-coverage</option> configure - option to build code coverage support.</para> - - <para>Once you've done that you can either use <literal>make coverage</literal> - to build code coverage information. Alternatively (and this is usually - easier) you can use - <ulink url="http://stef.thewalter.net/2012/12/git-coverage-useful-code-coverage.html"> - <literal>git coverage</literal></ulink> to easily check whether - you've tested the lines changed by a patch.</para> - - <para>A code coverage report is - <ulink url="http://p11-glue.freedesktop.org/build/coverage">available online</ulink></para>. - </section> - - <section id="devel-debugging"> - <title>Debugging Tips</title> - - <para>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.</para> - - <para>You can use the environment variable <literal>P11_KIT_STRICT=yes</literal> - to make p11-kit do an <literal>abort()</literal> (and core dump depending on - your configuration) when a critical warning occurs.</para> - </section> -</chapter> diff --git a/doc/manual/p11-kit-docs.xml b/doc/manual/p11-kit-docs.xml deleted file mode 100644 index 77ff318..0000000 --- a/doc/manual/p11-kit-docs.xml +++ /dev/null @@ -1,45 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" -[ - <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> - <!ENTITY version SYSTEM "version.xml"> -]> -<book id="index"> - <bookinfo> - <title>p11-kit</title> - <releaseinfo>for p11-kit &version;</releaseinfo> - </bookinfo> - - <xi:include href="p11-kit-config.xml"/> - <xi:include href="p11-kit-sharing.xml"/> - <xi:include href="p11-kit-proxy.xml"/> - <xi:include href="p11-kit-trust.xml"/> - - <chapter xml:id="tools"> - <title>Manual Pages</title> - <xi:include href="p11-kit.xml"/> - <xi:include href="pkcs11.conf.xml"/> - <xi:include href="trust.xml"/> - </chapter> - - <chapter xml:id="reference"> - <title>API Reference</title> - <xi:include href="xml/p11-kit.xml"/> - <xi:include href="xml/p11-kit-uri.xml"/> - <xi:include href="xml/p11-kit-pin.xml"/> - <xi:include href="xml/p11-kit-util.xml"/> - <xi:include href="xml/p11-kit-future.xml"/> - <xi:include href="xml/p11-kit-deprecated.xml"/> - - <index id="api-index-full"> - <title>API Index</title> - <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include> - </index> - - <xi:include href="annotation-glossary.xml"/> - </chapter> - - <xi:include href="p11-kit-devel.xml"/> - -</book> diff --git a/doc/manual/p11-kit-overrides.txt b/doc/manual/p11-kit-overrides.txt deleted file mode 100644 index e69de29..0000000 --- a/doc/manual/p11-kit-overrides.txt +++ /dev/null diff --git a/doc/manual/p11-kit-proxy.xml b/doc/manual/p11-kit-proxy.xml deleted file mode 100644 index 7cc3615..0000000 --- a/doc/manual/p11-kit-proxy.xml +++ /dev/null @@ -1,29 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter xml:id="sharing"> - <title>Proxy Module</title> - - <para>When an application is aware of the fact that coordination - is necessary between multiple consumers of a PKCS#11 module, and wants - to load standard configured PKCS#11 modules, it can link to - <literal>p11-kit</literal> and use the functions there to provide this - functionality.</para> - - <para>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, - <literal>p11-kit</literal> provides a proxy compatibility - module.</para> - - <para>This proxy module acts like a normal PKCS#11 module, but - internally loads a preconfigured set of PKCS#11 modules and - manages their features as described earlier. Each slot in the configured modules - is exposed as a slot of the <literal>p11-kit</literal> 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.</para> - - <para>The <literal>C_GetFunctionList</literal> exported entry point of the - proxy module returns a new managed PKCS#11 module each time it is called. These - managed instances are released when the proxy module is unloaded.</para> -</chapter> diff --git a/doc/manual/p11-kit-sections.txt b/doc/manual/p11-kit-sections.txt deleted file mode 100644 index 85e226f..0000000 --- a/doc/manual/p11-kit-sections.txt +++ /dev/null @@ -1,136 +0,0 @@ -<SECTION> -<FILE>p11-kit-uri</FILE> -P11_KIT_URI_SCHEME -P11_KIT_URI_SCHEME_LEN -P11KitUriType -P11KitUriResult -P11KitUri -p11_kit_uri -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 -</SECTION> - -<SECTION> -<FILE>p11-kit-pin</FILE> -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 -</SECTION> - -<SECTION> -<FILE>p11-kit</FILE> -P11_KIT_MODULE_CRITICAL -P11_KIT_MODULE_UNMANAGED -p11_kit_modules_load_and_initialize -p11_kit_modules_finalize_and_release -p11_kit_modules_load -p11_kit_modules_initialize -p11_kit_modules_finalize -p11_kit_modules_release -p11_kit_module_load -p11_kit_module_initialize -p11_kit_module_finalize -p11_kit_module_release -p11_kit_module_for_name -p11_kit_module_get_name -p11_kit_module_get_flags -p11_kit_config_option -</SECTION> - -<SECTION> -<FILE>p11-kit-util</FILE> -p11_kit_strerror -p11_kit_message -p11_kit_space_strdup -p11_kit_space_strlen -p11_kit_be_quiet -p11_kit_be_loud -<SUBSECTION Private> -CK_FUNCTION_LIST_PTR -CK_RV -CK_ATTRIBUTE -CK_ATTRIBUTE_PTR -CK_ATTRIBUTE_TYPE -CK_FLAGS -CK_FUNCTION_LIST -CK_INFO_PTR -CK_TOKEN_INFO_PTR -CK_ULONG -p11_kit_uri_result_t -p11_kit_uri_type_t -</SECTION> - -<SECTION> -<FILE>p11-kit-future</FILE> -p11_kit_set_progname -p11_kit_destroyer -P11KitIter -p11_kit_iter -p11_kit_iter_new -p11_kit_iter_set_uri -p11_kit_iter_add_callback -p11_kit_iter_add_filter -p11_kit_iter_callback -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_token -p11_kit_iter_get_session -p11_kit_iter_keep_session -p11_kit_iter_get_object -p11_kit_iter_load_attributes -p11_kit_iter_destroy_object -p11_kit_iter_free -P11KitIterBehavior -p11_kit_remote_serve_module -</SECTION> - -<SECTION> -<FILE>p11-kit-deprecated</FILE> -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_DEPRECATED_FOR -</SECTION> diff --git a/doc/manual/p11-kit-sharing.xml b/doc/manual/p11-kit-sharing.xml deleted file mode 100644 index 0edf36e..0000000 --- a/doc/manual/p11-kit-sharing.xml +++ /dev/null @@ -1,110 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> - -<chapter xml:id="sharing"> - <title>Sharing PKCS#11 modules</title> - - <section xml:id="sharing-problem"> - <title>Multiple consumers of PKCS#11 in a process</title> - - <para>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. - </para> - - <para>An example: An application might use GnuTLS for - TLS connections, and use libgcr for display of certificates. Both of - these want to load (and initialize) 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.</para> - - <para>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 <literal>CKR_CRYPTOKI_ALREADY_INITIALIZED</literal> - is correctly returned. This is normal PKCS#11 specification - defined behavior for when a module is initialized twice in the - same process. If consumer B is aware of this situation they may - choose to ignore this error code.</para> - - <para>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.</para> - - <para>It is necessary for the two consumers to coordinate their - initialization and finalization in some fashion. In - <literal>p11-kit</literal> we provide this coordination in a - loosely coupled, backwards compatible, and flexible way.</para> - </section> - - <section xml:id="sharing-managed"> - <title>Managed modules</title> - - <para><literal>p11-kit</literal> wraps PKCS#11 modules to manage - them and customize their functionality so that they are able - to be shared between multiple callers in the same process.</para> - - <para>Each caller that uses the - <link linkend="p11-kit-modules-load"><function>p11_kit_modules_load()</function></link> - or <link linkend="p11-kit-module-load"><function>p11_kit_module_load()</function></link> - function gets independent wrapped PKCS#11 module(s). This is unless a caller - or module configuration specifies that a module should be used in an - unmanaged fashion.</para> - - <para>When modules are managed, the following aspects are wrapped and - coordinated:</para> - - <itemizedlist> - <listitem> - <para>Calls to <literal>C_Initialize</literal> and - <literal>C_Finalize</literal> can be called by multiple - callers.</para> - - <para>The first time that the managed module - <literal>C_Initialize</literal> is called, the PKCS#11 module's actual - <literal>C_Initialize</literal> function is called. Subsequent calls by - other callers will cause <literal>p11-kit</literal> to increment an - internal initialization count, rather than calling - <literal>C_Initialize</literal> again.</para> - - <para>Multiple callers can call the managed - <literal>C_Initialize</literal> function concurrently from different - threads and <literal>p11-kit</literal> will guarantee that this managed - in a thread-safe manner.</para> - </listitem> - <listitem> - <para>When the managed module <literal>C_Finalize</literal> 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 actual <literal>C_Finalize</literal> - function is called.</para> - - <para>Multiple callers can call the managed <literal>C_Finalize</literal> - function concurrently from different threads and <literal>p11-kit</literal> - will guarantee that this managed in a thread-safe manner.</para> - </listitem> - <listitem> - <para>Call to <literal>C_CloseAllSessions</literal> only close the - sessions that the caller of the managed module has opened. This allows the - <literal>C_CloseAllSessions</literal> function to be used without closing - sessions for other callers of the same PKCS#11 module.</para> - </listitem> - <listitem> - <para>Managed modules have ability to log PKCS#11 method calls for debugging - purposes. See the <link linkend="option-log-calls"><literal>log-calls = yes</literal></link> - module configuration option.</para> - </listitem> - <listitem> - <para>Managed modules have the ability to be remoted to another machine or - isolated in their own process. - See the <link linkend="option-remote"><literal>remote = ...</literal></link> - module configuration option.</para> - </listitem> - </itemizedlist> - </section> -</chapter> diff --git a/doc/manual/p11-kit-trust.xml b/doc/manual/p11-kit-trust.xml deleted file mode 100644 index dde614c..0000000 --- a/doc/manual/p11-kit-trust.xml +++ /dev/null @@ -1,128 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" -[ - <!ENTITY sysdir SYSTEM "sysdir.xml"> - <!ENTITY userdir SYSTEM "userdir.xml"> -]> - -<chapter xml:id="trust-module"> -<title>Trust Policy Module</title> - - <para>The trust module provides system certificate anchors, blacklists - and other trust policy to crypto libraries applications. This - information is exposed as PKCS#11 objects.</para> - - <para>You can use the <link linkend="trust">trust</link> command line - tool to examine and modify the trust policy store.</para> - -<section id="trust-files"> - <title>Paths loaded by the Module</title> - - <para>The trust module loads certificates and trust policy information - from preconfigured paths and allows them to be looked up via PKCS#11. - The input paths can be determined with using the following command:</para> - -<programlisting> -$ pkg-config --variable p11_trust_paths p11-kit-1 -/usr/share/p11-kit/trust:/etc/pki/trust -</programlisting> - - <para>Files in the following formats are supported for loading by the - trust policy module:</para> - - <variablelist> - <varlistentry> - <term>X.509 certificates</term> - <listitem><para>X.509 certificates in raw DER format. Does not - automatically contain trust policy information.</para></listitem> - </varlistentry> - <varlistentry> - <term>PEM certificates</term> - <listitem><para>X.509 certificates in PEM format. These have a - <literal>BEGIN CERTIFICATE</literal> header. This file does not - automatically contain trust policy information.</para></listitem> - </varlistentry> - <varlistentry> - <term>OpenSSL trust certificates</term> - <listitem><para>OpenSSL specific certificates in PEM format - that contain trust information. These have a - <literal>BEGIN TRUSTED CERTIFICATE</literal> PEM header. Both - trust anchor and blacklist information can be loaded - from these files.</para></listitem> - </varlistentry> - </variablelist> - - <para>If the input path is a file, then it is loaded. Certificate(s) in the - file are automatically treated as anchors, unless they contain alternate - trust policy information.</para> - - <para>If the input path is a directory, files inside that directory are - parsed and loaded. If the file contains trust policy information (such as the - OpenSSL trust certificates) then it will be respected. Files without trust policy - information are not automatically marked as an anchor or blacklisted.</para> - - <para>In addition two optional subdirectories of the input path are loaded. Files - placed in the <literal>anchors/</literal> subdirectory become trust anchors - when they do not contain trust policy information. Files placed in the - <literal>blacklist/</literal> subdirectory are blacklisted whether they - contain trust information or not.</para> - - <para>The first input path becomes the first PKCS#11 token of the trust - module, and has the highest priority when callers search for trust - policy information.</para> -</section> - -<section id="trust-nss"> - <title>Using the Trust Policy Module with NSS</title> - - <para>The trust policy module is a drop in replacement for the - <literal>libnssckbi.so</literal> 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.</para> - - <para>The module may be used to replace the - <literal>libnssckbi.so</literal> file via an distribution - specific alternatives mechanism or otherwise.</para> - - <para>Alternatively NSS applications like Firefox or Thunderbird - may be configured to use the trust policy module by adding - the <literal>p11-kit-trust.so</literal> PKCS#11 module via their - GUI or command line configuration.</para> -</section> - -<section id="trust-glib-networking"> - <title>Using the Trust Policy Module with glib-networking</title> - - <para>The trust policy module can be used as a source of trust - information for glib-networking's <literal>gnutls-pkcs11</literal> backend. - The module provides PKCS#11 trust assertion objects as expected.</para> - - <para>The module should work by default if the <literal>gnutls-pkcs11</literal> - backend is selected as the glib-networking TLS backend.</para> -</section> - -<section id="trust-disable"> - <title>Disabling the Trust Policy Module</title> - - <para>This module is installed and enabled by default. It may - be disabled in the following ways:</para> - - <itemizedlist> - <listitem><para>Use the <option>--disable-trust-module</option> - during the <link linkend="devel-building-configure">p11-kit - build</link>.</para></listitem> - <listitem><para>Disable loading trust policy information - from this module by adding a file to <literal>&sysdir;/modules</literal> - called <literal>p11-kit-trust.module</literal> containing a - <literal>trust-policy: no</literal> line.</para></listitem> - - <listitem><para>Disable this module completely by - adding a file to <literal>&sysdir;/modules</literal> - called <literal>p11-kit-trust.module</literal> containing a - <literal>enable-in:</literal> line (without a value).</para></listitem> - </itemizedlist> - -</section> - -</chapter> diff --git a/doc/manual/p11-kit.xml b/doc/manual/p11-kit.xml deleted file mode 100644 index be3f982..0000000 --- a/doc/manual/p11-kit.xml +++ /dev/null @@ -1,131 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> - -<refentry id="p11-kit"> - -<refentryinfo> - <title>p11-kit</title> - <productname>p11-kit</productname> - <authorgroup> - <author> - <contrib>Maintainer</contrib> - <firstname>Stef</firstname> - <surname>Walter</surname> - <email>stef@thewalter.net</email> - </author> - </authorgroup> -</refentryinfo> - -<refmeta> - <refentrytitle>p11-kit</refentrytitle> - <manvolnum>8</manvolnum> - <refmiscinfo class="manual">System Commands</refmiscinfo> -</refmeta> - -<refnamediv> - <refname>p11-kit</refname> - <refpurpose>Tool for operating on configured PKCS#11 modules</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>p11-kit list-modules</command> - </cmdsynopsis> - <cmdsynopsis> - <command>p11-kit extract</command> ... - </cmdsynopsis> -</refsynopsisdiv> - -<refsect1 id="p11-kit-description"> - <title>Description</title> - <para><command>p11-kit</command> is a command line tool that - can be used to perform operations on PKCS#11 modules configured on the - system.</para> - - <para>See the various sub commands below. The following global options - can be used:</para> - - <variablelist> - <varlistentry> - <term><option>-v, --verbose</option></term> - <listitem><para>Run in verbose mode with debug - output.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>-q, --quiet</option></term> - <listitem><para>Run in quiet mode without warning or - failure messages.</para></listitem> - </varlistentry> - </variablelist> - -</refsect1> - -<refsect1 id="p11-kit-list-modules"> - <title>List Modules</title> - - <para>List system configured PKCS#11 modules.</para> - -<programlisting> -$ p11-kit list-modules -</programlisting> - - <para>The modules, information about them and the tokens present in - the PKCS#11 modules will be displayed.</para> - -</refsect1> - -<refsect1 id="p11-kit-extract"> - <title>Extract</title> - - <para>Extract certificates from configured PKCS#11 modules.</para> - - <para>See <member><citerefentry><refentrytitle>trust</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> - for more information</para> -</refsect1> - -<refsect1 id="p11-kit-extract-trust"> - <title>Extract Trust</title> - - <para>Extract standard trust information files.</para> - - <para>See <citerefentry><refentrytitle>trust</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for more information</para> -</refsect1> - -<refsect1 id="p11-kit-remote"> - <title>Remote</title> - - <para>Run a PKCS#11 module remotely.</para> - -<programlisting> -$ p11-kit remote /path/to/pkcs11-module.so -</programlisting> - - <para>This is not meant to be run directly from a terminal. But rather in a - <option>remote</option> option in a - <citerefentry><refentrytitle>pkcs11.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - file.</para> -</refsect1> - -<refsect1 id="p11-kit-bugs"> - <title>Bugs</title> - <para> - Please send bug reports to either the distribution bug tracker - or the upstream bug tracker at - <ulink url="https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&component=p11-kit">https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&component=p11-kit</ulink>. - </para> -</refsect1> - -<refsect1 id="p11-kit-see-also"> - <title>See also</title> - <simplelist type="inline"> - <member><citerefentry><refentrytitle>pkcs11.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> - </simplelist> - <para> - Further details available in the p11-kit online documentation at - <ulink url="http://p11-glue.freedesktop.org/doc/p11-kit/">http://p11-glue.freedesktop.org/doc/p11-kit/</ulink>. - </para> -</refsect1> - -</refentry> diff --git a/doc/manual/pkcs11.conf.xml b/doc/manual/pkcs11.conf.xml deleted file mode 100644 index ffd89a5..0000000 --- a/doc/manual/pkcs11.conf.xml +++ /dev/null @@ -1,281 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" -[ - <!ENTITY sysdir SYSTEM "sysdir.xml"> - <!ENTITY userdir SYSTEM "userdir.xml"> -]> - -<refentry id="pkcs11-conf"> - -<refentryinfo> - <title>pkcs11.conf</title> - <productname>p11-kit</productname> - <authorgroup> - <author> - <contrib>Maintainer</contrib> - <firstname>Stef</firstname> - <surname>Walter</surname> - <email>stef@thewalter.net</email> - </author> - </authorgroup> -</refentryinfo> - -<refmeta> - <refentrytitle>pkcs11.conf</refentrytitle> - <manvolnum>5</manvolnum> - <refmiscinfo class="manual">System Files</refmiscinfo> -</refmeta> - -<refnamediv> - <refname>pkcs11.conf</refname> - <refpurpose>Configuration files for PKCS#11 modules</refpurpose> -</refnamediv> - -<refsect1 id="pkcs11-conf-description"> - <title>Description</title> - <para>The <command>pkcs11.conf</command> configuration files are a standard - way to configure PKCS#11 modules.</para> -</refsect1> - -<refsect1 id="config-format"> - <title>File format</title> - <para>A complete configuration consists of several files. These files are - text files. Since <literal>p11-kit</literal> 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.</para> - - <para>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.</para> - - <para>The value is specified after the name on the same line, separated - from it by a <literal>:</literal> (colon). White space between the - name and value is ignored.</para> - - <para>Blank lines are ignored. White space at the beginning or end of - lines is stripped. Lines that begin with a <literal>#</literal> character - are ignored as comments. Comments are not recognized when they come after - a value on a line.</para> - - <para>A fictitious module configuration file might look like:</para> -<programlisting> -module: module.so -# Here is a comment - -managed: true -setting.2: A long value with text. -x-custom : text -</programlisting> -</refsect1> - -<refsect1 id="config-module"> - <title>Module Configuration</title> - - <para>Each configured PKCS#11 module has its own config file. These files - can be <link linkend="config-locations">placed in various locations</link>.</para> - <para>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 <literal>.module</literal> extension.</para> - <para>Most importantly each config file specifies the path of the PKCS#11 module to - load. A module config file has the following fields:</para> - - <variablelist> - <varlistentry> - <term><option>module:</option></term> - <listitem> - <para>The filename of the PKCS#11 module to load. - This should include an extension like <literal>.so</literal></para> - <para>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.</para> - - <para>If this is a relative path, then the module will be loaded - from the <link linkend="devel-paths-modules">default module directory</link>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>critical:</option></term> - <listitem> - <para>Set to <literal>yes</literal> 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.</para> - - <para>This argument is optional and defaults to <literal>no</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>enable-in:</option></term> - <listitem> - <para>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 - <literal>seahorse, ssh</literal>.</para> - <para>This is not a security feature. The argument is optional. If - not present, then any process will load the module.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>disable-in:</option></term> - <listitem> - <para>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 - <literal>firefox, thunderbird-bin</literal>.</para> - <para>This is not a security feature. The argument is optional. If - not present, then any process will load the module.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>managed:</option></term> - <listitem> - <para>Set to <literal>no</literal> if the module is not to be managed by - p11-kit. Making a module unmanaged is not recommended, and will cause - problems if multiple callers in a single process share a PKCS#11 module.</para> - - <para>This argument is optional and defaults to <literal>yes</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>priority:</option></term> - <listitem> - <para>The value should be an integer. When lists of modules are - returned to a caller of p11-kit, modules with a higher number are sorted - first. When applications search modules for certificates, keys and - trust policy information, this setting will affect what find - first.</para> - <para>This argument is optional, and defaults to zero. Modules - with the same <option>priority</option> option will be sorted - alphabetically.</para> - </listitem> - </varlistentry> - <varlistentry id="option-remote"> - <term><option>remote:</option></term> - <listitem> - <para>Instead of loading the PKCS#11 module locally, run the module - remotely.</para> - <para>Specify a command to run, prefixed with <literal>|</literal> a pipe. - The command must speak the p11-kit remoting protocol on its standard in - and standard out. For example:</para> -<programlisting> -remote: |ssh user@remote p11-kit remote /path/to/module.so -</programlisting> - <para>Other forms of remoting will appear in later p11-kit releases.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>trust-policy:</option></term> - <listitem> - <para>Set to <literal>yes</literal> to use use this module as a source - of trust policy information such as certificate anchors and black lists.</para> - </listitem> - </varlistentry> - <varlistentry id="option-log-calls"> - <term>log-calls:</term> - <listitem> - <para>Set to <literal>yes</literal> to write a log to stderr of all the - calls into the module. This is only supported for managed modules.</para> - - <para>This argument is optional and defaults to <literal>no</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Do not specify both <literal>enable-in</literal> and <literal>disable-in</literal> - for the same module.</para> - - <para>Other fields may be present, but it is recommended that field names - that are not specified in this document start with a <literal>x-</literal> - prefix.</para> -</refsect1> - -<refsect1 id="config-global"> - <title>Global Configuration</title> - - <para>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:</para> - - <variablelist> - <varlistentry> - <term><option>user-config:</option></term> - <listitem><para>This will be equal to one of the following values: - <literal>none</literal>, <literal>merge</literal>, - <literal>only</literal>.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>managed:</option></term> - <listitem> - <para>Set to <literal>yes</literal> or <literal>no</literal> to - force all modules to be managed or unmanaged by p11-kit. Setting this - setting in a global configuration file will override the - <literal>managed</literal> setting in the individual module configuration - files. Making modules unmanaged is not recommended, and will cause - problems if multiple callers in a single process share a PKCS#11 - module.</para> - - <para>This argument is optional.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>log-calls:</term> - <listitem> - <para>Set to <literal>yes</literal> to write a log to stderr of all the - calls into all configured modules. This is only supported for managed - modules.</para> - - <para>This argument is optional.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Other fields may be present, but it is recommended that field names - that are not specified in this document start with a <literal>x-</literal> - prefix.</para> -</refsect1> - -<refsect1 id="config-locations"> - <title>Configuration Files</title> - - <para>Each configured PKCS#11 module 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.</para> - - <para>The system global configuration file is usually in - <literal>&sysdir;/pkcs11.conf</literal> and the user global - configuration file is in <literal>&userdir;/pkcs11.conf</literal> in the - user's home directory.</para> - - <para>The module config files are usually located in the - <literal>&sysdir;/modules</literal> directory, with one configuration - file per module. In addition the <literal>&userdir;/modules</literal> directory - can be used for modules installed by the user.</para> - - <para>Note that user configuration files are not loaded from the home - directory if running inside a setuid or setgid program.</para> - - <para>The default system config file and module directory can be changed - when building p11-kit. Always - <link linkend="devel-paths">lookup these paths</link> using - <literal>pkg-config</literal>.</para> -</refsect1> - -<refsect1 id="pkcs11-conf-see-also"> - <title>See also</title> - <simplelist type="inline"> - <member><citerefentry><refentrytitle>p11-kit</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> - </simplelist> - <para>Further details available in the p11-kit online documentation at - <ulink url="http://p11-glue.freedesktop.org/doc/p11-kit/">http://p11-glue.freedesktop.org/doc/p11-kit/</ulink>. - </para> -</refsect1> - -</refentry> diff --git a/doc/manual/style.css b/doc/manual/style.css deleted file mode 100644 index 3d0f951..0000000 --- a/doc/manual/style.css +++ /dev/null @@ -1,116 +0,0 @@ -@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/trust.xml b/doc/manual/trust.xml deleted file mode 100644 index 05f2726..0000000 --- a/doc/manual/trust.xml +++ /dev/null @@ -1,372 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> - -<refentry id="trust"> - -<refentryinfo> - <title>trust</title> - <productname>p11-kit</productname> - <authorgroup> - <author> - <contrib>Maintainer</contrib> - <firstname>Stef</firstname> - <surname>Walter</surname> - <email>stef@thewalter.net</email> - </author> - </authorgroup> -</refentryinfo> - -<refmeta> - <refentrytitle>trust</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="manual">User Commands</refmiscinfo> -</refmeta> - -<refnamediv> - <refname>trust</refname> - <refpurpose>Tool for operating on the trust policy store</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>trust list</command> - </cmdsynopsis> - <cmdsynopsis> - <command>trust extract</command> <arg choice="plain">--filter=<what></arg> - <arg choice="plain">--format=<type></arg> /path/to/destination - </cmdsynopsis> - <cmdsynopsis> - <command>trust anchor</command> /path/to/certificate.crt - </cmdsynopsis> -</refsynopsisdiv> - -<refsect1 id="trust-description"> - <title>Description</title> - <para><command>trust</command> is a command line tool to examine and - modify the shared trust policy store.</para> - - <para>See the various sub commands below. The following global options - can be used:</para> - - <variablelist> - <varlistentry> - <term><option>-v, --verbose</option></term> - <listitem><para>Run in verbose mode with debug - output.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>-q, --quiet</option></term> - <listitem><para>Run in quiet mode without warning or - failure messages.</para></listitem> - </varlistentry> - </variablelist> - -</refsect1> - -<refsect1 id="trust-list"> - <title>List</title> - - <para>List trust policy store items.</para> - -<programlisting> -$ trust list -</programlisting> - - <para>List information about the various items in the trust policy store. - Each item is listed with it's PKCS#11 URI and some descriptive information.</para> - - <para>You can specify the following options to control what to list.</para> - - <varlistentry> - <term><option>--filter=<what></option></term> - <listitem> - <para>Specifies what certificates to extract. You can specify the following values: - <variablelist> - <varlistentry> - <term><option>ca-anchors</option></term> - <listitem><para>Certificate anchors</para></listitem> - </varlistentry> - <varlistentry> - <term><option>trust-policy</option></term> - <listitem><para>Anchors and blacklist (default)</para></listitem> - </varlistentry> - <varlistentry> - <term><option>blacklist</option></term> - <listitem><para>Blacklisted certificates</para></listitem> - </varlistentry> - <varlistentry> - <term><option>certificates</option></term> - <listitem><para>All certificates</para></listitem> - </varlistentry> - <varlistentry> - <term><option>pkcs11:object=xx</option></term> - <listitem><para>A PKCS#11 URI to filter with</para></listitem> - </varlistentry> - </variablelist> - </para> - - <para>If an output format is chosen that cannot support type what has been - specified by the filter, a message will be printed.</para> - - <para>None of the available formats support storage of blacklist entries - that do not contain a full certificate. Thus any certificates blacklisted by - their issuer and serial number alone, are not included in the extracted - blacklist.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--purpose=<usage></option></term> - <listitem><para>Limit to certificates usable for the given purpose - You can specify one of the following values: - <variablelist> - <varlistentry> - <term><option>server-auth</option></term> - <listitem><para>For authenticating servers</para></listitem> - </varlistentry> - <varlistentry> - <term><option>client-auth</option></term> - <listitem><para>For authenticating clients</para></listitem> - </varlistentry> - <varlistentry> - <term><option>email</option></term> - <listitem><para>For email protection</para></listitem> - </varlistentry> - <varlistentry> - <term><option>code-signing</option></term> - <listitem><para>For authenticated signed code</para></listitem> - </varlistentry> - <varlistentry> - <term><option>1.2.3.4.5...</option></term> - <listitem><para>An arbitrary purpose OID</para></listitem> - </varlistentry> - </variablelist> - </para></listitem> - </varlistentry> - -</refsect1> - -<refsect1 id="trust-anchor"> - <title>Anchor</title> - - <para>Store or remove trust anchors.</para> - -<programlisting> -$ trust anchor /path/to/certificate.crt -$ trust anchor --remove /path/to/certificate.crt -$ trust anchor --remove "pkcs11:id=%AA%BB%CC%DD%EE;object-type=cert" -</programlisting> - - <para>Store or remove trust anchors in the trust policy store. These are - usually root certificate authorities.</para> - - <para>Specify either the <option>--store</option> or <option>--remove</option> - operations. If no operation is specified then <option>--store</option> is - assumed.</para> - - <para>When storing, one or more certificate files are expected on the - command line. These are stored as anchors, unless they are already - present.</para> - - <para>When removing an anchor, either specify certificate files or - PKCS#11 URI's on the command line. Matching anchors will be removed.</para> - - <para>It may be that this command needs to be run as root in order to - modify the system trust policy store, if no user specific store is - available.</para> - - <para>You can specify the following options.</para> - - <variablelist> - <varlistentry> - <term><option>--remove</option></term> - <listitem><para>Remove one or more anchors from the trust - policy store. Specify certificate files or PKCS#11 URI's - on the command line.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--store</option></term> - <listitem><para>Store one or more anchors to the trust - policy store. Specify certificate files on the command - line.</para></listitem> - </varlistentry> - </variablelist> - -</refsect1> - -<refsect1 id="trust-extract"> - <title>Extract</title> - - <para>Extract trust policy from the shared trust policy store.</para> - -<programlisting> -$ trust extract --format=x509-directory --filter=ca-anchors /path/to/directory -</programlisting> - - <para>You can specify the following options to control what to extract. - The <option>--filter</option> and <option>--format</option> arguments - should be specified. By default this command will not overwrite the - destination file or directory.</para> - - <variablelist> - <varlistentry> - <term><option>--comment</option></term> - <listitem><para>Add identifying comments to PEM bundle output files - before each certificate.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--filter=<what></option></term> - <listitem> - <para>Specifies what certificates to extract. You can specify the following values: - <variablelist> - <varlistentry> - <term><option>ca-anchors</option></term> - <listitem><para>Certificate anchors (default)</para></listitem> - </varlistentry> - <varlistentry> - <term><option>trust-policy</option></term> - <listitem><para>Anchors and blacklist</para></listitem> - </varlistentry> - <varlistentry> - <term><option>blacklist</option></term> - <listitem><para>Blacklisted certificates</para></listitem> - </varlistentry> - <varlistentry> - <term><option>certificates</option></term> - <listitem><para>All certificates</para></listitem> - </varlistentry> - <varlistentry> - <term><option>pkcs11:object=xx</option></term> - <listitem><para>A PKCS#11 URI</para></listitem> - </varlistentry> - </variablelist> - </para> - - <para>If an output format is chosen that cannot support type what has been - specified by the filter, a message will be printed.</para> - - <para>None of the available formats support storage of blacklist entries - that do not contain a full certificate. Thus any certificates blacklisted by - their issuer and serial number alone, are not included in the extracted - blacklist.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--format=<type></option></term> - <listitem><para>The format of the destination file or directory. - You can specify one of the following values: - <variablelist> - <varlistentry> - <term><option>x509-file</option></term> - <listitem><para>DER X.509 certificate file</para></listitem> - </varlistentry> - <varlistentry> - <term><option>x509-directory</option></term> - <listitem><para>directory of X.509 certificates</para></listitem> - </varlistentry> - <varlistentry> - <term><option>pem-bundle</option></term> - <listitem><para>File containing one or more certificate PEM blocks</para></listitem> - </varlistentry> - <varlistentry> - <term><option>pem-directory</option></term> - <listitem><para>Directory of PEM files each containing one certificate</para></listitem> - </varlistentry> - <varlistentry> - <term><option>pem-directory-hash</option></term> - <listitem><para>Directory of PEM files each containing one certificate, with hash symlinks</para></listitem> - </varlistentry> - <varlistentry> - <term><option>openssl-bundle</option></term> - <listitem><para>OpenSSL specific PEM bundle of certificates</para></listitem> - </varlistentry> - <varlistentry> - <term><option>openssl-directory</option></term> - <listitem><para>Directory of OpenSSL specific PEM files</para></listitem> - </varlistentry> - <varlistentry> - <term><option>java-cacerts</option></term> - <listitem><para>Java keystore 'cacerts' certificate bundle</para></listitem> - </varlistentry> - </variablelist> - </para></listitem> - </varlistentry> - <varlistentry> - <term><option>--overwrite</option></term> - <listitem><para>Overwrite output file or directory.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--purpose=<usage></option></term> - <listitem><para>Limit to certificates usable for the given purpose - You can specify one of the following values: - <variablelist> - <varlistentry> - <term><option>server-auth</option></term> - <listitem><para>For authenticating servers</para></listitem> - </varlistentry> - <varlistentry> - <term><option>client-auth</option></term> - <listitem><para>For authenticating clients</para></listitem> - </varlistentry> - <varlistentry> - <term><option>email</option></term> - <listitem><para>For email protection</para></listitem> - </varlistentry> - <varlistentry> - <term><option>code-signing</option></term> - <listitem><para>For authenticated signed code</para></listitem> - </varlistentry> - <varlistentry> - <term><option>1.2.3.4.5...</option></term> - <listitem><para>An arbitrary purpose OID</para></listitem> - </varlistentry> - </variablelist> - </para></listitem> - </varlistentry> - </variablelist> - -</refsect1> - -<refsect1 id="trust-extract-compat"> - <title>Extract Compat</title> - - <para>Extract compatibility trust certificate bundles.</para> - -<programlisting> -$ trust extract-compat -</programlisting> - - <para>OpenSSL, Java and some versions of GnuTLS cannot currently read - trust information directly from the trust policy store. This command - extracts trust information such as certificate anchors for use by - these libraries.</para> - - <para>What this command does, and where it extracts the files is - distribution or site specific. Packagers or administrators are expected - customize this command.</para> - -</refsect1> - -<refsect1 id="trust-bugs"> - <title>Bugs</title> - <para> - Please send bug reports to either the distribution bug tracker - or the upstream bug tracker at - <ulink url="https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&component=p11-kit">https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&component=p11-kit</ulink>. - </para> -</refsect1> - -<refsect1 id="trust-see-also"> - <title>See also</title> - <simplelist type="inline"> - <member><citerefentry><refentrytitle>p11-kit</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> - </simplelist> - <para>An explanatory document about storing trust policy: - <ulink url="http://p11-glue.freedesktop.org/doc/storing-trust-policy/">http://p11-glue.freedesktop.org/doc/storing-trust-policy/</ulink></para> - <para> - Further details available in the p11-kit online documentation at - <ulink url="http://p11-glue.freedesktop.org/doc/p11-kit/">http://p11-glue.freedesktop.org/doc/p11-kit/</ulink>. - </para> -</refsect1> - -</refentry> |