com.ehsbe.commons.util
Class NetAuthenticator

java.lang.Object
  java.net.Authenticator
      com.ehsbe.commons.util.NetAuthenticator

Direct Known Subclasses:

JxNetAuthenticator

public class NetAuthenticator
extends Authenticator

An Authenticator, which is able to retrieve and store passwords from a single file. Since it should be possible to use this instance in a none interactive environment, the store always contains only one username/password per entity requesting authentication.

Version:

$Revision: 460 $

Author:

Firstname Lastname

Nested Class Summary

Nested classes/interfaces inherited from class java.net.Authenticator

Authenticator.RequestorType

Constructor Summary

NetAuthenticator()
Create an uninitialized authenticator, which will always return a null PasswordAuthentication as long as it has no entries.

NetAuthenticator(byte[] store, char[] pass)
Create an authenticator, by decrypting the password store containing byte array using the given password!

NetAuthenticator(File store, char[] pass)
Create an authenticator, which reads in the given password storage file decrypting it using the given password!

NetAuthenticator(InputStream store, char[] pass)
Create an authenticator, which reads in the given password storage input stream and decrypts it using the given password!

NetAuthenticator(String username, char[] password)
Create an authenticator, which will always use the same aka default user/password pair.

Method Summary

protected boolean	add(PasswordAuthentication pair, boolean replaceAll) Add/replaces the given username/password to/from the internal password store for the entity requesting authentication.
static void	cleanPass(char[] pass) Overwrites the given char array with '\0's
protected PasswordAuthentication	getPasswordAuthentication() Calls getPasswordAuthentications() and returns a copy of the first entry in the returned map.
protected Set<PasswordAuthentication>	getPasswordAuthentications() Checks, whether there is an entry in the internal password store, which matches the criteria of the entity requesting authentication.
protected boolean	isEmpty() Check, whether there are entries in this store.
protected boolean	isSecretKeySet() Check, whether a secret key has already been set.
protected void	read(byte[] store, char[] oldPass, char[] pass) Decrypts the password store containing byte array and replaces all internally stored information of this instance with the decoded content.
protected void	read(InputStream store, char[] oldPass, char[] pass) Reads the encrypted password store from the given stream completely into memory and gets finally encoded.
protected boolean	remove(String username) Remove the entry for the given user wrt. matching entity requesting authentication.
protected void	reset() Reset this instance to its initial state with an empty password store and no secret key.
protected void	setSecretKey(char[] oldPass, char[] newPass) Sets or replaces the current secret key to use for encryption.
protected byte[]	store() Writes the internal store encoded to the returned byte array.
protected void	store(OutputStream out) Writes the internal store encoded to the given output stream.
protected boolean	storeModified() Check, whether the password store has been changed and should be saved somewhere.

Methods inherited from class java.net.Authenticator

getRequestingHost, getRequestingPort, getRequestingPrompt, getRequestingProtocol, getRequestingScheme, getRequestingSite, getRequestingURL, getRequestorType, requestPasswordAuthentication, requestPasswordAuthentication, requestPasswordAuthentication, setDefault

Methods inherited from class java.lang.Object

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

Constructor Detail

NetAuthenticator

public NetAuthenticator()

Create an uninitialized authenticator, which will always return a null PasswordAuthentication as long as it has no entries.

NetAuthenticator

public NetAuthenticator(String username,
                        char[] password)
                 throws SecurityException

Create an authenticator, which will always use the same aka default user/password pair. Take care and use this one with caution, since it reveals both values to any server, no matter, whether you want this or not!

NOTE: This entry gets neither stored via store() or store(OutputStream) nor generates a secret key.

Parameters:

username - a none-null username

password - a none-null password

Throws:

SecurityException - if null parameter encountered

NetAuthenticator

public NetAuthenticator(File store,
                        char[] pass)
                 throws FileNotFoundException,
                        SecurityException

Create an authenticator, which reads in the given password storage file decrypting it using the given password!

Parameters:

store - the password storage file to read.

pass - the password to encrypt the storage file.

Throws:

FileNotFoundException

SecurityException

NetAuthenticator

public NetAuthenticator(InputStream store,
                        char[] pass)
                 throws SecurityException

Create an authenticator, which reads in the given password storage input stream and decrypts it using the given password!

Parameters:

store - the password storage file to read. Gets not closed.

pass - the password to encrypt the storage file.

Throws:

SecurityException

NetAuthenticator

public NetAuthenticator(byte[] store,
                        char[] pass)
                 throws SecurityException

Create an authenticator, by decrypting the password store containing byte array using the given password!

