com.pkware.smartcrypt.structured

Interface FormatPreservingEncryption

All Superinterfaces:

AutoCloseable, Closeable

public interface FormatPreservingEncryption
extends Closeable

Format preserving data encryption library. This class contains numerous methods for encrypting and decrypting different types of data while preserving various aspects of the original data. For example encryptAccountNumber(String, String) will encrypt only the numeric portion of a string leaving other characters unchanged while encryptAlphanumeric(String, String) will encrypt letters and digits while leaving formatting unchanged.

The data will be encrypted or decrypted using the key supplied by the caller when this object is created. The caller should also provide a tweak value for each encrypt or decrypt operation. The tweak value should be something that will be unique to field or row to strengthen the encryption. For example in a relational database a row identifier, or creation timestamp might be used. It is important that the tweak value not change over time because it if does the original data can not be recovered.

 byte [] key = Encoding.UTF8.GetBytes("12345678901234567890123456789012");
 FormatPreservingEncryption pfe = new FormatPreservingEncryption(key);
 String tweak = "Custom Tweak";
 String clearText = "12345-ABCD";
 String cipherText = fpe.EncryptAccountNumber(clearText, tweak);
 
 

cipherText now contains "09884-ABCD".

Method Summary

Modifier and Type	Method and Description
boolean	allowNoOp()
void	allowNoOp(boolean value)
String	decryptAccountNumber(String value, String tweak) Decrypts the ASCII digits within the string replacing each digit with another digit.
String	decryptAlphanumeric(String value, String tweak) Decrypts the ASCII uppercase, lowercase and digits within the string replacing each character with another of the same type.
String	decryptCreditCardNumber(String value, String tweak) Decrypts the ASCII digits within the string that represents a credit card number.
int	decryptInt(int value, int min, int max, String tweak) Decrypts an int.
int	decryptInt(int value, String tweak) Decrypts an int.
long	decryptLong(long value, long min, long max, String tweak) Decrypts a long.
long	decryptLong(long value, String tweak) Decrypts a long.
String	decryptPrintableAscii(String value, String tweak) Decrypts the printable ASCII characters (values 9, 32 - 126) within the string.
String	decryptSocialSecurityNumber(String value, String tweak) Decrypts the ASCII digits within the string replacing each digit with another digit.
String	decryptString(String value, String tweak, com.pkware.cryptography.formatpreserving.Classifier[] classifiers) Decrypt the specified value using an array of classifiers to determine which characters in the string should be decrypted.
String	decryptUpperLowerDigits(String value, String tweak) Decrypts the ASCII uppercase, lowercase and digits within the string replacing each character with another of the same type.
String	encryptAccountNumber(String value, String tweak) Encrypts the ASCII digits within the string replacing each digit with another digit.
String	encryptAlphanumeric(String value, String tweak) Encrypts the ASCII uppercase, lowercase and digits within the string replacing each character with another of the same type.
String	encryptCreditCardNumber(String value, String tweak) Encrypts the ASCII digits within the string that represents a credit card number.
int	encryptInt(int value, int min, int max, String tweak) Encrypts an int, guaranteeing that the result will be part of the specified range.
int	encryptInt(int value, String tweak) Encrypts an int, guaranteeing that the result will be part of the range [0, Int.MAX_VALUE].
long	encryptLong(long value, long min, long max, String tweak) Encrypts a long, guaranteeing that the result will be part of the specified range.
long	encryptLong(long value, String tweak) Encrypts a long, guaranteeing that the result will be part of the range [0, Long.MAX_VALUE].
String	encryptPrintableAscii(String value, String tweak) Encrypts the printable ASCII characters (values 9, 32 - 126) within the string.
String	encryptSocialSecurityNumber(String value, String tweak) Encrypts the ASCII digits within the string replacing each digit with another digit.
String	encryptString(String value, String tweak, com.pkware.cryptography.formatpreserving.Classifier[] classifiers) Encrypt the specified value using an array of classifiers to determine which characters in the string should be encrypted.
String	encryptUpperLowerDigits(String value, String tweak) Encrypts the ASCII uppercase, lowercase and digits within the string replacing each character with another of the same type.

Methods inherited from interface java.io.Closeable

close

Method Detail

allowNoOp

boolean allowNoOp()

Returns:

true if operations that do not transform the input are allowed, otherwise false. Defaults to false.

allowNoOp

void allowNoOp(boolean value)

Parameters:

value - true to allow operations that do not transform the input, false to cause them to raise an exception. Defaults to false.

encryptString

@Nonnull
String encryptString(String value,
                              String tweak,
                              com.pkware.cryptography.formatpreserving.Classifier[] classifiers)
                       throws com.pkware.cryptography.formatpreserving.NoopException,
                              MetaClientException,
                              com.pkware.archive.ArchiveException

Encrypt the specified value using an array of classifiers to determine which characters in the string should be encrypted.

Parameters:

value - The string containing the data to encrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The encrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the encryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for encryption. See Smartkey.canEncrypt().

