Trusted Service

Communication between a KeyServer and its clients can be secured using a “Trusted Service” protocol which supports cryptographic verification of the KeyServer host with digital signing of messages between clients (running KeyAccess) and the KeyServer process, and optional encryption of messages. To enable KeyServer for trusted service, a private key and its associated certificates must be installed on the server. Private keys and certificates are generated and obtained using the same process that is used when obtaining certificates for an SSL-enabled Web service, email server, LDAP server, etc.

Certificate Setup

The "Subject Name" field created within the certificate that you obtain to support KeyServer's Trusted Service must match the fully qualified DNS host name of the computer on which KeyServer will run. Furthermore, this fully qualified DNS name must be used in the KeyAccess setup dialog with exactly the same spelling. Use the PKCS#12 encoding format to store your certificate in a file that is named with the file extension ".pfx". This is the standard file format for storing keys and certificates on Windows. Use OpenSSL to create your .pfx file on Mac OS X, Linux, and Solaris. Place the .pfx file in the KeyServer Data Folder.

Along with the .pfx file, also create a plist text file (XML format) in the KeyServer Data Folder and name it "ks.conf". The ks.conf file must be setup to reference the .pfx file by its file name and also its data as illustrated in the following:

Example:

.pfx file name: “keyserver.domain.org.pfx
KeyServer host name: “keyserver.domain.org
KeyServer password: “MyPassword

Note: in our example we choose to name the .pfx file beginning with the fully qualified host name - but this file name is just a useful convention. It is only necessary that the file name end in .pfx and then the ks.conf illustrated below must reference this file using its exact name.

The ks.conf file must exactly reflect the example information above (including field separators) in its certname string. The file is structured as XML as follows:

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist [
   <!ELEMENT plist         (dict*)>
   <!ATTLIST plist         version CDATA "6.0">

   <!ELEMENT dict          (key*, string*, integer*)>

   <!ELEMENT key           (#PCDATA)>
   <!ELEMENT string        (#PCDATA)>
   <!ELEMENT integer       (#PCDATA)>
 ]>
 <plist version="6.0">
 <dict>
   <key>certname</key>
   <string>keyserver.domain.org:MyPassword@keyserver.domain.org.pfx</string>
 </dict>
 </plist>

Alternatively on Windows, instead of the ks.conf, you can point to the .pfx file through a reference in the Registry:

  HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\KeyServer\certname="keyserver.domain.org:MyPassword@keyserver.domain.org.pfx"


With the .pfx file in place and the ks.conf (or registry) set up, start the KeyServer service. Note that the .pfx and ks.conf files should have very restricted permissions. Ideally, they should only be accessible to the KeyServer process (the account it runs under), and not be readable or writable by other users. The .pfx file contains your KeyServer’s private key, and the ks.conf file contains the password needed to read the private key. If someone were to gain access to your KeyServer’s private key they could set up a separate server that impersonated your real server.

KeyAccess trust setting

By default, KeyAccess clients do not verify the KeyServer’s identity. This is analogous to browsing to a web site with “http://...” instead of “https://...” To have KeyAccess verify KeyServer’s identity, the “trust” preference must be set. This preference is stored in the Registry on Windows and in KeyAccess’s plist on OSX. The client installer can be configured to set this preference at install time. Use k2clientconfig (Win or OSX) as follows:

   k2clientconfg -v trust=1

The preference can also be changed after install:

On Windows:
   HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\KeyAccess\Settings\options\trust="1"

On Mac OS X, in Terminal:

   sudo defaults write /Library/Preferences/com.sassafras.KeyAccess trust 1

A trust setting of 1 tells KeyAccess to try making a trust connection to KeyServer. If the KeyServer identity cannot be verified, KeyAccess will still connect to it without trust. This setting can be used to test that the server is properly configured.

A trust setting of 2 tells KeyAccess to trust the identity of KeyServer even if the server’s certificate has a mismatched Subject name, or is signed by an unknown authority. Even in this case where the validating authority is not trusted, the certificate's digital signature must still be verified as "valid" before KeyAccess can successfully connect to the KeyServer.

A trust setting of 10 tells KeyAccess to trust only a valid certificate with a subject name that matches the KeyServer’s host name, signed by a trusted authority. If the certificate does not satisfy these criteria KeyAccess will not connect to KeyServer. This is the setting that should be used once you are sure that the server is configured properly.

A trust setting of 0 puts KeyAccess back to its default, which is to forego verifying KeyServer’s identity.

Note that KeyAccess must use the full DNS name (keyserver.domain.org in the example) when it connects to KeyServer. If an alias or IP address is used this value will not match the certificate’s Subject name, so the verification will fail.

Also note that the trust setting applies to all connections the client might make. If KeyShadows are used, they must all have valid certificates (and keys) stored in PFX files etc.

KeyAccess security setting

By default, communication between KeyAccess clients and KeyServer is not encrypted. To encrypt packets, the KeyAccess “security” preference must be set. Then when KeyAccess establishes a connection with KeyServer, it requests (or requires) that communication be encrypted. This preference is stored in the Registry on Windows and in KeyAccess’s plist on OSX. The client installer can be configured to set this preference at install time. Use k2clientconfig (Win or OSX) as follows:

   k2clientconfg -v security=1

The preference can also be changed after install:

On Windows:
   HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\KeyAccess\Settings\options\security="1"

On Mac OS X, in Terminal:

   sudo defaults write /Library/Preferences/com.sassafras.KeyAccess security 1

A security setting of 1 tells KeyAccess to request encryption from KeyServer. If the KeyServer cannot do encryption, KeyAccess will still connect to it without encryption. This setting can be used to test that the server is properly configured.

A security setting of 2 tells KeyAccess to require encryption from KeyServer. If communication cannot be encrypted, KeyAccess will not make the connection. If you want to use encryption, this is the setting that should be used once you are sure that the server is configured properly.

Note: the ability to encrypt packets can be turned off in the server.lic file, which disables this feature for the KeyServer.