com.edustructures.sifworks
Class SIFEncryption

java.lang.Object
  com.edustructures.sifworks.SIFEncryption

public abstract class SIFEncryption
extends java.lang.Object

Provides easy read and write access to encrypted passwords in the Authentication object

This class is abstract. Concrete instances can be obtained by calling the appropriate getInstance overload.

The SIFEncryption class uses the following properties to determine its default algorithm and key for writing and for finding keys for decrypting passwords. Please see for details

Property	Description
adk.encryption.algorithm	The default algorithm used for writing passwords
adk.encryption.key	The name of the default key to use for encryption
adk.encryption.keys.[keyname]	The actual key to use for encryption or decryption where “keyname” matches the @KeyName attribute of the AuthenticationInfoPassword object

For example usage, please see the AuthenticationProvider and AuthenticationSubscriber example projects.

Version:

ADK 1.5.1

Method Summary

PasswordAlgorithm	getAlgorithm() Returns the encryption algorithm that is in use by the class
static SIFEncryption	getInstance(PasswordAlgorithm algorithm, java.lang.String keyName, byte[] key) Creates an instance of SIFEncryption that uses the specified PasswordAlgorithm, keyName and key.
static SIFEncryption	getInstance(Password password, Zone zone) Creates an instance of SIFEncryption that can decrypt the password field automatically, using settings defined in the agent's properties.
static SIFEncryption	getInstance(Zone zone) Creates an instance of SIFEncryption that can be used for writing the AuthenticationInfoPassword field, using settings from the agent's properties
abstract byte[]	getKey() Returns the key that the class is currently using to encrypt or decrypt passwords
java.lang.String	getKeyName() Returns the name of the key that is currently being used.
abstract boolean	isHash() Returns true if the value is a hashed value and cannot be decrypted.
abstract java.lang.String	readPassword(Password password) Returns the unencrypted password value from the AuthenticationInfoPassword field.
void	writePassword(Password password, java.lang.String value) Encrypts the specified password and populates the AuthenticationInfoPassword field with the algorithm and key name values.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static SIFEncryption getInstance(PasswordAlgorithm algorithm,
                                        java.lang.String keyName,
                                        byte[] key)
                                 throws java.security.NoSuchAlgorithmException,
                                        javax.crypto.NoSuchPaddingException

Creates an instance of SIFEncryption that uses the specified PasswordAlgorithm, keyName and key.

Parameters:

algorithm - The algorithm to use for encrypting or decrypting passwords

keyName - The name of the encryption key to use.

key - The encryption key to use. This parameter is ignored for SHA1 and MD5 because they are not keyed hash algorithms. It's also ignore for BASE64

Returns:

an instance of the SIFEncryption class that can read and write passwords using the chosen algorithm and key.

Throws:

java.security.NoSuchAlgorithmException - Thrown if the specified algorithm is not available. For example, RC2 and RSA are not available in the default java 1.4 cipher suites.

javax.crypto.NoSuchPaddingException - Thrown if the padding method (which is always PKCS5Padding) is not available

getInstance

public static SIFEncryption getInstance(Password password,
                                        Zone zone)
                                 throws java.io.IOException,
                                        java.security.NoSuchAlgorithmException,
                                        javax.crypto.NoSuchPaddingException

Creates an instance of SIFEncryption that can decrypt the password field automatically, using settings defined in the agent's properties.

This method searches the agent properties in effect for the zone and looks for one that matches the key defined in the AuthenticationInfoPassword object. If it finds one, it returns an instance of SIFEncryption that has been initialized with the proper key and encryption algorithm for the field.

This method looks for a property named adk.encryption.keys.[keyName] where [keyName] is the name of the key field defined by the AuthenticationInfoPassword field.

Parameters:

password - The password object that needs to be decrypted

zone - The zone that is in scope for the current message

Returns:

An instance of SIFEncryption that can read the password from the given A uthenticationInfoPassword object

Throws:

java.io.IOException - If the key stored in the agent properties cannot be converted from BASE64 to binary

