Top Description Inners Fields Constructors Methods
io.undertow.security.impl

public Class SimpleNonceManager

extends Object
implements SessionNonceManager
Class Inheritance
All Implemented Interfaces
io.undertow.security.api.SessionNonceManager, io.undertow.security.api.NonceManager
Static Imports
io.undertow.UndertowMessages.MESSAGES, org.wildfly.common.Assert.checkNotNullParamWithNullPointerException
A default io.undertow.security.api.NonceManager implementation to provide reasonable single host management of nonces. This io.undertow.security.api.NonceManager manages nonces in two groups, the first is the group that are allocated to new requests, this group is a problem as we want to be able to limit how many we distribute so we don't have a DOS storing too many but we also don't a high number of requests to to push the other valid nonces out faster than they can be used. The second group is the set of nonces actively in use - these should be maintained as we can also maintain the nonce count and even track the next nonce once invalid. Maybe group one should be a timestamp and private key hashed together, if used with a nonce count they move to be tracked to ensure the same count is not used again - if successfully used without a nonce count add to a blacklist until expiration? A nonce used without a nonce count will essentially be single use with each request getting a new nonce.
Author
Darran Lofthouse

Nested and Inner Type Summary

Modifier and TypeClass and Description
private class
SimpleNonceManager.InvalidNonceCleaner

private class
SimpleNonceManager.KnownNonceCleaner

private static class
SimpleNonceManager.Nonce

The state associated with a nonce.

private static class
SimpleNonceManager.NonceHolder

A simple wrapper around a nonce to allow it to be used as a key in a weak map.

Field Summary

Modifier and TypeField and Description
private static final long
cacheTimePostExpiry

A previously used nonce will be allowed to remain in the knownNonces list for up to 5 minutes.

private static final String
DEFAULT_HASH_ALG

private static final long
firstUseTimeOut

After a nonce is issued the first authentication response MUST be received within 5 minutes.

private final Map<SimpleNonceManager.NonceHolder, String>
forwardMapping

A WeakHashMap to map expired nonces to their replacement nonce.

private final String
hashAlg

private final int
hashLength

private final Set<String>
invalidNonces

List of invalid nonces, this list contains the nonces that have been used without a nonce count.

private final Map<String, SimpleNonceManager.Nonce>
knownNonces

Map of known currently valid nonces, a SortedMap is used to order the nonces by their creation time stamp allowing a simple iteration over the keys to identify expired nonces.

private static final long
overallTimeOut

Overall a nonce is valid from 15 minutes from first being issued, if used after this then a new nonce will be issued.

private static final Random
rand

Create a static instance of SecureRandom, so it can be actually reused by all instances of this class.

private final String
secret

Constructor Summary

AccessConstructor and Description
public
SimpleNonceManager()

public
SimpleNonceManager(final String hashAlg)

Method Summary

Modifier and TypeMethod and Description
private boolean
addInvalidNonce(final SimpleNonceManager.Nonce nonce, final XnioExecutor executor)

public void
associateHash(String
- The nonce the hash is to be associated with.
nonce, byte[]
- The hash to associate.
hash)

Implements io.undertow.security.api.SessionNonceManager.associateHash.

Associate the supplied hash with the nonce specified.

private SimpleNonceManager.Nonce
createNewNonce(SimpleNonceManager.NonceHolder previousNonce)

private String
createNewNonceString()

private String
createNonce(final byte[] prefix, final byte[] timeStamp)

private byte[]
generateHash(final byte[] prefix, final byte[] timeStamp)

private MessageDigest
getDigest(final String hashAlg)

public byte[]
lookupHash(String
- The nonce the hash is required for.
nonce)

Implements io.undertow.security.api.SessionNonceManager.lookupHash.

Retrieve the existing hash associated with the nonce specified.

public String
nextNonce(String
- The last valid nonce received from the client or null if we don't already have a nonce.
lastNonce, HttpServerExchange exchange)

