com.novell.security.sso
Class SecretStore

java.lang.Object
  |
  +--com.novell.security.sso.SecretStore

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

JNDISecretStore, NCPSecretStore

public abstract class SecretStore

extends Object

implements Serializable

An abstract class that represents a SecretStore. Actual instances are created using the getInstance(Hashtable env) method. Information may be passed to implementations in the form of environment properties. Information may be obtained from implementations in the form of properties by calling the getEnvironmentProperty(String key). This design was used so that there would only be one interface to SecretStore independent of which protocol is used underneath.

Below is listed the known properties and their descriptions. Additional properties may be defined by implementations that may or may not be part of this list. See the implementation documentation for details.

Key	Property Class Type	Description
"com.novell.sso.callerdn"	java.lang.String	A property that specifies distinguised name of the caller, or in other words, the object that is making the request. Some implementations may require this to be set. Some implementations may set this for you either after construction of a SecretStore or after a call to getServiceInfo() has been made. The exact behavior is dependent on the implementation.
"com.novell.sso.handle"	Dependent on implementation	An environment property that specifies a handle. The exact definition is left up to the implementation. Some implementations may require that this property be provided. See implementation documentation for details.
"com.novell.sso.secretstore"	java.lang.String	An environment property that specifies the class name of the SecretStore implementation to use. This property is always required.
"com.novell.sso.serverdn"	java.lang.String	An environment property that specifies the distinguised name of the SecretStore server. This is set either after construction of a SecretStore or after a call to getServiceInfo() has been made. The exact behavior is dependent on the implementation.
"com.novell.sso.targetdn"	java.lang.String	An environment property that specifies the distinguised name of the object for which SecretStore operations will be made. This is set either after construction of a SecretStore or after a call to getServiceInfo() has been made. The exact behavior is dependent on the implementation.
"com.novell.sso.tree"	java.lang.String	An environment property that specifies the tree name on which the SecretStore server resides. Some implementations may require that this property be provided. See implementation documentation for details.

This class relies upon SSPermission for access control.

Since:

2.1

Version:

3.2

Author:

Steve Kinser

See Also:

getEnvironmentProperty(String key), getInstance(Hashtable env), SSPermission, Serialized Form

Field Summary

static String	CALLER_DN A property that specifies the distinguished name of the user that is requesting SecretStore operations.
static String	HANDLE An environment property that specifies a handle.
static String	SECRET_STORE An environment property that specifies the class name of the SecretStore implementation that will be loaded and used.
static String	SERVER_DN A property that specifies the distinguished name of the server that is being used for SecretStore operations.
static String	TARGET_DN An environment property that specifies the distinguished name of the object for which SecretStore operations will be made.
static String	TREE An environment property that specifies the tree in which the SecretStore server resides.
static String	USER_DN Deprecated. This has been replaced by TARGET_DN because the target object can be of any class.

Method Summary