decryptString

@Nonnull
String decryptString(String value,
                              String tweak,
                              com.pkware.cryptography.formatpreserving.Classifier[] classifiers)
                       throws com.pkware.cryptography.formatpreserving.NoopException,
                              MetaClientException,
                              com.pkware.archive.ArchiveException

Decrypt the specified value using an array of classifiers to determine which characters in the string should be decrypted.

Parameters:

value - The string containing the data to decrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The decrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the decryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for decryption. See Smartkey.canDecrypt().

encryptPrintableAscii

@Nonnull
String encryptPrintableAscii(String value,
                                      String tweak)
                               throws MetaClientException,
                                      com.pkware.archive.ArchiveException

Encrypts the printable ASCII characters (values 9, 32 - 126) within the string. Each character within this range will be encrypted and replaced by another character in that same range.

Parameters:

value - The string containing the data to encrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The encrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the encryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - If not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for encryption. See Smartkey.canEncrypt().

decryptPrintableAscii

@Nonnull
String decryptPrintableAscii(String value,
                                      String tweak)
                               throws MetaClientException,
                                      com.pkware.archive.ArchiveException

Decrypts the printable ASCII characters (values 9, 32 - 126) within the string. Each character within this range will be decrypted and replaced by another character in that same range.

Parameters:

value - The string containing the data to decrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The decrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the decryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - If not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for decryption. See Smartkey.canDecrypt().

encryptUpperLowerDigits

@Nonnull
String encryptUpperLowerDigits(String value,
                                        String tweak)
                                 throws MetaClientException,
                                        com.pkware.archive.ArchiveException

Encrypts the ASCII uppercase, lowercase and digits within the string replacing each character with another of the same type. For example uppercase letters will be replaced with uppercase letters and digits will be replaced with digits. Characters outside this range will not be encrypted.

Parameters:

value - The string containing the data to encrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The encrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the encryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - If not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for encryption. See Smartkey.canEncrypt().

decryptUpperLowerDigits

@Nonnull
String decryptUpperLowerDigits(String value,
                                        String tweak)
                                 throws MetaClientException,
                                        com.pkware.archive.ArchiveException

Decrypts the ASCII uppercase, lowercase and digits within the string replacing each character with another of the same type. For example uppercase letters will be replaced with uppercase letters and digits will be replaced with digits. Characters outside this range will not be decrypted.

Parameters:

value - The string containing the data to decrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The decrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the decryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - If not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for decryption. See Smartkey.canDecrypt().

encryptAlphanumeric

@Nonnull
String encryptAlphanumeric(String value,
                                    String tweak)
                             throws MetaClientException,
                                    com.pkware.archive.ArchiveException

Encrypts the ASCII uppercase, lowercase and digits within the string replacing each character with another of the same type. For example uppercase letters will be replaced with uppercase letters and digits will be replaced with digits. Characters outside this range will not be encrypted.

Parameters:

value - The string containing the data to encrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The encrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the encryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - If not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for encryption. See Smartkey.canEncrypt().

decryptAlphanumeric

@Nonnull
String decryptAlphanumeric(String value,
                                    String tweak)
                             throws MetaClientException,
                                    com.pkware.archive.ArchiveException

Decrypts the ASCII uppercase, lowercase and digits within the string replacing each character with another of the same type. For example uppercase letters will be replaced with uppercase letters and digits will be replaced with digits. Characters outside this range will not be decrypted.

Parameters:

value - The string containing the data to decrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The decrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the decryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for decryption. See Smartkey.canDecrypt().

encryptCreditCardNumber

@Nonnull
String encryptCreditCardNumber(String value,
                                        String tweak)
                                 throws MetaClientException,
                                        com.pkware.archive.ArchiveException

Encrypts the ASCII digits within the string that represents a credit card number. This function will verify the Luhn checksum prior to encrypting the credit card number and will produce an encrypted value with a valid Luhn checksum. Characters outside this range will not be encrypted.

Parameters:

value - The string containing the data to encrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The encrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the encryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for encryption. See Smartkey.canEncrypt().

decryptCreditCardNumber

@Nonnull
String decryptCreditCardNumber(String value,
                                        String tweak)
                                 throws MetaClientException,
                                        com.pkware.archive.ArchiveException

Decrypts the ASCII digits within the string that represents a credit card number. This function will verify the Luhn checksum prior to decrypting the credit card number. Characters outside this range will not be decrypted.

Parameters:

value - The string containing the data to decrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The decrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the decryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for decryption. See Smartkey.canDecrypt().

encryptSocialSecurityNumber

@Nonnull
String encryptSocialSecurityNumber(String value,
                                            String tweak)
                                     throws MetaClientException,
                                            com.pkware.archive.ArchiveException

Encrypts the ASCII digits within the string replacing each digit with another digit. Characters outside this range will not be encrypted.

Parameters:

value - The string containing the data to encrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The encrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the encryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for encryption. See Smartkey.canEncrypt().

