org.opentox.toxotis.util.aa
Class PasswordFileManager

java.lang.Object
  extended by java.util.Observable
      extended by org.opentox.toxotis.util.aa.PasswordFileManager

public final class PasswordFileManager
extends Observable

Create highly secure password files to store your credentials. Your username and password are stored in an encrypted format using a master key that you have to provide. The master key is used when you need to create a new username+password file or when you need to use this password file to authenticate your self. This way, you will never need to provide your credentials within your application. Firstly, you have to create a password file that has the following structure:

--- START MASTER KEY ---
 m2gWQ1FRUVdSXXxhOVBnazQyKy8vUzRcPWFfJ2tmKpE
 tZm1rcm5rZ2MNCaA/RPQtLjJfFjt/bHQ0S0Q/MzkxbU
 qg|lztU51cRDRmCcczbmMjZ3ZiZlFRbGRlYWtmbnIoL
 jAaYWZlLW5lbWbwT0IERXgHtUtubWQ+ZjJtQEBtZmlh
 ZG5hamVuZmdyb18xOTQVIWD3A:FJMQYzN5c2hjM1vTk
 ... [ More random characters go here ] ....
 eq25nDVg4sfmaFp4g5taFghtSD2g5l09Ufn*adegHlo
 --- END MASTER KEY ---

This can be done using the method createMasterPasswordFile(java.lang.String, java.lang.String, int, boolean). Store this file somewhere on your machine (We suggest that you made it hidden and specify its permissions properly). Then you can use this file to create an encrypted password file or authenticate yourself against the SSO server providing the path of your password file and not your credentials! Here are two examples:


 // Example 1: Create a password file
 PasswordFileManager.CRYPTO.createMasterPasswordFile("john", "s3cret", "./secret/my.key");
 
 // Example 2: Authentication using the password file
 // No credentials are provided
 AuthenticationToken at = PasswordFileManager.CRYPTO.
    authFromFile("./secret/my.key");
 

It does not work: The most common reasons for exceptional events are the following:

  1. The master password file is not found: Make sure you have created a master password file and have stored it in a directory where the application has access and read priviledges. You can set the path of the master key file using the method setMasterPasswordFile(String). The default destination for this file is './secret/secret.key' on linux and MacOSX machines and '.\secret\secret.key' on Windows.
  2. The master key file has bad syntax: Make sure your master key file has the header --- START MASTER KEY --- as the first line and the footer --- END MASTER KEY --- at the end. Leave no empty lines.
  3. The master key is found and is valid but you cannot authenticate yourself: This might happen if your password file was created with less or more salt. Check out the salting iterations using the method getCryptoIterations() (The default value is 23).

Author:
Pantelis Sopasakis, Charalampos Chomenides
See Also:
authFromFile(java.io.File), createPasswordFile(java.lang.String, java.lang.String, java.lang.String)

Field Summary
static PasswordFileManager CRYPTO
          This class is a singleton and this is the access point for it.
 
Method Summary
 AuthenticationToken authFromFile(File file)
          Acquire an authentication token using the credentials in an encrypted file.
 AuthenticationToken authFromFile(String filePath)
          Acquire an authentication token using the credentials in an encrypted file.
 void createMasterPasswordFile(String randomGenerator, String destination, int size, boolean verbose)
          Create a master password file for managing you password files.
 void createPasswordFile(String username, String password, String filePath)
          Create an encrypted file containing the credentials provided in this method.
protected  String decrypt(String encrypted)
           
protected  String encrypt(String message)
           
 int getCryptoIterations()
          Number of salting iterations that is used by this encryption/decryption algorithm.
 double getPasswordGenerationProgress()
          Returns a double between 0 and 100 that monitors the progress of the password file creation.
static void main(String... art)
           
 void setCryptoIterations(int cryptoIterations)
          Set the salting iterations to be used in all encryption/decryption operations of the Password Manager.
 void setMasterPasswordFile(String masterPasswordFile)
          Set the location of the master password file.
 
Methods inherited from class java.util.Observable
addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CRYPTO

public static final PasswordFileManager CRYPTO
This class is a singleton and this is the access point for it. Being final users don't need to worry about synchronization

