Project

General

Profile

Wiki » Documentation » Installation Configuration and Administration Guide » Directory Configuration Reference »

Certificates

The Certificates section of the directory enumerates the Certificate Authority (CA) certificates and peers certificates needed for the secure mode to operate. These certificates are listed in /security/certificates/ directory section and will be loaded at server start-up. See the chapters entitled Certificate Authority and Key-Stores and Trust-Stores for details on creating and importing certificates. For details about how to configure all the certificates using an automatically generated self-signed certificate as the root CA, see the Cryptography Setup Helper chapter of this book.

Search Algorithm

There is no search algorithm used for reading the certificates directory section. All configurations are global for the directory and can be found under the /security/certificates/ absolute path.

Example

<node class="container" name="security">
   <node class="container" name="certificates">
      <node class="container" name="cas">
         <node class="bytes" name="acme-root">
            <node-attribute name="value" value="ENCODED_ROOT_CA_WOULD_GO_HERE"/>
         </node>
      </node>
      <node class="container" name="peers">
         <node class="bytes" name="my_server1">
            <node-attribute name="value" value="ENCODED_CERTIFICATE_WOULD_GO_HERE"/>
         </node>
         <node class="bytes" name="my_server2">
            <node-attribute name="value" value="ENCODED_CERTIFICATE_WOULD_GO_HERE"/>
         </node>
         <node class="bytes" name="batch_program1">
            <node-attribute name="value" value="ENCODED_CERTIFICATE_WOULD_GO_HERE"/>
         </node>
      </node>
   </node>
</node>

Reference

The following options can be specified:

Option ID Data Type Default Value Required Details
cas container n/a No This parameter enumerates CA certificates. Each child node of this node must have the bytes class.
cas\<ca_name> bytes n/a No This parameter specifies a CA certificate. <ca_name> should be unique within the cas container node. The value of the node attribute of this node will contain the certificate.
peers container n/a No This parameter enumerates peers certificates. Each child node of this node must have the bytes class.
peers\<peer_name> bytes n/a No This parameter specifies a peer certificate. <peer_name> should be unique within the peers container node. The value of the node attribute of this node will contain the certificate.

Private Keys

When configuring the certificates using the SSLCertGenUtil FWD built-in tool (which automatically generates the certificates and their private keys using a self-signed root CA, which itself is automatically generated), it is possible to save the private keys (for the certificates and root CA) within the directory. In this case, the private keys will be encrypted using random-generated passwords; these passwords can be either saved within the directory or externally, in the bootstrap config files (for the server and client):

  • when the passwords are saved in the server's bootstrap config, they need to be specified via the access:password:keyentry-<alias> config, where <alias> is replaced with the certificate's alias. If all the private keys are encrypted using the same password, then this password can be specified via the access:password:masterkeyentry config.
  • when the passwords are saved in the directory, they will be hex-encoded. To ensure security, this requires that either the directory file is encrypted or permissions to read this this file are carefully configured.

In the directory, the private keys and their encryption passwords are saved in the security/certificate/private-keys node, for each certificate alias (including the root CA). For each alias, there will be:

  • a security/certificate/private-keys/<alias>/key-entry node, holding the hex-encoded, encrypted, private key. After decryption, this will be used to de-serialize a java.security.PrivateKey instance.
  • a security/certificate/private-keys/<alias>/key-password node, holding the hex-encoded password, used to encrypt this private key.

Both nodes are optional (as they can be also configured via the boostrap config file) and their data type is bytes. Bellow is an example of how these nodes can look like, after the SSLCertGenUtil is ran:

<node class="container" name="security">
   <node class="container" name="certificates">
      <node class="container" name="private-keys">
         <node class="container" name="acme-root">
            <node class="bytes" name="key-entry">
              <node-attribute name="value" value="ENCRYPTED_AND_ENCODED_PRIVATE_KEY_WOULD_GO_HERE"/>
            </node>
         </node>
         <node class="container" name="my-server1">
            <node class="bytes" name="key-entry">
              <node-attribute name="value" value="ENCRYPTED_AND_ENCODED_PRIVATE_KEY_WOULD_GO_HERE"/>
            </node>
            <node class="bytes" name="key-password">
              <node-attribute name="value" value="ENCODED_ENCRYPTIOPN_PASSWORD_WOULD_GO_HERE"/>
            </node>
         </node>
         <node class="container" name="my-server2">
            <node class="bytes" name="key-entry">
              <node-attribute name="value" value="ENCRYPTED_AND_ENCODED_PRIVATE_KEY_WOULD_GO_HERE"/>
            </node>
            <node class="bytes" name="key-password">
              <node-attribute name="value" value="ENCODED_ENCRYPTIOPN_PASSWORD_WOULD_GO_HERE"/>
            </node>
         </node>
         <node class="container" name="batch-program1">
            <node class="bytes" name="key-entry">
              <node-attribute name="value" value="ENCRYPTED_AND_ENCODED_PRIVATE_KEY_WOULD_GO_HERE"/>
            </node>
            <node class="bytes" name="key-password">
              <node-attribute name="value" value="ENCODED_ENCRYPTIOPN_PASSWORD_WOULD_GO_HERE"/>
            </node>
         </node>
      </node>
   </node>
</node>

Note that the FWD server does not use the private key for the root CA. This can be safely removed and stored in an external, secure, location. Also, the encryption password for the root CA's private key will not be saved in the directory.

© 2004-2017 Golden Code Development Corporation. ALL RIGHTS RESERVED.