Parameters:

store - the password storage file to read.

pass - the password to encrypt the storage file.

Throws:

SecurityException

Method Detail

getPasswordAuthentication

protected PasswordAuthentication getPasswordAuthentication()

Calls getPasswordAuthentications() and returns a copy of the first entry in the returned map.

Overrides:

getPasswordAuthentication in class Authenticator

Returns:

null if no appropriate entry was found, the entry by reference otherwise.

See Also:

getPasswordAuthentications(), Iterator.next()

getPasswordAuthentications

protected Set<PasswordAuthentication> getPasswordAuthentications()

Checks, whether there is an entry in the internal password store, which matches the criteria of the entity requesting authentication.

To give a user the chance to use/change/remove a password for the entity requesting authentication, one should overwrite this method and add/remove the new value before returning the final result.

If overwritten, one should return null or a singleton (i.e. an unmodifiable set, which contains just one entry). Otherwise the callee may choose the wrong entry to pass.

Returns:

null if not entries are found, a copy of the set of possible authentication pairs matching the entity requesting authentication otherwise.

See Also:

Collections.singleton(Object), getPasswordAuthentication()

add

protected final boolean add(PasswordAuthentication pair,
                            boolean replaceAll)
                     throws SecurityException

Add/replaces the given username/password to/from the internal password store for the entity requesting authentication. One should never call this outside of getPasswordAuthentications() or getPasswordAuthentication(), since it relies on the synchronized access via the requestPasswordAuthentication(...) methods.

Parameters:

pair - username/password to add. If null or one entry of the pair is null, it gets silently ignored.

replaceAll - if true replace all entries for the matching authentication requesting entity with the given one.

Returns:

true on success.

Throws:

SecurityException - if no secret key has been set yet

remove

protected final boolean remove(String username)
                        throws SecurityException

Remove the entry for the given user wrt. matching entity requesting authentication.

Parameters:

username - username to lookup.

Returns:

true if a matching entry has been found and thus got removed.

Throws:

SecurityException - if not secret key has been set yet.

cleanPass

public static void cleanPass(char[] pass)

Overwrites the given char array with '\0's

Parameters:

pass - array to overwrite.

read

protected final void read(InputStream store,
                          char[] oldPass,
                          char[] pass)
                   throws SecurityException

Reads the encrypted password store from the given stream completely into memory and gets finally encoded. Replaces all internally stored information of this instance.

Parameters:

store - store to read from

oldPass - secret key currently in use. Ignore if no secret key has been set yet.

pass - password to be used for decryption

Throws:

SecurityException - if reading the store or decryption fails.

read

protected final void read(byte[] store,
                          char[] oldPass,
                          char[] pass)
                   throws SecurityException

Decrypts the password store containing byte array and replaces all internally stored information of this instance with the decoded content.

On success the internal state gets reset to unchanged and the secret key replaced with the one used for decryption.

Parameters:

store - encrypted password store to read.

oldPass - secret key currently in use. Ignore if no secret key has been set yet.

pass - password to be used for decryption.

Throws:

SecurityException - if decryption fails or a parameter is invalid or null.

See Also:

storeModified()

store

protected final byte[] store()
                      throws SecurityException

Writes the internal store encoded to the returned byte array.

Returns:

an byte array containing the encoded password store.

Throws:

SecurityException - if encoding fails.

See Also:

isSecretKeySet(), setSecretKey(char[], char[])

store

protected final void store(OutputStream out)
                    throws SecurityException

Writes the internal store encoded to the given output stream. The store gets completely encoded in memory, before writing to the given output stream starts.

Parameters:

out - where to write

Throws:

SecurityException - if encoding or writing fails.

See Also:

store(), isSecretKeySet(), setSecretKey(char[], char[])

isSecretKeySet

protected final boolean isSecretKeySet()

Check, whether a secret key has already been set.

Returns:

true if set.

setSecretKey

protected final void setSecretKey(char[] oldPass,
                                  char[] newPass)
                           throws SecurityException

Sets or replaces the current secret key to use for encryption.

Parameters:

oldPass - the password for the current secret key. Ignored, if no secret key has been set yet.

newPass - the new password to set.

Throws:

SecurityException - if new and old password do not match or a new secret key can't be generated.

isEmpty

protected final boolean isEmpty()

Check, whether there are entries in this store.

Returns:

true if there is at least one entry in this store.

storeModified

protected final boolean storeModified()

Check, whether the password store has been changed and should be saved somewhere.

Returns:

true if modified.

reset

protected final void reset()

Reset this instance to its initial state with an empty password store and no secret key.