Purpose

The purpose of the SecretApi is to protect secrets while they are at rest and to increase the difficulty of anyone retrieving the secrets. The secrets are initially passwords for miscellaneous services like FTP accounts - but not the Link user account passwords.

The passwords stored as secrets are passwords for external services that Link and/or BizTalk needs to authenticate to during transactions. All secrets are stored encrypted in the database the application encryption key is stored separately, also in the database.

Depending on the configuration, the encryption key can also be stored encrypted using other means, for instance asymmetric encryption based on certificates. For the most advanced scenario, it is possible to develop and deploy a proprietary encryption module, that can handle encryption and decryption of the application encryption key using other means, for instance a hardware device.

Design

The design of the SecretsApi is based on two database tables and interfaces and classes exposed by the Bizbrans.SecretApi.dll. The actual secrets are encrypted using AES 256-bit encryption (symmetrical) and the application encryption key is either unencrypted, RSA encrypted (asymmetrical) or using a user plugin.

The design specifically ensures the option to change the protection of the application encryption key. The encryption can be changed between the mentioned methods and furthermore it is also possible to generate (or insert) a new key. To use a new key, all existing secrets must be converted from old to new key. This is handled by the Administration Tool, when the key is changed, and the design facilitates this with very little downtime.

Structure

The Secret

Crypto-providers are used to manage encryption and decryption of the actual secrets. At present, there are only two providers, a clear text provider (which means unencrypted) and an AES 256-bit encryption. The clear text provider is used when converting existing passwords and replaced afterwards. Al other situations use the AES provider. This is not user configurable.

Key Encryption Plug-ins are used to manage encryption and decryption of the application encryption keys. These also include an unencrypted option, as well as RSA and custom plug-ins.

When a secret must be stored, the clear text value is encrypted using the current (primary) application key and the active crypto provider. The encrypted value is entered in a new row in the database along with necessary metadata, like timestamps and the id of the crypto provider and the application encryption key that is used etc.

Updating an existing secret with a new value consist merely of encrypting the new value and then updating the row and metadata as appropriate. By keeping the same id, all references now reference the new value.

The secret references the crypto provider and the application encryption key (the [tEncryptionKeys] table) which is used and with access to these, the necessary information is available to decrypt the secret.

The Application Key

The application (encryption) key is the key used to encrypt all the actual secrets. There is only one active (primary) application key. When encrypting a secret, the active application key is used together with the current crypto provider to encrypt the key.

To protect the application key it it possible to choose a key encryption plug-in. There are two options provided and the user can supply more options via plug-in modules. The application key is encrypted with the chosen plug-in and the plug-in and the key encryption key is also stored. This allows the same plug-in to be used when the application key must be decrypted.

The contents of the key encryption key is entirely dependent on the plug-in used. For the unencrypted option, this value is ignored and does not matter, the supplied RSA plug-in requires the key encryption key to be the serial number of a certificate in the Windows Certificate Store and for custom plug-ins it can be whatever the plug-in requires to supply encryption and decryption.

The Link Administration tool can be used to generate a new application key and to switch the key encryption plugin used. See Administration Tool. When changing the application key, all existing secrets are re-encrypted to apply the new application key.

Conversion

During the conversion of passwords from prior versions passwords are moved to the SecretsApi, but to ensure a smooth conversion, data are not encrypted in this pass. The secrets are stored using the clear text crypto provider, except passwords for certificate private keys, which are already encrypted and that remains. Similarly an new application encryption key is created in the table, but the key is hardcoded and also unencrypted. This means that after conversion secrets are as safe as the passwords were before - actually a little safer as it is a bit more difficult to get to them. However, it is advisable to use the Link Administration tool to generate a new application encryption key and select a stronger encryption method. When doing this, all secrets are reprocessed and security is increased significantly.

Flow Diagrams

Retrieve a secret

Store a secret

Content on this page: