LibPKI configuration files

From OpenCA::Wiki

LibPKI uses a series of configuration files/directory to provide an easy way for application developers to use different PKI_TOKEN.


Table of contents
1 The Configuration Directory Structure
2 The HSM configuration files

2.1 OpenSSL ENGINE Example
2.2 PKCS#11 Example
2.3 Software HSM Example

[edit]

The Configuration Directory Structure

The basic configuration directory structure is as follows: 

 $(HOME)/.libpki/
            |
            +----> hsm.d/
            |
            +----> token.d/
            |
            +----> profile.d/
            |
            +----> store.d/
            |
            +----> private/
            |
            +----> objectIdentifiers.xml

The default locations that are automatically scanned for the existence of the .libpki/ directory are: 

     $(HOME)/.libpki/
     $(LIBPKI_PREFIX)/etc/.libpki/
     $ /etc/libpki/

Each of the .libpki sub-directories contain a specific set of configuration files. If you are familiar with public key crypto, you probably have already figured that out already. If not.. here's a brief explanation of the contents of each directory:

  • hsm.d - Configuration files for the available hardware security modules
  • token.d - Configuration files for the available PKI_TOKEN
  • profile.d - Configuration files for certificate/requests profiles
  • store.d - Configuration files for certificate/keys stores
  • private - Private Keys
  • objectIdentitifiers.xml - Configuration for specific OIDs not directly supported by LibPKI that are loaded when the library is initialized.

Notice that all the configuration files for libpki are XML files. This should make it easy to develop GUIs for configuring your PKI_TOKEN and HSMs.


[edit]

The HSM configuration files

In order to configure Hardware modules, you need to provide a configuration file that describes the device capabilities. Don't worry, it is very easy!

LibPKI supports the following type of HSMs:

  • OpenSSL Engine
  • PKCS#11


[edit]

OpenSSL ENGINE Example

Here's is an example of an HSM configuration file to use Alladin eToken USB devices via the OpenSSL ENGINE interface: 

<?xml version="1.0" ?>
<!-- Hardware Module Configuration -->
<pki:hsm xmlns:pki="http://www.openca.org/openca/pki/1/0/0">
  <!-- HSM Name -->
  <pki:name>etoken-engine</pki:name>
  <!-- Token Type (kmf, engine) -->
  <pki:type>engine</pki:type>
  <!-- HSM ID that pilots the HSM. Depending on the type of HSM
       it can be:
        * id:// - for kmf (name of the hw token)
        * id:// - for ENGINE openssl extensions
        * file:// - library file for PKCS11 tokens (not supported now)
  -->
  <pki:id>id://dynamic</pki:id>
  <!-- Private key identifier (URI - file:// id:// etc.. ) and
       certificate details should be specified in the token config
       file -->
  <!-- We have different sections: init, pre, post, finalize -->
  <!--
  <pki:init>
    These commands are reserved for initializations, most of tokens
    use their own tools
    <pki:cmd label=""></pki:cmd>
  </pki:init>
  -->
  <!-- PRE and POST commands are reserved for ENGINE tokens -->
  <pki:pre>
    <pki:cmd>SO_PATH:/usr/lib/libeTPkcs11.so</pki:cmd>
    <pki:cmd>ID:pkcs11</pki:cmd>
    <pki:cmd>LIST_ADD:1</pki:cmd>
    <pki:cmd>LOAD</pki:cmd>
    <!-- For new 4.55+ drivers (on Linux) use the new path to the
         right PKCS#11 libraries: 
                MODULE_PATH:/usr/lib/libeTPkcs11.so
    -->
    <pki:cmd>MODULE_PATH:/usr/local/lib/libetpkcs11.so</pki:cmd>
  </pki:pre>
  <!--
  <pki:post>
    <pki:cmd label=""></pki:cmd>
  </pki:post>
  -->
  <!-- Here is where the Token Password - or SO password (if any) - should
       go -->
  <pki:passin>stdin</pki:passin>
  <!-- ... or simply specify the password here -->
  <!-- <pki:passwd></pki:passwd> -->
</pki:hsm>


[edit]

PKCS#11 Example

Now, here's an example of how you can use the same token by using the provided (by alladin) PKCS#11 library (which is the most used standard available across different systems): 

  <?xml version="1.0" ?>
  <!-- Hardware Module Configuration -->
  <pki:hsm xmlns:pki="http://www.openca.org/openca/pki/1/0/0">
    <!-- HSM Name -->
    <pki:name>etoken-pkcs11</pki:name>
    <!-- Token Type (kmf, engine) -->
    <pki:type>pkcs11</pki:type>
    <!-- HSM ID that pilots the HSM. Depending on the type of HSM
         it can be:
          * id:// - for kmf (name of the hw token)
          * id:// - for ENGINE openssl extensions
          * file:// - library file for PKCS11 tokens (not supported now)
    -->
    <pki:id>file:///usr/lib/libeTPkcs11.so</pki:id>
    <!-- If the keyextractable is set to 'yes', the generated keys will
         be exportable. Default is non-exportable -->
    <pki:keyexportable>no</pki:keyexportable>
    <!-- Here is where the Token Password - or SO password (if any) - should
         go -->
    <pki:passin>stdin</pki:passin>
    <!-- ... or simply specify the password here -->
    <!-- <pki:passwd></pki:passwd> -->
  </pki:hsm>


[edit]

Software HSM Example

For Software Tokens, there's no need for an HSM configuration at this time, this might change in the future to support additional features of different cryptographic layers.

Retrieved from "http://wiki.openca.org/wiki/index.php/LibPKI_configuration_files"