Force.com Apex Code Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Crypto Class

Provides methods for creating digests, message authentication codes, and signatures, as well as encrypting and decrypting information.

Namespace

System

Usage

The methods in the Crypto class can be used for securing content in Force.com, or for integrating with external services such as Google or Amazon WebServices (AWS).

Encrypt and Decrypt Exceptions

The following exceptions can be thrown for these methods:
  • decrypt
  • encrypt
  • decryptWithManagedIV
  • encryptWithManagedIV
Exception Message Description
InvalidParameterValue Unable to parse initialization vector from encrypted data. Thrown if you're using managed initialization vectors, and the cipher text is less than 16 bytes.
InvalidParameterValue Invalid algorithm algoName. Must be AES128, AES192, or AES256. Thrown if the algorithm name isn't one of the valid values.
InvalidParameterValue Invalid private key. Must be size bytes. Thrown if size of the private key doesn't match the specified algorithm.
InvalidParameterValue Invalid initialization vector. Must be 16 bytes. Thrown if the initialization vector isn't 16 bytes.
InvalidParameterValue Invalid data. Input data is size bytes, which exceeds the limit of 1048576 bytes. Thrown if the data is greater than 1 MB. For decryption, 1048608 bytes are allowed for the initialization vector header, plus any additional padding the encryption added to align to block size.
NullPointerException Argument cannot be null. Thrown if one of the required method arguments is null.
SecurityException Given final block not properly padded. Thrown if the data isn't properly block-aligned or similar issues occur during encryption or decryption.
SecurityException Message Varies Thrown if something goes wrong during either encryption or decryption.

Crypto Methods

The following are methods for Crypto. All methods are static.

decrypt(String, Blob, Blob, Blob)

Decrypts the Blob cipherText using the specified algorithm, private key, and initialization vector. Use this method to decrypt blobs encrypted using a third party application or the encrypt method.

Signature

public static Blob decrypt(String algorithmName, Blob privateKey, Blob initializationVector, Blob cipherText)

Parameters

algorithmName
Type: String
privateKey
Type: Blob
initializationVector
Type: Blob
cipherText
Type: Blob

Return Value

Type: Blob

Usage

Valid values for algorithmName are:
  • AES128
  • AES192
  • AES256
These are all industry standard Advanced Encryption Standard (AES) algorithms with different size keys. They use cipher block chaining (CBC) and PKCS5 padding.

The length of privateKey must match the specified algorithm: 128 bits, 192 bits, or 256 bits, which is 16, 24, or 32 bytes, respectively. You can use a third-party application or the generateAesKey method to generate this key for you.

The initialization vector must be 128 bits (16 bytes.)

decryptWithManagedIV(String, Blob, Blob)

Decrypts the Blob IVAndCipherText using the specified algorithm and private key. Use this method to decrypt blobs encrypted using a third party application or the encryptWithManagedIV method.

Signature

public static Blob decryptWithManagedIV(String algorithmName, Blob privateKey, Blob IVAndCipherText)

Parameters

algorithmName
Type: String
privateKey
Type: Blob
IVAndCipherText
Type: Blob
The first 128 bits (16 bytes) of IVAndCipherText must contain the initialization vector.

Return Value

Type: Blob

Usage

Valid values for algorithmName are:
  • AES128
  • AES192
  • AES256
These are all industry standard Advanced Encryption Standard (AES) algorithms with different size keys. They use cipher block chaining (CBC) and PKCS5 padding.

The length of privateKey must match the specified algorithm: 128 bits, 192 bits, or 256 bits, which is 16, 24, or 32 bytes, respectively. You can use a third-party application or the generateAesKey method to generate this key for you.

encrypt(String, Blob, Blob, Blob)

Encrypts the Blob clearText using the specified algorithm, private key and initialization vector. Use this method when you want to specify your own initialization vector.

Signature

public static Blob encrypt(String algorithmName, Blob privateKey, Blob initializationVector, Blob clearText)

Parameters

algorithmName
Type: String
privateKey
Type: Blob
initializationVector
Type: Blob
clearText
Type: Blob

Return Value

Type: Blob

Usage

