jespa.security

Class SecurityProvider

java.lang.Object

java.util.AbstractMap<K,V>

java.util.HashMap

jespa.security.Properties

jespa.security.SecurityProvider

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.Map

Direct Known Subclasses:

ChainSecurityProvider, LdapSecurityProvider, NtlmSecurityProvider, WordPressSecurityProvider

public abstract class SecurityProvider
extends jespa.security.Properties

An abstract class defining an interface for performing common security operations.

Note: This class should not be confused with java.security.Provider which serves a mostly different purpose.

Some security operations that might be performed by SecurityProviders include, but are not limited to, the following:

• Validate credentials with the provider authority.
• Perform authentication with another peer as an initiator.
• Perform authentication with another peer as an acceptor.
• Retrieving information about the provider authority.
• Retrieving information about an acccount from the provider authority.
• Checking group membership of an account.
• Create, update and delete accounts in the provider authority
• Set and change passwords of accounts in the provider authority

A SecurityProvider is also a HashMap of properties that are used to:

1. define provider options and
2. allow the caller to retrieve products of an operation.

SecurityProvider objects have a limited life-cycle that depends on how they are used. SecurityProvider objects are created, used for a specific purpose, and then disposed. Once a SecurityProvider object has been disposed it cannot be re-used. Multiple SecurityProvider objects may be used concurrently.

The life-cycle of a SecurityProvider depends on what it is used for. Some examples of SecurityProvider life-cycles are:

• A SecurityProvider that is used to perform a "logon" by validating a credential with the authenticate method may persist until the corresponding account is to "logoff" (by calling dispose). In fact, the credential validated or additional credentials acquired during the login may only be valid in the context of the SecurityProvider that validated or acquired them.
• A SecurityProvider that is used to initiate authentication with a remote peer over a socket may persist for the duration of that connection. In fact the security provider may be required to perform cryptographic operations on messages exchanged over the socket.
• A SecurityProvider that is used to change a password should persist only long enough to perform the change password operation.

Channel Bindings

To expose channel bindings to other components such as the HttpSecurityService, implementations just have to set the property "channelBindings" to a byte[] value representing the channel bindings data. For example, a Kerberos acceptor might retrieve channel bindings data from the client supplied service ticket and set it with code like this.put("channelBindings", channelBindingsBytesFromTicket);. The HttpSecurutyService will retrieve and check this value and accept or reject the client based on the various bindings.cert.* settings.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	identity The identity of the currently authenticated user such as through acceptSecContext.
protected boolean	isComplete Indicates that an authentication using initSecContext or acceptSecContext has been completed.

Fields inherited from class jespa.security.Properties

DUPLICATE_REFERENCE, NO_PROPERTY

Constructor Summary

Constructors

Constructor and Description
SecurityProvider(java.util.Map properties) Construct a new SecurityProvider with a copy of the supplied properties.
SecurityProvider(java.util.Map properties, java.lang.String[] pnames) Construct a SecurityProvider with only the properties named in the pnames parameter.

Method Summary

Modifier and Type	Method and Description
byte[]	acceptSecContext(byte[] token, int off, int len) Accept authentication with another peer by exchanging tokens.
void	authenticate(java.lang.Object credential) Validates the supplied credential with this provider's authority.
void	dispose() Destroy any sensitive cryptographic material used by this SecurityProvider.
java.lang.Object	exportState() Returns an Object representing the current state of this SecurityProvider.
Account	getAccount(java.lang.String acctname, java.lang.String[] attrs) Retrieve an Account object representing the named account and populate it (an Account is also a Map) with the attributes listed in the attrs array.
Domain	getDomain(java.lang.String dname, java.lang.String[] attrs) Retrieve a Domain object representing the named domain and populate it (a Domain is also a Map) with the attributes listed in the attrs array.
boolean	getFlag(java.lang.String name) Retrieve the named security flag as a boolean.
java.lang.String	getIdentity() Retrieve the account name of the currently authenticated user or null if no applicable authentication has occured.
java.lang.String	getName()
java.lang.Object	getProperty(java.lang.String name, java.lang.Object def) Retrieve a property by name or return the supplied default value if the property is not set.
void	importState(java.lang.Object state) Initializes a SecurityProvider with the state Object returned in a previous call to exportState().
byte[]	initSecContext(byte[] token, int off, int len) Initiate authentication with another peer by exchanging tokens.
boolean	isComplete() Used with initSecContext(byte[], int, int) or acceptSecContext(byte[], int, int) to determine if more tokens need to be exchanged.
void	setFlag(java.lang.String name, boolean value) Sets the value of the named flag.
void	setProperty(java.lang.String name, java.lang.Object obj) Set a property such as a SecurityProvider specific option.
void	unwrap(ByteBuffer incoming) Process an input buffer provided by a peer using another instance of this SecurityProvider's wrap(jespa.io.ByteBuffer) method or an equivalent routine.
void	wrap(ByteBuffer outgoing) Process an output buffer to apply some form of security such as message signing or encryption.

