.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" 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" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" 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::Krb5 3pm" .TH WebAuth::Krb5 3pm "2014-03-20" "perl v5.14.2" "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::Krb5 \- WebAuth context for Kerberos calls .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use WebAuth qw(:const); \& use WebAuth::Krb5; \& \& my $wa = WebAuth\->new; \& eval { \& my $krb5 = WebAuth::Krb5\->new ($wa); \& $krb5\->init_via_keytab ($path); \& print $krb5\->get_principal (WA_KRB5_CANON_LOCAL); \& } \& if ($@) { \& # ... handle exception ... \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This Perl context represents a WebAuth Kerberos context. This context is used to make all Kerberos-related calls and can also store a Kerberos identity and its corresponding ticket cache. A context is normally initiated with credentials from a username and password, a keytab, an existing ticket cache, or an exported credential. .SH "CLASS METHODS" .IX Header "CLASS METHODS" As with WebAuth module functions, failures are signaled by throwing WebAuth::Exception rather than by return status. .IP "new (\s-1WEBAUTH\s0)" 4 .IX Item "new (WEBAUTH)" Create a new WebAuth::Krb5 object attached to the WebAuth context \s-1WEBAUTH\s0. This is a convenience wrapper around the WebAuth \fIkrb5_new()\fR method. .SH "INSTANCE METHODS" .IX Header "INSTANCE METHODS" As with WebAuth module functions, failures are signaled by throwing WebAuth::Exception rather than by return status. .IP "change_password (PASSWORD[, \s-1ARGS\s0])" 4 .IX Item "change_password (PASSWORD[, ARGS])" Change the password of the user represented by the Kerberos context to \&\s-1PASSWORD\s0. The WebAuth::Krb5 object must already contain the credentials required to change a password (normally a kadmin/changepw credential created with \fIkrb5_init_via_password()\fR or read from a context created that way using \fIkrb5_init_via_cred()\fR). .Sp By default, the kpasswd protocol is used to do the password change. This behavior can be modified using the optional \s-1ARGS\s0 argument which, if present, should be a reference to a hash with one or more of the following keys: .RS 4 .IP "command" 4 .IX Item "command" The command to send. Currently only used for the \f(CW\*(C`remctl\*(C'\fR password change protocol. .IP "host" 4 .IX Item "host" The host to which to send the password change. Currently only used for the \f(CW\*(C`remctl\*(C'\fR password change protocol. .IP "identity" 4 .IX Item "identity" The Kerberos principal of the password change service to which this command will authenticate in order to send the change. The default depends on the protocol. Currently this is only used for the \f(CW\*(C`remctl\*(C'\fR password change protocol, which defaults to the normal principal used by remctl clients when sending commands. However, normally this will be a principal that disallows TGS-REQ authentications rather than the remctl default. .Sp If this principal disallows TGS-REQ authentications, credentials for this principal must already be present in the WebAuth::Krb5 object before making this call since they cannot be retrieved from the \s-1KDC\s0 without additional authentication credentials. .IP "port" 4 .IX Item "port" The port on the password change host to contact. Currently only used for the \f(CW\*(C`remctl\*(C'\fR password change protocol. .IP "protocol" 4 .IX Item "protocol" The password change protocol to use. Currently supported values are \&\f(CW\*(C`kpasswd\*(C'\fR and \f(CW\*(C`remctl\*(C'\fR. \f(CW\*(C`kpasswd\*(C'\fR is the default and takes no further parameters, so in that case \s-1ARGS\s0 should normally be omitted. This key should normally always be set. .IP "subcommand" 4 .IX Item "subcommand" The subcommand to send. Currently only used for the \f(CW\*(C`remctl\*(C'\fR password change protocol. .IP "timeout" 4 .IX Item "timeout" How long to wait, in integer seconds, for a reply before giving up. Currently only used for the \f(CW\*(C`remctl\*(C'\fR password change protocol. .RE .RS 4 .Sp An example of doing a password change via the remctl protocol, using \&\f(CW\*(C`kadmin/changepw\*(C'\fR as the service principal and taking the other options from global configuration, with a ten-second timeout: .Sp .Vb 10 \& my $wa = WebAuth\->new; \& my $krb5 = WebAuth::Krb5\->new ($wa); \& $krb5\->init_via_password (\*(Aquser\*(Aq, \*(Aqpassword\*(Aq, \*(Aqkadmin/changepw\*(Aq); \& my $args = { \& protocol => \*(Aqremctl\*(Aq, \& host => $PASSWORD_CHANGE_SERVER, \& port => $PASSWORD_CHANGE_PORT, \& identity => \*(Aqkadmin/changepw\*(Aq, \& command => $PASSWORD_CHANGE_COMMAND, \& subcommand => $PASSWORD_CHANGE_SUBCOMMAND, \& timeout => 10, \& }; \& $krb5\->change_password (\*(Aqnew\-password\*(Aq, $args); .Ve .Sp For the \f(CW\*(C`remctl\*(C'\fR protocol, the server must expose a command and subcommand that takes a single argument, the new password, and changes the password of the authenticated user. .RE .IP "export_cred ([\s-1PRINC\s0])" 4 .IX Item "export_cred ([PRINC])" Exports either a Kerberos \s-1TGT\s0 or a Kerberos service ticket obtained using the credentials in the WebAuth::Krb5 context, have been initialized via one of the init_via_* methods or import_cred first. In a scalar context, returns the encoded Kerberos ticket (as binary data), suitable for passing to \fIimport_cred()\fR or putting into a WebAuth token. In a list context, returns a two-element list consisting of the encoded Kerberos ticket and the expiration time of the ticket in seconds since epoch. .IP "get_principal ([\s-1CANON\s0])" 4 .IX Item "get_principal ([CANON])" Returns the principal associated with the Kerberos context, which should have been initialized via one of the init_via_* methods or import_cred first. \s-1CANON\s0 should be one of \s-1WA_KRB5_CANON_NONE\s0 (specifying no principal canonicalization), \s-1WA_KRB5_CANON_LOCAL\s0 (specifying that the principal should be converted to a local name if possible), or \s-1WA_KRB5_CANON_STRIP\s0 (specifying that any realm information should be stripped). These constants are provided by the WebAuth module. .Sp If \s-1WA_KRB5_CANON_LOCAL\s0 is specified but krb5_aname_to_localname returns an error, the fully-qualified principal will be returned. .Sp If \s-1CANON\s0 is not specified, \s-1WA_KRB5_CANON_NONE\s0 is the default behavior. .IP "import_cred (CRED[, \s-1CACHE\s0])" 4 .IX Item "import_cred (CRED[, CACHE])" Imports the provided credential, created with export_cred, into the given Kerberos context. If the context is not already initialized, it will be initialized with the identity specified by the credential. \s-1CACHE\s0 specifies where to store the credential cache for this context and will be used only if the context is not already initialized. If \s-1CACHE\s0 is not specified and the context is not initialized, a memory cache will be used and destroyed when the context is destroyed. .IP "init_via_cache ([\s-1CACHE\s0])" 4 .IX Item "init_via_cache ([CACHE])" Initializes a Kerberos context from an existing ticket cache. If \s-1CACHE\s0 is not specified, the default Kerberos ticket cache is used. .IP "init_via_keytab (KEYTAB[, PRINC[, \s-1CACHE\s0]])" 4 .IX Item "init_via_keytab (KEYTAB[, PRINC[, CACHE]])" Initializes a Kerberos context by using the keys in the provided \s-1KEYTAB\s0 to get a Kerberos \s-1TGT\s0. If \s-1CACHE\s0 is not specified, a memory cache will be used and destroyed when the context is destroyed. .Sp \&\s-1PRINC\s0 specifies the principal for which to get tickets. If it is not specified, the first principal found in \s-1KEYTAB\s0 will be used. .IP "init_via_password (\s-1USER\s0, PASS[, PRINC[, KEYTAB[, SPRINC[, \s-1CACHE\s0]]]])" 4 .IX Item "init_via_password (USER, PASS[, PRINC[, KEYTAB[, SPRINC[, CACHE]]]])" Initializes a Kerberos context using the specified username/password to obtain a Kerberos \s-1TGT\s0. If \s-1KEYTAB\s0 is specified and \s-1PRINC\s0 is not given, the \&\s-1TGT\s0 will be verified using the normal krb5_verify_init_creds function. If \&\s-1CACHE\s0 is not specified, a memory cache will be used and destroyed when the context is destroyed. .Sp If \s-1SPRINC\s0 is given, it specifies the principal in \s-1KEYTAB\s0 to use for the validation. If it is not specified, undef, or the empty string, the first principal found in \s-1KEYTAB\s0 will be used. .Sp If \s-1PRINC\s0 is given and defined, obtain credentials for that principal rather than a \s-1TGT\s0. This is normally used to get a context with a \&\f(CW\*(C`kadmin/changepw\*(C'\fR service ticket to use to change the user's password. If this is specified, the validity of the acquired credentials will not be verified. .Sp If \s-1KEYTAB\s0 is not given, the validity of the returned tickets are not verified. This should only be used when obtaining \f(CW\*(C`kadmin/changepw\*(C'\fR service tickets to change a password. Skipping this validation step otherwise opens one up to \s-1KDC\s0 impersonation attacks. .Sp Returns the server principal used to verify the \s-1TGT\s0 if \s-1KEYTAB\s0 is given and \s-1PRINC\s0 is not given. Otherwise, returns undef. .IP "make_auth (PRINC[, \s-1DATA\s0])" 4 .IX Item "make_auth (PRINC[, DATA])" Construct a Kerberos authenticator for the specified principal and return the authenticator, suitable for passing to krb5_rd_req (possibly by way of the read_auth method). If \s-1DATA\s0 is provided, it will be encrypted with krb5_mk_priv in the session key of the authenticator. .Sp In a scalar context, returns the authenticator as binary data. In a list context, when \s-1DATA\s0 is given, returns a two-element list consisting of the authenticator and the encrypted \s-1DATA\s0. .IP "read_auth (\s-1REQUEST\s0, KEYTAB[, PRINC[, CANON[, \s-1EDATA\s0]]])" 4 .IX Item "read_auth (REQUEST, KEYTAB[, PRINC[, CANON[, EDATA]]])" Read a \s-1REQUEST\s0 created with make_auth and returns the client principal of the authenticator. \s-1KEYTAB\s0 is used to decode the request, and \s-1PRINC\s0 must be the principal for which the \s-1REQUEST\s0 was encoded. If \s-1PRINC\s0 is not provided, undef, or the empty string, the first principal found in \s-1KEYTAB\s0 will be used. .Sp The returned client principal is canonicalized following the rule specified in \s-1CANON\s0, following the same rules as in \fIget_principal()\fR. If \&\s-1CANON\s0 is not specified, \s-1WA_KRB5_CANON_NONE\s0 is the default behavior. .Sp If \s-1EDATA\s0 is provided, it is decrypted with krb5_rd_priv, and the return value in a list context will be a two-element list containing the principal and the decrypted data. .SH "CAVEATS" .IX Header "CAVEATS" A WebAuth::Krb5 object will retain a reference to the WebAuth object that was used to create it and will prevent the WebAuth context from being freed until the WebAuth::Krb5 object can be freed. This ensures that objects don't disappear at inappropriate times, but it also means that no memory allocated in the WebAuth context, even if unrelated to the WebAuth::Krb5 object, will be freed until all objects created from it are freed. Creating and holding on to references to WebAuth::Krb5 objects for long periods may therefore result in unexpected memory usage. .SH "AUTHOR" .IX Header "AUTHOR" Russ Allbery .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIWebAuth\fR\|(3) .PP This module is part of WebAuth. The current version is available from .