java.security.NoSuchAlgorithmException - Thrown if the specified algorithm is not available. For example, RC2 and RSA are not available in the default java 1.4 cipher suites.

javax.crypto.NoSuchPaddingException - Thrown if the padding method (which is always PKCS5Padding) is not available

getInstance

public static SIFEncryption getInstance(Zone zone)
                                 throws ADKException,
                                        java.io.IOException,
                                        javax.crypto.NoSuchPaddingException,
                                        java.security.NoSuchAlgorithmException

Creates an instance of SIFEncryption that can be used for writing the AuthenticationInfoPassword field, using settings from the agent's properties

This method searches for two properties in the agent properties. adk.encryption.algorithm returns the default algorithm the agent uses for encryption. adk.encryption.key returns the name of the key to use for encryption, which, if required, will be read from the adk.encryption.keys.[keyName] property. The adk.encryption.keys.[keyName] property is not used or required for base64, SHA1, and MD5.

The adk.encryption.key property is required for encryption methods that use a key. It is this value that will be written to the @KeyName attribute of the AuthenticationInfoPassword object.

Parameters:

zone - the zone that is in scope for the current message

Returns:

an instance of SIFEncryption that can write or read passwords using the default settings.

Throws:

ADKException - If the agent properties do not contain a default encryption algorithm or key. The adk.encryption.key property is required for encryption methods that use a key. It is this value that will be written to the @KeyName attribute of the AuthenticationInfoPassword object.

java.io.IOException - If the key stored in the agent properties cannot be converted from BASE64 to binary

java.security.NoSuchAlgorithmException - Thrown if the specified algorithm is not available. For example, RC2 and RSA are not available in the default java 1.4 cipher suites.

javax.crypto.NoSuchPaddingException - Thrown if the padding method (which is always PKCS5Padding) is not available

writePassword

public void writePassword(Password password,
                          java.lang.String value)
                   throws java.io.IOException,
                          java.security.InvalidKeyException,
                          javax.crypto.IllegalBlockSizeException,
                          javax.crypto.BadPaddingException

Encrypts the specified password and populates the AuthenticationInfoPassword field with the algorithm and key name values.

Parameters:

password - The password object to write the encrypted password to

value - The plain-text password to write to the object

Throws:

java.io.IOException - If the value cannot be encoded to base64

java.security.InvalidKeyException - If the key provided is not valid for the cipher algorithm

javax.crypto.IllegalBlockSizeException

javax.crypto.BadPaddingException

readPassword

public abstract java.lang.String readPassword(Password password)
                                       throws java.io.IOException,
                                              java.security.InvalidKeyException,
                                              javax.crypto.IllegalBlockSizeException,
                                              javax.crypto.BadPaddingException,
                                              java.security.InvalidAlgorithmParameterException

Returns the unencrypted password value from the AuthenticationInfoPassword field.

If the algorithm in use is a hash algorithm, the Base64 instance of the hash will be returned instead. The application can check the isHash() method to determine of the value being returned is a hash value or the plain-text password.

Parameters:

password - The password object to read the password value from

Returns:

The plain-text password or hash value

Throws:

java.io.IOException - If a decryption error occurs

java.security.InvalidKeyException - If a decryption error occurs

javax.crypto.IllegalBlockSizeException - If a decryption error occurs

javax.crypto.BadPaddingException - If a decryption error occurs

java.security.InvalidAlgorithmParameterException - If a decryption error occurs

getAlgorithm

public PasswordAlgorithm getAlgorithm()

Returns the encryption algorithm that is in use by the class

Returns:

the encryption algorithm that is currently being used

getKeyName

public java.lang.String getKeyName()

Returns the name of the key that is currently being used. This value is the same as the Password.getKeyName() attribute.

Returns:

the name of the key that is currently being used

getKey

public abstract byte[] getKey()

Returns the key that the class is currently using to encrypt or decrypt passwords

Returns:

the encryption key

isHash

public abstract boolean isHash()

Returns true if the value is a hashed value and cannot be decrypted. In this case, the readPassword(Password) method will return the hashed value as a Base64 string

Returns:

true if the password is a hashed value. false if it is a plain-text password that can be decrypted