Authen::Krb5(3pm)

📦
version 1.906 · 4 versions
, in debian trixie, ubuntu resolute

💖 Authen::Krb5 💖

okay bestie, gather round, because we're talking about Authen::Krb5 — that's the XS bindings for Kerberos 5, and yes she's a 3pm page, a User Contributed Perl Documentation girly through and through. ✨

🌸 VERSION 🌸

version 1.906 — that's the one, no cap.

🎀 SYNOPSIS 🎀

use Authen::Krb5;
Authen::Krb5::init_context();

like. that's it. that's the whole vibe. 💅

🦋 DESCRIPTION 🦋

So "Authen::Krb5" is an object oriented interface to the Kerberos 5 API. Iconic. But real talk: both the implementation and the documentation are nowhere near complete, and using this may require previous experience with Kerberos 5 programming. She's not holding your hand, she's holding your ticket. 😭

Most of the functions here are documented in detail in the Kerberos 5 API documentation over at <http://web.mit.edu/kerberos/krb5-current/doc/appdev/refs/api/index.html> — go read that, iykyk. 📚

✨ FUNCTIONS ✨

  • error(n) — returns the error code from the most recent "Authen::Krb5" call. And if you hand her an error code n? She gives you back a textual description of that error. bilingual queen. 💅
  • init_context() — initializes a context for the application. Returns a "Authen::Krb5::Context" object, or undef if there was an error. 🙈
  • "init_ets() (DEPRECATED)" — initializes the Kerberos error tables. Should be called along with "init_context()" at the beginning of a script. She's deprecated but she's still showing up to the function. 💀
  • get_default_realm() — returns the default realm of your host.
  • get_host_realm(host) — returns the realm of the specified host.
  • get_krbhst(realm) — returns a list of the Kerberos servers from the specified realm.
  • build_principal_ext(p) — okay so she is not like the actual "krb5_build_principal_ext", and I need you to know that. This is legacy code from Malcolm's code, which the author will probably change in future releases. In any case, it creates a 'server' principal for use in getting a TGT. Pass it the principal for which you would like a TGT. 🎟️
  • parse_name(name) — converts a string representation of a principal to a principal object. You can use this to create a principal from your username. main character move, honestly.
  • "sname_to_principal(hostname,sname,type)" — generates a server principal from the given hostname, service, and type. Type can be one of the following: NT_UNKNOWN, NT_PRINCIPAL, NT_SRV_INST, NT_SRV_HST, NT_SRV_XHST, NT_UID. See the Kerberos documentation for details. 👑
  • cc_resolve(name) — returns a credentials cache identifier which corresponds to the given name. 'name' must be in the form TYPE:RESIDUAL. See the Kerberos documentation for more information.
  • cc_default_name() — returns the name of the default credentials cache, which may be equivalent to KRB5CCACHE.
  • cc_default() — returns a Authen::Krb5::Ccache object representing the default credentials cache. 🫶
  • kt_resolve(name) — returns a Authen::Krb5::Keytab object representing the specified keytab name.
  • kt_default_name() — returns a string containing the default keytab name.
  • kt_default() — returns an Authen::Krb5::Keytab object representing the default keytab.
  • "kt_read_service_key(name, principal[, kvno, enctype])" — searches the keytab specified by name (the default keytab if name is undef) for a key matching principal (and optionally kvno and enctype) and returns the key in the form of an Authen::Krb5::Keyblock object. 🔑
  • "get_init_creds_password(client, password[, service])" — attempt to get an initial ticket for the client. 'client' is a principal object for which you want an initial ticket. 'password' is the password for the client. 'service', if given, is the string representation (not a principal object, bestie, read that again) for the ticket to acquire. If not given, it defaults to "krbtgt/REALM@REALM" for the local realm. Returns an Authen::Krb5::Creds object or undef on failure. 😭
  • "get_init_creds_keytab(client, keytab[, service])" — attempt to get an initial ticket for the client using a keytab. 'client' is a principal object for which you want an initial ticket. 'keytab' is a keytab object created with kt_resolve. 'service', if given, is the string representation (not a principal object) for the ticket to acquire. If not given, it defaults to "krbtgt/REALM@REALM" for the local realm. Returns an Authen::Krb5::Creds object or undef on failure. ✨
  • "get_in_tkt_with_password(client,server,password,cc)" — attempt to get an initial ticket for the client. 'client' is a principal object for which you want an initial ticket. 'server' is a principal object for the service (usually "krbtgt/REALM@REALM"). 'password' is the password for the client, and 'cc' is a Authen::Krb5::Ccache object representing the current credentials cache. Returns a Kerberos error code.
