Encrypting data in Business Central
This article gives an overview of data encryption and how to use it to add security Business Central.
Note
This applies only to on-premises versions of Business Central. For online versions, encryption is always enabled and you cannot turn it off.
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. Other methods are provided to assist building robust solutions when working with encryption and managing the encryption keys.
Encryption keys are stored in a secure location, and retrieved at runtime when needed. Extra 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 System.CreateEncryptionKey method creates an encryption key in a system that doesn't have a key present. Alternatively, if a key exists, you can use the System.ImportEncryptionKey method to introduce a key to a keyless system.
Warning
CreateEncryptionKey fails if the key already exists, you must then call System.DeleteEncryptionKey method to clear the state. System.ImportEncryptionKey method throws 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 back up your key and store it securely. Use the System.ExportEncryptionKey method and keep the output file in a secure location.
- Use the Business Central permission system to restrict access to encryption key logic.
- Be aware of the difference between the System.EncryptionKeyExists method and System.EncryptionKeyEnabled method.
EncryptionKeyExists versus EncryptionKeyEnabled
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 EncryptionKeyEnabled return true after the tenant table is updated with this information. However, if the encryption file is deleted, then EncryptionKeyEnabled continues to return true. Use the EncryptionKeyExists method to perform a file system check to see whether the key is present.