The initialization vector must be 128 bits (16 bytes.) Use either a third-party application or the decrypt method to decrypt blobs encrypted using this method. Use the encryptWithManagedIV method if you want Salesforce to generate the initialization vector for you. It is stored as the first 128 bits (16 bytes) of the encrypted Blob.

Valid values for algorithmName are:
  • AES128
  • AES192
  • AES256
These are all industry standard Advanced Encryption Standard (AES) algorithms with different size keys. They use cipher block chaining (CBC) and PKCS5 padding.

The length of privateKey must match the specified algorithm: 128 bits, 192 bits, or 256 bits, which is 16, 24, or 32 bytes, respectively. You can use a third-party application or the generateAesKey method to generate this key for you.

encryptWithManagedIV(String, Blob, Blob)

Encrypts the Blob clearText using the specified algorithm and private key. Use this method when you want Salesforce to generate the initialization vector for you.

Signature

public static Blob encryptWithManagedIV(String algorithmName, Blob privateKey, Blob clearText)

Parameters

algorithmName
Type: String
privateKey
Type: Blob
clearText
Type: Blob

Return Value

Type: Blob

Usage

The initialization vector is stored as the first 128 bits (16 bytes) of the encrypted Blob. Use either third-party applications or the decryptWithManagedIV method to decrypt blobs encrypted with this method. Use the encrypt method if you want to generate your own initialization vector.

Valid values for algorithmName are:
  • AES128
  • AES192
  • AES256
These are all industry standard Advanced Encryption Standard (AES) algorithms with different size keys. They use cipher block chaining (CBC) and PKCS5 padding.

The length of privateKey must match the specified algorithm: 128 bits, 192 bits, or 256 bits, which is 16, 24, or 32 bytes, respectively. You can use a third-party application or the generateAesKey method to generate this key for you.

generateAesKey(Integer)

Generates an Advanced Encryption Standard (AES) key.

Signature

public static Blob generateAesKey(Integer size)

Parameters

size
Type: Integer
The key's size in bits. Valid values are:
  • 128
  • 192
  • 256

Return Value

Type: Blob

generateDigest(String, Blob)

Computes a secure, one-way hash digest based on the supplied input string and algorithm name.

Signature

public static Blob generateDigest(String algorithmName, Blob input)

Parameters

algorithmName
Type: String
Valid values for algorithmName are:
  • MD5
  • SHA1
  • SHA-256
  • SHA-512
input
Type: Blob

Return Value

Type: Blob

generateMac(String, Blob, Blob)

Computes a message authentication code (MAC) for the input string, using the private key and the specified algorithm.

Signature

public static Blob generateMac(String algorithmName, Blob input, Blob privateKey)

Parameters

algorithmName
Type: String
The valid values for algorithmName are:
  • hmacMD5
  • hmacSHA1
  • hmacSHA256
  • hmacSHA512
input
Type: Blob
privateKey
Type: Blob
The value of privateKey does not need to be in decoded form. The value cannot exceed 4 KB.

Return Value

Type: Blob

getRandomInteger()

Returns a random Integer.

Signature

public static Integer getRandomInteger()

Return Value

Type: Integer

getRandomLong()

Returns a random Long.

Signature

public static Long getRandomLong()

Return Value

Type: Long

sign(String, Blob, Blob)

Computes a unique digital signature for the input string, using the supplied private key and the specified algorithm.

Signature

public static Blob sign(String algorithmName, Blob input, Blob privateKey)

Parameters

algorithmName
Type: String
The valid values for algorithmName are RSA-SHA1 or RSA. Both values represent the same algorithm.
input
Type: Blob
privateKey
Type: Blob
The value of privateKey must be decoded using the EncodingUtilbase64Decode method, and should be in RSA's PKCS #8 (1.2) Private-Key Information Syntax Standard form. The value cannot exceed 4 KB.

Return Value

Type: Blob

Example

The following snippet is an example declaration and initialization.

1String algorithmName = 'RSA';
2String key = '';
3Type: Blob privateKey = EncodingUtil.base64Decode(key);
4Type: Blob input = Type: Blob.valueOf('12345qwerty');
5Crypto.sign(algorithmName, input, privateKey);