Linux Certif

Toute la documentation sur la certification Linux LPI

WebAuth.3pm

NAME

WebAuth - Perl extension for WebAuth (version 3)

SYNOPSIS

   use WebAuth;
 
   eval {  
     $key = WebAuth::random_key(WebAuth::WA_AES_128);
     ...
   };
   if (WebAuth::Exception::match($@)) {
     # handle exception 
   }
 
 

DESCRIPTION

WebAuth is a low-level Perl interface into the WebAuth C API. Some functions have been made more Perl-like, though no attempt has been made to create an object-oriented interface to the WebAuth library.

All functions have the potential to croak with a WebAuth::Exception object, so an eval block should be placed around calls to WebAuth functions if you intend to recover from errors. See the WebAuth::Exception section for more information.

EXPORT

Nothing is exported by default, but the following %EXPORT_TAGS are available:

   attrs     the attr_* functions
   base64    the base64_* functions
   const     the wA_* constants
   hex       the hex_* functions
   key       the key_* and keyring_* functions
   krb5      the krb5_* functions
   random    the random_* functions
   token     the token_* functions
 
 

For example:

   use WebAuth qw(:krb5 :const);
 
 

FUNCTIONS

error_message(status)

$message = error_message($status)

Returns an error message for the specified status, which should be one of the WA_ERR_* values.

base64_encode(input);

$output = base64_encode($input);

base64 encodes the $input string and returns the result.

base64_decode(input)

  $output = base64_decode($input);
 
 

base64 decodes the $input string and returns the result in $output, or undef if unable to parse $input.

hex_encode(input);

$output = hex_encode($input);

hex encodes the $input string and returns the result.

hex_decode(input)

  $output = hex_decode($input);
 
 

hex decodes the $input string and returns the result in $output, or undef if unable to decode $input.

attrs_encode(attrs);

  $output = attrs_encode($attrs);
 
 

Takes as input $attrs (which must be a reference to a hash) and returns a string of the encoded attributes in $output. The values in the $attrs hash table get converted to strings if they aren't already.

attrs_decode(input);

  $attrs = attrs_decode($input);
 
 

attr decodes the $input string and returns the result in $attrs as a reference to a hash, or croaks in case of an error.

random_bytes(length)

  $bytes = random_bytes($length);
 
 

Returns the specified number of random bytes, or undef if random data was unavailable. The returned data is suitable for nonces, but not necessarily for keys. Use random_key to generate a suitable random key.

random_key(length)

  $key_material = random_key($length);
 
 

Returns the specified number of random bytes, or undef if random data was unavailable. The returned data is suitable for use as a key. Use the constants WA_AES_128, WA_AES_192, and WA_AES_256 to specify a 128 bit, 192 bit, or 256 bit AES key respectively.

key_create(type, key_material)

  $key = key_create($type, $key_material);
 
 

Creates a reference to a WEBAUTH_KEYPtr object, or undef on error. $type must be WA_AES_KEY, and $key_material must be a string with a length of WA_AES_128, WA_AES_192, or WA_AES_256 bytes. $key should be set to undef when the key is no longer needed.

keyring_new(initial_capacity)

  $ring = keyring_new($initial_capacity);
 
 

Creates a reference to a WEBAUTH_KEYRINGPtr object, or undef on error.

keyring_add(ring, creation_time, valid_after, key)

  keyring_add($ring, $c, $vf, $vt, $key);
 
 

Adds a key to the keyring. creation_time and valid_after can both be 0, in which case the current time is used. key is copied internally, and can be undef'd after calling this function.

keyring_write_file(ring, path)

  keyring_write_file($ring, $path);
 
 

Writes a key ring to a file.

keyring_read_file(path)

  $ring = keyring_read_file($path);
 
 

Reads a keyring from a file and returns it in $ring on success.

token_create(attrs, hint, key_or_ring)

   $token = token_create($attrs, $hint, $key_or_ring);
 
 

Takes as input $attrs (which must be a reference to a hash) and $key_or_ring (created with keyring_new or key_create) and returns the encrypted token. If hint is 0, the current time will be used.

The values in the $attrs hash table get converted to strings if they aren't already.

token_parse(token, ttl, key_or_ring)

   $attrs = token_parse($token, $ttl, $key_or_ring);
 
 

Takes as input an encrypted token and a key_or_ring (created with keyring_new or key_create) and returns the attributes.

krb5_new()

   $context = krb5_new();
 
 

Creates a new WEBAUTH_KRB5_CTXT reference in $context.

