Trusted Service/ HTTPS Tunnel

Note: KeyServer/KeyAccess 7.7.0.1 and later have the ability to use https for the client connection to the server (set KeyAccess to use https://[servername] as the server address). This will encrypt all traffic (including headers) and does not require other client side modifications or a special license or second cert on the server. It will however increase network overhead as it will be using TCP instead of UDP, so plan accordingly. You will need to have a valid SSL Certificate in place for the Web Service. Note also that because use of the tunnel precludes server to client communications, all actions can only be initiated during client contact which can be every 10-15 minutes. This is similar to when a client is behind a NAT, but means that messages and audit requests will take longer than with clients on a local network that allows UDP responses.

Overview

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.

Note: The ability to encrypt packets must be enabled in the server.lic file by Sassafras Software (it will read "feature.exportable= no" when enabled). If you wish to use this feature please request a license file that enables it from Sassafras Software Sales. The feature is subject to international security regulations and may not be available in some countries. Be aware that use of KeyAccess 7.7 or later on Linux requires OpenSSL 1.1.1 or later. We are also aware that OpenSSL 1.0 likely will not work with Trust settings with any version of KeyAccess. Earlier versions are of course not recommended at this point for security reasons, but did work historically with earlier client versions.

Note: There are header packets sent in the clear before the trust is established and the rest of the traffic is encrypted. This header information includes the logged in username, the ComputerID, and the computer name. Because of this you may want to use the https tunnel instead.

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 MacOS and Linux. 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"

Also note that with Windows if the certificates are in the normal local cert storage and KeyServer is running under the local system account, the string in the above example can simply be keyserver.domain.org: and that will indicate to look for a cert for that domain name in the Windows cert store. That is, everything after the : is eliminated and you don't need a pfx file.

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 Mac) as follows:

   k2clientconfig -v trust=1

To set the preference on Windows without modifying the installer, e.g., for use in remote install scripts, use this option for the installer command (requires version 7.5.0.5 or higher of the client installer):

   ksp-client-x64.exe -v PROP_TRUST=1

The preference can also be changed after install:

On Windows (reg dword): 
   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
On Linux you can edit the /usr/share/ka/ka.xml file and add the key: 
   <key>trust</key>
   <string>1</string>

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. These settings should not be used with the https tunnel. Use k2clientconfig (Win or Mac) as follows:

   k2clientconfig -v security=1

To set the preference on Windows without modifying the installer, e.g., for use in remote install scripts, use this option for the installer command (requires version 7.5.0.5 or higher of the client installer):

   ksp-client-x64.exe -v PROP_SECURITY=1

The preference can also be changed after install:

On Windows (reg dword): 
   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
On Linux you can edit the /usr/share/ka/ka.xml file and add the key: 
   <key>security</key>
   <string>1</string>

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.

A security setting of 0 will set KeyAccess to the default, which is to not use encryption.