1package GSSAPI;
2
3require 5.005_62;
4use strict;
5use warnings;
6use Carp;
7
8require Exporter;
9use XSLoader;
10
11our @ISA = qw(Exporter);
12our $VERSION = '0.28';
13
14# Items to export into callers namespace by default. Note: do not export
15# names by default without a very good reason. Use EXPORT_OK instead.
16# Do not simply export all your public functions/methods/constants.
17
18# This allows declaration	use GSSAPI ':all';
19# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
20# will save memory.
21
22our %EXPORT_TAGS = ( 'all' => [ qw(
23	GSS_C_ACCEPT
24	GSS_C_AF_APPLETALK
25	GSS_C_AF_BSC
26	GSS_C_AF_CCITT
27	GSS_C_AF_CHAOS
28	GSS_C_AF_DATAKIT
29	GSS_C_AF_DECnet
30	GSS_C_AF_DLI
31	GSS_C_AF_DSS
32	GSS_C_AF_ECMA
33	GSS_C_AF_HYLINK
34	GSS_C_AF_IMPLINK
35	GSS_C_AF_INET
36	GSS_C_AF_LAT
37	GSS_C_AF_LOCAL
38	GSS_C_AF_NBS
39	GSS_C_AF_NS
40	GSS_C_AF_NULLADDR
41	GSS_C_AF_OSI
42	GSS_C_AF_PUP
43	GSS_C_AF_SNA
44	GSS_C_AF_UNSPEC
45	GSS_C_AF_X25
46	GSS_C_ANON_FLAG
47	GSS_C_BOTH
48	GSS_C_CALLING_ERROR_MASK
49	GSS_C_CALLING_ERROR_OFFSET
50	GSS_C_CONF_FLAG
51	GSS_C_DELEG_FLAG
52	GSS_C_EMPTY_BUFFER
53	GSS_C_GSS_CODE
54	GSS_C_INDEFINITE
55	GSS_C_INITIATE
56	GSS_C_INTEG_FLAG
57	GSS_C_MECH_CODE
58	GSS_C_MUTUAL_FLAG
59	GSS_C_NO_BUFFER
60	GSS_C_NO_CHANNEL_BINDINGS
61	GSS_C_NO_CONTEXT
62	GSS_C_NO_CREDENTIAL
63	GSS_C_NO_NAME
64	GSS_C_NO_OID
65	GSS_C_NO_OID_SET
66	GSS_C_PROT_READY_FLAG
67	GSS_C_QOP_DEFAULT
68	GSS_C_REPLAY_FLAG
69	GSS_C_ROUTINE_ERROR_MASK
70	GSS_C_ROUTINE_ERROR_OFFSET
71	GSS_C_SEQUENCE_FLAG
72	GSS_C_SUPPLEMENTARY_MASK
73	GSS_C_SUPPLEMENTARY_OFFSET
74	GSS_C_TRANS_FLAG
75	GSS_S_BAD_BINDINGS
76	GSS_S_BAD_MECH
77	GSS_S_BAD_NAME
78	GSS_S_BAD_NAMETYPE
79	GSS_S_BAD_QOP
80	GSS_S_BAD_SIG
81	GSS_S_BAD_STATUS
82	GSS_S_CALL_BAD_STRUCTURE
83	GSS_S_CALL_INACCESSIBLE_READ
84	GSS_S_CALL_INACCESSIBLE_WRITE
85	GSS_S_COMPLETE
86	GSS_S_CONTEXT_EXPIRED
87	GSS_S_CONTINUE_NEEDED
88	GSS_S_CREDENTIALS_EXPIRED
89	GSS_S_CRED_UNAVAIL
90	GSS_S_DEFECTIVE_CREDENTIAL
91	GSS_S_DEFECTIVE_TOKEN
92	GSS_S_DUPLICATE_ELEMENT
93	GSS_S_DUPLICATE_TOKEN
94	GSS_S_FAILURE
95	GSS_S_GAP_TOKEN
96	GSS_S_NAME_NOT_MN
97	GSS_S_NO_CONTEXT
98	GSS_S_NO_CRED
99	GSS_S_OLD_TOKEN
100	GSS_S_UNAUTHORIZED
101	GSS_S_UNAVAILABLE
102	GSS_S_UNSEQ_TOKEN
103	indicate_mechs
104) ] );
105
106our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
107our @EXPORT    = ( @{ $EXPORT_TAGS{'all'} } );
108
109
110XSLoader::load 'GSSAPI', $VERSION;
111
112sub import {
113    my $self = shift;
114    my @args = @_;
115    my $package = caller;
116    $self->export_to_level(1, $self, @args);
117    foreach (qw(Status OID OID::Set)) {
118	eval "package $package; use GSSAPI::$_ \@args; 1"
119					or croak $@;
120    }
121}
122
123{
124    no strict 'refs';
125    foreach my $pack (qw(Context Cred Name)) {
126	@{"GSSAPI::${pack}::ISA"} = "GSSAPI";
127    }
128}
129
130# Preloaded methods go here.
131
132use constant GSS_C_NO_NAME		=> undef;
133use constant GSS_C_NO_BUFFER		=> undef;
134use constant GSS_C_NO_OID		=> undef;
135use constant GSS_C_NO_OID_SET		=> undef;
136use constant GSS_C_NO_CONTEXT		=> undef;
137use constant GSS_C_NO_CREDENTIAL	=> undef;
138use constant GSS_C_NO_CHANNEL_BINDINGS	=> undef;
139use constant GSS_C_EMPTY_BUFFER		=> "";
140
141
1421;
143__END__
144
145=head1 NAME
146
147GSSAPI - Perl extension providing access to the GSSAPIv2 library
148
149=head1 SYNOPSIS
150
151
152  use GSSAPI;
153
154  my $targethostname = 'HTTP@moerbsen.grolmsnet.lan';
155  my $status;
156
157
158
159   TRY: {
160       my ($target, $tname, $ttl );
161       $status = GSSAPI::Name->import( $target,
162                                       $server,
163                                       GSSAPI::OID::gss_nt_hostbased_service)
164               or last;
165       $status = $target->display($tname) or last;
166       print "\n using Name $tname";
167
168       my $ctx = GSSAPI::Context->new();
169       my $imech = GSSAPI::OID::gss_mech_krb5;
170       my $iflags = 0 ;
171       my $bindings = GSS_C_NO_CHANNEL_BINDINGS;
172       my $creds = GSS_C_NO_CREDENTIAL;
173       my $itime = 0;
174       my $itoken = q{};
175       my $otoken;
176
177       $status = $ctx->init($creds,$target,
178                            $imech,$iflags,$itime,$bindings,$itoken,
179                            undef, $otoken,undef,undef) or last;
180       $status = $ctx->valid_time_left($ttl) or last;
181       print "\n Security context's time to live $ttl secs";
182   }
183
184   unless ($status->major == GSS_S_COMPLETE  ) {
185      print "\nErrors: ", $status;
186   } else {
187      print "\n seems everything is fine, type klist to see the ticket\n";
188
189
190=head1 DESCRIPTION
191
192This module gives access to the routines of the GSSAPI library,
193as described in rfc2743 and rfc2744 and implemented by the
194Kerberos-1.2 distribution from MIT.
195
196Since 0.14 it also compiles and works with Heimdal.
197Lacks of Heimdal support are gss_release_oid(),
198gss_str_to_oid() and fail of some tests.
199Have a look at the tests in t/ directory too see what tests
200fail on Heimdal ( the *.t tests are just skipping them at the moment)
201
202The API presented by this module is a mildly object oriented
203reinterpretation of the C API, where opaque C structures are
204Perl objects, but the style of function call has been left
205mostly untouched.  As a result, most routines modify one or
206more of the parameters passed to them, reflecting the C
207call-by-reference (or call-by-value-return) semantics.
208
209All users of this module are therefore strongly advised to
210localize all usage of these routines to minimize pain if and
211when the API changes.
212
213=head1 USAGE
214
215This module wraps the GSSAPI C-Bindings. If you are
216new to GSSAPI it is a good idea to read RFC2743 and RFC2744,
217the documentation requires you to be familiar with the concept
218and the wordings of GSSAPI programming.
219
220the examples directory holds some working examples of usage:
221
222=over
223
224=item getcred_hostbased.pl
225
226gets a GSSAPI Token for a service specified
227on commandline.
228(like kgetcred on Heimdal or kvno on MIT)
229
230=item gss-client.pl
231
232a simple GSSAPI TCP client.
233
234=item gss-server.pl
235
236a simple GSSAPI TCP server.
237Use both as templates if you need quickhacking
238GSSAPI enabeled GSSAPI TCP services.
239
240=back
241
242
243=head2 GSSAPI::Name
244
245GSSAPI internal representation of principalname
246
247=head3 Methods
248
249=over
250
251=item import( $gssapinameobj, $servicename, $mechnism_oid );
252
253converts stringrepresentation $servicename of service into a GSSAPI internal format
254and stores it in $gssapiservicename.
255
256
257
258=over
259
260=item input
261
262=over
263
264=item servicename
265
266Scalar value, like 'HTTP@moerbsen.grolmsnet.lan'.
267
268=item mechnism_oid
269
270Chose one of the predefines mechanism OIDs from GSSAPI::OID
271
272=back
273
274=item output
275
276=over
277
278=item $gssapinameobj
279
280GSSAPI internal representation of servicename
281
282=back
283
284=item return value
285
286returns GSSAPI::Status Object
287
288=item Example:
289
290     $status = GSSAPI::Name->import( $gssapinameobj,
291                                     'HTTP@moerbsen.grolmsnet.lan',
292                                     GSSAPI::OID::gss_nt_hostbased_service);
293
294=back
295
296=item display($tname);
297
298converts the GSSAPI internal format into a humanreadable string and stores it into $tname.
299
300=over
301
302=item output
303
304humanreadable string will be stored into $tname.
305
306=item return value
307
308returns GSSAPI::Status Object
309
310=item Example:
311
312     my $tname;
313     $status = $gssapinameobj->display($tname);
314     die 'hmm, error...' if($status->major != GSS_S_COMPLETE );
315     print "\n  Name is $tname";
316
317=back
318
319
320=item compare( nameobj, ret)
321
322Wraps gss_compare_name().
323
324=over
325
326=item Input
327
328=over
329
330=item nameobj
331
332the 2nd GSSAPI::Name to be compared to
333
334=back
335
336
337=item output
338
339=over
340
341=item ret
342
343=over
344
345=item value is non-zero
346
347names refer to same entity
348
349=item value is zero
350
351names refer to different entities.
352
353=back
354
355=back
356
357=item return value
358
359returns GSSAPI::Status Object
360
361=back
362
363=back
364
365
366=head2 EXPORT
367
368  GSS_C_ACCEPT
369  GSS_C_AF_APPLETALK
370  GSS_C_AF_BSC
371  GSS_C_AF_CCITT
372  GSS_C_AF_CHAOS
373  GSS_C_AF_DATAKIT
374  GSS_C_AF_DECnet
375  GSS_C_AF_DLI
376  GSS_C_AF_DSS
377  GSS_C_AF_ECMA
378  GSS_C_AF_HYLINK
379  GSS_C_AF_IMPLINK
380  GSS_C_AF_INET
381  GSS_C_AF_LAT
382  GSS_C_AF_LOCAL
383  GSS_C_AF_NBS
384  GSS_C_AF_NS
385  GSS_C_AF_NULLADDR
386  GSS_C_AF_OSI
387  GSS_C_AF_PUP
388  GSS_C_AF_SNA
389  GSS_C_AF_UNSPEC
390  GSS_C_AF_X25
391  GSS_C_ANON_FLAG
392  GSS_C_BOTH
393  GSS_C_CALLING_ERROR_MASK
394  GSS_C_CALLING_ERROR_OFFSET
395  GSS_C_CONF_FLAG
396  GSS_C_DELEG_FLAG
397  GSS_C_EMPTY_BUFFER
398  GSS_C_GSS_CODE
399  GSS_C_INDEFINITE
400  GSS_C_INITIATE
401  GSS_C_INTEG_FLAG
402  GSS_C_MECH_CODE
403  GSS_C_MUTUAL_FLAG
404  GSS_C_NO_BUFFER
405  GSS_C_NO_CHANNEL_BINDINGS
406  GSS_C_NO_CONTEXT
407  GSS_C_NO_CREDENTIAL
408  GSS_C_NO_NAME
409  GSS_C_NO_OID
410  GSS_C_NO_OID_SET
411  GSS_C_PROT_READY_FLAG
412  GSS_C_QOP_DEFAULT
413  GSS_C_REPLAY_FLAG
414  GSS_C_ROUTINE_ERROR_MASK
415  GSS_C_ROUTINE_ERROR_OFFSET
416  GSS_C_SEQUENCE_FLAG
417  GSS_C_SUPPLEMENTARY_MASK
418  GSS_C_SUPPLEMENTARY_OFFSET
419  GSS_C_TRANS_FLAG
420  GSS_S_BAD_BINDINGS
421  GSS_S_BAD_MECH
422  GSS_S_BAD_NAME
423  GSS_S_BAD_NAMETYPE
424  GSS_S_BAD_QOP
425  GSS_S_BAD_SIG
426  GSS_S_BAD_STATUS
427  GSS_S_CALL_BAD_STRUCTURE
428  GSS_S_CALL_INACCESSIBLE_READ
429  GSS_S_CALL_INACCESSIBLE_WRITE
430  GSS_S_COMPLETE
431  GSS_S_CONTEXT_EXPIRED
432  GSS_S_CONTINUE_NEEDED
433  GSS_S_CREDENTIALS_EXPIRED
434  GSS_S_CRED_UNAVAIL
435  GSS_S_DEFECTIVE_CREDENTIAL
436  GSS_S_DEFECTIVE_TOKEN
437  GSS_S_DUPLICATE_ELEMENT
438  GSS_S_DUPLICATE_TOKEN
439  GSS_S_FAILURE
440  GSS_S_GAP_TOKEN
441  GSS_S_NAME_NOT_MN
442  GSS_S_NO_CONTEXT
443  GSS_S_NO_CRED
444  GSS_S_OLD_TOKEN
445  GSS_S_UNAUTHORIZED
446  GSS_S_UNAVAILABLE
447  GSS_S_UNSEQ_TOKEN
448
449=head2 Exportable functions
450
451    $status = indicate_mechs($oidset)
452
453Example
454
455   use GSSAPI qw(:all);
456
457   my $oidset;
458   my $isin = 0;
459
460   my $status = indicate_mechs( $oidset );
461   $status->major == GSS_S_COMPLETE || die 'error';
462
463   $status = $oidset->contains( gss_mech_krb5_old, $isin );
464   $status->major == GSS_S_COMPLETE || die 'error';
465
466   if ( $isin ) {
467     print 'Support of Kerberos 5 old mechtype';
468   } else {
469     print 'No Support of Kerberos 5 old mechtype';
470   }
471
472
473=head3 Constant OIDs provided:
474
475
476    # Constant OIDs provided:
477    $oid = gss_nt_user_name;
478    $oid = gss_nt_machine_uid_name;
479    $oid = gss_nt_string_uid_name;
480    $oid = gss_nt_service_name;
481    $oid = gss_nt_exported_name;
482    $oid = gss_nt_service_name_v2;
483    $oid = gss_nt_krb5_name;
484    $oid = gss_nt_krb5_principal;
485    $oid = gss_mech_krb5;
486    $oid = gss_mech_krb5_old;
487    $oid = gss_mech_spnego;
488
489
490All other functions are class or instance methods.
491
492=head1 SEE ALSO
493
494GSSAPI::Status(3p)
495GSSAPI::OID(3p)
496GSSAPI::OID::Set(3p)
497
498=over
499
500=item RFC2743
501
502Generic Security Service API Version 2 : C-bindings
503
504=item RFC2744
505
506Generic Security Service Application Program Interface
507
508=item LWP::Authen::Negotiate
509
510GSSAPI based Authentication plugin for LWP
511
512=item Authen::SASL::Perl::GSSAPI
513
514A SASL adapter, implementing the Authen::SASL interface,
515using GSSAPI.pm
516
517=item http://perlgssapi.sourceforge.net/
518
519Holds an actual list of GSSAPI.pm authentication using
520modules
521
522=back
523
524perl(1)
525
526
527=head1 BUGS
528
529More documentation how to use the module has to be added.
530
531=head1 SUPPORT
532
533See our project home at <http://perlgssapi.sourceforge.net/>
534
535Mailinglist perlgssapi-users@lists.sourceforge.net
536
537=head1 AUTHOR
538
539The module ist maintained by
540Achim Grolms <perl@grolmsnet.de>
541
542originally written by
543Philip Guenther <pguen@cpan.org>
544
545=head1 THANKS TO
546
547=over
548
549=item Philip Guenther
550
551=item Leif Johansson
552
553=item Merijn Broeren
554
555=item Harald Joerg
556
557=item Christopher Odenbach
558
559=item Dax Kelson
560
561=item Marc Lehmann
562
563=item David Leonard
564
565=item Florian Ragwitz
566
567maintainer of Debian package
568
569=item Markus Moeller
570
571Solaris 10 /  OpenSolaris support
572
573=back
574
575=head1 COPYRIGHT
576
577Copyright (c) 2006,2008 Achim Grolms. All rights reserved.
578This program is free software; you can redistribute it
579and/or modify it under the same terms as Perl itself.
580
581Copyright (c) 2000,2001,2005 Philip Guenther. All rights reserved.
582This program is free software; you can redistribute it
583and/or modify it under the same terms as Perl itself.
584
585=cut
586