void	commitMasterPasswordChange() Commits the master password change in SecretStore.
void	commitMasterPasswordChange(int flags) Commits the master password change in SecretStore.
void	commitMasterPasswordChange(int flags, char[] passhint) Commits the master password change in SecretStore.
StringTokenizer	enumerateSecrets() Enumerates the secrets in SecretStore by returning a StringTokenizer containing the secret identifiers in SecretStore separated by *.
StringTokenizer	enumerateSecrets(int flags, String filter) Enumerates the secrets in SecretStore by returning a StringTokenizer containing the secret identifiers in SecretStore separated by *.
StringTokenizer	enumerateSecrets(int flags, String filter, int maxLen) Enumerates the secrets in SecretStore by returning a StringTokenizer containing the secret identifiers in SecretStore separated by *.
boolean	equals(Object obj)
byte	getClientCryptoStrength() Returns the client's crypto strength.
int	getClientVersion() Returns the client's SecretStore version.
int	getEnumBuffLen() Returns the enumeration buffer length.
Object	getEnvironmentProperty(String key) Used to obtain information about environment properties and to provide a standard way for implementations to pass back information.
char[]	getHint() Returns the SecretStore's hint for the master password.
static SecretStore	getInstance(Hashtable env) Returns a SecretStore instance based on the Hastable environment that is passed in.
String	getLastAdminUnlockDn() Returns the distinguished name of the last SecretStore administrator that unlocked the SecretStore.
Date	getLastAdminUnlockTime() Returns the timestamp for the last time the SecretStore administrator unlocked the SecretStore.
int	getNumLockedSecrets() Returns the number of locked secrets in SecretStore.
int	getNumSecrets() Returns the number of secrets in SecretStore.
Secret	getSecret(String id) Returns a Secret with the specified id.
Secret	getSecret(String id, boolean useMasterPassword) Returns a Secret object with the specified id.
Secret[]	getSecrets(int flags, String filter, int maxLen, boolean useMasterPassword) Returns a Secret object with the specified id.
byte	getServerCryptoStrength() Returns the server's crypto strength.
int	getServerVersion() Returns the server's SecretStore version.
void	getServiceInfo() Obtains SecretStore Service Information.
void	getServiceInfo(int flags) Obtains SecretStore Service Information.
int	getStatus() Returns the status flags for SecretStore.
int	hashCode()
void	removeSecretStore() Removes this object's SecretStore.
void	removeSecretStore(int flags) Removes this object's SecretStore.
void	setMasterPassword(char[] masterPword) Sets the master password for this SecretStore.
int	sync(SecretStore targetStore) Synchronizes this object, sourceStore, with the targetStore.
int	sync(SecretStore targetStore, int flags, String filter, int maxLen) Synchronizes this object, sourceStore, with the targetStore.
String	toString() Returns a string representation of this object.
void	unlockSecretStore() Unlocks this object's SecretStore by using the Master Password.
void	unlockSecretStore(int flags) Unlocks this object's SecretStore using the Master Password.
void	unlockSecretStore(int flags, char[] ndsPassword) Unlocks this object's SecretStore.
void	unsetMasterPassword() Unsets the master password.
void	update(SecretStore targetStore) Updates targetStore with secrets from the SecretStore represented by this SecretStore object.
void	update(SecretStore targetStore, int flags, String filter, int maxLen) Updates targetStore with secrets from the SecretStore represented by this SecretStore object.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

CALLER_DN

public static final String CALLER_DN

A property that specifies the distinguished name of the user that is requesting SecretStore operations. This may be different than the property \"com.novell.sso.userdn\". An example is when the admin is querying information about a user's SecretStore. The value of this constant is "com.novell.sso.callerdn".

HANDLE

public static final String HANDLE

An environment property that specifies a handle. This property may or may not be required by every implementation. See the implementation documentation for details. The value of this constant is "com.novell.sso.handle".

SECRET_STORE

public static final String SECRET_STORE

An environment property that specifies the class name of the SecretStore implementation that will be loaded and used. This property is always required. The value of this constant is "com.novell.sso.secretstore".

SERVER_DN

public static final String SERVER_DN

A property that specifies the distinguished name of the server that is being used for SecretStore operations. The value of this constant is "com.novell.sso.serverdn".

TREE

public static final String TREE

An environment property that specifies the tree in which the SecretStore server resides. This property may not be required by every implementation. See the implementation documentation for details. The value of this constant is "com.novell.sso.tree".

TARGET_DN

public static final String TARGET_DN

An environment property that specifies the distinguished name of the object for which SecretStore operations will be made. This property may not be required by every implementation. See the implementation documentation for details. The value of this constant is "com.novell.sso.targetdn".

Since:

3.2

USER_DN

public static final String USER_DN

Deprecated. This has been replaced by TARGET_DN because the target object can be of any class.

An environment property that specifies the distinguished name of the user for which SecretStore operations will be made. This property may not be required by every implementation. See the implementation documentation for details. The value of this constant has been changed to "com.novell.sso.targetdn" as of version 3.2.

