org.restlet.security

## Class Guard

- java.lang.Object
- - org.restlet.Restlet
  - - org.restlet.routing.Filter
    - - org.restlet.security.Guard

All Implemented Interfaces:
  Uniform

Deprecated.
Use the `ChallengeAuthenticator` class instead.

    @Deprecated
    public class Guard
    extends Filter

Filter guarding the access to an attached Restlet. More concretely, it guards from unauthenticated and unauthorized requests, providing facilities to check credentials such as passwords. It is also a relatively generic class which can work with several challenge schemes such as HTTP Basic and HTTP Digest.

Here are the processing steps of a Guard when a request reaches it:

1. It first attempts to authenticate it, i.e. to make sure that the challenge scheme used is supported and that the credentials given by the client (such as a login and password) are valid. The actual implementation of the authentication is delegated to the matching authentication helper. The result of this authentication can be:
   1. Valid: the authentication credentials are valid, the right scheme was used and the credentials could be verified by calling back the checkSecret() method on Guard. Here are the next steps:
      1. The authorize() method is called and if authorization is given the accept() method is invoked, which delegates to the attached Restlet or Resource by default. Otherwise, the forbid method is called, which sets the response status to `Status.CLIENT_ERROR_FORBIDDEN` (403).
   2. Missing: no credentials could be found, the challenge() method is invoked which delegates to the matching authenticator helper.
   3. Invalid: bad credentials were given such as a wrong password or unsupported scheme was used. If the "rechallenge" property is true, the challenge() method is invoked otherwise, the forbid() method is invoked.
   4. Stale: the credentials expired and must be renew. Therefore, the challenge() method is invoked.

Concurrency note: instances of this class or its subclasses can be invoked by several threads at the same time and therefore must be thread-safe. You should be especially careful when storing state in member variables.

Author:
  Jerome Louvel

### Field Summary

Fields
`static int` `AUTHENTICATION_INVALID` Deprecated. Indicates that an authentication response is considered invalid.
`static int` `AUTHENTICATION_MISSING` Deprecated. Indicates that an authentication response couldn't be found.
`static int` `AUTHENTICATION_STALE` Deprecated. Indicates that an authentication response is stale.
`static int` `AUTHENTICATION_VALID` Deprecated. Indicates that an authentication response is valid.
`static long` `DEFAULT_NONCE_LIFESPAN_MILLIS` Deprecated. Default lifespan for generated nonces (5 minutes).

### Fields inherited from class org.restlet.routing.Filter

`CONTINUE, SKIP, STOP`

### Constructor Summary

Constructors
Constructor and Description
`Guard(Context context, ChallengeScheme scheme, java.lang.String realm)` Deprecated. Constructor.
`Guard(Context context, java.lang.String realm, java.util.Collection<java.lang.String> baseUris, java.lang.String serverKey)` Deprecated. Alternate Constructor for HTTP DIGEST authentication scheme.

### Method Summary

Methods
`void` `accept(Request request, Response response)` Deprecated. Accepts the call.
`int` `authenticate(Request request)` Deprecated. Indicates if the call is properly authenticated.
`boolean` `authorize(Request request)` Deprecated. Indicates if the request is authorized to pass through the Guard.
`void` `challenge(Response response, boolean stale)` Deprecated. Challenges the client by adding a challenge request to the response and by setting the status to CLIENT_ERROR_UNAUTHORIZED.
`boolean` `checkSecret(Request request, java.lang.String identifier, char[] secret)` Deprecated. Indicates if the secret is valid for the given identifier.
`int` `doHandle(Request request, Response response)` Deprecated. Handles the call by distributing it to the next Restlet.
`char[]` `findSecret(java.lang.String identifier)` Deprecated. Finds the secret associated to a given identifier.
`void` `forbid(Response response)` Deprecated. Rejects the call due to a failed authentication or authorization.
`java.util.Collection<java.lang.String>` `getDomainUris()` Deprecated. Returns the base URIs that collectively define the protected domain for HTTP Digest Authentication.
`long` `getNonceLifespan()` Deprecated. Returns the number of milliseconds between each mandatory nonce refresh.
`java.lang.String` `getRealm()` Deprecated. Returns the authentication realm.
`ChallengeScheme` `getScheme()` Deprecated. Returns the authentication challenge scheme.
`Resolver<char[]>` `getSecretResolver()` Deprecated. Returns the secret resolver.
`java.util.concurrent.ConcurrentMap<java.lang.String,char[]>` `getSecrets()` Deprecated. Returns the modifiable map of identifiers and secrets.
`java.lang.String` `getServerKey()` Deprecated. Returns the secret key known only by server.
`boolean` `isRechallengeEnabled()` Deprecated. Indicates if a new challenge should be sent when invalid credentials are received (true by default to conform to HTTP recommendations).
`void` `setDomainUris(java.util.Collection<java.lang.String> domainUris)` Deprecated. Sets the URIs that define the HTTP DIGEST authentication protection domains.
`void` `setNonceLifespan(long lifespan)` Deprecated. Sets the number of milliseconds between each mandatory nonce refresh.
`void` `setRealm(java.lang.String realm)` Deprecated. Sets the authentication realm.
`void` `setRechallengeEnabled(boolean rechallengeEnabled)` Deprecated. Indicates if a new challenge should be sent when invalid credentials are received.
`void` `setScheme(ChallengeScheme scheme)` Deprecated. Sets the authentication challenge scheme.
`void` `setSecretResolver(Resolver<char[]> secretResolver)` Deprecated. Sets the secret resolver.
`void` `setServerKey(java.lang.String serverKey)` Deprecated. Sets the secret key known only by server.

