Encrypting Data in Dynamics 365 Business Central

This article gives an overview of data encription and how to use it to add security Dynamics 365 Business Central.

Cryptography overview

The methods that support cryptography provide services that enable developers manage encrypting and decrypting data. Each tenant supports a single encryption key which is used for encrypting and decrypting data stored in the database. Additional methods are provided to assist building robust solutions when working with encryption and for managing the encryption keys.

Flow between plain text and encrypted text

Encryption keys are stored in a secure location, and retrieved at runtime when needed. Additional functionality is provided to export and import keys, which is important when moving solutions from one location to another.

Encryption key management

The process of encrypting and decrypting data requires a key. An encryption key is typically a random string of bits generated specifically to scramble and unscramble data. Encryption keys are created by using algorithms designed to make sure that each key is unique and unpredictable. The keys that are used by Dynamics 365 Business Central are generated by the .NET Framework Data Protection API.

Each tenant supports having a single encryption key. To use the encryption methods, a key must be created. There are two ways of doing this; either by importing a key or by creating a key. The CREATEENCRYPTIONKEY method will create an encryption key in a system that does not have a key present. Alternatively, if a key exists, you can use the IMPORTENCRYPTIONKEY method to introduce a key to a keyless system.

Warning

CREATEENCRYPTIONKEY will fail if the key already exists, you must then call DELETEENCRYPTIONKEY to clear the state. IMPORTENCRYPTIONKEY will throw a warning if a key already exists, regardless of if the key is present on the system or not.

Best practices

These are some best practices we recommend that you follow:

  • Make sure to always backup your key and store it securely. Use the EXPORTENCRYPTIONKEY method and keep the output file in a secure location.

  • Use the Dynamics 365 permission system to restrict access to encryption key logic.

  • Be aware of the difference between the ENCRYPTIONKEYEXISTS and ENCRYPTIONENABLED methods.

ENCRYPTIONKEYEXISTS versus ENCRYPTIONENABLED

The encryption key is stored in a file in a directory that the Dynamics 365 Business Central service has access to. When a key is created or imported, data is recorded in the tenant table registering that encryption has now been enabled. Any subsequent calls to ENCRYPTIONENABLED will return true after the tenant table has been updated with this information. However, if the encryption file is deleted, then ENCRYPTIONENABLED will continue to return true. Use the ENCRYPTIONKEYEXISTS method to perform a file system check to see whether the key is present.

See Also