CipherUtility (nifi-security-utils 1.12.1 API)

java.lang.Object
- org.apache.nifi.security.util.crypto.CipherUtility

public class CipherUtility
extends Object

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`BUFFER_SIZE`
`private static int`	`DEFAULT_MAX_ALLOWED_KEY_LENGTH`
`private static Pattern`	`KEY_LENGTH_PATTERN`
`private static Map<String,Integer>`	`MAX_PASSWORD_LENGTH_BY_ALGORITHM`

Constructor Summary

Constructors
Constructor and Description

CipherUtility()

Constructors
Constructor and Description
`CipherUtility()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static int`	`calculateCipherTextLength(int ptLength, int saltLength)` Returns the calculated cipher text length given the plaintext length and salt length, if any.
`static String`	`encodeBase64NoPadding(byte[] bytes)`
`static byte[]`	`extractRawSalt(byte[] fullSalt, KeyDerivationFunction kdf)` Returns the raw salt from the provided "full salt" which could be KDF-specific.
`static int`	`findSequence(byte[] haystack, byte[] needle)` Returns the array index of `haystack` if `needle` is found within it.
`private static int`	`getDefaultKeyLengthForCipher(String cipher)`
`static int`	`getIterationCountForAlgorithm(String algorithm)` Returns the KDF iteration count for various PBE algorithms.
`static String`	`getLoggableRepresentationOfSensitiveValue(String sensitivePropertyValue)` Returns a securely-derived, deterministic value from the provided plaintext property value.
`static String`	`getLoggableRepresentationOfSensitiveValue(String sensitivePropertyValue, SecureHasher secureHasher)` Returns a securely-derived, deterministic value from the provided plaintext property value.
`static int`	`getMaximumPasswordLengthForAlgorithmOnLimitedStrengthCrypto(EncryptionMethod encryptionMethod)`
`static int`	`getSaltLengthForAlgorithm(String algorithm)` Returns the salt length for various PBE algorithms.
`static String`	`getTimestampString()` Returns the current timestamp in a default format.
`static List<Integer>`	`getValidKeyLengthsForAlgorithm(String algorithm)` Returns a list of valid key lengths in bits for this algorithm.
`static Cipher`	`initPBECipher(String algorithm, String provider, String password, byte[] salt, int iterationCount, boolean encryptMode)` Initializes a `Cipher` object with the given PBE parameters.
`static boolean`	`isKeyedCipher(String algorithm)`
`static boolean`	`isPBECipher(String algorithm)`
`static boolean`	`isUnlimitedStrengthCryptoSupported()`
`static boolean`	`isValidKeyLength(int keyLength, String cipher)` Returns true if the provided key length is a valid key length for the provided cipher family.
`static boolean`	`isValidKeyLengthForAlgorithm(int keyLength, String algorithm)` Returns true if the provided key length is a valid key length for the provided algorithm.
`private static int`	`parseActualKeyLengthFromAlgorithm(String algorithm)`
`static String`	`parseCipherFromAlgorithm(String algorithm)` Returns the cipher algorithm from the full algorithm name.
`static int`	`parseKeyLengthFromAlgorithm(String algorithm)` Returns the cipher key length from the full algorithm name.
`static boolean`	`passwordLengthIsValidForAlgorithmOnLimitedStrengthCrypto(int passwordLength, EncryptionMethod encryptionMethod)`
`static void`	`processStreams(Cipher cipher, InputStream in, OutputStream out)`
`static byte[]`	`readBytesFromInputStream(InputStream in, String label, int limit, byte[] delimiter)`
`static ByteCountingInputStream`	`wrapStreamForCounting(InputStream inputStream)`
`static ByteCountingOutputStream`	`wrapStreamForCounting(OutputStream outputStream)`
`static void`	`writeBytesToOutputStream(OutputStream out, byte[] value, String label, byte[] delimiter)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - BUFFER_SIZE
```
public static final int BUFFER_SIZE
```
    See Also:
    
    Constant Field Values
  - KEY_LENGTH_PATTERN
```
private static final Pattern KEY_LENGTH_PATTERN
```
  - MAX_PASSWORD_LENGTH_BY_ALGORITHM
```
private static final Map<String,Integer> MAX_PASSWORD_LENGTH_BY_ALGORITHM
```
  - DEFAULT_MAX_ALLOWED_KEY_LENGTH
```
private static final int DEFAULT_MAX_ALLOWED_KEY_LENGTH
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - CipherUtility
```
public CipherUtility()
```
- Method Detail
  - parseCipherFromAlgorithm
