Message Property Encryption

Message property encryption is available as a dedicated NuGet package. The API documented on this page will continue to work for NServiceBus Version 6 but it will hint about its upcoming obsoletion with the following warning: Message property encryption is released as a dedicated 'NServiceBus.Encryption.MessageProperty' package..

Property encryption operates on specific properties of a message. The data in the property is encrypted, but the rest of the message is clear text. This keeps the performance impact of encryption as low as possible.

The encryption algorithm used is Rijndael.

Keep in mind that the security is only as strong as the keys; if the key is exposed, then an attacker can decrypt the information. Encryption keys should not be stored on the client (if deployed remotely) or even on a web server in the DMZ.

Encryption is enabled when explicitly configured with either endpointConfiguration.RijndaelEncryptionService or endpointConfiguration.RegisterEncryptionService.

Defining encrypted properties

There are two ways of telling NServiceBus what properties to encrypt.

Convention

Given a message of this convention

public class MyMessage :
    IMessage
{
    public string MyEncryptedProperty { get; set; }
}

Encrypt MyEncryptedProperty.

var conventions = endpointConfiguration.Conventions();
conventions.DefiningEncryptedPropertiesAs(
    definesEncryptedProperty: propertyInfo =>
    {
        return propertyInfo.Name.EndsWith("EncryptedProperty");
    });

Property type

Use the WireEncryptedString type to flag that a property should be encrypted.

using NServiceBus;

public class MyMessage :
    IMessage
{
    public WireEncryptedString MyEncryptedProperty { get; set; }
}

Enabling property encryption

Property encryption is enabled via the configuration API.

endpointConfiguration.RijndaelEncryptionService();

Key ID

Each key needs an unique key ID (KeyIdentifier). The key ID is communicated in the message header and allows the receiving endpoint to use the correct decryption key.

If a key ID is not set then no messages with encrypted properties can be sent. When NServiceBus receives a message without a key ID header, it will attempt decryption using all keys in the configuration. If all decryption attempts fail, the message will be moved to the error queue.

Troubleshooting

Error: Encrypted message has no 'NServiceBus.RijndaelKeyIdentifier' header. Possibility of data corruption. Upgrade endpoints that send messages with encrypted properties.

Key IDs are only supported in the following versions

  • NServiceBus 3.3.16+
  • NServiceBus 4.7.8+
  • NServiceBus 5.0.7+
  • NServiceBus 5.1.5+
  • NServiceBus 5.2.9 and newer
  • NServiceBus.Encryption.MessageProperty all versions

All previous versions support decrypting messages that have encrypted fragments but no key ID header.

Key ID naming strategy

A key ID identifies which key is used and it must not expose anything about the key itself.

Good strategies

  • Incremental (1, 2, 3, 4, etc.)
  • Time-based (2015-w01, 2015-m08, 2015-q03)
  • Random (ab4b7a6e71833798),

Bad strategies

  • Full hash of key (MD5, SHA-1, etc.)
  • Key fragment
Random named key IDs DO NOT improve security as the key ID is not encrypted.
Using a time-based key name does not weaken encryption. Messages already contain a timestamp that can be used to search for messages within a certain time range.

Using the same key with and without a key ID

If the KeyIdentifier attribute is set for a key then it will be used to decrypt message properties with a matching key ID but it will also be used to attempt decryption for messages without a key ID.

Key format

The key format can be specified in either Base64 or ASCII format.

With ASCII its not possible to use the full 8 bit range of a byte as it is a 7 bit encoding and even then some characters need to be escaped which is not done resulting in even less characters. Only about 100 values per byte are used. For 16 byte (128 bit) keys, this means that only about 10016 out of all available 25616 combinations are used.

Use Base64 whenever possible. ASCII 7 bit key format should only be used for backwards compatibility.

Defining the encryption key

When encryption is enabled, the encryption and decryption keys must be configured.

Both the sending and the receiving side must use the same key to communicate encrypted information.

Key strength

DescriptionCalculationCombinations
ASCII 16 characters125^163.55e+33 (7 bits minus control characters)
ASCII 24 characters125^242.11e+50 (7 bits minus control characters)
ASCII 32 characters125^321.26e+67 (7 bits minus control characters)
Base64 16 bytes:256^163.40e+38
Base64 24 bytes:256^246.27e+57
Base64 32 bytes:256^321.16e+77

