http://www.jboss.org/undertow-parent/undertow-core: Undertow (JBoss by Red Hat) 
/*
 * JBoss, Home of Professional Open Source.
 * Copyright 2014 Red Hat, Inc., and individual contributors
 * as indicated by the @author tags.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package io.undertow.security.api;

import io.undertow.server.HttpServerExchange;


A NonceManager is used by the HTTP Digest authentication mechanism to request nonces and to validate the nonces sent from the
client.

Author:Darran Lofthouse
/**
 * A NonceManager is used by the HTTP Digest authentication mechanism to request nonces and to validate the nonces sent from the
 * client.
 *
 * @author <a href="mailto:darran.lofthouse@jboss.com">Darran Lofthouse</a>
 */
public interface NonceManager {

    // TODO - Should a nonce manager be able to tie these to a connection or session, or any other piece of info we have about
    // the client?
    // Also different rules depending on HTTP method or the resource being accessed?

    
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.

Params:
  • lastNonce – - The last valid nonce received from the client or null if we don't already have a nonce.
Returns:The next nonce to be sent in a challenge to the client.
/**
     * 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.
     *
     * @param lastNonce - The last valid nonce received from the client or null if we don't already have a nonce.
     * @return The next nonce to be sent in a challenge to the client.
     */
    String nextNonce(final String lastNonce, final HttpServerExchange exchange);

    
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.

Params:
  • nonce – - The nonce received from the client.
  • nonceCount – - The nonce count from the client or -1 of none specified.
Returns:true if the nonce can be used otherwise return false.
/**
     * 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.
     *
     * @param nonce - The nonce received from the client.
     * @param nonceCount - The nonce count from the client or -1 of none specified.
     * @return true if the nonce can be used otherwise return false.
     */
    boolean validateNonce(final String nonce, final int nonceCount, final HttpServerExchange exchange);

}