```
public static String parseCipherFromAlgorithm(String algorithm)
```
    Returns the cipher algorithm from the full algorithm name. Useful for getting key lengths, etc.
    Ex: PBEWITHMD5AND128BITAES-CBC-OPENSSL -> AES
    
    Parameters:
    
    algorithm - the full algorithm name
    
    Returns:
    
    the generic cipher name or the full algorithm if one cannot be extracted
  - parseKeyLengthFromAlgorithm
```
public static int parseKeyLengthFromAlgorithm(String algorithm)
```
    Returns the cipher key length from the full algorithm name. Useful for getting key lengths, etc.
    Ex: PBEWITHMD5AND128BITAES-CBC-OPENSSL -> 128
    
    Parameters:
    
    algorithm - the full algorithm name
    
    Returns:
    
    the key length or -1 if one cannot be extracted
  - parseActualKeyLengthFromAlgorithm
```
private static int parseActualKeyLengthFromAlgorithm(String algorithm)
```
  - isValidKeyLength
```
public static boolean isValidKeyLength(int keyLength,
                                       String cipher)
```
    Returns true if the provided key length is a valid key length for the provided cipher family. Does not reflect if the Unlimited Strength Cryptography Jurisdiction Policies are installed. Does not reflect if the key length is correct for a specific combination of cipher and PBE-derived key length.
    Ex:
    256 is valid for AES/CBC/PKCS7Padding but not PBEWITHMD5AND128BITAES-CBC-OPENSSL. However, this method will return true for both because it only gets the cipher family, AES.
    64, AES -> false [128, 192, 256], AES -> true
    
    Parameters:
    
    keyLength - the key length in bits
    
    cipher - the cipher family
    
    Returns:
    
    true if this key length is valid
  - isValidKeyLengthForAlgorithm
```
public static boolean isValidKeyLengthForAlgorithm(int keyLength,
                                                   String algorithm)
```
    Returns true if the provided key length is a valid key length for the provided algorithm. Does not reflect if the Unlimited Strength Cryptography Jurisdiction Policies are installed.
    Ex:
    256 is valid for AES/CBC/PKCS7Padding but not PBEWITHMD5AND128BITAES-CBC-OPENSSL.
    64, AES/CBC/PKCS7Padding -> false [128, 192, 256], AES/CBC/PKCS7Padding -> true
    128, PBEWITHMD5AND128BITAES-CBC-OPENSSL -> true [192, 256], PBEWITHMD5AND128BITAES-CBC-OPENSSL -> false
    
    Parameters:
    
    keyLength - the key length in bits
    
    algorithm - the specific algorithm
    
    Returns:
    
    true if this key length is valid
  - getValidKeyLengthsForAlgorithm
```
public static List<Integer> getValidKeyLengthsForAlgorithm(String algorithm)
```
    Returns a list of valid key lengths in bits for this algorithm. If the algorithm cannot be parsed, an empty list is returned.
    
    Parameters:
    
    algorithm - the name of the algorithm
    
    Returns:
    
    a list of valid key lengths
  - getDefaultKeyLengthForCipher
```
private static int getDefaultKeyLengthForCipher(String cipher)
```
  - processStreams