Methods inherited from class jespa.security.Properties

decodeObject, encodeObject, getEncryptedProperty, getFilteredProperties, getFilteredProperties, getProperty, getPropertyAsBoolean, getPropertyAsLong, setEncryptedProperty

Methods inherited from class java.util.HashMap

clear, clone, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, forEach, get, getOrDefault, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values

Methods inherited from class java.util.AbstractMap

equals, hashCode, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode

Field Detail

identity

protected java.lang.String identity

The identity of the currently authenticated user such as through acceptSecContext.

isComplete

protected boolean isComplete

Indicates that an authentication using initSecContext or acceptSecContext has been completed.

Constructor Detail

SecurityProvider

public SecurityProvider(java.util.Map properties)

Construct a new SecurityProvider with a copy of the supplied properties.

Parameters:

properties - a Map of initial options specific to this SecurityProvider

SecurityProvider

public SecurityProvider(java.util.Map properties,
                        java.lang.String[] pnames)
                 throws SecurityProviderException

Construct a SecurityProvider with only the properties named in the pnames parameter.

Parameters:

properties - the properties from which the named properties will be copied.

pnames - an array of property names to be populated in this SecurityProvider

Throws:

SecurityProviderException

Method Detail

getName

public java.lang.String getName()
                         throws SecurityProviderException

Throws:

SecurityProviderException

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object obj)
                 throws SecurityProviderException

Set a property such as a SecurityProvider specific option. See the specific SecurityProvider documentation for lists of options and their semantics.

Overrides:

setProperty in class jespa.security.Properties

Parameters:

name - the name of the property to set.

obj - the value of the property to set (which may be null).

Throws:

SecurityProviderException - if the property or it's value are invalid or cannot be set.

getProperty

public java.lang.Object getProperty(java.lang.String name,
                                    java.lang.Object def)
                             throws SecurityProviderException

Retrieve a property by name or return the supplied default value if the property is not set. This method should be overridden to return suitable initial values for properties that are not set. It is acceptable and expected that this method may trigger significant SecurityProvider logic such as remote communication with a SecurityProvider authority.

Overrides:

getProperty in class jespa.security.Properties

Parameters:

name - the name of the property to retrieve.

def - the default value to return of the named property is not set.

Returns:

the property value.

Throws:

SecurityProviderException - if the name is invalid or it's value cannot be retrieved.

getFlag

public boolean getFlag(java.lang.String name)
                throws SecurityProviderException

Retrieve the named security flag as a boolean. For a list of supported security flags, see the API documentation for the specific security provider being used. These values may change with each call to initSecContext or acceptSecContext. Retreiving a security flag before authentication is compelete indicates as to whether or not the security provider supports the named feature. Retrieving a security flag after authentication is complete indicates as to whether or not the named feature has been successfully negotiated by both parties and is in effect.

The following table lists suggested names for common security flags:

Suggested names for common security flags

Name	Description
integrity	The wrap and unwrap methods support integrity checking to ensure that data has not been modified.
confidentiality	The wrap and unwrap methods support encryption.
sequenceDetection	The wrap and unwrap methods use sequence numbers to ensure messages are not received out-of-sequence.
replayDetection
mutualAuthentication
delegation
transferable
protocolReady

Security flags may also be retrieved and set as properties using the flag name prefixed with "flags.". For example, the code fragment provider.getFlag("confidentiality") refers to the same property as provider.getProperty("flags.confidentiality") but getFlag returns the result as a boolean.

Parameters:

name - the name of the flag value to retrieve.