Implements io.undertow.security.api.NonceManager.nextNonce.

Select the next nonce to be sent from the server taking into account the last valid nonce.

public boolean
validateNonce(String
- The nonce received from the client.
nonce, int
- The nonce count from the client or -1 of none specified.
nonceCount, HttpServerExchange exchange)

Implements io.undertow.security.api.NonceManager.validateNonce.

Validate that a nonce can be used.

private boolean
validateNonceWithCount(SimpleNonceManager.Nonce nonce, int nonceCount, final XnioIoThread executor)

private SimpleNonceManager.Nonce
verifyUnknownNonce(final String
-
nonce, final int nonceCount)

Verify a previously unknown nonce and return the NonceKey representation for the nonce.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

cacheTimePostExpiryback to summary
private static final long cacheTimePostExpiry

A previously used nonce will be allowed to remain in the knownNonces list for up to 5 minutes. The nonce will be accepted during this 5 minute window but will immediately be replaced causing any additional requests to be forced to use the new nonce. This is primarily for session based digests where loosing the cached session key would be bad.

DEFAULT_HASH_ALGback to summary
private static final String DEFAULT_HASH_ALG
firstUseTimeOutback to summary
private static final long firstUseTimeOut

After a nonce is issued the first authentication response MUST be received within 5 minutes.

forwardMappingback to summary
private final Map<SimpleNonceManager.NonceHolder, String> forwardMapping

A WeakHashMap to map expired nonces to their replacement nonce. For an item to be added to this Collection the value will have been removed from the knownNonces map. A replacement nonce will have been added to knownNonces that references the key used here - once the replacement nonce is removed from knownNonces then the key will be eligible for garbage collection allowing it to be removed from this map as well. The value in this Map is a plain String, this is to avoid inadvertently creating a long term reference to the key we expect to be garbage collected at some point in the future.

hashAlgback to summary
private final String hashAlg
hashLengthback to summary
private final int hashLength
invalidNoncesback to summary
private final Set<String> invalidNonces

List of invalid nonces, this list contains the nonces that have been used without a nonce count. In that situation they are considered single use and must not be used again.

knownNoncesback to summary
private final Map<String, SimpleNonceManager.Nonce> knownNonces

Map of known currently valid nonces, a SortedMap is used to order the nonces by their creation time stamp allowing a simple iteration over the keys to identify expired nonces.

overallTimeOutback to summary
private static final long overallTimeOut

Overall a nonce is valid from 15 minutes from first being issued, if used after this then a new nonce will be issued.

randback to summary
private static final Random rand

Create a static instance of SecureRandom, so it can be actually reused by all instances of this class. This should also increase the randomness of generated numbers.

secretback to summary
private final String secret

Constructor Detail

SimpleNonceManagerback to summary
public SimpleNonceManager()
SimpleNonceManagerback to summary
public SimpleNonceManager(final String hashAlg)

Method Detail

addInvalidNonceback to summary
private boolean addInvalidNonce(final SimpleNonceManager.Nonce nonce, final XnioExecutor executor)
associateHashback to summary
public void associateHash(String nonce, byte[] hash)

Implements io.undertow.security.api.SessionNonceManager.associateHash.

Doc from io.undertow.security.api.SessionNonceManager.associateHash.

Associate the supplied hash with the nonce specified.

Parameters
nonce:String

- The nonce the hash is to be associated with.

hash:byte[]

- The hash to associate.

createNewNonceback to summary
private SimpleNonceManager.Nonce createNewNonce(SimpleNonceManager.NonceHolder previousNonce)
createNewNonceStringback to summary
private String createNewNonceString()
createNonceback to summary
private String createNonce(final byte[] prefix, final byte[] timeStamp)
generateHashback to summary
private byte[] generateHash(final byte[] prefix, final byte[] timeStamp)
getDigestback to summary
private MessageDigest getDigest(final String hashAlg)
lookupHashback to summary
public byte[] lookupHash(String nonce)