Method Detail

getInstance

public static final SecretStore getInstance(Hashtable env)
                                     throws ClassNotFoundException,
                                            IllegalArgumentException,
                                            SSException

Returns a SecretStore instance based on the Hastable environment that is passed in. The environment properties specify the behavior.

The property SECRET_STORE determines which implementation of SecretStore will loaded and used. Actual SecretStore implementations may require additional information in the form of environment properties. Any additional properties are passed in via the env parameter.

The SecretStore environment is immutable. In order to change the environment it is necessary to obtain a new SecretStore instance and pass in the new environment.

Example of obtaining a SecretStore instance (using JNDISecretStore implementation):

 //Authenticating
 LdapContext initial = new InitialLdapContext(jndiEnv, null);

 //Getting LdapContext
 LdapContext ctx = (LdapContext)initial.lookup("cn=test,o=novell");

 //Forming the environment properties
 Hashtable env = new Hashtable();
 env.put(SecretStore.SECRET_STORE, "com.novell.security.sso.ldap.jndi.JNDISecretStore");
 env.put(SecretStore.USER_DN, "cn=test,o=novell");
 env.put(SecretStore.HANDLE, ctx);
 SecretStore store;

 //Creating the SecretStore
 try
 {
   store = SecretStore.getInstance(env);
 }
 catch(ClassNotFoundException e)
 {
   System.out.println(e.getMessage());
   e.printStackTrace();
 }

Parameters:

env - The Hashtable containing the environment properties.

Returns:

A SecretStore object.

Throws:

ClassNotFoundException - If the class specified by the SECRET_STORE property was not able to be loaded.

IllegalArgumentException - If the class specified by the SECRET_STORE property does not properly inherit from this class.

SSException - If a SSException occurred.

getClientCryptoStrength

public final byte getClientCryptoStrength()
                                   throws SSException

Returns the client's crypto strength. This method will result in a call to getServiceInfo if this SecretStore instance has not been initialized yet.

Possible return values:

SSInfo.NSSS_CRYPTO_DOMESTIC_ENGINE

SSInfo.NSSS_CRYPTO_EXPORT_ENGINE

SSInfo.NSSS_CRYPTO_UNDETERMINED_ENGINE

Returns:

The client crypto strength.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

SSPermission

getClientVersion

public final int getClientVersion()
                           throws SSException

Returns the client's SecretStore version. This method will result in a call to getServiceInfo() if this SecretStore instance has not been initialized yet.

Returns:

The client version.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

SSPermission

getEnumBuffLen

public final int getEnumBuffLen()
                         throws SSException

Returns the enumeration buffer length. This is the buffer size that would required by the enumerate operation if it were called. This method is only provided for completness since this API automatically allocates the required buffer. This method will result in a call to getServiceInfo() if this SecretStore instance has not been initialized yet.

Returns:

The enumeration buffer length.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

SSPermission

getEnvironmentProperty

public final Object getEnvironmentProperty(String key)

Used to obtain information about environment properties and to provide a standard way for implementations to pass back information. Some properties may not have been set if a call to getServiceInfo() has not been made yet. This method will not result in a call to getServiceInfo().

Parameters:

key - The key.

Returns:

The value. May be null if the key does not exist in the environment properties.

getHint

public final char[] getHint()
                     throws SSException

Returns the SecretStore's hint for the master password. This method will result in a call to getServiceInfo() if this SecretStore instance has not been initialized yet.

Returns:

The hint.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

commitMasterPasswordChange(int flags, char[] passhint), SSPermission

getLastAdminUnlockDn

public final String getLastAdminUnlockDn()
                                  throws SSException

Returns the distinguished name of the last SecretStore administrator that unlocked the SecretStore. This method will result in a call to getServiceInfo() if this SecretStore instance has not been initialized yet.
NOTE: The return value may be empty if the SecretStore has never been unlocked by a SecretStore administrator.

