.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 3"
.TH GSSAPI 3 "2010-04-27" "perl v5.26.3" "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 \s-1GSSAPI\s0 library,
as described in rfc2743 and rfc2744 and implemented by the
Kerberos\-1.2 distribution from \s-1MIT.\s0
.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 \s-1API\s0 presented by this module is a mildly object oriented
reinterpretation of the C \s-1API,\s0 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 \s-1API\s0 changes.
.SH "USAGE"
.IX Header "USAGE"
This module wraps the \s-1GSSAPI\s0 C\-Bindings. If you are
new to \s-1GSSAPI\s0 it is a good idea to read \s-1RFC2743\s0 and \s-1RFC2744,\s0
the documentation requires you to be familiar with the concept
and the wordings of \s-1GSSAPI\s0 programming.
.PP
the examples directory holds some working examples of usage:
.IP "getcred_hostbased.pl" 4
.IX Item "getcred_hostbased.pl"
gets a \s-1GSSAPI\s0 Token for a service specified
on commandline.
(like kgetcred on Heimdal or kvno on \s-1MIT\s0)
.IP "gss\-client.pl" 4
.IX Item "gss-client.pl"
a simple \s-1GSSAPI TCP\s0 client.
.IP "gss\-server.pl" 4
.IX Item "gss-server.pl"
a simple \s-1GSSAPI TCP\s0 server.
Use both as templates if you need quickhacking
\&\s-1GSSAPI\s0 enabeled \s-1GSSAPI TCP\s0 services.
.SS "GSSAPI::Name"
.IX Subsection "GSSAPI::Name"
\&\s-1GSSAPI\s0 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 \s-1GSSAPI\s0 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 \s-1GSSAPI::OID\s0
.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
\&\s-1GSSAPI\s0 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 \s-1GSSAPI\s0 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 "\s-1EXPORT\s0"
.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)
\&\s-1\fBGSSAPI::OID\s0\fR\|(3p)
\&\fBGSSAPI::OID::Set\fR\|(3p)
.IP "\s-1RFC2743\s0" 4
.IX Item "RFC2743"
Generic Security Service \s-1API\s0 Version 2 : C\-bindings
.IP "\s-1RFC2744\s0" 4
.IX Item "RFC2744"
Generic Security Service Application Program Interface
.IP "LWP::Authen::Negotiate" 4
.IX Item "LWP::Authen::Negotiate"
\&\s-1GSSAPI\s0 based Authentication plugin for \s-1LWP\s0
.IP "Authen::SASL::Perl::GSSAPI" 4
.IX Item "Authen::SASL::Perl::GSSAPI"
A \s-1SASL\s0 adapter, implementing the Authen::SASL interface,
using \s-1GSSAPI\s0.pm
.IP "http://perlgssapi.sourceforge.net/" 4
.IX Item "http://perlgssapi.sourceforge.net/"
Holds an actual list of \s-1GSSAPI\s0.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.