Using the Apex Crypto Class

This article explains useful information that will help you understand and successfully use the Apex Crypto class.

What is the Apex Crypto Class?

As per the Crypto Class documentation in the Apex Developer's Guide, the Apex Crypto class provides a number of cryptographic functions for creating digests, message authentication codes, and signatures, as well as functions for encrypting and decrypting information. These functions allow you to protect the confidentiality of data as well as allow external systems to verify the integrity of messages and authenticity of the sender.

Scenarios for Using the Apex Crypto Class

The cryptographic capabilities of the Crypto class is normally used in the following scenarios:

  • Confidentiality - the protection of data either at rest or in transit from unauthorized parties
  • Integrity - the data is complete and correct
  • Authenticity - proof of the authenticity of the sender or receiver of the message

Encryption and Decryption

Consists of functions to encrypt and decrypt information using AES128, AES192 and AES256 algorithms. Currently, only symmetric private key encryption using the AES algorithm is supported. Whilst encryption provides for data protection, it does not authenticate the sender (non-repudiation) and nor does it guarantee message integrity.

Creating Hash Digests

In this scenario, the input message of any length is converted using a one-way cryptographic hash function into a compact unique "digest" of fixed length. As the digest is unique, it can then be used by the receiver to ensure integrity of the message by comparing the transmitted digest with a digest calculated from the received message using the same algorithm. Its compact nature also allows for performance and efficient transmission.

The Crypto.generateDigest() function generates a one-way hash digest for this purpose and supports algorithms such as MD5, SHA1, SHA256 and SHA512. As hash digests are one way, compact representations of the original data, the resulting digest cannot be "decrypted" back to its original form.

Hash Based Message Authentication Codes (MAC)

Hash-based MAC functions generate a compact one-way digest using a cryptographic hash function and then uses a private key to encrypt the resulting digest. The combination of the an encrypted hash digest ensures non-repudiation of the message and its sender.

Compared to a hash digests, HMAC functions use a private key that the sender uses to encrypt the MAC and receiver to decrypt the MAC. The unencrypted digest can then verify the message integrity. As the receiver has to decrypt the MAC using the shared private key, you can verify the authenticity of the message sender.

The Crypto.generateMac() method supports the HMACMD5, HMACSHA1, HMACSHA256 and HMAC512 algorithms.

Creating a Digital Signature

Digital signatures guarantee both integrity and authenticity of the message using an asymmetric key. The sender generates a message digest (e.g. using SHA1) and encrypts it using a private key. The receiver then decrypts using a public key and compares the message digest with a digest generated from the received message.

The Crypto.sign() function generates a digital signature using the SHA1 algorithm to create the digest, which is then subsequently encrypted using the RSA algorithm with a PKCS8 formatted private key.

Supported Standards

The following are the various supported standards for each of the Crypto class methods.

Method Supported Standards
Encrypt()
EncryptWithManagedIv()
Decrypt()
DecryptWithManagedIv()
AES128, AES192, AES256 for encryption.
PCKS#5 padding and Cipher Block Chaining.
generateDigest()
generateMac()
MD5, SHA1, SHA256, SHA512
sign() SHA1 with RSA

Discussion and Sample Code

Encryption

The Crypto class provides the following functions to encrypt and decrypt using the AES algorithm:

  • encrypt()
  • decrypt()
  • encryptWithManagedIV()
  • decryptWithManagedIV()

The following considerations should be noted:

  • The AES128, AES192 and AES256 algorithms are supported
  • A private key can either be generated externally or via the Crypto.generateAESKey(Integer size) method. The length of the private key must match to the specified algorithm.
  • The private key should not be hardcoded in the Apex code. Instead, it should be placed in a protected custom setting.
  • The standard AES algorithm is used with a Cipher Mode of Cipher Block Chaining (CBC) and PKCS#5 padding. Ensure that any applications that you interact with use the same parameters.(Note that PKCS#5 and PKCS#7 are compatible.)
  • The algorithm requires an initialization vector of 16 bytes (128 bits). Use the encryptWithManagedIV() function to have Salesforce generate the IV for you in the first 16 bytes of the cipher text.Third party systems that receive the cipher should extract the IV from the first 16 bits. If third party systems send the IV in the first 16 bytes of the cipher, then use the decryptWithManagedIV() method to decrypt.
  • If you intend to generate your own initialization vector, then use the encrypt() and/or decrypt() methods, in which the IV is sent as a separate argument. Note that the cipher text passed to the decrypt() method should not contain the IV in the first 16 bytes and neither does the encrypt() function place the IV in the first 16 bytes of the generated cipher.


The following is an example where Salesforce generates the initialization vector and encrypts a String and then subsequently decrypts the cipher:

// Generate an AES key for the purpose of this sample. 
// Normally this key should be stored in a protected custom setting 
// or an encrypted field on a custom object
Blob cryptoKey = Crypto.generateAesKey(256);

// Generate the data to be encrypted.
Blob data = Blob.valueOf('Test data to encrypted');
// Encrypt the data and have Salesforce.com generate the initialization vector
Blob encryptedData = Crypto.encryptWithManagedIV('AES256', cryptoKey, data);
// Decrypt the data - the first 16 bytes contain the initialization vector
Blob decryptedData = Crypto.decryptWithManagedIV('AES256', cryptoKey, encryptedData);

// Decode the decrypted data for subsequent use
String decryptedDataString = decryptedData.toString();

Digital Signatures

The Apex Crypto class provides support for Digital Signatures with the sign() method. The following considerations apply:

  • The two algorithms are RSA and RSA-SHA1, which are functionally equivalent.
  • A PKCS8 formatted private key in base64 decoded form is required. This private key should not be hardcoded in the Apex script but should be stored in a protected custom setting or a encrypted fields in a custom table.
  • It is equivalent to the Java Signature.sign() class method using "SHA1withRSA".
  • In C#, it is the equivalent of (1) signing the clear text using SHA1Managed.ComputeHash() and (2) Signing using RSACryptoServiceProvider.ComputeHash() against the resulting hash.
  • Functionally, it will compute a SHA1 digest from clear text and encrypt the digest using RSA with the provided private key.

Utilities such as keytool or openSSL can be used to generate a certificate from which a private key can be extracted. The important thing to note is that the resulting private key must be in PCKS#8 format. For example:

// Generate your own certificate - subject information is redacted
openssl req -x509 -nodes -subj "/C=XX/ST=XXX/L=XXX/CN=www.xxx.com" -days 365 -newkey rsa:1024 -keyout key.pem -out cert.pem
// Output the private key onto the terminal in PKCS#8 format
openssl pkcs8 -topk8 -nocrypt -in key.pem -outform PEM

If you have a presupplied certificate in PFX format:

// Convert PFX into PEM
openssl pkcs12 -nodes -nocerts -in key.pfx -out key.pem 
// Output the private key onto the terminal in PKCS#8 format
openssl pkcs8 -topk8 -nocrypt -in key.pem -outform PEM

Don't forget to remove the newline characters when storing the private key!

The following is sample code to sign a given input string:

String algorithmName = 'RSA';
String key = 'pkcs8 format private key';
// Decode the key from base64 to binary
Blob privateKey = EncodingUtil.base64Decode(key);
Blob input = Blob.valueOf('12345qwerty');
Crypto.sign(algorithmName, input, privateKey);

Summary

This article summarizes the cryptographic capabilities of the Force.com platform, including functions to encrypt and decrypt data using the AES algorithm as well as a number of functions to generate digests, message authentication codes and digital signatures.

These functions can then be used to protect the confidentiality, integrity and authenticity of data.

References