Forms crypto engine

📘

Note

Optimizely Forms is only supported by MVC-based websites and HTML5-compliant browsers.

Optimizely Forms encryption components are as follows:

• ICrypto – Interface representing the mechanism (for example, symmetric or asymmetric) used to encrypt plain-text or decrypt cipher-text.

• SymmetricCryptoBase – Base class for symmetric crypto that uses symmetric algorithms to encrypt a plain-text or decrypt a cipher-text. This class follows a standard, so (in most cases) third-parties need only to override how the key is initialized for the symmetric algorithm by using the function SetKey(byte[] keyBytes).

• AesCrypto – Specific symmetric crypto that uses AesManaged as the symmetric algorithm for data encryption and decryption. This is the default SymmetricCrypto used by Optimizely Forms.

• RsaCrypto – Asymmetric crypto that uses (asymmetric algorithm) to encrypt a plain-text or decrypt a cipher-text. This class follows a standard, so (in most cases) third-parties need only to override how the key is initialized by using the function SetKey(object input).

• IFormCryptoEngine – Interface that supports encrypting and decrypting of form submission data.

• FormCryptoEngineBase – Base class of the forms crypto engine provided by Optimizely Forms. This class inherits IFormCryptoEngine. The default implementation includes both RSA crypto (asymmetric) and AES crypto (symmetric), giving more options to secure the data. This class is the most important; and in most cases, overriding exposed APIs of this class is enough to customize the data encryption and decryption following to be in-line with their contexts. To do that, you initially need to create a new class (for example, MyOwnFormCryptoEngine) inheriting FormCryptoEngineBase and then, override the functions below.

  • Initialize – To initialize the engine's required parameters. The crypto keys (mentioned above) can be set up here by calling their setup functions.
  • EncryptSubmission(Submission submission) – To encrypt submission data. The default implementation of this function first uses AES crypto to encrypt data, and then uses RSA crypto to encrypt the AES crypto key. All encrypted data including submission data and the key of AES crypto is returned as the final result. The engine sets up a random key for AES crypto by using the function GenerateRandomSymmetricKey below, which significantly improve data security.
  • GenerateRandomSymmetricKey() – This abstract function is used to generate a random symmetric key used by AES crypto to encrypt data. It can be used if you want to use only one key for all encryption activities of AES crypto.
  • DecryptSubmission(Submission submission) – To decrypt encrypted submission data. By default, Optimizely Forms does not implement this function.

• CryptoEngineFactory – Factory to initialize the forms crypto engine based on a setting in the Forms.config file. After customizing FormCryptoEngineBase with your own class (for example, MyOwnFormCryptoEngine), you can replace the AzureKeyVault-related engine provided by Optimizely Forms with your own engine. See the example below:

type="EPiServer.Forms.Core.Data.Internal.DdsEncryptedPermanentStorage, EPiServer.Forms.Core"
cryptoEngineType="full class name of MyOwnFormCryptoEngine, Your namespace"

Customize the AzureKeyVaultCryptoEngine

EPiServer.Forms exposes the APIs necessary to customize the encryption feature with AzureKeyVault. The default implementation of the forms crypto engine is provided in a separate package, EPiServer.Forms.Crypto.AzureKeyVault.

AzureKeyVaultCryptoEngine uses a symmetric algorithm for data encryption and decryption. The encryption key is stored in AzureKeyVault, a service which enables users to store and use cryptographic keys within the Microsoft Azure environment. For details about AzureKeyVault, see Encrypting form submission data.

DecryptedCSVDataExporter – Exporter which supports decrypted form data for users with correct access rights.