Returns:

The distinguished name of the last SecretStore administrator that unlocked the SecretStore.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

Since:

3.02

getLastAdminUnlockTime

public final Date getLastAdminUnlockTime()
                                  throws SSException

Returns the timestamp for the last time the SecretStore administrator unlocked the SecretStore. This method will result in a call to getServiceInfo() if this SecretStore instance has not been initialized yet.
NOTE: The return value may be a Date with a time value of 0 if the SecretStore has never been unlocked by a SecretStore administrator.

Returns:

The timestamp of the last time the SecretStore admin unlocked the SecretStore.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

Since:

3.02

setMasterPassword

public final void setMasterPassword(char[] masterPword)

Sets the master password for this SecretStore. This method does not result in the change to be made in SecretStore. In order for the change to be persistent, a call must be made to commitMasterPasswordChange().

This method exists for applications to be able to unlock SecretStore and also to be able to read secrets using the master password without having to persistently set the master password every time.

Parameters:

masterPword - The new master password for this SecretStore.

See Also:

unsetMasterPassword(), commitMasterPasswordChange(int flags, char[] passhint)

getNumLockedSecrets

public final int getNumLockedSecrets()
                              throws SSException

Returns the number of locked secrets in SecretStore. This method will result in a call to getServiceInfo() if this SecretStore instance has not been initialized yet.

Returns:

The number of locked secrets in SecretStore.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

SSPermission

getNumSecrets

public final int getNumSecrets()
                        throws SSException

Returns the number of secrets in SecretStore. This method will result in a call to getServiceInfo() if this SecretStore instance has not been initialized yet.

Returns:

The number of secrets in SecretStore.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

SSPermission

getSecret

public final Secret getSecret(String id)

Returns a Secret with the specified id. makes a call to getSecret(String id, boolean useMasterPassword) with a value of false for the useMasterPassword parameter.

Parameters:

id - The secret identifier.

Returns:

The new secret.

See Also:

getSecret(String id, boolean useMasterPassword)

getSecret

public Secret getSecret(String id,
                        boolean useMasterPassword)

Returns a Secret object with the specified id. Note that the id may not be null nor empty and may not contain a '*' character. Use this method to specify if the generated secret should use the master password for its enhanced protection password. Secrets constructed in this manner share the same context.

In the case that the master password is changed after Secrets are generated in this manner, these Secrets have a reference to the SecretStore's master password and so the new value will be accessible to them automatically.

Parameters:

id - The secret identifier.

useMasterPassword - Value that determines whether or not to use the master password for this SecretStore as the enhanced protection password for the generated secret.

Returns:

The new secret.

Throws:

IllegalArgumentException - if the identifier is null, empty, or contains a '*' character.

getSecrets

public Secret[] getSecrets(int flags,
                           String filter,
                           int maxLen,
                           boolean useMasterPassword)
                    throws SSException

Returns a Secret object with the specified id. Use this method to specify if the generated secret should use the master password for its enhanced protection password.

In the case that the master password is changed after Secrets are generated in this manner, these Secrets have a reference to the SecretStore's master password and so the new value will be accessible to them automatically.

Possible flags:

None currently defined. Parameter provided for future compatibility.

Parameters:

flags - The flags.

filter - The filter.

maxLen - The max length.

useMasterPassword - Value that determines whether or not to use the master password for this SecretStore as the enhanced protection password for the generated secret.

Returns:

The new secret.

Throws:

SSException - If a SSException occurred.

See Also:

getSecret(String id)

getServerCryptoStrength

public final byte getServerCryptoStrength()
                                   throws SSException

Returns the server's crypto strength. This method will result in a call to getServiceInfo() if this SecretStore instance has not been initialized yet.

Possible return values:

SSInfo.NSSS_CRYPTO_DOMESTIC_ENGINE

SSInfo.NSSS_CRYPTO_EXPORT_ENGINE

