NAME

WebKDC - Send requests to a WebAuth WebKDC

SYNOPSIS

    use WebKDC;
    use WebKDC::Exception;
    use WebKDC::WebRequest;
    use WebKDC::WebResponse;
    my ($status, $exception)
        = WebKDC::make_request_token_request ($req, $resp);
    my ($token, $subject);
    ($status, $exception, $token, $subject)
        = WebKDC::make_proxy_token_request ($krbreq, $tgt);

DESCRIPTION

This module provides functions to make a <requestToken> and a <webkdcProxyToken> call to a WebAuth WebKDC. These functions encapsulate the XML protocol and HTTP requests. This module is primarily intended for use by the WebLogin server to process requests from WebAuth Application Servers.

FUNCTIONS

make_proxy_token_request (AUTH, TGT)

Makes a <webkdcProxyToken> request to the WebKDC. The result, if successful, will be a webkdc-proxy token that can be passed into a subsequent call to make_request_token_request.

AUTH is a Kerberos authenticator for the WebKDC's Kerberos principal, as generated by the WebAuth::Krb5 make_auth method. TGT is a Kerberos ticket-granting ticket, exported with the WebAuth::Krb5 export_cred method, and then encrypted in the same call to make_auth as the DATA argument. Both must already be base64-encoded.

The return value is a four-element list. The first value will be the status. On error, the second value is an exception object and the remaining values are undef. On success, the second value is undef, the third value is the webkdc-proxy token (base64-encoded), and the fourth value is the subject (the identity) represented by the webkdc-proxy token.

make_request_token_request (REQUEST, RESPONSE)

Used to handle an incoming request token. REQUEST is a populated WebKDC::WebRequest object, and RESPONSE should be a newly-created WebKDC::WebResponse object. The request will be handled off to the configured WebKDC (see WebKDC::Config) and the results stored in the response object.

The return value is a list of the status and the exception object, if any. The status will be WK_SUCCESS on success and some other WK_ERR_* status code on failure. See WebKDC::WebKDCException for the other status codes.

throw (ERROR_CODE, ERROR_MSG, PEC, DATA)

Throw a WebKDCException with the given error code and message. This can also take an optional protocol error code and data.

request_token_request (REQUEST, RESPONSE)

Makes a requestTokenRequest call to the WebKDC, using data from the given WebKDC::WebRequest object. This will create the XML to communicate with the WebKDC, pass it along, then parse the response.

There is no return value. Instead, data is parsed from the WebKDC's response and placed into the WebKDC::WebResponse object passed to the function. On an error, we throw an exception with a specific error code.

proxy_token_request (REQUEST, TGT)

Makes a webkdcProxyTokenRequest call to the WebKDC, using the given WebKDC::WebRequest and TGT passed. This will create the XML to communicate with the WebKDC, pass it along, then parse the response.

The return value is a list of the returned proxy token and subject. On any failure, we throw an exception with a specific error code.

get_keyring (WA)

Returns a keyring object from the configured WebLogin keyring path.

get_child_value (ELEMENT, NAME, OPT)

Gets and returns the content of a child for the given element. NAME is the name of the child to search for. If there is no child of that name, throw an exception of type WK_ERR_UNRECOVERABLE_ERROR. If OPT is set and there was no child of the given name, instead just return undef.

AUTHOR

Roland Schemers and Russ Allbery <eagle@eyrie.org>.

SEE ALSO

WebAuth(3), WebAuth::Krb5(3), WebKDC::WebKDCException(3), WebKDC::WebRequest(3), WebKDC::WebRespsonse(3)

This module is part of WebAuth. The current version is available from <http://webauth.stanford.edu/>.