```
public static void processStreams(Cipher cipher,
                                  InputStream in,
                                  OutputStream out)
```
  - readBytesFromInputStream
```
public static byte[] readBytesFromInputStream(InputStream in,
                                              String label,
                                              int limit,
                                              byte[] delimiter)
                                       throws IOException,
                                              ProcessException
```
    Throws:
    
    IOException
    
    ProcessException
  - writeBytesToOutputStream
```
public static void writeBytesToOutputStream(OutputStream out,
                                            byte[] value,
                                            String label,
                                            byte[] delimiter)
                                     throws IOException
```
    Throws:
    
    IOException
  - encodeBase64NoPadding
```
public static String encodeBase64NoPadding(byte[] bytes)
```
  - passwordLengthIsValidForAlgorithmOnLimitedStrengthCrypto
```
public static boolean passwordLengthIsValidForAlgorithmOnLimitedStrengthCrypto(int passwordLength,
                                                                               EncryptionMethod encryptionMethod)
```
  - getMaximumPasswordLengthForAlgorithmOnLimitedStrengthCrypto
```
public static int getMaximumPasswordLengthForAlgorithmOnLimitedStrengthCrypto(EncryptionMethod encryptionMethod)
```
  - isUnlimitedStrengthCryptoSupported
```
public static boolean isUnlimitedStrengthCryptoSupported()
```
  - isPBECipher
```
public static boolean isPBECipher(String algorithm)
```
  - isKeyedCipher
```
public static boolean isKeyedCipher(String algorithm)
```
  - initPBECipher
```
public static Cipher initPBECipher(String algorithm,
                                   String provider,
                                   String password,
                                   byte[] salt,
                                   int iterationCount,
                                   boolean encryptMode)
                            throws IllegalArgumentException
```
    Initializes a Cipher object with the given PBE parameters.
    
    Parameters:
    
    algorithm - the algorithm
    
    provider - the JCA provider
    
    password - the password
    
    salt - the salt
    
    iterationCount - the KDF iteration count
    
    encryptMode - true to encrypt; false to decrypt
    
    Returns:
    
    the initialized Cipher
    
    Throws:
    
    IllegalArgumentException - if any parameter is invalid
  - getIterationCountForAlgorithm
```
public static int getIterationCountForAlgorithm(String algorithm)
```
    Returns the KDF iteration count for various PBE algorithms. These values were determined empirically from configured/chosen legacy values from the earlier version of the project. Code demonstrating this is available at StringEncryptorTest#testPBEncryptionShouldBeExternallyConsistent.
    
    Parameters:
    
    algorithm - the EncryptionMethod.algorithm
    
    Returns:
    
    the iteration count. Default is 0.
  - getSaltLengthForAlgorithm
```
public static int getSaltLengthForAlgorithm(String algorithm)
```
    Returns the salt length for various PBE algorithms. These values were determined empirically from configured/chosen legacy values from the earlier version of the project. Code demonstrating this is available at StringEncryptorTest#testPBEncryptionShouldBeExternallyConsistent.
    
    Parameters:
    
    algorithm - the EncryptionMethod.algorithm
    
    Returns:
    
    the salt length in bytes. Default is 16.
  - getLoggableRepresentationOfSensitiveValue
```
public static String getLoggableRepresentationOfSensitiveValue(String sensitivePropertyValue)
```
    Returns a securely-derived, deterministic value from the provided plaintext property value. This is because sensitive values should not be disclosed through the logs. However, the equality or difference of the sensitive value can be important, so it cannot be ignored completely. The specific derivation process is unimportant as long as it is a salted, cryptographically-secure hash function with an iteration cost sufficient for password storage in other applications.
    
    Parameters:
    
    sensitivePropertyValue - the plaintext property value
    
    Returns:
    
    a deterministic string value which represents this input but is safe to print in a log
  - getLoggableRepresentationOfSensitiveValue
