com.novell.security.sso
Class Secret

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

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

JNDISecret, NCPSecret, SharedSecret

public abstract class Secret

extends Object

implements Serializable

An abstract class that represents a secret in SecretStore. Actual instances of this class may be created by using the SecretStore.getSecret(String id) method.

In the past, to write a secret with collision detection enabled, it was necessary to first call the create() method and then the setValue(byte[]) method. This resulted in two calls over the network per secret.

To be able to write a secret with only one call over the network, it was necessary to disable collision detection by calling setValue with the SSInfo.NSSO_CREATE_ID_F flag. This was a faster alternative, but it wasn't necessarily the best because it could result in secrets being overwritten.

As of SecretStore 3.2, the functionality of the create() method was combined with the setValue(byte[]) method. Secret ID collision detection is still supported with the new SSInfo.NSSS_CHK_SID_FOR_COLLISION_F flag. This combination allows collision detection to be enabled without the performance hit of two calls over the network. The methods isCheckingSecretIDCollision() and setCheckingSecretIDCollision(boolean) have been added to support this new flag.

This kit deprecated the create() method as of 3.1 in order to phase in the new functionality. The SSInfo.NSSO_CREATE_ID_F flag is now assumed, so it has been deprecated also. Both the getAutoCreateIDPolicy() method and the setAutoCreateIDPolicy(boolean) method that automatically passed in this flag have been deprecated as well. However, to support SecretStore servers that don't support the 3.2 functionality yet, this kit still calls the create() method inside of the setValue(byte[]) method when the SSInfo.NSSS_CHK_SID_FOR_COLLISION_F flag is defined. This is done because SecretStore 3.2 hasn't been released yet. After SecretStore 3.2 is released, this kit will only support servers at least SecretStore 3.2 in order to take advantage of the performance improvements.

This class relies upon SSPermission for access control.

Since:

2.1

Version:

3.2

Author:

Steve Kinser

See Also:

SecretStore.getSecret(String id), SSPermission, Serialized Form

Method Summary

void	create() Deprecated. As of 3.10, directly call setValue(byte[] value) with the CheckingSecretIDCollision flag set to true to gain the same behavior.
void	create(int flags) Deprecated. As of 3.10, directly call setValue(byte[] value) with the CheckingSecretIDCollision flag set to true to gain the same behavior.
void	delete() Removes this secret from the SecretStore.
void	delete(int flags) Removes this secret from the SecretStore.
boolean	equals(Object obj) Determines whether this secret equals another object.
boolean	exists() Determines if this secret exists in SecretStore.
boolean	exists(int flags) Determines if this secret exists in SecretStore.
Date	getAccessTime() Returns a Date object representing when this secret was last accessed in SecretStore.
boolean	getAutoCreateIDPolicy() Deprecated. As of version 3.10
Date	getCreateTime() Returns a Date object representing when this secret was created in SecretStore.
boolean	getEnhancedProtectedPolicy() Deprecated. As of version 3.02, replaced by isEnhancedProtected().
Date	getModifyTime() Returns a Date object representing when this secret was last modified in SecretStore.
int	getStatus() Returns the secret's status.
byte[]	getValue() Returns the secret value located in this Secret object.
int	hashCode() Returns a hash code value for this object.
boolean	isCheckingSecretIDCollision() Returns a value that specifies if the setValue method is checking for a secret ID collision.
boolean	isEnhancedProtected() Returns a flag that specifies if this secret is enhanced protected.
boolean	isEnhancedProtectedWithPassword() Returns a flag that specifies if this secret is protected with an enhanced protection password.
void	read() Read this Secret from SecretStore.
void	read(int flags) Read this Secret from SecretStore.
void	setAutoCreateIDPolicy(boolean policy) Deprecated. As of version 3.10
void	setCheckingSecretIDCollision(boolean policy) Sets the checking secret ID collision policy for this secret.
void	setEnhancedProtected(boolean policy) Sets the enhanced protected property of the secret.
void	setEnhancedProtectedPolicy(boolean policy) Deprecated. As of version 3.02, replaced by setEnhancedProtected(boolean policy).
void	setEnhancedProtectionPassword(char[] erPass) Sets the optional enhanced protection password for this secret.
void	setValue(byte[] value) Set the secret value of this secret in SecretStore.
void	setValue(byte[] value, int flags) Set the secret value of this secret in SecretStore.
boolean	sync(Secret targetSecret) Synchronizes this object, sourceSecret, with the targetSecret.
String	toString() Returns a string representation of this object.
void	unsetEnhancedProtectionPassword() Unsets the optional enhanced protection password for this secret.
void	update(Secret targetSecret) Updates the targetSecret with this object's secret value.
void	update(Secret targetSecret, int flags) Updates the targetSecret with this object's secret value.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

