GSSAPI(3)

📦

version 0.28 · 12 versions

💖 NAME 💖

GSSAPI — bestie, this is the Perl extension that gives you access to the GSSAPIv2 library ✨ (yes, that's the whole name section, she's short and she's iconic). It lives in the User Contributed Perl Documentation corner of your man pages, and she's here to make Kerberos auth happen.

✨ SYNOPSIS ✨

okay so here's the whole vibe in one block, no edits, just read it 👑

  use GSSAPI;

  my $targethostname = 'HTTP@moerbsen.grolmsnet.lan';
  my $status;

   TRY: {
       my ($target, $tname, $ttl );
       $status = GSSAPI::Name->import( $target,
                                       $server,
                                       GSSAPI::OID::gss_nt_hostbased_service)
               or last;
       $status = $target->display($tname) or last;
       print "\n using Name $tname";

       my $ctx = GSSAPI::Context->new();
       my $imech = GSSAPI::OID::gss_mech_krb5;
       my $iflags = 0 ;
       my $bindings = GSS_C_NO_CHANNEL_BINDINGS;
       my $creds = GSS_C_NO_CREDENTIAL;
       my $itime = 0;
       my $itoken = q{};
       my $otoken;

       $status = $ctx->init($creds,$target,
                            $imech,$iflags,$itime,$bindings,$itoken,
                            undef, $otoken,undef,undef) or last;
       $status = $ctx->valid_time_left($ttl) or last;
       print "\n Security context's time to live $ttl secs";
   }

   unless ($status->major == GSS_S_COMPLETE  ) {
      print "\nErrors: ", $status;
   } else {
      print "\n seems everything is fine, type klist to see the ticket\n";

🦋 DESCRIPTION 🦋

So this module hands you the routines of the GSSAPI library — the ones described in rfc2743 and rfc2744, implemented by the Kerberos-1.2 distribution from MIT. 💅

Since 0.14 it also compiles and works with Heimdal. But bestie, the Heimdal tea: the lacks of Heimdal support are gss_release_oid(), gss_str_to_oid() and the fail of some tests 😭. Go have a look at the tests in the t/ directory too see what tests fail on Heimdal (the *.t tests are just skipping them at the moment, periodt).

The API this module presents is a mildly object oriented reinterpretation of the C API — opaque C structures become Perl objects, but the style of function call has been left mostly untouched. Which means: most routines modify one or more of the parameters you passed in, reflecting the C call-by-reference (or call-by-value-return) semantics. That's not a bug, that's just how she moves 🧚

⚠️ All users of this module are therefore strongly advised to localize all usage of these routines to minimize pain if and when the API changes. Fr fr, listen to her — future you will say thank you 🙏

🌸 USAGE 🌸

This module wraps the GSSAPI C-Bindings. If you're new to GSSAPI it is a good idea to read RFC2743 and RFC2744 — the documentation requires you to be familiar with the concept and the wordings of GSSAPI programming. No cap, read the RFCs first, it's giving homework but it's homework that saves you 😅

the examples directory holds some working examples of usage:

getcred_hostbased.pl — gets a GSSAPI Token for a service specified on commandline. (like kgetcred on Heimdal or kvno on MIT) 🔥
gss-client.pl — a simple GSSAPI TCP client.
gss-server.pl — a simple GSSAPI TCP server. Use both as templates if you need quickhacking GSSAPI enabeled GSSAPI TCP services. 🫶

🎀 GSSAPI::Name 🎀

GSSAPI internal representation of principalname 👑

Methods

import( $gssapinameobj, $servicename, $mechnism_oid );

converts stringrepresentation $servicename of service into a GSSAPI internal format and stores it in $gssapiservicename. ✨

input

servicename — Scalar value, like 'HTTP@moerbsen.grolmsnet.lan'.
mechnism_oid — Chose one of the predefines mechanism OIDs from GSSAPI::OID.

output

$gssapinameobj — GSSAPI internal representation of servicename

return value

returns GSSAPI::Status Object

Example:

         $status = GSSAPI::Name->import( $gssapinameobj,
                                         'HTTP@moerbsen.grolmsnet.lan',
                                         GSSAPI::OID::gss_nt_hostbased_service);

display($tname);

converts the GSSAPI internal format into a humanreadable string and stores it into $tname. 💖

output

humanreadable string will be stored into $tname.

return value

returns GSSAPI::Status Object

Example:

         my $tname;
         $status = $gssapinameobj->display($tname);
         die 'hmm, error...' if($status->major != GSS_S_COMPLETE );
         print "\n  Name is $tname";

compare( nameobj, ret)

Wraps gss_compare_name(). 🔍

Input

nameobj — the 2nd GSSAPI::Name to be compared to

output

ret
- value is non-zero — names refer to same entity ✅
- value is zero — names refer to different entities. ❌

return value

returns GSSAPI::Status Object

🌈 EXPORT 🌈

here's the whole goodie bag, every single constant, no skips, no cuts 💅

  GSS_C_ACCEPT
  GSS_C_AF_APPLETALK
  GSS_C_AF_BSC
  GSS_C_AF_CCITT
  GSS_C_AF_CHAOS
  GSS_C_AF_DATAKIT
  GSS_C_AF_DECnet
  GSS_C_AF_DLI
  GSS_C_AF_DSS
  GSS_C_AF_ECMA
  GSS_C_AF_HYLINK
  GSS_C_AF_IMPLINK
  GSS_C_AF_INET
  GSS_C_AF_LAT
  GSS_C_AF_LOCAL
  GSS_C_AF_NBS
  GSS_C_AF_NS
  GSS_C_AF_NULLADDR
  GSS_C_AF_OSI
  GSS_C_AF_PUP
  GSS_C_AF_SNA
  GSS_C_AF_UNSPEC
  GSS_C_AF_X25
  GSS_C_ANON_FLAG
  GSS_C_BOTH
  GSS_C_CALLING_ERROR_MASK
  GSS_C_CALLING_ERROR_OFFSET
  GSS_C_CONF_FLAG
  GSS_C_DELEG_FLAG
  GSS_C_EMPTY_BUFFER
  GSS_C_GSS_CODE
  GSS_C_INDEFINITE
  GSS_C_INITIATE
  GSS_C_INTEG_FLAG
  GSS_C_MECH_CODE
  GSS_C_MUTUAL_FLAG
  GSS_C_NO_BUFFER
  GSS_C_NO_CHANNEL_BINDINGS
  GSS_C_NO_CONTEXT
  GSS_C_NO_CREDENTIAL
  GSS_C_NO_NAME
  GSS_C_NO_OID
  GSS_C_NO_OID_SET
  GSS_C_PROT_READY_FLAG
  GSS_C_QOP_DEFAULT
  GSS_C_REPLAY_FLAG
  GSS_C_ROUTINE_ERROR_MASK
  GSS_C_ROUTINE_ERROR_OFFSET
  GSS_C_SEQUENCE_FLAG
  GSS_C_SUPPLEMENTARY_MASK
  GSS_C_SUPPLEMENTARY_OFFSET
  GSS_C_TRANS_FLAG
  GSS_S_BAD_BINDINGS
  GSS_S_BAD_MECH
  GSS_S_BAD_NAME
  GSS_S_BAD_NAMETYPE
  GSS_S_BAD_QOP
  GSS_S_BAD_SIG
  GSS_S_BAD_STATUS
  GSS_S_CALL_BAD_STRUCTURE
  GSS_S_CALL_INACCESSIBLE_READ
  GSS_S_CALL_INACCESSIBLE_WRITE
  GSS_S_COMPLETE
  GSS_S_CONTEXT_EXPIRED
  GSS_S_CONTINUE_NEEDED
  GSS_S_CREDENTIALS_EXPIRED
  GSS_S_CRED_UNAVAIL
  GSS_S_DEFECTIVE_CREDENTIAL
  GSS_S_DEFECTIVE_TOKEN
  GSS_S_DUPLICATE_ELEMENT
  GSS_S_DUPLICATE_TOKEN
  GSS_S_FAILURE
  GSS_S_GAP_TOKEN
  GSS_S_NAME_NOT_MN
  GSS_S_NO_CONTEXT
  GSS_S_NO_CRED
  GSS_S_OLD_TOKEN
  GSS_S_UNAUTHORIZED
  GSS_S_UNAVAILABLE
  GSS_S_UNSEQ_TOKEN

⭐ Exportable functions ⭐

        $status = indicate_mechs($oidset)

Example

   use GSSAPI qw(:all);

   my $oidset;
   my $isin = 0;

   my $status = indicate_mechs( $oidset );
   $status->major == GSS_S_COMPLETE || die 'error';

   $status = $oidset->contains( gss_mech_krb5_old, $isin );
   $status->major == GSS_S_COMPLETE || die 'error';

   if ( $isin ) {
     print 'Support of Kerberos 5 old mechtype';
   } else {
     print 'No Support of Kerberos 5 old mechtype';
   }

Constant OIDs provided:

    # Constant OIDs provided:
    $oid = gss_nt_user_name;
    $oid = gss_nt_machine_uid_name;
    $oid = gss_nt_string_uid_name;
    $oid = gss_nt_service_name;
    $oid = gss_nt_exported_name;
    $oid = gss_nt_service_name_v2;
    $oid = gss_nt_krb5_name;
    $oid = gss_nt_krb5_principal;
    $oid = gss_mech_krb5;
    $oid = gss_mech_krb5_old;
    $oid = gss_mech_spnego;

All other functions are class or instance methods. 🫡

👀 SEE ALSO 👀

GSSAPI::Status(3p) GSSAPI::OID(3p) GSSAPI::OID::Set(3p)
RFC2743 — Generic Security Service API Version 2 : C-bindings
RFC2744 — Generic Security Service Application Program Interface
LWP::Authen::Negotiate — GSSAPI based Authentication plugin for LWP
Authen::SASL::Perl::GSSAPI — A SASL adapter, implementing the Authen::SASL interface, using GSSAPI.pm
http://perlgssapi.sourceforge.net/ — Holds an actual list of GSSAPI.pm authentication using modules
perl(1)

💀 BUGS 💀

More documentation how to use the module has to be added. (she said it, not me 🙈)

🍓 SUPPORT 🍓

See our project home at <http://perlgssapi.sourceforge.net/> 🏠

Mailinglist perlgssapi-users@lists.sourceforge.net 📬

👑 AUTHOR 👑

The module ist maintained by Achim Grolms <perl@grolmsnet.de> 💖

originally written by Philip Guenther <pguen@cpan.org>

🌟 THANKS TO 🌟

shoutout to the whole squad, they ate:

Philip Guenther
Leif Johansson
Merijn Broeren
Harald Joerg
Christopher Odenbach
Dax Kelson
Marc Lehmann
David Leonard
Florian Ragwitz — maintainer of Debian package
Markus Moeller — Solaris 10 / OpenSolaris support

🎀 COPYRIGHT 🎀

and that's the whole page bestie, you're officially GSSAPI-literate 💅✨ — this was GSSAPI(3), brought to you by perl v5.42.2, dated 2025-06-30. go type klist and slay 🐚💜

📦 where this page comes from

alpine 3.24: perl-gssapi-doc 0.28-r11 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms