doc/manual/html/pkcs11.conf.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>pkcs11.conf</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="index.html" title="p11-kit">
   8 <link rel="up" href="tools.html" title="Manual Pages">
   9 <link rel="prev" href="p11-kit.html" title="p11-kit">
  10 <link rel="next" href="reference.html" title="API Reference">
  11 <meta name="generator" content="GTK-Doc V1.19 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  16 <td><a accesskey="p" href="p11-kit.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="tools.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">p11-kit</th>
  20 <td><a accesskey="n" href="reference.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="refentry">
  23 <a name="pkcs11.conf"></a><div class="titlepage"></div>
  24 <div class="refnamediv"><table width="100%"><tr>
  25 <td valign="top">
  26 <h2><span class="refentrytitle">pkcs11.conf</span></h2>
  27 <p>pkcs11.conf — Configuration files for PKCS#11 modules</p>
  28 </td>
  29 <td valign="top" align="right"></td>
  30 </tr></table></div>
  31 <div class="refsect1">
  32 <a name="id-1.5.3.4"></a><h2>Description</h2>
  33 <p>The <span class="command"><strong>pkcs11.conf</strong></span> configuration files are a standard
  34         way to configure PKCS#11 modules.</p>
  35 </div>
  36 <div class="refsect1">
  37 <a name="config-format"></a><h2>File format</h2>
  38 <p>A complete configuration consists of several files. These files are
  39         text files. Since <code class="literal">p11-kit</code> is built to be used in all
  40         sorts of environments and at very low levels of the software stack, we
  41         cannot make use of high level configuration APIs that you may find on a
  42         modern desktop.</p>
  43 <p>Each setting in the config file is specified consists of a name and
  44         a value. The name is a simple string consisting of characters and dashes.
  45         The name consists of alpha numeric characters, dot, hyphen and
  46         underscore.</p>
  47 <p>The value is specified after the name on the same line, separated
  48         from it by a <code class="literal">:</code> (colon). White space between the
  49         name and value is ignored.</p>
  50 <p>Blank lines are ignored. White space at the beginning or end of
  51         lines is stripped. Lines that begin with a <code class="literal">#</code> character
  52         are ignored as comments. Comments are not recognized when they come after
  53         a value on a line.</p>
  54 <p>A fictitious module configuration file might look like:</p>
  55 <pre class="programlisting">
  56 module: module.so
  57 # Here is a comment
  58
  59 managed: true
  60 setting.2: A long value with text.
  61 x-custom : text
  62 </pre>
  63 </div>
  64 <div class="refsect1">
  65 <a name="config-module"></a><h2>Module Configuration</h2>
  66 <p>Each configured PKCS#11 module has its own config file. These files
  67         can be <a class="link" href="pkcs11.conf.html#config-locations" title="Configuration Files">placed in various locations</a>.</p>
  68 <p>The filename of the configuration file may consist of upper and lowercase letters
  69         underscore, comma, dash and dots. The first characters needs to be an alphanumeric,
  70         the filename should end with a <code class="literal">.module</code> extension.</p>
  71 <p>Most importantly each config file specifies the path of the PKCS#11 module to
  72         load. A module config file has the following fields:</p>
  73 <div class="variablelist"><table border="0" class="variablelist">
  74 <colgroup>
  75 <col align="left" valign="top">
  76 <col>
  77 </colgroup>
  78 <tbody>
  79 <tr>
  80 <td><p><span class="term"><code class="option">module:</code></span></p></td>
  81 <td>
  82 <p>The filename of the PKCS#11 module to load.
  83                         This should include an extension like <code class="literal">.so</code></p>
  84 <p>If this value is blank, then the module will be ignored.
  85                         This can be used in the user configs to override loading of a module
  86                         specified in the system configuration.</p>
  87 <p>If this is a relative path, then the module will be loaded
  88                         from the <a class="link" href="devel-paths.html#devel-paths-modules" title="Default path for modules with relative paths">default module directory</a>.</p>
  89 </td>
  90 </tr>
  91 <tr>
  92 <td><p><span class="term"><code class="option">critical:</code></span></p></td>
  93 <td>
  94 <p>Set to <code class="literal">yes</code> if the module is critical and
  95                         required to load. If a critical module fails to load or initialize,
  96                         then the loading process for all registered modules will abort and
  97                         return an error code.</p>
  98 <p>This argument is optional and defaults to <code class="literal">no</code>.</p>
  99 </td>
 100 </tr>
 101 <tr>
 102 <td><p><span class="term"><code class="option">enable-in:</code></span></p></td>
 103 <td>
 104 <p>A comma and/or space separated list of names of programs that
 105                         this module should only be loaded in. The module will not be loaded
 106                         for other programs using p11-kit. The base name of the process executable
 107                         should be used here, for example
 108                         <code class="literal">seahorse, ssh</code>.</p>
 109 <p>This is not a security feature. The argument is optional. If
 110                         not present, then any process will load the module.</p>
 111 </td>
 112 </tr>
 113 <tr>
 114 <td><p><span class="term"><code class="option">disable-in:</code></span></p></td>
 115 <td>
 116 <p>A comma and/or space separated list of names of programs that
 117                         this module should not be loaded in. The module will be loaded for any
 118                         other programs using p11-kit. The base name of the process
 119                         executable should be used here, for example
 120                         <code class="literal">firefox, thunderbird-bin</code>.</p>
 121 <p>This is not a security feature. The argument is optional. If
 122                         not present, then any process will load the module.</p>
 123 </td>
 124 </tr>
 125 <tr>
 126 <td><p><span class="term"><code class="option">priority:</code></span></p></td>
 127 <td>
 128 <p>The value should be an integer. When lists of modules are
 129                         returned to a caller of p11-kit, modules with a higher number are sorted
 130                         first. When applications search modules for for certificates, keys and
 131                         trust policy information, this setting will affect what find
 132                         first.</p>
 133 <p>This argument is optional, and defaults to zero. Modules
 134                         with the same <code class="option">priority</code> option will be sorted
 135                         alphabetically.</p>
 136 </td>
 137 </tr>
 138 <tr>
 139 <td><p><span class="term"><code class="option">trust-policy:</code></span></p></td>
 140 <td><p>Set to <code class="literal">yes</code> to use use this module as a source
 141                         of trust policy information such as certificate anchors and black lists.</p></td>
 142 </tr>
 143 </tbody>
 144 </table></div>
 145 <p>Do not specify both <code class="literal">enable-in</code> and <code class="literal">disable-in</code>
 146         for the same module.</p>
 147 <p>Other fields may be present, but it is recommended that field names
 148         that are not specified in this document start with a <code class="literal">x-</code>
 149         prefix.</p>
 150 </div>
 151 <div class="refsect1">
 152 <a name="config-global"></a><h2>Global Configuration</h2>
 153 <p>A global configuration may also be present. This file contains settings
 154         that are not related to a single PKCS#11 module. The location(s) of the
 155         global configuration are described below. The global configuration file
 156         can contain the following fields:</p>
 157 <div class="variablelist"><table border="0" class="variablelist">
 158 <colgroup>
 159 <col align="left" valign="top">
 160 <col>
 161 </colgroup>
 162 <tbody><tr>
 163 <td><p><span class="term"><code class="option">user-config:</code></span></p></td>
 164 <td><p>This will be equal to one of the following values:
 165                 <code class="literal">none</code>, <code class="literal">merge</code>,
 166                 <code class="literal">only</code>.</p></td>
 167 </tr></tbody>
 168 </table></div>
 169 <p>Other fields may be present, but it is recommended that field names
 170         that are not specified in this document start with a <code class="literal">x-</code>
 171         prefix.</p>
 172 </div>
 173 <div class="refsect1">
 174 <a name="config-locations"></a><h2>Configuration Files</h2>
 175 <p>Each configured PKCS#11 module is has its own config file. These
 176         files are placed in a directory. In addition a global config file exists.
 177         There is a system configuration consisting of the various module config
 178         files and a file for global configuration. Optionally each user can provide
 179         additional configuration or override the system configuration.</p>
 180 <p>The system global configuration file is usually in
 181         <code class="literal">/etc/pkcs11/pkcs11.conf</code> and the user global
 182         configuration file is in <code class="literal">~/.pkcs11/pkcs11.conf</code> in the
 183         user's home directory.</p>
 184 <p>The module config files are usually located in the
 185         <code class="literal">/etc/pkcs11/modules</code> directory, with one configuration
 186         file per module. In addition the <code class="literal">~/.pkcs11/modules</code> directory
 187         can be used for modules installed by the user.</p>
 188 <p>The default system config file and module directory can be changed
 189         when building p11-kit. Always
 190         <a class="link" href="devel-paths.html" title="Packaging PKCS#11 module configs">lookup these paths</a> using
 191         <code class="literal">pkg-config</code>.</p>
 192 </div>
 193 <div class="refsect1">
 194 <a name="id-1.5.3.9"></a><h2>See also</h2>
 195 <span class="simplelist"><span class="citerefentry"><span class="refentrytitle">p11-kit</span>(8)</span></span><p>Further details available in the p11-kit online documentation at
 196         <a class="ulink" href="http://p11-glue.freedesktop.org/doc/p11-kit/" target="_top">http://p11-glue.freedesktop.org/doc/p11-kit/</a>.
 197         </p>
 198 </div>
 199 </div>
 200 <div class="footer">
 201 <hr>
 202           Generated by GTK-Doc V1.19</div>
 203 </body>
 204 </html>