org.azyva.dragom.security

Class CredentialStore

java.lang.Object

org.azyva.dragom.security.CredentialStore

public class CredentialStore
extends Object

This class allows managing credentials securely. It is used by DefaultCredentialStorePluginImpl. Although both classes are similar, the low-level logic for managing the credentials has been factored out in this class for increased flexibility. Note however that contrary to DefaultCredentialStorePluginImpl, this class does not interact with the user.

Credentials are managed in a Properties file whose containing 2 types of entries:

• <REALM>.<user>.Password=<encrypted-password>
• <REALM>.DefaultUser=<default-user>

The first defines a password for a user in a realm. The second defines a default user for a realm. See below for more information about realms.

The passwords are encrypted using a key that is constructed from three parts of key material:

• A constant password hardcoded in this class
• The current user name (system property user.name)
• A random password stored in a master password file

If the master password file does not exist, it is created with newly generated random password.

This is not the highest security, but is considered sufficient in the current context. Properly securing passwords that must be stored locally is hard. No matter the logic used, one always ends up having to store some decryption key somewhere. The fact that the master password file can be stored in the user home directory, not accessible for reading to others makes the solution sufficiently secure.

This class uses a sequence of mappings between resource Pattern's and corresponding realms and users. These mapping are specified when the class is initialized.

See java.util.regex for information about regular expressions in Java.

A resource is typically the URL of a service, such as https://john.smith@acme.com/my-git-repository.git.

When a method takes a resource, it maps this resource to a realm using these mappings. The first mapping whose resource Pattern matches the resource is used. A mapping must correspond to a resource. A catch-all mapping can be used if necessary.

Passwords are associated with realms obtained from the mappings, not resources directory.

A resource can also include a user. Mappings can specify a captured group to extract it.

Passwords are associated with realms, not resources directly. Therefore no method takes a realm as an argument. However, in some cases, such as for a tool that allows the user to manage the credentials, it can be convenient to let the user explicitly specify realms. This can be achieved generically by introducing a mapping that, for example, maps "REALM:(.*)" to the realm $1 (the first captured group).

Author:

David Raymond

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CredentialStore.RealmUser Realm and user tupple.
static class	CredentialStore.ResourceInfo Information about a resource.
static class	CredentialStore.ResourcePatternRealmUser Mapping from a resource Pattern to a realm and user.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_CREDENTIAL_FILE Default credential file.
static String	DEFAULT_MASTER_KEY_FILE Default master password file.
static String	PROPERTY_SUFFIX_DEFAULT_USER Property suffix for the default user.
static String	PROPERTY_SUFFIX_PASSWORD Property suffix for a password.

Constructor Summary

Constructors

Constructor and Description
CredentialStore(Path pathCredentialFile, Path pathMasterKeyFile, List<CredentialStore.ResourcePatternRealmUser> listResourcePatternRealmUser) Constructor.

Method Summary

Modifier and Type	Method and Description
boolean	deleteDefaultUser(String resource) Removes the default user for the realm corresponding to a resource.
boolean	deletePassword(String resource, String user) Deletes a password from the credential store.
String	getDefaultUser(String resource) Returns the default user for a resource.
List<CredentialStore.RealmUser>	getListRealmUser()
List<CredentialStore.RealmUser>	getListRealmUserDefault()
List<CredentialStore.ResourcePatternRealmUser>	getListResourcePatternRealmUser()
String	getPassword(String resource, String user) Returns a password from the credential store.
CredentialStore.ResourceInfo	getResourceInfo(String resource) Returns information about a resource.
void	resetCredentialFile() Resets the credential file so that it is reloaded when next required.
boolean	setDefaultUser(String resource, String user) Sets the default user for the realm corresponding to a resource.
boolean	setPassword(String resource, String user, String password) Sets a password in the credential store.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CREDENTIAL_FILE

public static final String DEFAULT_CREDENTIAL_FILE

Default credential file. When no credential file is specified during initialization this file is used in the user home directory.

The caller can use this constant to construct a credential file Path which uses that same file name, but a different directory.

See Also:

Constant Field Values

DEFAULT_MASTER_KEY_FILE

public static final String DEFAULT_MASTER_KEY_FILE

Default master password file. When no master password file is specified during initialization this file is used in the user home directory.

The caller can use this constant to construct a master password file Path which uses that same file name, but a different directory.

See Also:

Constant Field Values

PROPERTY_SUFFIX_DEFAULT_USER

public static final String PROPERTY_SUFFIX_DEFAULT_USER

Property suffix for the default user. The prefix is the realm.

See Also:

Constant Field Values

PROPERTY_SUFFIX_PASSWORD

public static final String PROPERTY_SUFFIX_PASSWORD

Property suffix for a password. The prefix is <realm>.<user>.