SSInfo.NSSS_CRYPTO_UNDETERMINED_ENGINE

Returns:

The server crypto strength.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

SSPermission

getServerVersion

public final int getServerVersion()
                           throws SSException

Returns the server's SecretStore version. This method will result in a call to getServiceInfo() if this SecretStore instance has not been initialized yet.

Returns:

Returns the server's version.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

SSPermission

getServiceInfo

public final void getServiceInfo()
                          throws SSException

Obtains SecretStore Service Information. It is usually not necessary to make a call to this method directly. The accessor methods of this class make a call to this method automatically the first time one of them is called. Subsequent calls to accessor methods will not result in the information being retrieved from SecretStore again. Making a direct call to this method will result in the information in this object to be retrieved again from SecretStore. This method makes a call to getServiceInfo(int flags) with a flags value of 0.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

getServiceInfo(int flags), SSPermission

getServiceInfo

public final void getServiceInfo(int flags)
                          throws SSException

Obtains SecretStore Service Information. It is usually not necessary to make a call to this method directly. The accessor methods of this class make a call to this method automatically the first time one of them is called. Subsequent calls to accessor methods will not result in the information being retrieved from SecretStore again. Making a direct call to this method will result in the information in this object to be retrieved again from SecretStore.

Possible flags:

SSInfo.NSSS_REPAIR_THE_STORE_F

Parameters:

flags - The flags for this operation.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

getServiceInfo(), SSPermission

getStatus

public final int getStatus()
                    throws SSException

Returns the status flags for SecretStore. This method will result in a call to getServiceInfo() if this SecretStore instance has not been initialized yet. Compare the value that is returned by this method with the flags that are associated with a SecretStore's status. Do this by using a statement like:

 int stat = store.getStatus();
 if ( (stat & SSInfo.NSSS_EP_MASTER_PWORD_PRESENT_F) == SSInfo.NSSS_EP_MASTER_PWORD_PRESENT_F)
 {
   System.out.println("There is a master password on the SecretStore");
 }
 else if ( (stat & SSInfo.NSSS_MP_NOT_ALLOWED_F) == SSInfo.NSSS_MP_NOT_ALLOWED_F)
 {
   System.out.println("Master Password has been disabled by the Administrator");
 }

Possible return values:

SSInfo.NSSS_ADMIN_UNLOCKED_F

SSInfo.NSSS_EP_MASTER_PWORD_PRESENT_F

SSInfo.NSSS_MP_NOT_ALLOWED_F

SSInfo.NSSS_STORE_NOT_SYNCED_F

SSInfo.NSSS_SECRET_LOCKED_F

Returns:

The status.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

SSPermission

commitMasterPasswordChange

public final void commitMasterPasswordChange()
                                      throws SSException

Commits the master password change in SecretStore. Makes a call to commitMasterPasswordChange(int flags, char[] passhint) with a flags value of 0 and an empty character array for passhint.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies admin access to SecretStore.

See Also:

setMasterPassword(char[] masterPword), unsetMasterPassword(), SSPermission

commitMasterPasswordChange

public final void commitMasterPasswordChange(int flags)
                                      throws SSException

Commits the master password change in SecretStore. Makes a call to commitMasterPasswordChange(int flags, char[] passhint) with an empty character array for passhint.

Possible flags:

None currently defined. Parameter provided for future compatibility.

Parameters:

flags - The flags for this operation.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies admin access to SecretStore.

See Also:

setMasterPassword(char[] masterPword), unsetMasterPassword(), SSPermission

commitMasterPasswordChange

public final void commitMasterPasswordChange(int flags,
                                             char[] passhint)
                                      throws SSException

Commits the master password change in SecretStore.

Possible flags:

None currently defined. Parameter provided for future compatibility.

Parameters:

flags - The flags for this operation

passhint - The hint associated with the master password.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies admin access to SecretStore.

See Also:

setMasterPassword(char[] masterPword), unsetMasterPassword(), SSPermission

