Inherits from KGChallengeHandler : NSObject
Declared in KGDispatchChallengeHandler.h

Overview

A DispatchChallengeHandler is responsible for dispatching challenge requests to appropriate challenge handlers when challenges arrive from specific URI locations in challenge responses.

This allows clients to use specific challenge handlers to handle specific types of challenges at different URI locations.

Tasks

  • – canHandle:

    Can the presented challenge be potentially handled by this challenge handler?

  • – handle:

    Handle the presented challenge by creating a challenge response or returning nil. This responsibility is usually achieved by using the associated KGLoginHandler to obtain user credentials, and transforming those credentials into a KGChallengeResponse.

    When it is not possible to create a KGChallengeResponse, this method MUST return nil.

  • – registerChallengeHandler:challengeHandler:

    Register a challenge handler to respond to challenges at one or more locations.

    When a challenge response is received for a protected URI, the locationDescription matches against elements of the protected URI; if a match is found, one consults the challenge handler(s) registered at that locationDescription to find a challenge handler suitable to respond to the challenge.

    A locationDescription comprises a username, password, host, port and paths, any of which can be wild-carded with the “*” character to match any number of request URIs. If no port is explicitly mentioned in a locationDescription, a default port will be inferred based on the scheme mentioned in the location description, according to the following table:

    schemedefault portSample locationDescription
    http80foo.example.com or http://foo.example.com
    ws80foo.example.com or ws://foo.example.com
    https443https://foo.example.com
    wss443wss://foo.example.com

    The protocol scheme (e.g. http or ws) if present in locationDescription will not be used to match locationDescription with the protected URI, because authentication challenges are implemented on top of one of the HTTP/s protocols always, whether one is initiating web socket connections or regular HTTP connections. That is to say for example, the locationDescription "foo.example.com" matches both URIs http://foo.example.com and ws://foo.example.com.

    Some examples of locationDescription values with wildcards are:

    1. */ — matches all requests to any host on port 80 (default port), with no user info or path specified.
    2. *.hostname.com:8000 — matches all requests to port 8000 on any sub-domain of hostname.com, but not hostname.com itself.
    3. server.hostname.com:*/* — matches all requests to a particular server on any port on any path but not the empty path.

  • – unregisterChallengeHandler:challengeHandler:

    If the provided challengeHandler is registered at the provided location, clear that association such that any future challenge requests matching the location will never be handled by the provided challenge handler.

    If no such location or challengeHandler registration exists, this method silently succeeds.

Instance Methods

canHandle:

Can the presented challenge be potentially handled by this challenge handler?

- (BOOL)canHandle:(KGChallengeRequest *)challengeRequest

Parameters

challengeRequest

a challenge request object containing a challenge

Return Value

true if this challenge handler could potentially respond meaningfully to the challenge.

Declared In

KGChallengeHandler.h

handle:

Handle the presented challenge by creating a challenge response or returning nil. This responsibility is usually achieved by using the associated KGLoginHandler to obtain user credentials, and transforming those credentials into a KGChallengeResponse.

When it is not possible to create a KGChallengeResponse, this method MUST return nil.

- (KGChallengeResponse *)handle:(KGChallengeRequest *)challengeRequest

Parameters

challengeRequest

a challenge object

Return Value

a challenge response object or nil if no response is possible.

Declared In

KGChallengeHandler.h

registerChallengeHandler:challengeHandler:

Register a challenge handler to respond to challenges at one or more locations.

When a challenge response is received for a protected URI, the locationDescription matches against elements of the protected URI; if a match is found, one consults the challenge handler(s) registered at that locationDescription to find a challenge handler suitable to respond to the challenge.

A locationDescription comprises a username, password, host, port and paths, any of which can be wild-carded with the “*” character to match any number of request URIs. If no port is explicitly mentioned in a locationDescription, a default port will be inferred based on the scheme mentioned in the location description, according to the following table:

schemedefault portSample locationDescription
http80foo.example.com or http://foo.example.com
ws80foo.example.com or ws://foo.example.com
https443https://foo.example.com
wss443wss://foo.example.com

The protocol scheme (e.g. http or ws) if present in locationDescription will not be used to match locationDescription with the protected URI, because authentication challenges are implemented on top of one of the HTTP/s protocols always, whether one is initiating web socket connections or regular HTTP connections. That is to say for example, the locationDescription "foo.example.com" matches both URIs http://foo.example.com and ws://foo.example.com.

Some examples of locationDescription values with wildcards are:

  1. */ — matches all requests to any host on port 80 (default port), with no user info or path specified.
  2. *.hostname.com:8000 — matches all requests to port 8000 on any sub-domain of hostname.com, but not hostname.com itself.
  3. server.hostname.com:*/* — matches all requests to a particular server on any port on any path but not the empty path.

- (KGDispatchChallengeHandler *)registerChallengeHandler:(NSString *)locationDescription challengeHandler:(KGChallengeHandler *)challengeHandler

Parameters

locationDescription

the (possibly wild-carded) location(s) at which to register a handler.

challengeHandler

the challenge handler to register at the location(s).

Return Value

a reference to this challenge handler for chained calls

Declared In

KGDispatchChallengeHandler.h

unregisterChallengeHandler:challengeHandler:

If the provided challengeHandler is registered at the provided location, clear that association such that any future challenge requests matching the location will never be handled by the provided challenge handler.

If no such location or challengeHandler registration exists, this method silently succeeds.

- (KGChallengeHandler *)unregisterChallengeHandler:(NSString *)locationDescription challengeHandler:(KGChallengeHandler *)challengeHandler

Parameters

locationDescription

the exact location description at which the challenge handler was originally registered

challengeHandler

the challenge handler to de-register.

Return Value

a reference to this object for chained call support

Declared In

KGDispatchChallengeHandler.h