summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am6
-rw-r--r--doc/internal/persist-format.txt59
-rw-r--r--doc/manual/Makefile.am169
-rw-r--r--doc/manual/annotation-glossary.xml67
-rw-r--r--doc/manual/docbook-params.xsl39
-rw-r--r--doc/manual/p11-kit-config.xml98
-rw-r--r--doc/manual/p11-kit-devel.xml323
-rw-r--r--doc/manual/p11-kit-docs.xml45
-rw-r--r--doc/manual/p11-kit-overrides.txt0
-rw-r--r--doc/manual/p11-kit-proxy.xml29
-rw-r--r--doc/manual/p11-kit-sections.txt136
-rw-r--r--doc/manual/p11-kit-sharing.xml110
-rw-r--r--doc/manual/p11-kit-trust.xml128
-rw-r--r--doc/manual/p11-kit.xml131
-rw-r--r--doc/manual/pkcs11.conf.xml281
-rw-r--r--doc/manual/style.css116
-rw-r--r--doc/manual/trust.xml372
17 files changed, 0 insertions, 2109 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
deleted file mode 100644
index de840c0..0000000
--- a/doc/Makefile.am
+++ /dev/null
@@ -1,6 +0,0 @@
-
-SUBDIRS = manual
-
-memcheck:
-
-leakcheck:
diff --git a/doc/internal/persist-format.txt b/doc/internal/persist-format.txt
deleted file mode 100644
index cb863be..0000000
--- a/doc/internal/persist-format.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-These are some notes about the p11-kit persistence format
-
-The format is designed to be somewhat human readable and debuggable, and a bit
-transparent but it is also not encouraged to read/write this format from other
-applications or tools without first discussing this at the the mailing list:
-
-p11-glue@lists.freedesktop.org
-
-The format of the file reflects the PKCS#11 attributes exposed by p11-kit. The
-attributes have a one to one mapping with PKCS#11 attributes of similar names.
-No assumptions should be made that an attribute does what you think it does
-from the label.
-
-Each object in the file starts with the header '[p11-kit-object-v1]'. After that
-point there are names and valeus separated by colons. Whitespace surrounding
-the names and values is ignored.
-
-Boolean values are 'true' and 'false'. Unsigned long attributes are plain
-numbers. String/binary attributes are surrounded with quotes and percent
-encoded. Object id attributes are in their dotted form. Various PKCS#11
-constants are available.
-
-PEM blocks can be present within an object, and these contribute certain
-PKCS#11 attributes to the object. The attributes that come from PEM blocks
-never override those explicitly specified.
-
-A 'CERTIFICATE' type PEM block contributes the 'value', 'class',
-'certificate-type', 'subject', 'issuer' 'start-date', 'end-date', 'id',
-'certificate-category', 'check-value', 'serial-number', 'public-key-info'
-attributes with appropriate values.
-
-A 'PUBLIC KEY' type PEM block contributes the 'public-key-info' attribute
-with an appropriate value.
-
-Comments starting with a '#' and blank lines are ignored.
-
-Only rudimentary checks are done to make sure that the resulting attributes
-make sense. This may change in the future, and invalid files will be
-unceremoniously rejected. So again use the mailing list if there's a need
-to be writing these files at this point:
-
-p11-glue@lists.freedesktop.org
-
-Example file:
-
-[p11-kit-object-v1]
-class = certificate
-modifiable = true
-java-midp-security-domain = 0
-label = "My special label"
-id = "%01%02%03go"
-
------BEGIN CERTIFICATE-----
-MIIEXDCCA0SgAwIBAgIEOGO5ZjANBgkqhkiG9w0BAQUFADCBtDEUMBIGA1UEChML
-................................................................
-B/L/CNDi3tm/Kq+4h4YhPATKt5Rof8886ZjXOP/swNlQ8C5LWK5Gb9Auw2DaclVy
-vUxFnmG6v4SBkgPR0ml8xQ==
------END CERTIFICATE-----
-x-distrusted = true
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&amp;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&amp;component=p11-kit">https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&amp;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=&lt;what&gt;</arg>
- <arg choice="plain">--format=&lt;type&gt;</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=&lt;what&gt;</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=&lt;usage&gt;</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=&lt;what&gt;</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=&lt;type&gt;</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=&lt;usage&gt;</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&amp;component=p11-kit">https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&amp;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>
View Lorry Controller Status