Returns:

the flag value. If the named flag is not defined, false is returned.

Throws:

SecurityProviderException

setFlag

public void setFlag(java.lang.String name,
                    boolean value)
             throws SecurityProviderException

Sets the value of the named flag. For a list of supported security flags, see the API documentation for the specific security provider being used.

Security flags may also be supplied as properties or set using other property methods by simply prefixing the flag names with "flags.". For example, the property name for integrity checking is "flags.integrity".

Parameters:

name - the name of the flag to set.

value - the new value of the flag.

Throws:

SecurityProviderException

getDomain

public Domain getDomain(java.lang.String dname,
                        java.lang.String[] attrs)
                 throws SecurityProviderException

Retrieve a Domain object representing the named domain and populate it (a Domain is also a Map) with the attributes listed in the attrs array. If the domain does not have a named attribute, that attribute will not be populated in the returned Domain object. The Domain object may contain additional attribute elements other than those requested in the attrs list.

If the dname parameter is null, a default Domain will be retrieved. If the attrs parameter is null, a default set of attributes will be assumed.

The behavior of this method is highly dependant on the specific SecurityProvider implementation being used. See the specific SecurityProvider documentation for details.

Parameters:

dname - the name of the domain to retrieve

attrs - the list of attribute names to populate in the Domain object returned

Throws:

SecurityProviderException - if the named domain could not be found or if a catostrophic error occurs.

getAccount

public Account getAccount(java.lang.String acctname,
                          java.lang.String[] attrs)
                   throws SecurityProviderException

Retrieve an Account object representing the named account and populate it (an Account is also a Map) with the attributes listed in the attrs array. If the account does not have one of the named attributes, that attribute will not be populated in the returned Account object. The Account object may contain additional attribute elements other than those requested in the attrs list.

If the acctname parameter is null, this method will return a default Account or null if this SecurityProvider has not been sufficiently initialized (such as by performing authentication).

If the attrs parameter is the special constant Account.ALL_ATTRS, this indicates that "all attributes" should be returned although the interpretation of this value depends greatly on the SecurityProvider (such as with the case of constructed attributes in Active Directory which can only be retrieved by explicitly requesting them by name).

If the attrs parameter is null, a default set of attributes will be retrieved. This default set may be determined only by what is convenient or efficent for the SecurityProvider implementation. With the exception of the attribute used to uniquely identify the account, the specific set of attributes returned if the attrs parameter is null is not defined unless stated otherwise in the API documentation of the SecurityProvider being used. Generally an attrs parameter of null should only be used when the caller has no interest in attributes or their values such as when checking for the existance of an account, deleting an account or checking group membership with Account.isMemberOf(java.lang.String).

If the acctname and attrs parameters are both null, a cached Account object may be returned.

Note: The acctname parameter should not be null when when performing Account.update(java.lang.String[]) operations to ensure that the Account object has current data. If data is not current, unexpected update behavior can result.

Note: Where possible, the acctname and attrs parameters should both be null when retrieving the Account used for checking group membership with Account.isMemberOf(java.lang.String). Otherwise, if cached group membership data is not utilized, the performance of isMemberOf may be poor.

The behavior of this method depends greatly on the specific SecurityProvider implementation being used.

Parameters:

acctname - the name of the account to retrieve or null to indicate that a default account should be retrieved

attrs - the names of the account attributes to retrieve or null to indicate that a default set of attriubutes should be retrieved or the special constant Account.ALL_ATTRS to indicate that "all attributes" should be retrieved.

Throws:

SecurityProviderException - if the named account could not be found or if a catostrophic error occurs.

getIdentity

public java.lang.String getIdentity()
                             throws SecurityProviderException

Retrieve the account name of the currently authenticated user or null if no applicable authentication has occured. The account name should be returned in a specific canonical form.

Returns:

the canonical account name of the currently authenticated user or null if no such user has sufficiently authenticated.

Throws:

SecurityProviderException - if an error occurs trying to retrieve the identity value.

exportState

public java.lang.Object exportState()
                             throws SecurityProviderException

Returns an Object representing the current state of this SecurityProvider. The state object may subsequently be imported with importState(java.lang.Object) into a different instance of the same type of SecurityProvider initialized with the same properties. The result should be a transfer of all state such that the new SecurityProvider instance should behave like the original within limits defined by the SecurityProvider type.