This means that a 16 character ASCII key is almost 100.000 times weaker then a 16 byte Base64 key.

Use Base64 key format if possible and ASCII 32 key format for backward compatibility only. ASCII 16 key format is no longer recommended.

Configuration

Via Code

var defaultKey = "2015-10";

var ascii = Encoding.ASCII;
var keys = new Dictionary<string, byte[]>
{
    {"2015-10", ascii.GetBytes("gdDbqRpqdRbTs3mhdZh9qCaDaxJXl+e6")},
    {"2015-09", ascii.GetBytes("abDbqRpQdRbTs3mhdZh9qCaDaxJXl+e6")},
    {"2015-08", ascii.GetBytes("cdDbqRpQdRbTs3mhdZh9qCaDaxJXl+e6")},
};
endpointConfiguration.RijndaelEncryptionService(defaultKey, keys);

Via App.config

Configuring this feature via app.config, IConfigurationProvider, or IProvideConfiguration is not recommended in Version 6, use the code configuration API instead. The configuration sections will be removed in Version 7.

The encryption key can be defined in the app.config.

<configSections>
  <section
    name="RijndaelEncryptionServiceConfig"
    type="NServiceBus.Config.RijndaelEncryptionServiceConfig, NServiceBus.Core"/>
</configSections>
<RijndaelEncryptionServiceConfig Key="tWIrVnPy3Smd2r/xcSb9r/1wcVY9/3KWbrzIaemx5yw="
                                 KeyIdentifier="2015-10"
                                 KeyFormat="Base64">
  <ExpiredKeys>
    <add Key="YWJEYnFScFFkUmJUczNtaGRaaDlxQ2FEYXhKWGwrZTY="
         KeyIdentifier="2015-09"
         KeyFormat="Base64"/>
    <add Key="cdDbqRpQdRbTs3mhdZh9qCaDaxJXl+e6" />
  </ExpiredKeys>
</RijndaelEncryptionServiceConfig>

Via IProvideConfiguration

public class ProvideConfiguration :
    IProvideConfiguration<RijndaelEncryptionServiceConfig>
{
    public RijndaelEncryptionServiceConfig GetConfiguration()
    {
        return new RijndaelEncryptionServiceConfig
        {
            Key = "gdDbqRpQdRbTs3mhdZh9qCaDaxJXl+e6",
            KeyIdentifier = "2015-10",
            KeyFormat = KeyFormat.Base64,
            ExpiredKeys = new RijndaelExpiredKeyCollection
            {
                new RijndaelExpiredKey
                {
                    Key = "abDbqRpQdRbTs3mhdZh9qCaDaxJXl+e6",
                    KeyIdentifier = "2015-09",
                    KeyFormat = KeyFormat.Base64
                },
                new RijndaelExpiredKey
                {
                    Key = "cdDbqRpQdRbTs3mhdZh9qCaDaxJXl+e6"
                }
            }
        };
    }
}

For more info on IProvideConfiguration see Customizing NServiceBus Configuration

Multi-Key decryption

Several of the examples above used both an encryption key and multiple decryption keys.

This feature allows a phased approach to key rotation. Endpoints can update to a new encryption key and maintain ability to decrypt information sent by endpoints using old keys.

When the original encryption key is replaced by a new encryption key, in-flight messages that were encrypted with the original key will not be decrypted unless the original encryption key is added to a list of decryption keys.

Custom handling of property encryption

To take full control over how properties are encrypted replace the IEncryptionService instance.

This allows explicit handling of the encryption and decryption of each value. So for example to use an algorithm other than Rijndael.

endpointConfiguration.RegisterEncryptionService(
    func: () =>
    {
        return new EncryptionService();
    });
using NServiceBus;
using NServiceBus.Pipeline;

public class EncryptionService :
    IEncryptionService
{
    public EncryptedValue Encrypt(string value, IOutgoingLogicalMessageContext context)
    {
        throw new NotImplementedException();
    }

    public string Decrypt(EncryptedValue encryptedValue, IIncomingLogicalMessageContext context)
    {
        throw new NotImplementedException();
    }
}

Samples


Last modified