krb5_keep_cred_cache(context)

   krb5_keep_cred_cache($context);
 
 

If called before $context is no longer in use, prevents the credential cache (created via one of the calls to krb5_init_via*) from being destroyed. This should only be used you need to keep a file-based credential cache from being removed.

krb5_init_via_password(context, user, password, keytab, server_principal[, cache])

    ($principal) = krb5_init_via_password($context, $user, $password, 
                                          $keytab, $server_principal[, $cache]);
 
 

Initializes a context using the specified username/password to obtain a TGT. The TGT will be verified using the principal in the keytab by doing a krb5_mk_req/krb5_rd_req. If $cache is not specified, a memory cache will be used and destroyed when the context is destroyed.

If $server_princpal is undef or "", then the first princpal found in the keytab will be used.

Returns the server principal used to verify the TGT.

krb5_init_via_keytab(context, keytab, server_princpal, [, cache])

    krb5_init_via_keytab($context, $keytab, $server_princpal[, $cache]);
 
 

Initializes a context using the principal in the specified keytab by getting a TGT. If $cache is not specified, a memory cache will be used and destroyed when the context is destroyed.

If $server_princpal is undef or "", then the first princpal found in the keytab will be used.

krb5_init_via_cache(context[, cache])

    krb5_init_via_cache($context, "/tmp/krb5cc_foo");
 
 

Initializes a context using the specified ticket cache. If $cache is not specified, the default kerberos ticket cache is used.

krb5_init_via_cred(context, cred[, cache])

    krb5_init_via_cred($context, $cred[, $cache]);
 
 

Initializes a context using a ticket that was previously exported using krb5_export_*. If $cache is not specified, a memory cache will be used and destroyed when the context is destroyed.

krb5_export_tgt(context)

   ($tgt, $expiration) = krb5_export_tgt($context)
 
 

Used to ``export'' a TGT from the specified context, which should have been initialized via one of the krb5_init_via_* functions. On success both $tgt and $expiration get set. $ticket is the ticket itself (binary data) and $expiration is the expiration time of the ticket.

krb5_import_cred(context, cred)

   krb5_import_cred($context, $cred);
 
 

Used to ``import'' a ticket that was created with krb5_export_*.

krb5_export_ticket(context, principal);

   ($ticket, $expiration) = krb5_export_ticket($context, $principal);
 
 

Used to ``export'' a ticket for the requested server principal. On success, both $ticket and $expiration will be set. $ticket is the ticket itself (binary data) and $expiration is the expiration time of the ticket.

krb5_service_principal(context, service, hostname)

     $principal = krb5_service_principal($context, $service, $hostname);
 
 

Used to construct a server principal for use with other calls such as krb5_mk_req and krb5_export_ticket. On success $principal will be set to the constructed principal, represented as a string.

krb5_get_principal(context, 1)

     $principal = krb5_getprincipal($context, 1);
 
 

Used to get the principal associated with the context. Should only be called after a successful call to krb5_init_via*. If local is 1, then krb5_aname_to_localname is called on the principal. If krb5_aname_to_localname returns an error then the fully-qualified principal name is returned.

krb5_mk_req(context, principal[,data])

     ($request[, $edata]) = krb5_mk_req($context, $principal[,$data]);
 
 

Used to construct a kerberos V5 request for the specified principal. $request will be set on success, and will contain the result of the krb5_mk_req call. If $data is passed in, tben it will be encrypted using krb5_mk_priv and returned as $edata.

krb5_rd_req(context, request, keytab, server_principal, local[, edata])

    ($principal[, $data]) 
       = krb5_rd_req($context, $request, $keytab, 
                               $server_princpal, 1[, $edata]);
 
 

Used to read a request created with krb5_mk_req. On success $principal will be set to the client principal in the request. If local is 1, then krb5_aname_to_localname is called on the principal. If krb5_aname_to_localname returns an error then the fully-qualified principal name is returned.

If $server_princpal is undef or "", then the first princpal found in the keytab will be used.

If $edata is passed in, it is decrypted with krb5_rd_priv.

WebAuth::Exception

The various WebAuth functions can all throw exceptions if something wrong happens. These exceptions will be of type WebAuth::Exception.

For example:

   eval {  
     $data = WebAuth::base64_decode($buffer);
     ...
   };
   if (WebAuth::Exception::match($@)) {
     my $e = $@;
     # you can call the following methods on an Exception object:
     # $e->status()
     # $e->error_message()
     # $e->detail_message()
     # $e->krb5_error_code()
     # $e->krb5_error_message()
     # $e->verbose_message()
   }
 
 