### Methods inherited from class org.restlet.routing.Filter

`afterHandle, beforeHandle, getNext, handle, hasNext, setNext, setNext, start, stop`

### Methods inherited from class org.restlet.Restlet

`finalize, getApplication, getAuthor, getContext, getDescription, getLogger, getName, getOwner, isStarted, isStopped, setAuthor, setContext, setDescription, setName, setOwner`

### Methods inherited from class java.lang.Object

`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### AUTHENTICATION_INVALID

    public static final int AUTHENTICATION_INVALID

Deprecated.
Indicates that an authentication response is considered invalid.

See Also:
  Constant Field Values

#### AUTHENTICATION_MISSING

    public static final int AUTHENTICATION_MISSING

Deprecated.
Indicates that an authentication response couldn't be found.

See Also:
  Constant Field Values

#### AUTHENTICATION_STALE

    public static final int AUTHENTICATION_STALE

Deprecated.
Indicates that an authentication response is stale.

See Also:
  Constant Field Values

#### AUTHENTICATION_VALID

    public static final int AUTHENTICATION_VALID

Deprecated.
Indicates that an authentication response is valid.

See Also:
  Constant Field Values

#### DEFAULT_NONCE_LIFESPAN_MILLIS

    public static final long DEFAULT_NONCE_LIFESPAN_MILLIS

Deprecated.
Default lifespan for generated nonces (5 minutes).

See Also:
  Constant Field Values

### Constructor Detail

#### Guard

    public Guard(Context context,
         ChallengeScheme scheme,
         java.lang.String realm)
          throws java.lang.IllegalArgumentException

Deprecated.
Constructor.

Parameters:
  `context` - The context.
  `scheme` - The authentication scheme to use.
  `realm` - The authentication realm.
Throws:
  `java.lang.IllegalArgumentException` - if the scheme is null

#### Guard

    public Guard(Context context,
         java.lang.String realm,
         java.util.Collection<java.lang.String> baseUris,
         java.lang.String serverKey)

Deprecated.
Alternate Constructor for HTTP DIGEST authentication scheme.

Parameters:
  `context` - context
  `realm` - authentication realm
  `baseUris` - protection domain as a collection of base URIs
  `serverKey` - secret key known only to server

### Method Detail

#### accept

    public void accept(Request request,
              Response response)

Deprecated.
Accepts the call. By default, it is invoked if the request is authenticated and authorized. The default behavior is to ask to the attached Restlet to handle the call.

Parameters:
  `request` - The request to accept.
  `response` - The response to accept.

#### authenticate

    public int authenticate(Request request)

Deprecated.
Indicates if the call is properly authenticated. By default, this delegates credentials checking to checkSecret(). Note that the `ChallengeResponse.setAuthenticated(boolean)` and `ClientInfo.setAuthenticated(boolean)` methods are always called after authentication.

Parameters:
  `request` - The request to authenticate.
Returns:
  -1 if the given credentials were invalid, 0 if no credentials were found and 1 otherwise.
See Also:
  `checkSecret(Request, String, char[])`

#### authorize

    public boolean authorize(Request request)

Deprecated.
Indicates if the request is authorized to pass through the Guard. This method is only called if the call was successfully authenticated. It always returns true by default. If specific checks are required, they could be added by overriding this method.

Parameters:
  `request` - The request to authorize.
Returns:
  True if the request is authorized.

#### challenge

    public void challenge(Response response,
                 boolean stale)

Deprecated.
Challenges the client by adding a challenge request to the response and by setting the status to CLIENT_ERROR_UNAUTHORIZED.

Parameters:
  `response` - The response to update.
  `stale` - Indicates if the new challenge is due to a stale response.

#### checkSecret

    public boolean checkSecret(Request request,
                      java.lang.String identifier,
                      char[] secret)

Deprecated.
Indicates if the secret is valid for the given identifier. By default, this returns true given the correct login/password couple as verified via the findSecret() method.

Parameters:
  `request` - The Request
  `identifier` - the identifier
  `secret` - the identifier's secret
Returns:
  true if the secret is valid for the given identifier

#### doHandle

    public int doHandle(Request request,
               Response response)

Deprecated.
Handles the call by distributing it to the next Restlet.

Overrides:
  `doHandle` in class `Filter`
Parameters:
  `request` - The request to handle.
  `response` - The response to update.
Returns:
  The continuation status.

#### findSecret

    public char[] findSecret(java.lang.String identifier)

Deprecated.
Finds the secret associated to a given identifier. By default it looks up into the secrets map, but this behavior can be overriden by setting a custom secret resolver using the `setSecretResolver(Resolver)` method.

Parameters:
  `identifier` - The identifier to lookup.
Returns:
  The secret associated to the identifier or null.

#### forbid

    public void forbid(Response response)

Deprecated.
Rejects the call due to a failed authentication or authorization. This can be overridden to change the default behavior, for example to display an error page. By default, if authentication is required, the challenge method is invoked, otherwise the call status is set to CLIENT_ERROR_FORBIDDEN.

Parameters:
  `response` - The reject response.

#### getDomainUris

    public java.util.Collection<java.lang.String> getDomainUris()

Deprecated.
Returns the base URIs that collectively define the protected domain for HTTP Digest Authentication.

Returns:
  The base URIs.

#### getNonceLifespan

    public long getNonceLifespan()

Deprecated.
Returns the number of milliseconds between each mandatory nonce refresh.

Returns:
  The nonce lifespan.

#### getRealm

    public java.lang.String getRealm()

Deprecated.
Returns the authentication realm.

Returns:
  The authentication realm.

#### getScheme

    public ChallengeScheme getScheme()

Deprecated.
Returns the authentication challenge scheme.

Returns:
  The authentication challenge scheme.

#### getSecretResolver

    public Resolver<char[]> getSecretResolver()

Deprecated.
Returns the secret resolver.

Returns:
  The secret resolver.

#### getSecrets

    public java.util.concurrent.ConcurrentMap<java.lang.String,char[]> getSecrets()

Deprecated.
Returns the modifiable map of identifiers and secrets.

Returns:
  The map of identifiers and secrets.

#### getServerKey

    public java.lang.String getServerKey()

Deprecated.
Returns the secret key known only by server. This is used by the HTTP DIGEST authentication scheme.

Returns:
  The server secret key.

#### isRechallengeEnabled

    public boolean isRechallengeEnabled()

Deprecated.
Indicates if a new challenge should be sent when invalid credentials are received (true by default to conform to HTTP recommendations). If set to false, upon reception of invalid credentials, the Guard will forbid the access (`Status.CLIENT_ERROR_FORBIDDEN`).

Returns:
  True if invalid credentials result in a new challenge.

#### setDomainUris

    public void setDomainUris(java.util.Collection<java.lang.String> domainUris)

Deprecated.
Sets the URIs that define the HTTP DIGEST authentication protection domains.

Parameters:
  `domainUris` - The URIs of protection domains.

#### setNonceLifespan

    public void setNonceLifespan(long lifespan)

Deprecated.
Sets the number of milliseconds between each mandatory nonce refresh.

Parameters:
  `lifespan` - The nonce lifespan in ms.

#### setRealm

    public void setRealm(java.lang.String realm)

Deprecated.
Sets the authentication realm.

Parameters:
  `realm` - The authentication realm.

#### setRechallengeEnabled

    public void setRechallengeEnabled(boolean rechallengeEnabled)

Deprecated.
Indicates if a new challenge should be sent when invalid credentials are received.

Parameters:
  `rechallengeEnabled` - True if invalid credentials result in a new challenge.
See Also:
  `isRechallengeEnabled()`

#### setScheme

    public void setScheme(ChallengeScheme scheme)

Deprecated.
Sets the authentication challenge scheme.

Parameters:
  `scheme` - The authentication challenge scheme.

#### setSecretResolver

    public void setSecretResolver(Resolver<char[]> secretResolver)

Deprecated.
Sets the secret resolver.

Parameters:
  `secretResolver` - The secret resolver.

#### setServerKey

    public void setServerKey(java.lang.String serverKey)

Deprecated.
Sets the secret key known only by server. This is used by the HTTP DIGEST authentication scheme.

Parameters:
  `serverKey` - The server secret key.