TDI Server Instance Security

This section does not deal with the specifics of client (TDI-based or other) access to a TDI Server, this is discussed in Remote Server API; instead, it focuses on the encryption algorithms used, and the miscellaneous configuration files needed to set up a server instance.

The TDI Server requires a keystore containing both its private key and associated certificate/public key that is used for PKI encryption of Config Files, properties in Properties files, Server User registry files and other objects, as well as being used for SSL communication.

The system properties api.keystore and api.key.alias specify the keystore and the key alias of the Server's certificate/key within the keystore. The password of the keystore and the password of the key itself (if different from the keystore password) are specified in the Server's stash file. Access to a keystore is guarded by a password, defined at the time the keystore is created, by the person who creates the keystore, and changeable only when providing the current password. In addition, each private key in a keystore can be guarded by its own password. For more information on the stash file of the server, see section Stash File.

The RSA algorithm is used for encryption of files and property values. It is used as a block cipher where the block size is determined by the modulus component of the RSA key. Encryption is done in ECB (Electronic Codebook) mode. PKCS#1 Padding is applied separately on each block. Note that the same RSA key-pair, which is used for encryption of files, is also used for SSL communication with the Server. TDI uses the RSA implementation from the IBMJCE security provider. All key sizes supported by that provider are also supported by TDI. From TDI v7.0, secret key ciphers can also be employed for encryption. RSA is used the default for backward compatibility reasons, but secret key ciphers are much faster and much more secure than public key ciphers.

DES and AES algorithms are used for encryption of password-protected configuration files. An encryption key (DES or AES) is derived from the UTF-8 binary representation of the password. The derived encryption key is 64 bit for DES and 128 bit for AES. ECB mode is used with no padding.

DES/AES keys are derived from passwords, when using password-protected configuration files. Apart from the above, the TDI does not generate keys. Existing keys are loaded from an external key store. Key establishment and key store access are performed through the IBMJCE and IBMJSSE2 security providers. All key sizes and algorithms supported by those providers can be used with the TDI.

Stash File

The stash file contains the Server keystore password values encrypted with AES128 with a fixed key. The Server stash file is named "idisrv.sth" (the name is not configurable) and it is loaded by the Server from the Solution Folder. A command line utility for creating a stash file is available in the TDI bin folder: createstash.bat or createstash.sh:

createstash <keyStorePassword> [<keyPassword>] [<securityProviderClass>]]

where keyStorePassword is the password of the keystore file specified by the api.keystore system property and <keyPassword> is the password of the Server's private key specified by the api.key.alias system property.

keyPassword is an optional parameter if no <securityProviderClass> parameter is specified. If <keyPassword> is not specified it is assumed that the Server's private key password is the same as the keystore's password. To use the utility with the <securityProviderClass> parameter, specify both previous parameters: keyStorePassword and keyPassword. If a security provider is specified then this provider is used for the cryptography.

The utility creates a stash file named "idisrv.sth" with the specified password(s) in the current directory.

Attention: IBM TDI 7.1 comes bundled with a sample stash file, with a password of "server". For improved security, we strongly advise you to generate our own stash file using the aforementioned utility. Also, the stash file must be kept inaccessible, except for the actual TDI Server that needs it.

Server Security Modes

The TDI Server can run in two modes: standard and secure.

Standard mode

When run in standard mode, the Server does not PKI encrypt configurations saved on disk, unless a specific Server API call that requests PKI encryption is invoked. When in this mode the Server is able to read both encrypted and unencrypted configurations.

Secure mode

When run in secure mode the Server encrypts all configurations it saves on the disk using PKI encryption. In secure mode the Server can only read and load encrypted configurations. When the system property com.ibm.di.server.securemode is set to "true", the Server runs in secure mode. (A system property for the use of the TDI Server can be set by adding it in the global.properties or solution.properties file or directly specify it on the java command line when starting the TDI server: -Dcom.ibm.di.server.securemode=true)

If the command line option -e is specified on the java command line when starting the Server, it runs in secure mode regardless of the value of the com.ibm.di.server.securemode system property.