See Also:

Constant Field Values

Constructor Detail

CredentialStore

public CredentialStore(Path pathCredentialFile,
                       Path pathMasterKeyFile,
                       List<CredentialStore.ResourcePatternRealmUser> listResourcePatternRealmUser)

Constructor.

If pathMasterPassworedFile is null, the master password file is "dragom-master-password" in the user home directory.

If pathCredentialFile is null, the credential file is "dragom-credentials.properties" in the user home directory.

After initialization, listResourcePatternRealmUser is considered as belonging to this class and should not be modified by the caller. This ciass does not make a copy for efficiency reasons.

Parameters:

pathMasterKeyFile - Path of the master password file. Can be null.

pathCredentialFile - Path of the credential file. Can be null.

listResourcePatternRealmUser - List of CredentialStore.ResourcePatternRealmUser.

Method Detail

resetCredentialFile

public void resetCredentialFile()

Resets the credential file so that it is reloaded when next required.

getResourceInfo

public CredentialStore.ResourceInfo getResourceInfo(String resource)

Returns information about a resource.

Parameters:

resource - Resource.

Returns:

ResourceInfo. null if no resource Pattern to realm and user mapping is found.

getPassword

public String getPassword(String resource,
                          String user)

Returns a password from the credential store.

If no resourcePattern mapping to a realm and user is found, null is returned.

If user is null, a user must be inferred. If it is specified within the resource, this user is used. Otherwise, if a default user is defined in the credentials for the realm corresponding to the resource, this user is used. Otherwise, null is returned.

If user is not null and a user is specified within the resource, they must match, otherwise null is returned.

If null is returned, getResourceInfo(java.lang.String) can be called to know more about the resource.

Parameters:

resource - Resource.

user - User. Can be null.

Returns:

Password. null if requested credentials are not defined in the store.

setPassword

public boolean setPassword(String resource,
                           String user,
                           String password)

Sets a password in the credential store.

If no resourcePattern mapping to a realm and user is found, false is returned.

If user is null, a user must be inferred. If it is specified within the resource, this user is used. Otherwise, if a default user is defined in the credentials for the realm corresponding to the resource, this user is used. Otherwise, false is returned.

If user is not null and a user is specified within the resource, they must match, otherwise false is returned.

If false is returned, getResourceInfo(java.lang.String) can be called to know more about the resource.

If a password is already set for the realm and the user, it is overwritten.

Parameters:

resource - Resource.

user - User. Can be null.

password - Password.

Returns:

Indicates if the password was successfully set.

deletePassword

public boolean deletePassword(String resource,
                              String user)

Deletes a password from the credential store.

If no resourcePattern mapping to a realm and user is found, false is returned.

If user is null, a user must be inferred. If it is specified within the resource, this user is used. Otherwise, if a default user is defined in the credentials for the realm corresponding to the resource, this user is used. Otherwise, false is returned.

If user is not null and a user is specified within the resource, they must match, otherwise false is returned.

If false is returned, getResourceInfo(java.lang.String) can be called to know more about the resource.

Parameters:

resource - Resource.

user - User. Can be null.

Returns:

Indicates if the password was successfully deleted.

getListResourcePatternRealmUser

public List<CredentialStore.ResourcePatternRealmUser> getListResourcePatternRealmUser()

Returns:

List of CredentialStore.ResourcePatternRealmUser.

getListRealmUser

public List<CredentialStore.RealmUser> getListRealmUser()

Returns:

List of RealmUser representing the realms and users for which a password is defined.

getListRealmUserDefault

public List<CredentialStore.RealmUser> getListRealmUserDefault()

Returns:

List of RealmUser representing the realms and their default users.

getDefaultUser

public String getDefaultUser(String resource)

Returns the default user for a resource.

If no resourcePattern mapping to a realm and user is found, null is returned.

If the resource specifies a user, null is returned.

Otherwise, the default user specified for the realm corresponding to the resource is returned.

If no default user is defined for the realm, null is returned.

Parameters:

resource - Resource.

Returns:

See description.

setDefaultUser

public boolean setDefaultUser(String resource,
                              String user)

Sets the default user for the realm corresponding to a resource.

If no resourcePattern mapping to a realm and user is found, false is returned.

If the resource specifies a user, false is returned.

If a default user is already defined for the realm corresponding to the resource, it is overwritten.

Parameters:

resource - Resource.

user - User.

Returns:

Indicates if the default user was successfully set.

deleteDefaultUser

public boolean deleteDefaultUser(String resource)

Removes the default user for the realm corresponding to a resource.

If no resourcePattern mapping to a realm and user is found, false is returned.

If the resource specifies a user, false is returned.

Parameters:

resource - Resource.

Returns:

Indicates if the default user was successfully deleted.