StringEncryptor (nifi-framework-components 1.13.0 API)

java.lang.Object
- org.apache.nifi.encrypt.StringEncryptor

```
public class StringEncryptor
extends Object
```
An application specific string encryptor that collects configuration from the application properties, system properties, and/or system environment.

Instance of this class are thread-safe

The encryption provider and algorithm is configured using the application properties:
- nifi.sensitive.props.provider
- nifi.sensitive.props.algorithm
The encryptor's password may be set by configuring the below property:
- nifi.sensitive.props.key

Field Summary

Fields
Modifier and Type	Field and Description
`private String`	`algorithm`
`private static String`	`ARGON2_AES_GCM_128_ALGORITHM`
`private static String`	`ARGON2_AES_GCM_256_ALGORITHM`
`private static String`	`B64_ENCODING`
`private org.apache.nifi.security.util.crypto.CipherProvider`	`cipherProvider`
`static int`	`CUSTOM_ALGORITHM_SALT_LENGTH`
`private static List<String>`	`CUSTOM_ALGORITHMS`
`private static String`	`DEFAULT_SENSITIVE_PROPS_KEY`
`private String`	`encoding`
`private static String`	`HEX_ENCODING`
`private static int`	`IV_LENGTH`
`private SecretKeySpec`	`key`
`private static org.slf4j.Logger`	`logger`
`static String`	`NF_SENSITIVE_PROPS_ALGORITHM`
`static String`	`NF_SENSITIVE_PROPS_KEY`
`static String`	`NF_SENSITIVE_PROPS_PROVIDER`
`private PBEKeySpec`	`password`
`private String`	`provider`
`private static List<String>`	`SUPPORTED_ALGORITHMS`
`private static List<String>`	`SUPPORTED_PROVIDERS`

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`StringEncryptor()` A default constructor for mocking during testing.
	`StringEncryptor(String algorithm, String provider, byte[] key)` This constructor creates an encryptor using Keyed Encryption.
	`StringEncryptor(String algorithm, String provider, String key)` This constructor creates an encryptor using Password-Based Encryption (PBE).

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`protected static boolean`	`algorithmIsValid(String algorithm)`
`private static String`	`centerString(String msg)`
`static StringEncryptor`	`createEncryptor(NiFiProperties niFiProperties)` Deprecated. as of NiFi 1.4.0 because the entire `NiFiProperties` object is not necessary to generate the encryptor.
`static StringEncryptor`	`createEncryptor(String algorithm, String provider, String password)` Creates an instance of the NiFi sensitive property encryptor.
`private boolean`	`customSecretIsValid(PBEKeySpec password, SecretKeySpec key, String algorithm)`
`private byte[]`	`decode(String encoded)`
`String`	`decrypt(String cipherText)` Decrypts the given cipher text.
`private byte[]`	`decryptKeyed(byte[] cipherBytes)`
`private byte[]`	`decryptPBE(byte[] cipherBytes)`
`private static int`	`determineSaltLength(String algorithm)`
`private String`	`encode(byte[] rawBytes)`
`String`	`encrypt(String clearText)` Encrypts the given clear text.
`private byte[]`	`encryptKeyed(String plaintext)`
`private byte[]`	`encryptPBE(String plaintext)`
`boolean`	`equals(Object o)` Returns `true` if the two `StringEncryptor` objects are logically equivalent.
`private String`	`extractKeyTypeFromAlgorithm(String algorithm)` Extracts the cipher "family" (i.e.
`private EncryptionMethod`	`getEncryptionMethodForAlgorithm(String algorithm)`
`int`	`hashCode()` Returns the hashcode of this object.
`protected void`	`initialize()`
`static boolean`	`isCustomAlgorithm(String algorithm)` Returns `true` if the provided algorithm is considered a "custom" algorithm (a combination of KDF and cipher not present in `EncryptionMethod` and implemented specially for string encryption).
`boolean`	`isInitialized()`
`private static boolean`	`isPBEKeySpecEqual(PBEKeySpec a, PBEKeySpec b)` Returns true if the two `PBEKeySpec` objects are logically equivalent (same params and password).
`private boolean`	`keyIsValid(SecretKeySpec key, String algorithm)`
`private boolean`	`paramsAreValid()`
`private boolean`	`passwordIsValid(PBEKeySpec password)`
`private static void`	`printBlankKeyWarning()`
`protected static boolean`	`providerIsValid(String provider)`
`private boolean`	`secretsAreEqual(PBEKeySpec otherPassword, SecretKeySpec otherKey)` Returns true if the provided `password` and `key` match those contained in this `StringEncryptor`.
`void`	`setEncoding(String base)`
`String`	`toString()` Returns a String containing the `algorithm`, `provider`, `encoding`, and `cipherProvider` class name.

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

- Field Detail
  - logger
```
private static final org.slf4j.Logger logger
```
  - SUPPORTED_ALGORITHMS
```
private static final List<String> SUPPORTED_ALGORITHMS
```
  - SUPPORTED_PROVIDERS
```
private static final List<String> SUPPORTED_PROVIDERS
```
  - ARGON2_AES_GCM_256_ALGORITHM
```
private static final String ARGON2_AES_GCM_256_ALGORITHM
```
    See Also:
    
    Constant Field Values
  - ARGON2_AES_GCM_128_ALGORITHM
```
private static final String ARGON2_AES_GCM_128_ALGORITHM
```
    See Also:
    
    Constant Field Values
  - CUSTOM_ALGORITHMS
```
private static final List<String> CUSTOM_ALGORITHMS
```
  - CUSTOM_ALGORITHM_SALT_LENGTH
```
public static final int CUSTOM_ALGORITHM_SALT_LENGTH
```
    See Also:
    
    Constant Field Values
  - IV_LENGTH
```
private static final int IV_LENGTH
```
    See Also:
    
    Constant Field Values
  - algorithm
```
private final String algorithm
```
  - provider
```
private final String provider
```
  - password
```
private final PBEKeySpec password
```
  - key
```
private SecretKeySpec key
```
  - HEX_ENCODING
```
private static final String HEX_ENCODING
```
    See Also:
    
    Constant Field Values
  - B64_ENCODING
```
private static final String B64_ENCODING
```
    See Also:
    
    Constant Field Values
  - encoding
```
private String encoding
```
  - cipherProvider
```
private org.apache.nifi.security.util.crypto.CipherProvider cipherProvider
```
  - NF_SENSITIVE_PROPS_KEY
```
public static final String NF_SENSITIVE_PROPS_KEY
```
    See Also:
    
    Constant Field Values
  - NF_SENSITIVE_PROPS_ALGORITHM
```
public static final String NF_SENSITIVE_PROPS_ALGORITHM
```
    See Also:
    
    Constant Field Values
  - NF_SENSITIVE_PROPS_PROVIDER
```
public static final String NF_SENSITIVE_PROPS_PROVIDER
```
    See Also:
    
    Constant Field Values
  - DEFAULT_SENSITIVE_PROPS_KEY
```
private static final String DEFAULT_SENSITIVE_PROPS_KEY
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - StringEncryptor
```
public StringEncryptor(String algorithm,
                       String provider,
                       String key)
```
    This constructor creates an encryptor using Password-Based Encryption (PBE). The key value is the direct value provided in nifi.sensitive.props.key in nifi.properties, which is a PASSWORD rather than a KEY, but is named such for backward/legacy logical compatibility throughout the rest of the codebase.
    For actual raw key provision, see StringEncryptor(String, String, byte[]).
    
    Parameters:
    
    algorithm - the PBE cipher algorithm (EncryptionMethod.getAlgorithm())
    
    provider - the JCA Security provider (EncryptionMethod.getProvider())
    
    key - the UTF-8 characters from nifi.properties -- nifi.sensitive.props.key
  - StringEncryptor
```
public StringEncryptor(String algorithm,
                       String provider,
                       byte[] key)
```
    This constructor creates an encryptor using Keyed Encryption. The key value is the raw byte value of a symmetric encryption key (usually expressed for human-readability/transmission in hexadecimal or Base64 encoded format).
    
    Parameters:
    
    algorithm - the PBE cipher algorithm (EncryptionMethod.getAlgorithm())
    
    provider - the JCA Security provider (EncryptionMethod.getProvider())
    
    key - a raw encryption key in bytes
  - StringEncryptor
```
protected StringEncryptor()
```
    A default constructor for mocking during testing.
- Method Detail
  - extractKeyTypeFromAlgorithm
```
private String extractKeyTypeFromAlgorithm(String algorithm)
                                    throws EncryptionException
```
    Extracts the cipher "family" (i.e. "AES", "DES", "RC4") from the full algorithm name.
    
    Parameters:
    
    algorithm - the algorithm (EncryptionMethod.getAlgorithm())
    
    Returns:
    
    the cipher family
    
    Throws:
    
    EncryptionException - if the algorithm is null/empty or not supported
  - createEncryptor
```
@Deprecated
public static StringEncryptor createEncryptor(NiFiProperties niFiProperties)
                                                   throws EncryptionException
```
    Deprecated. as of NiFi 1.4.0 because the entire NiFiProperties object is not necessary to generate the encryptor.
    
    Creates an instance of the NiFi sensitive property encryptor.
    
    Parameters:
    
    niFiProperties - properties
    
    Returns:
    
    encryptor
    
    Throws:
    
    EncryptionException - if any issues arise initializing or validating the encryptor
    
    See Also:
    
    createEncryptor(String, String, String)
  - createEncryptor
```
public static StringEncryptor createEncryptor(String algorithm,
                                              String provider,
                                              String password)
```
    Creates an instance of the NiFi sensitive property encryptor. If the password is blank, the default will be used and an error will be printed to the log.
    
    Parameters:
    
    algorithm - the encryption (and key derivation) algorithm (EncryptionMethod.getAlgorithm())
    
    provider - the JCA Security provider (EncryptionMethod.getProvider())
    
    password - the UTF-8 characters from nifi.properties -- nifi.sensitive.props.key
    
    Returns:
    
    the initialized encryptor
  - printBlankKeyWarning
```
private static void printBlankKeyWarning()
```
  - centerString
```
private static String centerString(String msg)
```
  - initialize
```
protected void initialize()
```
  - isCustomAlgorithm
```
public static boolean isCustomAlgorithm(String algorithm)
```
    Returns true if the provided algorithm is considered a "custom" algorithm (a combination of KDF and cipher not present in EncryptionMethod and implemented specially for string encryption). Case-insensitive.
    
    Parameters:
    
    algorithm - the algorithm to evaluate
    
    Returns:
    
    true if present in CUSTOM_ALGORITHMS
  - paramsAreValid
```
private boolean paramsAreValid()
```
  - customSecretIsValid
```
private boolean customSecretIsValid(PBEKeySpec password,
                                    SecretKeySpec key,
                                    String algorithm)
```
  - keyIsValid
```
private boolean keyIsValid(SecretKeySpec key,
                           String algorithm)
```
  - passwordIsValid
```
private boolean passwordIsValid(PBEKeySpec password)
```
  - setEncoding
```
public void setEncoding(String base)
```
  - encrypt
```
public String encrypt(String clearText)
               throws EncryptionException
```
    Encrypts the given clear text.
    
    Parameters:
    
    clearText - the message to encrypt
    
    Returns:
    
    the cipher text
    
    Throws:
    
    EncryptionException - if the encrypt fails
  - encryptPBE
```
private byte[] encryptPBE(String plaintext)
```
  - getEncryptionMethodForAlgorithm
```
private EncryptionMethod getEncryptionMethodForAlgorithm(String algorithm)
```
  - encryptKeyed
```
private byte[] encryptKeyed(String plaintext)
```
  - encode
```
private String encode(byte[] rawBytes)
```
  - decrypt
```
public String decrypt(String cipherText)
               throws EncryptionException
```
    Decrypts the given cipher text.
    
    Parameters:
    
    cipherText - the message to decrypt
    
    Returns:
    
    the clear text
    
    Throws:
    
    EncryptionException - if the decrypt fails
  - decryptPBE
```
private byte[] decryptPBE(byte[] cipherBytes)
```
  - determineSaltLength
```
private static int determineSaltLength(String algorithm)
```
  - decryptKeyed
```
private byte[] decryptKeyed(byte[] cipherBytes)
```
  - decode
```
private byte[] decode(String encoded)
               throws org.apache.commons.codec.DecoderException
```
    Throws:
    
    org.apache.commons.codec.DecoderException
  - isInitialized
```
public boolean isInitialized()
```
  - algorithmIsValid
```
protected static boolean algorithmIsValid(String algorithm)
```
  - providerIsValid
```
protected static boolean providerIsValid(String provider)
```
  - equals
```
public boolean equals(Object o)
```
    Returns true if the two StringEncryptor objects are logically equivalent. This requires the same algorithm, provider, encoding, and key/password.
    A ciphertext generated by one object can be decrypted by a separate object if they are equal as determined by this method.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    o - the other StringEncryptor
    
    Returns:
    
    true if these instances are equal
  - secretsAreEqual
```
private boolean secretsAreEqual(PBEKeySpec otherPassword,
                                SecretKeySpec otherKey)
```
    Returns true if the provided password and key match those contained in this StringEncryptor. This method does not compare password == key.
    Internally, uses isPBEKeySpecEqual(PBEKeySpec, PBEKeySpec) and SecretKeySpec.equals(Object).
    
    Parameters:
    
    otherPassword - the password PBEKeySpec
    
    otherKey - the key SecretKeySpec
    
    Returns:
    
    true if the passwords match and the keys match
  - isPBEKeySpecEqual
```
private static boolean isPBEKeySpecEqual(PBEKeySpec a,
                                         PBEKeySpec b)
```
    Returns true if the two PBEKeySpec objects are logically equivalent (same params and password).
    
    Parameters:
    
    a - a PBEKeySpec to compare
    
    b - a PBEKeySpec to compare
    
    Returns:
    
    true if they can be used for encryption interchangeably
  - hashCode
```
public int hashCode()
```
    Returns the hashcode of this object. Does not include cipherProvider in hashcode calculations.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    the hashcode
  - toString
```
public String toString()
```
    Returns a String containing the algorithm, provider, encoding, and cipherProvider class name.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a String representation of the object state

Class StringEncryptor

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

logger

SUPPORTED_ALGORITHMS

SUPPORTED_PROVIDERS

ARGON2_AES_GCM_256_ALGORITHM

ARGON2_AES_GCM_128_ALGORITHM

CUSTOM_ALGORITHMS

CUSTOM_ALGORITHM_SALT_LENGTH

IV_LENGTH

algorithm

provider

password

key

HEX_ENCODING

B64_ENCODING

encoding

cipherProvider

NF_SENSITIVE_PROPS_KEY

NF_SENSITIVE_PROPS_ALGORITHM

NF_SENSITIVE_PROPS_PROVIDER

DEFAULT_SENSITIVE_PROPS_KEY

Constructor Detail

StringEncryptor

StringEncryptor

StringEncryptor

Method Detail

extractKeyTypeFromAlgorithm

createEncryptor

createEncryptor

printBlankKeyWarning

centerString

initialize

isCustomAlgorithm

paramsAreValid

customSecretIsValid

keyIsValid

passwordIsValid

setEncoding

encrypt

encryptPBE

getEncryptionMethodForAlgorithm

encryptKeyed

encode

decrypt

decryptPBE

determineSaltLength

decryptKeyed

decode

isInitialized

algorithmIsValid

providerIsValid

equals

secretsAreEqual

isPBEKeySpecEqual

hashCode

toString