.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "GSSAPI 3pm"
.TH GSSAPI 3pm 2024-01-10 "perl v5.38.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
GSSAPI \- Perl extension providing access to the GSSAPIv2 library
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use GSSAPI;
\&
\&  my $targethostname = \*(AqHTTP@moerbsen.grolmsnet.lan\*(Aq;
\&  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 "\en 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 "\en Security context\*(Aqs time to live $ttl secs";
\&   }
\&
\&   unless ($status\->major == GSS_S_COMPLETE  ) {
\&      print "\enErrors: ", $status;
\&   } else {
\&      print "\en seems everything is fine, type klist to see the ticket\en";
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module gives access to the routines of the GSSAPI library,
as described in rfc2743 and rfc2744 and implemented by the
Kerberos\-1.2 distribution from MIT.
.PP
Since 0.14 it also compiles and works with Heimdal.
Lacks of Heimdal support are \fBgss_release_oid()\fR,
\&\fBgss_str_to_oid()\fR and fail of some tests.
Have a look at the tests in t/ directory too see what tests
fail on Heimdal ( the *.t tests are just skipping them at the moment)
.PP
The API presented by this module is a mildly object oriented
reinterpretation of the C API, where opaque C structures are
Perl objects, but the style of function call has been left
mostly untouched.  As a result, most routines modify one or
more of the parameters passed to them, reflecting the C
call-by-reference (or call-by-value-return) semantics.
.PP
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.
.SH USAGE
.IX Header "USAGE"
This module wraps the GSSAPI C\-Bindings. If you are
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.
.PP
the examples directory holds some working examples of usage:
.IP getcred_hostbased.pl 4
.IX Item "getcred_hostbased.pl"
gets a GSSAPI Token for a service specified
on commandline.
(like kgetcred on Heimdal or kvno on MIT)
.IP gss\-client.pl 4
.IX Item "gss-client.pl"
a simple GSSAPI TCP client.
.IP gss\-server.pl 4
.IX Item "gss-server.pl"
a simple GSSAPI TCP server.
Use both as templates if you need quickhacking
GSSAPI enabeled GSSAPI TCP services.
.SS GSSAPI::Name
.IX Subsection "GSSAPI::Name"
GSSAPI internal representation of principalname
.PP
\fIMethods\fR
.IX Subsection "Methods"
.ie n .IP "import( $gssapinameobj, $servicename, $mechnism_oid );" 4
.el .IP "import( \f(CW$gssapinameobj\fR, \f(CW$servicename\fR, \f(CW$mechnism_oid\fR );" 4
.IX Item "import( $gssapinameobj, $servicename, $mechnism_oid );"
converts stringrepresentation \f(CW$servicename\fR of service into a GSSAPI internal format
and stores it in \f(CW$gssapiservicename\fR.
.RS 4
.IP input 4
.IX Item "input"
.RS 4
.PD 0
.IP servicename 4
.IX Item "servicename"
.PD
Scalar value, like 'HTTP@moerbsen.grolmsnet.lan'.
.IP mechnism_oid 4
.IX Item "mechnism_oid"
Chose one of the predefines mechanism OIDs from GSSAPI::OID
.RE
.RS 4
.RE
.IP output 4
.IX Item "output"
.RS 4
.PD 0
.ie n .IP $gssapinameobj 4
.el .IP \f(CW$gssapinameobj\fR 4
.IX Item "$gssapinameobj"
.PD
GSSAPI internal representation of servicename
.RE
.RS 4
.RE
.IP "return value" 4
.IX Item "return value"
returns GSSAPI::Status Object
.IP Example: 4
.IX Item "Example:"
.Vb 3
\&     $status = GSSAPI::Name\->import( $gssapinameobj,
\&                                     \*(AqHTTP@moerbsen.grolmsnet.lan\*(Aq,
\&                                     GSSAPI::OID::gss_nt_hostbased_service);
.Ve
.RE
.RS 4
.RE
.IP display($tname); 4
.IX Item "display($tname);"
converts the GSSAPI internal format into a humanreadable string and stores it into \f(CW$tname\fR.
.RS 4
.IP output 4
.IX Item "output"
humanreadable string will be stored into \f(CW$tname\fR.
.IP "return value" 4
.IX Item "return value"
returns GSSAPI::Status Object
.IP Example: 4
.IX Item "Example:"
.Vb 4
\&     my $tname;
\&     $status = $gssapinameobj\->display($tname);
\&     die \*(Aqhmm, error...\*(Aq if($status\->major != GSS_S_COMPLETE );
\&     print "\en  Name is $tname";
.Ve
.RE
.RS 4
.RE
.IP "compare( nameobj, ret)" 4
.IX Item "compare( nameobj, ret)"
Wraps \fBgss_compare_name()\fR.
.RS 4
.IP Input 4
.IX Item "Input"
.RS 4
.PD 0
.IP nameobj 4
.IX Item "nameobj"
.PD
the 2nd GSSAPI::Name to be compared to
.RE
.RS 4
.RE
.IP output 4
.IX Item "output"
.RS 4
.PD 0
.IP ret 4
.IX Item "ret"
.RS 4
.IP "value is non-zero" 4
.IX Item "value is non-zero"
.PD
names refer to same entity
.IP "value is zero" 4
.IX Item "value is zero"
names refer to different entities.
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.IP "return value" 4
.IX Item "return value"
returns GSSAPI::Status Object
.RE
.RS 4
.RE
.SS EXPORT
.IX Subsection "EXPORT"
.Vb 10
\&  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
.Ve
.SS "Exportable functions"
.IX Subsection "Exportable functions"
.Vb 1
\&    $status = indicate_mechs($oidset)
.Ve
.PP
Example
.PP
.Vb 1
\&   use GSSAPI qw(:all);
\&
\&   my $oidset;
\&   my $isin = 0;
\&
\&   my $status = indicate_mechs( $oidset );
\&   $status\->major == GSS_S_COMPLETE || die \*(Aqerror\*(Aq;
\&
\&   $status = $oidset\->contains( gss_mech_krb5_old, $isin );
\&   $status\->major == GSS_S_COMPLETE || die \*(Aqerror\*(Aq;
\&
\&   if ( $isin ) {
\&     print \*(AqSupport of Kerberos 5 old mechtype\*(Aq;
\&   } else {
\&     print \*(AqNo Support of Kerberos 5 old mechtype\*(Aq;
\&   }
.Ve
.PP
\fIConstant OIDs provided:\fR
.IX Subsection "Constant OIDs provided:"
.PP
.Vb 12
\&    # 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;
.Ve
.PP
All other functions are class or instance methods.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBGSSAPI::Status\fR\|(3p)
\&\fBGSSAPI::OID\fR\|(3p)
\&\fBGSSAPI::OID::Set\fR\|(3p)
.IP RFC2743 4
.IX Item "RFC2743"
Generic Security Service API Version 2 : C\-bindings
.IP RFC2744 4
.IX Item "RFC2744"
Generic Security Service Application Program Interface
.IP LWP::Authen::Negotiate 4
.IX Item "LWP::Authen::Negotiate"
GSSAPI based Authentication plugin for LWP
.IP Authen::SASL::Perl::GSSAPI 4
.IX Item "Authen::SASL::Perl::GSSAPI"
A SASL adapter, implementing the Authen::SASL interface,
using GSSAPI.pm
.IP http://perlgssapi.sourceforge.net/ 4
.IX Item "http://perlgssapi.sourceforge.net/"
Holds an actual list of GSSAPI.pm authentication using
modules
.PP
\&\fBperl\fR\|(1)
.SH BUGS
.IX Header "BUGS"
More documentation how to use the module has to be added.
.SH SUPPORT
.IX Header "SUPPORT"
See our project home at <http://perlgssapi.sourceforge.net/>
.PP
Mailinglist perlgssapi\-users@lists.sourceforge.net
.SH AUTHOR
.IX Header "AUTHOR"
The module ist maintained by
Achim Grolms <perl@grolmsnet.de>
.PP
originally written by
Philip Guenther <pguen@cpan.org>
.SH "THANKS TO"
.IX Header "THANKS TO"
.IP "Philip Guenther" 4
.IX Item "Philip Guenther"
.PD 0
.IP "Leif Johansson" 4
.IX Item "Leif Johansson"
.IP "Merijn Broeren" 4
.IX Item "Merijn Broeren"
.IP "Harald Joerg" 4
.IX Item "Harald Joerg"
.IP "Christopher Odenbach" 4
.IX Item "Christopher Odenbach"
.IP "Dax Kelson" 4
.IX Item "Dax Kelson"
.IP "Marc Lehmann" 4
.IX Item "Marc Lehmann"
.IP "David Leonard" 4
.IX Item "David Leonard"
.IP "Florian Ragwitz" 4
.IX Item "Florian Ragwitz"
.PD
maintainer of Debian package
.IP "Markus Moeller" 4
.IX Item "Markus Moeller"
Solaris 10 /  OpenSolaris support
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 2006,2008 Achim Grolms. All rights reserved.
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
.PP
Copyright (c) 2000,2001,2005 Philip Guenther. All rights reserved.
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.