Transference of state between SecurityProvider instances may be used for a number of reasons including but not limited to:

• allowing stateful multi-step authentication to occur using multiple separate SecurityProvider instances such as with stateless networking protocols like HTTP or
• allow transferring an authenticated SecurityProvider between Java contexts or VMs that may not be able to communicate using means other than simple streams.

Exported SecurityProvider state may be limited in how it can be transferred. The reason may be to protect the integrity of the SecurityProvider data such as not writing potentially sensitive cryptographic material to an unprotected disk file. Or the reason may be a technical limitation such as the fact that the state may only be valid if the new SecurityProvider instance has access to a resource in the current VM like a database connection or network socket. If such a limitation is reached, an exception should be thrown from importState.

Once the state of a SecurityProvider has been exported, performing further operations may be invalid or may invalidate the exported state.

The return value should be a type that can easily be serialized such as a byte[] array or a java.io.Serializable object that can be used efficiently with I/O streams.

Returns:

an object (or preferrably a byte[] array) that represents the state of this SecurityProvider.

Throws:

SecurityProviderException - if the state could not or cannot be exported.

importState

public void importState(java.lang.Object state)
                 throws SecurityProviderException

Initializes a SecurityProvider with the state Object returned in a previous call to exportState(). Before the state is imported, this SecurityProvider must be initialized with the same properties as the original SecurityProvider.

Parameters:

state - an Object (or byte[] array) that represets the state to be imported.

Throws:

SecurityProviderException - if the state could not be imported such as because the state being imported has been transferred beyond it's acceptable boundries.

initSecContext

public byte[] initSecContext(byte[] token,
                             int off,
                             int len)
                      throws SecurityProviderException

Initiate authentication with another peer by exchanging tokens. If the return value is a non-null byte array (more commonly referred to as a "token"), it should be communicated to the other peer (such as embedded within a networking protocol message) where it will presumably be consumed by acceptSecContext(byte[], int, int) or an equivalent routine that accepts tokens of the same type. Tokens communicated back to this peer should be again passed to this method using the same SecurityProvider object (or one initialized using importState(java.lang.Object)). This exchange of tokens continues until isComplete returns true at which point authentication is complete from the prespective of the peer using this SecurityProvider. Note that any non-null final token may still need to be sent to the other peer to satisfy it's authentication context.

If the initial call to this method has no token (which is almost always true), an empty byte array (new byte[0]) should be supplied.

Parameters:

token - the buffer containing the authentication token supplied by the other peer or an empty byte array if no token has been supplied (which is almost always true with the initial call to this method).

off - the offset within token to the relevant data.

len - the length of the token within token at offset off.

Returns:

the token to be supplied to the other peer.

Throws:

SecurityProviderException - if the authentication operation failed. Where possible, the exception code should be SecurityProviderException.STATUS_ACCOUNT_NOT_FOUND if the other peer could not find the account for the identity being authenticated or SecurityProviderException.STATUS_INVALID_CREDENTIALS if the other peer indicated that the supplied credential was cryptographically incorrect. If the peer only indicated that the authentication failed in general and does not distinguish between the two cases, STATUS_INVALID_CREDENTIALS should be favored.

acceptSecContext

public byte[] acceptSecContext(byte[] token,
                               int off,
                               int len)
                        throws SecurityProviderException

Accept authentication with another peer by exchanging tokens. If the return value is a non-null byte array (more commonly referred to as a "token"), it should be communicated to the other peer (such as embedded within a networking protocol message) where it will presumably be consumed by initSecContext(byte[], int, int) or an equivalent routine that accepts tokens of the same type. Tokens supplied by the other peer should be again passed to this method using the same SecurityProvider object (or one initialized using importState(java.lang.Object)). This exchange of tokens continues until isComplete returns true at which point authentication from the prespective of the peer using this SecurityProvider is complete although any non-null final token may still need to be communicated back to the initiator to satisfy it's authentication context.