enumerateSecrets

public final StringTokenizer enumerateSecrets()
                                       throws SSException

Enumerates the secrets in SecretStore by returning a StringTokenizer containing the secret identifiers in SecretStore separated by *. This method calls enumerateSecrets(int flags, String filter, int maxLen) by using the maximum possible value for maxLen: SSInfo.NSSS_JUMBO_ENUM_BUF_LEN. This method also does not use a filter (passes an empty string).

Returns:

The StringTokenizer of the secret identifiers in SecretStore.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

enumerateSecrets(int flags, String filter, int maxLen), getSecrets(int flags, String filter, int maxLen, boolean useMasterPassword), SSPermission

enumerateSecrets

public final StringTokenizer enumerateSecrets(int flags,
                                              String filter)
                                       throws SSException

Enumerates the secrets in SecretStore by returning a StringTokenizer containing the secret identifiers in SecretStore separated by *. This method calls enumerateSecrets(int flags, String filter, int maxLen) by using the maximum possible value for maxLen: SSInfo.NSSS_JUMBO_ENUM_BUF_LEN.

Possible flags:

None currently defined. Parameter provided for future compatibility.

Parameters:

flags - Possible flags for this operation.

filter - A string that filters the secret identifiers that are returned.

Returns:

The StringTokenizer of the secret identifiers in SecretStore.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

enumerateSecrets(int flags, String filter, int maxLen), getSecrets(int flags, String filter, int maxLen, boolean useMasterPassword), SSPermission

enumerateSecrets

public final StringTokenizer enumerateSecrets(int flags,
                                              String filter,
                                              int maxLen)
                                       throws SSException

Enumerates the secrets in SecretStore by returning a StringTokenizer containing the secret identifiers in SecretStore separated by *.

Possible flags:

None currently defined. Parameter provided for future compatibility.

Parameters:

flags - Possible flags for this operation.

filter - A string that filters the secret identifiers that are returned.

maxLen - The maximum buffer that will be returned in the StringTokenizer.

Returns:

The StringTokenizer of the secret identifiers in SecretStore.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read access to SecretStore.

See Also:

enumerateSecrets(int flags, String filter), getSecrets(int flags, String filter, int maxLen, boolean useMasterPassword), SSPermission

removeSecretStore

public final void removeSecretStore()
                             throws SSException

Removes this object's SecretStore. Makes a call to removeSecretStore(int flags) with a flags value of 0.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies admin access to SecretStore.

See Also:

removeSecretStore(int flags), SSPermission

removeSecretStore

public final void removeSecretStore(int flags)
                             throws SSException

Removes this object's SecretStore.

Possible flags:

None currently defined. Parameter provided for future compatibility.

Parameters:

flags - The flags for this operation.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies admin access to SecretStore.

See Also:

removeSecretStore(), SSPermission

sync

public final int sync(SecretStore targetStore)
               throws SSException

Synchronizes this object, sourceStore, with the targetStore. This is only a one-way synchronization. This synchronization is done secret by secret according to the secret identifier. If the sourceStore has a secret that the targetStore does not have, then the targetStore is updated with that secret. If the sourceStore has a secret that the targetStore has, then the last modified timestamp for both secrets is examined. If the secret in the sourceStore has a timestamp that is more recent than the timestamp for the secret in the targetStore, then the secret in the targetStore is updated with the secret in the sourceStore. In the case that the timestamp for a secret in the targetStore is either less recent or equal to the timestamp for a corresponding secret in the targetStore, no update will occurr to that secret. In the case that the targetStore has a secret that is not in the sourceStore, no update will occurr to that secret.

It will be attempted to synchronize each secret. In the case that a SSException is thrown while attempting to sync a secret the exception will be examined. If there is a root exception the SSException will be passed back to the application immediately. If there is no root exception it will be saved and the sync will continue for the remaining secrets. Once the sync for each secret is attempted the last SSException (if one occurred) will be thrown. The identifier for the last secret that failed to sync will be passed back in the message.

