.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "WebAuth 3pm" .TH WebAuth 3pm "2019-01-05" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" WebAuth \- Perl extension for WebAuth .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use WebAuth; \& \& my $wa = WebAuth\->new; \& eval { \& $key = $wa\->random_key(WebAuth::WA_AES_128); \& ... \& }; \& if ($@) { \& # handle exception \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" WebAuth is a low-level Perl interface into the WebAuth C \s-1API.\s0 It mostly follows the C \s-1API\s0 but rearranges the calls into an object-oriented structure and changes the behavior of some methods to be more Perl-like. .PP Before calling any of the functions, obtain a new WebAuth object with \&\f(CW\*(C`WebAuth\->new\*(C'\fR. All subsequent functions take that object as their first parameter, or should be called as methods on that object, and other returned objects will normally have that context as hidden data. This object represents the WebAuth context. If the WebAuth object goes out of scope, all other objects created from it, such as keys and keyrings, will also become invalid. The caller therefore must be careful to ensure that no references to other objects are kept around after the WebAuth object is destroyed. .PP All and methods 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 WebAuth::Exception for more information. .PP In some cases, objects in other classes may be returned by methods. Those classes are documented in their own manual or \s-1POD\s0 pages. .SH "EXPORT" .IX Header "EXPORT" Nothing is exported by default, but the following export tags are available: .IP "const" 8 .IX Item "const" Exports the WA_* constants. For a complete list, see \*(L"\s-1CONSTANTS\*(R"\s0. .PP To import all constants, use: .PP .Vb 1 \& use WebAuth qw(:const); .Ve .PP Individual constants can be imported instead, of course. .SH "CLASS METHODS" .IX Header "CLASS METHODS" As described above, on any error not explicitly documented below, these methods will throw a WebAuth::Exception object. .IP "new ()" 4 .IX Item "new ()" Create a new WebAuth context object and return it. Remember that all other objects created from this context, such as keys, keyrings, and tokens, will be destroyed when this context is destroyed, even though Perl isn't aware of this. .SH "INSTANCE METHODS" .IX Header "INSTANCE METHODS" As described above, on any error not explicitly documented below, these methods will throw a WebAuth::Exception object. .IP "error_message (\s-1STATUS\s0)" 4 .IX Item "error_message (STATUS)" Returns an error message string corresponding to \s-1STATUS,\s0 which should be one of the WA_ERR_* values. It's rare to need to use this method, since generally any error return from the WebAuth C \s-1API\s0 is converted into a WebAuth::Exception and thrown instead, and the WebAuth::Exception object will contain a more detailed error message. .IP "key_create (\s-1TYPE,\s0 SIZE[, \s-1KEY_MATERIAL\s0])" 4 .IX Item "key_create (TYPE, SIZE[, KEY_MATERIAL])" Create a new WebAuth::Key object. \s-1TYPE\s0 currently must be \s-1WA_KEY_AES,\s0 and \s-1SIZE\s0 must be one of \s-1WA_AES_128, WA_AES_192,\s0 or \s-1WA_AES_256.\s0 This may change in the future if WebAuth gains support for additional key types. .Sp If \s-1KEY_MATERIAL\s0 is given, it should contain \s-1SIZE\s0 bytes of data, which will be used as the key. If \s-1KEY_MATERIAL\s0 is not given or is undef, a new random key of the specified \s-1TYPE\s0 and \s-1SIZE\s0 will be generated. .Sp The WebAuth::Key object will be destroyed when the WebAuth context used to create it is destroyed, and subsequent accesses to it may cause memory access errors or other serious bugs. Be careful not to retain a copy of a WebAuth::Key object after the WebAuth object that created it has been destroyed. .IP "keyring_new (\s-1KEY\s0)" 4 .IX Item "keyring_new (KEY)" .PD 0 .IP "keyring_new (\s-1SIZE\s0)" 4 .IX Item "keyring_new (SIZE)" .PD Create a new WebAuth::Keyring object. This object holds WebAuth::Key objects and is used for token encryption and decryption. .Sp The argument to this method may be either a WebAuth::Key object or a numeric size. If a WebAuth::Key object is provided, a new keyring containing only that key will be created and returned. If a size is provided, a new, empty keyring with space preallocated to hold that many keys is created and returned. (Regardless of the allocated size of a keyring, keyrings will always dynamically expand to hold any new keys that are added to them.) .Sp The WebAuth::Keyring object will be destroyed when the WebAuth context used to create it is destroyed, and subsequent accesses to it may cause memory access errors or other serious bugs. Be careful not to retain a copy of a WebAuth::Keyring object after the WebAuth object that created it has been destroyed. .IP "keyring_decode (\s-1DATA\s0)" 4 .IX Item "keyring_decode (DATA)" Create a new WebAuth::Keyring object by decoding \s-1DATA,\s0 which should be a keyring in its serialization format (as read from a file written by WebAuth::Keyring\->write or encoded with WebAuth::Keyring\->encode). All the caveats about the lifetime of the WebAuth::Keyring object mentioned for \&\fBkeyring_new()\fR also apply here. .IP "keyring_read (\s-1FILE\s0)" 4 .IX Item "keyring_read (FILE)" Create a new WebAuth::Keyring object by reading its contents from the provided file. The created keyring object will have no association with the file after being created; it won't automatically be saved, or updated when the file changes. All the caveats about the lifetime of the WebAuth::Keyring object mentioned for \fBkeyring_new()\fR also apply here. .IP "krb5_new ()" 4 .IX Item "krb5_new ()" Create a new WebAuth::Krb5 object and return it. This is used as a context for all Kerberos-related WebAuth calls. See WebAuth::Krb5 for supported methods. .IP "token_decode (\s-1INPUT, KEYRING\s0)" 4 .IX Item "token_decode (INPUT, KEYRING)" Given an encrypted and base64\-encoded token, decode and decrypt it using the provided WebAuth::Keyring object. The return value will be a subclass of WebAuth::Token. See WebAuth::Token for common methods and a list of possible token object types. .Sp Callers will normally want to check via \fBisa()\fR whether the returned token is of the type that the caller expected. Not performing that check can lead to security issues. .IP "token_decrypt (\s-1INPUT, KEYRING\s0)" 4 .IX Item "token_decrypt (INPUT, KEYRING)" Decrypt the input string, which should be raw encrypted token data (not base64\-encoded), using the provided keyring and return the decrypted data. .Sp This provides access to the low-level token decryption routine and should not normally be used. It's primarily available to aid in constructing test suites. \fBtoken_decode()\fR should normally be used instead. .IP "token_encrypt (\s-1INPUT, KEYRING\s0)" 4 .IX Item "token_encrypt (INPUT, KEYRING)" Encrypt the input string, which should be raw token attribute data, using the provided keyring and return the encrypted data. The encryption key used will be the one returned by the \fBbest_key()\fR method of WebAuth::Keyring on that \s-1KEYRING.\s0 .Sp This provides access to the low-level token encryption routine and should not normally be used. It's primarily available to aid in constructing test suites. A WebAuth::Token subclass and its \fBencode()\fR method should normally be used instead. .SH "CONSTANTS" .IX Header "CONSTANTS" This module also provides a variety of \s-1API\s0 constants for the WebAuth library. WebAuth \s-1API\s0 status codes used both for \s-1API\s0 calls and for login errors and error tokens: .PP .Vb 10 \& 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_PEC_CREDS_EXPIRED \& WA_PEC_MULTIFACTOR_REQUIRED \& WA_PEC_MULTIFACTOR_UNAVAILABLE \& WA_PEC_LOGIN_REJECTED \& WA_PEC_LOA_UNAVAILABLE \& WA_PEC_AUTH_REJECTED \& WA_PEC_AUTH_REPLAY \& WA_PEC_AUTH_LOCKOUT \& WA_PEC_LOGIN_TIMEOUT .Ve .PP Status codes used only for \s-1API\s0 calls: .PP .Vb 10 \& 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_FILE_OPENWRITE \& WA_ERR_FILE_WRITE \& WA_ERR_FILE_OPENREAD \& WA_ERR_FILE_READ \& WA_ERR_FILE_VERSION \& WA_ERR_NOT_FOUND \& WA_ERR_KRB5 \& WA_ERR_INVALID_CONTEXT \& WA_ERR_TOKEN_EXPIRED \& WA_ERR_TOKEN_STALE \& WA_ERR_APR \& WA_ERR_UNIMPLEMENTED \& WA_ERR_INVALID \& WA_ERR_REMOTE_FAILURE \& WA_ERR_FILE_NOT_FOUND \& WA_ERR_TOKEN_REJECTED .Ve .PP Key types for \fBkey_create()\fR and \f(CW\*(C`WebAuth::Key\->new\*(C'\fR: .PP .Vb 1 \& WA_KEY_AES .Ve .PP Key sizes for \fBkey_create()\fR and \f(CW\*(C`WebAuth::Key\->new\*(C'\fR: .PP .Vb 3 \& WA_AES_128 \& WA_AES_192 \& WA_AES_256 .Ve .PP Key usages for the \fBbest_key()\fR method of WebAuth::Keyring: .PP .Vb 2 \& WA_KEY_DECRYPT \& WA_KEY_ENCRYPT .Ve .PP Canonicalization modes for the \fBget_principal()\fR and \fBread_auth()\fR methods of WebAuth::Krb5: .PP .Vb 3 \& WA_KRB5_CANON_NONE \& WA_KRB5_CANON_LOCAL \& WA_KRB5_CANON_STRIP .Ve .SH "AUTHOR" .IX Header "AUTHOR" Roland Schemers, Jon Robertson , and Russ Allbery . .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBWebAuth::Exception\fR\|(3), \fBWebAuth::Key\fR\|(3), \fBWebAuth::Keyring\fR\|(3), \&\fBWebAuth::Token\fR\|(3) .PP This module is part of WebAuth. The current version is available from .