Implements io.undertow.security.api.SessionNonceManager.lookupHash.

Doc from io.undertow.security.api.SessionNonceManager.lookupHash.

Retrieve the existing hash associated with the nonce specified. If there is no association then null should be returned.

Parameters
nonce:String

- The nonce the hash is required for.

Returns:byte[]

The associated hash or null if there is no association.

nextNonceback to summary
public String nextNonce(String lastNonce, HttpServerExchange exchange)

Implements io.undertow.security.api.NonceManager.nextNonce.

Doc from io.undertow.security.api.NonceManager.nextNonce.

Select the next nonce to be sent from the server taking into account the last valid nonce. It is both possible and likely that the nonce last used by the client will still be valid, in that case the same nonce will be returned.

Parameters
lastNonce:String

- The last valid nonce received from the client or null if we don't already have a nonce.

Returns:String

The next nonce to be sent in a challenge to the client.

See Also
io.undertow.security.api.NonceManager#nextNonce(java.lang.String, io.undertow.server.HttpServerExchange)
validateNonceback to summary
public boolean validateNonce(String nonce, int nonceCount, HttpServerExchange exchange)

Implements io.undertow.security.api.NonceManager.validateNonce.

Doc from io.undertow.security.api.NonceManager.validateNonce.

Validate that a nonce can be used. If the nonce can not be used but the related digest was correct then a new nonce should be returned to the client indicating that the nonce was stale. For implementations of this interface this method is not expected by be idempotent, i.e. once a nonce is validated with a specific nonceCount it is not expected that this method will return true again if the same combination is presented. This method is expected to ONLY be called if the users credentials are valid as a storage overhead could be incurred this overhead must not be accessible to unauthenticated clients.

Parameters
nonce:String

- The nonce received from the client.

nonceCount:int

- The nonce count from the client or -1 of none specified.

Returns:boolean

true if the nonce can be used otherwise return false.

Annotations
@Override
See Also
io.undertow.security.api.NonceManager#validateNonce(java.lang.String, int, io.undertow.server.HttpServerExchange)
validateNonceWithCountback to summary
private boolean validateNonceWithCount(SimpleNonceManager.Nonce nonce, int nonceCount, final XnioIoThread executor)
verifyUnknownNonceback to summary
private SimpleNonceManager.Nonce verifyUnknownNonce(final String nonce, final int nonceCount)

Verify a previously unknown nonce and return the NonceKey representation for the nonce. Later when a nonce is re-used we can match based on the String alone - the information embedded within the nonce will be cached with it. This stage of the verification simply extracts the prefix and the embedded timestamp and recreates a new hashed and Base64 nonce based on the local secret - if the newly generated nonce matches the supplied one we accept it was created by this nonce manager. This verification does not validate that the timestamp is within a valid time period.

Parameters
nonce:String

-

io.undertow.security.impl back to summary

private Class SimpleNonceManager.InvalidNonceCleaner

extends Object
implements Runnable
Class Inheritance
  • java.lang.Object
  • io.undertow.security.impl.SimpleNonceManager.InvalidNonceCleaner
All Implemented Interfaces
java.lang.Runnable

Field Summary

Modifier and TypeField and Description
private final String
nonce

Constructor Summary

AccessConstructor and Description
private
InvalidNonceCleaner(final String nonce)

Method Summary

Modifier and TypeMethod and Description
public void
run()

Implements java.lang.Runnable.run.

Runs this operation.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

nonceback to summary
private final String nonce

Constructor Detail

InvalidNonceCleanerback to summary
private InvalidNonceCleaner(final String nonce)

Method Detail

runback to summary
public void run()

Implements java.lang.Runnable.run.

Doc from java.lang.Runnable.run.

Runs this operation.

io.undertow.security.impl back to summary

private Class SimpleNonceManager.KnownNonceCleaner

