com.novell.security.sso
Class SharedSecret

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

All Implemented Interfaces:

Serializable

public class SharedSecret

extends Secret

A class that represents a shared secret. Shared secrets are secrets that are in a format that encourages the sharing of secrets by single sign on-enabling applications (SSO apps). Shared secrets that are written by one application will be able to be read by another application as long as each application uses the shared secret format. This class automates the task of conforming to this format so that developers of SSO apps can take advantage of the format without having to worry about any of the details. For example, all escaping and unescaping are automatically performed by this API. The shared secret format is provided below as a reference.

This class uses the SharedEntry class to represent the key/value pairs (shared secret entries) that make up the shared secret value.

In order to support all implementations, NCP and JNDI for example, this class wraps another secret. Thus, this class has an inheritance relationship as well as a composition relationship with the Secret class. Calls to this method are delegated to the wrapped secret. This class formats the data according to this specification before delegating the call. The wrapped secret type is determined by how an object of this class was created. The constructors that take a Secret object as a parameter will set that object as the wrapped secret. The constructors that take a SecretStore object will create a new Secret object by calling secretStore.getSecret(id) and then set that newly returned Secret as the wrapped Secret.

By definition, when modifying shared secrets you should only modify those entries that you directly depend on. In other words, if another SSO app is dependent on an entry that is in a shared secret that you use, you should not delete this entry when modifying other entries. In order to encourage this, two constructors have been added that allow you to instruct the constructor to automatically perform a read operation that will bring into memory all existing entries. The constructors without the isToAutoLoad parameter will call their corresponding constructors with the the isToAutoLoad parameter set to true. If you desire to delay the read operation you may pass in false for the isToAutoLoad parameter and then make the read call manually later.

Shared Secret Format Reference

A shared secret is a regular secret that follows a set of rules. A type, a name, and a set of key/value pairs make up a shared secret. The type and name of a shared secret combine to form the shared secret’s secret identifier and the set of key/value pairs make up the value. This format reserves certain characters that must be escaped when used outside of their scope.

Shared Secret Identifier

The identifier must be in the following format:

[type]:[name]

Where:

[type] is either "SS_App" or "SS_CredSet" depending on the shared secret type.
[name] is an arbitray name that the SSO app chooses.

The colon ‘:’ serves as the delimiter and should not be escaped. All reserved characters that are used in either the type or name must be escaped. The type, colon, and name combined cannot exceed 255 displayable characters in length.

Shared Secret Value

The value is made up of key/value pairs in the following format:

[key][delimiter][value][linefeed]…[key][delimiter][value][linefeed][null]

Where:

[key] identifies a key.
[delimiter] is the equals character in most cases, otherwise the colon character.
[value] identifies a value.
[linefeed] is the linefeed character.
[null] is the null terminator that must always appear at the end of the value.

Linefeed characters separate the pairs from each other. All the pairs combined cannot exceed 60 KB. Keys should be treated as case-ignore strings; in values, case should be honored. In addition, a null terminator must follow the last pair. The null terminator must be present even when no entry exists. No duplicate keys may exist. Duplicate values are allowed. Duplicates should be discarded by SSO apps if they are encountered. All reserved characters used in the key or value must be escaped. The entries must be in 16-bit Little Endian Unicode, including the null terminator. The order the entries are placed in a shared secret value is undefined and should not be relied upon. For example, an entry with a key of "A" could be positioned in the shared secret value after an entry with a key of "Z". The entries should be considered an un-ordered set.

Reserved Characters

The following characters are reserved:

Backslash ('\')
Colon (':')
Equals ('=')
Linefeed (0x0A)
Null terminator (0x00)

Reserved characters that are used outside of their context must be escaped by preceding them with a backslash character. Note that the linefeed and null characters cannot ever be used outside of their context.

Shared Secret Types

The following shared secret types currently exist:

Application shared secret
Credential set shared secret

Application shared secrets contain information associating applications with credentials as well as application-specific data. Credential set shared secrets contain login credential information used for one or more applications. The distinction between the two types of shared secrets allows several applications to all use the same set of credentials. It also allows one application to have more than one set of credentials.

Application Shared Secrets

Application shared secrets are used to represent an application, a web site, or a host application. Application secret identifiers follow the format outlined previously with a type value of “SS_App”. The application name should be able to identify the application in a unique fashion. It normally should follow one of the formats in the table below.

Application Type	Description	Example
Windows application	program.exe	Grpwise.exe
Web application	Unique URI	novell.com
Mainframe/host application	host application name	MyHostApplication

The application value contains application-specific information that is necessary to authenticate the user to the application, but that is not considered a credential. Examples include the control id for a password field in a windows application, and the name of a password field in a web form. Users do not normally need to enter such information to authenticate; it is inherent in the application. This application specific-data is in the key/value pair format with an equals character as the delimiter. The choice of what keys to use is left up to SSO apps.

Application data also contains pointers to the credential sets with which the application is associated. These pointers follow the key/value pair format as follows:

SS_CredSet:[credsetname]

Where:

[credsetname] is the name of the credential set that is associated with the application.

Note that the key must be “SS_CredSet” and that the colon character serves as the delimiter for credential set pointers. An exception to the value format for these pointers is that duplicates are permitted when the key is “SS_CredSet” so that applications may be associated with more than one credential set.

The order in which application data key/value pairs and credential set pointer key/value pairs are placed in the shared secret value is unimportant.

Credential Set Shared Secrets

Credential set shared secrets are used to contain login credentials needed to authenticate a user to an application, a web site, or a host application. They may be shared between multiple applications of the same or different type, primarily when the authentication database or mechanism behind such applications is the same. Examples include NDS authentication to the same object in a tree, and windows and web interfaces to the same application such as GroupWise. By sharing credential sets, a password saved or changed in one application automatically applies to other applications that share the same authentication database and secret data.

Credential set secret identifiers follow the format outlined previously with a type value of “SS_CredSet”. The administrator or user normally determines the name of a credential set. The name should be such that it helps to associate shared credentials with the appropriate applications.

Credential data contains information that users provide to authenticate to an application. Examples include their username and their password. This data is in the key/value pair format with an equals character as the delimiter. The choice of what keys to use is left up to SSO apps. However, SSO apps must agree with each other on this in order to share SSO information. Thus where possible, the following keys should be used:

Username
Password
Other

Shared Secret Example

This example is for two applications, Novell Groupwise client and Novell Groupwise Webaccess, that share the same credential information. In other words, users provide the same username and password to authenticate to both of these applications. The details for the shared secrets that are used to store the SSO information for these applications is provided below. Where necessary, [null] is used to represent the null terminator and [linefeed] is used to represent the linefeed character.

Shared Secret	Identifier	Value
Groupwise client application	SS_App:Grpwise.exe	SS_CredSet:Groupwise[linefeed]NameCtrlID=1002[linefeed]PassCtrlID=1003[null]
Groupwise Webaccess application	SS_App:webaccess.novell.com	FormName=loginForm[linefeed]SS_CredSet:Groupwise[null]
Groupwise credential set	SS_CredSet:Groupwise	Username=johndoe[linefeed]Password=johnpass[null]

Both of the application shared secrets contain pointers to the Groupwise credential set. This allows the applications to share the same credential information. If a user changes his or her password for one application, the other application automatically gets the updated password. The shared secret for the Groupwise client application has two application-specific entries and the shared secret for the Groupwise Webaccess application shared secret has only one.

Since:

3.1

Version:

3.2

Author:

Steve Kinser

See Also:

SharedEntry, Serialized Form

Field Summary

static String	APPLICATION_TYPE The shared secret application type.
static String	CREDENTIAL_TYPE The shared secret credset type.

Constructor Summary

SharedSecret(Secret secret)
Constructs a shared secret by wrapping another secret.

SharedSecret(Secret secret, boolean isToAutoLoad)
Constructs a shared secret by wrapping another secret.

SharedSecret(SecretStore secretStore, String secretType, String name)
Constructs a new shared secret.

SharedSecret(SecretStore secretStore, String secretType, String name, boolean isToAutoLoad)
Constructs a new shared secret.

Method Summary

void	addEntry(SharedEntry entry) Adds an entry.
void	clearEntries() Clears out the entries.
boolean	equals(Object obj) This method call is delegated to the wrapped secret.
boolean	exists() This method call is delegated to the wrapped secret.
Date	getAccessTime() This method call is delegated to the wrapped secret.
Date	getCreateTime() This method call is delegated to the wrapped secret.
Set	getCredSetEntries() Returns an unmodifiable Set of the all the CredSet entries.
Collection	getEntries() Returns an unmodifiable Collection of the entries.
SharedEntry	getEntry(String key) Returns the SharedEntry identified by the key.
Date	getModifyTime() This method call is delegated to the wrapped secret.
String	getName() Returns the shared secret name.
String	getSecretType() Returns the shared secret type.
int	getStatus() This method call is delegated to the wrapped secret.
byte[]	getValue() This method call is delegated to the wrapped secret.
int	hashCode() This method call is delegated to the wrapped secret.
boolean	isCheckingSecretIDCollision() This method call is delegated to the wrapped secret.
static boolean	isSharedSecret(Secret secret) Returns true if the secret is a SharedSecret and false if not.
static boolean	isSharedSecretIdentifier(String identifier) Returns true if the secret identifier is a SharedSecret identifier and false if not.
void	removeEntry(SharedEntry entry) Removes the entry.
void	setCheckingSecretIDCollision(boolean policy) This method call is delegated to the wrapped secret.
void	setEnhancedProtectionPassword(char[] erPass) This method call is delegated to the wrapped secret.
void	setValue() Set the secret value of this secret in SecretStore.
void	unsetEnhancedProtectionPassword() This method call is delegated to the wrapped secret.
void	update(Secret targetSecret, int flags) This method call is delegated to the wrapped secret.

Methods inherited from class com.novell.security.sso.Secret

create, create, delete, delete, exists, getAutoCreateIDPolicy, getEnhancedProtectedPolicy, isEnhancedProtected, isEnhancedProtectedWithPassword, read, read, setAutoCreateIDPolicy, setEnhancedProtected, setEnhancedProtectedPolicy, setValue, setValue, sync, toString, update

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

APPLICATION_TYPE

public static final String APPLICATION_TYPE

The shared secret application type. The value of this is "SS_App".

CREDENTIAL_TYPE

public static final String CREDENTIAL_TYPE

The shared secret credset type. The value of this is "SS_CredSet".

Constructor Detail

SharedSecret

public SharedSecret(Secret secret)

Constructs a shared secret by wrapping another secret. This method is not normally used to create a new shared secret.

Parameters:

secret - The secret that will be wrapped by this secret.

See Also:

SharedSecret(SecretStore secretStore, String secretType, String name)

SharedSecret

public SharedSecret(Secret secret,
                    boolean isToAutoLoad)

Constructs a shared secret by wrapping another secret. This method is not normally used to create a new shared secret.

Parameters:

secret - The secret that will be wrapped by this secret.

isToAutoLoad - Specify true to cause a read operation to occur automatically just after construction.

See Also:

SharedSecret(SecretStore secretStore, String secretType, String name)

SharedSecret

public SharedSecret(SecretStore secretStore,
                    String secretType,
                    String name)

Constructs a new shared secret. The identifier is auto generated according to the secretType and name parameters and the secret that is wrapped is obtained from the provided SecretStore. Use the other constructor in order to view and/or edit pre-existing shared secrets.

Parameters:

secretStore - The SecretStore.

secretType - The type of v-GO secret.

name - The name of the shared secret.

See Also:

SharedSecret(Secret secret)

SharedSecret

public SharedSecret(SecretStore secretStore,
                    String secretType,
                    String name,
                    boolean isToAutoLoad)

Constructs a new shared secret. The identifier is auto generated according to the secretType and name parameters and the secret that is wrapped is obtained from the provided SecretStore. Use the other constructor in order to view and/or edit pre-existing shared secrets.

Parameters:

secretStore - The SecretStore.

secretType - The type of v-GO secret.

name - The name of the shared secret.

isToAutoLoad - Specify true to cause a read operation to occur automatically just after construction.

See Also:

SharedSecret(Secret secret)

Method Detail

getAccessTime

public Date getAccessTime()
                   throws SSException

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

getAccessTime in class Secret

Returns:

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

Throws:

SSException - If a SSException occurred.

getCreateTime

public Date getCreateTime()
                   throws SSException

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

getCreateTime in class Secret

Returns:

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

Throws:

SSException - If a SSException occurred.

getCredSetEntries

public Set getCredSetEntries()
                      throws SSException

Returns an unmodifiable Set of the all the CredSet entries.

Returns:

Unmodifiable Set.

Throws:

SSException - If a SSException occurred.

See Also:

addEntry(SharedEntry entry), removeEntry(SharedEntry entry)

getEntries

public Collection getEntries()
                      throws SSException

Returns an unmodifiable Collection of the entries.

Returns:

Unmodifiable Collection.

Throws:

SSException - If a SSException occurred.

See Also:

addEntry(SharedEntry entry), removeEntry(SharedEntry entry)

getEntry

public SharedEntry getEntry(String key)
                     throws SSException

Returns the SharedEntry identified by the key.

Parameters:

key - The SharedEntry key.

Returns:

The SharedEntry. May be null if the entry does not exist.

Throws:

SSException - If a SSException occurred.

See Also:

addEntry(SharedEntry entry), removeEntry(SharedEntry entry)

getModifyTime

public Date getModifyTime()
                   throws SSException

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

getModifyTime in class Secret

Returns:

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

Throws:

SSException - If a SSException occurred.

getName

public String getName()

Returns the shared secret name. This is the same as the identifier, except that it excludes the header and the delimiter, and also is not escaped.

Returns:

The shared secret name.

getSecretType

public String getSecretType()

Returns the shared secret type. Valid values are SharedSecret.APPLICATION_TYPE and SharedSecret.CREDENTIAL_TYPE.

Returns:

The shared secret type.

isCheckingSecretIDCollision

public boolean isCheckingSecretIDCollision()

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

isCheckingSecretIDCollision in class Secret

Returns:

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

isSharedSecret

public static boolean isSharedSecret(Secret secret)

Returns true if the secret is a SharedSecret and false if not. Note that this method does not verify that the secret value is correctly formatted. It only checks the name of the secret.

Parameters:

secret - The Secret that will be tested.

Returns:

true if the secret is a SharedSecret and false if not.

isSharedSecretIdentifier

public static boolean isSharedSecretIdentifier(String identifier)

Returns true if the secret identifier is a SharedSecret identifier and false if not.

Parameters:

identifier - The secret identifier that will be tested.

Returns:

true if the identifier is a SharedSecret identifier and false if not.

Since:

3.2

setCheckingSecretIDCollision

public void setCheckingSecretIDCollision(boolean policy)

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

setCheckingSecretIDCollision in class Secret

Parameters:

policy - the checking secretID collision policy.

setEnhancedProtectionPassword

public void setEnhancedProtectionPassword(char[] erPass)

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

setEnhancedProtectionPassword in class Secret

Parameters:

erPass - Specifies the enhanced protection password.

getStatus

public int getStatus()
              throws SSException

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

getStatus in class Secret

Returns:

int - The secret's status.

Throws:

SSException - If a SSException occurred.

getValue

public byte[] getValue()
                throws SSException

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

getValue in class Secret

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:

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

setValue

public void setValue()
              throws SSException

Set the secret value of this secret in SecretStore. Makes a call to Secret.setValue(byte[] value, int flags) with a value of null and a flags value of 0. See the javadoc for the Secret class for more information.

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:

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

addEntry

public void addEntry(SharedEntry entry)

Adds an entry.

Parameters:

entry - The SharedEntry that will be added.

See Also:

getEntry(String key), getEntries(), removeEntry(SharedEntry entry)

clearEntries

public void clearEntries()

Clears out the entries.

equals

public boolean equals(Object obj)

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

equals in class Secret

Parameters:

obj - The object with which to compare this secret.

Returns:

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

exists

public boolean exists()
               throws SSException

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

exists in class Secret

Returns:

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

Throws:

SSException - If a SSException occurred.

hashCode

public int hashCode()

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

hashCode in class Secret

Returns:

the wrapped secret's hash code.

removeEntry

public void removeEntry(SharedEntry entry)

Removes the entry.

Parameters:

entry - The SharedEntry that will be removed.

See Also:

getEntry(String key), getEntries(), addEntry(SharedEntry entry)

unsetEnhancedProtectionPassword

public void unsetEnhancedProtectionPassword()

This method call is delegated to the wrapped secret.

Overrides:

unsetEnhancedProtectionPassword in class Secret

Following copied from class: com.novell.security.sso.Secret

See Also:

Secret.setEnhancedProtectionPassword(char[] erPass)

update

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

This method call is delegated to the wrapped secret. See the javadoc for the Secret class for more information.

Overrides:

update in class Secret

Parameters:

targetSecret - The target Secret.

flags - The flags for this operation.

Throws:

SSException - If a SSException occurred.