create

public final void create()
                  throws SSException

Deprecated. As of 3.10, directly call setValue(byte[] value) with the CheckingSecretIDCollision flag set to true to gain the same behavior.

This method has been deprecated. The behavior of this method and of the setValue(byte[], int) method has been combined into one method, the setValue(byte[], int) method. To set the value while checking for secret ID collisions, pass in the SSInfo.NSSS_CHK_SID_FOR_COLLISION_F flag to the setValue(byte[], int) call.

To support backwards compatibility, this method calls setCheckingSecretIDCollision(boolean) with a value of true.

Throws:

SSException - If a SSException occurred.

See Also:

setValue(byte[]), setCheckingSecretIDCollision(boolean)

create

public final void create(int flags)
                  throws SSException

Deprecated. As of 3.10, directly call setValue(byte[] value) with the CheckingSecretIDCollision flag set to true to gain the same behavior.

This method has been deprecated. The behavior of this method and of the setValue(byte[], int) method has been combined into one method, the setValue(byte[], int) method. To set the value while checking for secret ID collisions, pass in the SSInfo.NSSS_CHK_SID_FOR_COLLISION_F flag to the setValue(byte[], int) call.

To support backwards compatibility, this method calls setCheckingSecretIDCollision(boolean) with a value of true.

Throws:

SSException - If a SSException occurred.

See Also:

setValue(byte[]), setCheckingSecretIDCollision(boolean)

delete

public final void delete()
                  throws SSException