decryptSocialSecurityNumber

@Nonnull
String decryptSocialSecurityNumber(String value,
                                            String tweak)
                                     throws MetaClientException,
                                            com.pkware.archive.ArchiveException

Decrypts the ASCII digits within the string replacing each digit with another digit. Characters outside this range will not be decrypted.

Parameters:

value - The string containing the data to decrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The decrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the decryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for decryption. See Smartkey.canDecrypt().

encryptAccountNumber

@Nonnull
String encryptAccountNumber(String value,
                                     String tweak)
                              throws MetaClientException,
                                     com.pkware.archive.ArchiveException

Encrypts the ASCII digits within the string replacing each digit with another digit. Characters outside this range will not be encrypted.

Parameters:

value - The string containing the data to encrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The encrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the encryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for encryption. See Smartkey.canEncrypt().

decryptAccountNumber

@Nonnull
String decryptAccountNumber(String value,
                                     String tweak)
                              throws MetaClientException,
                                     com.pkware.archive.ArchiveException

Decrypts the ASCII digits within the string replacing each digit with another digit. Characters outside this range will not be decrypted.

Parameters:

value - The string containing the data to decrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The decrypted string

Throws:

com.pkware.cryptography.formatpreserving.NoopException - If allowNoOp() is set to false and the decryption would not result in a transformation of the input

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for decryption. See Smartkey.canDecrypt().

encryptInt

int encryptInt(int value,
               String tweak)
        throws MetaClientException,
               com.pkware.archive.ArchiveException

Encrypts an int, guaranteeing that the result will be part of the range [0, Int.MAX_VALUE].

Parameters:

value - The value to encrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The encrypted int

Throws:

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for encryption. See Smartkey.canEncrypt().

decryptInt

int decryptInt(int value,
               String tweak)
        throws MetaClientException,
               com.pkware.archive.ArchiveException

Decrypts an int.

Parameters:

value - The value to decrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The original plaintext int

Throws:

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for decryption. See Smartkey.canDecrypt().

encryptInt

int encryptInt(int value,
               int min,
               int max,
               String tweak)
        throws MetaClientException,
               com.pkware.archive.ArchiveException

Encrypts an int, guaranteeing that the result will be part of the specified range.

Parameters:

value - The value to encrypt

min - The minimum value of the encrypted result. May not be the same value as the max, and the total range must be less than 2147483647.

max - The maximum value of the encrypted result. May not be the same value as the min, and the total range must be less than 2147483647.

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The encrypted int

Throws:

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for encryption. See Smartkey.canEncrypt().

decryptInt

int decryptInt(int value,
               int min,
               int max,
               String tweak)
        throws MetaClientException,
               com.pkware.archive.ArchiveException

Decrypts an int. The range must match the range provided during encryption.

Parameters:

value - The value to decrypt

min - The minimum value of the range provided during encryption

max - The maximum value of the range provided during encryption

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The original plaintext int

Throws:

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for decryption. See Smartkey.canDecrypt().

encryptLong

long encryptLong(long value,
                 String tweak)
          throws MetaClientException,
                 com.pkware.archive.ArchiveException

Encrypts a long, guaranteeing that the result will be part of the range [0, Long.MAX_VALUE].

Parameters:

value - The value to encrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The encrypted long

Throws:

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for encryption. See Smartkey.canEncrypt().

decryptLong

long decryptLong(long value,
                 String tweak)
          throws MetaClientException,
                 com.pkware.archive.ArchiveException

Decrypts a long.

Parameters:

value - The value to decrypt

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The original plaintext long

Throws:

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for decryption. See Smartkey.canDecrypt().

encryptLong

long encryptLong(long value,
                 long min,
                 long max,
                 String tweak)
          throws MetaClientException,
                 com.pkware.archive.ArchiveException

Encrypts a long, guaranteeing that the result will be part of the specified range.

Parameters:

value - The value to encrypt. Must be part of the range [0, Long.MAX_VALUE].

min - The minimum value of the encrypted result. Must be part of the range [0, Long.MAX_VALUE]. May not be the same value as the max.

max - The maximum value of the encrypted result. Must be part of the range [0, Long.MAX_VALUE]. May not be the same value as the min.

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The encrypted long

Throws:

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for encryption. See Smartkey.canEncrypt().

decryptLong

long decryptLong(long value,
                 long min,
                 long max,
                 String tweak)
          throws MetaClientException,
                 com.pkware.archive.ArchiveException

Decrypts a long. The range must match the range provided during encryption.

Parameters:

value - The value to decrypt

min - The minimum value of the range provided during encryption

max - The maximum value of the range provided during encryption

tweak - Encryption tweak, this value should be changed for each record or field. The same tweak must be used for encryption and decryption.

Returns:

The original plaintext long

Throws:

com.pkware.archive.ArchiveException - if not licensed for this operation. See PKSession.allowSymmetricEncryption().

MetaClientException - if this key is not allowed to be used for decryption. See Smartkey.canDecrypt().