Pre-TDI 6.0 password-based encryption of configuration files is supported for backward compatibility. Password-based encryption is used when the user specifies a password when creating the configuration. Pre-TDI 6.0 password-based configuration encryption cannot be combined with PKI encryption. If you specify a password when the Server is run in secure mode, an error message is displayed.

Working with encrypted TDI configuration files

Introduction

To provide confidentiality of data, TDI (TDI) can encrypt configuration files, property values in properties files, server user registry files and JavaScript files.

TDI encryption involves a cryptographic transformation that uses a key or a key-pair. The key/key-pair needs to be hosted in a keystore file.

The cryptographic transformation can be either public-key encryption or secret key encryption. By default TDI uses public key encryption. (The secret key encryption option has been introduced in TDI 7.0. Before that only public key encryption was supported.)

See:

Public key encryption utilizes a key-pair that consists of a public key and a private key. The public key is used for encryption and the private key is used for decryption. Currently only the RSA cipher is supported for public key encryption. Public/private key pairs can be generated and managed using the standard JRE utilities keytool and Ikeyman. See Manage keys, certificates and keystores for more information on managing certificates with associated public and private keys.

TDI data encryption is configured by the following system properties (these can be set in global.properties or solution.properties):

• com.ibm.di.server.encryption.keystore : the keystore file that contains the key/key-pair for encryption

• com.ibm.di.server.encryption.keystoretype : the type of the keystore file

• com.ibm.di.server.encryption.key.alias : the alias of the key/key-pair in the keystore

• com.ibm.di.server.encryption.transformation : the name of the encryption transformation; see remarks below

The password of the keystore and the password of the key/key-pair itself (if different from the keystore password) are specified in the Server's Stash File. (Access to a keystore is guarded by a password, defined at the time the keystore is created, by the person who creates the keystore, and changeable only when providing the current password. In addition, each private key in a keystore can be guarded by its own password.)

The name of the transformation can be either RSA or some secret key transformation (for example, AES/CBC/PKCS5Padding). More detailed discussion of what is in a transformation name can be found at http://www-128.ibm.com/developerworks/java/jdk/security/50/secguides/JceDocs/api_users_guide.html#trans; general information about Java Security (which is what TDI uses) can be found at http://www-128.ibm.com/developerworks/java/jdk/security/60/secguides/jsse2Docs/JSSE2RefGuide.html.

Notes:

1. The "com.ibm.di.server.encryption.*" properties affect not only encryption of configurations, but also encryption of property files, JavaScript™ files and the Server API User Registry.

2. If you change the encryption key and/or the encryption transformation, the Server cannot decipher previously encrypted files. To work around this problem, decrypt the old files with the old key ( have the old key available in order to do so) and encrypt them with the new key. Encryption and decryption of files can be done with the cryptoutils tool.

3. The standard RSA algorithm has a restriction on the length of data it can work on. TDI uses a custom scheme that splits input data into small enough equally sized blocks and encrypts each of them separately.

4. Data encrypted with RSA result in different cipher-texts on different encryption runs. This effect is a feature of the PKCS#1 padding scheme used with RSA.

5. A secret key (symmetric) cipher can be either a block cipher or a stream cipher. Stream ciphers encrypt the bits of the message one at a time, and block ciphers take a number of bits and encrypt them as a single unit (a block). Block ciphers (for example, AES) use a feedback mode (so that patterns in the plain-text are not preserved in cipher-text) and a padding scheme (to allow encryption of data, whose length is not multiple of the block size of the cipher). Stream ciphers (for example, RC4) do not use a feedback mode and a padding scheme.

6. If the transformation involves a block cipher, it must use some padding scheme (for example, "PKCS5Padding"), otherwise the Server not be able to encrypt data whose length is not multiple of the block size of the cipher. (Stream ciphers do not use padding, so they are not affected by this restriction.)

7. The algorithm of the key/key-pair must match the algorithm in the specified transformation. For example if the transformation is RSA then an RSA key-pair must be provided; if the transformation is DES/ECB/PKCS5Padding, provide a DES key. We can generate a new secret key using the keytool utility, see Manage keys, certificates and keystores.

8. JKS keystores do not support secret keys, so we should use some other keystore type such as JCEKS if we want to use a secret key encryption.