Removes this secret from the SecretStore. This method calls delete(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 write access to this secret.

See Also:

delete(int flags), SSPermission

delete

public final void delete(int flags)
                  throws SSException

Removes this secret from the SecretStore.

Possible flags:

None currently defined. Parameter provided for future compatibility.

Parameters:

flags - Possible flags for this operation.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies write access to this secret.

See Also:

delete(), SSPermission

equals

public boolean equals(Object obj)

Determines whether this secret equals another object. If the other object is not a Secret then false is returned. If it is, then the value is determined by the secrets' identifier. If they are equal true is returned, otherwise false is returned.

Overrides:

equals in class Object

Parameters:

obj - The object with which to compare this secret.

Returns:

true if the secrets' id and user match, false if not.

exists

public boolean exists()
               throws SSException

Determines if this secret exists in SecretStore. Note that a call to this method will always result in a call to SecretStore. This method calls the method exists(int flags) with a flags value of 0.

Returns:

true if the secret exists in SecretStore, false if not.

Throws:

SSException - If a SSException occurred.

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

See Also:

SSPermission

exists

public boolean exists(int flags)
               throws SSException

Determines if this secret exists in SecretStore. Note that a call to this method will always result in a call to SecretStore. See the read(int flags) method for information about the possible flags that may be passed in.

Parameters:

flags - Possible flags for this operation.

Returns:

true if the secret exists in SecretStore, false if not.

Throws:

SSException - If a SSException occurred.

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

See Also:

SSPermission

getAccessTime

public Date getAccessTime()
                   throws SSException

Returns a Date object representing when this secret was last accessed in SecretStore.

Returns:

A Date object representing when this secret was last accessed in SecretStore.

Throws:

SSException - If a SSException occurred.

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

See Also:

getCreateTime(), getModifyTime(), SSPermission

getAutoCreateIDPolicy

public boolean getAutoCreateIDPolicy()

Deprecated. As of version 3.10

This method has been depreciated. As of 3.10, the secret will automatically be created by the setValue(byte[]) method, so this flag is no longer needed.

Returns:

the auto create id policy.

See Also:

isCheckingSecretIDCollision()

getCreateTime

public Date getCreateTime()
                   throws SSException

Returns a Date object representing when this secret was created in SecretStore.

Returns:

A Date object representing when this secret was created in SecretStore.

Throws:

SSException - If a SSException occurred.

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

See Also:

getAccessTime(), getModifyTime(), SSPermission

getEnhancedProtectedPolicy

public boolean getEnhancedProtectedPolicy()
                                   throws SSException

Deprecated. As of version 3.02, replaced by isEnhancedProtected().

Returns the enhanced protection policy.

Returns:

The enhanced protection policy.

Throws:

SSException - If a SSException occurred.

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

See Also:

isEnhancedProtected(), setEnhancedProtected(boolean policy)

getModifyTime

public Date getModifyTime()
                   throws SSException

Returns a Date object representing when this secret was last modified in SecretStore.

Returns:

A Date object representing when this secret was last modified in SecretStore.

Throws:

SSException - If a SSException occurred.

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

See Also:

getAccessTime(), getCreateTime(), SSPermission

getStatus

public int getStatus()
              throws SSException

Returns the secret's status. Compare the value that is returned by this method with the flags that are associated with a secret's status. Do this by using a statement like:

 int stat = secret.getStatus();
 if ( (stat & SSInfo.NSSS_SECRET_NOT_INITIALIZED_F) == SSInfo.NSSS_SECRET_NOT_INITIALIZED_F)
 {
   System.out.println("Secret identifier found, but no secret value exists");
 }
 else if ( (stat & SSInfo.NSSS_SECRET_LOCKED_F) == SSInfo.NSSS_SECRET_LOCKED_F)
 {
   System.out.println("This secret has been locked!");
 }

Possible return values:

SSInfo.NSSS_SECRET_LOCKED_F

SSInfo.NSSS_SECRET_NOT_INITIALIZED_F

SSInfo.NSSS_ENHANCED_PROTECT_INFO_F

SSInfo.NSSS_STORE_NOT_SYNCED_F

SSInfo.NSSS_EP_PWORD_PRESENT_F

SSInfo.NSSS_ADMIN_LAST_MOD_F

SSInfo.NSSS_MP_NOT_ALLOWED_F

Returns:

The secret's status.

Throws:

SSException - If a SSException occurred.

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

See Also:

SSPermission

getValue

public byte[] getValue()
                throws SSException

Returns the secret value located in this Secret object. The default behavior of this method is to return the secret value that was last retrieved with a call to the read method. In order to refresh the latest information about this secret in SecretStore call the read() method explicitly.

NOTE: If getValue or read have not been called previously then a call to this method will result in a call to read with a default flag value of 0, after which the secret value will be returned.

Returns:

A byte array containing the secret value.

Throws:

SSException - If a SSException occurred.

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

See Also:

read(int flags), setValue(byte[] value), SSPermission

hashCode

public int hashCode()

Returns a hash code value for this object. Constructed using the hash code of the combination of the secret identifier.

Overrides:

hashCode in class Object

Returns:

A hash code value for this object.

isCheckingSecretIDCollision

public boolean isCheckingSecretIDCollision()

Returns a value that specifies if the setValue method is checking for a secret ID collision. In other words, name collision is enabled if this flag is true.

Returns:

true if the setValue(byte[]) method is checking for secret ID collisions and false if not.

Since:

3.1

isEnhancedProtected

public boolean isEnhancedProtected()
                            throws SSException

Returns a flag that specifies if this secret is enhanced protected.

Returns:

true if this secret is enhanced protected and false if not.

Throws:

SSException - If a SSException occurred.

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

Since:

3.02

See Also:

setEnhancedProtected(boolean policy)

isEnhancedProtectedWithPassword

public boolean isEnhancedProtectedWithPassword()
                                        throws SSException

Returns a flag that specifies if this secret is protected with an enhanced protection password.

Returns:

true if this secret is protected with an enhanced protection password and false if not.

Throws:

SSException - If a SSException occurred.

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

Since:

3.02

See Also:

setEnhancedProtectionPassword(char[] erPass)

read

public final void read()
                throws SSException

Read this Secret from SecretStore. Call this method in order to refresh this Secret object with the latest information about this secret in SecretStore. This method calls the method read(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 this secret.

See Also:

getValue(), SSPermission

read

public final void read(int flags)
                throws SSException

Read this Secret from SecretStore. Call this method in order to refresh this Secret object with the latest information about this secret in SecretStore.

NOTE: If this secret was created using the call SecretStore.getSecret(String id, boolean useMasterPassword) and true* was passed in for useMasterPassword, then the flag SSInfo.NSSS_EP_MASTER_PWORD_USED_F will automatically be set. If the enhanced protection password was set using the call setEnhancedProtectionPassword(char[] erPass), then the flag SSInfo.NSSS_EP_PASSWORD_USED_F will automatically be set.

Possible flags:

SSInfo.NSSS_REPAIR_THE_STORE_F

SSInfo.NSSS_EP_PASSWORD_USED_F

SSInfo.NSSS_EP_MASTER_PWORD_USED_F

Parameters:

flags - Possible 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 this secret.

See Also:

getValue(), SSPermission

setAutoCreateIDPolicy

public void setAutoCreateIDPolicy(boolean policy)

Deprecated. As of version 3.10

This method has been depreciated. As of 3.10, the secret will automatically be created by the setValue(byte[]) method, so this flag is no longer needed.

Parameters:

policy - the auto create id policy.

See Also:

setCheckingSecretIDCollision(boolean)

setCheckingSecretIDCollision

public void setCheckingSecretIDCollision(boolean policy)

Sets the checking secret ID collision policy for this secret. Setting this to true will cause the SSInfo.NSSS_CHK_SID_FOR_COLLISION_F flag to be automatically be passed in on the setValue(byte[]) call. Setting this to false will cause the flag to not be passed in automatically.

Parameters:

policy - the checking secretID collision policy.

Since:

3.1

setEnhancedProtected

public void setEnhancedProtected(boolean policy)

Sets the enhanced protected property of the secret. Setting this to true will cause the SSInfo.NSSS_ENHANCED_PROTECTION_F flag to be automatically passed in. Setting this to false will cause the SSInfo.NSSS_ENHANCED_PROTECTION_F, SSInfo.NSSS_EP_PASSWORD_USED_F, and SSInfo.NSSS_EP_MASTER_PWORD_USED_F flags to not be passed in automatically.

NOTE: For this change to take affect in SecretStore, setValue must be called.

Parameters:

policy - The policy that determines if this secret is enhanced protected.

Since:

3.02

See Also:

setValue(byte[] value), isEnhancedProtected()

setEnhancedProtectedPolicy

public void setEnhancedProtectedPolicy(boolean policy)

Deprecated. As of version 3.02, replaced by setEnhancedProtected(boolean policy).

Sets the enhanced protected property of the secret.

NOTE: For this change to take affect in SecretStore, setValue must be called.

Parameters:

policy - The policy that determines if this secret is enhanced protected.

See Also:

setValue(byte[] value), isEnhancedProtected()

setEnhancedProtectionPassword

public void setEnhancedProtectionPassword(char[] erPass)

Sets the optional enhanced protection password for this secret. The enhanced protection password is null by default. When an enhanced protection password is used that is not the master password for the SecretStore, two flags (SSInfo.NSSS_ENHANCED_PROTECTION_F and SSInfo.NSSS_EP_PASSWORD_USED_F) are automatically set for the caller when read is called. Although it is not necessary for the caller to also set these flags manually, it will not produce any undesirable results.

It is not required to have an enhanced protection password associated with a secret in order for the secret to have enhanced protection. In order to gain this behavior, call setEnhancedProtected(boolean policy) with a value of true. This will make this secret enhanced protected, but without an enhanced protection password.

NOTE: If it is desired to set an enhanced protected password for this secret, it is necessary to call this method before making a call to setValue or the change will not take affect. It is also required to call setValue after calling this method for the secret in SecretStore to be modified.

In order to verify that the enhanced protected password was set, use the status for this Secret object after setValue is called. This only applies to an enhanced protection password that is not the master password.

Parameters:

erPass - Specifies the enhanced protection password.

See Also:

setValue(byte[]), setEnhancedProtected(boolean)

setValue

public void setValue(byte[] value)
              throws SSException

Set the secret value of this secret in SecretStore. Makes a call to setValue(byte[] value, int flags) with a flags value of 0.

Parameters:

value - A byte array representing the secret value.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies write access to this secret.

See Also:

setValue(byte[] value, int flags), SSPermission

setValue

public void setValue(byte[] value,
                     int flags)
              throws SSException

Set the secret value of this secret in SecretStore. Calling this method without the SSInfo.NSSS_CHK_SID_FOR_COLLISION_F flag will result in name collision being disabled. In other words, this may cause an existing secret being overwritten by this secret. Enable name collision by passing in this flag.

It is possible to set more than one flag by using the following syntax:
(SSInfo.NSSS_CHK_SID_FOR_COLLISION_F | SSInfo.NSSS_ENHANCED_PROTECTION_F)
Any number of flags may be passed in this manner. Note that most of the flags associated with this method will be automatically passed in by calling certain methods of this class.

Possible Flags:

• SSInfo.NSSS_CHK_SID_FOR_COLLISION_F
• SSInfo.NSSS_ENHANCED_PROTECTION_F
• SSInfo.NSSS_EP_PASSWORD_USED_F
• SSInfo.NSSS_EP_MASTER_PWORD_USED_F

Parameters:

value - A byte array representing the secret value.

flags - Optional flags that can be passed in to modify behavior.

Throws:

SSException - If a SSException occurred.

SecurityException - If a security manager exists and its SecurityManager.checkPermission method denies write access to this secret.

See Also:

setValue(byte[] value), SSPermission

sync

public boolean sync(Secret targetSecret)
             throws SSException

Synchronizes this object, sourceSecret, with the targetSecret. Compares the last modified timestamp of the sourceSecret with the last modified timestamp of the targetSecret. The targetSecret will be updated if the timestamp for the sourceSecret is more recent; otherwise nothing occurs.

The created timestamp will be used in the case that the server for the sourceSecret has disabled the last modified timestamp. A timestamp value of 0 for the last modified timestamp is considered to mean that this behavior has been disabled by the server.

Parameters:

targetSecret - The secret that will be synchronized with.

Returns:

True if the targetSecret was updated, false if not.

Throws:

SSException - If a SSException occurred.

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

See Also:

SSPermission

toString

public String toString()

Returns a string representation of this object. Constructed using the secret identifier.

Overrides:

toString in class Object

Returns:

A string representation of the object.

unsetEnhancedProtectionPassword

public void unsetEnhancedProtectionPassword()

Unsets the optional enhanced protection password for this secret. Does not automatically set the enhanced protected policy to false.
NOTE: For the change in the enhanced protection password to take affect, it is required to call setValue after making a call to this method.

See Also:

setEnhancedProtectionPassword(char[] erPass)

update

public void update(Secret targetSecret)
            throws SSException

Updates the targetSecret with this object's secret value.

Parameters:

targetSecret - The target Secret.

Throws:

SSException - If a SSException occurred.

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

See Also:

SSPermission

update

public void update(Secret targetSecret,
                   int flags)
            throws SSException

Updates the targetSecret with this object's secret value.

Possible Flags:

• SSInfo.NSSS_CHK_SID_FOR_COLLISION_F
• SSInfo.NSSS_ENHANCED_PROTECTION_F
• SSInfo.NSSS_EP_PASSWORD_USED_F
• SSInfo.NSSS_EP_MASTER_PWORD_USED_F

Parameters:

targetSecret - The target Secret.

flags - The flags for this operation that are passed to the setValue method.

Throws:

SSException - If a SSException occurred.

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

See Also:

SSPermission