extends Object
implements Runnable
Class Inheritance
  • java.lang.Object
  • io.undertow.security.impl.SimpleNonceManager.KnownNonceCleaner
All Implemented Interfaces
java.lang.Runnable

Field Summary

Modifier and TypeField and Description
private final String
nonce

Constructor Summary

AccessConstructor and Description
private
KnownNonceCleaner(final String nonce)

Method Summary

Modifier and TypeMethod and Description
public void
run()

Implements java.lang.Runnable.run.

Runs this operation.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

nonceback to summary
private final String nonce

Constructor Detail

KnownNonceCleanerback to summary
private KnownNonceCleaner(final String nonce)

Method Detail

runback to summary
public void run()

Implements java.lang.Runnable.run.

Doc from java.lang.Runnable.run.

Runs this operation.

io.undertow.security.impl back to summary

private Class SimpleNonceManager.Nonce

extends Object
Class Inheritance
The state associated with a nonce. A NonceKey for a preciously valid nonce is also referenced, this is so that a WeakHashMap can be used to maintain a mapping from the original NonceKey to the new nonce value.

Field Summary

Modifier and TypeField and Description
private XnioExecutor.Key
executorKey

private int
maxNonceCount

private final String
nonce

private final SimpleNonceManager.NonceHolder
previousNonce

private byte[]
sessionKey

private final long
timeStamp

Constructor Summary

AccessConstructor and Description
private
Nonce(final String nonce)

private
Nonce(final String nonce, final long timeStamp, final int initialNC)

private
Nonce(final String nonce, final long timeStamp, final SimpleNonceManager.NonceHolder previousNonce)

private
Nonce(final String nonce, final long timeStamp, final int initialNC, final SimpleNonceManager.NonceHolder previousNonce)

Method Summary

Modifier and TypeMethod and Description
pack-priv int
getMaxNonceCount()

pack-priv byte[]
getSessionKey()

pack-priv void
setMaxNonceCount(int maxNonceCount)

pack-priv void
setSessionKey(final byte[] sessionKey)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

executorKeyback to summary
private XnioExecutor.Key executorKey
maxNonceCountback to summary
private int maxNonceCount
nonceback to summary
private final String nonce
previousNonceback to summary
private final SimpleNonceManager.NonceHolder previousNonce
Annotations
@SuppressWarnings:unused
sessionKeyback to summary
private byte[] sessionKey
timeStampback to summary
private final long timeStamp

Constructor Detail

Nonceback to summary
private Nonce(final String nonce)
Nonceback to summary
private Nonce(final String nonce, final long timeStamp, final int initialNC)
Nonceback to summary
private Nonce(final String nonce, final long timeStamp, final SimpleNonceManager.NonceHolder previousNonce)
Nonceback to summary
private Nonce(final String nonce, final long timeStamp, final int initialNC, final SimpleNonceManager.NonceHolder previousNonce)

Method Detail

getMaxNonceCountback to summary
pack-priv int getMaxNonceCount()
getSessionKeyback to summary
pack-priv byte[] getSessionKey()
setMaxNonceCountback to summary
pack-priv void setMaxNonceCount(int maxNonceCount)
setSessionKeyback to summary
pack-priv void setSessionKey(final byte[] sessionKey)
io.undertow.security.impl back to summary

private Class SimpleNonceManager.NonceHolder

extends Object
Class Inheritance
A simple wrapper around a nonce to allow it to be used as a key in a weak map.

Field Summary

Modifier and TypeField and Description
private final String
nonce

Constructor Summary

AccessConstructor and Description
private
NonceHolder(final String nonce)

Method Summary

Modifier and TypeMethod and Description
public boolean
equals(Object
the reference object with which to compare.
obj)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAlltoStringwaitwaitwait

Field Detail

nonceback to summary
private final String nonce

Constructor Detail

NonceHolderback to summary
private NonceHolder(final String nonce)

Method Detail

equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
obj:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override