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 <rra@stanford.edu>.

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/>.