NOTE: This will only work for secrets that are not locked and that do not have an enhanced protection password associated with them. It is required to manually sync secrets that are protected with an enhanced protection password or that are locked.

Makes a call to sync(SecretStore targetStore, int flags, String filter, int maxLen) with the defaults - 0 for flags, empty string for filter, and SSInfo.NSSS_JUMBO_ENUM_BUF_LEN for maxLen.

Parameters:

targetStore - The SecretStore that will be synchronized with.

Returns:

The number of secrets that were successfully modified.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read/write access to SecretStore.

See Also:

enumerateSecrets(int flags, String filter, int maxLen), sync(SecretStore targetStore, int flags, String filter, int maxLen), Secret.sync(Secret secret), SSPermission

sync

public int sync(SecretStore targetStore,
                int flags,
                String filter,
                int maxLen)
         throws SSException

Synchronizes this object, sourceStore, with the targetStore. This is only a one-way synchronization. This synchronization is done secret by secret according to the secret identifier. If the sourceStore has a secret that the targetStore does not have, then the targetStore is updated with that secret. If the sourceStore has a secret that the targetStore has, then the last modified timestamp for both secrets is examined. If the secret in the sourceStore has a timestamp that is more recent than the timestamp for the secret in the targetStore, then the secret in the targetStore is updated with the secret in the sourceStore. In the case that the timestamp for a secret in the targetStore is either less recent or equal to the timestamp for a corresponding secret in the targetStore, no update will occurr to that secret. In the case that the targetStore has a secret that is not in the sourceStore, no update will occurr to that secret. The other parameters can be used to limit the secrets that are to be synchronized.

It will be attempted to synchronize each secret. In the case that a SSException is thrown while attempting to sync a secret the exception will be examined. If there is a root exception the SSException will be passed back to the application immediately. If there is no root exception it will be saved and the sync will continue for the remaining secrets. Once the sync for each secret is attempted the last SSException (if one occurred) will be thrown. The identifier for the last secret that failed to sync will be passed back in the message.

NOTE: This will only work for secrets that are not locked and that do not have an enhanced protection password associated with them. It is required to manually sync secrets that are protected with an enhanced protection password or that are locked.

Possible flags:

None currently defined. Parameter provided for future compatibility.

Parameters:

targetStore - The SecretStore that will be synchronized with.

flags - The flags for the getSecrets method.

filter - The filter for the getSecrets method.

maxLen - The maxLen for the getSecrets method.

Returns:

The number of secrets that were successfully modified.

Throws:

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read/write access to SecretStore.

SSException - If a SSException occurred.

See Also:

enumerateSecrets(int flags, String filter, int maxLen), sync(SecretStore targetStore), Secret.sync(Secret secret), SSPermission

toString

public String toString()

Returns a string representation of this object. Constructed using the distinguished name of the object that owns this SecretStore (if one exists) and the name of this class.

Overrides:

toString in class Object

Returns:

String - A string representation of this object.

unlockSecretStore

public final void unlockSecretStore()
                             throws IllegalArgumentException,
                                    SSException

Unlocks this object's SecretStore by using the Master Password. Makes a call to unlockSecretStore(int flags) with a flags value of 0.

Throws:

IllegalArgumentException - If the Master Password was not set.

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies admin access to SecretStore.

See Also:

unlockSecretStore(int flags), unlockSecretStore(int flags, char[] ndsPassword), SSPermission

unlockSecretStore

public final void unlockSecretStore(int flags)
                             throws IllegalArgumentException,
                                    SSException

Unlocks this object's SecretStore using the Master Password.

Possible flags:

None currently defined. Parameter provided for future compatibility.

Parameters:

flags - The flags for this operation.

Throws:

IllegalArgumentException - If the Master Password was not set.

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies admin access to SecretStore.

See Also:

unlockSecretStore(), unlockSecretStore(int flags, char[] ndsPassword), SSPermission

unlockSecretStore

public final void unlockSecretStore(int flags,
                                    char[] ndsPassword)
                             throws SSException

Unlocks this object's SecretStore. Use this method to use the previous NDS Password instead of the master password for SecretStore. Passing in SSInfo.NSSS_REMOVE_LOCK_FROM_STORE_F in flags parameter will result in all locked secrets in SecretStore being deleted. This allows the SecretStore to be unlocked without having to know the Master Password or the previous NDS password. The drawback is that any locked secrets are deleted and cannot be recovered.

Possible flags:

SSInfo.NSSS_REMOVE_LOCK_FROM_STORE_F

Parameters:

flags - The flags for this operation.

ndsPassword - The previous eDirectory password.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies admin access to SecretStore.

See Also:

unlockSecretStore(), unlockSecretStore(int flags), SSPermission

unsetMasterPassword

public final void unsetMasterPassword()

Unsets the master password. No exception will occur if this method is called when the master password was never set in the first place. This method will not clear the master password persistently. In order to do this, the SecretStore must be removed and then initialized back. It is possible to overwrite an existing master password with a call to commitMasterPasswordChange(int flags, char[] passhint).

See Also:

setMasterPassword(char[] masterPword), commitMasterPasswordChange(int flags, char[] passhint)

update

public final void update(SecretStore targetStore)
                  throws SSException

Updates targetStore with secrets from the SecretStore represented by this SecretStore object. The getSecrets method of this object is first called and then the Secret array is used to update the target SecretStore.

It will be attempted to update each secret. In the case that a SSException is thrown while attempting to update a secret the exception will be examined. If there is a root exception the SSException will be passed back to the application immediately. If there is no root exception it will be saved and the update will continue for the remaining secrets. Once the update for each secret is attempted the last SSException (if one occurred) will be thrown. The identifier for the last secret that failed to update will be passed back in the message.

NOTE: This will only work for secrets that are not locked and that do not have an enhanced protection password associated with them. It is required to manually update secrets that are protected with an enhanced protection password or that are locked.

Makes a call to update(SecretStore targetStore, int flags, String filter, int maxLen) with the defaults - 0 for flags, empty string for filter, and SSInfo.NSSS_JUMBO_ENUM_BUF_LEN for maxLen.

Parameters:

targetStore - The SecretStore that will be updated.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read/write access to SecretStore.

See Also:

enumerateSecrets(int flags, String filter, int maxLen), update(SecretStore targetStore, int flags, String filter, int maxLen), Secret.update(Secret secret), SSPermission

update

public void update(SecretStore targetStore,
                   int flags,
                   String filter,
                   int maxLen)
            throws SSException

Updates targetStore with secrets from the SecretStore represented by this SecretStore object. The getSecrets method of this object is first called and then the Secret array is used to update the target SecretStore. The other parameters can be used to limit the secrets that are to be updated.

It will be attempted to update each secret. In the case that a SSException is thrown while attempting to update a secret the exception will be examined. If there is a root exception the SSException will be passed back to the application immediately. If there is no root exception it will be saved and the update will continue for the remaining secrets. Once the update for each secret is attempted the last SSException (if one occurred) will be thrown. The identifier for the last secret that failed to update will be passed back in the message.

NOTE: This will only work for secrets that are not locked and that do not have an enhanced protection password associated with them. It is required to manually update secrets that are protected with an enhanced protection password or that are locked.

Possible flags:

None currently defined. Parameter provided for future compatibility.

Parameters:

targetStore - The SecretStore that will be updated.

flags - The flags for the getSecrets method.

filter - The filter for the getSecrets method.

maxLen - The maxLen for the getSecrets method.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies read/write access to SecretStore.

See Also:

enumerateSecrets(int flags, String filter, int maxLen), update(SecretStore targetStore), Secret.update(Secret secret), SSPermission

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object