9. When using a block cipher in a feedback mode that requires an initialization vector (IV), encrypted data is prefixed with the initialization vector as plaintext. The IV does not have to be kept secret but must be unpredictable. That is why a random IV is generated for each piece of data that is being encrypted. Generation of random data can sometimes be resource-intensive, so you may wish to consider a non-IV feedback mode (ECB) if performance is an issue.

10. Which secret key transformations are supported for encryption depends on the capabilities of the Java security provider. By default TDI uses the IBMJCE provider. Supported block ciphers are: DES, AES, DESede (Triple DES), Blowfish and RC2. They can be used in any of the following feedback modes - ECB, CBC, CFB, OFB, PCBC. The only available padding scheme is "PKCS5Padding". The MARS block cipher should not be used for encryption, because it does not support padding (http://www-128.ibm.com/developerworks/java/jdk/security/50/secguides/JceDocs/api/com/ibm/crypto/provider/Mars.html). Supported stream ciphers are RC4 and ARCFOUR (basically the same cipher under two different names). The SEAL stream cipher requires large keys (160 bit) so it can be used only after configuring unrestricted IBM SDK policy on the TDI JRE (http://www-128.ibm.com/developerworks/java/jdk/security/50/#sdkpol).

Separation of certificates for PKI Encryption and SSL

Creating an encrypted TDI configuration file from scratch

This is how we create an encrypted IBM TDI configuration file from scratch.

Using the cryptoutils command line tool

1. Create a normal un-encrypted TDI configuration file using the Configuration Editor.

2. Use the cryptoutils command line tool to encrypt this configuration file as described in the "The TDI Encryption utility" section.

3. In order to run this encrypted configuration file start the TDI server in secure mode as described in the "Server Security Modes" section.

4. In order to edit this encrypted configuration file we can use one of two options described in the "Editing an encrypted TDI configuration file" section.

Editing an encrypted TDI configuration file

We can first decrypt the encrypted configuration file using the cryptoutils command line tool as described in the "The TDI Encryption utility" section. Then we can edit the decrypted configuration using the Configuration Editor and finally we can encrypt back the modified configuration file using the cryptoutils tool.

Standard TDI encryption of global.properties or solution.properties

The global.properties and solution.properties files store a number of properties, some of which can represent sensitive data such as passwords. In order to protect this sensitive data TDI 7.1 is capable of encrypting this data.

All properties whose names are prefixed with {protect}- are PKI encrypted by the Server using the Server's public key. The Server's key is specified by the com.ibm.di.server.encryption.key.alias property from the keystore specified by the api.keystore property. For example, if we want to encrypt a property com.ibm.di.server.encryption.keystore you can add the following line in the global.properties or solution.properties file:

{protect}-com.ibm.di.any.property=some_value

The next time the Server runs it detects that this property has to be encrypted and it immediately overwrites the file, writing the plain text value "some_value" in encrypted form.

On some operating systems (z/OS, Linux/UNIX systems if so configured) the global.properties file might not be accessible for writing. In this case the server outputs a warning message that the file has not been written/encrypted.

Protecting the properties in global.properties or solution.properties is also accessible from the "Global-Properties" and "Solution-Properties" Property Stores accessible from the Browse Server Stores option in the Configuration Editor.

Encryption of properties in external property files

Properties stored in external property files can be protected by encryption in just the same way as properties in the global.properties or solution.properties can.

Instead of using the server's default certificate, it is possible to encrypt properties in external property files using a specifically named certificate from the server's keystore.

For more information on encrypting properties stored in these files, see the Standard TDI encryption of global.properties or solution.properties section. The syntax of properties in an external property file is as follows:

[{protect}-]keyword <colon | equals> [{encr}][{java}]value 

• The optional {protect}- prefix signals that the value either is or should be encrypted. When the value starts with the character sequence {encr} it means that the value is already encrypted.

• The optional {java} value prefix signals that the value is a serialized java object. The value must be b64-encoded. For example:

  {protect}-api.truststore.pass={encr}J8AKimpEutu3BblOVg55F/5d5vO2kXWcNUWnCq3vINUc6K0719z9dEk3H43Ot2iTT1dZTI6FSSVin9KsCy
  BLmgv+n84w7HelKl3ro2dFmZbTYKMXuxGoqN9nL2VOvZoptNqzoWvs6IN/p3VkIIBtlao/9mEPEKuIwRnKtkQ89Bg=

The TDI Encryption utility

In the TDI_install_dir/serverapi directory you find a utility (cryptoutils) which enable you to decrypt and re-encrypt files, (for example, the Identity Registry file) such that we can edit the file manually.

The tool recognizes the following command-line parameters:

inputFile

{required} Specifies the file to be encrypted or decrypted.

outputFile

{required} Specifies the new file that is created with the resulting data after the encryption or decryption is done. If the file exists, it is overwritten.

mode

{required} Specifies the mode in which the tool operate; it can be one of the following modes:

• encrypt: encrypt user registry

• decrypt: decrypt user registry

• encrypt_config: encrypt a TDI configuration file or a JavaScript file

• decrypt_config: decrypt a TDI configuration file or a JavaScript file

• encrypt_props: encrypt the values of all protected properties in a TDI properties file

• decrypt_props: decrypt the values of all protected properties in a TDI properties file

User Registry files are encrypted differently from configuration and JavaScript files.

keyStore

{required} Keystore file which contains the key for encryption/decryption.

storepass

{required} Password of the keystore file.

alias

{required} Specifies the alias of the encryption/decryption key in the keystore

keypass

{optional} Password of the encryption/decryption key; by default, the keystore password is used to access the key

transformation

{optional} Specifies the name of the cryptography transformation used for encryption/decryption; can be RSA or any secret key transformation (for example, AES/CBC/PKCS5Padding); the default is RSA.

storetype

{optional} Specifies the type of the keystore file (for example, JKS); this parameter is case-insensitive (JCEKS and jceks are equivalent); if this parameter is missing, the default keystore type of the JRE (configured by the "keystore.type" security property in the java.security file of the JRE) is used.

cryptoproviderclass

{optional} Specifies the Java security provider which is used for encryption/decryption (but not for keystore access); by default the providers from the security provider list of the JRE (configured in java.security JRE file) is used.

Examples:

Encrypt the User Registry

A TDI Server running in secure mode requires that the User Registry is encrypted with the Server key.

We can encrypt a plaintext User Registry file like this:

cryptoutils -input registry.txt -output registry.enc -mode encrypt -keystore ../testserver.jks -storepass server -alias server

Decrypt a TDI configuration

cryptoutils -input myconfig.enc.xml -output myconfig.xml -mode decrypt_config -keystore ../testserver.jks 
  -storepass server -alias server 

This command decrypts the "myconfig.enc.xml" configuration file (possibly created by a TDI Server, which runs in secure mode). Now the decrypted configuration "myconfig.xml" can be easily modified using the Configuration Editor. After modifying the configuration, it can be encrypted again, so that a TDI Server in secure mode can read and use it.

Encrypt a TDI configuration using a symmetric cipher (rather than the default "RSA")

cryptoutils -input myconfig.xml -output myconfig.enc.xml -mode encrypt_config -keystore ../server.jck
  -storepass server -alias server -transformation AES/CBC/PKCS5Padding -storetype jceks

The above command assumes that the keystore "server.jck" exists. That keystore is supposed to contain an AES secret key under alias "server".

Decrypt the global.properties file

The TDI Server automatically encrypts the values of protected properties when reading the global.properties or solution.properties file.

We can decrypt all encrypted values in the global.properties file like this:

cryptoutils -input ../etc/global.properties -output ../etc/global.properties -mode decrypt_props
 -keystore ../testserver.jks -storepass server -alias server

When the cryptoutils tool is used to encrypt and decrypt the User Registry, configuration files (see the "Server Security Modes" section for details how the server treats encrypted configurations) or Encryption of TDI Server Hooks, it encrypts and decrypts a file as a whole.

On the other hand, the encryption/decryption mode for property files encrypts/decrypt only the values of the protected properties and not the whole file. Thus after encrypting a .properties file using encrypt_props mode, the property keys and the comments in the file are still readable by humans. For more information on protected properties see sections Standard TDI encryption of global.properties or solution.properties and Encryption of properties in external property files.