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.9'; 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_init_creds_password(client, password[, service]) 192 193Attempt to get an initial ticket for the client. 'client' is a principal 194object for which you want an initial ticket. 'password' is the password for 195the client. 'service', if given, is the string representation (not a 196principal object) for the ticket to acquire. If not given, it defaults to 197krbtgt/REALM@REALM for the local realm. Returns an Authen::Krb5::Creds 198object or undef on failure. 199 200=item get_init_creds_keytab(client, keytab[, service]) 201 202Attempt to get an inintial ticket for the client using a keytab. 'client' 203is a principal object for which you want an initial ticket. 'keytab' is a 204keytab object created with kt_resolve. 'service', if given, is the string 205representation (not a principal object) for the ticket to acquire. If not 206given, it defaults to krbtgt/REALM@REALM for the local realm. Returns an 207Authen::Krb5::Creds object or undef on failure. 208 209=item get_in_tkt_with_password(client,server,password,cc) 210 211Attempt to get an initial ticket for the client. 'client' is a principal 212object for which you want an initial ticket. 'server' is a principal object 213for the service (usually krbtgt/REALM@REALM). 'password' is the password 214for the client, and 'cc' is a Authen::Krb5::Ccache object representing the 215current credentials cache. Returns a Kerberos error code. 216 217Although this interface is deprecated in the Kerberos C libraries, it's 218supported in the Perl module. In this module, it's implemented in terms of 219krb5_get_init_creds_password, krb5_cc_initialize, and krb5_cc_store_cred. 220 221=item get_in_tkt_with_keytab(client,server,keytab,cc) 222 223Obtain an initial ticket for the client using a keytab. 'client' is a 224principal object for which you want an initial ticket. 'server' is a 225principal object for the service (usually krbtgt/REALM@REALM). 'keytab' is 226a keytab object createed with kt_resolve. 'cc' is a Authen::Krb5::Ccache 227object representing the current credentials cache. Returns a Kerberos error 228code. 229 230Although this interface is deprecated in the Kerberos C libraries, it's 231supported in the Perl module. In this module, it's implemented in terms of 232krb5_get_init_creds_keytab, krb5_cc_initialize, and krb5_cc_store_cred. 233 234=item mk_req(auth_context,ap_req_options,service,hostname,in,cc) 235 236Obtains a ticket for a specified service and returns a KRB_AP_REQ message 237suitable for passing to rd_req. 'auth_context' is the Authen::Krb5::AuthContext 238object you want to use for this connection, 'ap_req_options' is an OR'ed 239representation of the possible options (see Kerberos docs), 'service' is 240the name of the service for which you want a ticket (like 'host'), hostname 241is the hostname of the server, 'in' can be any user-specified data that can 242be verified at the server end, and 'cc' is your credentials cache object. 243 244=item rd_req(auth_context,in,server,keytab) 245 246Parses a KRB_AP_REQ message and returns its contents in a Authen::Krb5::Ticket 247object. 'auth_context' is the connection's Authen::Krb5::AuthContext object, 248'in' is the KRB_AP_REQ message (usually from mk_req), and server is the 249expected server's name for the ticket. 'keytab' is a Authen::Krb5::Keytab 250object for the keytab you want to use. Specify 'undef' or leave off to use 251the default keytab. 252 253=item mk_priv(auth_context,in) 254 255Encrypts 'in' using parameters specified in auth_context, and returns the 256encrypted data. Requires use of a replay cache. 257 258=item rd_priv(auth_context,in) 259 260Decrypts 'in' using parameters specified in auth_context, and returns the 261decrypted data. 262 263=item sendauth(auth_context,fh,version,client,server,options,in,in_creds,cc) 264 265Obtains and sends an authenticated ticket from a client program to a server 266program using the filehandle 'fh'. 'version' is an application-defined 267version string that recvauth compares to its own version string. 'client' 268is the client principal, e.g. username@REALM. 'server' is the service 269principal to which you are authenticating, e.g. service.hostname@REALM. 270The only useful option right now is AP_OPTS_MUTUAL_REQUIRED, which forces 271sendauth to perform mutual authentication with the server. 'in' is a string 272that will be received by recvauth and verified by the server--it's up to the 273application. 'in_creds' is not yet supported, so just use 'undef' here. 'cc' 274should be set to the current credentials cache. sendauth returns true 275on success and undefined on failure. 276 277=item recvauth(auth_context,fh,version,server,keytab) 278 279Receives authentication data from a client using the sendauth function through 280the filehandle 'fh'. 'version' is as described in the sendauth section. 281'server' is the server principal to which the client will be authenticating. 282'keytab' is a Authen::Krb5::Keytab object specifying the keytab to use for this 283service. recvauth returns a Authen::Krb5::Ticket object on success or 284undefined on failure. 285 286=item genaddrs(auth_context,fh,flags) 287 288Uses the open socket filehandle 'fh' to generate local and remote addresses 289for auth_context. Flags should be one of the following, depending on the 290type of address you want to generate (flags can be OR'ed): 291 292KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR 293KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR 294KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR 295KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 296 297=item gen_portaddr(addr,port) 298 299Generates 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 300order. For generateing a replay cache name, you should supply the local 301address of the client and the socket's local port number. Returns a 302Authen::Krb5::Address object containing the address. 303 304=item gen_replay_name(addr,string) 305 306Generate a unique replay cache name. 'addr' is a Authen::Krb5::Address object 307created by gen_portaddr. 'string' is used as a unique identifier for the 308replay cache. Returns the replay cache name. 309 310=item get_server_rcache(name) 311 312Returns a Authen::Krb5::Rcache object using the replay cache name 'name.' 313 314=back 315 316=head2 CLASSES & METHODS 317 318=over 4 319 320=item Authen::Krb5::Principal 321 322Kerberos 5 princpal object. 323 324=over 4 325 326=item o realm 327 328Returns the realm of the principal. 329 330=item o type 331 332Returns the type of the principal. 333 334=item o data 335 336Returns a list containing the components of the principal (everything before 337the realm). 338 339=back 340 341=item Authen::Krb5::Ccache 342 343Kerberos 5 credentials cache object. 344 345=over 4 346 347=item o initialize(p) 348 349Creates/refreshes a credentials cache for the primary principal 'p'. If the 350cache already exists, its contents are destroyed. 351 352=item o store_cred(creds) 353 354Stores the given credentials, which should be an Authen::Krb5::Creds object 355as returned from get_init_creds_password() or get_init_creds_keytab(), in 356the cache. 357 358=item o get_name 359 360Returns the name of the credentials cache. 361 362=item o get_principal 363 364Returns the primary principal of the credentials cache. 365 366=item o destroy 367 368Destroys the credentials cache and releases all resources it used. 369 370=item o start_seq_get() 371 372Returns a cursor that can be passed to I<next_cred()> to read in turn 373every credential in the cache. 374 375=item o next_cred(cursor) 376 377Returns the next credential in the cache as an Authen::Krb5::Creds 378object. 379 380=item o end_seq_get(cursor) 381 382Perform cleanup opreations after I<next_cred()> and invalidates 383I<cursor>. 384 385=back 386 387=item Authen::Krb5::KeyBlock 388 389Kerberos 5 keyblock object. 390 391=over 4 392 393=item o enctype() 394 395Returns the encryption type ID. 396 397=item o enctype_string() 398 399Returns a text description of the encryption type. 400 401=item o length() 402 403Returns the length of the session key. 404 405=item o contents() 406 407Returns the actual contents of the keyblock (the session key). 408 409=back 410 411=item Authen::Krb5::AuthContext 412 413Kerberos 5 auth_context object. 414 415=over 4 416 417=item o new 418 419Allocates memory for a new Authen::Krb5::AuthContext object and returns it. 420 421=item o setaddrs(localaddr,remoteaddr) 422 423Sets the local and remote addresses for the AuthContext object. 'localaddr' 424and 'remoteaddr' are Authen::Krb5::Address objects, usually of type 425ADDRTYPE_INET. 426 427=item o getaddrs() 428 429Returns a list containing the local and the remote address of the 430AuthContext object. 431 432=item o setrcache(rc) 433 434Sets the replay cache for auth_context. 'rc' is a Authen::Krb5::Rcache object 435generated by get_server_rcache. 436 437=item o getkey() 438 439Retrieves the session key as an Authen::Krb5::KeyBlock object. 440 441=back 442 443=item Authen::Krb5::Ticket 444 445Kerberos 5 ticket object. 446 447=over 4 448 449=item o server 450 451Returns the server stored in the ticket. 452 453=item o enc_part2 454 455Returns a Authen::Krb5::EncTktPart object representation of the ticket data. 456See below. 457 458=back 459 460=item Authen::Krb5::EncTktPart 461 462Object representation of the krb5_enc_tkt_part structure. 463 464=over 4 465 466=item o client 467 468The client principal contained in the ticket. 469 470=back 471 472=item Authen::Krb5::Keyblock 473 474Object representation of the krb5_keyblock structure. 475 476=over 4 477 478=item o enctype 479 480The integral enctype of the key. 481 482=item o length 483 484Length of the key. 485 486=item o contents 487 488Contents of the key itself, as a string. 489 490=back 491 492=item Authen::Krb5::Keytab 493 494=over 4 495 496=item o add_entry(entry) 497 498Adds I<entry> to the keytab. 499 500=item o remove_entry(entry) 501 502Removes I<entry> from the keytab. 503 504=item o get_name() 505 506Returns the name of the keytab. 507 508=item o get_entry(principal[, kvno, enctype]) 509 510Returns an Authen::Krb5::KeytabEntry object representing an entry in 511the keytab matching I<principal> and optionally I<kvno> and 512I<enctype>. 513 514=item o start_seq_get() 515 516Returns a cursor that can be passed to I<next_entry()> to read in turn 517every key in the keytab. 518 519=item o next_entry(cursor) 520 521Returns the next entry in the keytab as an Authen::Krb5::KeytabEntry 522object. 523 524=item o end_seq_get(cursor) 525 526Perform cleanup opreations after I<next_entry()> and invalidates 527I<cursor>. 528 529=back 530 531=item Authen::Krb5::KeytabEntry 532 533=over 4 534 535=item o new(principal, kvno, keyblock) 536 537Create a new Authen::Krb5::KeytabEntry object from an 538Authen::Krb5::Principal object, a key version number, and an 539Authen::Krb5::Keyblock object. 540 541=item o principal 542 543An Authen::Krb5::Principal object representing the principal contained 544in the entry. 545 546=item o timestamp 547 548The timestamp of the entry. 549 550=item o kvno 551 552The key version number of the key contained in the entry. 553 554=item o key 555 556An Authen::Krb5::Keyblock object representing a copy of the keyblock 557contained in the entry. 558 559=back 560 561=item Authen::Krb5::Creds 562 563Object representing a credential. 564 565=over 4 566 567=item o starttime() 568 569Returns the starttime time property of the credential. 570 571=item o authtime() 572 573Returns the authtime time property of the credential. 574 575=item o endtime() 576 577Returns the endtime time property of the credential. 578 579=item o renew_till() 580 581Returns the renew_till time property of the credential. 582 583=item o server() 584 585Returns the name of the service principal the credential is for. 586 587=item o client() 588 589Returns the client principal name (will usually be identical for all 590credentials in a credential cache). 591 592=item o ticket() 593 594Returns the Authen::Krb5::Ticket for this credential. 595 596=item o keyblock() 597 598Returns the keyblock of the credential. 599 600=back 601 602=head1 AUTHOR 603 604Jeff Horwitz (jeff@smashing.org) 605 606=head1 ACKNOWLEDGEMENTS 607 608Based on the original work by Doug MacEachern and Malcolm Beattie. Code 609contributions from Scott Hutton (shutton@indiana.edu). 610 611=head1 SEE ALSO 612 613perl(1), kerberos(1). 614 615=cut 616