match($exception[, $status])

   This class function (not a method) returns true if the given
   $exception is a WebAuth::Exception. If $status is specified, then
   $exception->status() will also be compared to $status.
 
 

status()

   This method returns the WebAuth status code for the exception,
   which will be one of the WA_ERR_* codes.
 
 

error_message()

   This method returns the WebAuth error message for the status code,
   using the WebAuth::error_message function.
 
 

detail_message()

   This method returns the "detail" message in the exception. The detail
   message is additional information created with the exception when
   it is raised, and is usually the name of the WebAuth C function that
   raised the exception.
 
 

krb5_error_code()

   If the status of the exception is WA_ERR_KRB5, then this function
   will return the Kerberos V5 error code that caused the exception.
   There are currently no constants defined for these error codes.
 
 

krb5_error_message()

   If the status of the exception is WA_ERR_KRB5, then this function
   will return the Kerberos V5 error message corresponding to the
   krb5_error_code.
 
 

verbose_message()

   This method returns a verbose error message, which consists
   of all information available in the exception, including the
   status code, error message, line number and file, and any detail
   message in the exception. It also will include the kerberos
   error code and error message if status is WA_ERR_KRB5.
 
   The verbose_message method is also called if the exception is
   used as a string.
 
 

CONSTANTS

The following constants from webauth.h are available:

   WA_ERR_NONE
   WA_ERR_NO_ROOM
   WA_ERR_CORRUPT
   WA_ERR_NO_MEM
   WA_ERR_BAD_HMAC
   WA_ERR_RAND_FAILURE
   WA_ERR_BAD_KEY
   WA_ERR_KEYRING_OPENWRITE
   WA_ERR_KEYRING_WRITE
   WA_ERR_KEYRING_OPENREAD
   WA_ERR_KEYRING_READ
   WA_ERR_KEYRING_VERISON
   WA_ERR_NOT_FOUND
   WA_ERR_KRB5
   WA_ERR_INVALID_CONTEXT
   WA_ERR_LOGIN_FAILED
   WA_ERR_TOKEN_EXPIRED
   WA_ERR_TOKEN_STALE
 
   WA_PEC_SERVICE_TOKEN_EXPIRED
   WA_PEC_SERVICE_TOKEN_INVALID
   WA_PEC_PROXY_TOKEN_EXPIRED
   WA_PEC_PROXY_TOKEN_INVALID
   WA_PEC_INVALID_REQUEST
   WA_PEC_UNAUTHORIZED
   WA_PEC_SERVER_FAILURE
   WA_PEC_REQUEST_TOKEN_STALE
   WA_PEC_REQUEST_TOKEN_INVALID
   WA_PEC_GET_CRED_FAILURE
   WA_PEC_REQUESTER_KRB5_CRED_INVALID
   WA_PEC_LOGIN_TOKEN_STALE
   WA_PEC_LOGIN_TOKEN_INVALID
   WA_PEC_LOGIN_FAILED
   WA_PEC_PROXY_TOKEN_REQUIRED
   WA_PEC_LOGIN_CANCELED
   WA_PEC_LOGIN_FORCED
   WA_PEC_USER_REJECTED
 
   WA_AES_KEY
   WA_AES_128
   WA_AES_192
   WA_AES_256
 
   WA_TK_APP_STATE
   WA_TK_COMMAND
   WA_TK_CRED_DATA
   WA_TK_CRED_SERVER
   WA_TK_CRED_TYPE
   WA_TK_CREATION_TIME
   WA_TK_ERROR_CODE
   WA_TK_ERROR_MESSAGE
   WA_TK_EXPIRATION_TIME
   WA_TK_SESSION_KEY
   WA_TK_LASTUSED_TIME
   WA_TK_PASSWORD
   WA_TK_PROXY_TYPE
   WA_TK_PROXY_DATA
   WA_TK_PROXY_SUBJECT
   WA_TK_REQUEST_OPTIONS
   WA_TK_REQUESTED_TOKEN_TYPE
   WA_TK_RETURN_URL
   WA_TK_SUBJECT
   WA_TK_SUBJECT_AUTH
   WA_TK_SUBJECT_AUTH_DATA
   WA_TK_TOKEN_TYPE
   WA_TK_USERNAME
   WA_TK_WEBKDC_TOKEN
 
 

AUTHOR

Roland Schemers (schemers@stanford.edu)

SEE ALSO

perl.