Forms crypto engine

2 min

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

form-encryption-design.png

Optimizely Forms encryption components are as follows:

ICrypto – Interface representing the mechanism (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 (an 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 – The base class of the forms crypto engine is provided by Optimizely Forms. This class inherits IFormCryptoEngine. The default implementation includes RSA crypto (asymmetric) and AES crypto (symmetric), giving more data security options. 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 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 set up 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. 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 improves data security.

GenerateRandomSymmetricKey() – This abstract function generates a random symmetric key AES crypto uses to encrypt data. It can be used if you want to use only one key for AES crypto encryption activities.

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 class (for example, MyOwnFormCryptoEngine), you can replace the AzureKeyVault-related engine provided by Optimizely Forms with your 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.

customformcryptoengine.png

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

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