1package Authen::Krb5; 2 3use strict; 4use Carp; 5use vars qw($VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD); 6 7require 5.004; 8 9require Exporter; 10require DynaLoader; 11require AutoLoader; 12 13@ISA = qw(Exporter DynaLoader); 14 15@EXPORT = qw( 16 ADDRTYPE_ADDRPORT 17 ADDRTYPE_CHAOS 18 ADDRTYPE_DDP 19 ADDRTYPE_INET 20 ADDRTYPE_IPPORT 21 ADDRTYPE_ISO 22 ADDRTYPE_XNS 23 AP_OPTS_MUTUAL_REQUIRED 24 AP_OPTS_RESERVED 25 AP_OPTS_USE_SESSION_KEY 26 AP_OPTS_USE_SUBKEY 27 AP_OPTS_WIRE_MASK 28 KDC_OPT_ALLOW_POSTDATE 29 KDC_OPT_ENC_TKT_IN_SKEY 30 KDC_OPT_FORWARDABLE 31 KDC_OPT_FORWARDED 32 KDC_OPT_POSTDATED 33 KDC_OPT_PROXIABLE 34 KDC_OPT_PROXY 35 KDC_OPT_RENEW 36 KDC_OPT_RENEWABLE 37 KDC_OPT_RENEWABLE_OK 38 KDC_OPT_VALIDATE 39 KRB5_AUTH_CONTEXT_DO_SEQUENCE 40 KRB5_AUTH_CONTEXT_DO_TIME 41 KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR 42 KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR 43 KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR 44 KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 45 KRB5_AUTH_CONTEXT_RET_SEQUENCE 46 KRB5_AUTH_CONTEXT_RET_TIME 47 KRB5_NT_PRINCIPAL 48 KRB5_NT_SRV_HST 49 KRB5_NT_SRV_INST 50 KRB5_NT_SRV_XHST 51 KRB5_NT_UID 52 KRB5_NT_UNKNOWN 53 KRB5_TGS_NAME 54); 55$VERSION = '1.6'; 56 57sub KRB5_TGS_NAME() { return "krbtgt"; } 58 59bootstrap Authen::Krb5 $VERSION; 60 61# Preloaded methods go here. 62 63sub AUTOLOAD { 64 # This AUTOLOAD is used to 'autoload' constants from the constant() 65 # XS function. If a constant is not found then control is passed 66 # to the AUTOLOAD in AutoLoader. 67 68 my $constname; 69 ($constname = $AUTOLOAD) =~ s/.*:://; 70 my $val = constant($constname, @_ ? $_[0] : 0); 71 if ($! != 0) { 72 if ($! =~ /Invalid/) { 73 $AutoLoader::AUTOLOAD = $AUTOLOAD; 74 goto &AutoLoader::AUTOLOAD; 75 } 76 else { 77 croak "Your vendor has not defined Krb5 macro $constname"; 78 } 79 } 80 eval "sub $AUTOLOAD { $val }"; 81 goto &$AUTOLOAD; 82} 83 84# Autoload methods go after =cut, and are processed by the autosplit program. 85 861; 87__END__ 88 89=head1 NAME 90 91Authen::Krb5 - Perl extension for Kerberos 5 92 93=head1 SYNOPSIS 94 95use Authen::Krb5; 96 97Authen::Krb5::init_context(); 98 99=head1 DESCRIPTION 100 101Authen::Krb5 is an object oriented interface to the Kerberos 5 API. Both the 102implementation and documentation are nowhere near complete, and may require 103previous experience with Kerberos 5 programming. Most of the functions here 104are documented in detail in the Kerberos 5 API documentation. 105 106=head2 FUNCTIONS 107 108=over 4 109 110=item error(n) 111 112Returns the error code from the most recent Authen::Krb5 call. If provided 113with an error code 'n', this function will return a textual description of the 114error. 115 116=item init_context() 117 118Initializes a context for the application. Returns a Authen::Krb5::Context 119object, or undef if there was an error. 120 121=item init_ets() (DEPRECATED) 122 123Initializes the Kerberos error tables. Should be called along with 124init_context at the beginning of a script. 125 126=item get_default_realm() 127 128Returns the default realm of your host. 129 130=item get_host_realm(host) 131 132Returns the realm of the specified host. 133 134=item get_krbhst(realm) 135 136Returns a list of the Kerberos servers from the specified realm. 137 138=item build_principal_ext(p) 139 140Not like the actual krb5_build_principal_ext. This is legacy code from 141Malcolm's code, which I'll probably change in future releases. In any case, 142it creates a 'server' principal for use in getting a TGT. Pass it the 143principal for which you would like a TGT. 144 145=item parse_name(name) 146 147Converts a string representation of a principal to a principal object. You 148can use this to create a principal from your username. 149 150=item sname_to_principal(hostname,sname,type) 151 152Generates a server principal from the given hostname, service, and type. 153Type can be one of the following: NT_UNKNOWN, NT_PRINCIPAL, NT_SRV_INST, 154NT_SRV_HST, NT_SRV_XHST, NT_UID. See the Kerberos documentation for details. 155 156=item cc_resolve(name) 157 158Returns a credentials cache identifier which corresponds to the given name. 159'name' must be in the form TYPE:RESIDUAL. See the Kerberos documentation 160for more information. 161 162=item cc_default_name() 163 164Returns the name of the default credentials cache, which may be equivalent 165to KRB5CCACHE. 166 167=item cc_default() 168 169Returns a Authen::Krb5::Ccache object representing the default credentials 170cache. 171 172=item kt_resolve(name) 173 174Returns a Authen::Krb5::Keytab object representing the specified keytab name. 175 176=item kt_default_name() 177 178Returns a sting containing the default keytab name. 179 180=item kt_default() 181 182Returns an Authen::Krb5::Keytab object representing the default keytab. 183 184=item kt_read_service_key(name, principal[, kvno, enctype]) 185 186Searches the keytab specified by I<name> (the default keytab if 187I<name> is undef) for a key matching I<principal> (and optionally 188I<kvno> and I<enctype>) and returns the key in the form of an 189Authen::Krb5::Keyblock object. 190 191=item get_in_tkt_with_password(client,server,password,cc) 192 193Attempt to get an initial ticket for the client. 'client' is a principal 194object for which you want an initial ticket. 'server' is a principal object 195for the service (usually krbtgt/REALM@REALM). 'password' is the password for 196the client, and 'cc' is a Authen::Krb5::Ccache object representing the current 197credentials cache. Returns a Kerberos error code. 198 199=item get_in_tkt_with_keytab(client,server,keytab,cc) 200 201Obtain an initial ticket for the client using a keytab. 'client' is a 202principal object for which you want an initial ticket. 'server' is a principal 203object for the service (usually krbtgt/REALM@REALM). 'keytab' is a keytab 204object createed with kt_resolve. 'cc' is a Authen::Krb5::Ccache object 205representing the current credentials cache. Returns a Kerberos error code. 206 207=item mk_req(auth_context,ap_req_options,service,hostname,in,cc) 208 209Obtains a ticket for a specified service and returns a KRB_AP_REQ message 210suitable for passing to rd_req. 'auth_context' is the Authen::Krb5::AuthContext 211object you want to use for this connection, 'ap_req_options' is an OR'ed 212representation of the possible options (see Kerberos docs), 'service' is 213the name of the service for which you want a ticket (like 'host'), hostname 214is the hostname of the server, 'in' can be any user-specified data that can 215be verified at the server end, and 'cc' is your credentials cache object. 216 217=item rd_req(auth_context,in,server,keytab) 218 219Parses a KRB_AP_REQ message and returns its contents in a Authen::Krb5::Ticket 220object. 'auth_context' is the connection's Authen::Krb5::AuthContext object, 221'in' is the KRB_AP_REQ message (usually from mk_req), and server is the 222expected server's name for the ticket. 'keytab' is a Authen::Krb5::Keytab 223object for the keytab you want to use. Specify 'undef' or leave off to use 224the default keytab. 225 226=item mk_priv(auth_context,in) 227 228Encrypts 'in' using parameters specified in auth_context, and returns the 229encrypted data. Requires use of a replay cache. 230 231=item rd_priv(auth_context,in) 232 233Decrypts 'in' using parameters specified in auth_context, and returns the 234decrypted data. 235 236=item sendauth(auth_context,fh,version,client,server,options,in,in_creds,cc) 237 238Obtains and sends an authenticated ticket from a client program to a server 239program using the filehandle 'fh'. 'version' is an application-defined 240version string that recvauth compares to its own version string. 'client' 241is the client principal, e.g. username@REALM. 'server' is the service 242principal to which you are authenticating, e.g. service.hostname@REALM. 243The only useful option right now is AP_OPTS_MUTUAL_REQUIRED, which forces 244sendauth to perform mutual authentication with the server. 'in' is a string 245that will be received by recvauth and verified by the server--it's up to the 246application. 'in_creds' is not yet supported, so just use 'undef' here. 'cc' 247should be set to the current credentials cache. sendauth returns true 248on success and undefined on failure. 249 250=item recvauth(auth_context,fh,version,server,keytab) 251 252Receives authentication data from a client using the sendauth function through 253the filehandle 'fh'. 'version' is as described in the sendauth section. 254'server' is the server principal to which the client will be authenticating. 255'keytab' is a Authen::Krb5::Keytab object specifying the keytab to use for this 256service. recvauth returns a Authen::Krb5::Ticket object on success or 257undefined on failure. 258 259=item genaddrs(auth_context,fh,flags) 260 261Uses the open socket filehandle 'fh' to generate local and remote addresses 262for auth_context. Flags should be one of the following, depending on the 263type of address you want to generate (flags can be OR'ed): 264 265KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR 266KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR 267KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR 268KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 269 270=item gen_portaddr(addr,port) 271 272Generates a local port address that can be used to name a replay cache. 'addr' is a Authen::Krb5::Address object, and port is a port number in network byte 273order. For generateing a replay cache name, you should supply the local 274address of the client and the socket's local port number. Returns a 275Authen::Krb5::Address object containing the address. 276 277=item gen_replay_name(addr,string) 278 279Generate a unique replay cache name. 'addr' is a Authen::Krb5::Address object 280created by gen_portaddr. 'string' is used as a unique identifier for the 281replay cache. Returns the replay cache name. 282 283=item get_server_rcache(name) 284 285Returns a Authen::Krb5::Rcache object using the replay cache name 'name.' 286 287=back 288 289=head2 CLASSES & METHODS 290 291=over 4 292 293=item Authen::Krb5::Principal 294 295Kerberos 5 princpal object. 296 297=over 4 298 299=item o realm 300 301Returns the realm of the principal. 302 303=item o type 304 305Returns the type of the principal. 306 307=item o data 308 309Returns a list containing the components of the principal (everything before 310the realm). 311 312=back 313 314=item Authen::Krb5::Ccache 315 316Kerberos 5 credentials cache object. 317 318=over 4 319 320=item o initialize(p) 321 322Creates/refreshes a credentials cache for the primary principal 'p'. If the 323cache already exists, its contents are destroyed. 324 325=item o get_name 326 327Returns the name of the credentials cache. 328 329=item o get_principal 330 331Returns the primary principal of the credentials cache. 332 333=item o destroy 334 335Destroys the credentials cache and releases all resources it used. 336 337=item o start_seq_get() 338 339Returns a cursor that can be passed to I<next_cred()> to read in turn 340every credential in the cache. 341 342=item o next_cred(cursor) 343 344Returns the next credential in the cache as an Authen::Krb5::Creds 345object. 346 347=item o end_seq_get(cursor) 348 349Perform cleanup opreations after I<next_cred()> and invalidates 350I<cursor>. 351 352=back 353 354=item Authen::Krb5::KeyBlock 355 356Kerberos 5 keyblock object. 357 358=over 4 359 360=item o enctype() 361 362Returns the encryption type ID. 363 364=item o enctype_string() 365 366Returns a text description of the encryption type. 367 368=item o length() 369 370Returns the length of the session key. 371 372=item o contents() 373 374Returns the actual contents of the keyblock (the session key). 375 376=back 377 378=item Authen::Krb5::AuthContext 379 380Kerberos 5 auth_context object. 381 382=over 4 383 384=item o new 385 386Allocates memory for a new Authen::Krb5::AuthContext object and returns it. 387 388=item o setaddrs(localaddr,remoteaddr) 389 390Sets the local and remote addresses for the AuthContext object. 'localaddr' 391and 'remoteaddr' are Authen::Krb5::Address objects, usually of type 392ADDRTYPE_INET. 393 394=item o getaddrs() 395 396Returns a list containing the local and the remote address of the 397AuthContext object. 398 399=item o setrcache(rc) 400 401Sets the replay cache for auth_context. 'rc' is a Authen::Krb5::Rcache object 402generated by get_server_rcache. 403 404=item o getkey() 405 406Retrieves the session key as an Authen::Krb5::KeyBlock object. 407 408=back 409 410=item Authen::Krb5::Ticket 411 412Kerberos 5 ticket object. 413 414=over 4 415 416=item o server 417 418Returns the server stored in the ticket. 419 420=item o enc_part2 421 422Returns a Authen::Krb5::EncTktPart object representation of the ticket data. 423See below. 424 425=back 426 427=item Authen::Krb5::EncTktPart 428 429Object representation of the krb5_enc_tkt_part structure. 430 431=over 4 432 433=item o client 434 435The client principal contained in the ticket. 436 437=back 438 439=item Authen::Krb5::Keyblock 440 441Object representation of the krb5_keyblock structure. 442 443=over 4 444 445=item o enctype 446 447The integral enctype of the key. 448 449=item o length 450 451Length of the key. 452 453=item o contents 454 455Contents of the key itself, as a string. 456 457=back 458 459=item Authen::Krb5::Keytab 460 461=over 4 462 463=item o add_entry(entry) 464 465Adds I<entry> to the keytab. 466 467=item o remove_entry(entry) 468 469Removes I<entry> from the keytab. 470 471=item o get_name() 472 473Returns the name of the keytab. 474 475=item o get_entry(principal[, kvno, enctype]) 476 477Returns an Authen::Krb5::KeytabEntry object representing an entry in 478the keytab matching I<principal> and optionally I<kvno> and 479I<enctype>. 480 481=item o start_seq_get() 482 483Returns a cursor that can be passed to I<next_entry()> to read in turn 484every key in the keytab. 485 486=item o next_entry(cursor) 487 488Returns the next entry in the keytab as an Authen::Krb5::KeytabEntry 489object. 490 491=item o end_seq_get(cursor) 492 493Perform cleanup opreations after I<next_entry()> and invalidates 494I<cursor>. 495 496=back 497 498=item Authen::Krb5::KeytabEntry 499 500=over 4 501 502=item o new(principal, kvno, keyblock) 503 504Create a new Authen::Krb5::KeytabEntry object from an 505Authen::Krb5::Principal object, a key version number, and an 506Authen::Krb5::Keyblock object. 507 508=item o principal 509 510An Authen::Krb5::Principal object representing the principal contained 511in the entry. 512 513=item o timestamp 514 515The timestamp of the entry. 516 517=item o kvno 518 519The key version number of the key contained in the entry. 520 521=item o key 522 523An Authen::Krb5::Keyblock object representing a copy of the keyblock 524contained in the entry. 525 526=back 527 528=head1 AUTHOR 529 530Jeff Horwitz (jeff@laserlink.net) 531 532=head1 ACKNOWLEDGEMENTS 533 534Based on the original work by Doug MacEachern and Malcolm Beattie. Code 535contributions from Scott Hutton (shutton@indiana.edu). 536 537=head1 SEE ALSO 538 539perl(1), kerberos(1). 540 541=cut 542