```
public static String getLoggableRepresentationOfSensitiveValue(String sensitivePropertyValue,
                                                               SecureHasher secureHasher)
```
    Returns a securely-derived, deterministic value from the provided plaintext property value. This is because sensitive values should not be disclosed through the logs. However, the equality or difference of the sensitive value can be important, so it cannot be ignored completely. The specific derivation process is determined by the provided SecureHasher implementation.
    
    Parameters:
    
    sensitivePropertyValue - the plaintext property value
    
    secureHasher - an instance of SecureHasher which will be used to mask the value
    
    Returns:
    
    a deterministic string value which represents this input but is safe to print in a log
  - getTimestampString
```
public static String getTimestampString()
```
    Returns the current timestamp in a default format. Used by many encryption operations for logging/debugging.
    
    Returns:
    
    the current timestamp in 'yyyy-MM-dd HH:mm:ss.SSS Z' format
  - wrapStreamForCounting
```
public static ByteCountingInputStream wrapStreamForCounting(InputStream inputStream)
```
  - wrapStreamForCounting
```
public static ByteCountingOutputStream wrapStreamForCounting(OutputStream outputStream)
```
  - calculateCipherTextLength
```
public static int calculateCipherTextLength(int ptLength,
                                            int saltLength)
```
    Returns the calculated cipher text length given the plaintext length and salt length, if any. If the salt length is > 0, the salt delimiter length (8) is included as well.
    
    Parameters:
    
    ptLength - the plaintext length
    
    saltLength - the salt length
    
    Returns:
    
    the complete cipher text, salt (optional), IV, and delimiter(s) length
  - findSequence
```
public static int findSequence(byte[] haystack,
                               byte[] needle)
```
    Returns the array index of haystack if needle is found within it. This is a sequence scanner.
    
    Parameters:
    
    haystack - the search space byte[]
    
    needle - the sequence to find
    
    Returns:
    
    the first index of the sequence or -1 if it does not exist
  - extractRawSalt
```
public static byte[] extractRawSalt(byte[] fullSalt,
                                    KeyDerivationFunction kdf)
```
    Returns the raw salt from the provided "full salt" which could be KDF-specific. Examples: Argon2 -> $argon2id$v=19$m=4096,t=3,p=1$abcdefABCDEF0123456789 Bcrypt -> $2a$10$abcdefABCDEF0123456789 Scrypt -> $s0$e0801$abcdefABCDEF0123456789 If the KDF does not have a custom encoding for the salt, the provided "full salt" is returned intact.
    
    Parameters:
    
    fullSalt - the KDF-formatted salt
    
    kdf - the KDF used
    
    Returns:
    
    the raw salt

Class CipherUtility

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

BUFFER_SIZE

KEY_LENGTH_PATTERN

MAX_PASSWORD_LENGTH_BY_ALGORITHM

DEFAULT_MAX_ALLOWED_KEY_LENGTH

Constructor Detail

CipherUtility

Method Detail

parseCipherFromAlgorithm

parseKeyLengthFromAlgorithm

parseActualKeyLengthFromAlgorithm

isValidKeyLength

isValidKeyLengthForAlgorithm

getValidKeyLengthsForAlgorithm

getDefaultKeyLengthForCipher

processStreams

readBytesFromInputStream

writeBytesToOutputStream

encodeBase64NoPadding

passwordLengthIsValidForAlgorithmOnLimitedStrengthCrypto

getMaximumPasswordLengthForAlgorithmOnLimitedStrengthCrypto

isUnlimitedStrengthCryptoSupported

isPBECipher

isKeyedCipher

initPBECipher

getIterationCountForAlgorithm

getSaltLengthForAlgorithm

getLoggableRepresentationOfSensitiveValue

getLoggableRepresentationOfSensitiveValue

getTimestampString

wrapStreamForCounting

wrapStreamForCounting

calculateCipherTextLength

findSequence

extractRawSalt