Method Detail

getPasswordGenerationProgress

public double getPasswordGenerationProgress()
Returns a double between 0 and 100 that monitors the progress of the password file creation.

Returns:
Password generation progress

createMasterPasswordFile

public void createMasterPasswordFile(String randomGenerator,
                                     String destination,
                                     int size,
                                     boolean verbose)
                              throws IOException
Create a master password file for managing you password files. You credentials will be stored in a password file

Parameters:
randomGenerator - Path to random numbers generator device (for example on a Linux machine you can choose /dev/random or /dev/urandom). Setting it to null,a pseudorandom generator that depends on SecureRandom will be used.
destination - Path where the master key will be stored
size - Size of your password
verbose - Whether information about the procedure should be output to the console
Throws:
IOException - In case either the random generator or the destination for the master password are unreachable or a read/write exception occurs.

encrypt

protected String encrypt(String message)
                  throws SecurityException
Throws:
SecurityException

decrypt

protected String decrypt(String encrypted)
                  throws SecurityException
Throws:
SecurityException

createPasswordFile

public void createPasswordFile(String username,
                               String password,
                               String filePath)
                        throws IOException
Create an encrypted file containing the credentials provided in this method. You need the master password file that was used to encrypt these credentials to decrypt them and use them to acquire an authentication token.

Parameters:
username - You username
password - Your password
filePath - The file where the credentials should be stored.
Throws:
IOException - In case the destination is not reachable or you do not have access and write priviledges to that file or other I/O event inhibits the data transaction.

authFromFile

public AuthenticationToken authFromFile(String filePath)
                                 throws IOException,
                                        ToxOtisException,
                                        ServiceInvocationException
Acquire an authentication token using the credentials in an encrypted file. These are decrypted using the master key (the destination to the master key file should have been set properly) and POSTed to the SSO server which returns a token for that user or an error response if the credentials are not valid.

Parameters:
filePath - Path to the file containing the credentials
Returns:
An Authentication Token upon successful authentication against the SSO server.
Throws:
IOException - In case the file path you provided cannot be found (an instance of java.io.FileNotFoundException or if you do not have sufficient priviledges to read from that file.
ToxOtisException - In case the remote SSO server responds with an error code (e.g. 401 - Unauthorized or 403 - Forbidden), other HTTP related events inhibit the creation of am Authentication Token or if the provided password file is not valid.
ServiceInvocationException
See Also:
authFromFile(File)

authFromFile

public AuthenticationToken authFromFile(File file)
                                 throws IOException,
                                        ToxOtisException,
                                        ServiceInvocationException
Acquire an authentication token using the credentials in an encrypted file. These are decrypted using the master key (the destination to the master key file should have been set properly) and POSTed to the SSO server which returns a token for that user or an error response if the credentials are not valid.

Parameters:
file - File containing the credentials (an instance of java.io.File)
Returns:
An Authentication Token upon successful authentication against the SSO server.
Throws:
IOException - In case the file path you provided cannot be found (an instance of java.io.FileNotFoundException or if you do not have sufficient priviledges to read from that file.
ToxOtisException - In case the remote SSO server responds with an error code (e.g. 401 - Unauthorized or 403 - Forbidden), other HTTP related events inhibit the creation of am Authentication Token or if the provided password file is not valid.
ServiceInvocationException
See Also:
authFromFile(String)

setMasterPasswordFile

public void setMasterPasswordFile(String masterPasswordFile)
Set the location of the master password file. By default this is set to './secret/secret.key'

Parameters:
masterPasswordFile - Path to the master password file
See Also:
Documentation

getCryptoIterations

public int getCryptoIterations()
Number of salting iterations that is used by this encryption/decryption algorithm.

Returns:
Returns the number of salting for the username and password.

setCryptoIterations

public void setCryptoIterations(int cryptoIterations)
Set the salting iterations to be used in all encryption/decryption operations of the Password Manager. A large number of salting iterations offers greater security but might cause slower responses.

Parameters:
cryptoIterations - Number of salting iteration.

main

public static void main(String... art)
                 throws Exception
Throws:
Exception


Copyright © 2011-2012 OpenTox. All Rights Reserved.