« back to all changes in this revision
Viewing changes to doc/gss.info
- browse files at revision 15
- compare with another revision
- download diff
- download tarball
- view history from revision 15
- Committer: Package Import Robot
- Author(s): Simon Josefsson
- Date: 2014-10-09 15:51:38 UTC
- mfrom: (1.2.9)
- Revision ID: package-import@ubuntu.com-20141009155138-50b2mr1qsqcln38w
Tags: 1.0.3-1
* New upstream version.
- Drop unnecessary Debian patches.
* Update standards version to 3.9.6.
* Improve copyright file.
* Use DEP3 patches.
- Drop unnecessary Debian patches.
* Update standards version to 3.9.6.
* Improve copyright file.
* Use DEP3 patches.
- files added:
- build-aux/ar-lib
- files removed:
- .pc/disable-Werror.patch
- debian/patches
- files modified:
- .clcopying
added
removed
doc/gss.info
1
This is gss.info, produced by makeinfo version 4.13 from gss.texi.
2
3
This manual is last updated 21 November 2011 for version 1.0.2 of GNU
4
GSS.
5
6
Copyright (C) 2003-2011 Simon Josefsson.
1
This is gss.info, produced by makeinfo version 5.2 from gss.texi.
2
3
This manual is last updated 9 October 2014 for version 1.0.3 of GNU GSS.
4
5
Copyright (C) 2003-2014 Simon Josefsson.
7
6
8
7
Permission is granted to copy, distribute and/or modify this
9
8
document under the terms of the GNU Free Documentation License,
11
10
Foundation; with no Invariant Sections, no Front-Cover Texts, and
12
11
no Back-Cover Texts. A copy of the license is included in the
13
12
section entitled "GNU Free Documentation License".
14
15
13
INFO-DIR-SECTION GNU Libraries
16
14
START-INFO-DIR-ENTRY
17
15
* gss: (gss). Generic Security Service API Library
23
21
GNU Generic Security Service Library
24
22
************************************
25
23
26
This manual is last updated 21 November 2011 for version 1.0.2 of GNU
27
GSS.
24
This manual is last updated 9 October 2014 for version 1.0.3 of GNU GSS.
28
25
29
Copyright (C) 2003-2011 Simon Josefsson.
26
Copyright (C) 2003-2014 Simon Josefsson.
30
27
31
28
Permission is granted to copy, distribute and/or modify this
32
29
document under the terms of the GNU Free Documentation License,
61
58
**************
62
59
63
60
GSS is an implementation of the Generic Security Service Application
64
Program Interface (GSS-API). GSS-API is used by network servers to
61
Program Interface (GSS-API). GSS-API is used by network servers to
65
62
provide security services, e.g., to authenticate SMTP/IMAP clients
66
63
against SMTP/IMAP servers. GSS consists of a library and a manual.
67
64
68
65
GSS is developed for the GNU/Linux system, but runs on over 20
69
platforms including most major Unix platforms and Windows, and many
70
kind of devices including iPAQ handhelds and S/390 mainframes.
66
platforms including most major Unix platforms and Windows, and many kind
67
of devices including iPAQ handhelds and S/390 mainframes.
71
68
72
69
GSS is a GNU project, and is licensed under the GNU General Public
73
70
License version 3 or later.
96
93
The reader is assumed to possess basic familiarity with GSS-API and
97
94
network programming in C or C++. For general GSS-API information, and
98
95
some programming examples, there is a guide available online at
99
`http://docs.sun.com/db/doc/816-1331'.
96
<http://docs.sun.com/db/doc/816-1331>.
100
97
101
98
This manual can be used in several ways. If read from the beginning
102
to the end, it gives a good introduction into the library and how it
103
can be used in an application. Forward references are included where
99
to the end, it gives a good introduction into the library and how it can
100
be used in an application. Forward references are included where
104
101
necessary. Later on, the manual can be used as a reference manual to
105
102
get just the information needed about any particular interface of the
106
103
library. Experienced programmers might want to start looking at the
133
130
It should work on all Unix like operating systems, including
134
131
Windows.
135
132
136
137
133
138
134
File: gss.info, Node: GSS-API Overview, Next: Supported Platforms, Prev: Features, Up: Introduction
139
135
152
148
There are four stages to using the GSS-API:
153
149
154
150
1. The application acquires a set of credentials with which it may
155
prove its identity to other processes. The application's
151
prove its identity to other processes. The application's
156
152
credentials vouch for its global identity, which may or may not be
157
153
related to any local username under which it may be running.
158
154
165
161
and message sequence numbers. As part of the establishment of a
166
162
security context, the context initiator is authenticated to the
167
163
responder, and may require that the responder is authenticated in
168
turn. The initiator may optionally give the responder the right
169
to initiate further security contexts, acting as an agent or
170
delegate of the initiator. This transfer of rights is termed
171
delegation, and is achieved by creating a set of credentials,
172
similar to those used by the initiating application, but which may
173
be used by the responder.
164
turn. The initiator may optionally give the responder the right to
165
initiate further security contexts, acting as an agent or delegate
166
of the initiator. This transfer of rights is termed delegation,
167
and is achieved by creating a set of credentials, similar to those
168
used by the initiating application, but which may be used by the
169
responder.
174
170
175
171
To establish and maintain the shared information that makes up the
176
172
security context, certain GSS-API calls will return a token data
179
175
routine is responsible for transferring the token to the peer
180
176
application, encapsulated if necessary in an application-
181
177
application protocol. On receipt of such a token, the peer
182
application should pass it to a corresponding GSS-API routine
183
which will decode the token and extract the information, updating
184
the security context state information accordingly.
178
application should pass it to a corresponding GSS-API routine which
179
will decode the token and extract the information, updating the
180
security context state information accordingly.
185
181
186
182
3. Per-message services are invoked to apply either: integrity and
187
183
data origin authentication, or confidentiality, integrity and data
188
184
origin authentication to application data, which are treated by
189
185
GSS-API as arbitrary octet-strings. An application transmitting a
190
message that it wishes to protect will call the appropriate
191
GSS-API routine (gss_get_mic or gss_wrap) to apply protection,
192
specifying the appropriate security context, and send the
193
resulting token to the receiving application. The receiver will
194
pass the received token (and, in the case of data protected by
195
gss_get_mic, the accompanying message-data) to the corresponding
196
decoding routine (gss_verify_mic or gss_unwrap) to remove the
197
protection and validate the data.
186
message that it wishes to protect will call the appropriate GSS-API
187
routine (gss_get_mic or gss_wrap) to apply protection, specifying
188
the appropriate security context, and send the resulting token to
189
the receiving application. The receiver will pass the received
190
token (and, in the case of data protected by gss_get_mic, the
191
accompanying message-data) to the corresponding decoding routine
192
(gss_verify_mic or gss_unwrap) to remove the protection and
193
validate the data.
198
194
199
195
4. At the completion of a communications session (which may extend
200
196
across several transport connections), each application calls a
211
207
212
208
GSS has at some point in time been tested on the following platforms.
213
209
214
1. Debian GNU/Linux 3.0 (Woody)
215
216
GCC 2.95.4 and GNU Make. This is the main development platform.
217
`alphaev67-unknown-linux-gnu', `alphaev6-unknown-linux-gnu',
218
`arm-unknown-linux-gnu', `hppa-unknown-linux-gnu',
219
`hppa64-unknown-linux-gnu', `i686-pc-linux-gnu',
220
`ia64-unknown-linux-gnu', `m68k-unknown-linux-gnu',
221
`mips-unknown-linux-gnu', `mipsel-unknown-linux-gnu',
222
`powerpc-unknown-linux-gnu', `s390-ibm-linux-gnu',
223
`sparc-unknown-linux-gnu'.
224
225
2. Debian GNU/Linux 2.1
226
227
GCC 2.95.1 and GNU Make. `armv4l-unknown-linux-gnu'.
228
229
3. Tru64 UNIX
230
231
Tru64 UNIX C compiler and Tru64 Make. `alphaev67-dec-osf5.1',
232
`alphaev68-dec-osf5.1'.
233
234
4. SuSE Linux 7.1
235
236
GCC 2.96 and GNU Make. `alphaev6-unknown-linux-gnu',
237
`alphaev67-unknown-linux-gnu'.
238
239
5. SuSE Linux 7.2a
240
241
GCC 3.0 and GNU Make. `ia64-unknown-linux-gnu'.
242
243
6. RedHat Linux 7.2
244
245
GCC 2.96 and GNU Make. `alphaev6-unknown-linux-gnu',
246
`alphaev67-unknown-linux-gnu', `ia64-unknown-linux-gnu'.
247
248
7. RedHat Linux 8.0
249
250
GCC 3.2 and GNU Make. `i686-pc-linux-gnu'.
251
252
8. RedHat Advanced Server 2.1
253
254
GCC 2.96 and GNU Make. `i686-pc-linux-gnu'.
255
256
9. Slackware Linux 8.0.01
257
258
GCC 2.95.3 and GNU Make. `i686-pc-linux-gnu'.
259
260
10. Mandrake Linux 9.0
261
262
GCC 3.2 and GNU Make. `i686-pc-linux-gnu'.
263
264
11. IRIX 6.5
265
266
MIPS C compiler, IRIX Make. `mips-sgi-irix6.5'.
267
268
12. AIX 4.3.2
269
270
IBM C for AIX compiler, AIX Make. `rs6000-ibm-aix4.3.2.0'.
271
272
13. Microsoft Windows 2000 (Cygwin)
273
274
GCC 3.2, GNU make. `i686-pc-cygwin'.
275
276
14. HP-UX 11
277
278
HP-UX C compiler and HP Make. `ia64-hp-hpux11.22',
279
`hppa2.0w-hp-hpux11.11'.
280
281
15. SUN Solaris 2.8
282
283
Sun WorkShop Compiler C 6.0 and SUN Make. `sparc-sun-solaris2.8'.
284
285
16. NetBSD 1.6
286
287
GCC 2.95.3 and GNU Make. `alpha-unknown-netbsd1.6',
288
`i386-unknown-netbsdelf1.6'.
289
290
17. OpenBSD 3.1 and 3.2
291
292
GCC 2.95.3 and GNU Make. `alpha-unknown-openbsd3.1',
293
`i386-unknown-openbsd3.1'.
294
295
18. FreeBSD 4.7
296
297
GCC 2.95.4 and GNU Make. `alpha-unknown-freebsd4.7',
298
`i386-unknown-freebsd4.7'.
299
300
19. Cross compiled to uClinux/uClibc on Motorola Coldfire.
301
302
GCC 3.4 and GNU Make `m68k-uclinux-elf'.
303
210
1. Debian GNU/Linux 3.0 (Woody)
211
212
GCC 2.95.4 and GNU Make. This is the main development platform.
213
'alphaev67-unknown-linux-gnu', 'alphaev6-unknown-linux-gnu',
214
'arm-unknown-linux-gnu', 'hppa-unknown-linux-gnu',
215
'hppa64-unknown-linux-gnu', 'i686-pc-linux-gnu',
216
'ia64-unknown-linux-gnu', 'm68k-unknown-linux-gnu',
217
'mips-unknown-linux-gnu', 'mipsel-unknown-linux-gnu',
218
'powerpc-unknown-linux-gnu', 's390-ibm-linux-gnu',
219
'sparc-unknown-linux-gnu'.
220
221
2. Debian GNU/Linux 2.1
222
223
GCC 2.95.1 and GNU Make. 'armv4l-unknown-linux-gnu'.
224
225
3. Tru64 UNIX
226
227
Tru64 UNIX C compiler and Tru64 Make. 'alphaev67-dec-osf5.1',
228
'alphaev68-dec-osf5.1'.
229
230
4. SuSE Linux 7.1
231
232
GCC 2.96 and GNU Make. 'alphaev6-unknown-linux-gnu',
233
'alphaev67-unknown-linux-gnu'.
234
235
5. SuSE Linux 7.2a
236
237
GCC 3.0 and GNU Make. 'ia64-unknown-linux-gnu'.
238
239
6. RedHat Linux 7.2
240
241
GCC 2.96 and GNU Make. 'alphaev6-unknown-linux-gnu',
242
'alphaev67-unknown-linux-gnu', 'ia64-unknown-linux-gnu'.
243
244
7. RedHat Linux 8.0
245
246
GCC 3.2 and GNU Make. 'i686-pc-linux-gnu'.
247
248
8. RedHat Advanced Server 2.1
249
250
GCC 2.96 and GNU Make. 'i686-pc-linux-gnu'.
251
252
9. Slackware Linux 8.0.01
253
254
GCC 2.95.3 and GNU Make. 'i686-pc-linux-gnu'.
255
256
10. Mandrake Linux 9.0
257
258
GCC 3.2 and GNU Make. 'i686-pc-linux-gnu'.
259
260
11. IRIX 6.5
261
262
MIPS C compiler, IRIX Make. 'mips-sgi-irix6.5'.
263
264
12. AIX 4.3.2
265
266
IBM C for AIX compiler, AIX Make. 'rs6000-ibm-aix4.3.2.0'.
267
268
13. Microsoft Windows 2000 (Cygwin)
269
270
GCC 3.2, GNU make. 'i686-pc-cygwin'.
271
272
14. HP-UX 11
273
274
HP-UX C compiler and HP Make. 'ia64-hp-hpux11.22',
275
'hppa2.0w-hp-hpux11.11'.
276
277
15. SUN Solaris 2.8
278
279
Sun WorkShop Compiler C 6.0 and SUN Make. 'sparc-sun-solaris2.8'.
280
281
16. NetBSD 1.6
282
283
GCC 2.95.3 and GNU Make. 'alpha-unknown-netbsd1.6',
284
'i386-unknown-netbsdelf1.6'.
285
286
17. OpenBSD 3.1 and 3.2
287
288
GCC 2.95.3 and GNU Make. 'alpha-unknown-openbsd3.1',
289
'i386-unknown-openbsd3.1'.
290
291
18. FreeBSD 4.7
292
293
GCC 2.95.4 and GNU Make. 'alpha-unknown-freebsd4.7',
294
'i386-unknown-freebsd4.7'.
295
296
19. Cross compiled to uClinux/uClibc on Motorola Coldfire.
297
298
GCC 3.4 and GNU Make 'm68k-uclinux-elf'.
304
299
305
300
If you use GSS on, or port GSS to, a new platform please report it to
306
301
the author.
311
306
1.5 Commercial Support
312
307
======================
313
308
314
Commercial support is available for users of GNU GSS. The kind of
309
Commercial support is available for users of GNU GSS. The kind of
315
310
support that can be purchased may include:
316
311
317
312
* Implement new features. Such as a new GSS-API mechanism.
323
318
324
319
* System design of components related to GSS-API.
325
320
326
327
321
If you are interested, please write to:
328
322
329
323
Simon Josefsson Datakonsult AB
344
338
345
339
The package can be downloaded from several places, including:
346
340
347
`ftp://ftp.gnu.org/gnu/gss/'
341
<ftp://ftp.gnu.org/gnu/gss/>
348
342
349
The latest version is stored in a file, e.g., `gss-1.0.2.tar.gz'
350
where the `1.0.2' indicate the highest version number.
343
The latest version is stored in a file, e.g., 'gss-1.0.3.tar.gz'
344
where the '1.0.3' indicate the highest version number.
351
345
352
346
The package is then extracted, configured and built like many other
353
packages that use Autoconf. For detailed information on configuring
354
and building it, refer to the `INSTALL' file that is part of the
347
packages that use Autoconf. For detailed information on configuring and
348
building it, refer to the 'INSTALL' file that is part of the
355
349
distribution archive.
356
350
357
351
Here is an example terminal session that downloads, configures,
358
352
builds and installs the package. You will need a few basic tools, such
359
as `sh', `make' and `cc'.
353
as 'sh', 'make' and 'cc'.
360
354
361
$ wget -q ftp://ftp.gnu.org/gnu/gss/gss-1.0.2.tar.gz
362
$ tar xfz gss-1.0.2.tar.gz
363
$ cd gss-1.0.2/
355
$ wget -q ftp://ftp.gnu.org/gnu/gss/gss-1.0.3.tar.gz
356
$ tar xfz gss-1.0.3.tar.gz
357
$ cd gss-1.0.3/
364
358
$ ./configure
365
359
...
366
360
$ make
379
373
If you think you have found a bug in GSS, please investigate it and
380
374
report it.
381
375
382
* Please make sure that the bug is really in GSS, and preferably
383
also check that it hasn't already been fixed in the latest version.
376
* Please make sure that the bug is really in GSS, and preferably also
377
check that it hasn't already been fixed in the latest version.
384
378
385
379
* You have to send us a test case that makes it possible for us to
386
380
reproduce the bug.
390
384
Make sure that the bug report includes all information you would
391
385
need to fix this kind of bug for someone else.
392
386
393
394
387
Please make an effort to produce a self-contained report, with
395
388
something definite that can be tested or debugged. Vague queries or
396
389
piecemeal messages are difficult to act on and don't help the
406
399
407
400
Send your bug report to:
408
401
409
`bug-gss@gnu.org'
402
'bug-gss@gnu.org'
410
403
411
404
412
405
File: gss.info, Node: Contributing, Next: Planned Features, Prev: Bug Reports, Up: Introduction
417
410
If you want to submit a patch for inclusion - from solve a typo you
418
411
discovered, up to adding support for a new feature - you should submit
419
412
it as a bug report (*note Bug Reports::). There are some things that
420
you can do to increase the chances for it to be included in the
421
official package.
413
you can do to increase the chances for it to be included in the official
414
package.
422
415
423
416
Unless your patch is very small (say, under 10 lines) we require that
424
417
you assign the copyright of your work to the Free Software Foundation.
435
428
Standards: (standards)top.).
436
429
437
430
If you normally code using another coding standard, there is no
438
problem, but you should use `indent' to reformat the code (*note
431
problem, but you should use 'indent' to reformat the code (*note
439
432
GNU Indent: (indent)top.) before submitting your work.
440
433
441
* Use the unified diff format `diff -u'.
434
* Use the unified diff format 'diff -u'.
442
435
443
436
* Return errors. No reason whatsoever should abort the execution of
444
the library. Even memory allocation errors, e.g. when malloc
437
the library. Even memory allocation errors, e.g. when malloc
445
438
return NULL, should work although result in an error code.
446
439
447
440
* Design with thread safety in mind. Don't use global variables.
459
452
460
453
* Supply a ChangeLog and NEWS entries, where appropriate.
461
454
462
463
455
464
456
File: gss.info, Node: Planned Features, Prev: Contributing, Up: Introduction
465
457
476
468
477
469
* Support loadable modules via dlopen, a'la Solaris GSS.
478
470
479
* Port to Cyclone? CCured?
480
471
* Port to Cyclone? CCured?
481
472
482
473
483
474
File: gss.info, Node: Preparation, Next: Standard GSS API, Prev: Introduction, Up: Top
487
478
488
479
To use GSS, you have to perform some changes to your sources and the
489
480
build system. The necessary changes are small and explained in the
490
following sections. At the end of this chapter, it is described how
491
the library is initialized, and how the requirements of the library are
481
following sections. At the end of this chapter, it is described how the
482
library is initialized, and how the requirements of the library are
492
483
verified.
493
484
494
485
A faster way to find out how to adapt your application for use with
509
500
==========
510
501
511
502
All standard interfaces (data types and functions) of the official GSS
512
API are defined in the header file `gss/api.h'. The file is taken
503
API are defined in the header file 'gss/api.h'. The file is taken
513
504
verbatim from the RFC (after correcting a few typos) where it is known
514
as `gssapi.h'. However, to be able to co-exist gracefully with other
515
GSS-API implementation, the name `gssapi.h' was changed.
505
as 'gssapi.h'. However, to be able to co-exist gracefully with other
506
GSS-API implementation, the name 'gssapi.h' was changed.
516
507
517
The header file `gss.h' includes `gss/api.h', and declares a few
518
non-standard extensions (by including `gss/ext.h'), takes care of
508
The header file 'gss.h' includes 'gss/api.h', and declares a few
509
non-standard extensions (by including 'gss/ext.h'), takes care of
519
510
including header files related to all supported mechanisms (e.g.,
520
`gss/krb5.h') and finally adds C++ namespace protection of all
521
definitions. Therefore, including `gss.h' in your project is
522
recommended over `gss/api.h'. If using `gss.h' instead of `gss/api.h'
511
'gss/krb5.h') and finally adds C++ namespace protection of all
512
definitions. Therefore, including 'gss.h' in your project is
513
recommended over 'gss/api.h'. If using 'gss.h' instead of 'gss/api.h'
523
514
causes problems, it should be regarded a bug.
524
515
525
516
You must include either file in all programs using the library,
527
518
528
519
#include <gss.h>
529
520
530
The name space of GSS is `gss_*' for function names, `gss_*' for
531
data types and `GSS_*' for other symbols. In addition the same name
532
prefixes with one prepended underscore are reserved for internal use
533
and should never be used by an application.
521
The name space of GSS is 'gss_*' for function names, 'gss_*' for data
522
types and 'GSS_*' for other symbols. In addition the same name prefixes
523
with one prepended underscore are reserved for internal use and should
524
never be used by an application.
534
525
535
526
Each supported GSS mechanism may want to expose mechanism specific
536
527
functionality, and can do so through one or more header files under the
537
`gss/' directory. The Kerberos 5 mechanism uses the file `gss/krb5.h',
538
but again, it is included (with C++ namespace fixes) from `gss.h'.
528
'gss/' directory. The Kerberos 5 mechanism uses the file 'gss/krb5.h',
529
but again, it is included (with C++ namespace fixes) from 'gss.h'.
539
530
540
531
541
532
File: gss.info, Node: Initialization, Next: Version Check, Prev: Header, Up: Preparation
546
537
GSS does not need to be initialized before it can be used.
547
538
548
539
In order to take advantage of the internationalisation features in
549
GSS, e.g. translated error messages, the application must set the
550
current locale using `setlocale()' before calling, e.g.,
551
`gss_display_status()'. This is typically done in `main()' as in the
540
GSS, e.g. translated error messages, the application must set the
541
current locale using 'setlocale()' before calling, e.g.,
542
'gss_display_status()'. This is typically done in 'main()' as in the
552
543
following example.
553
544
554
545
#include <gss.h>
566
557
one which fits all requirements. Even with binary compatibility new
567
558
features may have been introduced but due to problem with the dynamic
568
559
linker an old version is actually used. So you may want to check that
569
the version is okay right after program startup. The function is
570
called `gss_check_version()' and is described formally in *Note
571
Extended GSS API::.
560
the version is okay right after program startup. The function is called
561
'gss_check_version()' and is described formally in *Note Extended GSS
562
API::.
572
563
573
564
The normal way to use the function is to put something similar to the
574
following early in your `main()':
565
following early in your 'main()':
575
566
576
567
#include <gss.h>
577
568
...
588
579
2.4 Building the source
589
580
=======================
590
581
591
If you want to compile a source file that includes the `gss.h' header
582
If you want to compile a source file that includes the 'gss.h' header
592
583
file, you must make sure that the compiler can find it in the directory
593
584
hierarchy. This is accomplished by adding the path to the directory in
594
585
which the header file is located to the compilers include file search
595
path (via the `-I' option).
586
path (via the '-I' option).
596
587
597
588
However, the path to the include file is determined at the time the
598
589
source is configured. To solve this problem, GSS uses the external
599
package `pkg-config' that knows the path to the include file and other
590
package 'pkg-config' that knows the path to the include file and other
600
591
configuration options. The options that need to be added to the
601
compiler invocation at compile time are output by the `--cflags' option
602
to `pkg-config gss'. The following example shows how it can be used at
592
compiler invocation at compile time are output by the '--cflags' option
593
to 'pkg-config gss'. The following example shows how it can be used at
603
594
the command line:
604
595
605
596
gcc -c foo.c `pkg-config gss --cflags`
606
597
607
Adding the output of `pkg-config gss --cflags' to the compilers
608
command line will ensure that the compiler can find the `gss.h' header
598
Adding the output of 'pkg-config gss --cflags' to the compilers
599
command line will ensure that the compiler can find the 'gss.h' header
609
600
file.
610
601
611
602
A similar problem occurs when linking the program with the library.
612
603
Again, the compiler has to find the library files. For this to work,
613
the path to the library files has to be added to the library search
614
path (via the `-L' option). For this, the option `--libs' to
615
`pkg-config gss' can be used. For convenience, this option also
616
outputs all other options that are required to link the program with
617
the GSS libarary (for instance, the `-lshishi' option). The example
618
shows how to link `foo.o' with GSS into a program `foo'.
604
the path to the library files has to be added to the library search path
605
(via the '-L' option). For this, the option '--libs' to 'pkg-config
606
gss' can be used. For convenience, this option also outputs all other
607
options that are required to link the program with the GSS libarary (for
608
instance, the '-lshishi' option). The example shows how to link 'foo.o'
609
with GSS into a program 'foo'.
619
610
620
611
gcc -o foo foo.o `pkg-config gss --libs`
621
612
622
613
Of course you can also combine both examples to a single command by
623
specifying both options to `pkg-config':
614
specifying both options to 'pkg-config':
624
615
625
616
gcc -o foo foo.c `pkg-config gss --cflags --libs`
626
617
631
622
==========================
632
623
633
624
The GSS API does not have a standard error code for the out of memory
634
error condition. This library will return `GSS_S_FAILURE' and set
635
`minor_status' to ENOMEM.
625
error condition. This library will return 'GSS_S_FAILURE' and set
626
'minor_status' to ENOMEM.
636
627
637
628
638
629
File: gss.info, Node: Standard GSS API, Next: Extended GSS API, Prev: Preparation, Up: Top
673
664
674
665
Many of the GSS-API routines take arguments and return values that
675
666
describe contiguous octet-strings. All such data is passed between the
676
GSS-API and the caller using the `gss_buffer_t' data type. This data
667
GSS-API and the caller using the 'gss_buffer_t' data type. This data
677
668
type is a pointer to a buffer descriptor, which consists of a length
678
669
field that contains the total number of bytes in the datum, and a value
679
670
field which contains a pointer to the actual datum:
684
675
} gss_buffer_desc, *gss_buffer_t;
685
676
686
677
Storage for data returned to the application by a GSS-API routine
687
using the `gss_buffer_t' conventions is allocated by the GSS-API
678
using the 'gss_buffer_t' conventions is allocated by the GSS-API
688
679
routine. The application may free this storage by invoking the
689
`gss_release_buffer' routine. Allocation of the `gss_buffer_desc'
680
'gss_release_buffer' routine. Allocation of the 'gss_buffer_desc'
690
681
object is always the responsibility of the application; unused
691
`gss_buffer_desc' objects may be initialized to the value
692
`GSS_C_EMPTY_BUFFER'.
682
'gss_buffer_desc' objects may be initialized to the value
683
'GSS_C_EMPTY_BUFFER'.
693
684
694
685
3.1.2.1 Opaque data types
695
686
.........................
696
687
697
Certain multiple-word data items are considered opaque data types at
698
the GSS-API, because their internal structure has no significance
699
either to the GSS-API or to the caller. Examples of such opaque data
700
types are the input_token parameter to `gss_init_sec_context' (which is
701
opaque to the caller), and the input_message parameter to `gss_wrap'
702
(which is opaque to the GSS-API). Opaque data is passed between the
703
GSS-API and the application using the `gss_buffer_t' datatype.
688
Certain multiple-word data items are considered opaque data types at the
689
GSS-API, because their internal structure has no significance either to
690
the GSS-API or to the caller. Examples of such opaque data types are
691
the input_token parameter to 'gss_init_sec_context' (which is opaque to
692
the caller), and the input_message parameter to 'gss_wrap' (which is
693
opaque to the GSS-API). Opaque data is passed between the GSS-API and
694
the application using the 'gss_buffer_t' datatype.
704
695
705
696
3.1.2.2 Character strings
706
697
.........................
707
698
708
699
Certain multiple-word data items may be regarded as simple ISO Latin-1
709
700
character strings. Examples are the printable strings passed to
710
`gss_import_name' via the input_name_buffer parameter. Some GSS-API
701
'gss_import_name' via the input_name_buffer parameter. Some GSS-API
711
702
routines also return character strings. All such character strings are
712
703
passed between the application and the GSS-API implementation using the
713
`gss_buffer_t' datatype, which is a pointer to a `gss_buffer_desc'
704
'gss_buffer_t' datatype, which is a pointer to a 'gss_buffer_desc'
714
705
object.
715
706
716
When a `gss_buffer_desc' object describes a printable string, the
717
length field of the `gss_buffer_desc' should only count printable
707
When a 'gss_buffer_desc' object describes a printable string, the
708
length field of the 'gss_buffer_desc' should only count printable
718
709
characters within the string. In particular, a trailing NUL character
719
710
should NOT be included in the length count, nor should either the
720
711
GSS-API implementation or the application assume the presence of an
723
714
3.1.3 Object Identifiers
724
715
------------------------
725
716
726
Certain GSS-API procedures take parameters of the type `gss_OID', or
717
Certain GSS-API procedures take parameters of the type 'gss_OID', or
727
718
Object identifier. This is a type containing ISO-defined tree-
728
719
structured values, and is used by the GSS-API caller to select an
729
720
underlying security mechanism and to specify namespaces. A value of
730
type `gss_OID' has the following structure:
721
type 'gss_OID' has the following structure:
731
722
732
723
typedef struct gss_OID_desc_struct {
733
724
OM_uint32 length;
736
727
737
728
The elements field of this structure points to the first byte of an
738
729
octet string containing the ASN.1 BER encoding of the value portion of
739
the normal BER TLV encoding of the `gss_OID'. The length field
740
contains the number of bytes in this value. For example, the `gss_OID'
741
value corresponding to `iso(1) identified-organization(3) icd-ecma(12)
730
the normal BER TLV encoding of the 'gss_OID'. The length field contains
731
the number of bytes in this value. For example, the 'gss_OID' value
732
corresponding to 'iso(1) identified-organization(3) icd-ecma(12)
742
733
member-company(2) dec(1011) cryptoAlgorithms(7) DASS(5)', meaning the
743
734
DASS X.509 authentication mechanism, has a length field of 7 and an
744
735
elements field pointing to seven octets containing the following octal
745
values: 53,14,2,207,163,7,5. GSS-API implementations should provide
746
constant `gss_OID' values to allow applications to request any supported
736
values: 53,14,2,207,163,7,5. GSS-API implementations should provide
737
constant 'gss_OID' values to allow applications to request any supported
747
738
mechanism, although applications are encouraged on portability grounds
748
to accept the default mechanism. `gss_OID' values should also be
739
to accept the default mechanism. 'gss_OID' values should also be
749
740
provided to allow applications to specify particular name types (see
750
section 3.10). Applications should treat `gss_OID_desc' values
751
returned by GSS-API routines as read-only. In particular, the
752
application should not attempt to deallocate them with free().
741
section 3.10). Applications should treat 'gss_OID_desc' values returned
742
by GSS-API routines as read-only. In particular, the application should
743
not attempt to deallocate them with free().
753
744
754
745
3.1.4 Object Identifier Sets
755
746
----------------------------
756
747
757
Certain GSS-API procedures take parameters of the type `gss_OID_set'.
748
Certain GSS-API procedures take parameters of the type 'gss_OID_set'.
758
749
This type represents one or more object identifiers (*note Object
759
Identifiers::). A `gss_OID_set' object has the following structure:
750
Identifiers::). A 'gss_OID_set' object has the following structure:
760
751
761
752
typedef struct gss_OID_set_desc_struct {
762
753
size_t count;
764
755
} gss_OID_set_desc, *gss_OID_set;
765
756
766
757
The count field contains the number of OIDs within the set. The
767
elements field is a pointer to an array of `gss_OID_desc' objects, each
768
of which describes a single OID. `gss_OID_set' values are used to name
769
the available mechanisms supported by the GSS-API, to request the use
770
of specific mechanisms, and to indicate which mechanisms a given
771
credential supports.
758
elements field is a pointer to an array of 'gss_OID_desc' objects, each
759
of which describes a single OID. 'gss_OID_set' values are used to name
760
the available mechanisms supported by the GSS-API, to request the use of
761
specific mechanisms, and to indicate which mechanisms a given credential
762
supports.
772
763
773
764
All OID sets returned to the application by GSS-API are dynamic
774
objects (the `gss_OID_set_desc', the "elements" array of the set, and
765
objects (the 'gss_OID_set_desc', the "elements" array of the set, and
775
766
the "elements" array of each member OID are all dynamically allocated),
776
767
and this storage must be deallocated by the application using the
777
`gss_release_oid_set' routine.
768
'gss_release_oid_set' routine.
778
769
779
770
780
771
File: gss.info, Node: Complex Data Types, Next: Optional Parameters, Prev: Simple Data Types, Up: Standard GSS API
787
778
788
779
A credential handle is a caller-opaque atomic datum that identifies a
789
780
GSS-API credential data structure. It is represented by the caller-
790
opaque type `gss_cred_id_t'.
781
opaque type 'gss_cred_id_t'.
791
782
792
783
GSS-API credentials can contain mechanism-specific principal
793
784
authentication data for multiple mechanisms. A GSS-API credential is
794
composed of a set of credential-elements, each of which is applicable
795
to a single mechanism. A credential may contain at most one
796
credential-element for each supported mechanism. A credential-element
785
composed of a set of credential-elements, each of which is applicable to
786
a single mechanism. A credential may contain at most one
787
credential-element for each supported mechanism. A credential-element
797
788
identifies the data needed by a single mechanism to authenticate a
798
789
single principal, and conceptually contains two credential-references
799
790
that describe the actual mechanism-specific authentication data, one to
803
794
same underlying mechanism-specific authentication data.
804
795
805
796
Credentials describe a set of mechanism-specific principals, and give
806
their holder the ability to act as any of those principals. All
797
their holder the ability to act as any of those principals. All
807
798
principal identities asserted by a single GSS-API credential should
808
799
belong to the same entity, although enforcement of this property is an
809
800
implementation-specific matter. The GSS-API does not make the actual
813
804
the principal whose identity will be asserted by the credential when
814
805
used with that mechanism.
815
806
816
The `gss_init_sec_context' and `gss_accept_sec_context' routines
817
allow the value `GSS_C_NO_CREDENTIAL' to be specified as their
818
credential handle parameter. This special credential-handle indicates
819
a desire by the application to act as a default principal.
807
The 'gss_init_sec_context' and 'gss_accept_sec_context' routines
808
allow the value 'GSS_C_NO_CREDENTIAL' to be specified as their
809
credential handle parameter. This special credential-handle indicates a
810
desire by the application to act as a default principal.
820
811
821
812
3.2.2 Contexts
822
813
--------------
823
814
824
The `gss_ctx_id_t' data type contains a caller-opaque atomic value that
815
The 'gss_ctx_id_t' data type contains a caller-opaque atomic value that
825
816
identifies one end of a GSS-API security context.
826
817
827
818
The security context holds state information about each end of a peer
834
825
synchronization between the context data structures at each end of a
835
826
GSS-API security context. The token is a cryptographically protected
836
827
octet-string, generated by the underlying mechanism at one end of a
837
GSS-API security context for use by the peer mechanism at the other
838
end. Encapsulation (if required) and transfer of the token are the
828
GSS-API security context for use by the peer mechanism at the other end.
829
Encapsulation (if required) and transfer of the token are the
839
830
responsibility of the peer applications. A token is passed between the
840
GSS-API and the application using the `gss_buffer_t' conventions.
831
GSS-API and the application using the 'gss_buffer_t' conventions.
841
832
842
833
3.2.4 Interprocess tokens
843
834
-------------------------
844
835
845
Certain GSS-API routines are intended to transfer data between
846
processes in multi-process programs. These routines use a
847
caller-opaque octet-string, generated by the GSS-API in one process for
848
use by the GSS-API in another process. The calling application is
849
responsible for transferring such tokens between processes in an
850
OS-specific manner. Note that, while GSS-API implementors are
851
encouraged to avoid placing sensitive information within interprocess
852
tokens, or to cryptographically protect them, many implementations will
853
be unable to avoid placing key material or other sensitive data within
854
them. It is the application's responsibility to ensure that
855
interprocess tokens are protected in transit, and transferred only to
856
processes that are trustworthy. An interprocess token is passed between
857
the GSS-API and the application using the `gss_buffer_t' conventions.
836
Certain GSS-API routines are intended to transfer data between processes
837
in multi-process programs. These routines use a caller-opaque
838
octet-string, generated by the GSS-API in one process for use by the
839
GSS-API in another process. The calling application is responsible for
840
transferring such tokens between processes in an OS-specific manner.
841
Note that, while GSS-API implementors are encouraged to avoid placing
842
sensitive information within interprocess tokens, or to
843
cryptographically protect them, many implementations will be unable to
844
avoid placing key material or other sensitive data within them. It is
845
the application's responsibility to ensure that interprocess tokens are
846
protected in transit, and transferred only to processes that are
847
trustworthy. An interprocess token is passed between the GSS-API and
848
the application using the 'gss_buffer_t' conventions.
858
849
859
850
3.2.5 Names
860
851
-----------
871
862
Two distinct representations are defined for names:
872
863
873
864
* An internal form. This is the GSS-API "native" format for names,
874
represented by the implementation-specific `gss_name_t' type. It
875
is opaque to GSS-API callers. A single `gss_name_t' object may
865
represented by the implementation-specific 'gss_name_t' type. It
866
is opaque to GSS-API callers. A single 'gss_name_t' object may
876
867
contain multiple names from different namespaces, but all names
877
868
should refer to the same entity. An example of such an internal
878
869
name would be the name returned from a call to the
879
`gss_inquire_cred' routine, when applied to a credential
880
containing credential elements for multiple authentication
881
mechanisms employing different namespaces. This `gss_name_t'
882
object will contain a distinct name for the entity for each
883
authentication mechanism.
870
'gss_inquire_cred' routine, when applied to a credential containing
871
credential elements for multiple authentication mechanisms
872
employing different namespaces. This 'gss_name_t' object will
873
contain a distinct name for the entity for each authentication
874
mechanism.
884
875
885
For GSS-API implementations supporting multiple namespaces,
886
objects of type `gss_name_t' must contain sufficient information to
876
For GSS-API implementations supporting multiple namespaces, objects
877
of type 'gss_name_t' must contain sufficient information to
887
878
determine the namespace to which each primitive name belongs.
888
879
889
* Mechanism-specific contiguous octet-string forms. A format
890
capable of containing a single name (from a single namespace).
891
Contiguous string names are always accompanied by an object
892
identifier specifying the namespace to which the name belongs, and
893
their format is dependent on the authentication mechanism that
894
employs the name. Many, but not all, contiguous string names will
895
be printable, and may therefore be used by GSS-API applications for
880
* Mechanism-specific contiguous octet-string forms. A format capable
881
of containing a single name (from a single namespace). Contiguous
882
string names are always accompanied by an object identifier
883
specifying the namespace to which the name belongs, and their
884
format is dependent on the authentication mechanism that employs
885
the name. Many, but not all, contiguous string names will be
886
printable, and may therefore be used by GSS-API applications for
896
887
communication with their users.
897
888
898
Routines (`gss_import_name' and `gss_display_name') are provided to
899
convert names between contiguous string representations and the
900
internal `gss_name_t' type. `gss_import_name' may support multiple
901
syntaxes for each supported namespace, allowing users the freedom to
902
choose a preferred name representation. `gss_display_name' should use an
889
Routines ('gss_import_name' and 'gss_display_name') are provided to
890
convert names between contiguous string representations and the internal
891
'gss_name_t' type. 'gss_import_name' may support multiple syntaxes for
892
each supported namespace, allowing users the freedom to choose a
893
preferred name representation. 'gss_display_name' should use an
903
894
implementation-chosen printable syntax for each supported name-type.
904
895
905
If an application calls `gss_display_name', passing the internal
906
name resulting from a call to `gss_import_name', there is no guarantee
907
the resulting contiguous string name will be the same as the original
908
imported string name. Nor do name-space identifiers necessarily
909
survive unchanged after a journey through the internal name-form. An
910
example of this might be a mechanism that authenticates X.500 names,
911
but provides an algorithmic mapping of Internet DNS names into X.500.
912
That mechanism's implementation of `gss_import_name' might, when
913
presented with a DNS name, generate an internal name that contained
914
both the original DNS name and the equivalent X.500 name.
915
Alternatively, it might only store the X.500 name. In the latter case,
916
`gss_display_name' would most likely generate a printable X.500 name,
917
rather than the original DNS name.
896
If an application calls 'gss_display_name', passing the internal name
897
resulting from a call to 'gss_import_name', there is no guarantee the
898
resulting contiguous string name will be the same as the original
899
imported string name. Nor do name-space identifiers necessarily survive
900
unchanged after a journey through the internal name-form. An example of
901
this might be a mechanism that authenticates X.500 names, but provides
902
an algorithmic mapping of Internet DNS names into X.500. That
903
mechanism's implementation of 'gss_import_name' might, when presented
904
with a DNS name, generate an internal name that contained both the
905
original DNS name and the equivalent X.500 name. Alternatively, it
906
might only store the X.500 name. In the latter case, 'gss_display_name'
907
would most likely generate a printable X.500 name, rather than the
908
original DNS name.
918
909
919
910
The process of authentication delivers to the context acceptor an
920
911
internal name. Since this name has been authenticated by a single
921
912
mechanism, it contains only a single name (even if the internal name
922
presented by the context initiator to `gss_init_sec_context' had
913
presented by the context initiator to 'gss_init_sec_context' had
923
914
multiple components). Such names are termed internal mechanism names,
924
or "MN"s and the names emitted by `gss_accept_sec_context' are always
925
of this type. Since some applications may require MNs without wanting
926
to incur the overhead of an authentication operation, a second
927
function, `gss_canonicalize_name', is provided to convert a general
928
internal name into an MN.
915
or "MN"s and the names emitted by 'gss_accept_sec_context' are always of
916
this type. Since some applications may require MNs without wanting to
917
incur the overhead of an authentication operation, a second function,
918
'gss_canonicalize_name', is provided to convert a general internal name
919
into an MN.
929
920
930
921
Comparison of internal-form names may be accomplished via the
931
`gss_compare_name' routine, which returns true if the two names being
922
'gss_compare_name' routine, which returns true if the two names being
932
923
compared refer to the same entity. This removes the need for the
933
924
application program to understand the syntaxes of the various printable
934
925
names that a given GSS-API implementation may support. Since GSS-API
935
926
assumes that all primitive names contained within a given internal name
936
refer to the same entity, `gss_compare_name' can return true if the two
937
names have at least one primitive name in common. If the
938
implementation embodies knowledge of equivalence relationships between
939
names taken from different namespaces, this knowledge may also allow
940
successful comparison of internal names containing no overlapping
941
primitive elements.
927
refer to the same entity, 'gss_compare_name' can return true if the two
928
names have at least one primitive name in common. If the implementation
929
embodies knowledge of equivalence relationships between names taken from
930
different namespaces, this knowledge may also allow successful
931
comparison of internal names containing no overlapping primitive
932
elements.
942
933
943
934
When used in large access control lists, the overhead of invoking
944
`gss_import_name' and `gss_compare_name' on each name from the ACL may
935
'gss_import_name' and 'gss_compare_name' on each name from the ACL may
945
936
be prohibitive. As an alternative way of supporting this case, GSS-API
946
937
defines a special form of the contiguous string name which may be
947
compared directly (e.g. with memcmp()). Contiguous names suitable for
948
comparison are generated by the `gss_export_name' routine, which
938
compared directly (e.g. with memcmp()). Contiguous names suitable for
939
comparison are generated by the 'gss_export_name' routine, which
949
940
requires an MN as input. Exported names may be re- imported by the
950
`gss_import_name' routine, and the resulting internal name will also be
951
an MN. The `gss_OID' constant `GSS_C_NT_EXPORT_NAME' indentifies the
941
'gss_import_name' routine, and the resulting internal name will also be
942
an MN. The 'gss_OID' constant 'GSS_C_NT_EXPORT_NAME' indentifies the
952
943
"export name" type, and the value of this constant is given in Appendix
953
A. Structurally, an exported name object consists of a header
954
containing an OID identifying the mechanism that authenticated the
955
name, and a trailer containing the name itself, where the syntax of the
956
trailer is defined by the individual mechanism specification. The
957
precise format of an export name is defined in the language-independent
958
GSS-API specification [GSSAPI].
944
A. Structurally, an exported name object consists of a header containing
945
an OID identifying the mechanism that authenticated the name, and a
946
trailer containing the name itself, where the syntax of the trailer is
947
defined by the individual mechanism specification. The precise format
948
of an export name is defined in the language-independent GSS-API
949
specification [GSSAPI].
959
950
960
Note that the results obtained by using `gss_compare_name' will in
951
Note that the results obtained by using 'gss_compare_name' will in
961
952
general be different from those obtained by invoking
962
`gss_canonicalize_name' and `gss_export_name', and then comparing the
953
'gss_canonicalize_name' and 'gss_export_name', and then comparing the
963
954
exported names. The first series of operation determines whether two
964
955
(unauthenticated) names identify the same principal; the second whether
965
956
a particular mechanism would authenticate them as the same principal.
966
957
These two operations will in general give the same results only for MNs.
967
958
968
The `gss_name_t' datatype should be implemented as a pointer type.
959
The 'gss_name_t' datatype should be implemented as a pointer type.
969
960
To allow the compiler to aid the application programmer by performing
970
961
type-checking, the use of (void *) is discouraged. A pointer to an
971
962
implementation-defined type is the preferred choice.
972
963
973
Storage is allocated by routines that return `gss_name_t' values. A
974
procedure, `gss_release_name', is provided to free storage associated
964
Storage is allocated by routines that return 'gss_name_t' values. A
965
procedure, 'gss_release_name', is provided to free storage associated
975
966
with an internal-form name.
976
967
977
968
3.2.6 Channel Bindings
979
970
980
971
GSS-API supports the use of user-specified tags to identify a given
981
972
context to the peer application. These tags are intended to be used to
982
identify the particular communications channel that carries the
983
context. Channel bindings are communicated to the GSS-API using the
984
following structure:
973
identify the particular communications channel that carries the context.
974
Channel bindings are communicated to the GSS-API using the following
975
structure:
985
976
986
977
typedef struct gss_channel_bindings_struct {
987
978
OM_uint32 initiator_addrtype;
1030
1021
initiator_address, acceptor_addrtype, acceptor_address and
1031
1022
application_data to form an octet string. The mechanism calculates a
1032
1023
MIC over this octet string, and binds the MIC to the context
1033
establishment token emitted by `gss_init_sec_context'. The same bindings
1034
are presented by the context acceptor to `gss_accept_sec_context', and a
1035
MIC is calculated in the same way. The calculated MIC is compared with
1036
that found in the token, and if the MICs differ,
1037
`gss_accept_sec_context' will return a `GSS_S_BAD_BINDINGS' error, and
1038
the context will not be established. Some mechanisms may include the
1039
actual channel binding data in the token (rather than just a MIC);
1040
applications should therefore not use confidential data as
1024
establishment token emitted by 'gss_init_sec_context'. The same
1025
bindings are presented by the context acceptor to
1026
'gss_accept_sec_context', and a MIC is calculated in the same way. The
1027
calculated MIC is compared with that found in the token, and if the MICs
1028
differ, 'gss_accept_sec_context' will return a 'GSS_S_BAD_BINDINGS'
1029
error, and the context will not be established. Some mechanisms may
1030
include the actual channel binding data in the token (rather than just a
1031
MIC); applications should therefore not use confidential data as
1041
1032
channel-binding components.
1042
1033
1043
1034
Individual mechanisms may impose additional constraints on addresses
1044
1035
and address types that may appear in channel bindings. For example, a
1045
1036
mechanism may verify that the initiator_address field of the channel
1046
bindings presented to `gss_init_sec_context' contains the correct
1037
bindings presented to 'gss_init_sec_context' contains the correct
1047
1038
network address of the host system. Portable applications should
1048
1039
therefore ensure that they either provide correct information for the
1049
1040
address fields, or omit addressing information, specifying
1050
`GSS_C_AF_NULLADDR' as the address-types.
1041
'GSS_C_AF_NULLADDR' as the address-types.
1051
1042
1052
1043
1053
1044
File: gss.info, Node: Optional Parameters, Next: Error Handling, Prev: Complex Data Types, Up: Standard GSS API
1093
1084
3.4.1 GSS status codes
1094
1085
----------------------
1095
1086
1096
GSS-API routines return GSS status codes as their `OM_uint32' function
1087
GSS-API routines return GSS status codes as their 'OM_uint32' function
1097
1088
value. These codes indicate errors that are independent of the
1098
1089
underlying mechanism(s) used to provide the security service. The
1099
1090
errors that can be indicated via a GSS status code are either generic
1119
1110
field is non-zero, the invoking application's call of the routine was
1120
1111
erroneous. Calling errors are defined in table 3-1. If the routine
1121
1112
error field is non-zero, the routine failed for one of the routine-
1122
specific reasons listed below in table 3-2. Whether or not the upper
1123
16 bits indicate a failure or a success, the routine may indicate
1113
specific reasons listed below in table 3-2. Whether or not the upper 16
1114
bits indicate a failure or a success, the routine may indicate
1124
1115
additional information by setting bits in the supplementary info field
1125
of the status code. The meaning of individual bits is listed below in
1116
of the status code. The meaning of individual bits is listed below in
1126
1117
table 3-3.
1127
1118
1128
1119
Table 3-1 Calling Errors
1200
1191
a zero value, to indicate an absence of any API errors or supplementary
1201
1192
information bits.
1202
1193
1203
All GSS_S_xxx symbols equate to complete `OM_uint32' status codes,
1194
All GSS_S_xxx symbols equate to complete 'OM_uint32' status codes,
1204
1195
rather than to bitfield values. For example, the actual value of the
1205
symbol `GSS_S_BAD_NAMETYPE' (value 3 in the routine error field) is
1206
3<<16. The macros `GSS_CALLING_ERROR', `GSS_ROUTINE_ERROR' and
1207
`GSS_SUPPLEMENTARY_INFO' are provided, each of which takes a GSS status
1196
symbol 'GSS_S_BAD_NAMETYPE' (value 3 in the routine error field) is
1197
3<<16. The macros 'GSS_CALLING_ERROR', 'GSS_ROUTINE_ERROR' and
1198
'GSS_SUPPLEMENTARY_INFO' are provided, each of which takes a GSS status
1208
1199
code and removes all but the relevant field. For example, the value
1209
obtained by applying `GSS_ROUTINE_ERROR' to a status code removes the
1200
obtained by applying 'GSS_ROUTINE_ERROR' to a status code removes the
1210
1201
calling errors and supplementary info fields, leaving only the routine
1211
1202
errors field. The values delivered by these macros may be directly
1212
compared with a `GSS_S_xxx' symbol of the appropriate type. The macro
1213
`GSS_ERROR' is also provided, which when applied to a GSS status code
1203
compared with a 'GSS_S_xxx' symbol of the appropriate type. The macro
1204
'GSS_ERROR' is also provided, which when applied to a GSS status code
1214
1205
returns a non-zero value if the status code indicated a calling or
1215
1206
routine error, and a zero value otherwise. All macros defined by
1216
1207
GSS-API evaluate their argument(s) exactly once.
1220
1211
value; routine errors and supplementary info should be returned via
1221
1212
major status values only.
1222
1213
1223
The GSS major status code `GSS_S_FAILURE' is used to indicate that
1214
The GSS major status code 'GSS_S_FAILURE' is used to indicate that
1224
1215
the underlying mechanism detected an error for which no specific GSS
1225
status code is defined. The mechanism-specific status code will
1226
provide more details about the error.
1216
status code is defined. The mechanism-specific status code will provide
1217
more details about the error.
1227
1218
1228
1219
In addition to the explicit major status codes for each API function,
1229
the code `GSS_S_FAILURE' may be returned by any routine, indicating an
1220
the code 'GSS_S_FAILURE' may be returned by any routine, indicating an
1230
1221
implementation-specific or mechanism-specific error condition, further
1231
details of which are reported via the `minor_status' parameter.
1222
details of which are reported via the 'minor_status' parameter.
1232
1223
1233
1224
3.4.2 Mechanism-specific status codes
1234
1225
-------------------------------------
1236
1227
GSS-API routines return a minor_status parameter, which is used to
1237
1228
indicate specialized errors from the underlying security mechanism.
1238
1229
This parameter may contain a single mechanism-specific error, indicated
1239
by a `OM_uint32' value.
1230
by a 'OM_uint32' value.
1240
1231
1241
1232
The minor_status parameter will always be set by a GSS-API routine,
1242
1233
even if it returns a calling error or one of the generic API errors
1243
1234
indicated above as fatal, although most other output parameters may
1244
1235
remain unset in such cases. However, output parameters that are
1245
1236
expected to return pointers to storage allocated by a routine must
1246
always be set by the routine, even in the event of an error, although
1247
in such cases the GSS-API routine may elect to set the returned
1248
parameter value to NULL to indicate that no storage was actually
1249
allocated. Any length field associated with such pointers (as in a
1250
`gss_buffer_desc' structure) should also be set to zero in such cases.
1237
always be set by the routine, even in the event of an error, although in
1238
such cases the GSS-API routine may elect to set the returned parameter
1239
value to NULL to indicate that no storage was actually allocated. Any
1240
length field associated with such pointers (as in a 'gss_buffer_desc'
1241
structure) should also be set to zero in such cases.
1251
1242
1252
1243
1253
1244
File: gss.info, Node: Credential Management, Next: Context-Level Routines, Prev: Error Handling, Up: Standard GSS API
1280
1271
ACTUAL_MECHS, OM_uint32 * TIME_REC)
1281
1272
MINOR_STATUS: (integer, modify) Mechanism specific status code.
1282
1273
1283
DESIRED_NAME: (gss_name_t, read) Name of principal whose
1284
credential should be acquired.
1274
DESIRED_NAME: (gss_name_t, read) Name of principal whose credential
1275
should be acquired.
1285
1276
1286
1277
TIME_REQ: (Integer, read, optional) Number of seconds that
1287
credentials should remain valid. Specify GSS_C_INDEFINITE to
1278
credentials should remain valid. Specify GSS_C_INDEFINITE to
1288
1279
request that the credentials have the maximum permitted lifetime.
1289
1280
1290
1281
DESIRED_MECHS: (Set of Object IDs, read, optional) Set of
1293
1284
1294
1285
CRED_USAGE: (gss_cred_usage_t, read) GSS_C_BOTH - Credentials may
1295
1286
be used either to initiate or accept security contexts.
1296
GSS_C_INITIATE - Credentials will only be used to initiate
1297
security contexts. GSS_C_ACCEPT - Credentials will only be used
1298
to accept security contexts.
1287
GSS_C_INITIATE - Credentials will only be used to initiate security
1288
contexts. GSS_C_ACCEPT - Credentials will only be used to accept
1289
security contexts.
1299
1290
1300
OUTPUT_CRED_HANDLE: (gss_cred_id_t, modify) The returned
1301
credential handle. Resources associated with this credential
1302
handle must be released by the application after use with a call
1303
to gss_release_cred().
1291
OUTPUT_CRED_HANDLE: (gss_cred_id_t, modify) The returned credential
1292
handle. Resources associated with this credential handle must be
1293
released by the application after use with a call to
1294
gss_release_cred().
1304
1295
1305
1296
ACTUAL_MECHS: (Set of Object IDs, modify, optional) The set of
1306
1297
mechanisms for which the credential is valid. Storage associated
1307
with the returned OID-set must be released by the application
1308
after use with a call to gss_release_oid_set(). Specify NULL if
1309
not required.
1298
with the returned OID-set must be released by the application after
1299
use with a call to gss_release_oid_set(). Specify NULL if not
1300
required.
1310
1301
1311
1302
TIME_REC: (Integer, modify, optional) Actual number of seconds for
1312
1303
which the returned credentials will remain valid. If the
1313
1304
implementation does not support expiration of credentials, the
1314
value GSS_C_INDEFINITE will be returned. Specify NULL if not
1305
value GSS_C_INDEFINITE will be returned. Specify NULL if not
1315
1306
required.
1316
1307
1317
1308
Allows an application to acquire a handle for a pre-existing
1349
1340
1350
1341
If credential acquisition is time-consuming for a mechanism, the
1351
1342
mechanism may choose to delay the actual acquisition until the
1352
credential is required (e.g. by gss_init_sec_context or
1343
credential is required (e.g. by gss_init_sec_context or
1353
1344
gss_accept_sec_context). Such mechanism-specific implementation
1354
1345
decisions should be invisible to the calling application; thus a
1355
1346
call of gss_inquire_cred immediately following the call of
1358
1349
1359
1350
Return value:
1360
1351
1361
`GSS_S_COMPLETE': Successful completion.
1362
1363
`GSS_S_BAD_MECH': Unavailable mechanism requested.
1364
1365
`GSS_S_BAD_NAMETYPE': Type contained within desired_name parameter
1352
'GSS_S_COMPLETE': Successful completion.
1353
1354
'GSS_S_BAD_MECH': Unavailable mechanism requested.
1355
1356
'GSS_S_BAD_NAMETYPE': Type contained within desired_name parameter
1366
1357
is not supported.
1367
1358
1368
`GSS_S_BAD_NAME': Value supplied for desired_name parameter is ill
1359
'GSS_S_BAD_NAME': Value supplied for desired_name parameter is ill
1369
1360
formed.
1370
1361
1371
`GSS_S_CREDENTIALS_EXPIRED': The credentials could not be acquired
1362
'GSS_S_CREDENTIALS_EXPIRED': The credentials could not be acquired
1372
1363
Because they have expired.
1373
1364
1374
`GSS_S_NO_CRED': No credentials were found for the specified name.
1365
'GSS_S_NO_CRED': No credentials were found for the specified name.
1375
1366
1376
1367
gss_add_cred
1377
1368
------------
1399
1390
DESIRED_MECH: (Object ID, read) Underlying security mechanism with
1400
1391
which the credential may be used.
1401
1392
1402
CRED_USAGE: (gss_cred_usage_t, read) GSS_C_BOTH - Credential may
1403
be used either to initiate or accept security contexts.
1393
CRED_USAGE: (gss_cred_usage_t, read) GSS_C_BOTH - Credential may be
1394
used either to initiate or accept security contexts.
1404
1395
GSS_C_INITIATE - Credential will only be used to initiate security
1405
1396
contexts. GSS_C_ACCEPT - Credential will only be used to accept
1406
1397
security contexts.
1407
1398
1408
1399
INITIATOR_TIME_REQ: (Integer, read, optional) number of seconds
1409
1400
that the credential should remain valid for initiating security
1410
contexts. This argument is ignored if the composed credentials
1411
are of type GSS_C_ACCEPT. Specify GSS_C_INDEFINITE to request
1412
that the credentials have the maximum permitted initiator lifetime.
1401
contexts. This argument is ignored if the composed credentials are
1402
of type GSS_C_ACCEPT. Specify GSS_C_INDEFINITE to request that the
1403
credentials have the maximum permitted initiator lifetime.
1413
1404
1414
ACCEPTOR_TIME_REQ: (Integer, read, optional) number of seconds
1415
that the credential should remain valid for accepting security
1416
contexts. This argument is ignored if the composed credentials
1417
are of type GSS_C_INITIATE. Specify GSS_C_INDEFINITE to request
1418
that the credentials have the maximum permitted initiator lifetime.
1405
ACCEPTOR_TIME_REQ: (Integer, read, optional) number of seconds that
1406
the credential should remain valid for accepting security contexts.
1407
This argument is ignored if the composed credentials are of type
1408
GSS_C_INITIATE. Specify GSS_C_INDEFINITE to request that the
1409
credentials have the maximum permitted initiator lifetime.
1419
1410
1420
1411
OUTPUT_CRED_HANDLE: (gss_cred_id_t, modify, optional) The returned
1421
1412
credential handle, containing the new credential-element and all
1422
the credential-elements from input_cred_handle. If a valid
1423
pointer to a gss_cred_id_t is supplied for this parameter,
1424
gss_add_cred creates a new credential handle containing all
1425
credential-elements from the input_cred_handle and the newly
1426
acquired credential-element; if NULL is specified for this
1427
parameter, the newly acquired credential-element will be added to
1428
the credential identified by input_cred_handle. The resources
1429
associated with any credential handle returned via this parameter
1430
must be released by the application after use with a call to
1431
gss_release_cred().
1413
the credential-elements from input_cred_handle. If a valid pointer
1414
to a gss_cred_id_t is supplied for this parameter, gss_add_cred
1415
creates a new credential handle containing all credential-elements
1416
from the input_cred_handle and the newly acquired
1417
credential-element; if NULL is specified for this parameter, the
1418
newly acquired credential-element will be added to the credential
1419
identified by input_cred_handle. The resources associated with any
1420
credential handle returned via this parameter must be released by
1421
the application after use with a call to gss_release_cred().
1432
1422
1433
1423
ACTUAL_MECHS: (Set of Object IDs, modify, optional) The complete
1434
1424
set of mechanisms for which the new credential is valid. Storage
1435
for the returned OID-set must be freed by the application after
1436
use with a call to gss_release_oid_set(). Specify NULL if not
1425
for the returned OID-set must be freed by the application after use
1426
with a call to gss_release_oid_set(). Specify NULL if not
1437
1427
required.
1438
1428
1439
1429
INITIATOR_TIME_REC: (Integer, modify, optional) Actual number of
1440
1430
seconds for which the returned credentials will remain valid for
1441
1431
initiating contexts using the specified mechanism. If the
1442
1432
implementation or mechanism does not support expiration of
1443
credentials, the value GSS_C_INDEFINITE will be returned. Specify
1433
credentials, the value GSS_C_INDEFINITE will be returned. Specify
1444
1434
NULL if not required
1445
1435
1446
1436
ACCEPTOR_TIME_REC: (Integer, modify, optional) Actual number of
1447
1437
seconds for which the returned credentials will remain valid for
1448
1438
accepting security contexts using the specified mechanism. If the
1449
1439
implementation or mechanism does not support expiration of
1450
credentials, the value GSS_C_INDEFINITE will be returned. Specify
1440
credentials, the value GSS_C_INDEFINITE will be returned. Specify
1451
1441
NULL if not required
1452
1442
1453
1443
Adds a credential-element to a credential. The credential-element
1454
1444
is identified by the name of the principal to which it refers.
1455
1445
GSS-API implementations must impose a local access-control policy
1456
1446
on callers of this routine to prevent unauthorized callers from
1457
acquiring credential-elements to which they are not entitled. This
1447
acquiring credential-elements to which they are not entitled. This
1458
1448
routine is not intended to provide a "login to the network"
1459
1449
function, as such a function would involve the creation of new
1460
1450
mechanism-specific authentication data, rather than merely
1479
1469
1480
1470
If credential acquisition is time-consuming for a mechanism, the
1481
1471
mechanism may choose to delay the actual acquisition until the
1482
credential is required (e.g. by gss_init_sec_context or
1472
credential is required (e.g. by gss_init_sec_context or
1483
1473
gss_accept_sec_context). Such mechanism-specific implementation
1484
1474
decisions should be invisible to the calling application; thus a
1485
1475
call of gss_inquire_cred immediately following the call of
1489
1479
This routine can be used to either compose a new credential
1490
1480
containing all credential-elements of the original in addition to
1491
1481
the newly-acquire credential-element, or to add the new credential-
1492
element to an existing credential. If NULL is specified for the
1482
element to an existing credential. If NULL is specified for the
1493
1483
output_cred_handle parameter argument, the new credential-element
1494
will be added to the credential identified by input_cred_handle;
1495
if a valid pointer is specified for the output_cred_handle
1496
parameter, a new credential handle will be created.
1484
will be added to the credential identified by input_cred_handle; if
1485
a valid pointer is specified for the output_cred_handle parameter,
1486
a new credential handle will be created.
1497
1487
1498
1488
If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle,
1499
1489
gss_add_cred will compose a credential (and set the
1500
1490
output_cred_handle parameter accordingly) based on default
1501
1491
behavior. That is, the call will have the same effect as if the
1502
application had first made a call to gss_acquire_cred(),
1503
specifying the same usage and passing GSS_C_NO_NAME as the
1504
desired_name parameter to obtain an explicit credential handle
1505
embodying default behavior, passed this credential handle to
1506
gss_add_cred(), and finally called gss_release_cred() on the first
1507
credential handle.
1492
application had first made a call to gss_acquire_cred(), specifying
1493
the same usage and passing GSS_C_NO_NAME as the desired_name
1494
parameter to obtain an explicit credential handle embodying default
1495
behavior, passed this credential handle to gss_add_cred(), and
1496
finally called gss_release_cred() on the first credential handle.
1508
1497
1509
1498
If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle
1510
1499
parameter, a non-NULL output_cred_handle must be supplied.
1511
1500
1512
1501
Return value:
1513
1502
1514
`GSS_S_COMPLETE': Successful completion.
1515
1516
`GSS_S_BAD_MECH': Unavailable mechanism requested.
1517
1518
`GSS_S_BAD_NAMETYPE': Type contained within desired_name parameter
1503
'GSS_S_COMPLETE': Successful completion.
1504
1505
'GSS_S_BAD_MECH': Unavailable mechanism requested.
1506
1507
'GSS_S_BAD_NAMETYPE': Type contained within desired_name parameter
1519
1508
is not supported.
1520
1509
1521
`GSS_S_BAD_NAME': Value supplied for desired_name parameter is
1510
'GSS_S_BAD_NAME': Value supplied for desired_name parameter is
1522
1511
ill-formed.
1523
1512
1524
`GSS_S_DUPLICATE_ELEMENT': The credential already contains an
1513
'GSS_S_DUPLICATE_ELEMENT': The credential already contains an
1525
1514
element for the requested mechanism with overlapping usage and
1526
1515
validity period.
1527
1516
1528
`GSS_S_CREDENTIALS_EXPIRED': The required credentials could not be
1517
'GSS_S_CREDENTIALS_EXPIRED': The required credentials could not be
1529
1518
added because they have expired.
1530
1519
1531
`GSS_S_NO_CRED': No credentials were found for the specified name.
1520
'GSS_S_NO_CRED': No credentials were found for the specified name.
1532
1521
1533
1522
gss_inquire_cred
1534
1523
----------------
1550
1539
1551
1540
LIFETIME: (Integer, modify, optional) The number of seconds for
1552
1541
which the credential will remain valid. If the credential has
1553
expired, this parameter will be set to zero. If the
1554
implementation does not support credential expiration, the value
1555
GSS_C_INDEFINITE will be returned. Specify NULL if not required.
1542
expired, this parameter will be set to zero. If the implementation
1543
does not support credential expiration, the value GSS_C_INDEFINITE
1544
will be returned. Specify NULL if not required.
1556
1545
1557
CRED_USAGE: (gss_cred_usage_t, modify, optional) How the
1558
credential may be used. One of the following: GSS_C_INITIATE,
1559
GSS_C_ACCEPT, GSS_C_BOTH. Specify NULL if not required.
1546
CRED_USAGE: (gss_cred_usage_t, modify, optional) How the credential
1547
may be used. One of the following: GSS_C_INITIATE, GSS_C_ACCEPT,
1548
GSS_C_BOTH. Specify NULL if not required.
1560
1549
1561
1550
MECHANISMS: (gss_OID_set, modify, optional) Set of mechanisms
1562
1551
supported by the credential. Storage associated with this OID set
1567
1556
1568
1557
Return value:
1569
1558
1570
`GSS_S_COMPLETE': Successful completion.
1571
1572
`GSS_S_NO_CRED': The referenced credentials could not be accessed.
1573
1574
`GSS_S_DEFECTIVE_CREDENTIAL': The referenced credentials were
1559
'GSS_S_COMPLETE': Successful completion.
1560
1561
'GSS_S_NO_CRED': The referenced credentials could not be accessed.
1562
1563
'GSS_S_DEFECTIVE_CREDENTIAL': The referenced credentials were
1575
1564
invalid.
1576
1565
1577
`GSS_S_CREDENTIALS_EXPIRED': The referenced credentials have
1566
'GSS_S_CREDENTIALS_EXPIRED': The referenced credentials have
1578
1567
expired. If the lifetime parameter was not passed as NULL, it will
1579
1568
be set to 0.
1580
1569
1601
1590
1602
1591
INITIATOR_LIFETIME: (Integer, modify, optional) The number of
1603
1592
seconds for which the credential will remain capable of initiating
1604
security contexts under the specified mechanism. If the
1605
credential can no longer be used to initiate contexts, or if the
1606
credential usage for this mechanism is GSS_C_ACCEPT, this
1607
parameter will be set to zero. If the implementation does not
1608
support expiration of initiator credentials, the value
1609
GSS_C_INDEFINITE will be returned. Specify NULL if not required.
1593
security contexts under the specified mechanism. If the credential
1594
can no longer be used to initiate contexts, or if the credential
1595
usage for this mechanism is GSS_C_ACCEPT, this parameter will be
1596
set to zero. If the implementation does not support expiration of
1597
initiator credentials, the value GSS_C_INDEFINITE will be returned.
1598
Specify NULL if not required.
1610
1599
1611
1600
ACCEPTOR_LIFETIME: (Integer, modify, optional) The number of
1612
1601
seconds for which the credential will remain capable of accepting
1613
security contexts under the specified mechanism. If the
1614
credential can no longer be used to accept contexts, or if the
1615
credential usage for this mechanism is GSS_C_INITIATE, this
1616
parameter will be set to zero. If the implementation does not
1617
support expiration of acceptor credentials, the value
1618
GSS_C_INDEFINITE will be returned. Specify NULL if not required.
1602
security contexts under the specified mechanism. If the credential
1603
can no longer be used to accept contexts, or if the credential
1604
usage for this mechanism is GSS_C_INITIATE, this parameter will be
1605
set to zero. If the implementation does not support expiration of
1606
acceptor credentials, the value GSS_C_INDEFINITE will be returned.
1607
Specify NULL if not required.
1619
1608
1620
CRED_USAGE: (gss_cred_usage_t, modify, optional) How the
1621
credential may be used with the specified mechanism. One of the
1622
following: GSS_C_INITIATE, GSS_C_ACCEPT, GSS_C_BOTH. Specify NULL
1623
if not required.
1609
CRED_USAGE: (gss_cred_usage_t, modify, optional) How the credential
1610
may be used with the specified mechanism. One of the following:
1611
GSS_C_INITIATE, GSS_C_ACCEPT, GSS_C_BOTH. Specify NULL if not
1612
required.
1624
1613
1625
1614
Obtains per-mechanism information about a credential.
1626
1615
1627
1616
Return value:
1628
1617
1629
`GSS_S_COMPLETE': Successful completion.
1630
1631
`GSS_S_NO_CRED': The referenced credentials could not be accessed.
1632
1633
`GSS_S_DEFECTIVE_CREDENTIAL': The referenced credentials were
1618
'GSS_S_COMPLETE': Successful completion.
1619
1620
'GSS_S_NO_CRED': The referenced credentials could not be accessed.
1621
1622
'GSS_S_DEFECTIVE_CREDENTIAL': The referenced credentials were
1634
1623
invalid.
1635
1624
1636
`GSS_S_CREDENTIALS_EXPIRED': The referenced credentials have
1625
'GSS_S_CREDENTIALS_EXPIRED': The referenced credentials have
1637
1626
expired. If the lifetime parameter was not passed as NULL, it will
1638
1627
be set to 0.
1639
1628
1656
1645
1657
1646
Return value:
1658
1647
1659
`GSS_S_COMPLETE': Successful completion.
1648
'GSS_S_COMPLETE': Successful completion.
1660
1649
1661
`GSS_S_NO_CRED': Credentials could not be accessed.
1650
'GSS_S_NO_CRED': Credentials could not be accessed.
1662
1651
1663
1652
1664
1653
File: gss.info, Node: Context-Level Routines, Next: Per-Message Routines, Prev: Credential Management, Up: Standard GSS API
1694
1683
const gss_cred_id_t INITIATOR_CRED_HANDLE, gss_ctx_id_t *
1695
1684
CONTEXT_HANDLE, const gss_name_t TARGET_NAME, const gss_OID
1696
1685
MECH_TYPE, OM_uint32 REQ_FLAGS, OM_uint32 TIME_REQ, const
1697
gss_channel_bindings_t INPUT_CHAN_BINDINGS, const
1698
gss_buffer_t INPUT_TOKEN, gss_OID * ACTUAL_MECH_TYPE,
1699
gss_buffer_t OUTPUT_TOKEN, OM_uint32 * RET_FLAGS, OM_uint32 *
1700
TIME_REC)
1686
gss_channel_bindings_t INPUT_CHAN_BINDINGS, const gss_buffer_t
1687
INPUT_TOKEN, gss_OID * ACTUAL_MECH_TYPE, gss_buffer_t
1688
OUTPUT_TOKEN, OM_uint32 * RET_FLAGS, OM_uint32 * TIME_REC)
1701
1689
MINOR_STATUS: (integer, modify) Mechanism specific status code.
1702
1690
1703
1691
INITIATOR_CRED_HANDLE: (gss_cred_id_t, read, optional) Handle for
1707
1695
1708
1696
CONTEXT_HANDLE: (gss_ctx_id_t, read/modify) Context handle for new
1709
1697
context. Supply GSS_C_NO_CONTEXT for first call; use value
1710
returned by first call in continuation calls. Resources
1711
associated with this context-handle must be released by the
1712
application after use with a call to gss_delete_sec_context().
1698
returned by first call in continuation calls. Resources associated
1699
with this context-handle must be released by the application after
1700
use with a call to gss_delete_sec_context().
1713
1701
1714
1702
TARGET_NAME: (gss_name_t, read) Name of target.
1715
1703
1733
1721
Specify GSS_C_NO_CHANNEL_BINDINGS if channel bindings are not used.
1734
1722
1735
1723
INPUT_TOKEN: (buffer, opaque, read, optional) Token received from
1736
peer application. Supply GSS_C_NO_BUFFER, or a pointer to a
1737
buffer containing the value GSS_C_EMPTY_BUFFER on initial call.
1724
peer application. Supply GSS_C_NO_BUFFER, or a pointer to a buffer
1725
containing the value GSS_C_EMPTY_BUFFER on initial call.
1738
1726
1739
1727
ACTUAL_MECH_TYPE: (OID, modify, optional) Actual mechanism used.
1740
1728
The OID returned via this parameter will be a pointer to static
1757
1745
the context. See below for the flags.
1758
1746
1759
1747
TIME_REC: (Integer, modify, optional) Number of seconds for which
1760
the context will remain valid. If the implementation does not
1748
the context will remain valid. If the implementation does not
1761
1749
support context expiration, the value GSS_C_INDEFINITE will be
1762
1750
returned. Specify NULL if not required.
1763
1751
1769
1757
transferred to the peer application, where the peer application
1770
1758
will present it to gss_accept_sec_context. If no token need be
1771
1759
sent, gss_init_sec_context will indicate this by setting the length
1772
field of the output_token argument to zero. To complete the context
1773
establishment, one or more reply tokens may be required from the
1774
peer application; if so, gss_init_sec_context will return a status
1775
containing the supplementary information bit GSS_S_CONTINUE_NEEDED.
1776
In this case, gss_init_sec_context should be called again when the
1777
reply token is received from the peer application, passing the
1778
reply token to gss_init_sec_context via the input_token parameters.
1760
field of the output_token argument to zero. To complete the
1761
context establishment, one or more reply tokens may be required
1762
from the peer application; if so, gss_init_sec_context will return
1763
a status containing the supplementary information bit
1764
GSS_S_CONTINUE_NEEDED. In this case, gss_init_sec_context should be
1765
called again when the reply token is received from the peer
1766
application, passing the reply token to gss_init_sec_context via
1767
the input_token parameters.
1779
1768
1780
1769
Portable applications should be constructed to use the token length
1781
1770
and return status to determine whether a token needs to be sent or
1841
1830
GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG,
1842
1831
GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the
1843
1832
ret_flags parameter should contain the values that the
1844
implementation expects would be valid if context
1845
establishment were to succeed. In particular, if the
1846
application has requested a service such as delegation or
1847
anonymous authentication via the req_flags argument, and such
1848
a service is unavailable from the underlying mechanism,
1833
implementation expects would be valid if context establishment
1834
were to succeed. In particular, if the application has
1835
requested a service such as delegation or anonymous
1836
authentication via the req_flags argument, and such a service
1837
is unavailable from the underlying mechanism,
1849
1838
gss_init_sec_context should generate a token that will not
1850
1839
provide the service, and indicate via the ret_flags argument
1851
1840
that the service will not be supported. The application may
1862
1851
1863
1852
* GSS-API implementations that support per-message protection
1864
1853
are encouraged to set the GSS_C_PROT_READY_FLAG in the final
1865
ret_flags returned to a caller (i.e. when accompanied by a
1866
GSS_S_COMPLETE status code). However, applications should
1867
not rely on this behavior as the flag was not defined in
1868
Version 1 of the GSS-API. Instead, applications should
1869
determine what per-message services are available after a
1870
successful context establishment according to the
1871
GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.
1854
ret_flags returned to a caller (i.e. when accompanied by a
1855
GSS_S_COMPLETE status code). However, applications should not
1856
rely on this behavior as the flag was not defined in Version 1
1857
of the GSS-API. Instead, applications should determine what
1858
per-message services are available after a successful context
1859
establishment according to the GSS_C_INTEG_FLAG and
1860
GSS_C_CONF_FLAG values.
1872
1861
1873
1862
* All other bits within the ret_flags argument should be set to
1874
1863
zero.
1875
1864
1876
1877
1865
If the initial call of gss_init_sec_context() fails, the
1878
1866
implementation should not create a context object, and should leave
1879
1867
the value of the context_handle parameter set to GSS_C_NO_CONTEXT
1887
1875
During context establishment, the informational status bits
1888
1876
GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors,
1889
1877
and GSS-API mechanisms should always return them in association
1890
with a routine error of GSS_S_FAILURE. This requirement for
1891
pairing did not exist in version 1 of the GSS-API specification, so
1878
with a routine error of GSS_S_FAILURE. This requirement for pairing
1879
did not exist in version 1 of the GSS-API specification, so
1892
1880
applications that wish to run over version 1 implementations must
1893
1881
special-case these codes.
1894
1882
1895
The `req_flags' values:
1896
1897
1898
`GSS_C_DELEG_FLAG'
1883
The 'req_flags' values:
1884
1885
'GSS_C_DELEG_FLAG'
1899
1886
1900
1887
* True - Delegate credentials to remote peer.
1901
1888
1902
1889
* False - Don't delegate.
1903
1890
1904
1905
1906
`GSS_C_MUTUAL_FLAG'
1891
'GSS_C_MUTUAL_FLAG'
1907
1892
1908
1893
* True - Request that remote peer authenticate itself.
1909
1894
1910
1895
* False - Authenticate self to remote peer only.
1911
1896
1912
1913
1914
`GSS_C_REPLAY_FLAG'
1897
'GSS_C_REPLAY_FLAG'
1915
1898
1916
1899
* True - Enable replay detection for messages protected
1917
1900
with gss_wrap or gss_get_mic.
1918
1901
1919
1902
* False - Don't attempt to detect replayed messages.
1920
1903
1921
1922
1923
`GSS_C_SEQUENCE_FLAG'
1904
'GSS_C_SEQUENCE_FLAG'
1924
1905
1925
1906
* True - Enable detection of out-of-sequence protected
1926
1907
messages.
1927
1908
1928
1909
* False - Don't attempt to detect out-of-sequence messages.
1929
1910
1930
1931
1932
`GSS_C_CONF_FLAG'
1911
'GSS_C_CONF_FLAG'
1933
1912
1934
1913
* True - Request that confidentiality service be made
1935
1914
available (via gss_wrap).
1937
1916
* False - No per-message confidentiality service is
1938
1917
required.
1939
1918
1940
1941
1942
`GSS_C_INTEG_FLAG'
1919
'GSS_C_INTEG_FLAG'
1943
1920
1944
1921
* True - Request that integrity service be made available
1945
1922
(via gss_wrap or gss_get_mic).
1946
1923
1947
1924
* False - No per-message integrity service is required.
1948
1925
1949
1950
1951
`GSS_C_ANON_FLAG'
1926
'GSS_C_ANON_FLAG'
1952
1927
1953
1928
* True - Do not reveal the initiator's identity to the
1954
1929
acceptor.
1955
1930
1956
1931
* False - Authenticate normally.
1957
1932
1958
1959
The `ret_flags' values:
1960
1961
1962
`GSS_C_DELEG_FLAG'
1933
The 'ret_flags' values:
1934
1935
'GSS_C_DELEG_FLAG'
1963
1936
1964
1937
* True - Credentials were delegated to the remote peer.
1965
1938
1966
1939
* False - No credentials were delegated.
1967
1940
1968
1969
1970
`GSS_C_MUTUAL_FLAG'
1941
'GSS_C_MUTUAL_FLAG'
1971
1942
1972
1943
* True - The remote peer has authenticated itself.
1973
1944
1974
1945
* False - Remote peer has not authenticated itself.
1975
1946
1976
1977
1978
`GSS_C_REPLAY_FLAG'
1947
'GSS_C_REPLAY_FLAG'
1979
1948
1980
1949
* True - replay of protected messages will be detected.
1981
1950
1982
1951
* False - replayed messages will not be detected.
1983
1952
1984
1985
1986
`GSS_C_SEQUENCE_FLAG'
1953
'GSS_C_SEQUENCE_FLAG'
1987
1954
1988
1955
* True - out-of-sequence protected messages will be
1989
1956
detected.
1990
1957
1991
1958
* False - out-of-sequence messages will not be detected.
1992
1959
1993
1994
1995
`GSS_C_CONF_FLAG'
1960
'GSS_C_CONF_FLAG'
1996
1961
1997
1962
* True - Confidentiality service may be invoked by calling
1998
1963
gss_wrap routine.
1999
1964
2000
1965
* False - No confidentiality service (via gss_wrap)
2001
available. gss_wrap will provide message encapsulation,
1966
available. gss_wrap will provide message encapsulation,
2002
1967
data-origin authentication and integrity services only.
2003
1968
2004
2005
2006
`GSS_C_INTEG_FLAG'
1969
'GSS_C_INTEG_FLAG'
2007
1970
2008
1971
* True - Integrity service may be invoked by calling either
2009
1972
gss_get_mic or gss_wrap routines.
2010
1973
2011
1974
* False - Per-message integrity service unavailable.
2012
1975
2013
2014
2015
`GSS_C_ANON_FLAG'
1976
'GSS_C_ANON_FLAG'
2016
1977
2017
1978
* True - The initiator's identity has not been revealed,
2018
1979
and will not be revealed if any emitted token is passed
2021
1982
* False - The initiator's identity has been or will be
2022
1983
authenticated normally.
2023
1984
2024
2025
2026
`GSS_C_PROT_READY_FLAG'
2027
2028
* True - Protection services (as specified by the states
2029
of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are
2030
available for use if the accompanying major status
2031
return value is either GSS_S_COMPLETE or
2032
GSS_S_CONTINUE_NEEDED.
1985
'GSS_C_PROT_READY_FLAG'
1986
1987
* True - Protection services (as specified by the states of
1988
the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available
1989
for use if the accompanying major status return value is
1990
either GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED.
2033
1991
2034
1992
* False - Protection services (as specified by the states
2035
1993
of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are
2036
1994
available only if the accompanying major status return
2037
1995
value is GSS_S_COMPLETE.
2038
1996
2039
2040
2041
`GSS_C_TRANS_FLAG'
1997
'GSS_C_TRANS_FLAG'
2042
1998
2043
1999
* True - The resultant security context may be transferred
2044
2000
to other processes via a call to
2046
2002
2047
2003
* False - The security context is not transferable.
2048
2004
2049
2050
2005
All other bits should be set to zero.
2051
2006
2052
2007
Return value:
2053
2008
2054
`GSS_S_COMPLETE': Successful completion.
2009
'GSS_S_COMPLETE': Successful completion.
2055
2010
2056
`GSS_S_CONTINUE_NEEDED': Indicates that a token from the peer
2011
'GSS_S_CONTINUE_NEEDED': Indicates that a token from the peer
2057
2012
application is required to complete the context, and that
2058
2013
gss_init_sec_context must be called again with that token.
2059
2014
2060
`GSS_S_DEFECTIVE_TOKEN': Indicates that consistency checks
2015
'GSS_S_DEFECTIVE_TOKEN': Indicates that consistency checks
2061
2016
performed on the input_token failed.
2062
2017
2063
`GSS_S_DEFECTIVE_CREDENTIAL': Indicates that consistency checks
2018
'GSS_S_DEFECTIVE_CREDENTIAL': Indicates that consistency checks
2064
2019
performed on the credential failed.
2065
2020
2066
`GSS_S_NO_CRED': The supplied credentials were not valid for
2021
'GSS_S_NO_CRED': The supplied credentials were not valid for
2067
2022
context initiation, or the credential handle did not reference any
2068
2023
credentials.
2069
2024
2070
`GSS_S_CREDENTIALS_EXPIRED': The referenced credentials have
2025
'GSS_S_CREDENTIALS_EXPIRED': The referenced credentials have
2071
2026
expired.
2072
2027
2073
`GSS_S_BAD_BINDINGS': The input_token contains different channel
2028
'GSS_S_BAD_BINDINGS': The input_token contains different channel
2074
2029
bindings to those specified via the input_chan_bindings parameter.
2075
2030
2076
`GSS_S_BAD_SIG': The input_token contains an invalid MIC, or a MIC
2031
'GSS_S_BAD_SIG': The input_token contains an invalid MIC, or a MIC
2077
2032
that could not be verified.
2078
2033
2079
`GSS_S_OLD_TOKEN': The input_token was too old. This is a fatal
2034
'GSS_S_OLD_TOKEN': The input_token was too old. This is a fatal
2080
2035
error during context establishment.
2081
2036
2082
`GSS_S_DUPLICATE_TOKEN': The input_token is valid, but is a
2037
'GSS_S_DUPLICATE_TOKEN': The input_token is valid, but is a
2083
2038
duplicate of a token already processed. This is a fatal error
2084
2039
during context establishment.
2085
2040
2086
`GSS_S_NO_CONTEXT': Indicates that the supplied context handle did
2041
'GSS_S_NO_CONTEXT': Indicates that the supplied context handle did
2087
2042
not refer to a valid context.
2088
2043
2089
`GSS_S_BAD_NAMETYPE': The provided target_name parameter contained
2044
'GSS_S_BAD_NAMETYPE': The provided target_name parameter contained
2090
2045
an invalid or unsupported type of name.
2091
2046
2092
`GSS_S_BAD_NAME': The provided target_name parameter was
2047
'GSS_S_BAD_NAME': The provided target_name parameter was
2093
2048
ill-formed.
2094
2049
2095
`GSS_S_BAD_MECH': The specified mechanism is not supported by the
2050
'GSS_S_BAD_MECH': The specified mechanism is not supported by the
2096
2051
provided credential, or is unrecognized by the implementation.
2097
2052
2098
2053
gss_accept_sec_context
2115
2070
after use with a call to gss_delete_sec_context().
2116
2071
2117
2072
ACCEPTOR_CRED_HANDLE: (gss_cred_id_t, read) Credential handle
2118
claimed by context acceptor. Specify GSS_C_NO_CREDENTIAL to accept
2073
claimed by context acceptor. Specify GSS_C_NO_CREDENTIAL to accept
2119
2074
the context as a default principal. If GSS_C_NO_CREDENTIAL is
2120
2075
specified, but no default acceptor principal is defined,
2121
2076
GSS_S_NO_CRED will be returned.
2140
2095
2141
2096
OUTPUT_TOKEN: (buffer, opaque, modify) Token to be passed to peer
2142
2097
application. If the length field of the returned token buffer is
2143
0, then no token need be passed to the peer application. If a
2144
non- zero length field is returned, the associated storage must be
2145
freed after use by the application with a call to
2146
gss_release_buffer().
2098
0, then no token need be passed to the peer application. If a non-
2099
zero length field is returned, the associated storage must be freed
2100
after use by the application with a call to gss_release_buffer().
2147
2101
2148
2102
RET_FLAGS: (bit-mask, modify, optional) Contains various
2149
2103
independent flags, each of which indicates that the context
2154
2108
the context. See below for the flags.
2155
2109
2156
2110
TIME_REC: (Integer, modify, optional) Number of seconds for which
2157
the context will remain valid. Specify NULL if not required.
2111
the context will remain valid. Specify NULL if not required.
2158
2112
2159
DELEGATED_CRED_HANDLE: (gss_cred_id_t, modify, optional
2160
credential) Handle for credentials received from context
2161
initiator. Only valid if deleg_flag in ret_flags is true, in
2162
which case an explicit credential handle (i.e. not
2163
GSS_C_NO_CREDENTIAL) will be returned; if deleg_flag is false,
2164
gss_accept_sec_context() will set this parameter to
2165
GSS_C_NO_CREDENTIAL. If a credential handle is returned, the
2166
associated resources must be released by the application after use
2167
with a call to gss_release_cred(). Specify NULL if not required.
2113
DELEGATED_CRED_HANDLE: (gss_cred_id_t, modify, optional credential)
2114
Handle for credentials received from context initiator. Only valid
2115
if deleg_flag in ret_flags is true, in which case an explicit
2116
credential handle (i.e. not GSS_C_NO_CREDENTIAL) will be returned;
2117
if deleg_flag is false, gss_accept_sec_context() will set this
2118
parameter to GSS_C_NO_CREDENTIAL. If a credential handle is
2119
returned, the associated resources must be released by the
2120
application after use with a call to gss_release_cred(). Specify
2121
NULL if not required.
2168
2122
2169
2123
Allows a remotely initiated security context between the
2170
2124
application and a remote peer to be established. The routine may
2242
2196
2243
2197
Although this requires that GSS-API implementations set the
2244
2198
GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller
2245
(i.e. when accompanied by a GSS_S_COMPLETE status code),
2199
(i.e. when accompanied by a GSS_S_COMPLETE status code),
2246
2200
applications should not rely on this behavior as the flag was not
2247
2201
defined in Version 1 of the GSS-API. Instead, applications should
2248
2202
be prepared to use per-message services after a successful context
2268
2222
During context establishment, the informational status bits
2269
2223
GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors,
2270
2224
and GSS-API mechanisms should always return them in association
2271
with a routine error of GSS_S_FAILURE. This requirement for
2272
pairing did not exist in version 1 of the GSS-API specification,
2273
so applications that wish to run over version 1 implementations
2274
must special-case these codes.
2275
2276
The `ret_flags' values:
2277
2278
2279
`GSS_C_DELEG_FLAG'
2225
with a routine error of GSS_S_FAILURE. This requirement for pairing
2226
did not exist in version 1 of the GSS-API specification, so
2227
applications that wish to run over version 1 implementations must
2228
special-case these codes.
2229
2230
The 'ret_flags' values:
2231
2232
'GSS_C_DELEG_FLAG'
2280
2233
2281
2234
* True - Delegated credentials are available via the
2282
2235
delegated_cred_handle parameter.
2283
2236
2284
2237
* False - No credentials were delegated.
2285
2238
2286
2287
2288
`GSS_C_MUTUAL_FLAG'
2239
'GSS_C_MUTUAL_FLAG'
2289
2240
2290
2241
* True - Remote peer asked for mutual authentication.
2291
2242
2292
2243
* False - Remote peer did not ask for mutual
2293
2244
authentication.
2294
2245
2295
2296
2297
`GSS_C_REPLAY_FLAG'
2246
'GSS_C_REPLAY_FLAG'
2298
2247
2299
2248
* True - replay of protected messages will be detected.
2300
2249
2301
2250
* False - replayed messages will not be detected.
2302
2251
2303
2304
2305
`GSS_C_SEQUENCE_FLAG'
2252
'GSS_C_SEQUENCE_FLAG'
2306
2253
2307
2254
* True - out-of-sequence protected messages will be
2308
2255
detected.
2309
2256
2310
2257
* False - out-of-sequence messages will not be detected.
2311
2258
2312
2313
2314
`GSS_C_CONF_FLAG'
2259
'GSS_C_CONF_FLAG'
2315
2260
2316
2261
* True - Confidentiality service may be invoked by calling
2317
2262
the gss_wrap routine.
2318
2263
2319
2264
* False - No confidentiality service (via gss_wrap)
2320
available. gss_wrap will provide message encapsulation,
2265
available. gss_wrap will provide message encapsulation,
2321
2266
data-origin authentication and integrity services only.
2322
2267
2323
2324
2325
`GSS_C_INTEG_FLAG'
2268
'GSS_C_INTEG_FLAG'
2326
2269
2327
2270
* True - Integrity service may be invoked by calling either
2328
2271
gss_get_mic or gss_wrap routines.
2329
2272
2330
2273
* False - Per-message integrity service unavailable.
2331
2274
2332
2333
2334
`GSS_C_ANON_FLAG'
2275
'GSS_C_ANON_FLAG'
2335
2276
2336
2277
* True - The initiator does not wish to be authenticated;
2337
2278
the src_name parameter (if requested) contains an
2339
2280
2340
2281
* False - The initiator has been authenticated normally.
2341
2282
2342
2343
2344
`GSS_C_PROT_READY_FLAG'
2345
2346
* True - Protection services (as specified by the states
2347
of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are
2348
available if the accompanying major status return value
2349
is either GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED.
2283
'GSS_C_PROT_READY_FLAG'
2284
2285
* True - Protection services (as specified by the states of
2286
the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available
2287
if the accompanying major status return value is either
2288
GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED.
2350
2289
2351
2290
* False - Protection services (as specified by the states
2352
2291
of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are
2353
2292
available only if the accompanying major status return
2354
2293
value is GSS_S_COMPLETE.
2355
2294
2356
2357
2358
`GSS_C_TRANS_FLAG'
2295
'GSS_C_TRANS_FLAG'
2359
2296
2360
2297
* True - The resultant security context may be transferred
2361
2298
to other processes via a call to
2363
2300
2364
2301
* False - The security context is not transferable.
2365
2302
2366
2367
2303
All other bits should be set to zero.
2368
2304
2369
2305
Return value:
2370
2306
2371
`GSS_S_CONTINUE_NEEDED': Indicates that a token from the peer
2307
'GSS_S_CONTINUE_NEEDED': Indicates that a token from the peer
2372
2308
application is required to complete the context, and that
2373
2309
gss_accept_sec_context must be called again with that token.
2374
2310
2375
`GSS_S_DEFECTIVE_TOKEN': Indicates that consistency checks
2311
'GSS_S_DEFECTIVE_TOKEN': Indicates that consistency checks
2376
2312
performed on the input_token failed.
2377
2313
2378
`GSS_S_DEFECTIVE_CREDENTIAL': Indicates that consistency checks
2314
'GSS_S_DEFECTIVE_CREDENTIAL': Indicates that consistency checks
2379
2315
performed on the credential failed.
2380
2316
2381
`GSS_S_NO_CRED': The supplied credentials were not valid for
2317
'GSS_S_NO_CRED': The supplied credentials were not valid for
2382
2318
context acceptance, or the credential handle did not reference any
2383
2319
credentials.
2384
2320
2385
`GSS_S_CREDENTIALS_EXPIRED': The referenced credentials have
2321
'GSS_S_CREDENTIALS_EXPIRED': The referenced credentials have
2386
2322
expired.
2387
2323
2388
`GSS_S_BAD_BINDINGS': The input_token contains different channel
2324
'GSS_S_BAD_BINDINGS': The input_token contains different channel
2389
2325
bindings to those specified via the input_chan_bindings parameter.
2390
2326
2391
`GSS_S_NO_CONTEXT': Indicates that the supplied context handle did
2327
'GSS_S_NO_CONTEXT': Indicates that the supplied context handle did
2392
2328
not refer to a valid context.
2393
2329
2394
`GSS_S_BAD_SIG': The input_token contains an invalid MIC.
2330
'GSS_S_BAD_SIG': The input_token contains an invalid MIC.
2395
2331
2396
`GSS_S_OLD_TOKEN': The input_token was too old. This is a fatal
2332
'GSS_S_OLD_TOKEN': The input_token was too old. This is a fatal
2397
2333
error during context establishment.
2398
2334
2399
`GSS_S_DUPLICATE_TOKEN': The input_token is valid, but is a
2335
'GSS_S_DUPLICATE_TOKEN': The input_token is valid, but is a
2400
2336
duplicate of a token already processed. This is a fatal error
2401
2337
during context establishment.
2402
2338
2403
`GSS_S_BAD_MECH': The received token specified a mechanism that is
2339
'GSS_S_BAD_MECH': The received token specified a mechanism that is
2404
2340
not supported by the implementation or the provided credential.
2405
2341
2406
2342
gss_delete_sec_context
2420
2356
It is recommended that applications specify GSS_C_NO_BUFFER for
2421
2357
this parameter, requesting local deletion only. If a buffer
2422
2358
parameter is provided by the application, the mechanism may return
2423
a token in it; mechanisms that implement only local deletion
2424
should set the length field of this token to zero to indicate to
2425
the application that no token is to be sent to the peer.
2359
a token in it; mechanisms that implement only local deletion should
2360
set the length field of this token to zero to indicate to the
2361
application that no token is to be sent to the peer.
2426
2362
2427
2363
Delete a security context. gss_delete_sec_context will delete the
2428
2364
local data structures associated with the specified security
2439
2375
gss_init_sec_context()/gss_accept_sec_context() calls.
2440
2376
2441
2377
The output_token parameter is retained for compatibility with
2442
version 1 of the GSS-API. It is recommended that both peer
2378
version 1 of the GSS-API. It is recommended that both peer
2443
2379
applications invoke gss_delete_sec_context passing the value
2444
2380
GSS_C_NO_BUFFER for the output_token parameter, indicating that no
2445
2381
token is required, and that gss_delete_sec_context should simply
2451
2387
2452
2388
Return value:
2453
2389
2454
`GSS_S_COMPLETE': Successful completion.
2390
'GSS_S_COMPLETE': Successful completion.
2455
2391
2456
`GSS_S_NO_CONTEXT': No valid context was supplied.
2392
'GSS_S_NO_CONTEXT': No valid context was supplied.
2457
2393
2458
2394
gss_process_context_token
2459
2395
-------------------------
2487
2423
2488
2424
Return value:
2489
2425
2490
`GSS_S_COMPLETE': Successful completion.
2426
'GSS_S_COMPLETE': Successful completion.
2491
2427
2492
`GSS_S_DEFECTIVE_TOKEN': Indicates that consistency checks
2428
'GSS_S_DEFECTIVE_TOKEN': Indicates that consistency checks
2493
2429
performed on the token failed.
2494
2430
2495
`GSS_S_NO_CONTEXT': The context_handle did not refer to a valid
2431
'GSS_S_NO_CONTEXT': The context_handle did not refer to a valid
2496
2432
context.
2497
2433
2498
2434
gss_context_time
2506
2442
CONTEXT_HANDLE: (gss_ctx_id_t, read) Identifies the context to be
2507
2443
interrogated.
2508
2444
2509
TIME_REC: (Integer, modify) Number of seconds that the context
2510
will remain valid. If the context has already expired, zero will
2511
be returned.
2445
TIME_REC: (Integer, modify) Number of seconds that the context will
2446
remain valid. If the context has already expired, zero will be
2447
returned.
2512
2448
2513
2449
Determines the number of seconds for which the specified context
2514
2450
will remain valid.
2515
2451
2516
2452
Return value:
2517
2453
2518
`GSS_S_COMPLETE': Successful completion.
2519
2520
`GSS_S_CONTEXT_EXPIRED': The context has already expired.
2521
2522
`GSS_S_NO_CONTEXT': The context_handle parameter did not identify a
2454
'GSS_S_COMPLETE': Successful completion.
2455
2456
'GSS_S_CONTEXT_EXPIRED': The context has already expired.
2457
2458
'GSS_S_NO_CONTEXT': The context_handle parameter did not identify a
2523
2459
valid context
2524
2460
2525
2461
gss_inquire_context
2528
2464
-- Function: OM_uint32 gss_inquire_context (OM_uint32 * MINOR_STATUS,
2529
2465
const gss_ctx_id_t CONTEXT_HANDLE, gss_name_t * SRC_NAME,
2530
2466
gss_name_t * TARG_NAME, OM_uint32 * LIFETIME_REC, gss_OID *
2531
MECH_TYPE, OM_uint32 * CTX_FLAGS, int * LOCALLY_INITIATED,
2532
int * OPEN)
2467
MECH_TYPE, OM_uint32 * CTX_FLAGS, int * LOCALLY_INITIATED, int
2468
* OPEN)
2533
2469
MINOR_STATUS: (Integer, modify) Mechanism specific status code.
2534
2470
2535
2471
CONTEXT_HANDLE: (gss_ctx_id_t, read) A handle that refers to the
2537
2473
2538
2474
SRC_NAME: (gss_name_t, modify, optional) The name of the context
2539
2475
initiator. If the context was established using anonymous
2540
authentication, and if the application invoking
2541
gss_inquire_context is the context acceptor, an anonymous name
2542
will be returned. Storage associated with this name must be freed
2543
by the application after use with a call to gss_release_name().
2544
Specify NULL if not required.
2476
authentication, and if the application invoking gss_inquire_context
2477
is the context acceptor, an anonymous name will be returned.
2478
Storage associated with this name must be freed by the application
2479
after use with a call to gss_release_name(). Specify NULL if not
2480
required.
2545
2481
2546
2482
TARG_NAME: (gss_name_t, modify, optional) The name of the context
2547
2483
acceptor. Storage associated with this name must be freed by the
2551
2487
gss_init_sec_context(), the value GSS_C_NO_NAME will be returned.
2552
2488
Specify NULL if not required.
2553
2489
2554
LIFETIME_REC: (Integer, modify, optional) The number of seconds
2555
for which the context will remain valid. If the context has
2556
expired, this parameter will be set to zero. If the
2557
implementation does not support context expiration, the value
2558
GSS_C_INDEFINITE will be returned. Specify NULL if not required.
2490
LIFETIME_REC: (Integer, modify, optional) The number of seconds for
2491
which the context will remain valid. If the context has expired,
2492
this parameter will be set to zero. If the implementation does not
2493
support context expiration, the value GSS_C_INDEFINITE will be
2494
returned. Specify NULL if not required.
2559
2495
2560
2496
MECH_TYPE: (gss_OID, modify, optional) The security mechanism
2561
2497
providing the context. The returned OID will be a pointer to
2566
2502
CTX_FLAGS: (bit-mask, modify, optional) Contains various
2567
2503
independent flags, each of which indicates that the context
2568
2504
supports (or is expected to support, if ctx_open is false) a
2569
specific service option. If not needed, specify NULL. Symbolic
2505
specific service option. If not needed, specify NULL. Symbolic
2570
2506
names are provided for each flag, and the symbolic names
2571
2507
corresponding to the required flags should be logically-ANDed with
2572
2508
the ret_flags value to test whether a given option is supported by
2577
2513
required.
2578
2514
2579
2515
OPEN: (Boolean, modify) Non-zero if the context is fully
2580
established; Zero if a context-establishment token is expected
2581
from the peer application. Specify NULL if not required.
2516
established; Zero if a context-establishment token is expected from
2517
the peer application. Specify NULL if not required.
2582
2518
2583
2519
Obtains information about a security context. The caller must
2584
2520
already have obtained a handle that refers to the context, although
2585
2521
the context need not be fully established.
2586
2522
2587
The `ctx_flags' values:
2588
2589
2590
`GSS_C_DELEG_FLAG'
2523
The 'ctx_flags' values:
2524
2525
'GSS_C_DELEG_FLAG'
2591
2526
2592
2527
* True - Credentials were delegated from the initiator to
2593
2528
the acceptor.
2594
2529
2595
2530
* False - No credentials were delegated.
2596
2531
2597
2598
2599
`GSS_C_MUTUAL_FLAG'
2532
'GSS_C_MUTUAL_FLAG'
2600
2533
2601
2534
* True - The acceptor was authenticated to the initiator.
2602
2535
2603
2536
* False - The acceptor did not authenticate itself.
2604
2537
2605
2606
2607
`GSS_C_REPLAY_FLAG'
2538
'GSS_C_REPLAY_FLAG'
2608
2539
2609
2540
* True - replay of protected messages will be detected.
2610
2541
2611
2542
* False - replayed messages will not be detected.
2612
2543
2613
2614
2615
`GSS_C_SEQUENCE_FLAG'
2544
'GSS_C_SEQUENCE_FLAG'
2616
2545
2617
2546
* True - out-of-sequence protected messages will be
2618
2547
detected.
2619
2548
2620
2549
* False - out-of-sequence messages will not be detected.
2621
2550
2622
2623
2624
`GSS_C_CONF_FLAG'
2551
'GSS_C_CONF_FLAG'
2625
2552
2626
2553
* True - Confidentiality service may be invoked by calling
2627
2554
gss_wrap routine.
2628
2555
2629
2556
* False - No confidentiality service (via gss_wrap)
2630
available. gss_wrap will provide message encapsulation,
2557
available. gss_wrap will provide message encapsulation,
2631
2558
data-origin authentication and integrity services only.
2632
2559
2633
2634
2635
`GSS_C_INTEG_FLAG'
2560
'GSS_C_INTEG_FLAG'
2636
2561
2637
2562
* True - Integrity service may be invoked by calling either
2638
2563
gss_get_mic or gss_wrap routines.
2639
2564
2640
2565
* False - Per-message integrity service unavailable.
2641
2566
2642
2643
2644
`GSS_C_ANON_FLAG'
2567
'GSS_C_ANON_FLAG'
2645
2568
2646
2569
* True - The initiator's identity will not be revealed to
2647
2570
the acceptor. The src_name parameter (if requested)
2649
2572
2650
2573
* False - The initiator has been authenticated normally.
2651
2574
2652
2653
2654
`GSS_C_PROT_READY_FLAG'
2655
2656
* True - Protection services (as specified by the states
2657
of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are
2658
available for use.
2575
'GSS_C_PROT_READY_FLAG'
2576
2577
* True - Protection services (as specified by the states of
2578
the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available
2579
for use.
2659
2580
2660
2581
* False - Protection services (as specified by the states
2661
2582
of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are
2662
2583
available only if the context is fully established (i.e.
2663
2584
if the open parameter is non-zero).
2664
2585
2665
2666
2667
`GSS_C_TRANS_FLAG'
2586
'GSS_C_TRANS_FLAG'
2668
2587
2669
2588
* True - The resultant security context may be transferred
2670
2589
to other processes via a call to
2674
2593
2675
2594
Return value:
2676
2595
2677
`GSS_S_COMPLETE': Successful completion.
2596
'GSS_S_COMPLETE': Successful completion.
2678
2597
2679
`GSS_S_NO_CONTEXT': The referenced context could not be accessed.
2598
'GSS_S_NO_CONTEXT': The referenced context could not be accessed.
2680
2599
2681
2600
gss_wrap_size_limit
2682
2601
-------------------
2696
2615
details.
2697
2616
2698
2617
QOP_REQ: (gss_qop_t, read) Indicates the level of protection that
2699
gss_wrap will be asked to provide. See the routine description
2700
for gss_wrap for more details.
2618
gss_wrap will be asked to provide. See the routine description for
2619
gss_wrap for more details.
2701
2620
2702
2621
REQ_OUTPUT_SIZE: (Integer, read) The desired maximum size for
2703
2622
tokens emitted by gss_wrap.
2716
2635
application to fragment messages prior to applying protection.
2717
2636
2718
2637
GSS-API implementations are recommended but not required to detect
2719
invalid QOP values when gss_wrap_size_limit() is called. This
2638
invalid QOP values when gss_wrap_size_limit() is called. This
2720
2639
routine guarantees only a maximum message size, not the
2721
2640
availability of specific QOP values for message protection.
2722
2641
2731
2650
2732
2651
Return value:
2733
2652
2734
`GSS_S_COMPLETE': Successful completion.
2735
2736
`GSS_S_NO_CONTEXT': The referenced context could not be accessed.
2737
2738
`GSS_S_CONTEXT_EXPIRED': The context has expired.
2739
2740
`GSS_S_BAD_QOP': The specified QOP is not supported by the
2653
'GSS_S_COMPLETE': Successful completion.
2654
2655
'GSS_S_NO_CONTEXT': The referenced context could not be accessed.
2656
2657
'GSS_S_CONTEXT_EXPIRED': The context has expired.
2658
2659
'GSS_S_BAD_QOP': The specified QOP is not supported by the
2741
2660
mechanism.
2742
2661
2743
2662
gss_export_sec_context
2761
2680
application where a single process receives incoming connection
2762
2681
requests and accepts security contexts over them, then passes the
2763
2682
established context to one or more other processes for message
2764
exchange. gss_export_sec_context() deactivates the security context
2765
for the calling process and creates an interprocess token which,
2766
when passed to gss_import_sec_context in another process, will
2767
re-activate the context in the second process. Only a single
2683
exchange. gss_export_sec_context() deactivates the security
2684
context for the calling process and creates an interprocess token
2685
which, when passed to gss_import_sec_context in another process,
2686
will re-activate the context in the second process. Only a single
2768
2687
instantiation of a given context may be active at any one time; a
2769
2688
subsequent attempt by a context exporter to access the exported
2770
2689
security context will fail.
2781
2700
to either avoid placing such sensitive information within
2782
2701
interprocess tokens, or to encrypt the token before returning it to
2783
2702
the application, in a typical object-library GSS-API implementation
2784
this may not be possible. Thus the application must take care to
2703
this may not be possible. Thus the application must take care to
2785
2704
protect the interprocess token, and ensure that any process to
2786
2705
which the token is transferred is trustworthy.
2787
2706
2788
2707
If creation of the interprocess token is successful, the
2789
2708
implementation shall deallocate all process-wide resources
2790
2709
associated with the security context, and set the context_handle to
2791
GSS_C_NO_CONTEXT. In the event of an error that makes it
2792
impossible to complete the export of the security context, the
2793
implementation must not return an interprocess token, and should
2794
strive to leave the security context referenced by the
2795
context_handle parameter untouched. If this is impossible, it is
2796
permissible for the implementation to delete the security context,
2797
providing it also sets the context_handle parameter to
2798
GSS_C_NO_CONTEXT.
2710
GSS_C_NO_CONTEXT. In the event of an error that makes it impossible
2711
to complete the export of the security context, the implementation
2712
must not return an interprocess token, and should strive to leave
2713
the security context referenced by the context_handle parameter
2714
untouched. If this is impossible, it is permissible for the
2715
implementation to delete the security context, providing it also
2716
sets the context_handle parameter to GSS_C_NO_CONTEXT.
2799
2717
2800
2718
Return value:
2801
2719
2802
`GSS_S_COMPLETE': Successful completion.
2803
2804
`GSS_S_CONTEXT_EXPIRED': The context has expired.
2805
2806
`GSS_S_NO_CONTEXT': The context was invalid.
2807
2808
`GSS_S_UNAVAILABLE': The operation is not supported.
2720
'GSS_S_COMPLETE': Successful completion.
2721
2722
'GSS_S_CONTEXT_EXPIRED': The context has expired.
2723
2724
'GSS_S_NO_CONTEXT': The context was invalid.
2725
2726
'GSS_S_UNAVAILABLE': The operation is not supported.
2809
2727
2810
2728
gss_import_sec_context
2811
2729
----------------------
2819
2737
exporting process
2820
2738
2821
2739
CONTEXT_HANDLE: (gss_ctx_id_t, modify) Context handle of newly
2822
reactivated context. Resources associated with this context
2823
handle must be released by the application after use with a call
2824
to gss_delete_sec_context().
2740
reactivated context. Resources associated with this context handle
2741
must be released by the application after use with a call to
2742
gss_delete_sec_context().
2825
2743
2826
2744
Allows a process to import a security context established by
2827
2745
another process. A given interprocess token may be imported only
2829
2747
2830
2748
Return value:
2831
2749
2832
`GSS_S_COMPLETE': Successful completion.
2750
'GSS_S_COMPLETE': Successful completion.
2833
2751
2834
`GSS_S_NO_CONTEXT': The token did not contain a valid context
2752
'GSS_S_NO_CONTEXT': The token did not contain a valid context
2835
2753
reference.
2836
2754
2837
`GSS_S_DEFECTIVE_TOKEN': The token was invalid.
2838
2839
`GSS_S_UNAVAILABLE': The operation is unavailable.
2840
2841
`GSS_S_UNAUTHORIZED': Local policy prevents the import of this
2755
'GSS_S_DEFECTIVE_TOKEN': The token was invalid.
2756
2757
'GSS_S_UNAVAILABLE': The operation is unavailable.
2758
2759
'GSS_S_UNAUTHORIZED': Local policy prevents the import of this
2842
2760
context by the current process.
2843
2761
2844
2762
2876
2794
CONTEXT_HANDLE: (gss_ctx_id_t, read) Identifies the context on
2877
2795
which the message will be sent.
2878
2796
2879
QOP_REQ: (gss_qop_t, read, optional) Specifies requested quality
2880
of protection. Callers are encouraged, on portability grounds, to
2797
QOP_REQ: (gss_qop_t, read, optional) Specifies requested quality of
2798
protection. Callers are encouraged, on portability grounds, to
2881
2799
accept the default quality of protection offered by the chosen
2882
2800
mechanism, which may be requested by specifying GSS_C_QOP_DEFAULT
2883
2801
for this parameter. If an unsupported protection strength is
2890
2808
use with a call to gss_release_buffer().
2891
2809
2892
2810
Generates a cryptographic MIC for the supplied message, and places
2893
the MIC in a token for transfer to the peer application. The
2811
the MIC in a token for transfer to the peer application. The
2894
2812
qop_req parameter allows a choice between several cryptographic
2895
2813
algorithms, if supported by the chosen mechanism.
2896
2814
2900
2818
2901
2819
Return value:
2902
2820
2903
`GSS_S_COMPLETE': Successful completion.
2904
2905
`GSS_S_CONTEXT_EXPIRED': The context has already expired.
2906
2907
`GSS_S_NO_CONTEXT': The context_handle parameter did not identify a
2821
'GSS_S_COMPLETE': Successful completion.
2822
2823
'GSS_S_CONTEXT_EXPIRED': The context has already expired.
2824
2825
'GSS_S_NO_CONTEXT': The context_handle parameter did not identify a
2908
2826
valid context.
2909
2827
2910
`GSS_S_BAD_QOP': The specified QOP is not supported by the
2828
'GSS_S_BAD_QOP': The specified QOP is not supported by the
2911
2829
mechanism.
2912
2830
2913
2831
gss_verify_mic
2941
2859
2942
2860
Return value:
2943
2861
2944
`GSS_S_COMPLETE': Successful completion.
2945
2946
`GSS_S_DEFECTIVE_TOKEN': The token failed consistency checks.
2947
2948
`GSS_S_BAD_SIG': The MIC was incorrect.
2949
2950
`GSS_S_DUPLICATE_TOKEN': The token was valid, and contained a
2862
'GSS_S_COMPLETE': Successful completion.
2863
2864
'GSS_S_DEFECTIVE_TOKEN': The token failed consistency checks.
2865
2866
'GSS_S_BAD_SIG': The MIC was incorrect.
2867
2868
'GSS_S_DUPLICATE_TOKEN': The token was valid, and contained a
2951
2869
correct MIC for the message, but it had already been processed.
2952
2870
2953
`GSS_S_OLD_TOKEN': The token was valid, and contained a correct MIC
2871
'GSS_S_OLD_TOKEN': The token was valid, and contained a correct MIC
2954
2872
for the message, but it is too old to check for duplication.
2955
2873
2956
`GSS_S_UNSEQ_TOKEN': The token was valid, and contained a correct
2874
'GSS_S_UNSEQ_TOKEN': The token was valid, and contained a correct
2957
2875
MIC for the message, but has been verified out of sequence; a later
2958
2876
token has already been received.
2959
2877
2960
`GSS_S_GAP_TOKEN': The token was valid, and contained a correct MIC
2878
'GSS_S_GAP_TOKEN': The token was valid, and contained a correct MIC
2961
2879
for the message, but has been verified out of sequence; an earlier
2962
2880
expected token has not yet been received.
2963
2881
2964
`GSS_S_CONTEXT_EXPIRED': The context has already expired.
2882
'GSS_S_CONTEXT_EXPIRED': The context has already expired.
2965
2883
2966
`GSS_S_NO_CONTEXT': The context_handle parameter did not identify a
2884
'GSS_S_NO_CONTEXT': The context_handle parameter did not identify a
2967
2885
valid context.
2968
2886
2969
2887
gss_wrap
2979
2897
which the message will be sent.
2980
2898
2981
2899
CONF_REQ_FLAG: (boolean, read) Non-zero - Both confidentiality and
2982
integrity services are requested. Zero - Only integrity service is
2900
integrity services are requested. Zero - Only integrity service is
2983
2901
requested.
2984
2902
2985
2903
QOP_REQ: (gss_qop_t, read, optional) Specifies required quality of
2986
2904
protection. A mechanism-specific default may be requested by
2987
setting qop_req to GSS_C_QOP_DEFAULT. If an unsupported
2988
protection strength is requested, gss_wrap will return a
2989
major_status of GSS_S_BAD_QOP.
2905
setting qop_req to GSS_C_QOP_DEFAULT. If an unsupported protection
2906
strength is requested, gss_wrap will return a major_status of
2907
GSS_S_BAD_QOP.
2990
2908
2991
2909
INPUT_MESSAGE_BUFFER: (buffer, opaque, read) Message to be
2992
2910
protected.
2993
2911
2994
CONF_STATE: (boolean, modify, optional) Non-zero -
2995
Confidentiality, data origin authentication and integrity services
2996
have been applied. Zero - Integrity and data origin services only
2997
has been applied. Specify NULL if not required.
2912
CONF_STATE: (boolean, modify, optional) Non-zero - Confidentiality,
2913
data origin authentication and integrity services have been
2914
applied. Zero - Integrity and data origin services only has been
2915
applied. Specify NULL if not required.
2998
2916
2999
2917
OUTPUT_MESSAGE_BUFFER: (buffer, opaque, modify) Buffer to receive
3000
2918
protected message. Storage associated with this message must be
3012
2930
3013
2931
Return value:
3014
2932
3015
`GSS_S_COMPLETE': Successful completion.
3016
3017
`GSS_S_CONTEXT_EXPIRED': The context has already expired.
3018
3019
`GSS_S_NO_CONTEXT': The context_handle parameter did not identify a
2933
'GSS_S_COMPLETE': Successful completion.
2934
2935
'GSS_S_CONTEXT_EXPIRED': The context has already expired.
2936
2937
'GSS_S_NO_CONTEXT': The context_handle parameter did not identify a
3020
2938
valid context.
3021
2939
3022
`GSS_S_BAD_QOP': The specified QOP is not supported by the
2940
'GSS_S_BAD_QOP': The specified QOP is not supported by the
3023
2941
mechanism.
3024
2942
3025
2943
gss_unwrap
3042
2960
gss_release_buffer().
3043
2961
3044
2962
CONF_STATE: (boolean, modify, optional) Non-zero - Confidentiality
3045
and integrity protection were used. Zero - Integrity service only
2963
and integrity protection were used. Zero - Integrity service only
3046
2964
was used. Specify NULL if not required.
3047
2965
3048
2966
QOP_STATE: (gss_qop_t, modify, optional) Quality of protection
3049
2967
provided. Specify NULL if not required.
3050
2968
3051
2969
Converts a message previously protected by gss_wrap back to a
3052
usable form, verifying the embedded MIC. The conf_state parameter
2970
usable form, verifying the embedded MIC. The conf_state parameter
3053
2971
indicates whether the message was encrypted; the qop_state
3054
2972
parameter indicates the strength of protection that was used to
3055
2973
provide the confidentiality and integrity services.
3060
2978
3061
2979
Return value:
3062
2980
3063
`GSS_S_COMPLETE': Successful completion.
3064
3065
`GSS_S_DEFECTIVE_TOKEN': The token failed consistency checks.
3066
3067
`GSS_S_BAD_SIG': The MIC was incorrect.
3068
3069
`GSS_S_DUPLICATE_TOKEN': The token was valid, and contained a
2981
'GSS_S_COMPLETE': Successful completion.
2982
2983
'GSS_S_DEFECTIVE_TOKEN': The token failed consistency checks.
2984
2985
'GSS_S_BAD_SIG': The MIC was incorrect.
2986
2987
'GSS_S_DUPLICATE_TOKEN': The token was valid, and contained a
3070
2988
correct MIC for the message, but it had already been processed.
3071
2989
3072
`GSS_S_OLD_TOKEN': The token was valid, and contained a correct MIC
2990
'GSS_S_OLD_TOKEN': The token was valid, and contained a correct MIC
3073
2991
for the message, but it is too old to check for duplication.
3074
2992
3075
`GSS_S_UNSEQ_TOKEN': The token was valid, and contained a correct
2993
'GSS_S_UNSEQ_TOKEN': The token was valid, and contained a correct
3076
2994
MIC for the message, but has been verified out of sequence; a later
3077
2995
token has already been received.
3078
2996
3079
`GSS_S_GAP_TOKEN': The token was valid, and contained a correct MIC
2997
'GSS_S_GAP_TOKEN': The token was valid, and contained a correct MIC
3080
2998
for the message, but has been verified out of sequence; an earlier
3081
2999
expected token has not yet been received.
3082
3000
3083
`GSS_S_CONTEXT_EXPIRED': The context has already expired.
3001
'GSS_S_CONTEXT_EXPIRED': The context has already expired.
3084
3002
3085
`GSS_S_NO_CONTEXT': The context_handle parameter did not identify a
3003
'GSS_S_NO_CONTEXT': The context_handle parameter did not identify a
3086
3004
valid context.
3087
3005
3088
3006
3112
3030
gss_import_name
3113
3031
---------------
3114
3032
3115
-- Function: OM_uint32 gss_import_name (OM_uint32 * MINOR_STATUS,
3116
const gss_buffer_t INPUT_NAME_BUFFER, const gss_OID
3117
INPUT_NAME_TYPE, gss_name_t * OUTPUT_NAME)
3033
-- Function: OM_uint32 gss_import_name (OM_uint32 * MINOR_STATUS, const
3034
gss_buffer_t INPUT_NAME_BUFFER, const gss_OID INPUT_NAME_TYPE,
3035
gss_name_t * OUTPUT_NAME)
3118
3036
MINOR_STATUS: (Integer, modify) Mechanism specific status code.
3119
3037
3120
3038
INPUT_NAME_BUFFER: (buffer, octet-string, read) Buffer containing
3131
3049
after use with a call to gss_release_name().
3132
3050
3133
3051
Convert a contiguous string name to internal form. In general, the
3134
internal name returned (via the @output_name parameter) will not
3135
be an MN; the exception to this is if the @input_name_type
3136
indicates that the contiguous string provided via the
3137
@input_name_buffer parameter is of type GSS_C_NT_EXPORT_NAME, in
3138
which case the returned internal name will be an MN for the
3139
mechanism that exported the name.
3052
internal name returned (via the @output_name parameter) will not be
3053
an MN; the exception to this is if the @input_name_type indicates
3054
that the contiguous string provided via the @input_name_buffer
3055
parameter is of type GSS_C_NT_EXPORT_NAME, in which case the
3056
returned internal name will be an MN for the mechanism that
3057
exported the name.
3140
3058
3141
3059
Return value:
3142
3060
3143
`GSS_S_COMPLETE': Successful completion.
3144
3145
`GSS_S_BAD_NAMETYPE': The input_name_type was unrecognized.
3146
3147
`GSS_S_BAD_NAME': The input_name parameter could not be interpreted
3061
'GSS_S_COMPLETE': Successful completion.
3062
3063
'GSS_S_BAD_NAMETYPE': The input_name_type was unrecognized.
3064
3065
'GSS_S_BAD_NAME': The input_name parameter could not be interpreted
3148
3066
as a name of the specified type.
3149
3067
3150
`GSS_S_BAD_MECH': The input name-type was GSS_C_NT_EXPORT_NAME, but
3068
'GSS_S_BAD_MECH': The input name-type was GSS_C_NT_EXPORT_NAME, but
3151
3069
the mechanism contained within the input-name is not supported.
3152
3070
3153
3071
gss_display_name
3187
3105
3188
3106
Return value:
3189
3107
3190
`GSS_S_COMPLETE': Successful completion.
3108
'GSS_S_COMPLETE': Successful completion.
3191
3109
3192
`GSS_S_BAD_NAME': @input_name was ill-formed.
3110
'GSS_S_BAD_NAME': @input_name was ill-formed.
3193
3111
3194
3112
gss_compare_name
3195
3113
----------------
3204
3122
NAME2: (gss_name_t, read) Internal-form name.
3205
3123
3206
3124
NAME_EQUAL: (boolean, modify) Non-zero - names refer to same
3207
entity. Zero - names refer to different entities (strictly, the
3125
entity. Zero - names refer to different entities (strictly, the
3208
3126
names are not known to refer to the same identity).
3209
3127
3210
3128
Allows an application to compare two internal-form names to
3216
3134
3217
3135
Return value:
3218
3136
3219
`GSS_S_COMPLETE': Successful completion.
3220
3221
`GSS_S_BAD_NAMETYPE': The two names were of incomparable types.
3222
3223
`GSS_S_BAD_NAME': One or both of name1 or name2 was ill-formed.
3137
'GSS_S_COMPLETE': Successful completion.
3138
3139
'GSS_S_BAD_NAMETYPE': The two names were of incomparable types.
3140
3141
'GSS_S_BAD_NAME': One or both of name1 or name2 was ill-formed.
3224
3142
3225
3143
gss_release_name
3226
3144
----------------
3237
3155
3238
3156
Return value:
3239
3157
3240
`GSS_S_COMPLETE': Successful completion.
3158
'GSS_S_COMPLETE': Successful completion.
3241
3159
3242
`GSS_S_BAD_NAME': The name parameter did not contain a valid name.
3160
'GSS_S_BAD_NAME': The name parameter did not contain a valid name.
3243
3161
3244
3162
gss_inquire_names_for_mech
3245
3163
--------------------------
3252
3170
MECHANISM: (gss_OID, read) The mechanism to be interrogated.
3253
3171
3254
3172
NAME_TYPES: (gss_OID_set, modify) Set of name-types supported by
3255
the specified mechanism. The returned OID set must be freed by
3256
the application after use with a call to gss_release_oid_set().
3173
the specified mechanism. The returned OID set must be freed by the
3174
application after use with a call to gss_release_oid_set().
3257
3175
3258
3176
Returns the set of nametypes supported by the specified mechanism.
3259
3177
3260
3178
Return value:
3261
3179
3262
`GSS_S_COMPLETE': Successful completion.
3180
'GSS_S_COMPLETE': Successful completion.
3263
3181
3264
3182
gss_inquire_mechs_for_name
3265
3183
--------------------------
3294
3212
3295
3213
Return value:
3296
3214
3297
`GSS_S_COMPLETE': Successful completion.
3298
3299
`GSS_S_BAD_NAME': The input_name parameter was ill-formed.
3300
3301
`GSS_S_BAD_NAMETYPE': The input_name parameter contained an invalid
3215
'GSS_S_COMPLETE': Successful completion.
3216
3217
'GSS_S_BAD_NAME': The input_name parameter was ill-formed.
3218
3219
'GSS_S_BAD_NAMETYPE': The input_name parameter contained an invalid
3302
3220
or unsupported type of name.
3303
3221
3304
3222
gss_canonicalize_name
3305
3223
---------------------
3306
3224
3307
-- Function: OM_uint32 gss_canonicalize_name (OM_uint32 *
3308
MINOR_STATUS, const gss_name_t INPUT_NAME, const gss_OID
3309
MECH_TYPE, gss_name_t * OUTPUT_NAME)
3225
-- Function: OM_uint32 gss_canonicalize_name (OM_uint32 * MINOR_STATUS,
3226
const gss_name_t INPUT_NAME, const gss_OID MECH_TYPE,
3227
gss_name_t * OUTPUT_NAME)
3310
3228
MINOR_STATUS: (Integer, modify) Mechanism specific status code.
3311
3229
3312
3230
INPUT_NAME: (gss_name_t, read) The name for which a canonical form
3313
3231
is desired.
3314
3232
3315
MECH_TYPE: (Object ID, read) The authentication mechanism for
3316
which the canonical form of the name is desired. The desired
3317
mechanism must be specified explicitly; no default is provided.
3233
MECH_TYPE: (Object ID, read) The authentication mechanism for which
3234
the canonical form of the name is desired. The desired mechanism
3235
must be specified explicitly; no default is provided.
3318
3236
3319
3237
OUTPUT_NAME: (gss_name_t, modify) The resultant canonical name.
3320
3238
Storage associated with this name must be freed by the application
3330
3248
3331
3249
Return value:
3332
3250
3333
`GSS_S_COMPLETE': Successful completion.
3251
'GSS_S_COMPLETE': Successful completion.
3334
3252
3335
3253
gss_export_name
3336
3254
---------------
3337
3255
3338
-- Function: OM_uint32 gss_export_name (OM_uint32 * MINOR_STATUS,
3339
const gss_name_t INPUT_NAME, gss_buffer_t EXPORTED_NAME)
3256
-- Function: OM_uint32 gss_export_name (OM_uint32 * MINOR_STATUS, const
3257
gss_name_t INPUT_NAME, gss_buffer_t EXPORTED_NAME)
3340
3258
MINOR_STATUS: (Integer, modify) Mechanism specific status code.
3341
3259
3342
3260
INPUT_NAME: (gss_name_t, read) The MN to be exported.
3347
3265
gss_release_buffer().
3348
3266
3349
3267
To produce a canonical contiguous string representation of a
3350
mechanism name (MN), suitable for direct comparison (e.g. with
3351
memcmp) for use in authorization functions (e.g. matching entries
3268
mechanism name (MN), suitable for direct comparison (e.g. with
3269
memcmp) for use in authorization functions (e.g. matching entries
3352
3270
in an access-control list). The @input_name parameter must specify
3353
a valid MN (i.e. an internal name generated by
3271
a valid MN (i.e. an internal name generated by
3354
3272
gss_accept_sec_context() or by gss_canonicalize_name()).
3355
3273
3356
3274
Return value:
3357
3275
3358
`GSS_S_COMPLETE': Successful completion.
3276
'GSS_S_COMPLETE': Successful completion.
3359
3277
3360
`GSS_S_NAME_NOT_MN': The provided internal name was not a mechanism
3278
'GSS_S_NAME_NOT_MN': The provided internal name was not a mechanism
3361
3279
name.
3362
3280
3363
`GSS_S_BAD_NAME': The provided internal name was ill-formed.
3281
'GSS_S_BAD_NAME': The provided internal name was ill-formed.
3364
3282
3365
`GSS_S_BAD_NAMETYPE': The internal name was of a type not supported
3283
'GSS_S_BAD_NAMETYPE': The internal name was of a type not supported
3366
3284
by the GSS-API implementation.
3367
3285
3368
3286
gss_duplicate_name
3379
3297
after use with a call to gss_release_name().
3380
3298
3381
3299
Create an exact duplicate of the existing internal name @src_name.
3382
The new @dest_name will be independent of src_name (i.e. @src_name
3300
The new @dest_name will be independent of src_name (i.e. @src_name
3383
3301
and @dest_name must both be released, and the release of one shall
3384
3302
not affect the validity of the other).
3385
3303
3386
3304
Return value:
3387
3305
3388
`GSS_S_COMPLETE': Successful completion.
3306
'GSS_S_COMPLETE': Successful completion.
3389
3307
3390
`GSS_S_BAD_NAME': The src_name parameter was ill-formed.
3308
'GSS_S_BAD_NAME': The src_name parameter was ill-formed.
3391
3309
3392
3310
3393
3311
File: gss.info, Node: Miscellaneous Routines, Next: SASL GS2 Routines, Prev: Name Manipulation, Up: Standard GSS API
3433
3351
is intended for use in conjunction with gss_create_empty_oid_set
3434
3352
when constructing a set of mechanism OIDs for input to
3435
3353
gss_acquire_cred. The oid_set parameter must refer to an OID-set
3436
that was created by GSS-API (e.g. a set returned by
3437
gss_create_empty_oid_set()). GSS-API creates a copy of the
3354
that was created by GSS-API (e.g. a set returned by
3355
gss_create_empty_oid_set()). GSS-API creates a copy of the
3438
3356
member_oid and inserts this copy into the set, expanding the
3439
3357
storage allocated to the OID-set's elements array if necessary.
3440
3358
The routine may add the new member OID anywhere within the elements
3444
3362
3445
3363
Return value:
3446
3364
3447
`GSS_S_COMPLETE': Successful completion.
3365
'GSS_S_COMPLETE': Successful completion.
3448
3366
3449
3367
gss_display_status
3450
3368
------------------
3457
3375
3458
3376
STATUS_VALUE: (Integer, read) Status value to be converted.
3459
3377
3460
STATUS_TYPE: (Integer, read) GSS_C_GSS_CODE - status_value is a
3461
GSS status code. GSS_C_MECH_CODE - status_value is a mechanism
3462
status code.
3378
STATUS_TYPE: (Integer, read) GSS_C_GSS_CODE - status_value is a GSS
3379
status code. GSS_C_MECH_CODE - status_value is a mechanism status
3380
code.
3463
3381
3464
3382
MECH_TYPE: (Object ID, read, optional) Underlying mechanism (used
3465
to interpret a minor status value). Supply GSS_C_NO_OID to obtain
3383
to interpret a minor status value). Supply GSS_C_NO_OID to obtain
3466
3384
the system default.
3467
3385
3468
3386
MESSAGE_CONTEXT: (Integer, read/modify) Should be initialized to
3475
3393
3476
3394
STATUS_STRING: (buffer, character string, modify) Textual
3477
3395
interpretation of the status_value. Storage associated with this
3478
parameter must be freed by the application after use with a call
3479
to gss_release_buffer().
3396
parameter must be freed by the application after use with a call to
3397
gss_release_buffer().
3480
3398
3481
3399
Allows an application to obtain a textual representation of a
3482
3400
GSS-API status code, for display to the user or for logging
3528
3446
} while (message_context != 0);
3529
3447
Return value:
3530
3448
3531
`GSS_S_COMPLETE': Successful completion.
3449
'GSS_S_COMPLETE': Successful completion.
3532
3450
3533
`GSS_S_BAD_MECH': Indicates that translation in accordance with an
3451
'GSS_S_BAD_MECH': Indicates that translation in accordance with an
3534
3452
unsupported mechanism type was requested.
3535
3453
3536
`GSS_S_BAD_STATUS': The status value was not recognized, or the
3454
'GSS_S_BAD_STATUS': The status value was not recognized, or the
3537
3455
status type was neither GSS_C_GSS_CODE nor GSS_C_MECH_CODE.
3538
3456
3539
3457
gss_indicate_mechs
3554
3472
3555
3473
Return value:
3556
3474
3557
`GSS_S_COMPLETE': Successful completion.
3475
'GSS_S_COMPLETE': Successful completion.
3558
3476
3559
3477
gss_release_buffer
3560
3478
------------------
3564
3482
MINOR_STATUS: (integer, modify) Mechanism specific status code.
3565
3483
3566
3484
BUFFER: (buffer, modify) The storage associated with the buffer
3567
will be deleted. The gss_buffer_desc object will not be freed,
3568
but its length field will be zeroed.
3485
will be deleted. The gss_buffer_desc object will not be freed, but
3486
its length field will be zeroed.
3569
3487
3570
3488
Free storage associated with a buffer. The storage must have been
3571
3489
allocated by a GSS-API routine. In addition to freeing the
3572
3490
associated storage, the routine will zero the length field in the
3573
3491
descriptor to which the buffer parameter refers, and
3574
3492
implementations are encouraged to additionally set the pointer
3575
field in the descriptor to NULL. Any buffer object returned by a
3493
field in the descriptor to NULL. Any buffer object returned by a
3576
3494
GSS-API routine may be passed to gss_release_buffer (even if there
3577
3495
is no storage associated with the buffer).
3578
3496
3579
3497
Return value:
3580
3498
3581
`GSS_S_COMPLETE': Successful completion.
3499
'GSS_S_COMPLETE': Successful completion.
3582
3500
3583
3501
gss_release_oid_set
3584
3502
-------------------
3601
3519
3602
3520
Return value:
3603
3521
3604
`GSS_S_COMPLETE': Successful completion.
3522
'GSS_S_COMPLETE': Successful completion.
3605
3523
3606
3524
gss_create_empty_oid_set
3607
3525
------------------------
3623
3541
3624
3542
Return value:
3625
3543
3626
`GSS_S_COMPLETE': Successful completion.
3544
'GSS_S_COMPLETE': Successful completion.
3627
3545
3628
3546
gss_test_oid_set_member
3629
3547
-----------------------
3630
3548
3631
3549
-- Function: OM_uint32 gss_test_oid_set_member (OM_uint32 *
3632
MINOR_STATUS, const gss_OID MEMBER, const gss_OID_set SET,
3633
int * PRESENT)
3550
MINOR_STATUS, const gss_OID MEMBER, const gss_OID_set SET, int
3551
* PRESENT)
3634
3552
MINOR_STATUS: (integer, modify) Mechanism specific status code.
3635
3553
3636
3554
MEMBER: (Object ID, read) The object identifier whose presence is
3649
3567
3650
3568
Return value:
3651
3569
3652
`GSS_S_COMPLETE': Successful completion.
3570
'GSS_S_COMPLETE': Successful completion.
3653
3571
3654
3572
gss_encapsulate_token
3655
3573
---------------------
3656
3574
3657
-- Function: extern OM_uint32 gss_encapsulate_token
3658
(gss_const_buffer_t INPUT_TOKEN, gss_const_OID TOKEN_OID,
3659
gss_buffer_t OUTPUT_TOKEN)
3575
-- Function: extern OM_uint32 gss_encapsulate_token (gss_const_buffer_t
3576
INPUT_TOKEN, gss_const_OID TOKEN_OID, gss_buffer_t
3577
OUTPUT_TOKEN)
3660
3578
INPUT_TOKEN: (buffer, opaque, read) Buffer with GSS-API context
3661
3579
token data.
3662
3580
3674
3592
3675
3593
Returns:
3676
3594
3677
`GSS_S_COMPLETE': Indicates successful completion, and that output
3595
'GSS_S_COMPLETE': Indicates successful completion, and that output
3678
3596
parameters holds correct information.
3679
3597
3680
`GSS_S_FAILURE': Indicates that encapsulation failed for reasons
3598
'GSS_S_FAILURE': Indicates that encapsulation failed for reasons
3681
3599
unspecified at the GSS-API level.
3682
3600
3683
3601
gss_decapsulate_token
3702
3620
3703
3621
Return value:
3704
3622
3705
`GSS_S_COMPLETE': Indicates successful completion, and that output
3623
'GSS_S_COMPLETE': Indicates successful completion, and that output
3706
3624
parameters holds correct information.
3707
3625
3708
`GSS_S_DEFECTIVE_TOKEN': Means that the token failed consistency
3626
'GSS_S_DEFECTIVE_TOKEN': Means that the token failed consistency
3709
3627
checks (e.g., OID mismatch or ASN.1 DER length errors).
3710
3628
3711
`GSS_S_FAILURE': Indicates that decapsulation failed for reasons
3629
'GSS_S_FAILURE': Indicates that decapsulation failed for reasons
3712
3630
unspecified at the GSS-API level.
3713
3631
3714
3632
gss_oid_equal
3754
3672
3755
3673
Returns:
3756
3674
3757
`GSS_S_COMPLETE': Successful completion.
3675
'GSS_S_COMPLETE': Successful completion.
3758
3676
3759
`GSS_S_BAD_MECH': There is no GSS-API mechanism known as
3677
'GSS_S_BAD_MECH': There is no GSS-API mechanism known as
3760
3678
@sasl_mech_name.
3761
3679
3762
3680
gss_inquire_saslname_for_mech
3771
3689
DESIRED_MECH: (OID, read) Identifies the GSS-API mechanism to
3772
3690
query.
3773
3691
3774
SASL_MECH_NAME: (buffer, character-string, modify, optional)
3775
Buffer to receive SASL mechanism name. The application must free
3776
storage associated with this name after use with a call to
3692
SASL_MECH_NAME: (buffer, character-string, modify, optional) Buffer
3693
to receive SASL mechanism name. The application must free storage
3694
associated with this name after use with a call to
3777
3695
gss_release_buffer().
3778
3696
3779
3697
MECH_NAME: (buffer, character-string, modify, optional) Buffer to
3792
3710
3793
3711
Returns:
3794
3712
3795
`GSS_S_COMPLETE': Successful completion.
3713
'GSS_S_COMPLETE': Successful completion.
3796
3714
3797
`GSS_S_BAD_MECH': The @desired_mech OID is unsupported.
3715
'GSS_S_BAD_MECH': The @desired_mech OID is unsupported.
3798
3716
3799
3717
3800
3718
File: gss.info, Node: Extended GSS API, Next: Invoking gss, Prev: Standard GSS API, Up: Top
3803
3721
******************
3804
3722
3805
3723
None of the following functions are standard GSS API functions. As
3806
such, they are not declared in `gss/api.h', but rather in `gss/ext.h'
3807
(which is included from `gss.h'). *Note Header::.
3724
such, they are not declared in 'gss/api.h', but rather in 'gss/ext.h'
3725
(which is included from 'gss.h'). *Note Header::.
3808
3726
3809
3727
gss_check_version
3810
3728
-----------------
3816
3734
as a string in @req_version.
3817
3735
3818
3736
Return value: The actual version string of the library; NULL if the
3819
condition is not met. If NULL is passed to this function no
3820
check is done and only the version string is returned.
3737
condition is not met. If NULL is passed to this function no check
3738
is done and only the version string is returned.
3821
3739
3822
3740
gss_userok
3823
3741
----------
3829
3747
USERNAME: Zero terminated string with username.
3830
3748
3831
3749
Compare the username against the output from gss_export_name()
3832
invoked on @name, after removing the leading OID. This answers the
3750
invoked on @name, after removing the leading OID. This answers the
3833
3751
question whether the particular mechanism would authenticate them
3834
3752
as the same principal
3835
3753
3849
3767
Description
3850
3768
***********
3851
3769
3852
`gss' is the main program of GNU GSS.
3770
'gss' is the main program of GNU GSS.
3853
3771
3854
3772
Mandatory or optional arguments to long options are also mandatory or
3855
3773
optional for any corresponding short options.
3857
3775
Commands
3858
3776
********
3859
3777
3860
`gss' recognizes these commands:
3778
'gss' recognizes these commands:
3861
3779
3862
3780
-l, --list-mechanisms
3863
3781
List information about supported mechanisms
3864
3782
in a human readable format.
3865
3866
3783
-m, --major=LONG Describe a `major status' error code value.
3784
-a, --accept-sec-context
3785
Accept a security context as server.
3786
-i, --init-sec-context=MECH
3787
Initialize a security context as client.
3788
MECH is the SASL name of mechanism, use -l
3789
to list supported mechanisms.
3790
-n, --server-name=SERVICE@HOSTNAME
3791
For -i, set the name of the remote host.
3792
For example, "imap@mail.example.com".
3867
3793
3868
3794
Other Options
3869
3795
*************
3877
3803
Examples
3878
3804
********
3879
3805
3880
-h, --help Print help and exit
3881
-V, --version Print version and exit
3882
-q, --quiet Silent operation (default=off)
3806
To list the supported mechanisms, use 'gss -l' like this:
3807
3808
$ src/gss -l
3809
Found 1 supported mechanisms.
3810
3811
Mechanism 0:
3812
Mechanism name: Kerberos V5
3813
Mechanism description: Kerberos V5 GSS-API mechanism
3814
SASL Mechanism name: GS2-KRB5
3815
$
3816
3817
To initialize a Kerberos V5 security context, use the
3818
'--init-sec-context' parameter. Kerberos V5 needs to know the name of
3819
the remote entity, so you need to supply the '--server-name' parameter
3820
as well. That will provide the name of the server. For example, use
3821
'imap@mail.example.com' to setup a security context with the 'imap'
3822
service on the host 'mail.example.com'. The Kerberos V5 client will use
3823
your ticket-granting ticket (which needs to be available) and acquire a
3824
server ticket for the service. The KDC must know about the server for
3825
this to work. The tool will print the GSS-API context tokens base64
3826
encoded on standard output.
3827
3828
$ gss -i GS2-KRB5 -n host@interop.josefsson.org
3829
Context token (protection is available):
3830
YIICIQYJKoZIhvcSAQICAQBuggIQMIICDKADAgEFoQMCAQ6iBwMFACAAAACjggEYYYIBFDCCARCgAwIBBaEXGxVpbnRlcm9wLmpvc2Vmc3Nvbi5vcmeiKDAmoAMCAQGhHzAdGwRob3N0GxVpbnRlcm9wLmpvc2Vmc3Nvbi5vcmejgcUwgcKgAwIBEqKBugSBt0zqTh6tBBKV2BwDjQg6H4abEaPshPa0o3tT/TH9U7BaSw/M9ugYYqpHAhOitVjcQidhG2FdSl1n3FOgDBufHHO+gHOW0Y1XHc2QtEdkg1xYF2J4iR1vNQB14kXDM78pogCsfvfLnjsEESKWoeKRGOYWPRx0ksLJDnl/e5tXecZTjhJ3hLrFNBEWRmpIOakTAPnL+Xzz6xcnLHMLLnhZ5VcHqtIMm5p9IDWsP0juIncJ6tO8hjMA2qSB2jCB16ADAgESooHPBIHMWSeRBgV80gh/6hNNMr00jTVwCs5TEAIkljvjOfyPmNBzIFWoG+Wj5ZKOBdizdi7vYbJ2s8b1iSsq/9YEZSqaTxul+5aNrclKoJ7J/IW4kTuMklHcQf/A16TeZFsm9TdfE+x8+PjbOBFtKYXT8ODT8LLicNNiDbWW0meY7lsktXAVpZiUds4wTZ1W5bOSEGY7+mxAWrAlTnNwNAt1J2MHZnfGJFJDLJZldXoyG8OwHyp4h1nBhgzC5BfAmL85QJVxxgVfiHhM5oT9mE1O
3831
Input context token:
3832
3833
3834
The tool is waiting for the final Kerberos V5 context token from the
3835
server. Note the status text informing you that message protection is
3836
available.
3837
3838
To accept a Kerberos V5 context, the process is similar. The server
3839
needs to know its name, so that it can find the host key from
3840
(typically) '/etc/shishi/shishi.keys'. Once started it will wait for a
3841
context token from the client. Below we'll paste in the token printed
3842
above.
3843
3844
$ gss -a -n host@interop.josefsson.org
3845
Importing name "host@interop.josefsson.org"...
3846
Acquiring credentials...
3847
Input context token:
3848
YIICIQYJKoZIhvcSAQICAQBuggIQMIICDKADAgEFoQMCAQ6iBwMFACAAAACjggEYYYIBFDCCARCgAwIBBaEXGxVpbnRlcm9wLmpvc2Vmc3Nvbi5vcmeiKDAmoAMCAQGhHzAdGwRob3N0GxVpbnRlcm9wLmpvc2Vmc3Nvbi5vcmejgcUwgcKgAwIBEqKBugSBt0zqTh6tBBKV2BwDjQg6H4abEaPshPa0o3tT/TH9U7BaSw/M9ugYYqpHAhOitVjcQidhG2FdSl1n3FOgDBufHHO+gHOW0Y1XHc2QtEdkg1xYF2J4iR1vNQB14kXDM78pogCsfvfLnjsEESKWoeKRGOYWPRx0ksLJDnl/e5tXecZTjhJ3hLrFNBEWRmpIOakTAPnL+Xzz6xcnLHMLLnhZ5VcHqtIMm5p9IDWsP0juIncJ6tO8hjMA2qSB2jCB16ADAgESooHPBIHMWSeRBgV80gh/6hNNMr00jTVwCs5TEAIkljvjOfyPmNBzIFWoG+Wj5ZKOBdizdi7vYbJ2s8b1iSsq/9YEZSqaTxul+5aNrclKoJ7J/IW4kTuMklHcQf/A16TeZFsm9TdfE+x8+PjbOBFtKYXT8ODT8LLicNNiDbWW0meY7lsktXAVpZiUds4wTZ1W5bOSEGY7+mxAWrAlTnNwNAt1J2MHZnfGJFJDLJZldXoyG8OwHyp4h1nBhgzC5BfAmL85QJVxxgVfiHhM5oT9mE1O
3849
Context has been accepted. Final context token:
3850
YHEGCSqGSIb3EgECAgIAb2IwYKADAgEFoQMCAQ+iVDBSoAMCARKhAwIBAKJGBESy1Zoy9DrG+DuV/6aWmAp79s9d+ofGXC/WKOzRuxAqo98vMRWbsbILW8z9aF1th4GZz0kjFz/hZAmnWyomZ9JiP3yQvg==
3851
$
3852
3853
Returning to the client, you may now cut'n'paste the final context
3854
token as shown by the server. The client has then authenticated the
3855
server as well. The output from the client is shown below.
3856
3857
YHEGCSqGSIb3EgECAgIAb2IwYKADAgEFoQMCAQ+iVDBSoAMCARKhAwIBAKJGBESy1Zoy9DrG+DuV/6aWmAp79s9d+ofGXC/WKOzRuxAqo98vMRWbsbILW8z9aF1th4GZz0kjFz/hZAmnWyomZ9JiP3yQvg==
3858
Context has been initialized.
3859
$
3883
3860
3884
3861
3885
3862
File: gss.info, Node: Acknowledgements, Next: Criticism of GSS, Prev: Invoking gss, Up: Top
3896
3873
Appendix A Criticism of GSS
3897
3874
***************************
3898
3875
3899
The author has doubts whether GSS is the best solution for free
3900
software projects looking for a implementation agnostic security
3901
framework. We express these doubts in this section, so that the reader
3902
can judge for herself if any of the potential problems discussed here
3903
are relevant for their project, or if the benefit outweigh the
3904
problems. We are aware that some of the opinions are highly
3905
subjective, but we offer them in the hope they can serve as anecdotal
3906
evidence.
3876
The author has doubts whether GSS is the best solution for free software
3877
projects looking for a implementation agnostic security framework. We
3878
express these doubts in this section, so that the reader can judge for
3879
herself if any of the potential problems discussed here are relevant for
3880
their project, or if the benefit outweigh the problems. We are aware
3881
that some of the opinions are highly subjective, but we offer them in
3882
the hope they can serve as anecdotal evidence.
3907
3883
3908
3884
GSS can be criticized on several levels. We start with the actual
3909
3885
implementation.
3914
3890
evidence of this is the major_status and minor_status error code
3915
3891
solution. It is a complicated way to describe error conditions, but
3916
3892
what makes matters worse, the error condition is separated; half of the
3917
error condition is in the function return value and the other half is
3918
in the first argument to the function, which is always a pointer to an
3919
integer. (The pointer is not even allowed to be `NULL', if the
3893
error condition is in the function return value and the other half is in
3894
the first argument to the function, which is always a pointer to an
3895
integer. (The pointer is not even allowed to be 'NULL', if the
3920
3896
application doesn't care about the minor error code.) This makes the
3921
3897
API unreadable, and difficult to use. A better solutions would be to
3922
3898
return a struct containing the entire error condition, which can be
3923
3899
accessed using macros, although we acknowledge that the C language used
3924
at the time GSS was designed may not have allowed this (this may in
3925
fact be the reason the awkward solution was chosen). Instead, the
3926
return value could have been passed back to callers using a pointer to
3927
a struct, accessible using various macros, and the function could have
3928
a void prototype. The fact that minor_status is placed first in the
3929
parameter list increases the pain it is to use the API. Important
3930
parameters should be placed first. A better place for minor_status (if
3900
at the time GSS was designed may not have allowed this (this may in fact
3901
be the reason the awkward solution was chosen). Instead, the return
3902
value could have been passed back to callers using a pointer to a
3903
struct, accessible using various macros, and the function could have a
3904
void prototype. The fact that minor_status is placed first in the
3905
parameter list increases the pain it is to use the API. Important
3906
parameters should be placed first. A better place for minor_status (if
3931
3907
it must be present at all) would have been last in the prototypes.
3932
3908
3933
3909
Another evidence of the C inexperience are the memory management
3934
3910
issues; GSS provides functions to deallocate data stored within, e.g.,
3935
`gss_buffer_t' but the caller is responsible of deallocating the
3936
structure pointed at by the `gss_buffer_t' (i.e., the
3937
`gss_buffer_desc') itself. Memory management issues are error prone,
3938
and this division easily leads to memory leaks (or worse). Instead,
3939
the API should be the sole owner of all `gss_ctx_id_t',
3940
`gss_cred_id_t', and `gss_buffer_t' structures: they should be
3941
allocated by the library, and deallocated (using the utility functions
3942
defined for this purpose) by the library.
3911
'gss_buffer_t' but the caller is responsible of deallocating the
3912
structure pointed at by the 'gss_buffer_t' (i.e., the 'gss_buffer_desc')
3913
itself. Memory management issues are error prone, and this division
3914
easily leads to memory leaks (or worse). Instead, the API should be the
3915
sole owner of all 'gss_ctx_id_t', 'gss_cred_id_t', and 'gss_buffer_t'
3916
structures: they should be allocated by the library, and deallocated
3917
(using the utility functions defined for this purpose) by the library.
3943
3918
3944
3919
TBA: specification is unclear how memory for OIDs are managed. For
3945
3920
example, who is responsible for deallocate potentially newly allocated
3946
OIDs returned as `actual_mechs' in `gss_acquire_cred'? Further, are
3921
OIDs returned as 'actual_mechs' in 'gss_acquire_cred'? Further, are
3947
3922
OIDs deeply copied into OID sets? In other words, if I add an OID into
3948
3923
an OID set, and modify the original OID, will the OID in the OID set be
3949
3924
modified too?
3959
3934
#error Incompatible definition of OM_uint32 from xom.h
3960
3935
#endif
3961
3936
3962
The C pre-processor does not know about the `sizeof' function, so it
3963
is treated as an identifier, which maps to 0. Thus, the expression
3964
does not check that the size of `OM_uint32' is correct. It checks
3965
whether the expression `0 != 0' holds.
3937
The C pre-processor does not know about the 'sizeof' function, so it
3938
is treated as an identifier, which maps to 0. Thus, the expression does
3939
not check that the size of 'OM_uint32' is correct. It checks whether
3940
the expression '0 != 0' holds.
3966
3941
3967
3942
TBA: thread issues
3968
3943
3990
3965
Especially if the servers contacted is decided by the, yet
3991
3966
unauthenticated, remote client.
3992
3967
3993
TBA: krb5: no support for GSS_C_PROT_READY_FLAG. We support it
3968
TBA: krb5: no support for GSS_C_PROT_READY_FLAG. We support it
3994
3969
anyway, though.
3995
3970
3996
3971
TBA: krb5: gssapi-cfx differ from rfc 1964 in the reply token in that
4006
3981
solution).
4007
3982
4008
3983
Our conclusion is that free software projects that are looking for a
4009
security framework should evaluate carefully whether GSS actually is
4010
the best solution before using it. In particular it is recommended to
3984
security framework should evaluate carefully whether GSS actually is the
3985
best solution before using it. In particular it is recommended to
4011
3986
compare GSS with the Simple Authentication and Security Layer (SASL)
4012
3987
framework, which in several situations provide the same feature as GSS
4013
does. The most compelling argument for SASL over GSS is, as its
4014
acronym suggest, Simple, whereas GSS is far from it.
3988
does. The most compelling argument for SASL over GSS is, as its acronym
3989
suggest, Simple, whereas GSS is far from it.
4015
3990
4016
3991
However, that said, for free software projects that wants to support
4017
3992
Kerberos 5, we do acknowledge that no other framework provides a more
4028
4003
* Menu:
4029
4004
4030
4005
* GNU Free Documentation License:: License for copying this manual.
4031
* GNU GPL:: License for copying the programs.
4032
4006
4033
4007
4034
File: gss.info, Node: GNU Free Documentation License, Next: GNU GPL, Up: Copying Information
4008
File: gss.info, Node: GNU Free Documentation License, Up: Copying Information
4035
4009
4036
4010
B.1 GNU Free Documentation License
4037
4011
==================================
4039
4013
Version 1.3, 3 November 2008
4040
4014
4041
4015
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
4042
`http://fsf.org/'
4016
<http://fsf.org/>
4043
4017
4044
4018
Everyone is permitted to copy and distribute verbatim copies
4045
4019
of this license document, but changing it is not allowed.
4064
4038
free program should come with manuals providing the same freedoms
4065
4039
that the software does. But this License is not limited to
4066
4040
software manuals; it can be used for any textual work, regardless
4067
of subject matter or whether it is published as a printed book.
4068
We recommend this License principally for works whose purpose is
4041
of subject matter or whether it is published as a printed book. We
4042
recommend this License principally for works whose purpose is
4069
4043
instruction or reference.
4070
4044
4071
4045
1. APPLICABILITY AND DEFINITIONS
4072
4046
4073
4047
This License applies to any manual or other work, in any medium,
4074
that contains a notice placed by the copyright holder saying it
4075
can be distributed under the terms of this License. Such a notice
4048
that contains a notice placed by the copyright holder saying it can
4049
be distributed under the terms of this License. Such a notice
4076
4050
grants a world-wide, royalty-free license, unlimited in duration,
4077
4051
to use that work under the conditions stated herein. The
4078
4052
"Document", below, refers to any such manual or work. Any member
4079
of the public is a licensee, and is addressed as "you". You
4080
accept the license if you copy, modify or distribute the work in a
4081
way requiring permission under copyright law.
4053
of the public is a licensee, and is addressed as "you". You accept
4054
the license if you copy, modify or distribute the work in a way
4055
requiring permission under copyright law.
4082
4056
4083
4057
A "Modified Version" of the Document means any work containing the
4084
4058
Document or a portion of it, either copied verbatim, or with
4096
4070
regarding them.
4097
4071
4098
4072
The "Invariant Sections" are certain Secondary Sections whose
4099
titles are designated, as being those of Invariant Sections, in
4100
the notice that says that the Document is released under this
4101
License. If a section does not fit the above definition of
4102
Secondary then it is not allowed to be designated as Invariant.
4103
The Document may contain zero Invariant Sections. If the Document
4104
does not identify any Invariant Sections then there are none.
4073
titles are designated, as being those of Invariant Sections, in the
4074
notice that says that the Document is released under this License.
4075
If a section does not fit the above definition of Secondary then it
4076
is not allowed to be designated as Invariant. The Document may
4077
contain zero Invariant Sections. If the Document does not identify
4078
any Invariant Sections then there are none.
4105
4079
4106
4080
The "Cover Texts" are certain short passages of text that are
4107
4081
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
4112
4086
A "Transparent" copy of the Document means a machine-readable copy,
4113
4087
represented in a format whose specification is available to the
4114
4088
general public, that is suitable for revising the document
4115
straightforwardly with generic text editors or (for images
4116
composed of pixels) generic paint programs or (for drawings) some
4117
widely available drawing editor, and that is suitable for input to
4118
text formatters or for automatic translation to a variety of
4119
formats suitable for input to text formatters. A copy made in an
4120
otherwise Transparent file format whose markup, or absence of
4121
markup, has been arranged to thwart or discourage subsequent
4122
modification by readers is not Transparent. An image format is
4123
not Transparent if used for any substantial amount of text. A
4124
copy that is not "Transparent" is called "Opaque".
4089
straightforwardly with generic text editors or (for images composed
4090
of pixels) generic paint programs or (for drawings) some widely
4091
available drawing editor, and that is suitable for input to text
4092
formatters or for automatic translation to a variety of formats
4093
suitable for input to text formatters. A copy made in an otherwise
4094
Transparent file format whose markup, or absence of markup, has
4095
been arranged to thwart or discourage subsequent modification by
4096
readers is not Transparent. An image format is not Transparent if
4097
used for any substantial amount of text. A copy that is not
4098
"Transparent" is called "Opaque".
4125
4099
4126
4100
Examples of suitable formats for Transparent copies include plain
4127
4101
ASCII without markup, Texinfo input format, LaTeX input format,
4128
SGML or XML using a publicly available DTD, and
4129
standard-conforming simple HTML, PostScript or PDF designed for
4130
human modification. Examples of transparent image formats include
4131
PNG, XCF and JPG. Opaque formats include proprietary formats that
4132
can be read and edited only by proprietary word processors, SGML or
4133
XML for which the DTD and/or processing tools are not generally
4134
available, and the machine-generated HTML, PostScript or PDF
4135
produced by some word processors for output purposes only.
4102
SGML or XML using a publicly available DTD, and standard-conforming
4103
simple HTML, PostScript or PDF designed for human modification.
4104
Examples of transparent image formats include PNG, XCF and JPG.
4105
Opaque formats include proprietary formats that can be read and
4106
edited only by proprietary word processors, SGML or XML for which
4107
the DTD and/or processing tools are not generally available, and
4108
the machine-generated HTML, PostScript or PDF produced by some word
4109
processors for output purposes only.
4136
4110
4137
4111
The "Title Page" means, for a printed book, the title page itself,
4138
4112
plus such following pages as are needed to hold, legibly, the
4170
4144
may not use technical measures to obstruct or control the reading
4171
4145
or further copying of the copies you make or distribute. However,
4172
4146
you may accept compensation in exchange for copies. If you
4173
distribute a large enough number of copies you must also follow
4174
the conditions in section 3.
4147
distribute a large enough number of copies you must also follow the
4148
conditions in section 3.
4175
4149
4176
4150
You may also lend copies, under the same conditions stated above,
4177
4151
and you may publicly display copies.
4185
4159
these Cover Texts: Front-Cover Texts on the front cover, and
4186
4160
Back-Cover Texts on the back cover. Both covers must also clearly
4187
4161
and legibly identify you as the publisher of these copies. The
4188
front cover must present the full title with all words of the
4189
title equally prominent and visible. You may add other material
4190
on the covers in addition. Copying with changes limited to the
4191
covers, as long as they preserve the title of the Document and
4192
satisfy these conditions, can be treated as verbatim copying in
4193
other respects.
4162
front cover must present the full title with all words of the title
4163
equally prominent and visible. You may add other material on the
4164
covers in addition. Copying with changes limited to the covers, as
4165
long as they preserve the title of the Document and satisfy these
4166
conditions, can be treated as verbatim copying in other respects.
4194
4167
4195
4168
If the required texts for either cover are too voluminous to fit
4196
4169
legibly, you should put the first ones listed (as many as fit
4198
4171
adjacent pages.
4199
4172
4200
4173
If you publish or distribute Opaque copies of the Document
4201
numbering more than 100, you must either include a
4202
machine-readable Transparent copy along with each Opaque copy, or
4203
state in or with each Opaque copy a computer-network location from
4204
which the general network-using public has access to download
4205
using public-standard network protocols a complete Transparent
4206
copy of the Document, free of added material. If you use the
4207
latter option, you must take reasonably prudent steps, when you
4208
begin distribution of Opaque copies in quantity, to ensure that
4209
this Transparent copy will remain thus accessible at the stated
4210
location until at least one year after the last time you
4211
distribute an Opaque copy (directly or through your agents or
4212
retailers) of that edition to the public.
4174
numbering more than 100, you must either include a machine-readable
4175
Transparent copy along with each Opaque copy, or state in or with
4176
each Opaque copy a computer-network location from which the general
4177
network-using public has access to download using public-standard
4178
network protocols a complete Transparent copy of the Document, free
4179
of added material. If you use the latter option, you must take
4180
reasonably prudent steps, when you begin distribution of Opaque
4181
copies in quantity, to ensure that this Transparent copy will
4182
remain thus accessible at the stated location until at least one
4183
year after the last time you distribute an Opaque copy (directly or
4184
through your agents or retailers) of that edition to the public.
4213
4185
4214
4186
It is requested, but not required, that you contact the authors of
4215
the Document well before redistributing any large number of
4216
copies, to give them a chance to provide you with an updated
4217
version of the Document.
4187
the Document well before redistributing any large number of copies,
4188
to give them a chance to provide you with an updated version of the
4189
Document.
4218
4190
4219
4191
4. MODIFICATIONS
4220
4192
4221
4193
You may copy and distribute a Modified Version of the Document
4222
4194
under the conditions of sections 2 and 3 above, provided that you
4223
release the Modified Version under precisely this License, with
4224
the Modified Version filling the role of the Document, thus
4225
licensing distribution and modification of the Modified Version to
4226
whoever possesses a copy of it. In addition, you must do these
4227
things in the Modified Version:
4195
release the Modified Version under precisely this License, with the
4196
Modified Version filling the role of the Document, thus licensing
4197
distribution and modification of the Modified Version to whoever
4198
possesses a copy of it. In addition, you must do these things in
4199
the Modified Version:
4228
4200
4229
4201
A. Use in the Title Page (and on the covers, if any) a title
4230
distinct from that of the Document, and from those of
4231
previous versions (which should, if there were any, be listed
4232
in the History section of the Document). You may use the
4233
same title as a previous version if the original publisher of
4234
that version gives permission.
4202
distinct from that of the Document, and from those of previous
4203
versions (which should, if there were any, be listed in the
4204
History section of the Document). You may use the same title
4205
as a previous version if the original publisher of that
4206
version gives permission.
4235
4207
4236
4208
B. List on the Title Page, as authors, one or more persons or
4237
4209
entities responsible for authorship of the modifications in
4261
4233
4262
4234
I. Preserve the section Entitled "History", Preserve its Title,
4263
4235
and add to it an item stating at least the title, year, new
4264
authors, and publisher of the Modified Version as given on
4265
the Title Page. If there is no section Entitled "History" in
4266
the Document, create one stating the title, year, authors,
4267
and publisher of the Document as given on its Title Page,
4268
then add an item describing the Modified Version as stated in
4269
the previous sentence.
4236
authors, and publisher of the Modified Version as given on the
4237
Title Page. If there is no section Entitled "History" in the
4238
Document, create one stating the title, year, authors, and
4239
publisher of the Document as given on its Title Page, then add
4240
an item describing the Modified Version as stated in the
4241
previous sentence.
4270
4242
4271
4243
J. Preserve the network location, if any, given in the Document
4272
4244
for public access to a Transparent copy of the Document, and
4273
4245
likewise the network locations given in the Document for
4274
previous versions it was based on. These may be placed in
4275
the "History" section. You may omit a network location for a
4276
work that was published at least four years before the
4277
Document itself, or if the original publisher of the version
4278
it refers to gives permission.
4246
previous versions it was based on. These may be placed in the
4247
"History" section. You may omit a network location for a work
4248
that was published at least four years before the Document
4249
itself, or if the original publisher of the version it refers
4250
to gives permission.
4279
4251
4280
4252
K. For any section Entitled "Acknowledgements" or "Dedications",
4281
Preserve the Title of the section, and preserve in the
4282
section all the substance and tone of each of the contributor
4253
Preserve the Title of the section, and preserve in the section
4254
all the substance and tone of each of the contributor
4283
4255
acknowledgements and/or dedications given therein.
4284
4256
4285
L. Preserve all the Invariant Sections of the Document,
4286
unaltered in their text and in their titles. Section numbers
4287
or the equivalent are not considered part of the section
4288
titles.
4257
L. Preserve all the Invariant Sections of the Document, unaltered
4258
in their text and in their titles. Section numbers or the
4259
equivalent are not considered part of the section titles.
4289
4260
4290
4261
M. Delete any section Entitled "Endorsements". Such a section
4291
4262
may not be included in the Modified Version.
4298
4269
4299
4270
If the Modified Version includes new front-matter sections or
4300
4271
appendices that qualify as Secondary Sections and contain no
4301
material copied from the Document, you may at your option
4302
designate some or all of these sections as invariant. To do this,
4303
add their titles to the list of Invariant Sections in the Modified
4304
Version's license notice. These titles must be distinct from any
4305
other section titles.
4272
material copied from the Document, you may at your option designate
4273
some or all of these sections as invariant. To do this, add their
4274
titles to the list of Invariant Sections in the Modified Version's
4275
license notice. These titles must be distinct from any other
4276
section titles.
4306
4277
4307
4278
You may add a section Entitled "Endorsements", provided it contains
4308
4279
nothing but endorsements of your Modified Version by various
4311
4282
definition of a standard.
4312
4283
4313
4284
You may add a passage of up to five words as a Front-Cover Text,
4314
and a passage of up to 25 words as a Back-Cover Text, to the end
4315
of the list of Cover Texts in the Modified Version. Only one
4316
passage of Front-Cover Text and one of Back-Cover Text may be
4317
added by (or through arrangements made by) any one entity. If the
4318
Document already includes a cover text for the same cover,
4319
previously added by you or by arrangement made by the same entity
4320
you are acting on behalf of, you may not add another; but you may
4321
replace the old one, on explicit permission from the previous
4322
publisher that added the old one.
4285
and a passage of up to 25 words as a Back-Cover Text, to the end of
4286
the list of Cover Texts in the Modified Version. Only one passage
4287
of Front-Cover Text and one of Back-Cover Text may be added by (or
4288
through arrangements made by) any one entity. If the Document
4289
already includes a cover text for the same cover, previously added
4290
by you or by arrangement made by the same entity you are acting on
4291
behalf of, you may not add another; but you may replace the old
4292
one, on explicit permission from the previous publisher that added
4293
the old one.
4323
4294
4324
4295
The author(s) and publisher(s) of the Document do not by this
4325
4296
License give permission to use their names for publicity for or to
4329
4300
4330
4301
You may combine the Document with other documents released under
4331
4302
this License, under the terms defined in section 4 above for
4332
modified versions, provided that you include in the combination
4333
all of the Invariant Sections of all of the original documents,
4303
modified versions, provided that you include in the combination all
4304
of the Invariant Sections of all of the original documents,
4334
4305
unmodified, and list them all as Invariant Sections of your
4335
4306
combined work in its license notice, and that you preserve all
4336
4307
their Warranty Disclaimers.
4357
4328
documents released under this License, and replace the individual
4358
4329
copies of this License in the various documents with a single copy
4359
4330
that is included in the collection, provided that you follow the
4360
rules of this License for verbatim copying of each of the
4361
documents in all other respects.
4331
rules of this License for verbatim copying of each of the documents
4332
in all other respects.
4362
4333
4363
4334
You may extract a single document from such a collection, and
4364
4335
distribute it individually under this License, provided you insert
4365
a copy of this License into the extracted document, and follow
4366
this License in all other respects regarding verbatim copying of
4367
that document.
4336
a copy of this License into the extracted document, and follow this
4337
License in all other respects regarding verbatim copying of that
4338
document.
4368
4339
4369
4340
7. AGGREGATION WITH INDEPENDENT WORKS
4370
4341
4371
4342
A compilation of the Document or its derivatives with other
4372
separate and independent documents or works, in or on a volume of
4373
a storage or distribution medium, is called an "aggregate" if the
4343
separate and independent documents or works, in or on a volume of a
4344
storage or distribution medium, is called an "aggregate" if the
4374
4345
copyright resulting from the compilation is not used to limit the
4375
4346
legal rights of the compilation's users beyond what the individual
4376
4347
works permit. When the Document is included in an aggregate, this
4415
4386
4416
4387
However, if you cease all violation of this License, then your
4417
4388
license from a particular copyright holder is reinstated (a)
4418
provisionally, unless and until the copyright holder explicitly
4419
and finally terminates your license, and (b) permanently, if the
4389
provisionally, unless and until the copyright holder explicitly and
4390
finally terminates your license, and (b) permanently, if the
4420
4391
copyright holder fails to notify you of the violation by some
4421
4392
reasonable means prior to 60 days after the cessation.
4422
4393
4428
4399
after your receipt of the notice.
4429
4400
4430
4401
Termination of your rights under this section does not terminate
4431
the licenses of parties who have received copies or rights from
4432
you under this License. If your rights have been terminated and
4433
not permanently reinstated, receipt of a copy of some or all of
4434
the same material does not give you any rights to use it.
4402
the licenses of parties who have received copies or rights from you
4403
under this License. If your rights have been terminated and not
4404
permanently reinstated, receipt of a copy of some or all of the
4405
same material does not give you any rights to use it.
4435
4406
4436
10. FUTURE REVISIONS OF THIS LICENSE
4407
10. FUTURE REVISIONS OF THIS LICENSE
4437
4408
4438
4409
The Free Software Foundation may publish new, revised versions of
4439
4410
the GNU Free Documentation License from time to time. Such new
4440
4411
versions will be similar in spirit to the present version, but may
4441
4412
differ in detail to address new problems or concerns. See
4442
`http://www.gnu.org/copyleft/'.
4413
<http://www.gnu.org/copyleft/>.
4443
4414
4444
4415
Each version of the License is given a distinguishing version
4445
4416
number. If the Document specifies that a particular numbered
4446
4417
version of this License "or any later version" applies to it, you
4447
4418
have the option of following the terms and conditions either of
4448
4419
that specified version or of any later version that has been
4449
published (not as a draft) by the Free Software Foundation. If
4450
the Document does not specify a version number of this License,
4451
you may choose any version ever published (not as a draft) by the
4452
Free Software Foundation. If the Document specifies that a proxy
4453
can decide which future versions of this License can be used, that
4420
published (not as a draft) by the Free Software Foundation. If the
4421
Document does not specify a version number of this License, you may
4422
choose any version ever published (not as a draft) by the Free
4423
Software Foundation. If the Document specifies that a proxy can
4424
decide which future versions of this License can be used, that
4454
4425
proxy's public statement of acceptance of a version permanently
4455
4426
authorizes you to choose that version for the Document.
4456
4427
4457
11. RELICENSING
4428
11. RELICENSING
4458
4429
4459
4430
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
4460
4431
World Wide Web server that publishes copyrightable works and also
4484
4455
site under CC-BY-SA on the same site at any time before August 1,
4485
4456
2009, provided the MMC is eligible for relicensing.
4486
4457
4487
4488
4458
ADDENDUM: How to use this License for your documents
4489
4459
====================================================
4490
4460
4512
4482
situation.
4513
4483
4514
4484
If your document contains nontrivial examples of program code, we
4515
recommend releasing these examples in parallel under your choice of
4516
free software license, such as the GNU General Public License, to
4517
permit their use in free software.
4518
4519
4520
File: gss.info, Node: GNU GPL, Prev: GNU Free Documentation License, Up: Copying Information
4521
4522
B.2 GNU General Public License
4523
==============================
4524
4525
Version 3, 29 June 2007
4526
4527
Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/'
4528
4529
Everyone is permitted to copy and distribute verbatim copies of this
4530
license document, but changing it is not allowed.
4531
4532
Preamble
4533
========
4534
4535
The GNU General Public License is a free, copyleft license for software
4536
and other kinds of works.
4537
4538
The licenses for most software and other practical works are designed
4539
to take away your freedom to share and change the works. By contrast,
4540
the GNU General Public License is intended to guarantee your freedom to
4541
share and change all versions of a program--to make sure it remains
4542
free software for all its users. We, the Free Software Foundation, use
4543
the GNU General Public License for most of our software; it applies
4544
also to any other work released this way by its authors. You can apply
4545
it to your programs, too.
4546
4547
When we speak of free software, we are referring to freedom, not
4548
price. Our General Public Licenses are designed to make sure that you
4549
have the freedom to distribute copies of free software (and charge for
4550
them if you wish), that you receive source code or can get it if you
4551
want it, that you can change the software or use pieces of it in new
4552
free programs, and that you know you can do these things.
4553
4554
To protect your rights, we need to prevent others from denying you
4555
these rights or asking you to surrender the rights. Therefore, you
4556
have certain responsibilities if you distribute copies of the software,
4557
or if you modify it: responsibilities to respect the freedom of others.
4558
4559
For example, if you distribute copies of such a program, whether
4560
gratis or for a fee, you must pass on to the recipients the same
4561
freedoms that you received. You must make sure that they, too, receive
4562
or can get the source code. And you must show them these terms so they
4563
know their rights.
4564
4565
Developers that use the GNU GPL protect your rights with two steps:
4566
(1) assert copyright on the software, and (2) offer you this License
4567
giving you legal permission to copy, distribute and/or modify it.
4568
4569
For the developers' and authors' protection, the GPL clearly explains
4570
that there is no warranty for this free software. For both users' and
4571
authors' sake, the GPL requires that modified versions be marked as
4572
changed, so that their problems will not be attributed erroneously to
4573
authors of previous versions.
4574
4575
Some devices are designed to deny users access to install or run
4576
modified versions of the software inside them, although the
4577
manufacturer can do so. This is fundamentally incompatible with the
4578
aim of protecting users' freedom to change the software. The
4579
systematic pattern of such abuse occurs in the area of products for
4580
individuals to use, which is precisely where it is most unacceptable.
4581
Therefore, we have designed this version of the GPL to prohibit the
4582
practice for those products. If such problems arise substantially in
4583
other domains, we stand ready to extend this provision to those domains
4584
in future versions of the GPL, as needed to protect the freedom of
4585
users.
4586
4587
Finally, every program is threatened constantly by software patents.
4588
States should not allow patents to restrict development and use of
4589
software on general-purpose computers, but in those that do, we wish to
4590
avoid the special danger that patents applied to a free program could
4591
make it effectively proprietary. To prevent this, the GPL assures that
4592
patents cannot be used to render the program non-free.
4593
4594
The precise terms and conditions for copying, distribution and
4595
modification follow.
4596
4597
TERMS AND CONDITIONS
4598
====================
4599
4600
0. Definitions.
4601
4602
"This License" refers to version 3 of the GNU General Public
4603
License.
4604
4605
"Copyright" also means copyright-like laws that apply to other
4606
kinds of works, such as semiconductor masks.
4607
4608
"The Program" refers to any copyrightable work licensed under this
4609
License. Each licensee is addressed as "you". "Licensees" and
4610
"recipients" may be individuals or organizations.
4611
4612
To "modify" a work means to copy from or adapt all or part of the
4613
work in a fashion requiring copyright permission, other than the
4614
making of an exact copy. The resulting work is called a "modified
4615
version" of the earlier work or a work "based on" the earlier work.
4616
4617
A "covered work" means either the unmodified Program or a work
4618
based on the Program.
4619
4620
To "propagate" a work means to do anything with it that, without
4621
permission, would make you directly or secondarily liable for
4622
infringement under applicable copyright law, except executing it
4623
on a computer or modifying a private copy. Propagation includes
4624
copying, distribution (with or without modification), making
4625
available to the public, and in some countries other activities as
4626
well.
4627
4628
To "convey" a work means any kind of propagation that enables other
4629
parties to make or receive copies. Mere interaction with a user
4630
through a computer network, with no transfer of a copy, is not
4631
conveying.
4632
4633
An interactive user interface displays "Appropriate Legal Notices"
4634
to the extent that it includes a convenient and prominently visible
4635
feature that (1) displays an appropriate copyright notice, and (2)
4636
tells the user that there is no warranty for the work (except to
4637
the extent that warranties are provided), that licensees may
4638
convey the work under this License, and how to view a copy of this
4639
License. If the interface presents a list of user commands or
4640
options, such as a menu, a prominent item in the list meets this
4641
criterion.
4642
4643
1. Source Code.
4644
4645
The "source code" for a work means the preferred form of the work
4646
for making modifications to it. "Object code" means any
4647
non-source form of a work.
4648
4649
A "Standard Interface" means an interface that either is an
4650
official standard defined by a recognized standards body, or, in
4651
the case of interfaces specified for a particular programming
4652
language, one that is widely used among developers working in that
4653
language.
4654
4655
The "System Libraries" of an executable work include anything,
4656
other than the work as a whole, that (a) is included in the normal
4657
form of packaging a Major Component, but which is not part of that
4658
Major Component, and (b) serves only to enable use of the work
4659
with that Major Component, or to implement a Standard Interface
4660
for which an implementation is available to the public in source
4661
code form. A "Major Component", in this context, means a major
4662
essential component (kernel, window system, and so on) of the
4663
specific operating system (if any) on which the executable work
4664
runs, or a compiler used to produce the work, or an object code
4665
interpreter used to run it.
4666
4667
The "Corresponding Source" for a work in object code form means all
4668
the source code needed to generate, install, and (for an executable
4669
work) run the object code and to modify the work, including
4670
scripts to control those activities. However, it does not include
4671
the work's System Libraries, or general-purpose tools or generally
4672
available free programs which are used unmodified in performing
4673
those activities but which are not part of the work. For example,
4674
Corresponding Source includes interface definition files
4675
associated with source files for the work, and the source code for
4676
shared libraries and dynamically linked subprograms that the work
4677
is specifically designed to require, such as by intimate data
4678
communication or control flow between those subprograms and other
4679
parts of the work.
4680
4681
The Corresponding Source need not include anything that users can
4682
regenerate automatically from other parts of the Corresponding
4683
Source.
4684
4685
The Corresponding Source for a work in source code form is that
4686
same work.
4687
4688
2. Basic Permissions.
4689
4690
All rights granted under this License are granted for the term of
4691
copyright on the Program, and are irrevocable provided the stated
4692
conditions are met. This License explicitly affirms your unlimited
4693
permission to run the unmodified Program. The output from running
4694
a covered work is covered by this License only if the output,
4695
given its content, constitutes a covered work. This License
4696
acknowledges your rights of fair use or other equivalent, as
4697
provided by copyright law.
4698
4699
You may make, run and propagate covered works that you do not
4700
convey, without conditions so long as your license otherwise
4701
remains in force. You may convey covered works to others for the
4702
sole purpose of having them make modifications exclusively for
4703
you, or provide you with facilities for running those works,
4704
provided that you comply with the terms of this License in
4705
conveying all material for which you do not control copyright.
4706
Those thus making or running the covered works for you must do so
4707
exclusively on your behalf, under your direction and control, on
4708
terms that prohibit them from making any copies of your
4709
copyrighted material outside their relationship with you.
4710
4711
Conveying under any other circumstances is permitted solely under
4712
the conditions stated below. Sublicensing is not allowed; section
4713
10 makes it unnecessary.
4714
4715
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
4716
4717
No covered work shall be deemed part of an effective technological
4718
measure under any applicable law fulfilling obligations under
4719
article 11 of the WIPO copyright treaty adopted on 20 December
4720
1996, or similar laws prohibiting or restricting circumvention of
4721
such measures.
4722
4723
When you convey a covered work, you waive any legal power to forbid
4724
circumvention of technological measures to the extent such
4725
circumvention is effected by exercising rights under this License
4726
with respect to the covered work, and you disclaim any intention
4727
to limit operation or modification of the work as a means of
4728
enforcing, against the work's users, your or third parties' legal
4729
rights to forbid circumvention of technological measures.
4730
4731
4. Conveying Verbatim Copies.
4732
4733
You may convey verbatim copies of the Program's source code as you
4734
receive it, in any medium, provided that you conspicuously and
4735
appropriately publish on each copy an appropriate copyright notice;
4736
keep intact all notices stating that this License and any
4737
non-permissive terms added in accord with section 7 apply to the
4738
code; keep intact all notices of the absence of any warranty; and
4739
give all recipients a copy of this License along with the Program.
4740
4741
You may charge any price or no price for each copy that you convey,
4742
and you may offer support or warranty protection for a fee.
4743
4744
5. Conveying Modified Source Versions.
4745
4746
You may convey a work based on the Program, or the modifications to
4747
produce it from the Program, in the form of source code under the
4748
terms of section 4, provided that you also meet all of these
4749
conditions:
4750
4751
a. The work must carry prominent notices stating that you
4752
modified it, and giving a relevant date.
4753
4754
b. The work must carry prominent notices stating that it is
4755
released under this License and any conditions added under
4756
section 7. This requirement modifies the requirement in
4757
section 4 to "keep intact all notices".
4758
4759
c. You must license the entire work, as a whole, under this
4760
License to anyone who comes into possession of a copy. This
4761
License will therefore apply, along with any applicable
4762
section 7 additional terms, to the whole of the work, and all
4763
its parts, regardless of how they are packaged. This License
4764
gives no permission to license the work in any other way, but
4765
it does not invalidate such permission if you have separately
4766
received it.
4767
4768
d. If the work has interactive user interfaces, each must display
4769
Appropriate Legal Notices; however, if the Program has
4770
interactive interfaces that do not display Appropriate Legal
4771
Notices, your work need not make them do so.
4772
4773
A compilation of a covered work with other separate and independent
4774
works, which are not by their nature extensions of the covered
4775
work, and which are not combined with it such as to form a larger
4776
program, in or on a volume of a storage or distribution medium, is
4777
called an "aggregate" if the compilation and its resulting
4778
copyright are not used to limit the access or legal rights of the
4779
compilation's users beyond what the individual works permit.
4780
Inclusion of a covered work in an aggregate does not cause this
4781
License to apply to the other parts of the aggregate.
4782
4783
6. Conveying Non-Source Forms.
4784
4785
You may convey a covered work in object code form under the terms
4786
of sections 4 and 5, provided that you also convey the
4787
machine-readable Corresponding Source under the terms of this
4788
License, in one of these ways:
4789
4790
a. Convey the object code in, or embodied in, a physical product
4791
(including a physical distribution medium), accompanied by the
4792
Corresponding Source fixed on a durable physical medium
4793
customarily used for software interchange.
4794
4795
b. Convey the object code in, or embodied in, a physical product
4796
(including a physical distribution medium), accompanied by a
4797
written offer, valid for at least three years and valid for
4798
as long as you offer spare parts or customer support for that
4799
product model, to give anyone who possesses the object code
4800
either (1) a copy of the Corresponding Source for all the
4801
software in the product that is covered by this License, on a
4802
durable physical medium customarily used for software
4803
interchange, for a price no more than your reasonable cost of
4804
physically performing this conveying of source, or (2) access
4805
to copy the Corresponding Source from a network server at no
4806
charge.
4807
4808
c. Convey individual copies of the object code with a copy of
4809
the written offer to provide the Corresponding Source. This
4810
alternative is allowed only occasionally and noncommercially,
4811
and only if you received the object code with such an offer,
4812
in accord with subsection 6b.
4813
4814
d. Convey the object code by offering access from a designated
4815
place (gratis or for a charge), and offer equivalent access
4816
to the Corresponding Source in the same way through the same
4817
place at no further charge. You need not require recipients
4818
to copy the Corresponding Source along with the object code.
4819
If the place to copy the object code is a network server, the
4820
Corresponding Source may be on a different server (operated
4821
by you or a third party) that supports equivalent copying
4822
facilities, provided you maintain clear directions next to
4823
the object code saying where to find the Corresponding Source.
4824
Regardless of what server hosts the Corresponding Source, you
4825
remain obligated to ensure that it is available for as long
4826
as needed to satisfy these requirements.
4827
4828
e. Convey the object code using peer-to-peer transmission,
4829
provided you inform other peers where the object code and
4830
Corresponding Source of the work are being offered to the
4831
general public at no charge under subsection 6d.
4832
4833
4834
A separable portion of the object code, whose source code is
4835
excluded from the Corresponding Source as a System Library, need
4836
not be included in conveying the object code work.
4837
4838
A "User Product" is either (1) a "consumer product", which means
4839
any tangible personal property which is normally used for personal,
4840
family, or household purposes, or (2) anything designed or sold for
4841
incorporation into a dwelling. In determining whether a product
4842
is a consumer product, doubtful cases shall be resolved in favor of
4843
coverage. For a particular product received by a particular user,
4844
"normally used" refers to a typical or common use of that class of
4845
product, regardless of the status of the particular user or of the
4846
way in which the particular user actually uses, or expects or is
4847
expected to use, the product. A product is a consumer product
4848
regardless of whether the product has substantial commercial,
4849
industrial or non-consumer uses, unless such uses represent the
4850
only significant mode of use of the product.
4851
4852
"Installation Information" for a User Product means any methods,
4853
procedures, authorization keys, or other information required to
4854
install and execute modified versions of a covered work in that
4855
User Product from a modified version of its Corresponding Source.
4856
The information must suffice to ensure that the continued
4857
functioning of the modified object code is in no case prevented or
4858
interfered with solely because modification has been made.
4859
4860
If you convey an object code work under this section in, or with,
4861
or specifically for use in, a User Product, and the conveying
4862
occurs as part of a transaction in which the right of possession
4863
and use of the User Product is transferred to the recipient in
4864
perpetuity or for a fixed term (regardless of how the transaction
4865
is characterized), the Corresponding Source conveyed under this
4866
section must be accompanied by the Installation Information. But
4867
this requirement does not apply if neither you nor any third party
4868
retains the ability to install modified object code on the User
4869
Product (for example, the work has been installed in ROM).
4870
4871
The requirement to provide Installation Information does not
4872
include a requirement to continue to provide support service,
4873
warranty, or updates for a work that has been modified or
4874
installed by the recipient, or for the User Product in which it
4875
has been modified or installed. Access to a network may be denied
4876
when the modification itself materially and adversely affects the
4877
operation of the network or violates the rules and protocols for
4878
communication across the network.
4879
4880
Corresponding Source conveyed, and Installation Information
4881
provided, in accord with this section must be in a format that is
4882
publicly documented (and with an implementation available to the
4883
public in source code form), and must require no special password
4884
or key for unpacking, reading or copying.
4885
4886
7. Additional Terms.
4887
4888
"Additional permissions" are terms that supplement the terms of
4889
this License by making exceptions from one or more of its
4890
conditions. Additional permissions that are applicable to the
4891
entire Program shall be treated as though they were included in
4892
this License, to the extent that they are valid under applicable
4893
law. If additional permissions apply only to part of the Program,
4894
that part may be used separately under those permissions, but the
4895
entire Program remains governed by this License without regard to
4896
the additional permissions.
4897
4898
When you convey a copy of a covered work, you may at your option
4899
remove any additional permissions from that copy, or from any part
4900
of it. (Additional permissions may be written to require their own
4901
removal in certain cases when you modify the work.) You may place
4902
additional permissions on material, added by you to a covered work,
4903
for which you have or can give appropriate copyright permission.
4904
4905
Notwithstanding any other provision of this License, for material
4906
you add to a covered work, you may (if authorized by the copyright
4907
holders of that material) supplement the terms of this License
4908
with terms:
4909
4910
a. Disclaiming warranty or limiting liability differently from
4911
the terms of sections 15 and 16 of this License; or
4912
4913
b. Requiring preservation of specified reasonable legal notices
4914
or author attributions in that material or in the Appropriate
4915
Legal Notices displayed by works containing it; or
4916
4917
c. Prohibiting misrepresentation of the origin of that material,
4918
or requiring that modified versions of such material be
4919
marked in reasonable ways as different from the original
4920
version; or
4921
4922
d. Limiting the use for publicity purposes of names of licensors
4923
or authors of the material; or
4924
4925
e. Declining to grant rights under trademark law for use of some
4926
trade names, trademarks, or service marks; or
4927
4928
f. Requiring indemnification of licensors and authors of that
4929
material by anyone who conveys the material (or modified
4930
versions of it) with contractual assumptions of liability to
4931
the recipient, for any liability that these contractual
4932
assumptions directly impose on those licensors and authors.
4933
4934
All other non-permissive additional terms are considered "further
4935
restrictions" within the meaning of section 10. If the Program as
4936
you received it, or any part of it, contains a notice stating that
4937
it is governed by this License along with a term that is a further
4938
restriction, you may remove that term. If a license document
4939
contains a further restriction but permits relicensing or
4940
conveying under this License, you may add to a covered work
4941
material governed by the terms of that license document, provided
4942
that the further restriction does not survive such relicensing or
4943
conveying.
4944
4945
If you add terms to a covered work in accord with this section, you
4946
must place, in the relevant source files, a statement of the
4947
additional terms that apply to those files, or a notice indicating
4948
where to find the applicable terms.
4949
4950
Additional terms, permissive or non-permissive, may be stated in
4951
the form of a separately written license, or stated as exceptions;
4952
the above requirements apply either way.
4953
4954
8. Termination.
4955
4956
You may not propagate or modify a covered work except as expressly
4957
provided under this License. Any attempt otherwise to propagate or
4958
modify it is void, and will automatically terminate your rights
4959
under this License (including any patent licenses granted under
4960
the third paragraph of section 11).
4961
4962
However, if you cease all violation of this License, then your
4963
license from a particular copyright holder is reinstated (a)
4964
provisionally, unless and until the copyright holder explicitly
4965
and finally terminates your license, and (b) permanently, if the
4966
copyright holder fails to notify you of the violation by some
4967
reasonable means prior to 60 days after the cessation.
4968
4969
Moreover, your license from a particular copyright holder is
4970
reinstated permanently if the copyright holder notifies you of the
4971
violation by some reasonable means, this is the first time you have
4972
received notice of violation of this License (for any work) from
4973
that copyright holder, and you cure the violation prior to 30 days
4974
after your receipt of the notice.
4975
4976
Termination of your rights under this section does not terminate
4977
the licenses of parties who have received copies or rights from
4978
you under this License. If your rights have been terminated and
4979
not permanently reinstated, you do not qualify to receive new
4980
licenses for the same material under section 10.
4981
4982
9. Acceptance Not Required for Having Copies.
4983
4984
You are not required to accept this License in order to receive or
4985
run a copy of the Program. Ancillary propagation of a covered work
4986
occurring solely as a consequence of using peer-to-peer
4987
transmission to receive a copy likewise does not require
4988
acceptance. However, nothing other than this License grants you
4989
permission to propagate or modify any covered work. These actions
4990
infringe copyright if you do not accept this License. Therefore,
4991
by modifying or propagating a covered work, you indicate your
4992
acceptance of this License to do so.
4993
4994
10. Automatic Licensing of Downstream Recipients.
4995
4996
Each time you convey a covered work, the recipient automatically
4997
receives a license from the original licensors, to run, modify and
4998
propagate that work, subject to this License. You are not
4999
responsible for enforcing compliance by third parties with this
5000
License.
5001
5002
An "entity transaction" is a transaction transferring control of an
5003
organization, or substantially all assets of one, or subdividing an
5004
organization, or merging organizations. If propagation of a
5005
covered work results from an entity transaction, each party to that
5006
transaction who receives a copy of the work also receives whatever
5007
licenses to the work the party's predecessor in interest had or
5008
could give under the previous paragraph, plus a right to
5009
possession of the Corresponding Source of the work from the
5010
predecessor in interest, if the predecessor has it or can get it
5011
with reasonable efforts.
5012
5013
You may not impose any further restrictions on the exercise of the
5014
rights granted or affirmed under this License. For example, you
5015
may not impose a license fee, royalty, or other charge for
5016
exercise of rights granted under this License, and you may not
5017
initiate litigation (including a cross-claim or counterclaim in a
5018
lawsuit) alleging that any patent claim is infringed by making,
5019
using, selling, offering for sale, or importing the Program or any
5020
portion of it.
5021
5022
11. Patents.
5023
5024
A "contributor" is a copyright holder who authorizes use under this
5025
License of the Program or a work on which the Program is based.
5026
The work thus licensed is called the contributor's "contributor
5027
version".
5028
5029
A contributor's "essential patent claims" are all patent claims
5030
owned or controlled by the contributor, whether already acquired or
5031
hereafter acquired, that would be infringed by some manner,
5032
permitted by this License, of making, using, or selling its
5033
contributor version, but do not include claims that would be
5034
infringed only as a consequence of further modification of the
5035
contributor version. For purposes of this definition, "control"
5036
includes the right to grant patent sublicenses in a manner
5037
consistent with the requirements of this License.
5038
5039
Each contributor grants you a non-exclusive, worldwide,
5040
royalty-free patent license under the contributor's essential
5041
patent claims, to make, use, sell, offer for sale, import and
5042
otherwise run, modify and propagate the contents of its
5043
contributor version.
5044
5045
In the following three paragraphs, a "patent license" is any
5046
express agreement or commitment, however denominated, not to
5047
enforce a patent (such as an express permission to practice a
5048
patent or covenant not to sue for patent infringement). To
5049
"grant" such a patent license to a party means to make such an
5050
agreement or commitment not to enforce a patent against the party.
5051
5052
If you convey a covered work, knowingly relying on a patent
5053
license, and the Corresponding Source of the work is not available
5054
for anyone to copy, free of charge and under the terms of this
5055
License, through a publicly available network server or other
5056
readily accessible means, then you must either (1) cause the
5057
Corresponding Source to be so available, or (2) arrange to deprive
5058
yourself of the benefit of the patent license for this particular
5059
work, or (3) arrange, in a manner consistent with the requirements
5060
of this License, to extend the patent license to downstream
5061
recipients. "Knowingly relying" means you have actual knowledge
5062
that, but for the patent license, your conveying the covered work
5063
in a country, or your recipient's use of the covered work in a
5064
country, would infringe one or more identifiable patents in that
5065
country that you have reason to believe are valid.
5066
5067
If, pursuant to or in connection with a single transaction or
5068
arrangement, you convey, or propagate by procuring conveyance of, a
5069
covered work, and grant a patent license to some of the parties
5070
receiving the covered work authorizing them to use, propagate,
5071
modify or convey a specific copy of the covered work, then the
5072
patent license you grant is automatically extended to all
5073
recipients of the covered work and works based on it.
5074
5075
A patent license is "discriminatory" if it does not include within
5076
the scope of its coverage, prohibits the exercise of, or is
5077
conditioned on the non-exercise of one or more of the rights that
5078
are specifically granted under this License. You may not convey a
5079
covered work if you are a party to an arrangement with a third
5080
party that is in the business of distributing software, under
5081
which you make payment to the third party based on the extent of
5082
your activity of conveying the work, and under which the third
5083
party grants, to any of the parties who would receive the covered
5084
work from you, a discriminatory patent license (a) in connection
5085
with copies of the covered work conveyed by you (or copies made
5086
from those copies), or (b) primarily for and in connection with
5087
specific products or compilations that contain the covered work,
5088
unless you entered into that arrangement, or that patent license
5089
was granted, prior to 28 March 2007.
5090
5091
Nothing in this License shall be construed as excluding or limiting
5092
any implied license or other defenses to infringement that may
5093
otherwise be available to you under applicable patent law.
5094
5095
12. No Surrender of Others' Freedom.
5096
5097
If conditions are imposed on you (whether by court order,
5098
agreement or otherwise) that contradict the conditions of this
5099
License, they do not excuse you from the conditions of this
5100
License. If you cannot convey a covered work so as to satisfy
5101
simultaneously your obligations under this License and any other
5102
pertinent obligations, then as a consequence you may not convey it
5103
at all. For example, if you agree to terms that obligate you to
5104
collect a royalty for further conveying from those to whom you
5105
convey the Program, the only way you could satisfy both those
5106
terms and this License would be to refrain entirely from conveying
5107
the Program.
5108
5109
13. Use with the GNU Affero General Public License.
5110
5111
Notwithstanding any other provision of this License, you have
5112
permission to link or combine any covered work with a work licensed
5113
under version 3 of the GNU Affero General Public License into a
5114
single combined work, and to convey the resulting work. The terms
5115
of this License will continue to apply to the part which is the
5116
covered work, but the special requirements of the GNU Affero
5117
General Public License, section 13, concerning interaction through
5118
a network will apply to the combination as such.
5119
5120
14. Revised Versions of this License.
5121
5122
The Free Software Foundation may publish revised and/or new
5123
versions of the GNU General Public License from time to time.
5124
Such new versions will be similar in spirit to the present
5125
version, but may differ in detail to address new problems or
5126
concerns.
5127
5128
Each version is given a distinguishing version number. If the
5129
Program specifies that a certain numbered version of the GNU
5130
General Public License "or any later version" applies to it, you
5131
have the option of following the terms and conditions either of
5132
that numbered version or of any later version published by the
5133
Free Software Foundation. If the Program does not specify a
5134
version number of the GNU General Public License, you may choose
5135
any version ever published by the Free Software Foundation.
5136
5137
If the Program specifies that a proxy can decide which future
5138
versions of the GNU General Public License can be used, that
5139
proxy's public statement of acceptance of a version permanently
5140
authorizes you to choose that version for the Program.
5141
5142
Later license versions may give you additional or different
5143
permissions. However, no additional obligations are imposed on any
5144
author or copyright holder as a result of your choosing to follow a
5145
later version.
5146
5147
15. Disclaimer of Warranty.
5148
5149
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
5150
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
5151
COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
5152
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
5153
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
5154
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
5155
RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
5156
SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
5157
NECESSARY SERVICING, REPAIR OR CORRECTION.
5158
5159
16. Limitation of Liability.
5160
5161
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
5162
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
5163
AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
5164
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
5165
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
5166
THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
5167
BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
5168
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
5169
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
5170
THE POSSIBILITY OF SUCH DAMAGES.
5171
5172
17. Interpretation of Sections 15 and 16.
5173
5174
If the disclaimer of warranty and limitation of liability provided
5175
above cannot be given local legal effect according to their terms,
5176
reviewing courts shall apply local law that most closely
5177
approximates an absolute waiver of all civil liability in
5178
connection with the Program, unless a warranty or assumption of
5179
liability accompanies a copy of the Program in return for a fee.
5180
5181
5182
END OF TERMS AND CONDITIONS
5183
===========================
5184
5185
How to Apply These Terms to Your New Programs
5186
=============================================
5187
5188
If you develop a new program, and you want it to be of the greatest
5189
possible use to the public, the best way to achieve this is to make it
5190
free software which everyone can redistribute and change under these
5191
terms.
5192
5193
To do so, attach the following notices to the program. It is safest
5194
to attach them to the start of each source file to most effectively
5195
state the exclusion of warranty; and each file should have at least the
5196
"copyright" line and a pointer to where the full notice is found.
5197
5198
ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
5199
Copyright (C) YEAR NAME OF AUTHOR
5200
5201
This program is free software: you can redistribute it and/or modify
5202
it under the terms of the GNU General Public License as published by
5203
the Free Software Foundation, either version 3 of the License, or (at
5204
your option) any later version.
5205
5206
This program is distributed in the hope that it will be useful, but
5207
WITHOUT ANY WARRANTY; without even the implied warranty of
5208
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5209
General Public License for more details.
5210
5211
You should have received a copy of the GNU General Public License
5212
along with this program. If not, see `http://www.gnu.org/licenses/'.
5213
5214
Also add information on how to contact you by electronic and paper
5215
mail.
5216
5217
If the program does terminal interaction, make it output a short
5218
notice like this when it starts in an interactive mode:
5219
5220
PROGRAM Copyright (C) YEAR NAME OF AUTHOR
5221
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
5222
This is free software, and you are welcome to redistribute it
5223
under certain conditions; type `show c' for details.
5224
5225
The hypothetical commands `show w' and `show c' should show the
5226
appropriate parts of the General Public License. Of course, your
5227
program's commands might be different; for a GUI interface, you would
5228
use an "about box".
5229
5230
You should also get your employer (if you work as a programmer) or
5231
school, if any, to sign a "copyright disclaimer" for the program, if
5232
necessary. For more information on this, and how to apply and follow
5233
the GNU GPL, see `http://www.gnu.org/licenses/'.
5234
5235
The GNU General Public License does not permit incorporating your
5236
program into proprietary programs. If your program is a subroutine
5237
library, you may consider it more useful to permit linking proprietary
5238
applications with the library. If this is what you want to do, use the
5239
GNU Lesser General Public License instead of this License. But first,
5240
please read `http://www.gnu.org/philosophy/why-not-lgpl.html'.
4485
recommend releasing these examples in parallel under your choice of free
4486
software license, such as the GNU General Public License, to permit
4487
their use in free software.
5241
4488
5242
4489
5243
4490
File: gss.info, Node: Concept Index, Next: API Index, Prev: Copying Information, Up: Top
5251
4498
* AIX: Supported Platforms. (line 62)
5252
4499
* command line: Invoking gss. (line 6)
5253
4500
* Compiling your application: Building the source. (line 6)
5254
* Contributing: Contributing. (line 7)
4501
* Contributing: Contributing. (line 6)
5255
4502
* Debian: Supported Platforms. (line 8)
4503
* Debian <1>: Supported Platforms. (line 19)
5256
4504
* Download: Downloading and Installing.
5257
4505
(line 6)
5258
4506
* FDL, GNU Free Documentation License: GNU Free Documentation License.
5259
4507
(line 6)
5260
4508
* FreeBSD: Supported Platforms. (line 89)
5261
4509
* Future goals: Planned Features. (line 6)
5262
* GPL, GNU General Public License: GNU GPL. (line 6)
5263
* Hacking: Contributing. (line 7)
4510
* Hacking: Contributing. (line 6)
5264
4511
* Header files: Header. (line 6)
5265
4512
* HP-UX: Supported Platforms. (line 70)
5266
4513
* Installation: Downloading and Installing.
5267
4514
(line 6)
5268
* invoking gss: Invoking gss. (line 6)
4515
* invoking 'gss': Invoking gss. (line 6)
5269
4516
* IRIX: Supported Platforms. (line 58)
5270
* License, GNU GPL: GNU GPL. (line 6)
5271
4517
* Mandrake: Supported Platforms. (line 54)
5272
4518
* mechanism status codes: Error Handling. (line 6)
5273
4519
* Memory allocation failure: Out of Memory handling.
5278
4524
* Out of Memory handling: Out of Memory handling.
5279
4525
(line 6)
5280
4526
* RedHat: Supported Platforms. (line 37)
4527
* RedHat <1>: Supported Platforms. (line 42)
4528
* RedHat <2>: Supported Platforms. (line 50)
5281
4529
* RedHat Advanced Server: Supported Platforms. (line 46)
5282
4530
* Reporting Bugs: Bug Reports. (line 6)
5283
4531
* Solaris: Supported Platforms. (line 75)
5301
4549
5302
4550
* gss: Invoking gss. (line 6)
5303
4551
* gss_accept_sec_context: Context-Level Routines.
5304
(line 445)
4552
(line 404)
5305
4553
* gss_acquire_cred: Credential Management.
5306
(line 29)
4554
(line 24)
5307
4555
* gss_add_cred: Credential Management.
5308
(line 134)
4556
(line 127)
5309
4557
* gss_add_oid_set_member: Miscellaneous Routines.
5310
(line 32)
4558
(line 30)
5311
4559
* GSS_CALLING_ERROR: Error Handling. (line 119)
5312
* gss_canonicalize_name: Name Manipulation. (line 222)
5313
* gss_check_version: Extended GSS API. (line 14)
5314
* gss_compare_name: Name Manipulation. (line 112)
4560
* gss_canonicalize_name: Name Manipulation. (line 219)
4561
* gss_check_version: Extended GSS API. (line 13)
4562
* gss_compare_name: Name Manipulation. (line 109)
5315
4563
* gss_context_time: Context-Level Routines.
5316
(line 840)
4564
(line 785)
5317
4565
* gss_create_empty_oid_set: Miscellaneous Routines.
5318
(line 219)
4566
(line 217)
5319
4567
* gss_decapsulate_token: Miscellaneous Routines.
5320
(line 297)
4568
(line 294)
5321
4569
* gss_delete_sec_context: Context-Level Routines.
5322
(line 749)
5323
* gss_display_name: Name Manipulation. (line 71)
4570
(line 693)
4571
* gss_display_name: Name Manipulation. (line 68)
5324
4572
* gss_display_status: Miscellaneous Routines.
5325
(line 64)
5326
* gss_duplicate_name: Name Manipulation. (line 285)
4573
(line 60)
4574
* gss_duplicate_name: Name Manipulation. (line 283)
5327
4575
* gss_encapsulate_token: Miscellaneous Routines.
5328
(line 268)
4576
(line 265)
5329
4577
* GSS_ERROR: Error Handling. (line 119)
5330
* gss_export_name: Name Manipulation. (line 252)
4578
* gss_export_name: Name Manipulation. (line 250)
5331
4579
* gss_export_sec_context: Context-Level Routines.
5332
(line 1086)
4580
(line 1013)
5333
4581
* gss_get_mic: Per-Message Routines.
5334
(line 30)
5335
* gss_import_name: Name Manipulation. (line 30)
4582
(line 27)
4583
* gss_import_name: Name Manipulation. (line 27)
5336
4584
* gss_import_sec_context: Context-Level Routines.
5337
(line 1153)
4585
(line 1079)
5338
4586
* gss_indicate_mechs: Miscellaneous Routines.
5339
(line 152)
4587
(line 150)
5340
4588
* gss_init_sec_context: Context-Level Routines.
5341
(line 38)
4589
(line 30)
5342
4590
* gss_inquire_context: Context-Level Routines.
5343
(line 870)
4591
(line 812)
5344
4592
* gss_inquire_cred: Credential Management.
5345
(line 288)
4593
(line 282)
5346
4594
* gss_inquire_cred_by_mech: Credential Management.
5347
(line 336)
5348
* gss_inquire_mech_for_saslname: SASL GS2 Routines. (line 12)
5349
* gss_inquire_mechs_for_name: Name Manipulation. (line 182)
5350
* gss_inquire_names_for_mech: Name Manipulation. (line 162)
5351
* gss_inquire_saslname_for_mech: SASL GS2 Routines. (line 39)
4595
(line 330)
4596
* gss_inquire_mechs_for_name: Name Manipulation. (line 179)
4597
* gss_inquire_mech_for_saslname: SASL GS2 Routines. (line 9)
4598
* gss_inquire_names_for_mech: Name Manipulation. (line 159)
4599
* gss_inquire_saslname_for_mech: SASL GS2 Routines. (line 35)
5352
4600
* gss_oid_equal: Miscellaneous Routines.
5353
(line 327)
4601
(line 325)
5354
4602
* gss_process_context_token: Context-Level Routines.
5355
(line 801)
4603
(line 745)
5356
4604
* gss_release_buffer: Miscellaneous Routines.
5357
(line 172)
4605
(line 170)
5358
4606
* gss_release_cred: Credential Management.
5359
(line 393)
5360
* gss_release_name: Name Manipulation. (line 142)
4607
(line 389)
4608
* gss_release_name: Name Manipulation. (line 140)
5361
4609
* gss_release_oid_set: Miscellaneous Routines.
5362
(line 196)
4610
(line 194)
5363
4611
* GSS_ROUTINE_ERROR: Error Handling. (line 119)
4612
* GSS_SUPPLEMENTARY_INFO: Error Handling. (line 119)
5364
4613
* GSS_S_...: Error Handling. (line 44)
5365
* GSS_SUPPLEMENTARY_INFO: Error Handling. (line 119)
5366
4614
* gss_test_oid_set_member: Miscellaneous Routines.
5367
(line 242)
4615
(line 239)
5368
4616
* gss_unwrap: Per-Message Routines.
5369
(line 188)
5370
* gss_userok: Extended GSS API. (line 28)
4617
(line 184)
4618
* gss_userok: Extended GSS API. (line 26)
5371
4619
* gss_verify_mic: Per-Message Routines.
5372
(line 76)
4620
(line 72)
5373
4621
* gss_wrap: Per-Message Routines.
5374
(line 132)
4622
(line 128)
5375
4623
* gss_wrap_size_limit: Context-Level Routines.
5376
(line 1025)
4624
(line 951)
5377
4625
5378
4626
5379
4627
5380
4628
Tag Table:
5381
Node: Top713
5382
Node: Introduction2061
5383
Node: Getting Started2939
5384
Node: Features3953
5385
Node: GSS-API Overview4715
5386
Node: Supported Platforms8424
5387
Node: Commercial Support10970
5388
Node: Downloading and Installing11859
5389
Node: Bug Reports12912
5390
Node: Contributing14292
5391
Node: Planned Features16404
5392
Node: Preparation17018
5393
Node: Header17673
5394
Node: Initialization19236
5395
Node: Version Check19802
5396
Node: Building the source20739
5397
Node: Out of Memory handling22594
5398
Node: Standard GSS API22908
5399
Node: Simple Data Types23694
5400
Ref: Object Identifiers26461
5401
Node: Complex Data Types29067
5402
Node: Optional Parameters43220
5403
Node: Error Handling44452
5404
Node: Credential Management53250
5405
Ref: gss_acquire_cred54194
5406
Ref: gss_add_cred59175
4629
Node: Top709
4630
Node: Introduction2055
4631
Node: Getting Started2932
4632
Node: Features3946
4633
Node: GSS-API Overview4707
4634
Node: Supported Platforms8417
4635
Node: Commercial Support10969
4636
Node: Downloading and Installing11856
4637
Node: Bug Reports12909
4638
Node: Contributing14289
4639
Node: Planned Features16400
4640
Node: Preparation17014
4641
Node: Header17669
4642
Node: Initialization19232
4643
Node: Version Check19799
4644
Node: Building the source20736
4645
Node: Out of Memory handling22591
4646
Node: Standard GSS API22905
4647
Node: Simple Data Types23691
4648
Ref: Object Identifiers26458
4649
Node: Complex Data Types29064
4650
Node: Optional Parameters43223
4651
Node: Error Handling44455
4652
Node: Credential Management53254
4653
Ref: gss_acquire_cred54198
4654
Ref: gss_add_cred59182
5407
4655
Ref: gss_inquire_cred67190
5408
4656
Ref: gss_inquire_cred_by_mech69186
5409
Ref: gss_release_cred71820
5410
Node: Context-Level Routines72575
5411
Ref: gss_init_sec_context73920
5412
Ref: gss_accept_sec_context89939
5413
Ref: gss_delete_sec_context103044
5414
Ref: gss_process_context_token105594
5415
Ref: gss_context_time107284
5416
Ref: gss_inquire_context108108
5417
Ref: gss_wrap_size_limit113653
5418
Ref: gss_export_sec_context116330
5419
Ref: gss_import_sec_context119596
5420
Node: Per-Message Routines120709
5421
Ref: gss_get_mic121822
5422
Ref: gss_verify_mic123684
5423
Ref: gss_wrap125824
5424
Ref: gss_unwrap128084
5425
Node: Name Manipulation130635
5426
Ref: gss_import_name131787
5427
Ref: gss_display_name133506
5428
Ref: gss_compare_name135218
5429
Ref: gss_release_name136277
5430
Ref: gss_inquire_names_for_mech136854
5431
Ref: gss_inquire_mechs_for_name137544
5432
Ref: gss_canonicalize_name139287
5433
Ref: gss_export_name140592
5434
Ref: gss_duplicate_name141847
5435
Node: Miscellaneous Routines142699
5436
Ref: gss_add_oid_set_member143976
5437
Ref: gss_display_status145289
5438
Ref: gss_indicate_mechs148972
5439
Ref: gss_release_buffer149617
5440
Ref: gss_release_oid_set150603
5441
Ref: gss_create_empty_oid_set151426
5442
Ref: gss_test_oid_set_member152249
5443
Ref: gss_encapsulate_token153146
5444
Ref: gss_decapsulate_token154280
5445
Ref: gss_oid_equal155438
5446
Node: SASL GS2 Routines155964
5447
Ref: gss_inquire_mech_for_saslname156170
5448
Ref: gss_inquire_saslname_for_mech157071
5449
Node: Extended GSS API158420
5450
Ref: gss_check_version158785
5451
Ref: gss_userok159246
5452
Node: Invoking gss159745
5453
Node: Acknowledgements160742
5454
Node: Criticism of GSS160965
5455
Node: Copying Information167001
5456
Node: GNU Free Documentation License167318
5457
Node: GNU GPL192464
5458
Node: Concept Index230027
5459
Node: API Index233143
4657
Ref: gss_release_cred71818
4658
Node: Context-Level Routines72573
4659
Ref: gss_init_sec_context73918
4660
Ref: gss_accept_sec_context89886
4661
Ref: gss_delete_sec_context102971
4662
Ref: gss_process_context_token105520
4663
Ref: gss_context_time107210
4664
Ref: gss_inquire_context108034
4665
Ref: gss_wrap_size_limit113562
4666
Ref: gss_export_sec_context116240
4667
Ref: gss_import_sec_context119503
4668
Node: Per-Message Routines120616
4669
Ref: gss_get_mic121729
4670
Ref: gss_verify_mic123592
4671
Ref: gss_wrap125732
4672
Ref: gss_unwrap127993
4673
Node: Name Manipulation130544
4674
Ref: gss_import_name131696
4675
Ref: gss_display_name133415
4676
Ref: gss_compare_name135127
4677
Ref: gss_release_name136187
4678
Ref: gss_inquire_names_for_mech136764
4679
Ref: gss_inquire_mechs_for_name137454
4680
Ref: gss_canonicalize_name139197
4681
Ref: gss_export_name140502
4682
Ref: gss_duplicate_name141760
4683
Node: Miscellaneous Routines142613
4684
Ref: gss_add_oid_set_member143890
4685
Ref: gss_display_status145205
4686
Ref: gss_indicate_mechs148890
4687
Ref: gss_release_buffer149535
4688
Ref: gss_release_oid_set150520
4689
Ref: gss_create_empty_oid_set151343
4690
Ref: gss_test_oid_set_member152166
4691
Ref: gss_encapsulate_token153063
4692
Ref: gss_decapsulate_token154197
4693
Ref: gss_oid_equal155355
4694
Node: SASL GS2 Routines155881
4695
Ref: gss_inquire_mech_for_saslname156087
4696
Ref: gss_inquire_saslname_for_mech156988
4697
Node: Extended GSS API158337
4698
Ref: gss_check_version158702
4699
Ref: gss_userok159162
4700
Node: Invoking gss159660
4701
Node: Acknowledgements164618
4702
Node: Criticism of GSS164841
4703
Node: Copying Information170876
4704
Node: GNU Free Documentation License171122
4705
Node: Concept Index196232
4706
Node: API Index199421
5460
4707
5461
4708
End Tag Table
Loggerhead is a web-based interface for Breezy
Version: 2.0.1