Note that it may be nessary to use the exportState()/importState(java.lang.Object) methods to initialize a SecurityProvider if, during the token exchange, a SecurityProvider object cannot persist between invocations of this method. For example, Java application servers frequently do not allow arbitrary objects to perist between HTTP requests. If the token exchange requires more than one request / response it would not be possible to maintain a single SecurityProvider instance. This issue is remedied by temporarily exporting the state with exportState where it can safely and efficiently be stored as an HTTP session variable. That state can then be restored into a new SecurityProvider with each subsequent HTTP request thereby allowing stateful authentication to proceed over the otherwise stateless HTTP protocol.

Parameters:

token - the buffer containing the authentication token supplied by the other peer.

off - the offset within token to the relevant data.

len - the length of the token within token at offset off.

Returns:

the token to be supplied to the other peer.

Throws:

SecurityProviderException - if a catostrophic error occured in processing. Note that unlike initSecContext, this method should not throw an exception to indicate that authentication has failed. Most errors will be encoded into a final token so as to communicate the failure to the initiator.

isComplete

public boolean isComplete()

Used with initSecContext(byte[], int, int) or acceptSecContext(byte[], int, int) to determine if more tokens need to be exchanged.

Returns:

true if authentication is complete. Otherwise, more tokens from the other peer need to be supplied to the authentication function being used.

wrap

public void wrap(ByteBuffer outgoing)
          throws SecurityProviderException

Process an output buffer to apply some form of security such as message signing or encryption. The processing may be reversed by calling the unwrap(jespa.io.ByteBuffer) method of another instance of this SecurityProvider or an equivalent routine.

Precisely what this method does depends on the SecurityProvider and it's properties which may be negotiated during another operation such as authentication between peers.

The wrap and unwrap methods are most commonly used to add security to network protocol messages. In this case it is first necessary to authenticate the peers using initSecContext(byte[], int, int) and acceptSecContext(byte[], int, int) to negotiate and initialize any security flags, message digests and crytographic materials that may be used for processing.

This method uses a ByteBuffer instead of byte[] arrays because it wraps data in-place without copying data and because the method cascades directly with other routines that use ByteBuffer. To emulate similar methods that operate on simple byte[] arrays, code like the following would be used:

ByteBuffer bb = new ByteBuffer();
bb.encodeBytes(outgoing, offset, len);
bb.setIndex(0);
provider.wrap(bb);
byte[] wrapped = bb.toByteArray();

Parameters:

outgoing - the buffer to be processed.

Throws:

SecurityProviderException - if a failure occurs processing the data.

unwrap

public void unwrap(ByteBuffer incoming)
            throws SecurityProviderException

Process an input buffer provided by a peer using another instance of this SecurityProvider's wrap(jespa.io.ByteBuffer) method or an equivalent routine.

This method uses a ByteBuffer instead of byte[] arrays because it unwraps data in-place without copying data and because the method cascades directly with other routines that use ByteBuffer. To emulate similar methods that operate on simple byte[] arrays, code like the following would be used:

ByteBuffer bb = new ByteBuffer();
bb.encodeBytes(incoming, offset, len);
bb.setIndex(0);
provider.unwrap(bb);
byte[] unwrapped = bb.toByteArray();

Parameters:

incoming - the buffer to be processed.

Throws:

SecurityProviderException - if a failure occurs processing the data.

authenticate

public void authenticate(java.lang.Object credential)
                  throws SecurityProviderException

Validates the supplied credential with this provider's authority. This method may only be called once. Meaning, a new SecurityProvider instance must be created to validate one credential. If the credential is successfully validated, the SecurityProvider may need to persist to make available properties related to the authentication context.

A SecurityProvider authority could be an LDAP database, a simple in-memory list of accounts, or a stub for the local host security authority such as nsswitch on UNIX or the LSA on Microsoft Windows.

Parameters:

credential - a credential to be validated. Providers should support the generic PasswordCredential class.

Throws:

SecurityProviderException - if the validation fails. The exception code should be SecurityProviderException.STATUS_ACCOUNT_NOT_FOUND if the credential identity was not found by the provider authority or SecurityProviderException.STATUS_INVALID_CREDENTIALS if the credential was cryptographically incorrect. If the authority only indicated that the authentication failed in general and does not distinguish between the two cases, STATUS_INVALID_CREDENTIALS should be favored.

dispose

public void dispose()
             throws SecurityProviderException

Destroy any sensitive cryptographic material used by this SecurityProvider. A SecurityProvider cannot be used after it is disposed.

Throws:

SecurityProviderException