Although this interface is deprecated in the Kerberos C libraries, it's supported in the Perl module. In this module, it's implemented in terms of "krb5_get_init_creds_password", krb5_cc_initialize, and krb5_cc_store_cred.
  • "get_in_tkt_with_keytab(client,server,keytab,cc)" — obtain an initial ticket for the client using a keytab. 'client' is a principal object for which you want an initial ticket. 'server' is a principal object for the service (usually "krbtgt/REALM@REALM"). 'keytab' is a keytab object created with kt_resolve. 'cc' is a Authen::Krb5::Ccache object representing the current credentials cache. Returns a Kerberos error code.
Although this interface is deprecated in the Kerberos C libraries, it's supported in the Perl module. In this module, it's implemented in terms of krb5_get_init_creds_keytab, krb5_cc_initialize, and krb5_cc_store_cred.
  • "mk_req(auth_context,ap_req_options,service,hostname,in,cc)" — obtains a ticket for a specified service and returns a "KRB_AP_REQ" message suitable for passing to rd_req. 'auth_context' is the Authen::Krb5::AuthContext object you want to use for this connection, 'ap_req_options' is an OR'ed representation of the possible options (see Kerberos docs), 'service' is the name of the service for which you want a ticket (like 'host'), hostname is the hostname of the server, 'in' can be any user-specified data that can be verified at the server end, and 'cc' is your credentials cache object. 🌈
  • "rd_req(auth_context,in,server,keytab)" — parses a "KRB_AP_REQ" message and returns its contents in a Authen::Krb5::Ticket object. 'auth_context' is the connection's Authen::Krb5::AuthContext object, 'in' is the "KRB_AP_REQ" message (usually from mk_req), and server is the expected server's name for the ticket. 'keytab' is a Authen::Krb5::Keytab object for the keytab you want to use. Specify "undef" or leave off to use the default keytab. 🎟️
  • "mk_priv(auth_context,in)" — encrypts 'in' using parameters specified in auth_context, and returns the encrypted data. Requires use of a replay cache. 🔥
  • "rd_priv(auth_context,in)" — decrypts 'in' using parameters specified in auth_context, and returns the decrypted data.
  • "sendauth(auth_context,fh,version,client,server,options,in,in_creds,cc)" — obtains and sends an authenticated ticket from a client program to a server program using the filehandle 'fh'. 'version' is an application-defined version string that recvauth compares to its own version string. 'client' is the client principal, e.g. "username@REALM". 'server' is the service principal to which you are authenticating, e.g. "service.hostname@REALM". The only useful option right now is "AP_OPTS_MUTUAL_REQUIRED", which forces sendauth to perform mutual authentication with the server. 'in' is a string that will be received by recvauth and verified by the server — it's up to the application. 'in_creds' is not yet supported, so just use 'undef' here. 'cc' should be set to the current credentials cache. sendauth returns true on success and undefined on failure. 💖
  • "recvauth(auth_context,fh,version,server,keytab)" — receives authentication data from a client using the sendauth function through the filehandle 'fh'. 'version' is as described in the sendauth section. 'server' is the server principal to which the client will be authenticating. 'keytab' is a "Authen::Krb5::Keytab" object specifying the keytab to use for this service. recvauth returns a "Authen::Krb5::Ticket" object on success or undefined on failure. 🫶
  • "genaddrs(auth_context,fh,flags)" — uses the open socket filehandle 'fh' to generate local and remote addresses for auth_context. Flags should be one of the following, depending on the type of address you want to generate (flags can be OR'ed):
KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR
KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR
KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR
KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR
  • "gen_portaddr(addr,port)" — generates 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 order. For generating a replay cache name, you should supply the local address of the client and the socket's local port number. Returns a Authen::Krb5::Address object containing the address. 🧚
  • "gen_replay_name(addr,string)" — generate a unique replay cache name. 'addr' is a Authen::Krb5::Address object created by gen_portaddr. 'string' is used as a unique identifier for the replay cache. Returns the replay cache name. ⭐
  • get_server_rcache(name) — returns a Authen::Krb5::Rcache object using the replay cache name 'name.' 💜

🌟 ACKNOWLEDGEMENTS 🌟

Based on the original work by Doug MacEachern and Malcolm Beattie. Code contributions from Scott Hutton (shutton@indiana.edu). giving credit where credit is due, we love to see it. 🫶

👀 SEE ALSO 👀

perl(1), kerberos(1).

👑 AUTHOR 👑

Jeff Horwitz <jeff@smashing.org>

This software is copyright (c) 2000 by Jeff Horwitz.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

and that's the whole page bestie!! 💖 this one shipped as Authen::Krb5(3pm) under perl v5.40.1, dated 2025-04-11 — she's a User Contributed Perl Documentation girly and she ate. periodt. ✨🎀🦋

📦 where this page comes from