File: gss.html

package info (click to toggle)
gss 1.0.3-2
links: PTS, VCS
area: main
in suites: stretch
size: 8,232 kB
ctags: 2,436
sloc: sh: 13,069; ansic: 11,900; python: 2,873; perl: 623; makefile: 172; sed: 16
file content (5470 lines) | stat: -rw-r--r-- 259,914 bytes
parent folder | download | duplicates (4)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is last updated 9 October 2014 for version
1.0.3 of GNU GSS.

Copyright (C) 2003-2014 Simon Josefsson.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled "GNU Free
Documentation License". -->
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Generic Security Service Library</title>

<meta name="description" content="GNU Generic Security Service Library">
<meta name="keywords" content="GNU Generic Security Service Library">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="#Top" rel="start" title="Top">
<link href="#Concept-Index" rel="index" title="Concept Index">
<link href="#SEC_Contents" rel="contents" title="Table of Contents">
<link href="dir.html#Top" rel="up" title="(dir)">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
body {
	margin: 2%;
	padding: 0 5%;
	background: #ffffff;
}
h1,h2,h3,h4,h5 {
    font-weight: bold;
    padding: 5px 5px 5px 5px;
    background-color: #c2e0ff;
    color: #336699;
}
h1 {
    padding: 2em 2em 2em 5%;
    color: white;
    background: #336699;
    text-align: center;
    letter-spacing: 3px;
}
h2 { text-decoration: underline; }
pre {
  margin: 0 5%;
  padding: 0.5em;
}
pre.example {
  border: solid 1px;
  background: #eeeeff;
  padding-bottom: 1em;
}
pre.verbatim {
  border: solid 1px gray;
  background: white;
  padding-bottom: 1em;
}
div.node {
  margin: 0 -5% 0 -2%;
  padding: 0.5em 0.5em;
  margin-top: 0.5em;
  margin-bottom: 0.5em;
  font-weight: bold;
}
dd, li {
  padding-top: 0.1em;
  padding-bottom: 0.1em;
}

-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<h1 class="settitle" align="center">GNU Generic Security Service Library</h1>





<a name="SEC_Contents"></a>
<h2 class="contents-heading">Table of Contents</h2>

<div class="contents">

<ul class="no-bullet">
  <li><a name="toc-Introduction-1" href="#Introduction">1 Introduction</a>
  <ul class="no-bullet">
    <li><a name="toc-Getting-Started-1" href="#Getting-Started">1.1 Getting Started</a></li>
    <li><a name="toc-Features-1" href="#Features">1.2 Features</a></li>
    <li><a name="toc-GSS_002dAPI-Overview-1" href="#GSS_002dAPI-Overview">1.3 GSS-API Overview</a></li>
    <li><a name="toc-Supported-Platforms-1" href="#Supported-Platforms">1.4 Supported Platforms</a></li>
    <li><a name="toc-Commercial-Support-1" href="#Commercial-Support">1.5 Commercial Support</a></li>
    <li><a name="toc-Downloading-and-Installing-1" href="#Downloading-and-Installing">1.6 Downloading and Installing</a></li>
    <li><a name="toc-Bug-Reports-1" href="#Bug-Reports">1.7 Bug Reports</a></li>
    <li><a name="toc-Contributing-1" href="#Contributing">1.8 Contributing</a></li>
    <li><a name="toc-Planned-Features-1" href="#Planned-Features">1.9 Planned Features</a></li>
  </ul></li>
  <li><a name="toc-Preparation-1" href="#Preparation">2 Preparation</a>
  <ul class="no-bullet">
    <li><a name="toc-Header-1" href="#Header">2.1 Header</a></li>
    <li><a name="toc-Initialization-1" href="#Initialization">2.2 Initialization</a></li>
    <li><a name="toc-Version-Check-1" href="#Version-Check">2.3 Version Check</a></li>
    <li><a name="toc-Building-the-source-1" href="#Building-the-source">2.4 Building the source</a></li>
    <li><a name="toc-Out-of-Memory-handling-1" href="#Out-of-Memory-handling">2.5 Out of Memory handling</a></li>
  </ul></li>
  <li><a name="toc-Standard-GSS-API-1" href="#Standard-GSS-API">3 Standard GSS API</a>
  <ul class="no-bullet">
    <li><a name="toc-Simple-Data-Types-1" href="#Simple-Data-Types">3.1 Simple Data Types</a>
    <ul class="no-bullet">
      <li><a name="toc-Integer-types" href="#Integer-types">3.1.1 Integer types</a></li>
      <li><a name="toc-String-and-similar-data" href="#String-and-similar-data">3.1.2 String and similar data</a>
      <ul class="no-bullet">
        <li><a name="toc-Opaque-data-types" href="#Opaque-data-types">3.1.2.1 Opaque data types</a></li>
        <li><a name="toc-Character-strings" href="#Character-strings">3.1.2.2 Character strings</a></li>
      </ul></li>
      <li><a name="toc-Object-Identifiers-1" href="#Object-Identifiers-1">3.1.3 Object Identifiers</a></li>
      <li><a name="toc-Object-Identifier-Sets" href="#Object-Identifier-Sets">3.1.4 Object Identifier Sets</a></li>
    </ul></li>
    <li><a name="toc-Complex-Data-Types-1" href="#Complex-Data-Types">3.2 Complex Data Types</a>
    <ul class="no-bullet">
      <li><a name="toc-Credentials" href="#Credentials">3.2.1 Credentials</a></li>
      <li><a name="toc-Contexts" href="#Contexts">3.2.2 Contexts</a></li>
      <li><a name="toc-Authentication-tokens" href="#Authentication-tokens">3.2.3 Authentication tokens</a></li>
      <li><a name="toc-Interprocess-tokens" href="#Interprocess-tokens">3.2.4 Interprocess tokens</a></li>
      <li><a name="toc-Names" href="#Names">3.2.5 Names</a></li>
      <li><a name="toc-Channel-Bindings" href="#Channel-Bindings">3.2.6 Channel Bindings</a></li>
    </ul></li>
    <li><a name="toc-Optional-Parameters-1" href="#Optional-Parameters">3.3 Optional Parameters</a></li>
    <li><a name="toc-Error-Handling-1" href="#Error-Handling">3.4 Error Handling</a>
    <ul class="no-bullet">
      <li><a name="toc-GSS-status-codes" href="#GSS-status-codes">3.4.1 GSS status codes</a></li>
      <li><a name="toc-Mechanism_002dspecific-status-codes" href="#Mechanism_002dspecific-status-codes">3.4.2 Mechanism-specific status codes</a></li>
    </ul></li>
    <li><a name="toc-Credential-Management-1" href="#Credential-Management">3.5 Credential Management</a></li>
    <li><a name="toc-Context_002dLevel-Routines-1" href="#Context_002dLevel-Routines">3.6 Context-Level Routines</a></li>
    <li><a name="toc-Per_002dMessage-Routines-1" href="#Per_002dMessage-Routines">3.7 Per-Message Routines</a></li>
    <li><a name="toc-Name-Manipulation-1" href="#Name-Manipulation">3.8 Name Manipulation</a></li>
    <li><a name="toc-Miscellaneous-Routines-1" href="#Miscellaneous-Routines">3.9 Miscellaneous Routines</a></li>
    <li><a name="toc-SASL-GS2-Routines-1" href="#SASL-GS2-Routines">3.10 SASL GS2 Routines</a></li>
  </ul></li>
  <li><a name="toc-Extended-GSS-API-1" href="#Extended-GSS-API">4 Extended GSS API</a></li>
  <li><a name="toc-Invoking-gss-1" href="#Invoking-gss">5 Invoking gss</a></li>
  <li><a name="toc-Acknowledgements-1" href="#Acknowledgements">6 Acknowledgements</a></li>
  <li><a name="toc-Criticism-of-GSS-1" href="#Criticism-of-GSS">Appendix A Criticism of GSS</a></li>
  <li><a name="toc-Copying-Information-1" href="#Copying-Information">Appendix B Copying Information</a>
  <ul class="no-bullet">
    <li><a name="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">B.1 GNU Free Documentation License</a></li>
  </ul></li>
  <li><a name="toc-Concept-Index-1" href="#Concept-Index">Concept Index</a></li>
  <li><a name="toc-API-Index-1" href="#API-Index">API Index</a></li>
</ul>
</div>


<a name="Top"></a>
<div class="header">
<p>
Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="GNU-Generic-Security-Service-Library"></a>
<h1 class="top">GNU Generic Security Service Library</h1>
<p>This manual is last updated 9 October 2014 for version
1.0.3 of GNU GSS.
</p>
<p>Copyright &copy; 2003-2014 Simon Josefsson.
</p>
<blockquote>
<p>Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled &ldquo;GNU Free
Documentation License&rdquo;.
</p></blockquote>


<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Introduction" accesskey="1">Introduction</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">How to use this manual.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Preparation" accesskey="2">Preparation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">What you should do before using the library.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Standard-GSS-API" accesskey="3">Standard GSS API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Reference documentation for the Standard API.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Extended-GSS-API" accesskey="4">Extended GSS API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Non-standard functions.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Invoking-gss" accesskey="5">Invoking gss</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Command line interface to the library.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Acknowledgements" accesskey="6">Acknowledgements</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Whom to blame.
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Appendices

</pre></th></tr><tr><td align="left" valign="top">&bull; <a href="#Criticism-of-GSS" accesskey="7">Criticism of GSS</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Why you maybe shouldn&rsquo;t use GSS.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Copying-Information" accesskey="8">Copying Information</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">How you can copy and share GSS.
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Indices

</pre></th></tr><tr><td align="left" valign="top">&bull; <a href="#Concept-Index" accesskey="9">Concept Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Index of concepts and programs.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#API-Index">API Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Index of functions, variables and data types.
</td></tr>
</table>

<hr>
<a name="Introduction"></a>
<div class="header">
<p>
Next: <a href="#Preparation" accesskey="n" rel="next">Preparation</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Introduction-1"></a>
<h2 class="chapter">1 Introduction</h2>

<p>GSS is an implementation of the Generic Security Service Application
Program Interface (GSS-API).  GSS-API is used by network servers to
provide security services, e.g., to authenticate SMTP/IMAP clients
against SMTP/IMAP servers.  GSS consists of a library and a manual.
</p>
<p>GSS is developed for the GNU/Linux system, but runs on over 20
platforms including most major Unix platforms and Windows, and many
kind of devices including iPAQ handhelds and S/390 mainframes.
</p>
<p>GSS is a GNU project, and is licensed under the GNU General Public
License version 3 or later.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Getting-Started" accesskey="1">Getting Started</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Features" accesskey="2">Features</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#GSS_002dAPI-Overview" accesskey="3">GSS-API Overview</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Supported-Platforms" accesskey="4">Supported Platforms</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Commercial-Support" accesskey="5">Commercial Support</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Downloading-and-Installing" accesskey="6">Downloading and Installing</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Bug-Reports" accesskey="7">Bug Reports</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Contributing" accesskey="8">Contributing</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Planned-Features" accesskey="9">Planned Features</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Getting-Started"></a>
<div class="header">
<p>
Next: <a href="#Features" accesskey="n" rel="next">Features</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Getting-Started-1"></a>
<h3 class="section">1.1 Getting Started</h3>

<p>This manual documents the GSS programming interface.  All functions
and data types provided by the library are explained.
</p>
<p>The reader is assumed to possess basic familiarity with GSS-API and
network programming in C or C++.  For general GSS-API information, and
some programming examples, there is a guide available online at
<a href="http://docs.sun.com/db/doc/816-1331">http://docs.sun.com/db/doc/816-1331</a>.
</p>
<p>This manual can be used in several ways.  If read from the beginning
to the end, it gives a good introduction into the library and how it
can be used in an application.  Forward references are included where
necessary.  Later on, the manual can be used as a reference manual to
get just the information needed about any particular interface of the
library.  Experienced programmers might want to start looking at the
examples at the end of the manual, and then only read up those parts
of the interface which are unclear.
</p>
<hr>
<a name="Features"></a>
<div class="header">
<p>
Next: <a href="#GSS_002dAPI-Overview" accesskey="n" rel="next">GSS-API Overview</a>, Previous: <a href="#Getting-Started" accesskey="p" rel="prev">Getting Started</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Features-1"></a>
<h3 class="section">1.2 Features</h3>

<p>GSS might have a couple of advantages over other libraries doing a
similar job.
</p>
<dl compact="compact">
<dt>It&rsquo;s Free Software</dt>
<dd><p>Anybody can use, modify, and redistribute it under the terms of the
GNU General Public License version 3 or later.
</p>
</dd>
<dt>It&rsquo;s thread-safe</dt>
<dd><p>No global variables are used and multiple library handles and session
handles may be used in parallell.
</p>
</dd>
<dt>It&rsquo;s internationalized</dt>
<dd><p>It handles non-ASCII names and user visible strings used in the
library (e.g., error messages) can be translated into the users&rsquo;
language.
</p>
</dd>
<dt>It&rsquo;s portable</dt>
<dd><p>It should work on all Unix like operating systems, including Windows.
</p>
</dd>
</dl>

<hr>
<a name="GSS_002dAPI-Overview"></a>
<div class="header">
<p>
Next: <a href="#Supported-Platforms" accesskey="n" rel="next">Supported Platforms</a>, Previous: <a href="#Features" accesskey="p" rel="prev">Features</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="GSS_002dAPI-Overview-1"></a>
<h3 class="section">1.3 GSS-API Overview</h3>

<p>This section describes GSS-API from a protocol point of view.
</p>
<p>The Generic Security Service Application Programming Interface
provides security services to calling applications.  It allows a
communicating application to authenticate the user associated with
another application, to delegate rights to another application, and to
apply security services such as confidentiality and integrity on a
per-message basis.
</p>
<p>There are four stages to using the GSS-API:
</p>
<ol>
<li> The application acquires a set of credentials with which it may prove
its identity to other processes. The application&rsquo;s credentials vouch
for its global identity, which may or may not be related to any local
username under which it may be running.

</li><li> A pair of communicating applications establish a joint security
context using their credentials.  The security context is a pair of
GSS-API data structures that contain shared state information, which
is required in order that per-message security services may be
provided.  Examples of state that might be shared between applications
as part of a security context are cryptographic keys, and message
sequence numbers.  As part of the establishment of a security context,
the context initiator is authenticated to the responder, and may
require that the responder is authenticated in turn.  The initiator
may optionally give the responder the right to initiate further
security contexts, acting as an agent or delegate of the initiator.
This transfer of rights is termed delegation, and is achieved by
creating a set of credentials, similar to those used by the initiating
application, but which may be used by the responder.

<p>To establish and maintain the shared information that makes up the
security context, certain GSS-API calls will return a token data
structure, which is an opaque data type that may contain
cryptographically protected data.  The caller of such a GSS-API
routine is responsible for transferring the token to the peer
application, encapsulated if necessary in an application- application
protocol.  On receipt of such a token, the peer application should
pass it to a corresponding GSS-API routine which will decode the token
and extract the information, updating the security context state
information accordingly.
</p>
</li><li> Per-message services are invoked to apply either: integrity and data
origin authentication, or confidentiality, integrity and data origin
authentication to application data, which are treated by GSS-API as
arbitrary octet-strings.  An application transmitting a message that
it wishes to protect will call the appropriate GSS-API routine
(gss_get_mic or gss_wrap) to apply protection, specifying the
appropriate security context, and send the resulting token to the
receiving application.  The receiver will pass the received token
(and, in the case of data protected by gss_get_mic, the accompanying
message-data) to the corresponding decoding routine (gss_verify_mic or
gss_unwrap) to remove the protection and validate the data.

</li><li> At the completion of a communications session (which may extend across
several transport connections), each application calls a GSS-API
routine to delete the security context.  Multiple contexts may also be
used (either successively or simultaneously) within a single
communications association, at the option of the applications.
</li></ol>

<hr>
<a name="Supported-Platforms"></a>
<div class="header">
<p>
Next: <a href="#Commercial-Support" accesskey="n" rel="next">Commercial Support</a>, Previous: <a href="#GSS_002dAPI-Overview" accesskey="p" rel="prev">GSS-API Overview</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Supported-Platforms-1"></a>
<h3 class="section">1.4 Supported Platforms</h3>

<p>GSS has at some point in time been tested on the following platforms.
</p>
<ol>
<li> Debian GNU/Linux 3.0 (Woody)
<a name="index-Debian"></a>

<p>GCC 2.95.4 and GNU Make. This is the main development platform.
<code>alphaev67-unknown-linux-gnu</code>, <code>alphaev6-unknown-linux-gnu</code>,
<code>arm-unknown-linux-gnu</code>, <code>hppa-unknown-linux-gnu</code>,
<code>hppa64-unknown-linux-gnu</code>, <code>i686-pc-linux-gnu</code>,
<code>ia64-unknown-linux-gnu</code>, <code>m68k-unknown-linux-gnu</code>,
<code>mips-unknown-linux-gnu</code>, <code>mipsel-unknown-linux-gnu</code>,
<code>powerpc-unknown-linux-gnu</code>, <code>s390-ibm-linux-gnu</code>,
<code>sparc-unknown-linux-gnu</code>.
</p>
</li><li> Debian GNU/Linux 2.1
<a name="index-Debian-1"></a>

<p>GCC 2.95.1 and GNU Make. <code>armv4l-unknown-linux-gnu</code>.
</p>
</li><li> Tru64 UNIX
<a name="index-Tru64"></a>

<p>Tru64 UNIX C compiler and Tru64 Make. <code>alphaev67-dec-osf5.1</code>,
<code>alphaev68-dec-osf5.1</code>.
</p>
</li><li> SuSE Linux 7.1
<a name="index-SuSE"></a>

<p>GCC 2.96 and GNU Make. <code>alphaev6-unknown-linux-gnu</code>,
<code>alphaev67-unknown-linux-gnu</code>.
</p>
</li><li> SuSE Linux 7.2a
<a name="index-SuSE-Linux"></a>

<p>GCC 3.0 and GNU Make. <code>ia64-unknown-linux-gnu</code>.
</p>
</li><li> RedHat Linux 7.2
<a name="index-RedHat"></a>

<p>GCC 2.96 and GNU Make. <code>alphaev6-unknown-linux-gnu</code>,
<code>alphaev67-unknown-linux-gnu</code>, <code>ia64-unknown-linux-gnu</code>.
</p>
</li><li> RedHat Linux 8.0
<a name="index-RedHat-1"></a>

<p>GCC 3.2 and GNU Make. <code>i686-pc-linux-gnu</code>.
</p>
</li><li> RedHat Advanced Server 2.1
<a name="index-RedHat-Advanced-Server"></a>

<p>GCC 2.96 and GNU Make. <code>i686-pc-linux-gnu</code>.
</p>
</li><li> Slackware Linux 8.0.01
<a name="index-RedHat-2"></a>

<p>GCC 2.95.3 and GNU Make. <code>i686-pc-linux-gnu</code>.
</p>
</li><li> Mandrake Linux 9.0
<a name="index-Mandrake"></a>

<p>GCC 3.2 and GNU Make. <code>i686-pc-linux-gnu</code>.
</p>
</li><li> IRIX 6.5
<a name="index-IRIX"></a>

<p>MIPS C compiler, IRIX Make. <code>mips-sgi-irix6.5</code>.
</p>
</li><li> AIX 4.3.2
<a name="index-AIX"></a>

<p>IBM C for AIX compiler, AIX Make.  <code>rs6000-ibm-aix4.3.2.0</code>.
</p>
</li><li> Microsoft Windows 2000 (Cygwin)
<a name="index-Windows"></a>

<p>GCC 3.2, GNU make. <code>i686-pc-cygwin</code>.
</p>
</li><li> HP-UX 11
<a name="index-HP_002dUX"></a>

<p>HP-UX C compiler and HP Make. <code>ia64-hp-hpux11.22</code>,
<code>hppa2.0w-hp-hpux11.11</code>.
</p>
</li><li> SUN Solaris 2.8
<a name="index-Solaris"></a>

<p>Sun WorkShop Compiler C 6.0 and SUN Make. <code>sparc-sun-solaris2.8</code>.
</p>
</li><li> NetBSD 1.6
<a name="index-NetBSD"></a>

<p>GCC 2.95.3 and GNU Make. <code>alpha-unknown-netbsd1.6</code>,
<code>i386-unknown-netbsdelf1.6</code>.
</p>
</li><li> OpenBSD 3.1 and 3.2
<a name="index-OpenBSD"></a>

<p>GCC 2.95.3 and GNU Make. <code>alpha-unknown-openbsd3.1</code>,
<code>i386-unknown-openbsd3.1</code>.
</p>
</li><li> FreeBSD 4.7
<a name="index-FreeBSD"></a>

<p>GCC 2.95.4 and GNU Make. <code>alpha-unknown-freebsd4.7</code>,
<code>i386-unknown-freebsd4.7</code>.
</p>
</li><li> Cross compiled to uClinux/uClibc on Motorola Coldfire.
<a name="index-Motorola-Coldfire"></a>
<a name="index-uClinux"></a>
<a name="index-uClibc"></a>

<p>GCC 3.4 and GNU Make <code>m68k-uclinux-elf</code>.
</p>
</li></ol>

<p>If you use GSS on, or port GSS to, a new platform please report it to
the author.
</p>
<hr>
<a name="Commercial-Support"></a>
<div class="header">
<p>
Next: <a href="#Downloading-and-Installing" accesskey="n" rel="next">Downloading and Installing</a>, Previous: <a href="#Supported-Platforms" accesskey="p" rel="prev">Supported Platforms</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Commercial-Support-1"></a>
<h3 class="section">1.5 Commercial Support</h3>

<p>Commercial support is available for users of GNU GSS.  The kind of
support that can be purchased may include:
</p>
<ul>
<li> Implement new features.
Such as a new GSS-API mechanism.

</li><li> Port GSS to new platforms.
This could include porting to an embedded platforms that may need
memory or size optimization.

</li><li> Integrating GSS as a security environment in your existing project.

</li><li> System design of components related to GSS-API.

</li></ul>

<p>If you are interested, please write to:
</p>
<pre class="verbatim">Simon Josefsson Datakonsult AB
Hagagatan 24
113 47 Stockholm
Sweden

E-mail: simon@josefsson.org
</pre>
<p>If your company provides support related to GNU GSS and would like to
be mentioned here, contact the author (see <a href="#Bug-Reports">Bug Reports</a>).
</p>
<hr>
<a name="Downloading-and-Installing"></a>
<div class="header">
<p>
Next: <a href="#Bug-Reports" accesskey="n" rel="next">Bug Reports</a>, Previous: <a href="#Commercial-Support" accesskey="p" rel="prev">Commercial Support</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Downloading-and-Installing-1"></a>
<h3 class="section">1.6 Downloading and Installing</h3>
<a name="index-Installation"></a>
<a name="index-Download"></a>

<p>The package can be downloaded from several places, including:
</p>
<p><a href="ftp://ftp.gnu.org/gnu/gss/">ftp://ftp.gnu.org/gnu/gss/</a>
</p>
<p>The latest version is stored in a file, e.g.,
&lsquo;<samp>gss-1.0.3.tar.gz</samp>&rsquo; where the &lsquo;<samp>1.0.3</samp>&rsquo;
indicate the highest version number.
</p>
<p>The package is then extracted, configured and built like many other
packages that use Autoconf.  For detailed information on configuring
and building it, refer to the <samp>INSTALL</samp> file that is part of the
distribution archive.
</p>
<p>Here is an example terminal session that downloads, configures, builds
and installs the package.  You will need a few basic tools, such as
&lsquo;<samp>sh</samp>&rsquo;, &lsquo;<samp>make</samp>&rsquo; and &lsquo;<samp>cc</samp>&rsquo;.
</p>
<div class="example">
<pre class="example">$ wget -q ftp://ftp.gnu.org/gnu/gss/gss-1.0.3.tar.gz
$ tar xfz gss-1.0.3.tar.gz
$ cd gss-1.0.3/
$ ./configure
...
$ make
...
$ make install
...
</pre></div>

<p>After that GSS should be properly installed and ready for use.
</p>
<hr>
<a name="Bug-Reports"></a>
<div class="header">
<p>
Next: <a href="#Contributing" accesskey="n" rel="next">Contributing</a>, Previous: <a href="#Downloading-and-Installing" accesskey="p" rel="prev">Downloading and Installing</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Bug-Reports-1"></a>
<h3 class="section">1.7 Bug Reports</h3>
<a name="index-Reporting-Bugs"></a>

<p>If you think you have found a bug in GSS, please investigate it and
report it.
</p>
<ul>
<li> Please make sure that the bug is really in GSS, and
preferably also check that it hasn&rsquo;t already been fixed in the latest
version.

</li><li> You have to send us a test case that makes it possible for us to
reproduce the bug.

</li><li> You also have to explain what is wrong; if you get a crash, or
if the results printed are not good and in that case, in what way.
Make sure that the bug report includes all information you would need
to fix this kind of bug for someone else.

</li></ul>

<p>Please make an effort to produce a self-contained report, with
something definite that can be tested or debugged.  Vague queries or
piecemeal messages are difficult to act on and don&rsquo;t help the
development effort.
</p>
<p>If your bug report is good, we will do our best to help you to get a
corrected version of the software; if the bug report is poor, we won&rsquo;t
do anything about it (apart from asking you to send better bug
reports).
</p>
<p>If you think something in this manual is unclear, or downright
incorrect, or if the language needs to be improved, please also send a
note.
</p>
<p>Send your bug report to:
</p>
<div align="center">&lsquo;<samp>bug-gss@gnu.org</samp>&rsquo;
</div>
<hr>
<a name="Contributing"></a>
<div class="header">
<p>
Next: <a href="#Planned-Features" accesskey="n" rel="next">Planned Features</a>, Previous: <a href="#Bug-Reports" accesskey="p" rel="prev">Bug Reports</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Contributing-1"></a>
<h3 class="section">1.8 Contributing</h3>
<a name="index-Contributing"></a>
<a name="index-Hacking"></a>

<p>If you want to submit a patch for inclusion &ndash; from solve a typo you
discovered, up to adding support for a new feature &ndash; you should
submit it as a bug report (see <a href="#Bug-Reports">Bug Reports</a>).  There are some
things that you can do to increase the chances for it to be included
in the official package.
</p>
<p>Unless your patch is very small (say, under 10 lines) we require that
you assign the copyright of your work to the Free Software Foundation.
This is to protect the freedom of the project.  If you have not
already signed papers, we will send you the necessary information when
you submit your contribution.
</p>
<p>For contributions that doesn&rsquo;t consist of actual programming code, the
only guidelines are common sense.  Use it.
</p>
<p>For code contributions, a number of style guides will help you:
</p>
<ul>
<li> Coding Style.
Follow the GNU Standards document (see <a href="http://www.gnu.org/prep/standards/standards.html#Top">(standards)GNU Coding Standards</a>).

<p>If you normally code using another coding standard, there is no
problem, but you should use &lsquo;<samp>indent</samp>&rsquo; to reformat the code
(see <a href="indent.html#Top">(indent)GNU Indent</a>) before submitting your work.
</p>
</li><li> Use the unified diff format &lsquo;<samp>diff -u</samp>&rsquo;.

</li><li> Return errors.
No reason whatsoever should abort the execution of the library.  Even
memory allocation errors, e.g. when malloc return NULL, should work
although result in an error code.

</li><li> Design with thread safety in mind.
Don&rsquo;t use global variables.  Don&rsquo;t even write to per-handle global
variables unless the documented behaviour of the function you write is
to write to the per-handle global variable.

</li><li> Avoid using the C math library.
It causes problems for embedded implementations, and in most
situations it is very easy to avoid using it.

</li><li> Document your functions.
Use comments before each function headers, that, if properly
formatted, are extracted into Texinfo manuals and GTK-DOC web pages.

</li><li> Supply a ChangeLog and NEWS entries, where appropriate.

</li></ul>

<hr>
<a name="Planned-Features"></a>
<div class="header">
<p>
Previous: <a href="#Contributing" accesskey="p" rel="prev">Contributing</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Planned-Features-1"></a>
<h3 class="section">1.9 Planned Features</h3>
<a name="index-Todo-list"></a>
<a name="index-Future-goals"></a>

<p>This is also known as the &ldquo;todo list&rdquo;.  If you like to start working
on anything, please let me know so work duplication can be avoided.
</p>
<ul>
<li> Support non-blocking mode.
This would be an API extension.  It could work by forking a process
and interface to it, or by using a user-specific daemon.  E.g., h =
START(accept_sec_context(...)), FINISHED(h), ret = FINISH(h), ABORT(h).

</li><li> Support loadable modules via dlopen, a&rsquo;la Solaris GSS.

</li><li> Port to Cyclone? CCured?

</li></ul>


<hr>
<a name="Preparation"></a>
<div class="header">
<p>
Next: <a href="#Standard-GSS-API" accesskey="n" rel="next">Standard GSS API</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Preparation-1"></a>
<h2 class="chapter">2 Preparation</h2>

<p>To use GSS, you have to perform some changes to your sources and the
build system.  The necessary changes are small and explained in the
following sections.  At the end of this chapter, it is described how
the library is initialized, and how the requirements of the library
are verified.
</p>
<p>A faster way to find out how to adapt your application for use with
GSS may be to look at the examples at the end of this manual.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Header" accesskey="1">Header</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Initialization" accesskey="2">Initialization</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Version-Check" accesskey="3">Version Check</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Building-the-source" accesskey="4">Building the source</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Out-of-Memory-handling" accesskey="5">Out of Memory handling</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Header"></a>
<div class="header">
<p>
Next: <a href="#Initialization" accesskey="n" rel="next">Initialization</a>, Up: <a href="#Preparation" accesskey="u" rel="up">Preparation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Header-1"></a>
<h3 class="section">2.1 Header</h3>

<a name="index-Header-files"></a>
<p>All standard interfaces (data types and functions) of the official GSS
API are defined in the header file <samp>gss/api.h</samp>.  The file is
taken verbatim from the RFC (after correcting a few typos) where it is
known as <samp>gssapi.h</samp>.  However, to be able to co-exist gracefully
with other GSS-API implementation, the name <samp>gssapi.h</samp> was
changed.
</p>
<p>The header file <samp>gss.h</samp> includes <samp>gss/api.h</samp>, and declares a
few non-standard extensions (by including <samp>gss/ext.h</samp>), takes
care of including header files related to all supported mechanisms
(e.g., <samp>gss/krb5.h</samp>) and finally adds C++ namespace protection of
all definitions.  Therefore, including <samp>gss.h</samp> in your project is
recommended over <samp>gss/api.h</samp>.  If using <samp>gss.h</samp> instead of
<samp>gss/api.h</samp> causes problems, it should be regarded a bug.
</p>
<p>You must include either file in all programs using the library, either
directly or through some other header file, like this:
</p>
<div class="example">
<pre class="example">#include &lt;gss.h&gt;
</pre></div>

<p>The name space of GSS is <code>gss_*</code> for function names, <code>gss_*</code>
for data types and <code>GSS_*</code> for other symbols.  In addition the
same name prefixes with one prepended underscore are reserved for
internal use and should never be used by an application.
</p>
<p>Each supported GSS mechanism may want to expose mechanism specific
functionality, and can do so through one or more header files under
the <samp>gss/</samp> directory.  The Kerberos 5 mechanism uses the file
<samp>gss/krb5.h</samp>, but again, it is included (with C++ namespace
fixes) from <samp>gss.h</samp>.
</p>
<hr>
<a name="Initialization"></a>
<div class="header">
<p>
Next: <a href="#Version-Check" accesskey="n" rel="next">Version Check</a>, Previous: <a href="#Header" accesskey="p" rel="prev">Header</a>, Up: <a href="#Preparation" accesskey="u" rel="up">Preparation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Initialization-1"></a>
<h3 class="section">2.2 Initialization</h3>

<p>GSS does not need to be initialized before it can be used.
</p>
<p>In order to take advantage of the internationalisation features in
GSS, e.g. translated error messages, the application must set the
current locale using <code>setlocale()</code> before calling, e.g.,
<code>gss_display_status()</code>.  This is typically done in <code>main()</code>
as in the following example.
</p>
<div class="example">
<pre class="example">#include &lt;gss.h&gt;
#include &lt;locale.h&gt;
...
  setlocale (LC_ALL, &quot;&quot;);
</pre></div>

<hr>
<a name="Version-Check"></a>
<div class="header">
<p>
Next: <a href="#Building-the-source" accesskey="n" rel="next">Building the source</a>, Previous: <a href="#Initialization" accesskey="p" rel="prev">Initialization</a>, Up: <a href="#Preparation" accesskey="u" rel="up">Preparation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Version-Check-1"></a>
<h3 class="section">2.3 Version Check</h3>

<p>It is often desirable to check that the version of GSS used is indeed
one which fits all requirements.  Even with binary compatibility new
features may have been introduced but due to problem with the dynamic
linker an old version is actually used.  So you may want to check that
the version is okay right after program startup.  The function is
called <code>gss_check_version()</code> and is described formally in
See <a href="#Extended-GSS-API">Extended GSS API</a>.
</p>
<p>The normal way to use the function is to put something similar to the
following early in your <code>main()</code>:
</p>
<div class="example">
<pre class="example">#include &lt;gss.h&gt;
...
  if (!gss_check_version (GSS_VERSION))
    {
      printf (&quot;gss_check_version() failed:\n&quot;
              &quot;Header file incompatible with shared library.\n&quot;);
      exit(EXIT_FAILURE);
    }
</pre></div>

<hr>
<a name="Building-the-source"></a>
<div class="header">
<p>
Next: <a href="#Out-of-Memory-handling" accesskey="n" rel="next">Out of Memory handling</a>, Previous: <a href="#Version-Check" accesskey="p" rel="prev">Version Check</a>, Up: <a href="#Preparation" accesskey="u" rel="up">Preparation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Building-the-source-1"></a>
<h3 class="section">2.4 Building the source</h3>
<a name="index-Compiling-your-application"></a>

<p>If you want to compile a source file that includes the <samp>gss.h</samp> header
file, you must make sure that the compiler can find it in the
directory hierarchy.  This is accomplished by adding the path to the
directory in which the header file is located to the compilers include
file search path (via the <samp>-I</samp> option).
</p>
<p>However, the path to the include file is determined at the time the
source is configured.  To solve this problem, GSS uses the external
package <code>pkg-config</code> that knows the path to the include file
and other configuration options.  The options that need to be added to
the compiler invocation at compile time are output by the
<samp>--cflags</samp> option to <code>pkg-config gss</code>.  The following
example shows how it can be used at the command line:
</p>
<div class="example">
<pre class="example">gcc -c foo.c `pkg-config gss --cflags`
</pre></div>

<p>Adding the output of &lsquo;<samp>pkg-config gss --cflags</samp>&rsquo; to the compilers
command line will ensure that the compiler can find the <samp>gss.h</samp> header
file.
</p>
<p>A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files.  For this to work,
the path to the library files has to be added to the library search
path (via the <samp>-L</samp> option).  For this, the option
<samp>--libs</samp> to <code>pkg-config gss</code> can be used.  For
convenience, this option also outputs all other options that are
required to link the program with the GSS libarary (for instance, the
&lsquo;<samp>-lshishi</samp>&rsquo; option).  The example shows how to link <samp>foo.o</samp>
with GSS into a program <code>foo</code>.
</p>
<div class="example">
<pre class="example">gcc -o foo foo.o `pkg-config gss --libs`
</pre></div>

<p>Of course you can also combine both examples to a single command by
specifying both options to <code>pkg-config</code>:
</p>
<div class="example">
<pre class="example">gcc -o foo foo.c `pkg-config gss --cflags --libs`
</pre></div>

<hr>
<a name="Out-of-Memory-handling"></a>
<div class="header">
<p>
Previous: <a href="#Building-the-source" accesskey="p" rel="prev">Building the source</a>, Up: <a href="#Preparation" accesskey="u" rel="up">Preparation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Out-of-Memory-handling-1"></a>
<h3 class="section">2.5 Out of Memory handling</h3>

<a name="index-Out-of-Memory-handling"></a>
<a name="index-Memory-allocation-failure"></a>
<p>The GSS API does not have a standard error code for the out of memory
error condition.  This library will return <code>GSS_S_FAILURE</code> and
set <code>minor_status</code> to ENOMEM.
</p>
<hr>
<a name="Standard-GSS-API"></a>
<div class="header">
<p>
Next: <a href="#Extended-GSS-API" accesskey="n" rel="next">Extended GSS API</a>, Previous: <a href="#Preparation" accesskey="p" rel="prev">Preparation</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Standard-GSS-API-1"></a>
<h2 class="chapter">3 Standard GSS API</h2>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Simple-Data-Types" accesskey="1">Simple Data Types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">About integers, strings, OIDs, and OID sets.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Complex-Data-Types" accesskey="2">Complex Data Types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">About credentials, contexts, names, etc.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Optional-Parameters" accesskey="3">Optional Parameters</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">What value to use when you don&rsquo;t want one.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Error-Handling" accesskey="4">Error Handling</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">How errors in GSS are reported and handled.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Credential-Management" accesskey="5">Credential Management</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Standard GSS credential functions.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Context_002dLevel-Routines" accesskey="6">Context-Level Routines</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Standard GSS context functions.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Per_002dMessage-Routines" accesskey="7">Per-Message Routines</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Standard GSS per-message functions.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Name-Manipulation" accesskey="8">Name Manipulation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Standard GSS name manipulation functions.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Miscellaneous-Routines" accesskey="9">Miscellaneous Routines</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Standard miscellaneous functions.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#SASL-GS2-Routines">SASL GS2 Routines</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Standard SASL GS2 related functions.
</td></tr>
</table>

<hr>
<a name="Simple-Data-Types"></a>
<div class="header">
<p>
Next: <a href="#Complex-Data-Types" accesskey="n" rel="next">Complex Data Types</a>, Up: <a href="#Standard-GSS-API" accesskey="u" rel="up">Standard GSS API</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Simple-Data-Types-1"></a>
<h3 class="section">3.1 Simple Data Types</h3>

<p>The following conventions are used by the GSS-API C-language bindings:
</p>
<a name="Integer-types"></a>
<h4 class="subsection">3.1.1 Integer types</h4>

<p>GSS-API uses the following integer data type:
</p>
<pre class="verbatim">   OM_uint32    32-bit unsigned integer
</pre>
<a name="String-and-similar-data"></a>
<h4 class="subsection">3.1.2 String and similar data</h4>

<p>Many of the GSS-API routines take arguments and return values that
describe contiguous octet-strings.  All such data is passed between
the GSS-API and the caller using the <code>gss_buffer_t</code> data type.
This data type is a pointer to a buffer descriptor, which consists of
a length field that contains the total number of bytes in the datum,
and a value field which contains a pointer to the actual datum:
</p>
<pre class="verbatim">   typedef struct gss_buffer_desc_struct {
      size_t    length;
      void      *value;
   } gss_buffer_desc, *gss_buffer_t;
</pre>
<p>Storage for data returned to the application by a GSS-API routine
using the <code>gss_buffer_t</code> conventions is allocated by the GSS-API
routine.  The application may free this storage by invoking the
<code>gss_release_buffer</code> routine.  Allocation of the
<code>gss_buffer_desc</code> object is always the responsibility of the
application; unused <code>gss_buffer_desc</code> objects may be initialized
to the value <code>GSS_C_EMPTY_BUFFER</code>.
</p>
<a name="Opaque-data-types"></a>
<h4 class="subsubsection">3.1.2.1 Opaque data types</h4>

<p>Certain multiple-word data items are considered opaque data types at
the GSS-API, because their internal structure has no significance
either to the GSS-API or to the caller.  Examples of such opaque data
types are the input_token parameter to <code>gss_init_sec_context</code>
(which is opaque to the caller), and the input_message parameter to
<code>gss_wrap</code> (which is opaque to the GSS-API).  Opaque data is
passed between the GSS-API and the application using the
<code>gss_buffer_t</code> datatype.
</p>
<a name="Character-strings"></a>
<h4 class="subsubsection">3.1.2.2 Character strings</h4>

<p>Certain multiple-word data items may be regarded as simple ISO Latin-1
character strings.  Examples are the printable strings passed to
<code>gss_import_name</code> via the input_name_buffer parameter. Some
GSS-API routines also return character strings.  All such character
strings are passed between the application and the GSS-API
implementation using the <code>gss_buffer_t</code> datatype, which is a
pointer to a <code>gss_buffer_desc</code> object.
</p>
<p>When a <code>gss_buffer_desc</code> object describes a printable string, the
length field of the <code>gss_buffer_desc</code> should only count printable
characters within the string.  In particular, a trailing NUL character
should NOT be included in the length count, nor should either the
GSS-API implementation or the application assume the presence of an
uncounted trailing NUL.
</p>
<a name="Object-Identifiers-1"></a>
<h4 class="subsection">3.1.3 Object Identifiers</h4>
<a name="Object-Identifiers"></a>
<p>Certain GSS-API procedures take parameters of the type <code>gss_OID</code>,
or Object identifier.  This is a type containing ISO-defined tree-
structured values, and is used by the GSS-API caller to select an
underlying security mechanism and to specify namespaces.  A value of
type <code>gss_OID</code> has the following structure:
</p>
<pre class="verbatim">   typedef struct gss_OID_desc_struct {
      OM_uint32   length;
      void        *elements;
   } gss_OID_desc, *gss_OID;
</pre>
<p>The elements field of this structure points to the first byte of an
octet string containing the ASN.1 BER encoding of the value portion of
the normal BER TLV encoding of the <code>gss_OID</code>.  The length field
contains the number of bytes in this value.  For example, the
<code>gss_OID</code> value corresponding to <code>iso(1)
identified-organization(3) icd-ecma(12) member-company(2) dec(1011)
cryptoAlgorithms(7) DASS(5)</code>, meaning the DASS X.509 authentication
mechanism, has a length field of 7 and an elements field pointing to
seven octets containing the following octal values:
53,14,2,207,163,7,5. GSS-API implementations should provide constant
<code>gss_OID</code> values to allow applications to request any supported
mechanism, although applications are encouraged on portability grounds
to accept the default mechanism.  <code>gss_OID</code> values should also be
provided to allow applications to specify particular name types (see
section 3.10).  Applications should treat <code>gss_OID_desc</code> values
returned by GSS-API routines as read-only.  In particular, the
application should not attempt to deallocate them with free().
</p>
<a name="Object-Identifier-Sets"></a>
<h4 class="subsection">3.1.4 Object Identifier Sets</h4>

<p>Certain GSS-API procedures take parameters of the type
<code>gss_OID_set</code>.  This type represents one or more object
identifiers (see <a href="#Object-Identifiers">Object Identifiers</a>).  A <code>gss_OID_set</code> object
has the following structure:
</p>
<pre class="verbatim">   typedef struct gss_OID_set_desc_struct {
      size_t    count;
      gss_OID   elements;
   } gss_OID_set_desc, *gss_OID_set;
</pre>
<p>The count field contains the number of OIDs within the set.  The
elements field is a pointer to an array of <code>gss_OID_desc</code>
objects, each of which describes a single OID.  <code>gss_OID_set</code>
values are used to name the available mechanisms supported by the
GSS-API, to request the use of specific mechanisms, and to indicate
which mechanisms a given credential supports.
</p>
<p>All OID sets returned to the application by GSS-API are dynamic
objects (the <code>gss_OID_set_desc</code>, the &quot;elements&quot; array of the set,
and the &quot;elements&quot; array of each member OID are all dynamically
allocated), and this storage must be deallocated by the application
using the <code>gss_release_oid_set</code> routine.
</p>
<hr>
<a name="Complex-Data-Types"></a>
<div class="header">
<p>
Next: <a href="#Optional-Parameters" accesskey="n" rel="next">Optional Parameters</a>, Previous: <a href="#Simple-Data-Types" accesskey="p" rel="prev">Simple Data Types</a>, Up: <a href="#Standard-GSS-API" accesskey="u" rel="up">Standard GSS API</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Complex-Data-Types-1"></a>
<h3 class="section">3.2 Complex Data Types</h3>

<a name="Credentials"></a>
<h4 class="subsection">3.2.1 Credentials</h4>

<p>A credential handle is a caller-opaque atomic datum that identifies a
GSS-API credential data structure.  It is represented by the caller-
opaque type <code>gss_cred_id_t</code>.
</p>
<p>GSS-API credentials can contain mechanism-specific principal
authentication data for multiple mechanisms.  A GSS-API credential is
composed of a set of credential-elements, each of which is applicable
to a single mechanism.  A credential may contain at most one
credential-element for each supported mechanism. A credential-element
identifies the data needed by a single mechanism to authenticate a
single principal, and conceptually contains two credential-references
that describe the actual mechanism-specific authentication data, one
to be used by GSS-API for initiating contexts, and one to be used for
accepting contexts.  For mechanisms that do not distinguish between
acceptor and initiator credentials, both references would point to the
same underlying mechanism-specific authentication data.
</p>
<p>Credentials describe a set of mechanism-specific principals, and give
their holder the ability to act as any of those principals. All
principal identities asserted by a single GSS-API credential should
belong to the same entity, although enforcement of this property is an
implementation-specific matter.  The GSS-API does not make the actual
credentials available to applications; instead a credential handle is
used to identify a particular credential, held internally by GSS-API.
The combination of GSS-API credential handle and mechanism identifies
the principal whose identity will be asserted by the credential when
used with that mechanism.
</p>
<p>The <code>gss_init_sec_context</code> and <code>gss_accept_sec_context</code>
routines allow the value <code>GSS_C_NO_CREDENTIAL</code> to be specified as
their credential handle parameter.  This special credential-handle
indicates a desire by the application to act as a default principal.
</p>
<a name="Contexts"></a>
<h4 class="subsection">3.2.2 Contexts</h4>

<p>The <code>gss_ctx_id_t</code> data type contains a caller-opaque atomic
value that identifies one end of a GSS-API security context.
</p>
<p>The security context holds state information about each end of a peer
communication, including cryptographic state information.
</p>
<a name="Authentication-tokens"></a>
<h4 class="subsection">3.2.3 Authentication tokens</h4>

<p>A token is a caller-opaque type that GSS-API uses to maintain
synchronization between the context data structures at each end of a
GSS-API security context.  The token is a cryptographically protected
octet-string, generated by the underlying mechanism at one end of a
GSS-API security context for use by the peer mechanism at the other
end.  Encapsulation (if required) and transfer of the token are the
responsibility of the peer applications.  A token is passed between
the GSS-API and the application using the <code>gss_buffer_t</code>
conventions.
</p>
<a name="Interprocess-tokens"></a>
<h4 class="subsection">3.2.4 Interprocess tokens</h4>

<p>Certain GSS-API routines are intended to transfer data between
processes in multi-process programs.  These routines use a
caller-opaque octet-string, generated by the GSS-API in one process
for use by the GSS-API in another process.  The calling application is
responsible for transferring such tokens between processes in an
OS-specific manner.  Note that, while GSS-API implementors are
encouraged to avoid placing sensitive information within interprocess
tokens, or to cryptographically protect them, many implementations
will be unable to avoid placing key material or other sensitive data
within them.  It is the application&rsquo;s responsibility to ensure that
interprocess tokens are protected in transit, and transferred only to
processes that are trustworthy. An interprocess token is passed
between the GSS-API and the application using the <code>gss_buffer_t</code>
conventions.
</p>
<a name="Names"></a>
<h4 class="subsection">3.2.5 Names</h4>

<p>A name is used to identify a person or entity.  GSS-API authenticates
the relationship between a name and the entity claiming the name.
</p>
<p>Since different authentication mechanisms may employ different
namespaces for identifying their principals, GSSAPI&rsquo;s naming support
is necessarily complex in multi-mechanism environments (or even in
some single-mechanism environments where the underlying mechanism
supports multiple namespaces).
</p>
<p>Two distinct representations are defined for names:
</p>
<ul>
<li> An internal form.
This is the GSS-API &quot;native&quot; format for names, represented by the
implementation-specific <code>gss_name_t</code> type.  It is opaque to
GSS-API callers.  A single <code>gss_name_t</code> object may contain
multiple names from different namespaces, but all names should refer
to the same entity.  An example of such an internal name would be the
name returned from a call to the <code>gss_inquire_cred</code> routine, when
applied to a credential containing credential elements for multiple
authentication mechanisms employing different namespaces.  This
<code>gss_name_t</code> object will contain a distinct name for the entity
for each authentication mechanism.

<p>For GSS-API implementations supporting multiple namespaces, objects of
type <code>gss_name_t</code> must contain sufficient information to
determine the namespace to which each primitive name belongs.
</p>
</li><li> Mechanism-specific contiguous octet-string forms.
A format capable of containing a single name (from a single
namespace).  Contiguous string names are always accompanied by an
object identifier specifying the namespace to which the name belongs,
and their format is dependent on the authentication mechanism that
employs the name.  Many, but not all, contiguous string names will be
printable, and may therefore be used by GSS-API applications for
communication with their users.
</li></ul>

<p>Routines (<code>gss_import_name</code> and <code>gss_display_name</code>) are
provided to convert names between contiguous string representations
and the internal <code>gss_name_t</code> type.  <code>gss_import_name</code> may
support multiple syntaxes for each supported namespace, allowing users
the freedom to choose a preferred name
representation. <code>gss_display_name</code> should use an
implementation-chosen printable syntax for each supported name-type.
</p>
<p>If an application calls <code>gss_display_name</code>, passing the internal
name resulting from a call to <code>gss_import_name</code>, there is no
guarantee the resulting contiguous string name will be the same as the
original imported string name.  Nor do name-space identifiers
necessarily survive unchanged after a journey through the internal
name-form.  An example of this might be a mechanism that authenticates
X.500 names, but provides an algorithmic mapping of Internet DNS names
into X.500.  That mechanism&rsquo;s implementation of <code>gss_import_name</code>
might, when presented with a DNS name, generate an internal name that
contained both the original DNS name and the equivalent X.500 name.
Alternatively, it might only store the X.500 name.  In the latter
case, <code>gss_display_name</code> would most likely generate a printable
X.500 name, rather than the original DNS name.
</p>
<p>The process of authentication delivers to the context acceptor an
internal name.  Since this name has been authenticated by a single
mechanism, it contains only a single name (even if the internal name
presented by the context initiator to <code>gss_init_sec_context</code> had
multiple components).  Such names are termed internal mechanism names,
or &quot;MN&quot;s and the names emitted by <code>gss_accept_sec_context</code> are
always of this type.  Since some applications may require MNs without
wanting to incur the overhead of an authentication operation, a second
function, <code>gss_canonicalize_name</code>, is provided to convert a
general internal name into an MN.
</p>
<p>Comparison of internal-form names may be accomplished via the
<code>gss_compare_name</code> routine, which returns true if the two names
being compared refer to the same entity.  This removes the need for
the application program to understand the syntaxes of the various
printable names that a given GSS-API implementation may support.
Since GSS-API assumes that all primitive names contained within a
given internal name refer to the same entity, <code>gss_compare_name</code>
can return true if the two names have at least one primitive name in
common.  If the implementation embodies knowledge of equivalence
relationships between names taken from different namespaces, this
knowledge may also allow successful comparison of internal names
containing no overlapping primitive elements.
</p>
<p>When used in large access control lists, the overhead of invoking
<code>gss_import_name</code> and <code>gss_compare_name</code> on each name from
the ACL may be prohibitive.  As an alternative way of supporting this
case, GSS-API defines a special form of the contiguous string name
which may be compared directly (e.g. with memcmp()).  Contiguous names
suitable for comparison are generated by the <code>gss_export_name</code>
routine, which requires an MN as input.  Exported names may be re-
imported by the <code>gss_import_name</code> routine, and the resulting
internal name will also be an MN.  The <code>gss_OID</code> constant
<code>GSS_C_NT_EXPORT_NAME</code> indentifies the &quot;export name&quot; type, and
the value of this constant is given in Appendix A.  Structurally, an
exported name object consists of a header containing an OID
identifying the mechanism that authenticated the name, and a trailer
containing the name itself, where the syntax of the trailer is defined
by the individual mechanism specification.  The precise format of an
export name is defined in the language-independent GSS-API
specification [GSSAPI].
</p>
<p>Note that the results obtained by using <code>gss_compare_name</code> will
in general be different from those obtained by invoking
<code>gss_canonicalize_name</code> and <code>gss_export_name</code>, and then
comparing the exported names.  The first series of operation
determines whether two (unauthenticated) names identify the same
principal; the second whether a particular mechanism would
authenticate them as the same principal.  These two operations will in
general give the same results only for MNs.
</p>
<p>The <code>gss_name_t</code> datatype should be implemented as a pointer
type. To allow the compiler to aid the application programmer by
performing type-checking, the use of (void *) is discouraged.  A
pointer to an implementation-defined type is the preferred choice.
</p>
<p>Storage is allocated by routines that return <code>gss_name_t</code>
values. A procedure, <code>gss_release_name</code>, is provided to free
storage associated with an internal-form name.
</p>
<a name="Channel-Bindings"></a>
<h4 class="subsection">3.2.6 Channel Bindings</h4>

<p>GSS-API supports the use of user-specified tags to identify a given
context to the peer application.  These tags are intended to be used
to identify the particular communications channel that carries the
context.  Channel bindings are communicated to the GSS-API using the
following structure:
</p>
<pre class="verbatim">   typedef struct gss_channel_bindings_struct {
      OM_uint32       initiator_addrtype;
      gss_buffer_desc initiator_address;
      OM_uint32       acceptor_addrtype;
      gss_buffer_desc acceptor_address;
      gss_buffer_desc application_data;
   } *gss_channel_bindings_t;
</pre>
<p>The initiator_addrtype and acceptor_addrtype fields denote the type of
addresses contained in the initiator_address and acceptor_address
buffers.  The address type should be one of the following:
</p>
<pre class="verbatim">   GSS_C_AF_UNSPEC     Unspecified address type
   GSS_C_AF_LOCAL      Host-local address type
   GSS_C_AF_INET       Internet address type (e.g. IP)
   GSS_C_AF_IMPLINK    ARPAnet IMP address type
   GSS_C_AF_PUP        pup protocols (eg BSP) address type
   GSS_C_AF_CHAOS      MIT CHAOS protocol address type
   GSS_C_AF_NS         XEROX NS address type
   GSS_C_AF_NBS        nbs address type
   GSS_C_AF_ECMA       ECMA address type
   GSS_C_AF_DATAKIT    datakit protocols address type
   GSS_C_AF_CCITT      CCITT protocols
   GSS_C_AF_SNA        IBM SNA address type
   GSS_C_AF_DECnet     DECnet address type
   GSS_C_AF_DLI        Direct data link interface address type
   GSS_C_AF_LAT        LAT address type
   GSS_C_AF_HYLINK     NSC Hyperchannel address type
   GSS_C_AF_APPLETALK  AppleTalk address type
   GSS_C_AF_BSC        BISYNC 2780/3780 address type
   GSS_C_AF_DSS        Distributed system services address type
   GSS_C_AF_OSI        OSI TP4 address type
   GSS_C_AF_X25        X.25
   GSS_C_AF_NULLADDR   No address specified
</pre>
<p>Note that these symbols name address families rather than specific
addressing formats.  For address families that contain several
alternative address forms, the initiator_address and acceptor_address
fields must contain sufficient information to determine which address
form is used.  When not otherwise specified, addresses should be
specified in network byte-order (that is, native byte-ordering for the
address family).
</p>
<p>Conceptually, the GSS-API concatenates the initiator_addrtype,
initiator_address, acceptor_addrtype, acceptor_address and
application_data to form an octet string.  The mechanism calculates a
MIC over this octet string, and binds the MIC to the context
establishment token emitted by <code>gss_init_sec_context</code>. The same bindings
are presented by the context acceptor to <code>gss_accept_sec_context</code>, and a
MIC is calculated in the same way. The calculated MIC is compared with
that found in the token, and if the MICs differ,
<code>gss_accept_sec_context</code> will return a <code>GSS_S_BAD_BINDINGS</code> error, and the
context will not be established.  Some mechanisms may include the
actual channel binding data in the token (rather than just a MIC);
applications should therefore not use confidential data as
channel-binding components.
</p>
<p>Individual mechanisms may impose additional constraints on addresses
and address types that may appear in channel bindings.  For example, a
mechanism may verify that the initiator_address field of the channel
bindings presented to <code>gss_init_sec_context</code> contains the correct
network address of the host system.  Portable applications should
therefore ensure that they either provide correct information for the
address fields, or omit addressing information, specifying
<code>GSS_C_AF_NULLADDR</code> as the address-types.
</p>
<hr>
<a name="Optional-Parameters"></a>
<div class="header">
<p>
Next: <a href="#Error-Handling" accesskey="n" rel="next">Error Handling</a>, Previous: <a href="#Complex-Data-Types" accesskey="p" rel="prev">Complex Data Types</a>, Up: <a href="#Standard-GSS-API" accesskey="u" rel="up">Standard GSS API</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Optional-Parameters-1"></a>
<h3 class="section">3.3 Optional Parameters</h3>

<p>Various parameters are described as optional.  This means that they
follow a convention whereby a default value may be requested.  The
following conventions are used for omitted parameters.  These
conventions apply only to those parameters that are explicitly
documented as optional.
</p>
<ul>
<li> gss_buffer_t types.
Specify GSS_C_NO_BUFFER as a value.  For an input parameter this
signifies that default behavior is requested, while for an output
parameter it indicates that the information that would be returned via
the parameter is not required by the application.

</li><li> Integer types (input).
Individual parameter documentation lists values to be used to indicate
default actions.

</li><li> Integer types (output).
Specify NULL as the value for the pointer.

</li><li> Pointer types.
Specify NULL as the value.

</li><li> Object IDs.
Specify GSS_C_NO_OID as the value.

</li><li> Object ID Sets.
Specify GSS_C_NO_OID_SET as the value.

</li><li> Channel Bindings.
Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings
are not to be used.
</li></ul>

<hr>
<a name="Error-Handling"></a>
<div class="header">
<p>
Next: <a href="#Credential-Management" accesskey="n" rel="next">Credential Management</a>, Previous: <a href="#Optional-Parameters" accesskey="p" rel="prev">Optional Parameters</a>, Up: <a href="#Standard-GSS-API" accesskey="u" rel="up">Standard GSS API</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Error-Handling-1"></a>
<h3 class="section">3.4 Error Handling</h3>

<a name="index-status-codes"></a>
<a name="index-mechanism-status-codes"></a>
<p>Every GSS-API routine returns two distinct values to report status
information to the caller: GSS status codes and Mechanism status
codes.
</p>
<a name="GSS-status-codes"></a>
<h4 class="subsection">3.4.1 GSS status codes</h4>

<p>GSS-API routines return GSS status codes as their <code>OM_uint32</code>
function value.  These codes indicate errors that are independent of
the underlying mechanism(s) used to provide the security service.  The
errors that can be indicated via a GSS status code are either generic
API routine errors (errors that are defined in the GSS-API
specification) or calling errors (errors that are specific to these
language bindings).
</p>
<p>A GSS status code can indicate a single fatal generic API error from
the routine and a single calling error.  In addition, supplementary
status information may be indicated via the setting of bits in the
supplementary info field of a GSS status code.
</p>
<p>These errors are encoded into the 32-bit GSS status code as follows:
</p>
<pre class="verbatim">      MSB                                                        LSB
      |------------------------------------------------------------|
      |  Calling Error | Routine Error  |    Supplementary Info    |
      |------------------------------------------------------------|
   Bit 31            24 23            16 15                       0
</pre>
<p>Hence if a GSS-API routine returns a GSS status code whose upper 16
bits contain a non-zero value, the call failed.  If the calling error
field is non-zero, the invoking application&rsquo;s call of the routine was
erroneous.  Calling errors are defined in table 3-1.  If the routine
error field is non-zero, the routine failed for one of the routine-
specific reasons listed below in table 3-2.  Whether or not the upper
16 bits indicate a failure or a success, the routine may indicate
additional information by setting bits in the supplementary info field
of the status code. The meaning of individual bits is listed below in
table 3-3.
</p>
<a name="index-GSS_005fS_005f_002e_002e_002e"></a>
<pre class="verbatim">   Table 3-1  Calling Errors

   Name                   Value in field           Meaning
   ----                   --------------           -------
   GSS_S_CALL_INACCESSIBLE_READ  1       A required input parameter
                                         could not be read
   GSS_S_CALL_INACCESSIBLE_WRITE 2       A required output parameter
                                          could not be written.
   GSS_S_CALL_BAD_STRUCTURE      3       A parameter was malformed
</pre>
<pre class="verbatim">   Table 3-2  Routine Errors

   Name                   Value in field           Meaning
   ----                   --------------           -------
   GSS_S_BAD_MECH                1       An unsupported mechanism
                                         was requested
   GSS_S_BAD_NAME                2       An invalid name was
                                         supplied
   GSS_S_BAD_NAMETYPE            3       A supplied name was of an
                                         unsupported type
   GSS_S_BAD_BINDINGS            4       Incorrect channel bindings
                                         were supplied
   GSS_S_BAD_STATUS              5       An invalid status code was
                                         supplied
   GSS_S_BAD_MIC GSS_S_BAD_SIG   6       A token had an invalid MIC
   GSS_S_NO_CRED                 7       No credentials were
                                         supplied, or the
                                         credentials were
                                         unavailable or
                                         inaccessible.
   GSS_S_NO_CONTEXT              8       No context has been
                                         established
   GSS_S_DEFECTIVE_TOKEN         9       A token was invalid
   GSS_S_DEFECTIVE_CREDENTIAL   10       A credential was invalid
   GSS_S_CREDENTIALS_EXPIRED    11       The referenced credentials
                                         have expired
   GSS_S_CONTEXT_EXPIRED        12       The context has expired
   GSS_S_FAILURE                13       Miscellaneous failure (see
                                         text)
   GSS_S_BAD_QOP                14       The quality-of-protection
                                         requested could not be
                                         provided
   GSS_S_UNAUTHORIZED           15       The operation is forbidden
                                         by local security policy
   GSS_S_UNAVAILABLE            16       The operation or option is
                                         unavailable
   GSS_S_DUPLICATE_ELEMENT      17       The requested credential
                                         element already exists
   GSS_S_NAME_NOT_MN            18       The provided name was not a
                                         mechanism name
</pre>
<pre class="verbatim">   Table 3-3  Supplementary Status Bits

   Name                   Bit Number           Meaning
   ----                   ----------           -------
   GSS_S_CONTINUE_NEEDED   0 (LSB)   Returned only by
                                     gss_init_sec_context or
                                     gss_accept_sec_context. The
                                     routine must be called again
                                     to complete its function.
                                     See routine documentation for
                                     detailed description
   GSS_S_DUPLICATE_TOKEN   1         The token was a duplicate of
                                     an earlier token
   GSS_S_OLD_TOKEN         2         The token's validity period
                                     has expired
   GSS_S_UNSEQ_TOKEN       3         A later token has already been
                                     processed
   GSS_S_GAP_TOKEN         4         An expected per-message token
                                     was not received
</pre>
<p>The routine documentation also uses the name GSS_S_COMPLETE, which is
a zero value, to indicate an absence of any API errors or
supplementary information bits.
</p>
<a name="index-GSS_005fCALLING_005fERROR"></a>
<a name="index-GSS_005fROUTINE_005fERROR"></a>
<a name="index-GSS_005fSUPPLEMENTARY_005fINFO"></a>
<a name="index-GSS_005fERROR"></a>
<p>All GSS_S_xxx symbols equate to complete <code>OM_uint32</code> status
codes, rather than to bitfield values.  For example, the actual value
of the symbol <code>GSS_S_BAD_NAMETYPE</code> (value 3 in the routine error
field) is 3&lt;&lt;16.  The macros <code>GSS_CALLING_ERROR</code>,
<code>GSS_ROUTINE_ERROR</code> and <code>GSS_SUPPLEMENTARY_INFO</code> are
provided, each of which takes a GSS status code and removes all but
the relevant field.  For example, the value obtained by applying
<code>GSS_ROUTINE_ERROR</code> to a status code removes the calling errors
and supplementary info fields, leaving only the routine errors field.
The values delivered by these macros may be directly compared with a
<code>GSS_S_xxx</code> symbol of the appropriate type.  The macro
<code>GSS_ERROR</code> is also provided, which when applied to a GSS status
code returns a non-zero value if the status code indicated a calling
or routine error, and a zero value otherwise.  All macros defined by
GSS-API evaluate their argument(s) exactly once.
</p>
<p>A GSS-API implementation may choose to signal calling errors in a
platform-specific manner instead of, or in addition to the routine
value; routine errors and supplementary info should be returned via
major status values only.
</p>
<p>The GSS major status code <code>GSS_S_FAILURE</code> is used to indicate
that the underlying mechanism detected an error for which no specific
GSS status code is defined.  The mechanism-specific status code will
provide more details about the error.
</p>
<p>In addition to the explicit major status codes for each API function,
the code <code>GSS_S_FAILURE</code> may be returned by any routine,
indicating an implementation-specific or mechanism-specific error
condition, further details of which are reported via the
<code>minor_status</code> parameter.
</p>
<a name="Mechanism_002dspecific-status-codes"></a>
<h4 class="subsection">3.4.2 Mechanism-specific status codes</h4>

<p>GSS-API routines return a minor_status parameter, which is used to
indicate specialized errors from the underlying security mechanism.
This parameter may contain a single mechanism-specific error,
indicated by a <code>OM_uint32</code> value.
</p>
<p>The minor_status parameter will always be set by a GSS-API routine,
even if it returns a calling error or one of the generic API errors
indicated above as fatal, although most other output parameters may
remain unset in such cases.  However, output parameters that are
expected to return pointers to storage allocated by a routine must
always be set by the routine, even in the event of an error, although
in such cases the GSS-API routine may elect to set the returned
parameter value to NULL to indicate that no storage was actually
allocated.  Any length field associated with such pointers (as in a
<code>gss_buffer_desc</code> structure) should also be set to zero in such cases.
</p>
<hr>
<a name="Credential-Management"></a>
<div class="header">
<p>
Next: <a href="#Context_002dLevel-Routines" accesskey="n" rel="next">Context-Level Routines</a>, Previous: <a href="#Error-Handling" accesskey="p" rel="prev">Error Handling</a>, Up: <a href="#Standard-GSS-API" accesskey="u" rel="up">Standard GSS API</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Credential-Management-1"></a>
<h3 class="section">3.5 Credential Management</h3>

<pre class="verbatim">   GSS-API Credential-management Routines

   Routine                         Function
   -------                         --------
   gss_acquire_cred                Assume a global identity; Obtain
                                   a GSS-API credential handle for
                                   pre-existing credentials.
   gss_add_cred                    Construct credentials
                                   incrementally.
   gss_inquire_cred                Obtain information about a
                                   credential.
   gss_inquire_cred_by_mech        Obtain per-mechanism information
                                   about a credential.
   gss_release_cred                Discard a credential handle.
</pre>
<a name="gss_005facquire_005fcred-1"></a>
<h4 class="subheading">gss_acquire_cred</h4>
<a name="gss_005facquire_005fcred"></a><dl>
<dt><a name="index-gss_005facquire_005fcred"></a>Function: <em>OM_uint32</em> <strong>gss_acquire_cred</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_name_t <var>desired_name</var>, OM_uint32 <var>time_req</var>, const gss_OID_set <var>desired_mechs</var>, gss_cred_usage_t <var>cred_usage</var>, gss_cred_id_t * <var>output_cred_handle</var>, gss_OID_set * <var>actual_mechs</var>, OM_uint32 * <var>time_rec</var>)</em></dt>
<dd><p><var>minor_status</var>: (integer, modify) Mechanism specific status code.
</p>
<p><var>desired_name</var>: (gss_name_t, read) Name of principal whose
credential should be acquired.
</p>
<p><var>time_req</var>: (Integer, read, optional) Number of seconds that
credentials should remain valid. Specify GSS_C_INDEFINITE to
request that the credentials have the maximum permitted lifetime.
</p>
<p><var>desired_mechs</var>: (Set of Object IDs, read, optional) Set of
underlying security mechanisms that may be used.
GSS_C_NO_OID_SET may be used to obtain an implementation-specific
default.
</p>
<p><var>cred_usage</var>: (gss_cred_usage_t, read) GSS_C_BOTH - Credentials may
be used either to initiate or accept security contexts.
GSS_C_INITIATE - Credentials will only be used to initiate
security contexts.  GSS_C_ACCEPT - Credentials will only be used
to accept security contexts.
</p>
<p><var>output_cred_handle</var>: (gss_cred_id_t, modify) The returned
credential handle.  Resources associated with this credential
handle must be released by the application after use with a call
to gss_release_cred().
</p>
<p><var>actual_mechs</var>: (Set of Object IDs, modify, optional) The set of
mechanisms for which the credential is valid.  Storage associated
with the returned OID-set must be released by the application
after use with a call to gss_release_oid_set().  Specify NULL if
not required.
</p>
<p><var>time_rec</var>: (Integer, modify, optional) Actual number of seconds for
which the returned credentials will remain valid.  If the
implementation does not support expiration of credentials, the
value GSS_C_INDEFINITE will be returned. Specify NULL if not
required.
</p>

<p>Allows an application to acquire a handle for a pre-existing
credential by name.  GSS-API implementations must impose a local
access-control policy on callers of this routine to prevent
unauthorized callers from acquiring credentials to which they are
not entitled.  This routine is not intended to provide a &quot;login to
the network&quot; function, as such a function would involve the
creation of new credentials rather than merely acquiring a handle
to existing credentials.  Such functions, if required, should be
defined in implementation-specific extensions to the API.
</p>

<p>If desired_name is GSS_C_NO_NAME, the call is interpreted as a
request for a credential handle that will invoke default behavior
when passed to gss_init_sec_context() (if cred_usage is
GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if
cred_usage is GSS_C_ACCEPT or GSS_C_BOTH).
</p>

<p>Mechanisms should honor the desired_mechs parameter, and return a
credential that is suitable to use only with the requested
mechanisms.  An exception to this is the case where one underlying
credential element can be shared by multiple mechanisms; in this
case it is permissible for an implementation to indicate all
mechanisms with which the credential element may be used.  If
desired_mechs is an empty set, behavior is undefined.
</p>

<p>This routine is expected to be used primarily by context acceptors,
since implementations are likely to provide mechanism-specific ways
of obtaining GSS-API initiator credentials from the system login
process.  Some implementations may therefore not support the
acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name
produced by applying either gss_inquire_cred to a valid credential,
or gss_inquire_context to an active context.
</p>

<p>If credential acquisition is time-consuming for a mechanism, the
mechanism may choose to delay the actual acquisition until the
credential is required (e.g. by gss_init_sec_context or
gss_accept_sec_context).  Such mechanism-specific implementation
decisions should be invisible to the calling application; thus a
call of gss_inquire_cred immediately following the call of
gss_acquire_cred must return valid credential data, and may
therefore incur the overhead of a deferred credential acquisition.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_BAD_MECH</code>: Unavailable mechanism requested.
</p>

<p><code>GSS_S_BAD_NAMETYPE</code>: Type contained within desired_name parameter
is not supported.
</p>

<p><code>GSS_S_BAD_NAME</code>: Value supplied for desired_name parameter is ill
formed.
</p>

<p><code>GSS_S_CREDENTIALS_EXPIRED</code>: The credentials could not be acquired
Because they have expired.
</p>

<p><code>GSS_S_NO_CRED</code>: No credentials were found for the specified name.
</p></dd></dl>

<a name="gss_005fadd_005fcred-1"></a>
<h4 class="subheading">gss_add_cred</h4>
<a name="gss_005fadd_005fcred"></a><dl>
<dt><a name="index-gss_005fadd_005fcred"></a>Function: <em>OM_uint32</em> <strong>gss_add_cred</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_cred_id_t <var>input_cred_handle</var>, const gss_name_t <var>desired_name</var>, const gss_OID <var>desired_mech</var>, gss_cred_usage_t <var>cred_usage</var>, OM_uint32 <var>initiator_time_req</var>, OM_uint32 <var>acceptor_time_req</var>, gss_cred_id_t * <var>output_cred_handle</var>, gss_OID_set * <var>actual_mechs</var>, OM_uint32 * <var>initiator_time_rec</var>, OM_uint32 * <var>acceptor_time_rec</var>)</em></dt>
<dd><p><var>minor_status</var>: (integer, modify) Mechanism specific status code.
</p>
<p><var>input_cred_handle</var>: (gss_cred_id_t, read, optional) The credential
to which a credential-element will be added.  If
GSS_C_NO_CREDENTIAL is specified, the routine will compose the
new credential based on default behavior (see text).
Note that, while the credential-handle is not modified by
gss_add_cred(), the underlying credential will be modified if
output_credential_handle is NULL.
</p>
<p><var>desired_name</var>: (gss_name_t, read.)  Name of principal whose
credential should be acquired.
</p>
<p><var>desired_mech</var>: (Object ID, read) Underlying security mechanism with
which the credential may be used.
</p>
<p><var>cred_usage</var>: (gss_cred_usage_t, read) GSS_C_BOTH - Credential may
be used either to initiate or accept security contexts.
GSS_C_INITIATE - Credential will only be used to initiate
security contexts.  GSS_C_ACCEPT - Credential will only be used
to accept security contexts.
</p>
<p><var>initiator_time_req</var>: (Integer, read, optional) number of seconds
that the credential should remain valid for initiating security
contexts.  This argument is ignored if the composed credentials
are of type GSS_C_ACCEPT.  Specify GSS_C_INDEFINITE to request
that the credentials have the maximum permitted initiator
lifetime.
</p>
<p><var>acceptor_time_req</var>: (Integer, read, optional) number of seconds
that the credential should remain valid for accepting security
contexts.  This argument is ignored if the composed credentials
are of type GSS_C_INITIATE.  Specify GSS_C_INDEFINITE to request
that the credentials have the maximum permitted initiator
lifetime.
</p>
<p><var>output_cred_handle</var>: (gss_cred_id_t, modify, optional) The returned
credential handle, containing the new credential-element and all
the credential-elements from input_cred_handle.  If a valid
pointer to a gss_cred_id_t is supplied for this parameter,
gss_add_cred creates a new credential handle containing all
credential-elements from the input_cred_handle and the newly
acquired credential-element; if NULL is specified for this
parameter, the newly acquired credential-element will be added to
the credential identified by input_cred_handle.  The resources
associated with any credential handle returned via this parameter
must be released by the application after use with a call to
gss_release_cred().
</p>
<p><var>actual_mechs</var>: (Set of Object IDs, modify, optional) The complete
set of mechanisms for which the new credential is valid.  Storage
for the returned OID-set must be freed by the application after
use with a call to gss_release_oid_set(). Specify NULL if not
required.
</p>
<p><var>initiator_time_rec</var>: (Integer, modify, optional) Actual number of
seconds for which the returned credentials will remain valid for
initiating contexts using the specified mechanism.  If the
implementation or mechanism does not support expiration of
credentials, the value GSS_C_INDEFINITE will be returned. Specify
NULL if not required
</p>
<p><var>acceptor_time_rec</var>: (Integer, modify, optional) Actual number of
seconds for which the returned credentials will remain valid for
accepting security contexts using the specified mechanism.  If
the implementation or mechanism does not support expiration of
credentials, the value GSS_C_INDEFINITE will be returned. Specify
NULL if not required
</p>

<p>Adds a credential-element to a credential.  The credential-element is
identified by the name of the principal to which it refers.  GSS-API
implementations must impose a local access-control policy on callers
of this routine to prevent unauthorized callers from acquiring
credential-elements to which they are not entitled. This routine is
not intended to provide a &quot;login to the network&quot; function, as such a
function would involve the creation of new mechanism-specific
authentication data, rather than merely acquiring a GSS-API handle to
existing data.  Such functions, if required, should be defined in
implementation-specific extensions to the API.
</p>

<p>If desired_name is GSS_C_NO_NAME, the call is interpreted as a
request to add a credential element that will invoke default behavior
when passed to gss_init_sec_context() (if cred_usage is
GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if
cred_usage is GSS_C_ACCEPT or GSS_C_BOTH).
</p>

<p>This routine is expected to be used primarily by context acceptors,
since implementations are likely to provide mechanism-specific ways
of obtaining GSS-API initiator credentials from the system login
process.  Some implementations may therefore not support the
acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name
produced by applying either gss_inquire_cred to a valid credential,
or gss_inquire_context to an active context.
</p>

<p>If credential acquisition is time-consuming for a mechanism, the
mechanism may choose to delay the actual acquisition until the
credential is required (e.g. by gss_init_sec_context or
gss_accept_sec_context).  Such mechanism-specific implementation
decisions should be invisible to the calling application; thus a call
of gss_inquire_cred immediately following the call of gss_add_cred
must return valid credential data, and may therefore incur the
overhead of a deferred credential acquisition.
</p>

<p>This routine can be used to either compose a new credential
containing all credential-elements of the original in addition to the
newly-acquire credential-element, or to add the new credential-
element to an existing credential. If NULL is specified for the
output_cred_handle parameter argument, the new credential-element
will be added to the credential identified by input_cred_handle; if a
valid pointer is specified for the output_cred_handle parameter, a
new credential handle will be created.
</p>

<p>If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle,
gss_add_cred will compose a credential (and set the
output_cred_handle parameter accordingly) based on default behavior.
That is, the call will have the same effect as if the application had
first made a call to gss_acquire_cred(), specifying the same usage
and passing GSS_C_NO_NAME as the desired_name parameter to obtain an
explicit credential handle embodying default behavior, passed this
credential handle to gss_add_cred(), and finally called
gss_release_cred() on the first credential handle.
</p>

<p>If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle
parameter, a non-NULL output_cred_handle must be supplied.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_BAD_MECH</code>: Unavailable mechanism requested.
</p>

<p><code>GSS_S_BAD_NAMETYPE</code>: Type contained within desired_name parameter
is not supported.
</p>

<p><code>GSS_S_BAD_NAME</code>: Value supplied for desired_name parameter is
ill-formed.
</p>

<p><code>GSS_S_DUPLICATE_ELEMENT</code>: The credential already contains an
element for the requested mechanism with overlapping usage and
validity period.
</p>

<p><code>GSS_S_CREDENTIALS_EXPIRED</code>: The required credentials could not be
added because they have expired.
</p>

<p><code>GSS_S_NO_CRED</code>: No credentials were found for the specified name.
</p></dd></dl>

<a name="gss_005finquire_005fcred-1"></a>
<h4 class="subheading">gss_inquire_cred</h4>
<a name="gss_005finquire_005fcred"></a><dl>
<dt><a name="index-gss_005finquire_005fcred"></a>Function: <em>OM_uint32</em> <strong>gss_inquire_cred</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_cred_id_t <var>cred_handle</var>, gss_name_t * <var>name</var>, OM_uint32 * <var>lifetime</var>, gss_cred_usage_t * <var>cred_usage</var>, gss_OID_set * <var>mechanisms</var>)</em></dt>
<dd><p><var>minor_status</var>: (integer, modify) Mechanism specific status code.
</p>
<p><var>cred_handle</var>: (gss_cred_id_t, read) A handle that refers to the
target credential.  Specify GSS_C_NO_CREDENTIAL to inquire about
the default initiator principal.
</p>
<p><var>name</var>: (gss_name_t, modify, optional) The name whose identity the
credential asserts.  Storage associated with this name should be
freed by the application after use with a call to
gss_release_name().  Specify NULL if not required.
</p>
<p><var>lifetime</var>: (Integer, modify, optional) The number of seconds for
which the credential will remain valid.  If the credential has
expired, this parameter will be set to zero.  If the
implementation does not support credential expiration, the value
GSS_C_INDEFINITE will be returned.  Specify NULL if not required.
</p>
<p><var>cred_usage</var>: (gss_cred_usage_t, modify, optional) How the
credential may be used.  One of the following: GSS_C_INITIATE,
GSS_C_ACCEPT, GSS_C_BOTH. Specify NULL if not required.
</p>
<p><var>mechanisms</var>: (gss_OID_set, modify, optional) Set of mechanisms
supported by the credential.  Storage associated with this OID
set must be freed by the application after use with a call to
gss_release_oid_set().  Specify NULL if not required.
</p>

<p>Obtains information about a credential.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_NO_CRED</code>: The referenced credentials could not be accessed.
</p>

<p><code>GSS_S_DEFECTIVE_CREDENTIAL</code>: The referenced credentials were invalid.
</p>

<p><code>GSS_S_CREDENTIALS_EXPIRED</code>: The referenced credentials have
expired.  If the lifetime parameter was not passed as NULL, it will
be set to 0.
</p></dd></dl>

<a name="gss_005finquire_005fcred_005fby_005fmech-1"></a>
<h4 class="subheading">gss_inquire_cred_by_mech</h4>
<a name="gss_005finquire_005fcred_005fby_005fmech"></a><dl>
<dt><a name="index-gss_005finquire_005fcred_005fby_005fmech"></a>Function: <em>OM_uint32</em> <strong>gss_inquire_cred_by_mech</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_cred_id_t <var>cred_handle</var>, const gss_OID <var>mech_type</var>, gss_name_t * <var>name</var>, OM_uint32 * <var>initiator_lifetime</var>, OM_uint32 * <var>acceptor_lifetime</var>, gss_cred_usage_t * <var>cred_usage</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>cred_handle</var>: (gss_cred_id_t, read) A handle that refers to the
target credential.  Specify GSS_C_NO_CREDENTIAL to inquire about
the default initiator principal.
</p>
<p><var>mech_type</var>: (gss_OID, read) The mechanism for which information
should be returned.
</p>
<p><var>name</var>: (gss_name_t, modify, optional) The name whose identity the
credential asserts.  Storage associated with this name must be
freed by the application after use with a call to
gss_release_name().  Specify NULL if not required.
</p>
<p><var>initiator_lifetime</var>: (Integer, modify, optional) The number of
seconds for which the credential will remain capable of
initiating security contexts under the specified mechanism.  If
the credential can no longer be used to initiate contexts, or if
the credential usage for this mechanism is GSS_C_ACCEPT, this
parameter will be set to zero.  If the implementation does not
support expiration of initiator credentials, the value
GSS_C_INDEFINITE will be returned.  Specify NULL if not required.
</p>
<p><var>acceptor_lifetime</var>: (Integer, modify, optional) The number of
seconds for which the credential will remain capable of accepting
security contexts under the specified mechanism.  If the
credential can no longer be used to accept contexts, or if the
credential usage for this mechanism is GSS_C_INITIATE, this
parameter will be set to zero.  If the implementation does not
support expiration of acceptor credentials, the value
GSS_C_INDEFINITE will be returned.  Specify NULL if not required.
</p>
<p><var>cred_usage</var>: (gss_cred_usage_t, modify, optional) How the
credential may be used with the specified mechanism.  One of the
following: GSS_C_INITIATE, GSS_C_ACCEPT, GSS_C_BOTH. Specify NULL
if not required.
</p>

<p>Obtains per-mechanism information about a credential.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_NO_CRED</code>: The referenced credentials could not be accessed.
</p>

<p><code>GSS_S_DEFECTIVE_CREDENTIAL</code>: The referenced credentials were invalid.
</p>

<p><code>GSS_S_CREDENTIALS_EXPIRED</code>: The referenced credentials have
expired.  If the lifetime parameter was not passed as NULL, it will
be set to 0.
</p></dd></dl>

<a name="gss_005frelease_005fcred-1"></a>
<h4 class="subheading">gss_release_cred</h4>
<a name="gss_005frelease_005fcred"></a><dl>
<dt><a name="index-gss_005frelease_005fcred"></a>Function: <em>OM_uint32</em> <strong>gss_release_cred</strong> <em>(OM_uint32 * <var>minor_status</var>, gss_cred_id_t * <var>cred_handle</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>cred_handle</var>: (gss_cred_id_t, modify, optional) Opaque handle
identifying credential to be released.  If GSS_C_NO_CREDENTIAL is
supplied, the routine will complete successfully, but will do
nothing.
</p>

<p>Informs GSS-API that the specified credential handle is no longer
required by the application, and frees associated resources.  The
cred_handle is set to GSS_C_NO_CREDENTIAL on successful completion
of this call.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_NO_CRED</code>: Credentials could not be accessed.
</p></dd></dl>


<hr>
<a name="Context_002dLevel-Routines"></a>
<div class="header">
<p>
Next: <a href="#Per_002dMessage-Routines" accesskey="n" rel="next">Per-Message Routines</a>, Previous: <a href="#Credential-Management" accesskey="p" rel="prev">Credential Management</a>, Up: <a href="#Standard-GSS-API" accesskey="u" rel="up">Standard GSS API</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Context_002dLevel-Routines-1"></a>
<h3 class="section">3.6 Context-Level Routines</h3>

<pre class="verbatim">   GSS-API Context-Level Routines

   Routine                         Function
   -------                         --------
   gss_init_sec_context            Initiate a security context with
                                   a peer application.
   gss_accept_sec_context          Accept a security context
                                   initiated by a peer application.
   gss_delete_sec_context          Discard a security context.
   gss_process_context_token       Process a token on a security
                                   context from a peer application.
   gss_context_time                Determine for how long a context
                                   will remain valid.
   gss_inquire_context             Obtain information about a
                                   security context.
   gss_wrap_size_limit             Determine token-size limit for
                                   gss_wrap on a context.
   gss_export_sec_context          Transfer a security context to
                                   another process.
   gss_import_sec_context          Import a transferred context.
</pre>
<a name="gss_005finit_005fsec_005fcontext-1"></a>
<h4 class="subheading">gss_init_sec_context</h4>
<a name="gss_005finit_005fsec_005fcontext"></a><dl>
<dt><a name="index-gss_005finit_005fsec_005fcontext"></a>Function: <em>OM_uint32</em> <strong>gss_init_sec_context</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_cred_id_t <var>initiator_cred_handle</var>, gss_ctx_id_t * <var>context_handle</var>, const gss_name_t <var>target_name</var>, const gss_OID <var>mech_type</var>, OM_uint32 <var>req_flags</var>, OM_uint32 <var>time_req</var>, const gss_channel_bindings_t <var>input_chan_bindings</var>, const gss_buffer_t <var>input_token</var>, gss_OID * <var>actual_mech_type</var>, gss_buffer_t <var>output_token</var>, OM_uint32 * <var>ret_flags</var>, OM_uint32 * <var>time_rec</var>)</em></dt>
<dd><p><var>minor_status</var>: (integer, modify) Mechanism specific status code.
</p>
<p><var>initiator_cred_handle</var>: (gss_cred_id_t, read, optional) Handle for
credentials claimed.  Supply GSS_C_NO_CREDENTIAL to act as a
default initiator principal.  If no default initiator is defined,
the function will return GSS_S_NO_CRED.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, read/modify) Context handle for new
context.  Supply GSS_C_NO_CONTEXT for first call; use value
returned by first call in continuation calls.  Resources
associated with this context-handle must be released by the
application after use with a call to gss_delete_sec_context().
</p>
<p><var>target_name</var>: (gss_name_t, read) Name of target.
</p>
<p><var>mech_type</var>: (OID, read, optional) Object ID of desired
mechanism. Supply GSS_C_NO_OID to obtain an implementation
specific default.
</p>
<p><var>req_flags</var>: (bit-mask, read) Contains various independent flags,
each of which requests that the context support a specific
service option.  Symbolic names are provided for each flag, and
the symbolic names corresponding to the required flags should be
logically-ORed together to form the bit-mask value.  See below
for the flags.
</p>
<p><var>time_req</var>: (Integer, read, optional) Desired number of seconds for
which context should remain valid.  Supply 0 to request a default
validity period.
</p>
<p><var>input_chan_bindings</var>: (channel bindings, read, optional)
Application-specified bindings.  Allows application to securely
bind channel identification information to the security context.
Specify GSS_C_NO_CHANNEL_BINDINGS if channel bindings are not
used.
</p>
<p><var>input_token</var>: (buffer, opaque, read, optional) Token received from
peer application.  Supply GSS_C_NO_BUFFER, or a pointer to a
buffer containing the value GSS_C_EMPTY_BUFFER on initial call.
</p>
<p><var>actual_mech_type</var>: (OID, modify, optional) Actual mechanism used.
The OID returned via this parameter will be a pointer to static
storage that should be treated as read-only; In particular the
application should not attempt to free it.  Specify NULL if not
required.
</p>
<p><var>output_token</var>: (buffer, opaque, modify) Token to be sent to peer
application.  If the length field of the returned buffer is zero,
no token need be sent to the peer application.  Storage
associated with this buffer must be freed by the application
after use with a call to gss_release_buffer().
</p>
<p><var>ret_flags</var>: (bit-mask, modify, optional) Contains various
independent flags, each of which indicates that the context
supports a specific service option.  Specify NULL if not
required.  Symbolic names are provided for each flag, and the
symbolic names corresponding to the required flags should be
logically-ANDed with the ret_flags value to test whether a given
option is supported by the context.  See below for the flags.
</p>
<p><var>time_rec</var>: (Integer, modify, optional) Number of seconds for which
the context will remain valid. If the implementation does not
support context expiration, the value GSS_C_INDEFINITE will be
returned.  Specify NULL if not required.
</p>

<p>Initiates the establishment of a security context between the
application and a remote peer.  Initially, the input_token
parameter should be specified either as GSS_C_NO_BUFFER, or as a
pointer to a gss_buffer_desc object whose length field contains the
value zero.  The routine may return a output_token which should be
transferred to the peer application, where the peer application
will present it to gss_accept_sec_context.  If no token need be
sent, gss_init_sec_context will indicate this by setting the length
field of the output_token argument to zero. To complete the context
establishment, one or more reply tokens may be required from the
peer application; if so, gss_init_sec_context will return a status
containing the supplementary information bit GSS_S_CONTINUE_NEEDED.
In this case, gss_init_sec_context should be called again when the
reply token is received from the peer application, passing the
reply token to gss_init_sec_context via the input_token parameters.
</p>

<p>Portable applications should be constructed to use the token length
and return status to determine whether a token needs to be sent or
waited for.  Thus a typical portable caller should always invoke
gss_init_sec_context within a loop:
</p>
<div class="example">
<pre class="example">int context_established = 0;
gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
       ...
input_token-&gt;length = 0;

while (!context_established) {
  maj_stat = gss_init_sec_context(&amp;min_stat,
                                  cred_hdl,
                                  &amp;context_hdl,
                                  target_name,
                                  desired_mech,
                                  desired_services,
                                  desired_time,
                                  input_bindings,
                                  input_token,
                                  &amp;actual_mech,
                                  output_token,
                                  &amp;actual_services,
                                  &amp;actual_time);
  if (GSS_ERROR(maj_stat)) {
    report_error(maj_stat, min_stat);
  };

  if (output_token-&gt;length != 0) {
    send_token_to_peer(output_token);
    gss_release_buffer(&amp;min_stat, output_token)
  };
  if (GSS_ERROR(maj_stat)) {

    if (context_hdl != GSS_C_NO_CONTEXT)
      gss_delete_sec_context(&amp;min_stat,
                             &amp;context_hdl,
                             GSS_C_NO_BUFFER);
    break;
  };

  if (maj_stat &amp; GSS_S_CONTINUE_NEEDED) {
    receive_token_from_peer(input_token);
  } else {
    context_established = 1;
  };
};
</pre></div>

<p>Whenever the routine returns a major status that includes the value
GSS_S_CONTINUE_NEEDED, the context is not fully established and the
following restrictions apply to the output parameters:
</p>
<ul>
<li> The value returned via the time_rec parameter is undefined unless
the accompanying ret_flags parameter contains the bit
GSS_C_PROT_READY_FLAG, indicating that per-message services may be
applied in advance of a successful completion status, the value
returned via the actual_mech_type parameter is undefined until the
routine returns a major status value of GSS_S_COMPLETE.

</li><li> The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG,
GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG,
GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the
ret_flags parameter should contain the values that the
implementation expects would be valid if context establishment were
to succeed.  In particular, if the application has requested a
service such as delegation or anonymous authentication via the
req_flags argument, and such a service is unavailable from the
underlying mechanism, gss_init_sec_context should generate a token
that will not provide the service, and indicate via the ret_flags
argument that the service will not be supported.  The application
may choose to abort the context establishment by calling
gss_delete_sec_context (if it cannot continue in the absence of the
service), or it may choose to transmit the token and continue
context establishment (if the service was merely desired but not
mandatory).

</li><li> The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
within ret_flags should indicate the actual state at the time
gss_init_sec_context returns, whether or not the context is fully
established.

</li><li> GSS-API implementations that support per-message protection are
encouraged to set the GSS_C_PROT_READY_FLAG in the final ret_flags
returned to a caller (i.e. when accompanied by a GSS_S_COMPLETE
status code).  However, applications should not rely on this
behavior as the flag was not defined in Version 1 of the GSS-API.
Instead, applications should determine what per-message services
are available after a successful context establishment according to
the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.

</li><li> All other bits within the ret_flags argument should be set to
zero.

</li></ul>

<p>If the initial call of gss_init_sec_context() fails, the
implementation should not create a context object, and should leave
the value of the context_handle parameter set to GSS_C_NO_CONTEXT
to indicate this.  In the event of a failure on a subsequent call,
the implementation is permitted to delete the &quot;half-built&quot; security
context (in which case it should set the context_handle parameter
to GSS_C_NO_CONTEXT), but the preferred behavior is to leave the
security context untouched for the application to delete (using
gss_delete_sec_context).
</p>

<p>During context establishment, the informational status bits
GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors,
and GSS-API mechanisms should always return them in association
with a routine error of GSS_S_FAILURE.  This requirement for
pairing did not exist in version 1 of the GSS-API specification, so
applications that wish to run over version 1 implementations must
special-case these codes.
</p>

<p>The <code>req_flags</code> values:
</p>
<dl compact="compact">
<dd><p><code>GSS_C_DELEG_FLAG</code>
</p>


<ul>
<li> True - Delegate credentials to remote peer.

</li><li> False - Don&rsquo;t delegate.

</li></ul>
</dd>
<dd><p><code>GSS_C_MUTUAL_FLAG</code>
</p>


<ul>
<li> True - Request that remote peer authenticate itself.

</li><li> False - Authenticate self to remote peer only.

</li></ul>
</dd>
<dd><p><code>GSS_C_REPLAY_FLAG</code>
</p>


<ul>
<li> True - Enable replay detection for messages protected with
gss_wrap or gss_get_mic.

</li><li> False - Don&rsquo;t attempt to detect replayed messages.

</li></ul>
</dd>
<dd><p><code>GSS_C_SEQUENCE_FLAG</code>
</p>


<ul>
<li> True - Enable detection of out-of-sequence protected messages.

</li><li> False - Don&rsquo;t attempt to detect out-of-sequence messages.

</li></ul>
</dd>
<dd><p><code>GSS_C_CONF_FLAG</code>
</p>


<ul>
<li> True - Request that confidentiality service be made available
(via gss_wrap).

</li><li> False - No per-message confidentiality service is required.

</li></ul>
</dd>
<dd><p><code>GSS_C_INTEG_FLAG</code>
</p>


<ul>
<li> True - Request that integrity service be made available (via
gss_wrap or gss_get_mic).

</li><li> False - No per-message integrity service is required.

</li></ul>
</dd>
<dd><p><code>GSS_C_ANON_FLAG</code>
</p>


<ul>
<li> True - Do not reveal the initiator&rsquo;s identity to the acceptor.

</li><li> False - Authenticate normally.

</li></ul>
</dd>
</dl>

<p>The <code>ret_flags</code> values:
</p>
<dl compact="compact">
<dd><p><code>GSS_C_DELEG_FLAG</code>
</p>


<ul>
<li> True - Credentials were delegated to the remote peer.

</li><li> False - No credentials were delegated.

</li></ul>
</dd>
<dd><p><code>GSS_C_MUTUAL_FLAG</code>
</p>


<ul>
<li> True - The remote peer has authenticated itself.

</li><li> False - Remote peer has not authenticated itself.

</li></ul>
</dd>
<dd><p><code>GSS_C_REPLAY_FLAG</code>
</p>


<ul>
<li> True - replay of protected messages will be detected.

</li><li> False - replayed messages will not be detected.

</li></ul>
</dd>
<dd><p><code>GSS_C_SEQUENCE_FLAG</code>
</p>


<ul>
<li> True - out-of-sequence protected messages will be detected.

</li><li> False - out-of-sequence messages will not be detected.

</li></ul>
</dd>
<dd><p><code>GSS_C_CONF_FLAG</code>
</p>


<ul>
<li> True - Confidentiality service may be invoked by calling gss_wrap
routine.

</li><li> False - No confidentiality service (via gss_wrap)
available. gss_wrap will provide message encapsulation, data-origin
authentication and integrity services only.

</li></ul>
</dd>
<dd><p><code>GSS_C_INTEG_FLAG</code>
</p>


<ul>
<li> True - Integrity service may be invoked by calling either
gss_get_mic or gss_wrap routines.

</li><li> False - Per-message integrity service unavailable.

</li></ul>
</dd>
<dd><p><code>GSS_C_ANON_FLAG</code>
</p>


<ul>
<li> True - The initiator&rsquo;s identity has not been revealed, and will
not be revealed if any emitted token is passed to the acceptor.

</li><li> False - The initiator&rsquo;s identity has been or will be
authenticated normally.

</li></ul>
</dd>
<dd><p><code>GSS_C_PROT_READY_FLAG</code>
</p>


<ul>
<li> True - Protection services (as specified by the states of the
GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available for use if the
accompanying major status return value is either GSS_S_COMPLETE or
GSS_S_CONTINUE_NEEDED.

</li><li> False - Protection services (as specified by the states of the
GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available only if the
accompanying major status return value is GSS_S_COMPLETE.

</li></ul>
</dd>
<dd><p><code>GSS_C_TRANS_FLAG</code>
</p>


<ul>
<li> True - The resultant security context may be transferred to other
processes via a call to gss_export_sec_context().

</li><li> False - The security context is not transferable.

</li></ul>
</dd>
</dl>

<p>All other bits should be set to zero.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_CONTINUE_NEEDED</code>: Indicates that a token from the peer
application is required to complete the context, and that
gss_init_sec_context must be called again with that token.
</p>

<p><code>GSS_S_DEFECTIVE_TOKEN</code>: Indicates that consistency checks
performed on the input_token failed.
</p>

<p><code>GSS_S_DEFECTIVE_CREDENTIAL</code>: Indicates that consistency checks
performed on the credential failed.
</p>

<p><code>GSS_S_NO_CRED</code>: The supplied credentials were not valid for
context initiation, or the credential handle did not reference any
credentials.
</p>

<p><code>GSS_S_CREDENTIALS_EXPIRED</code>: The referenced credentials have
expired.
</p>

<p><code>GSS_S_BAD_BINDINGS</code>: The input_token contains different channel
bindings to those specified via the input_chan_bindings parameter.
</p>

<p><code>GSS_S_BAD_SIG</code>: The input_token contains an invalid MIC, or a MIC
that could not be verified.
</p>

<p><code>GSS_S_OLD_TOKEN</code>: The input_token was too old.  This is a fatal
error during context establishment.
</p>

<p><code>GSS_S_DUPLICATE_TOKEN</code>: The input_token is valid, but is a
duplicate of a token already processed.  This is a fatal error
during context establishment.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: Indicates that the supplied context handle did
not refer to a valid context.
</p>

<p><code>GSS_S_BAD_NAMETYPE</code>: The provided target_name parameter contained
an invalid or unsupported type of name.
</p>

<p><code>GSS_S_BAD_NAME</code>: The provided target_name parameter was
ill-formed.
</p>

<p><code>GSS_S_BAD_MECH</code>: The specified mechanism is not supported by the
provided credential, or is unrecognized by the implementation.
</p></dd></dl>

<a name="gss_005faccept_005fsec_005fcontext-1"></a>
<h4 class="subheading">gss_accept_sec_context</h4>
<a name="gss_005faccept_005fsec_005fcontext"></a><dl>
<dt><a name="index-gss_005faccept_005fsec_005fcontext"></a>Function: <em>OM_uint32</em> <strong>gss_accept_sec_context</strong> <em>(OM_uint32 * <var>minor_status</var>, gss_ctx_id_t * <var>context_handle</var>, const gss_cred_id_t <var>acceptor_cred_handle</var>, const gss_buffer_t <var>input_token_buffer</var>, const gss_channel_bindings_t <var>input_chan_bindings</var>, gss_name_t * <var>src_name</var>, gss_OID * <var>mech_type</var>, gss_buffer_t <var>output_token</var>, OM_uint32 * <var>ret_flags</var>, OM_uint32 * <var>time_rec</var>, gss_cred_id_t * <var>delegated_cred_handle</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, read/modify) Context handle for new
context.  Supply GSS_C_NO_CONTEXT for first call; use value
returned in subsequent calls.  Once gss_accept_sec_context() has
returned a value via this parameter, resources have been assigned
to the corresponding context, and must be freed by the
application after use with a call to gss_delete_sec_context().
</p>
<p><var>acceptor_cred_handle</var>: (gss_cred_id_t, read) Credential handle
claimed by context acceptor. Specify GSS_C_NO_CREDENTIAL to
accept the context as a default principal.  If
GSS_C_NO_CREDENTIAL is specified, but no default acceptor
principal is defined, GSS_S_NO_CRED will be returned.
</p>
<p><var>input_token_buffer</var>: (buffer, opaque, read) Token obtained from
remote application.
</p>
<p><var>input_chan_bindings</var>: (channel bindings, read, optional)
Application- specified bindings.  Allows application to securely
bind channel identification information to the security context.
If channel bindings are not used, specify
GSS_C_NO_CHANNEL_BINDINGS.
</p>
<p><var>src_name</var>: (gss_name_t, modify, optional) Authenticated name of
context initiator.  After use, this name should be deallocated by
passing it to gss_release_name().  If not required, specify NULL.
</p>
<p><var>mech_type</var>: (Object ID, modify, optional) Security mechanism used.
The returned OID value will be a pointer into static storage, and
should be treated as read-only by the caller (in particular, it
does not need to be freed).  If not required, specify NULL.
</p>
<p><var>output_token</var>: (buffer, opaque, modify) Token to be passed to peer
application.  If the length field of the returned token buffer is
0, then no token need be passed to the peer application.  If a
non- zero length field is returned, the associated storage must
be freed after use by the application with a call to
gss_release_buffer().
</p>
<p><var>ret_flags</var>: (bit-mask, modify, optional) Contains various
independent flags, each of which indicates that the context
supports a specific service option.  If not needed, specify NULL.
Symbolic names are provided for each flag, and the symbolic names
corresponding to the required flags should be logically-ANDed
with the ret_flags value to test whether a given option is
supported by the context.  See below for the flags.
</p>
<p><var>time_rec</var>: (Integer, modify, optional) Number of seconds for which
the context will remain valid. Specify NULL if not required.
</p>
<p><var>delegated_cred_handle</var>: (gss_cred_id_t, modify, optional
credential) Handle for credentials received from context
initiator.  Only valid if deleg_flag in ret_flags is true, in
which case an explicit credential handle (i.e. not
GSS_C_NO_CREDENTIAL) will be returned; if deleg_flag is false,
gss_accept_sec_context() will set this parameter to
GSS_C_NO_CREDENTIAL.  If a credential handle is returned, the
associated resources must be released by the application after
use with a call to gss_release_cred().  Specify NULL if not
required.
</p>

<p>Allows a remotely initiated security context between the
application and a remote peer to be established.  The routine may
return a output_token which should be transferred to the peer
application, where the peer application will present it to
gss_init_sec_context.  If no token need be sent,
gss_accept_sec_context will indicate this by setting the length
field of the output_token argument to zero.  To complete the
context establishment, one or more reply tokens may be required
from the peer application; if so, gss_accept_sec_context will
return a status flag of GSS_S_CONTINUE_NEEDED, in which case it
should be called again when the reply token is received from the
peer application, passing the token to gss_accept_sec_context via
the input_token parameters.
</p>

<p>Portable applications should be constructed to use the token length
and return status to determine whether a token needs to be sent or
waited for.  Thus a typical portable caller should always invoke
gss_accept_sec_context within a loop:
</p>
<div class="example">
<pre class="example">gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;

do {
  receive_token_from_peer(input_token);
  maj_stat = gss_accept_sec_context(&amp;min_stat,
                                    &amp;context_hdl,
                                    cred_hdl,
                                    input_token,
                                    input_bindings,
                                    &amp;client_name,
                                    &amp;mech_type,
                                    output_token,
                                    &amp;ret_flags,
                                    &amp;time_rec,
                                    &amp;deleg_cred);
  if (GSS_ERROR(maj_stat)) {
    report_error(maj_stat, min_stat);
  };
  if (output_token-&gt;length != 0) {
    send_token_to_peer(output_token);

    gss_release_buffer(&amp;min_stat, output_token);
  };
  if (GSS_ERROR(maj_stat)) {
    if (context_hdl != GSS_C_NO_CONTEXT)
      gss_delete_sec_context(&amp;min_stat,
                             &amp;context_hdl,
                             GSS_C_NO_BUFFER);
    break;
  };
} while (maj_stat &amp; GSS_S_CONTINUE_NEEDED);
</pre></div>

<p>Whenever the routine returns a major status that includes the value
GSS_S_CONTINUE_NEEDED, the context is not fully established and the
following restrictions apply to the output parameters:
</p>

<p>The value returned via the time_rec parameter is undefined Unless the
accompanying ret_flags parameter contains the bit
GSS_C_PROT_READY_FLAG, indicating that per-message services may be
applied in advance of a successful completion status, the value
returned via the mech_type parameter may be undefined until the
routine returns a major status value of GSS_S_COMPLETE.
</p>

<p>The values of the GSS_C_DELEG_FLAG,
GSS_C_MUTUAL_FLAG,GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG,
GSS_C_CONF_FLAG,GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned
via the ret_flags parameter should contain the values that the
implementation expects would be valid if context establishment were
to succeed.
</p>

<p>The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
within ret_flags should indicate the actual state at the time
gss_accept_sec_context returns, whether or not the context is fully
established.
</p>

<p>Although this requires that GSS-API implementations set the
GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller
(i.e. when accompanied by a GSS_S_COMPLETE status code), applications
should not rely on this behavior as the flag was not defined in
Version 1 of the GSS-API. Instead, applications should be prepared to
use per-message services after a successful context establishment,
according to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.
</p>

<p>All other bits within the ret_flags argument should be set to zero.
While the routine returns GSS_S_CONTINUE_NEEDED, the values returned
via the ret_flags argument indicate the services that the
implementation expects to be available from the established context.
</p>

<p>If the initial call of gss_accept_sec_context() fails, the
implementation should not create a context object, and should leave
the value of the context_handle parameter set to GSS_C_NO_CONTEXT to
indicate this.  In the event of a failure on a subsequent call, the
implementation is permitted to delete the &quot;half-built&quot; security
context (in which case it should set the context_handle parameter to
GSS_C_NO_CONTEXT), but the preferred behavior is to leave the
security context (and the context_handle parameter) untouched for the
application to delete (using gss_delete_sec_context).
</p>

<p>During context establishment, the informational status bits
GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and
GSS-API mechanisms should always return them in association with a
routine error of GSS_S_FAILURE.  This requirement for pairing did not
exist in version 1 of the GSS-API specification, so applications that
wish to run over version 1 implementations must special-case these
codes.
</p>

<p>The <code>ret_flags</code> values:
</p>
<dl compact="compact">
<dd><p><code>GSS_C_DELEG_FLAG</code>
</p>


<ul>
<li> True - Delegated credentials are available via the
delegated_cred_handle parameter.

</li><li> False - No credentials were delegated.

</li></ul>
</dd>
<dd><p><code>GSS_C_MUTUAL_FLAG</code>
</p>


<ul>
<li> True - Remote peer asked for mutual authentication.

</li><li> False - Remote peer did not ask for mutual authentication.

</li></ul>
</dd>
<dd><p><code>GSS_C_REPLAY_FLAG</code>
</p>


<ul>
<li> True - replay of protected messages will be detected.

</li><li> False - replayed messages will not be detected.

</li></ul>
</dd>
<dd><p><code>GSS_C_SEQUENCE_FLAG</code>
</p>


<ul>
<li> True - out-of-sequence protected messages will be detected.

</li><li> False - out-of-sequence messages will not be detected.

</li></ul>
</dd>
<dd><p><code>GSS_C_CONF_FLAG</code>
</p>


<ul>
<li> True - Confidentiality service may be invoked by calling the
gss_wrap routine.

</li><li> False - No confidentiality service (via gss_wrap)
available. gss_wrap will provide message encapsulation, data-origin
authentication and integrity services only.

</li></ul>
</dd>
<dd><p><code>GSS_C_INTEG_FLAG</code>
</p>


<ul>
<li> True - Integrity service may be invoked by calling either
gss_get_mic or gss_wrap routines.

</li><li> False - Per-message integrity service unavailable.

</li></ul>
</dd>
<dd><p><code>GSS_C_ANON_FLAG</code>
</p>


<ul>
<li> True - The initiator does not wish to be authenticated; the
src_name parameter (if requested) contains an anonymous internal
name.

</li><li> False - The initiator has been authenticated normally.

</li></ul>
</dd>
<dd><p><code>GSS_C_PROT_READY_FLAG</code>
</p>


<ul>
<li> True - Protection services (as specified by the states of the
GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available if the
accompanying major status return value is either GSS_S_COMPLETE or
GSS_S_CONTINUE_NEEDED.

</li><li> False - Protection services (as specified by the states of the
GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available only if the
accompanying major status return value is GSS_S_COMPLETE.

</li></ul>
</dd>
<dd><p><code>GSS_C_TRANS_FLAG</code>
</p>


<ul>
<li> True - The resultant security context may be transferred to other
processes via a call to gss_export_sec_context().

</li><li> False - The security context is not transferable.

</li></ul>
</dd>
</dl>

<p>All other bits should be set to zero.
</p>
<p>Return value:
</p>

<p><code>GSS_S_CONTINUE_NEEDED</code>: Indicates that a token from the peer
application is required to complete the context, and that
gss_accept_sec_context must be called again with that token.
</p>

<p><code>GSS_S_DEFECTIVE_TOKEN</code>: Indicates that consistency checks
performed on the input_token failed.
</p>

<p><code>GSS_S_DEFECTIVE_CREDENTIAL</code>: Indicates that consistency checks
performed on the credential failed.
</p>

<p><code>GSS_S_NO_CRED</code>: The supplied credentials were not valid for
context acceptance, or the credential handle did not reference any
credentials.
</p>

<p><code>GSS_S_CREDENTIALS_EXPIRED</code>: The referenced credentials have
expired.
</p>

<p><code>GSS_S_BAD_BINDINGS</code>: The input_token contains different channel
bindings to those specified via the input_chan_bindings parameter.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: Indicates that the supplied context handle did
not refer to a valid context.
</p>

<p><code>GSS_S_BAD_SIG</code>: The input_token contains an invalid MIC.
</p>

<p><code>GSS_S_OLD_TOKEN</code>: The input_token was too old.  This is a fatal
error during context establishment.
</p>

<p><code>GSS_S_DUPLICATE_TOKEN</code>: The input_token is valid, but is a
duplicate of a token already processed.  This is a fatal error
during context establishment.
</p>

<p><code>GSS_S_BAD_MECH</code>: The received token specified a mechanism that is
not supported by the implementation or the provided credential.
</p></dd></dl>

<a name="gss_005fdelete_005fsec_005fcontext-1"></a>
<h4 class="subheading">gss_delete_sec_context</h4>
<a name="gss_005fdelete_005fsec_005fcontext"></a><dl>
<dt><a name="index-gss_005fdelete_005fsec_005fcontext"></a>Function: <em>OM_uint32</em> <strong>gss_delete_sec_context</strong> <em>(OM_uint32 * <var>minor_status</var>, gss_ctx_id_t * <var>context_handle</var>, gss_buffer_t <var>output_token</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, modify) Context handle identifying
context to delete.  After deleting the context, the GSS-API will
set this context handle to GSS_C_NO_CONTEXT.
</p>
<p><var>output_token</var>: (buffer, opaque, modify, optional) Token to be sent
to remote application to instruct it to also delete the context.
It is recommended that applications specify GSS_C_NO_BUFFER for
this parameter, requesting local deletion only.  If a buffer
parameter is provided by the application, the mechanism may
return a token in it; mechanisms that implement only local
deletion should set the length field of this token to zero to
indicate to the application that no token is to be sent to the
peer.
</p>

<p>Delete a security context.  gss_delete_sec_context will delete the
local data structures associated with the specified security
context, and may generate an output_token, which when passed to the
peer gss_process_context_token will instruct it to do likewise.  If
no token is required by the mechanism, the GSS-API should set the
length field of the output_token (if provided) to zero.  No further
security services may be obtained using the context specified by
context_handle.
</p>

<p>In addition to deleting established security contexts,
gss_delete_sec_context must also be able to delete &quot;half-built&quot;
security contexts resulting from an incomplete sequence of
gss_init_sec_context()/gss_accept_sec_context() calls.
</p>

<p>The output_token parameter is retained for compatibility with
version 1 of the GSS-API.  It is recommended that both peer
applications invoke gss_delete_sec_context passing the value
GSS_C_NO_BUFFER for the output_token parameter, indicating that no
token is required, and that gss_delete_sec_context should simply
delete local context data structures.  If the application does pass
a valid buffer to gss_delete_sec_context, mechanisms are encouraged
to return a zero-length token, indicating that no peer action is
necessary, and that no token should be transferred by the
application.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: No valid context was supplied.
</p></dd></dl>

<a name="gss_005fprocess_005fcontext_005ftoken-1"></a>
<h4 class="subheading">gss_process_context_token</h4>
<a name="gss_005fprocess_005fcontext_005ftoken"></a><dl>
<dt><a name="index-gss_005fprocess_005fcontext_005ftoken"></a>Function: <em>OM_uint32</em> <strong>gss_process_context_token</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_ctx_id_t <var>context_handle</var>, const gss_buffer_t <var>token_buffer</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Implementation specific status code.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, read) Context handle of context on
which token is to be processed
</p>
<p><var>token_buffer</var>: (buffer, opaque, read) Token to process.
</p>

<p>Provides a way to pass an asynchronous token to the security
service.  Most context-level tokens are emitted and processed
synchronously by gss_init_sec_context and gss_accept_sec_context,
and the application is informed as to whether further tokens are
expected by the GSS_C_CONTINUE_NEEDED major status bit.
Occasionally, a mechanism may need to emit a context-level token at
a point when the peer entity is not expecting a token.  For
example, the initiator&rsquo;s final call to gss_init_sec_context may
emit a token and return a status of GSS_S_COMPLETE, but the
acceptor&rsquo;s call to gss_accept_sec_context may fail.  The acceptor&rsquo;s
mechanism may wish to send a token containing an error indication
to the initiator, but the initiator is not expecting a token at
this point, believing that the context is fully established.
Gss_process_context_token provides a way to pass such a token to
the mechanism at any time.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_DEFECTIVE_TOKEN</code>: Indicates that consistency checks
performed on the token failed.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: The context_handle did not refer to a valid
context.
</p></dd></dl>

<a name="gss_005fcontext_005ftime-1"></a>
<h4 class="subheading">gss_context_time</h4>
<a name="gss_005fcontext_005ftime"></a><dl>
<dt><a name="index-gss_005fcontext_005ftime"></a>Function: <em>OM_uint32</em> <strong>gss_context_time</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_ctx_id_t <var>context_handle</var>, OM_uint32 * <var>time_rec</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Implementation specific status
code.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, read) Identifies the context to be
interrogated.
</p>
<p><var>time_rec</var>: (Integer, modify) Number of seconds that the context
will remain valid.  If the context has already expired, zero will
be returned.
</p>

<p>Determines the number of seconds for which the specified context
will remain valid.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_CONTEXT_EXPIRED</code>: The context has already expired.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: The context_handle parameter did not identify a
valid context
</p></dd></dl>

<a name="gss_005finquire_005fcontext-1"></a>
<h4 class="subheading">gss_inquire_context</h4>
<a name="gss_005finquire_005fcontext"></a><dl>
<dt><a name="index-gss_005finquire_005fcontext"></a>Function: <em>OM_uint32</em> <strong>gss_inquire_context</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_ctx_id_t <var>context_handle</var>, gss_name_t * <var>src_name</var>, gss_name_t * <var>targ_name</var>, OM_uint32 * <var>lifetime_rec</var>, gss_OID * <var>mech_type</var>, OM_uint32 * <var>ctx_flags</var>, int * <var>locally_initiated</var>, int * <var>open</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, read) A handle that refers to the
security context.
</p>
<p><var>src_name</var>: (gss_name_t, modify, optional) The name of the context
initiator.  If the context was established using anonymous
authentication, and if the application invoking
gss_inquire_context is the context acceptor, an anonymous name
will be returned.  Storage associated with this name must be
freed by the application after use with a call to
gss_release_name().  Specify NULL if not required.
</p>
<p><var>targ_name</var>: (gss_name_t, modify, optional) The name of the context
acceptor.  Storage associated with this name must be freed by the
application after use with a call to gss_release_name().  If the
context acceptor did not authenticate itself, and if the
initiator did not specify a target name in its call to
gss_init_sec_context(), the value GSS_C_NO_NAME will be returned.
Specify NULL if not required.
</p>
<p><var>lifetime_rec</var>: (Integer, modify, optional) The number of seconds
for which the context will remain valid.  If the context has
expired, this parameter will be set to zero.  If the
implementation does not support context expiration, the value
GSS_C_INDEFINITE will be returned.  Specify NULL if not required.
</p>
<p><var>mech_type</var>: (gss_OID, modify, optional) The security mechanism
providing the context.  The returned OID will be a pointer to
static storage that should be treated as read-only by the
application; in particular the application should not attempt to
free it.  Specify NULL if not required.
</p>
<p><var>ctx_flags</var>: (bit-mask, modify, optional) Contains various
independent flags, each of which indicates that the context
supports (or is expected to support, if ctx_open is false) a
specific service option.  If not needed, specify NULL.  Symbolic
names are provided for each flag, and the symbolic names
corresponding to the required flags should be logically-ANDed
with the ret_flags value to test whether a given option is
supported by the context.  See below for the flags.
</p>
<p><var>locally_initiated</var>: (Boolean, modify) Non-zero if the invoking
application is the context initiator.  Specify NULL if not
required.
</p>
<p><var>open</var>: (Boolean, modify) Non-zero if the context is fully
established; Zero if a context-establishment token is expected
from the peer application.  Specify NULL if not required.
</p>

<p>Obtains information about a security context.  The caller must
already have obtained a handle that refers to the context, although
the context need not be fully established.
</p>

<p>The <code>ctx_flags</code> values:
</p>
<dl compact="compact">
<dd><p><code>GSS_C_DELEG_FLAG</code>
</p>


<ul>
<li> True - Credentials were delegated from the initiator to the
acceptor.

</li><li> False - No credentials were delegated.

</li></ul>
</dd>
<dd><p><code>GSS_C_MUTUAL_FLAG</code>
</p>


<ul>
<li> True - The acceptor was authenticated to the initiator.

</li><li> False - The acceptor did not authenticate itself.

</li></ul>
</dd>
<dd><p><code>GSS_C_REPLAY_FLAG</code>
</p>


<ul>
<li> True - replay of protected messages will be detected.

</li><li> False - replayed messages will not be detected.

</li></ul>
</dd>
<dd><p><code>GSS_C_SEQUENCE_FLAG</code>
</p>


<ul>
<li> True - out-of-sequence protected messages will be detected.

</li><li> False - out-of-sequence messages will not be detected.

</li></ul>
</dd>
<dd><p><code>GSS_C_CONF_FLAG</code>
</p>


<ul>
<li> True - Confidentiality service may be invoked by calling gss_wrap
routine.

</li><li> False - No confidentiality service (via gss_wrap)
available. gss_wrap will provide message encapsulation, data-origin
authentication and integrity services only.

</li></ul>
</dd>
<dd><p><code>GSS_C_INTEG_FLAG</code>
</p>


<ul>
<li> True - Integrity service may be invoked by calling either
gss_get_mic or gss_wrap routines.

</li><li> False - Per-message integrity service unavailable.

</li></ul>
</dd>
<dd><p><code>GSS_C_ANON_FLAG</code>
</p>


<ul>
<li> True - The initiator&rsquo;s identity will not be revealed to the
acceptor.  The src_name parameter (if requested) contains an
anonymous internal name.

</li><li> False - The initiator has been authenticated normally.

</li></ul>
</dd>
<dd><p><code>GSS_C_PROT_READY_FLAG</code>
</p>


<ul>
<li> True - Protection services (as specified by the states of the
GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available for use.

</li><li> False - Protection services (as specified by the states of the
GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available only if the
context is fully established (i.e. if the open parameter is
non-zero).

</li></ul>
</dd>
<dd><p><code>GSS_C_TRANS_FLAG</code>
</p>


<ul>
<li> True - The resultant security context may be transferred to other
processes via a call to gss_export_sec_context().

</li><li> False - The security context is not transferable.

</li></ul>
</dd>
</dl>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: The referenced context could not be accessed.
</p></dd></dl>

<a name="gss_005fwrap_005fsize_005flimit-1"></a>
<h4 class="subheading">gss_wrap_size_limit</h4>
<a name="gss_005fwrap_005fsize_005flimit"></a><dl>
<dt><a name="index-gss_005fwrap_005fsize_005flimit"></a>Function: <em>OM_uint32</em> <strong>gss_wrap_size_limit</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_ctx_id_t <var>context_handle</var>, int <var>conf_req_flag</var>, gss_qop_t <var>qop_req</var>, OM_uint32 <var>req_output_size</var>, OM_uint32 * <var>max_input_size</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, read) A handle that refers to the
security over which the messages will be sent.
</p>
<p><var>conf_req_flag</var>: (Boolean, read) Indicates whether gss_wrap will be
asked to apply confidentiality protection in addition to
integrity protection.  See the routine description for gss_wrap
for more details.
</p>
<p><var>qop_req</var>: (gss_qop_t, read) Indicates the level of protection that
gss_wrap will be asked to provide.  See the routine description
for gss_wrap for more details.
</p>
<p><var>req_output_size</var>: (Integer, read) The desired maximum size for
tokens emitted by gss_wrap.
</p>
<p><var>max_input_size</var>: (Integer, modify) The maximum input message size
that may be presented to gss_wrap in order to guarantee that the
emitted token shall be no larger than req_output_size bytes.
</p>

<p>Allows an application to determine the maximum message size that,
if presented to gss_wrap with the same conf_req_flag and qop_req
parameters, will result in an output token containing no more than
req_output_size bytes.
</p>

<p>This call is intended for use by applications that communicate over
protocols that impose a maximum message size.  It enables the
application to fragment messages prior to applying protection.
</p>

<p>GSS-API implementations are recommended but not required to detect
invalid QOP values when gss_wrap_size_limit() is called. This
routine guarantees only a maximum message size, not the
availability of specific QOP values for message protection.
</p>

<p>Successful completion of this call does not guarantee that gss_wrap
will be able to protect a message of length max_input_size bytes,
since this ability may depend on the availability of system
resources at the time that gss_wrap is called.  However, if the
implementation itself imposes an upper limit on the length of
messages that may be processed by gss_wrap, the implementation
should not return a value via max_input_bytes that is greater than
this length.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: The referenced context could not be accessed.
</p>

<p><code>GSS_S_CONTEXT_EXPIRED</code>: The context has expired.
</p>

<p><code>GSS_S_BAD_QOP</code>: The specified QOP is not supported by the
mechanism.
</p></dd></dl>

<a name="gss_005fexport_005fsec_005fcontext-1"></a>
<h4 class="subheading">gss_export_sec_context</h4>
<a name="gss_005fexport_005fsec_005fcontext"></a><dl>
<dt><a name="index-gss_005fexport_005fsec_005fcontext"></a>Function: <em>OM_uint32</em> <strong>gss_export_sec_context</strong> <em>(OM_uint32 * <var>minor_status</var>, gss_ctx_id_t * <var>context_handle</var>, gss_buffer_t <var>interprocess_token</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, modify) Context handle identifying
the context to transfer.
</p>
<p><var>interprocess_token</var>: (buffer, opaque, modify) Token to be
transferred to target process.  Storage associated with this
token must be freed by the application after use with a call to
gss_release_buffer().
</p>

<p>Provided to support the sharing of work between multiple processes.
This routine will typically be used by the context-acceptor, in an
application where a single process receives incoming connection
requests and accepts security contexts over them, then passes the
established context to one or more other processes for message
exchange. gss_export_sec_context() deactivates the security context
for the calling process and creates an interprocess token which,
when passed to gss_import_sec_context in another process, will
re-activate the context in the second process. Only a single
instantiation of a given context may be active at any one time; a
subsequent attempt by a context exporter to access the exported
security context will fail.
</p>

<p>The implementation may constrain the set of processes by which the
interprocess token may be imported, either as a function of local
security policy, or as a result of implementation decisions.  For
example, some implementations may constrain contexts to be passed
only between processes that run under the same account, or which
are part of the same process group.
</p>

<p>The interprocess token may contain security-sensitive information
(for example cryptographic keys).  While mechanisms are encouraged
to either avoid placing such sensitive information within
interprocess tokens, or to encrypt the token before returning it to
the application, in a typical object-library GSS-API implementation
this may not be possible. Thus the application must take care to
protect the interprocess token, and ensure that any process to
which the token is transferred is trustworthy.
</p>

<p>If creation of the interprocess token is successful, the
implementation shall deallocate all process-wide resources
associated with the security context, and set the context_handle to
GSS_C_NO_CONTEXT.  In the event of an error that makes it
impossible to complete the export of the security context, the
implementation must not return an interprocess token, and should
strive to leave the security context referenced by the
context_handle parameter untouched.  If this is impossible, it is
permissible for the implementation to delete the security context,
providing it also sets the context_handle parameter to
GSS_C_NO_CONTEXT.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_CONTEXT_EXPIRED</code>: The context has expired.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: The context was invalid.
</p>

<p><code>GSS_S_UNAVAILABLE</code>: The operation is not supported.
</p></dd></dl>

<a name="gss_005fimport_005fsec_005fcontext-1"></a>
<h4 class="subheading">gss_import_sec_context</h4>
<a name="gss_005fimport_005fsec_005fcontext"></a><dl>
<dt><a name="index-gss_005fimport_005fsec_005fcontext"></a>Function: <em>OM_uint32</em> <strong>gss_import_sec_context</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_buffer_t <var>interprocess_token</var>, gss_ctx_id_t * <var>context_handle</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>interprocess_token</var>: (buffer, opaque, modify) Token received from
exporting process
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, modify) Context handle of newly
reactivated context.  Resources associated with this context
handle must be released by the application after use with a call
to gss_delete_sec_context().
</p>

<p>Allows a process to import a security context established by
another process.  A given interprocess token may be imported only
once.  See gss_export_sec_context.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: The token did not contain a valid context
reference.
</p>

<p><code>GSS_S_DEFECTIVE_TOKEN</code>: The token was invalid.
</p>

<p><code>GSS_S_UNAVAILABLE</code>: The operation is unavailable.
</p>

<p><code>GSS_S_UNAUTHORIZED</code>: Local policy prevents the import of this
 context by the current process.
</p></dd></dl>


<hr>
<a name="Per_002dMessage-Routines"></a>
<div class="header">
<p>
Next: <a href="#Name-Manipulation" accesskey="n" rel="next">Name Manipulation</a>, Previous: <a href="#Context_002dLevel-Routines" accesskey="p" rel="prev">Context-Level Routines</a>, Up: <a href="#Standard-GSS-API" accesskey="u" rel="up">Standard GSS API</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Per_002dMessage-Routines-1"></a>
<h3 class="section">3.7 Per-Message Routines</h3>

<pre class="verbatim">   GSS-API Per-message Routines

   Routine                         Function
   -------                         --------
   gss_get_mic                     Calculate a cryptographic message
                                   integrity code (MIC) for a
                                   message; integrity service.
   gss_verify_mic                  Check a MIC against a message;
                                   verify integrity of a received
                                   message.
   gss_wrap                        Attach a MIC to a message, and
                                   optionally encrypt the message
                                   content.
                                   confidentiality service
   gss_unwrap                      Verify a message with attached
                                   MIC, and decrypt message content
                                   if necessary.
</pre>
<a name="gss_005fget_005fmic-1"></a>
<h4 class="subheading">gss_get_mic</h4>
<a name="gss_005fget_005fmic"></a><dl>
<dt><a name="index-gss_005fget_005fmic"></a>Function: <em>OM_uint32</em> <strong>gss_get_mic</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_ctx_id_t <var>context_handle</var>, gss_qop_t <var>qop_req</var>, const gss_buffer_t <var>message_buffer</var>, gss_buffer_t <var>message_token</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, read) Identifies the context on
which the message will be sent.
</p>
<p><var>qop_req</var>: (gss_qop_t, read, optional) Specifies requested quality
of protection.  Callers are encouraged, on portability grounds,
to accept the default quality of protection offered by the chosen
mechanism, which may be requested by specifying GSS_C_QOP_DEFAULT
for this parameter.  If an unsupported protection strength is
requested, gss_get_mic will return a major_status of
GSS_S_BAD_QOP.
</p>
<p><var>message_buffer</var>: (buffer, opaque, read) Message to be protected.
</p>
<p><var>message_token</var>: (buffer, opaque, modify) Buffer to receive token.  The
application must free storage associated with this buffer after
use with a call to gss_release_buffer().
</p>

<p>Generates a cryptographic MIC for the supplied message, and places
the MIC in a token for transfer to the peer application. The
qop_req parameter allows a choice between several cryptographic
algorithms, if supported by the chosen mechanism.
</p>

<p>Since some application-level protocols may wish to use tokens
emitted by gss_wrap() to provide &quot;secure framing&quot;, implementations
must support derivation of MICs from zero-length messages.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_CONTEXT_EXPIRED</code>: The context has already expired.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: The context_handle parameter did not identify a
valid context.
</p>

<p><code>GSS_S_BAD_QOP</code>: The specified QOP is not supported by the
mechanism.
</p></dd></dl>

<a name="gss_005fverify_005fmic-1"></a>
<h4 class="subheading">gss_verify_mic</h4>
<a name="gss_005fverify_005fmic"></a><dl>
<dt><a name="index-gss_005fverify_005fmic"></a>Function: <em>OM_uint32</em> <strong>gss_verify_mic</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_ctx_id_t <var>context_handle</var>, const gss_buffer_t <var>message_buffer</var>, const gss_buffer_t <var>token_buffer</var>, gss_qop_t * <var>qop_state</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, read) Identifies the context on
which the message arrived.
</p>
<p><var>message_buffer</var>: (buffer, opaque, read) Message to be verified.
</p>
<p><var>token_buffer</var>: (buffer, opaque, read) Token associated with
message.
</p>
<p><var>qop_state</var>: (gss_qop_t, modify, optional) Quality of protection
gained from MIC Specify NULL if not required.
</p>

<p>Verifies that a cryptographic MIC, contained in the token
parameter, fits the supplied message.  The qop_state parameter
allows a message recipient to determine the strength of protection
that was applied to the message.
</p>

<p>Since some application-level protocols may wish to use tokens
emitted by gss_wrap() to provide &quot;secure framing&quot;, implementations
must support the calculation and verification of MICs over
zero-length messages.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_DEFECTIVE_TOKEN</code>: The token failed consistency checks.
</p>

<p><code>GSS_S_BAD_SIG</code>: The MIC was incorrect.
</p>

<p><code>GSS_S_DUPLICATE_TOKEN</code>: The token was valid, and contained a
correct MIC for the message, but it had already been processed.
</p>

<p><code>GSS_S_OLD_TOKEN</code>: The token was valid, and contained a correct MIC
for the message, but it is too old to check for duplication.
</p>

<p><code>GSS_S_UNSEQ_TOKEN</code>: The token was valid, and contained a correct
MIC for the message, but has been verified out of sequence; a later
token has already been received.
</p>

<p><code>GSS_S_GAP_TOKEN</code>: The token was valid, and contained a correct MIC
for the message, but has been verified out of sequence; an earlier
expected token has not yet been received.
</p>

<p><code>GSS_S_CONTEXT_EXPIRED</code>: The context has already expired.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: The context_handle parameter did not identify a
valid context.
</p></dd></dl>

<a name="gss_005fwrap-1"></a>
<h4 class="subheading">gss_wrap</h4>
<a name="gss_005fwrap"></a><dl>
<dt><a name="index-gss_005fwrap"></a>Function: <em>OM_uint32</em> <strong>gss_wrap</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_ctx_id_t <var>context_handle</var>, int <var>conf_req_flag</var>, gss_qop_t <var>qop_req</var>, const gss_buffer_t <var>input_message_buffer</var>, int * <var>conf_state</var>, gss_buffer_t <var>output_message_buffer</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, read) Identifies the context on
which the message will be sent.
</p>
<p><var>conf_req_flag</var>: (boolean, read) Non-zero - Both confidentiality and
integrity services are requested. Zero - Only integrity service is
requested.
</p>
<p><var>qop_req</var>: (gss_qop_t, read, optional) Specifies required quality of
protection.  A mechanism-specific default may be requested by
setting qop_req to GSS_C_QOP_DEFAULT.  If an unsupported
protection strength is requested, gss_wrap will return a
major_status of GSS_S_BAD_QOP.
</p>
<p><var>input_message_buffer</var>: (buffer, opaque, read) Message to be
protected.
</p>
<p><var>conf_state</var>: (boolean, modify, optional) Non-zero -
Confidentiality, data origin authentication and integrity
services have been applied. Zero - Integrity and data origin
services only has been applied.  Specify NULL if not required.
</p>
<p><var>output_message_buffer</var>: (buffer, opaque, modify) Buffer to receive
protected message.  Storage associated with this message must be
freed by the application after use with a call to
gss_release_buffer().
</p>

<p>Attaches a cryptographic MIC and optionally encrypts the specified
input_message.  The output_message contains both the MIC and the
message.  The qop_req parameter allows a choice between several
cryptographic algorithms, if supported by the chosen mechanism.
</p>

<p>Since some application-level protocols may wish to use tokens
emitted by gss_wrap() to provide &quot;secure framing&quot;, implementations
must support the wrapping of zero-length messages.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_CONTEXT_EXPIRED</code>: The context has already expired.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: The context_handle parameter did not identify a
 valid context.
</p>

<p><code>GSS_S_BAD_QOP</code>: The specified QOP is not supported by the
mechanism.
</p></dd></dl>

<a name="gss_005funwrap-1"></a>
<h4 class="subheading">gss_unwrap</h4>
<a name="gss_005funwrap"></a><dl>
<dt><a name="index-gss_005funwrap"></a>Function: <em>OM_uint32</em> <strong>gss_unwrap</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_ctx_id_t <var>context_handle</var>, const gss_buffer_t <var>input_message_buffer</var>, gss_buffer_t <var>output_message_buffer</var>, int * <var>conf_state</var>, gss_qop_t * <var>qop_state</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>context_handle</var>: (gss_ctx_id_t, read) Identifies the context on
which the message arrived.
</p>
<p><var>input_message_buffer</var>: (buffer, opaque, read) Protected message.
</p>
<p><var>output_message_buffer</var>: (buffer, opaque, modify) Buffer to receive
unwrapped message.  Storage associated with this buffer must be
freed by the application after use use with a call to
gss_release_buffer().
</p>
<p><var>conf_state</var>: (boolean, modify, optional) Non-zero - Confidentiality
and integrity protection were used. Zero - Integrity service only
was used.  Specify NULL if not required.
</p>
<p><var>qop_state</var>: (gss_qop_t, modify, optional) Quality of protection
provided.  Specify NULL if not required.
</p>

<p>Converts a message previously protected by gss_wrap back to a
usable form, verifying the embedded MIC.  The conf_state parameter
indicates whether the message was encrypted; the qop_state
parameter indicates the strength of protection that was used to
provide the confidentiality and integrity services.
</p>

<p>Since some application-level protocols may wish to use tokens
emitted by gss_wrap() to provide &quot;secure framing&quot;, implementations
must support the wrapping and unwrapping of zero-length messages.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_DEFECTIVE_TOKEN</code>: The token failed consistency checks.
</p>

<p><code>GSS_S_BAD_SIG</code>: The MIC was incorrect.
</p>

<p><code>GSS_S_DUPLICATE_TOKEN</code>: The token was valid, and contained a
 correct MIC for the message, but it had already been processed.
</p>

<p><code>GSS_S_OLD_TOKEN</code>: The token was valid, and contained a correct MIC
for the message, but it is too old to check for duplication.
</p>

<p><code>GSS_S_UNSEQ_TOKEN</code>: The token was valid, and contained a correct
MIC for the message, but has been verified out of sequence; a later
token has already been received.
</p>

<p><code>GSS_S_GAP_TOKEN</code>: The token was valid, and contained a correct MIC
for the message, but has been verified out of sequence; an earlier
expected token has not yet been received.
</p>

<p><code>GSS_S_CONTEXT_EXPIRED</code>: The context has already expired.
</p>

<p><code>GSS_S_NO_CONTEXT</code>: The context_handle parameter did not identify a
valid context.
</p></dd></dl>


<hr>
<a name="Name-Manipulation"></a>
<div class="header">
<p>
Next: <a href="#Miscellaneous-Routines" accesskey="n" rel="next">Miscellaneous Routines</a>, Previous: <a href="#Per_002dMessage-Routines" accesskey="p" rel="prev">Per-Message Routines</a>, Up: <a href="#Standard-GSS-API" accesskey="u" rel="up">Standard GSS API</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Name-Manipulation-1"></a>
<h3 class="section">3.8 Name Manipulation</h3>

<pre class="verbatim">   GSS-API Name manipulation Routines

   Routine                         Function
   -------                         --------
   gss_import_name                 Convert a contiguous string name
                                   to internal-form.
   gss_display_name                Convert internal-form name to
                                   text.
   gss_compare_name                Compare two internal-form names.
   gss_release_name                Discard an internal-form name.
   gss_inquire_names_for_mech      List the name-types supported by.
                                   the specified mechanism.
   gss_inquire_mechs_for_name      List mechanisms that support the
                                   specified name-type.
   gss_canonicalize_name           Convert an internal name to an MN.
   gss_export_name                 Convert an MN to export form.
   gss_duplicate_name              Create a copy of an internal name.
</pre>
<a name="gss_005fimport_005fname-1"></a>
<h4 class="subheading">gss_import_name</h4>
<a name="gss_005fimport_005fname"></a><dl>
<dt><a name="index-gss_005fimport_005fname"></a>Function: <em>OM_uint32</em> <strong>gss_import_name</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_buffer_t <var>input_name_buffer</var>, const gss_OID <var>input_name_type</var>, gss_name_t * <var>output_name</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>input_name_buffer</var>: (buffer, octet-string, read) Buffer containing
contiguous string name to convert.
</p>
<p><var>input_name_type</var>: (Object ID, read, optional) Object ID specifying
type of printable name.  Applications may specify either
GSS_C_NO_OID to use a mechanism-specific default printable
syntax, or an OID recognized by the GSS-API implementation to
name a specific namespace.
</p>
<p><var>output_name</var>: (gss_name_t, modify) Returned name in internal form.
Storage associated with this name must be freed by the
application after use with a call to gss_release_name().
</p>

<p>Convert a contiguous string name to internal form.  In general, the
internal name returned (via the @output_name parameter) will not
be an MN; the exception to this is if the @input_name_type
indicates that the contiguous string provided via the
@input_name_buffer parameter is of type GSS_C_NT_EXPORT_NAME, in
which case the returned internal name will be an MN for the
mechanism that exported the name.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_BAD_NAMETYPE</code>: The input_name_type was unrecognized.
</p>

<p><code>GSS_S_BAD_NAME</code>: The input_name parameter could not be interpreted
as a name of the specified type.
</p>

<p><code>GSS_S_BAD_MECH</code>: The input name-type was GSS_C_NT_EXPORT_NAME, but
the mechanism contained within the input-name is not supported.
</p></dd></dl>

<a name="gss_005fdisplay_005fname-1"></a>
<h4 class="subheading">gss_display_name</h4>
<a name="gss_005fdisplay_005fname"></a><dl>
<dt><a name="index-gss_005fdisplay_005fname"></a>Function: <em>OM_uint32</em> <strong>gss_display_name</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_name_t <var>input_name</var>, gss_buffer_t <var>output_name_buffer</var>, gss_OID * <var>output_name_type</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>input_name</var>: (gss_name_t, read) Name to be displayed.
</p>
<p><var>output_name_buffer</var>: (buffer, character-string, modify) Buffer to
receive textual name string.  The application must free storage
associated with this name after use with a call to
gss_release_buffer().
</p>
<p><var>output_name_type</var>: (Object ID, modify, optional) The type of the
returned name.  The returned gss_OID will be a pointer into
static storage, and should be treated as read-only by the caller
(in particular, the application should not attempt to free
it). Specify NULL if not required.
</p>

<p>Allows an application to obtain a textual representation of an
opaque internal-form name for display purposes.  The syntax of a
printable name is defined by the GSS-API implementation.
</p>

<p>If input_name denotes an anonymous principal, the implementation
should return the gss_OID value GSS_C_NT_ANONYMOUS as the
output_name_type, and a textual name that is syntactically distinct
from all valid supported printable names in output_name_buffer.
</p>

<p>If input_name was created by a call to gss_import_name, specifying
GSS_C_NO_OID as the name-type, implementations that employ lazy
conversion between name types may return GSS_C_NO_OID via the
output_name_type parameter.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_BAD_NAME</code>: @input_name was ill-formed.
</p></dd></dl>

<a name="gss_005fcompare_005fname-1"></a>
<h4 class="subheading">gss_compare_name</h4>
<a name="gss_005fcompare_005fname"></a><dl>
<dt><a name="index-gss_005fcompare_005fname"></a>Function: <em>OM_uint32</em> <strong>gss_compare_name</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_name_t <var>name1</var>, const gss_name_t <var>name2</var>, int * <var>name_equal</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>name1</var>: (gss_name_t, read) Internal-form name.
</p>
<p><var>name2</var>: (gss_name_t, read) Internal-form name.
</p>
<p><var>name_equal</var>: (boolean, modify) Non-zero - names refer to same
entity. Zero - names refer to different entities (strictly, the
names are not known to refer to the same identity).
</p>

<p>Allows an application to compare two internal-form names to
determine whether they refer to the same entity.
</p>

<p>If either name presented to gss_compare_name denotes an anonymous
principal, the routines should indicate that the two names do not
refer to the same identity.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_BAD_NAMETYPE</code>: The two names were of incomparable types.
</p>

<p><code>GSS_S_BAD_NAME</code>: One or both of name1 or name2 was ill-formed.
</p></dd></dl>

<a name="gss_005frelease_005fname-1"></a>
<h4 class="subheading">gss_release_name</h4>
<a name="gss_005frelease_005fname"></a><dl>
<dt><a name="index-gss_005frelease_005fname"></a>Function: <em>OM_uint32</em> <strong>gss_release_name</strong> <em>(OM_uint32 * <var>minor_status</var>, gss_name_t * <var>name</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>name</var>: (gss_name_t, modify) The name to be deleted.
</p>

<p>Free GSSAPI-allocated storage associated with an internal-form
name.  The name is set to GSS_C_NO_NAME on successful completion of
this call.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_BAD_NAME</code>: The name parameter did not contain a valid name.
</p></dd></dl>

<a name="gss_005finquire_005fnames_005ffor_005fmech-1"></a>
<h4 class="subheading">gss_inquire_names_for_mech</h4>
<a name="gss_005finquire_005fnames_005ffor_005fmech"></a><dl>
<dt><a name="index-gss_005finquire_005fnames_005ffor_005fmech"></a>Function: <em>OM_uint32</em> <strong>gss_inquire_names_for_mech</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_OID <var>mechanism</var>, gss_OID_set * <var>name_types</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>mechanism</var>: (gss_OID, read) The mechanism to be interrogated.
</p>
<p><var>name_types</var>: (gss_OID_set, modify) Set of name-types supported by
the specified mechanism.  The returned OID set must be freed by
the application after use with a call to gss_release_oid_set().
</p>

<p>Returns the set of nametypes supported by the specified mechanism.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p></dd></dl>

<a name="gss_005finquire_005fmechs_005ffor_005fname-1"></a>
<h4 class="subheading">gss_inquire_mechs_for_name</h4>
<a name="gss_005finquire_005fmechs_005ffor_005fname"></a><dl>
<dt><a name="index-gss_005finquire_005fmechs_005ffor_005fname"></a>Function: <em>OM_uint32</em> <strong>gss_inquire_mechs_for_name</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_name_t <var>input_name</var>, gss_OID_set * <var>mech_types</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>input_name</var>: (gss_name_t, read) The name to which the inquiry
relates.
</p>
<p><var>mech_types</var>: (gss_OID_set, modify) Set of mechanisms that may
support the specified name.  The returned OID set must be freed
by the caller after use with a call to gss_release_oid_set().
</p>

<p>Returns the set of mechanisms supported by the GSS-API
implementation that may be able to process the specified name.
</p>

<p>Each mechanism returned will recognize at least one element within
the name.  It is permissible for this routine to be implemented
within a mechanism-independent GSS-API layer, using the type
information contained within the presented name, and based on
registration information provided by individual mechanism
implementations.  This means that the returned mech_types set may
indicate that a particular mechanism will understand the name when
in fact it would refuse to accept the name as input to
gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred or
gss_add_cred (due to some property of the specific name, as opposed
to the name type).  Thus this routine should be used only as a
prefilter for a call to a subsequent mechanism-specific routine.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_BAD_NAME</code>: The input_name parameter was ill-formed.
</p>

<p><code>GSS_S_BAD_NAMETYPE</code>: The input_name parameter contained an invalid
or unsupported type of name.
</p></dd></dl>

<a name="gss_005fcanonicalize_005fname-1"></a>
<h4 class="subheading">gss_canonicalize_name</h4>
<a name="gss_005fcanonicalize_005fname"></a><dl>
<dt><a name="index-gss_005fcanonicalize_005fname"></a>Function: <em>OM_uint32</em> <strong>gss_canonicalize_name</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_name_t <var>input_name</var>, const gss_OID <var>mech_type</var>, gss_name_t * <var>output_name</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>input_name</var>: (gss_name_t, read) The name for which a canonical form
is desired.
</p>
<p><var>mech_type</var>: (Object ID, read) The authentication mechanism for
which the canonical form of the name is desired.  The desired
mechanism must be specified explicitly; no default is provided.
</p>
<p><var>output_name</var>: (gss_name_t, modify) The resultant canonical name.
Storage associated with this name must be freed by the
application after use with a call to gss_release_name().
</p>

<p>Generate a canonical mechanism name (MN) from an arbitrary internal
name.  The mechanism name is the name that would be returned to a
context acceptor on successful authentication of a context where
the initiator used the input_name in a successful call to
gss_acquire_cred, specifying an OID set containing @mech_type as
its only member, followed by a call to gss_init_sec_context(),
specifying @mech_type as the authentication mechanism.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p></dd></dl>

<a name="gss_005fexport_005fname-1"></a>
<h4 class="subheading">gss_export_name</h4>
<a name="gss_005fexport_005fname"></a><dl>
<dt><a name="index-gss_005fexport_005fname"></a>Function: <em>OM_uint32</em> <strong>gss_export_name</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_name_t <var>input_name</var>, gss_buffer_t <var>exported_name</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>input_name</var>: (gss_name_t, read) The MN to be exported.
</p>
<p><var>exported_name</var>: (gss_buffer_t, octet-string, modify) The canonical
contiguous string form of @input_name.  Storage associated with
this string must freed by the application after use with
gss_release_buffer().
</p>

<p>To produce a canonical contiguous string representation of a
mechanism name (MN), suitable for direct comparison (e.g. with
memcmp) for use in authorization functions (e.g. matching entries
in an access-control list).  The @input_name parameter must specify
a valid MN (i.e. an internal name generated by
gss_accept_sec_context() or by gss_canonicalize_name()).
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_NAME_NOT_MN</code>: The provided internal name was not a mechanism
name.
</p>

<p><code>GSS_S_BAD_NAME</code>: The provided internal name was ill-formed.
</p>

<p><code>GSS_S_BAD_NAMETYPE</code>: The internal name was of a type not supported
by the GSS-API implementation.
</p></dd></dl>

<a name="gss_005fduplicate_005fname-1"></a>
<h4 class="subheading">gss_duplicate_name</h4>
<a name="gss_005fduplicate_005fname"></a><dl>
<dt><a name="index-gss_005fduplicate_005fname"></a>Function: <em>OM_uint32</em> <strong>gss_duplicate_name</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_name_t <var>src_name</var>, gss_name_t * <var>dest_name</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>src_name</var>: (gss_name_t, read) Internal name to be duplicated.
</p>
<p><var>dest_name</var>: (gss_name_t, modify) The resultant copy of @src_name.
Storage associated with this name must be freed by the application
after use with a call to gss_release_name().
</p>

<p>Create an exact duplicate of the existing internal name @src_name.
The new @dest_name will be independent of src_name (i.e. @src_name
and @dest_name must both be released, and the release of one shall
not affect the validity of the other).
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_BAD_NAME</code>: The src_name parameter was ill-formed.
</p></dd></dl>


<hr>
<a name="Miscellaneous-Routines"></a>
<div class="header">
<p>
Next: <a href="#SASL-GS2-Routines" accesskey="n" rel="next">SASL GS2 Routines</a>, Previous: <a href="#Name-Manipulation" accesskey="p" rel="prev">Name Manipulation</a>, Up: <a href="#Standard-GSS-API" accesskey="u" rel="up">Standard GSS API</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Miscellaneous-Routines-1"></a>
<h3 class="section">3.9 Miscellaneous Routines</h3>

<pre class="verbatim">   GSS-API Miscellaneous Routines

   Routine                        Function
   -------                        --------
   gss_add_oid_set_member         Add an object identifier to
                                  a set.
   gss_display_status             Convert a GSS-API status code
                                  to text.
   gss_indicate_mechs             Determine available underlying
                                  authentication mechanisms.
   gss_release_buffer             Discard a buffer.
   gss_release_oid_set            Discard a set of object
                                  identifiers.
   gss_create_empty_oid_set       Create a set containing no
                                  object identifiers.
   gss_test_oid_set_member        Determines whether an object
                                  identifier is a member of a set.
   gss_encapsulate_token          Encapsulate a context token.
   gss_decapsulate_token          Decapsulate a context token.
   gss_oid_equal                  Compare two OIDs for equality.
</pre>
<a name="gss_005fadd_005foid_005fset_005fmember-1"></a>
<h4 class="subheading">gss_add_oid_set_member</h4>
<a name="gss_005fadd_005foid_005fset_005fmember"></a><dl>
<dt><a name="index-gss_005fadd_005foid_005fset_005fmember"></a>Function: <em>OM_uint32</em> <strong>gss_add_oid_set_member</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_OID <var>member_oid</var>, gss_OID_set * <var>oid_set</var>)</em></dt>
<dd><p><var>minor_status</var>: (integer, modify) Mechanism specific status code.
</p>
<p><var>member_oid</var>: (Object ID, read) The object identifier to copied into
the set.
</p>
<p><var>oid_set</var>: (Set of Object ID, modify) The set in which the object
identifier should be inserted.
</p>

<p>Add an Object Identifier to an Object Identifier set.  This routine
is intended for use in conjunction with gss_create_empty_oid_set
when constructing a set of mechanism OIDs for input to
gss_acquire_cred.  The oid_set parameter must refer to an OID-set
that was created by GSS-API (e.g. a set returned by
gss_create_empty_oid_set()). GSS-API creates a copy of the
member_oid and inserts this copy into the set, expanding the
storage allocated to the OID-set&rsquo;s elements array if necessary.
The routine may add the new member OID anywhere within the elements
array, and implementations should verify that the new member_oid is
not already contained within the elements array; if the member_oid
is already present, the oid_set should remain unchanged.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p></dd></dl>

<a name="gss_005fdisplay_005fstatus-1"></a>
<h4 class="subheading">gss_display_status</h4>
<a name="gss_005fdisplay_005fstatus"></a><dl>
<dt><a name="index-gss_005fdisplay_005fstatus"></a>Function: <em>OM_uint32</em> <strong>gss_display_status</strong> <em>(OM_uint32 * <var>minor_status</var>, OM_uint32 <var>status_value</var>, int <var>status_type</var>, const gss_OID <var>mech_type</var>, OM_uint32 * <var>message_context</var>, gss_buffer_t <var>status_string</var>)</em></dt>
<dd><p><var>minor_status</var>: (integer, modify) Mechanism specific status code.
</p>
<p><var>status_value</var>: (Integer, read) Status value to be converted.
</p>
<p><var>status_type</var>: (Integer, read) GSS_C_GSS_CODE - status_value is a
GSS status code. GSS_C_MECH_CODE - status_value is a mechanism
status code.
</p>
<p><var>mech_type</var>: (Object ID, read, optional) Underlying mechanism (used
to interpret a minor status value). Supply GSS_C_NO_OID to obtain
the system default.
</p>
<p><var>message_context</var>: (Integer, read/modify) Should be initialized to
zero by the application prior to the first call.  On return from
gss_display_status(), a non-zero status_value parameter indicates
that additional messages may be extracted from the status code
via subsequent calls to gss_display_status(), passing the same
status_value, status_type, mech_type, and message_context
parameters.
</p>
<p><var>status_string</var>: (buffer, character string, modify) Textual
interpretation of the status_value.  Storage associated with this
parameter must be freed by the application after use with a call
to gss_release_buffer().
</p>

<p>Allows an application to obtain a textual representation of a
GSS-API status code, for display to the user or for logging
purposes.  Since some status values may indicate multiple
conditions, applications may need to call gss_display_status
multiple times, each call generating a single text string.  The
message_context parameter is used by gss_display_status to store
state information about which error messages have already been
extracted from a given status_value; message_context must be
initialized to 0 by the application prior to the first call, and
gss_display_status will return a non-zero value in this parameter
if there are further messages to extract.
</p>

<p>The message_context parameter contains all state information
required by gss_display_status in order to extract further messages
from the status_value; even when a non-zero value is returned in
this parameter, the application is not required to call
gss_display_status again unless subsequent messages are desired.
The following code extracts all messages from a given status code
and prints them to stderr:
</p>
<div class="example">
<pre class="example">OM_uint32 message_context;
OM_uint32 status_code;
OM_uint32 maj_status;
OM_uint32 min_status;
gss_buffer_desc status_string;

       ...

message_context = 0;

do {
  maj_status = gss_display_status (
                  &amp;min_status,
                  status_code,
                  GSS_C_GSS_CODE,
                  GSS_C_NO_OID,
                  &amp;message_context,
                  &amp;status_string)

  fprintf(stderr,
          &quot;%.*s\n&quot;,
         (int)status_string.length,

         (char *)status_string.value);

  gss_release_buffer(&amp;min_status, &amp;status_string);

} while (message_context != 0);
</pre></div>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_BAD_MECH</code>: Indicates that translation in accordance with an
unsupported mechanism type was requested.
</p>

<p><code>GSS_S_BAD_STATUS</code>: The status value was not recognized, or the
status type was neither GSS_C_GSS_CODE nor GSS_C_MECH_CODE.
</p></dd></dl>

<a name="gss_005findicate_005fmechs-1"></a>
<h4 class="subheading">gss_indicate_mechs</h4>
<a name="gss_005findicate_005fmechs"></a><dl>
<dt><a name="index-gss_005findicate_005fmechs"></a>Function: <em>OM_uint32</em> <strong>gss_indicate_mechs</strong> <em>(OM_uint32 * <var>minor_status</var>, gss_OID_set * <var>mech_set</var>)</em></dt>
<dd><p><var>minor_status</var>: (integer, modify) Mechanism specific status code.
</p>
<p><var>mech_set</var>: (set of Object IDs, modify) Set of
implementation-supported mechanisms.  The returned gss_OID_set
value will be a dynamically-allocated OID set, that should be
released by the caller after use with a call to
gss_release_oid_set().
</p>

<p>Allows an application to determine which underlying security
mechanisms are available.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p></dd></dl>

<a name="gss_005frelease_005fbuffer-1"></a>
<h4 class="subheading">gss_release_buffer</h4>
<a name="gss_005frelease_005fbuffer"></a><dl>
<dt><a name="index-gss_005frelease_005fbuffer"></a>Function: <em>OM_uint32</em> <strong>gss_release_buffer</strong> <em>(OM_uint32 * <var>minor_status</var>, gss_buffer_t <var>buffer</var>)</em></dt>
<dd><p><var>minor_status</var>: (integer, modify) Mechanism specific status code.
</p>
<p><var>buffer</var>: (buffer, modify) The storage associated with the buffer
will be deleted.  The gss_buffer_desc object will not be freed,
but its length field will be zeroed.
</p>

<p>Free storage associated with a buffer.  The storage must have been
allocated by a GSS-API routine.  In addition to freeing the
associated storage, the routine will zero the length field in the
descriptor to which the buffer parameter refers, and
implementations are encouraged to additionally set the pointer
field in the descriptor to NULL.  Any buffer object returned by a
GSS-API routine may be passed to gss_release_buffer (even if there
is no storage associated with the buffer).
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p></dd></dl>

<a name="gss_005frelease_005foid_005fset-1"></a>
<h4 class="subheading">gss_release_oid_set</h4>
<a name="gss_005frelease_005foid_005fset"></a><dl>
<dt><a name="index-gss_005frelease_005foid_005fset"></a>Function: <em>OM_uint32</em> <strong>gss_release_oid_set</strong> <em>(OM_uint32 * <var>minor_status</var>, gss_OID_set * <var>set</var>)</em></dt>
<dd><p><var>minor_status</var>: (integer, modify) Mechanism specific status code.
</p>
<p><var>set</var>: (Set of Object IDs, modify) The storage associated with the
gss_OID_set will be deleted.
</p>

<p>Free storage associated with a GSSAPI-generated gss_OID_set object.
The set parameter must refer to an OID-set that was returned from a
GSS-API routine.  gss_release_oid_set() will free the storage
associated with each individual member OID, the OID set&rsquo;s elements
array, and the gss_OID_set_desc.
</p>

<p>The gss_OID_set parameter is set to GSS_C_NO_OID_SET on successful
completion of this routine.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p></dd></dl>

<a name="gss_005fcreate_005fempty_005foid_005fset-1"></a>
<h4 class="subheading">gss_create_empty_oid_set</h4>
<a name="gss_005fcreate_005fempty_005foid_005fset"></a><dl>
<dt><a name="index-gss_005fcreate_005fempty_005foid_005fset"></a>Function: <em>OM_uint32</em> <strong>gss_create_empty_oid_set</strong> <em>(OM_uint32 * <var>minor_status</var>, gss_OID_set * <var>oid_set</var>)</em></dt>
<dd><p><var>minor_status</var>: (integer, modify) Mechanism specific status code.
</p>
<p><var>oid_set</var>: (Set of Object IDs, modify) The empty object identifier
set.  The routine will allocate the gss_OID_set_desc object,
which the application must free after use with a call to
gss_release_oid_set().
</p>

<p>Create an object-identifier set containing no object identifiers,
to which members may be subsequently added using the
gss_add_oid_set_member() routine.  These routines are intended to
be used to construct sets of mechanism object identifiers, for
input to gss_acquire_cred.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p></dd></dl>

<a name="gss_005ftest_005foid_005fset_005fmember-1"></a>
<h4 class="subheading">gss_test_oid_set_member</h4>
<a name="gss_005ftest_005foid_005fset_005fmember"></a><dl>
<dt><a name="index-gss_005ftest_005foid_005fset_005fmember"></a>Function: <em>OM_uint32</em> <strong>gss_test_oid_set_member</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_OID <var>member</var>, const gss_OID_set <var>set</var>, int * <var>present</var>)</em></dt>
<dd><p><var>minor_status</var>: (integer, modify) Mechanism specific status code.
</p>
<p><var>member</var>: (Object ID, read) The object identifier whose presence is
to be tested.
</p>
<p><var>set</var>: (Set of Object ID, read) The Object Identifier set.
</p>
<p><var>present</var>: (Boolean, modify) Non-zero if the specified OID is a
member of the set, zero if not.
</p>

<p>Interrogate an Object Identifier set to determine whether a
specified Object Identifier is a member.  This routine is intended
to be used with OID sets returned by gss_indicate_mechs(),
gss_acquire_cred(), and gss_inquire_cred(), but will also work with
user-generated sets.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p></dd></dl>

<a name="gss_005fencapsulate_005ftoken-1"></a>
<h4 class="subheading">gss_encapsulate_token</h4>
<a name="gss_005fencapsulate_005ftoken"></a><dl>
<dt><a name="index-gss_005fencapsulate_005ftoken"></a>Function: <em>extern OM_uint32</em> <strong>gss_encapsulate_token</strong> <em>(gss_const_buffer_t <var>input_token</var>, gss_const_OID <var>token_oid</var>, gss_buffer_t <var>output_token</var>)</em></dt>
<dd><p><var>input_token</var>: (buffer, opaque, read) Buffer with GSS-API context token data.
</p>
<p><var>token_oid</var>: (Object ID, read) Object identifier of token.
</p>
<p><var>output_token</var>: (buffer, opaque, modify) Encapsulated token data;
caller must release with gss_release_buffer().
</p>

<p>Add the mechanism-independent token header to GSS-API context token
data.  This is used for the initial token of a GSS-API context
establishment sequence.  It incorporates an identifier of the
mechanism type to be used on that context, and enables tokens to be
interpreted unambiguously at GSS-API peers.  See further section
3.1 of RFC 2743.  This function is standardized in RFC 6339.
</p>
<p>Returns:
</p>

<p><code>GSS_S_COMPLETE</code>: Indicates successful completion, and that output
parameters holds correct information.
</p>

<p><code>GSS_S_FAILURE</code>: Indicates that encapsulation failed for reasons
unspecified at the GSS-API level.
</p></dd></dl>

<a name="gss_005fdecapsulate_005ftoken-1"></a>
<h4 class="subheading">gss_decapsulate_token</h4>
<a name="gss_005fdecapsulate_005ftoken"></a><dl>
<dt><a name="index-gss_005fdecapsulate_005ftoken"></a>Function: <em>OM_uint32</em> <strong>gss_decapsulate_token</strong> <em>(gss_const_buffer_t <var>input_token</var>, gss_const_OID <var>token_oid</var>, gss_buffer_t <var>output_token</var>)</em></dt>
<dd><p><var>input_token</var>: (buffer, opaque, read) Buffer with GSS-API context token.
</p>
<p><var>token_oid</var>: (Object ID, read) Expected object identifier of token.
</p>
<p><var>output_token</var>: (buffer, opaque, modify) Decapsulated token data;
caller must release with gss_release_buffer().
</p>

<p>Remove the mechanism-independent token header from an initial
GSS-API context token.  Unwrap a buffer in the
mechanism-independent token format.  This is the reverse of
gss_encapsulate_token().  The translation is loss-less, all data is
preserved as is.  This function is standardized in RFC 6339.
</p>
<p>Return value:
</p>

<p><code>GSS_S_COMPLETE</code>: Indicates successful completion, and that output
parameters holds correct information.
</p>

<p><code>GSS_S_DEFECTIVE_TOKEN</code>: Means that the token failed consistency
checks (e.g., OID mismatch or ASN.1 DER length errors).
</p>

<p><code>GSS_S_FAILURE</code>: Indicates that decapsulation failed for reasons
unspecified at the GSS-API level.
</p></dd></dl>

<a name="gss_005foid_005fequal-1"></a>
<h4 class="subheading">gss_oid_equal</h4>
<a name="gss_005foid_005fequal"></a><dl>
<dt><a name="index-gss_005foid_005fequal"></a>Function: <em>int</em> <strong>gss_oid_equal</strong> <em>(gss_const_OID <var>first_oid</var>, gss_const_OID <var>second_oid</var>)</em></dt>
<dd><p><var>first_oid</var>: (Object ID, read) First Object identifier.
</p>
<p><var>second_oid</var>: (Object ID, read) First Object identifier.
</p>

<p>Compare two OIDs for equality.  The comparison is &quot;deep&quot;, i.e., the
actual byte sequences of the OIDs are compared instead of just the
pointer equality.  This function is standardized in RFC 6339.
</p>
<p>Return value:
Returns boolean value true when the two OIDs are
  equal, otherwise false.
</p></dd></dl>


<hr>
<a name="SASL-GS2-Routines"></a>
<div class="header">
<p>
Previous: <a href="#Miscellaneous-Routines" accesskey="p" rel="prev">Miscellaneous Routines</a>, Up: <a href="#Standard-GSS-API" accesskey="u" rel="up">Standard GSS API</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="SASL-GS2-Routines-1"></a>
<h3 class="section">3.10 SASL GS2 Routines</h3>

<a name="gss_005finquire_005fmech_005ffor_005fsaslname-1"></a>
<h4 class="subheading">gss_inquire_mech_for_saslname</h4>
<a name="gss_005finquire_005fmech_005ffor_005fsaslname"></a><dl>
<dt><a name="index-gss_005finquire_005fmech_005ffor_005fsaslname"></a>Function: <em>OM_uint32</em> <strong>gss_inquire_mech_for_saslname</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_buffer_t <var>sasl_mech_name</var>, gss_OID * <var>mech_type</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>sasl_mech_name</var>: (buffer, character-string, read) Buffer with SASL
mechanism name.
</p>
<p><var>mech_type</var>: (OID, modify, optional) Actual mechanism used.  The OID
returned via this parameter will be a pointer to static storage
that should be treated as read-only; In particular the
application should not attempt to free it.  Specify NULL if not
required.
</p>

<p>Output GSS-API mechanism OID of mechanism associated with given
@sasl_mech_name.
</p>
<p>Returns:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_BAD_MECH</code>: There is no GSS-API mechanism known as @sasl_mech_name.
</p></dd></dl>

<a name="gss_005finquire_005fsaslname_005ffor_005fmech-1"></a>
<h4 class="subheading">gss_inquire_saslname_for_mech</h4>
<a name="gss_005finquire_005fsaslname_005ffor_005fmech"></a><dl>
<dt><a name="index-gss_005finquire_005fsaslname_005ffor_005fmech"></a>Function: <em>OM_uint32</em> <strong>gss_inquire_saslname_for_mech</strong> <em>(OM_uint32 * <var>minor_status</var>, const gss_OID <var>desired_mech</var>, gss_buffer_t <var>sasl_mech_name</var>, gss_buffer_t <var>mech_name</var>, gss_buffer_t <var>mech_description</var>)</em></dt>
<dd><p><var>minor_status</var>: (Integer, modify) Mechanism specific status code.
</p>
<p><var>desired_mech</var>: (OID, read) Identifies the GSS-API mechanism to query.
</p>
<p><var>sasl_mech_name</var>: (buffer, character-string, modify, optional)
Buffer to receive SASL mechanism name.  The application must free
storage associated with this name after use with a call to
gss_release_buffer().
</p>
<p><var>mech_name</var>: (buffer, character-string, modify, optional) Buffer to
receive human readable mechanism name.  The application must free
storage associated with this name after use with a call to
gss_release_buffer().
</p>
<p><var>mech_description</var>: (buffer, character-string, modify, optional)
Buffer to receive description of mechanism.  The application must
free storage associated with this name after use with a call to
gss_release_buffer().
</p>

<p>Output the SASL mechanism name of a GSS-API mechanism.  It also
returns a name and description of the mechanism in a user friendly
form.
</p>
<p>Returns:
</p>

<p><code>GSS_S_COMPLETE</code>: Successful completion.
</p>

<p><code>GSS_S_BAD_MECH</code>: The @desired_mech OID is unsupported.
</p></dd></dl>


<hr>
<a name="Extended-GSS-API"></a>
<div class="header">
<p>
Next: <a href="#Invoking-gss" accesskey="n" rel="next">Invoking gss</a>, Previous: <a href="#Standard-GSS-API" accesskey="p" rel="prev">Standard GSS API</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Extended-GSS-API-1"></a>
<h2 class="chapter">4 Extended GSS API</h2>

<p>None of the following functions are standard GSS API functions.  As
such, they are not declared in <samp>gss/api.h</samp>, but rather in
<samp>gss/ext.h</samp> (which is included from <samp>gss.h</samp>).
See <a href="#Header">Header</a>.
</p>
<a name="gss_005fcheck_005fversion-1"></a>
<h4 class="subheading">gss_check_version</h4>
<a name="gss_005fcheck_005fversion"></a><dl>
<dt><a name="index-gss_005fcheck_005fversion"></a>Function: <em>const char *</em> <strong>gss_check_version</strong> <em>(const char * <var>req_version</var>)</em></dt>
<dd><p><var>req_version</var>: version string to compare with, or NULL
</p>

<p>Check that the version of the library is at minimum the one
given as a string in @req_version.
</p>
<p>Return value:
The actual version string of the library; NULL if the
  condition is not met.  If NULL is passed to this function no
  check is done and only the version string is returned.
</p></dd></dl>

<a name="gss_005fuserok-1"></a>
<h4 class="subheading">gss_userok</h4>
<a name="gss_005fuserok"></a><dl>
<dt><a name="index-gss_005fuserok"></a>Function: <em>int</em> <strong>gss_userok</strong> <em>(const gss_name_t <var>name</var>, const char * <var>username</var>)</em></dt>
<dd><p><var>name</var>: (gss_name_t, read) Name to be compared.
</p>
<p><var>username</var>: Zero terminated string with username.
</p>

<p>Compare the username against the output from gss_export_name()
invoked on @name, after removing the leading OID.  This answers the
question whether the particular mechanism would authenticate them
as the same principal
</p>
<p>Return value:
Returns 0 if the names match, non-0 otherwise.
</p></dd></dl>


<hr>
<a name="Invoking-gss"></a>
<div class="header">
<p>
Next: <a href="#Acknowledgements" accesskey="n" rel="next">Acknowledgements</a>, Previous: <a href="#Extended-GSS-API" accesskey="p" rel="prev">Extended GSS API</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Invoking-gss-1"></a>
<h2 class="chapter">5 Invoking gss</h2>

<a name="index-gss"></a>
<a name="index-invoking-gss"></a>
<a name="index-command-line"></a>

<a name="Name"></a>
<h2 class="majorheading">Name</h2>

<p>GNU GSS (gss) &ndash; Command line interface to the GSS Library.
</p>
<a name="Description"></a>
<h2 class="majorheading">Description</h2>

<p><code>gss</code> is the main program of GNU GSS.
</p>
<p>Mandatory or optional arguments to long options are also mandatory or
optional for any corresponding short options.
</p>
<a name="Commands"></a>
<h2 class="majorheading">Commands</h2>

<p><code>gss</code> recognizes these commands:
</p>
<pre class="verbatim">  -l, --list-mechanisms
                    List information about supported mechanisms
                    in a human readable format.
  -m, --major=LONG  Describe a `major status' error code value.
  -a, --accept-sec-context
                    Accept a security context as server.
  -i, --init-sec-context=MECH
                    Initialize a security context as client.
                    MECH is the SASL name of mechanism, use -l
                    to list supported mechanisms.
  -n, --server-name=SERVICE@HOSTNAME
                    For -i, set the name of the remote host.
                    For example, &quot;imap@mail.example.com&quot;.
</pre>
<a name="Other-Options"></a>
<h2 class="majorheading">Other Options</h2>

<p>These are some standard parameters.
</p>
<pre class="verbatim">  -h, --help        Print help and exit
  -V, --version     Print version and exit
  -q, --quiet       Silent operation  (default=off)
</pre>
<a name="Examples"></a>
<h2 class="majorheading">Examples</h2>

<p>To list the supported mechanisms, use <code>gss -l</code> like this:
</p>
<pre class="verbatim">$ src/gss -l
Found 1 supported mechanisms.

Mechanism 0:
        Mechanism name: Kerberos V5
        Mechanism description: Kerberos V5 GSS-API mechanism
        SASL Mechanism name: GS2-KRB5
$
</pre>
<p>To initialize a Kerberos V5 security context, use the
<code>--init-sec-context</code> parameter.  Kerberos V5 needs to know the name
of the remote entity, so you need to supply the <code>--server-name</code>
parameter as well.  That will provide the name of the server.  For
example, use <code>imap@mail.example.com</code> to setup a security context
with the <code>imap</code> service on the host <code>mail.example.com</code>.  The
Kerberos V5 client will use your ticket-granting ticket (which needs to
be available) and acquire a server ticket for the service.  The KDC must
know about the server for this to work.  The tool will print the GSS-API
context tokens base64 encoded on standard output.
</p>
<pre class="verbatim">$ gss -i GS2-KRB5 -n host@interop.josefsson.org
Context token (protection is available):
YIICIQYJKoZIhvcSAQICAQBuggIQMIICDKADAgEFoQMCAQ6iBwMFACAAAACjggEYYYIBFDCCARCgAwIBBaEXGxVpbnRlcm9wLmpvc2Vmc3Nvbi5vcmeiKDAmoAMCAQGhHzAdGwRob3N0GxVpbnRlcm9wLmpvc2Vmc3Nvbi5vcmejgcUwgcKgAwIBEqKBugSBt0zqTh6tBBKV2BwDjQg6H4abEaPshPa0o3tT/TH9U7BaSw/M9ugYYqpHAhOitVjcQidhG2FdSl1n3FOgDBufHHO+gHOW0Y1XHc2QtEdkg1xYF2J4iR1vNQB14kXDM78pogCsfvfLnjsEESKWoeKRGOYWPRx0ksLJDnl/e5tXecZTjhJ3hLrFNBEWRmpIOakTAPnL+Xzz6xcnLHMLLnhZ5VcHqtIMm5p9IDWsP0juIncJ6tO8hjMA2qSB2jCB16ADAgESooHPBIHMWSeRBgV80gh/6hNNMr00jTVwCs5TEAIkljvjOfyPmNBzIFWoG+Wj5ZKOBdizdi7vYbJ2s8b1iSsq/9YEZSqaTxul+5aNrclKoJ7J/IW4kTuMklHcQf/A16TeZFsm9TdfE+x8+PjbOBFtKYXT8ODT8LLicNNiDbWW0meY7lsktXAVpZiUds4wTZ1W5bOSEGY7+mxAWrAlTnNwNAt1J2MHZnfGJFJDLJZldXoyG8OwHyp4h1nBhgzC5BfAmL85QJVxxgVfiHhM5oT9mE1O
Input context token:

</pre>
<p>The tool is waiting for the final Kerberos V5 context token from the
server.  Note the status text informing you that message protection is
available.
</p>
<p>To accept a Kerberos V5 context, the process is similar.  The server
needs to know its name, so that it can find the host key from
(typically) <code>/etc/shishi/shishi.keys</code>.  Once started it will wait
for a context token from the client.  Below we&rsquo;ll paste in the token
printed above.
</p>
<pre class="verbatim">$ gss -a -n host@interop.josefsson.org
Importing name &quot;host@interop.josefsson.org&quot;...
Acquiring credentials...
Input context token:
YIICIQYJKoZIhvcSAQICAQBuggIQMIICDKADAgEFoQMCAQ6iBwMFACAAAACjggEYYYIBFDCCARCgAwIBBaEXGxVpbnRlcm9wLmpvc2Vmc3Nvbi5vcmeiKDAmoAMCAQGhHzAdGwRob3N0GxVpbnRlcm9wLmpvc2Vmc3Nvbi5vcmejgcUwgcKgAwIBEqKBugSBt0zqTh6tBBKV2BwDjQg6H4abEaPshPa0o3tT/TH9U7BaSw/M9ugYYqpHAhOitVjcQidhG2FdSl1n3FOgDBufHHO+gHOW0Y1XHc2QtEdkg1xYF2J4iR1vNQB14kXDM78pogCsfvfLnjsEESKWoeKRGOYWPRx0ksLJDnl/e5tXecZTjhJ3hLrFNBEWRmpIOakTAPnL+Xzz6xcnLHMLLnhZ5VcHqtIMm5p9IDWsP0juIncJ6tO8hjMA2qSB2jCB16ADAgESooHPBIHMWSeRBgV80gh/6hNNMr00jTVwCs5TEAIkljvjOfyPmNBzIFWoG+Wj5ZKOBdizdi7vYbJ2s8b1iSsq/9YEZSqaTxul+5aNrclKoJ7J/IW4kTuMklHcQf/A16TeZFsm9TdfE+x8+PjbOBFtKYXT8ODT8LLicNNiDbWW0meY7lsktXAVpZiUds4wTZ1W5bOSEGY7+mxAWrAlTnNwNAt1J2MHZnfGJFJDLJZldXoyG8OwHyp4h1nBhgzC5BfAmL85QJVxxgVfiHhM5oT9mE1O
Context has been accepted.  Final context token:
YHEGCSqGSIb3EgECAgIAb2IwYKADAgEFoQMCAQ+iVDBSoAMCARKhAwIBAKJGBESy1Zoy9DrG+DuV/6aWmAp79s9d+ofGXC/WKOzRuxAqo98vMRWbsbILW8z9aF1th4GZz0kjFz/hZAmnWyomZ9JiP3yQvg==
$
</pre>
<p>Returning to the client, you may now cut&rsquo;n&rsquo;paste the final context token
as shown by the server.  The client has then authenticated the server as
well.  The output from the client is shown below.
</p>
<pre class="verbatim">YHEGCSqGSIb3EgECAgIAb2IwYKADAgEFoQMCAQ+iVDBSoAMCARKhAwIBAKJGBESy1Zoy9DrG+DuV/6aWmAp79s9d+ofGXC/WKOzRuxAqo98vMRWbsbILW8z9aF1th4GZz0kjFz/hZAmnWyomZ9JiP3yQvg==
Context has been initialized.
$
</pre>
<hr>
<a name="Acknowledgements"></a>
<div class="header">
<p>
Next: <a href="#Criticism-of-GSS" accesskey="n" rel="next">Criticism of GSS</a>, Previous: <a href="#Invoking-gss" accesskey="p" rel="prev">Invoking gss</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Acknowledgements-1"></a>
<h2 class="chapter">6 Acknowledgements</h2>

<p>This manual borrows text from RFC 2743 and RFC 2744 that describe GSS
API formally.
</p>

<hr>
<a name="Criticism-of-GSS"></a>
<div class="header">
<p>
Next: <a href="#Copying-Information" accesskey="n" rel="next">Copying Information</a>, Previous: <a href="#Acknowledgements" accesskey="p" rel="prev">Acknowledgements</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Criticism-of-GSS-1"></a>
<h2 class="appendix">Appendix A Criticism of GSS</h2>

<p>The author has doubts whether GSS is the best solution for free
software projects looking for a implementation agnostic security
framework.  We express these doubts in this section, so that the
reader can judge for herself if any of the potential problems
discussed here are relevant for their project, or if the benefit
outweigh the problems.  We are aware that some of the opinions are
highly subjective, but we offer them in the hope they can serve as
anecdotal evidence.
</p>
<p>GSS can be criticized on several levels.  We start with the actual
implementation.
</p>
<p>GSS does not appear to be designed by experienced C programmers.
While generally this may be a good thing (C is not the best language),
but since they defined the API in C, it is unfortunate.  The primary
evidence of this is the major_status and minor_status error code
solution.  It is a complicated way to describe error conditions, but
what makes matters worse, the error condition is separated; half of
the error condition is in the function return value and the other half
is in the first argument to the function, which is always a pointer to
an integer.  (The pointer is not even allowed to be <code>NULL</code>, if
the application doesn&rsquo;t care about the minor error code.)  This makes
the API unreadable, and difficult to use.  A better solutions would be
to return a struct containing the entire error condition, which can be
accessed using macros, although we acknowledge that the C language
used at the time GSS was designed may not have allowed this (this may
in fact be the reason the awkward solution was chosen).  Instead, the
return value could have been passed back to callers using a pointer to
a struct, accessible using various macros, and the function could have
a void prototype.  The fact that minor_status is placed first in the
parameter list increases the pain it is to use the API.  Important
parameters should be placed first. A better place for minor_status (if
it must be present at all) would have been last in the prototypes.
</p>
<p>Another evidence of the C inexperience are the memory management
issues; GSS provides functions to deallocate data stored within, e.g.,
<code>gss_buffer_t</code> but the caller is responsible of deallocating the
structure pointed at by the <code>gss_buffer_t</code> (i.e., the
<code>gss_buffer_desc</code>) itself.  Memory management issues are error
prone, and this division easily leads to memory leaks (or worse).
Instead, the API should be the sole owner of all <code>gss_ctx_id_t</code>,
<code>gss_cred_id_t</code>, and <code>gss_buffer_t</code> structures: they should
be allocated by the library, and deallocated (using the utility
functions defined for this purpose) by the library.
</p>
<p>TBA: specification is unclear how memory for OIDs are managed.  For
example, who is responsible for deallocate potentially newly allocated
OIDs returned as <code>actual_mechs</code> in <code>gss_acquire_cred</code>?
Further, are OIDs deeply copied into OID sets?  In other words, if I
add an OID into an OID set, and modify the original OID, will the OID
in the OID set be modified too?
</p>
<p>Another illustrating example is the sample GSS header file given in
the RFC, which contains:
</p>
<div class="example">
<pre class="example">/*
 * We have included the xom.h header file.  Verify that OM_uint32
 * is defined correctly.
 */
#if sizeof(gss_uint32) != sizeof(OM_uint32)
#error Incompatible definition of OM_uint32 from xom.h
#endif
</pre></div>

<p>The C pre-processor does not know about the <code>sizeof</code> function, so
it is treated as an identifier, which maps to 0.  Thus, the expression
does not check that the size of <code>OM_uint32</code> is correct.  It
checks whether the expression <code>0 != 0</code> holds.
</p>
<p>TBA: thread issues
</p>
<p>TBA: multiple mechanisms in a GSS library
</p>
<p>TBA: high-level design criticism.
</p>
<p>TBA: no credential forwarding.
</p>
<p>TBA: internationalization
</p>
<p>TBA: dynamically generated OIDs and memory deallocation issue.  I.e.,
should gss_import_name or gss_duplicate_name allocate memory and copy
the OID provided, or simply copy the pointer?  If the former, who
would deallocate that memory?  If the latter, the application may
deallocate or modify the OID, which seem unwanted.
</p>
<p>TBA: krb5: no way to access authorization-data
</p>
<p>TBA: krb5: firewall/pre-IP: iakerb status?
</p>
<p>TBA: krb5: single-DES only
</p>
<p>TBA: the API may block, unusable in select() based servers.
Especially if the servers contacted is decided by the, yet
unauthenticated, remote client.
</p>
<p>TBA: krb5: no support for GSS_C_PROT_READY_FLAG.  We support it
anyway, though.
</p>
<p>TBA: krb5: gssapi-cfx differ from rfc 1964 in the reply token in that
the latter require presence of sequence numbers whereas the former
doesn&rsquo;t.
</p>
<p>Finally we note that few free security applications uses GSS, perhaps
the only major exception to this are Kerberos 5 implementations.
While not substantial evidence, this do suggest that the GSS may not
be the simplest solution available to solve actual problems, since
otherwise more projects would have chosen to take advantage of the
work that went into GSS instead of using another framework (or
designing their own solution).
</p>
<p>Our conclusion is that free software projects that are looking for a
security framework should evaluate carefully whether GSS actually is
the best solution before using it.  In particular it is recommended to
compare GSS with the Simple Authentication and Security Layer (SASL)
framework, which in several situations provide the same feature as GSS
does.  The most compelling argument for SASL over GSS is, as its
acronym suggest, Simple, whereas GSS is far from it.
</p>
<p>However, that said, for free software projects that wants to support
Kerberos 5, we do acknowledge that no other framework provides a more
portable and interoperable interface into the Kerberos 5 system.  If
your project needs to use Kerberos 5 specifically, we do recommend you
to use GSS instead of the Kerberos 5 implementation specific APIs.
</p>
<hr>
<a name="Copying-Information"></a>
<div class="header">
<p>
Next: <a href="#Concept-Index" accesskey="n" rel="next">Concept Index</a>, Previous: <a href="#Criticism-of-GSS" accesskey="p" rel="prev">Criticism of GSS</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Copying-Information-1"></a>
<h2 class="appendix">Appendix B Copying Information</h2>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#GNU-Free-Documentation-License" accesskey="1">GNU Free Documentation License</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">License for copying this manual.
</td></tr>
</table>

<hr>
<a name="GNU-Free-Documentation-License"></a>
<div class="header">
<p>
Up: <a href="#Copying-Information" accesskey="u" rel="up">Copying Information</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="GNU-Free-Documentation-License-1"></a>
<h3 class="appendixsec">B.1 GNU Free Documentation License</h3>

<a name="index-FDL_002c-GNU-Free-Documentation-License"></a>

<div align="center">Version 1.3, 3 November 2008
</div>

<div class="display">
<pre class="display">Copyright &copy; 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
<a href="http://fsf.org/">http://fsf.org/</a>

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
</pre></div>

<ol>
<li> PREAMBLE

<p>The purpose of this License is to make a manual, textbook, or other
functional and useful document <em>free</em> in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
</p>
<p>This License is a kind of &ldquo;copyleft&rdquo;, which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft
license designed for free software.
</p>
<p>We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.
</p>
</li><li> APPLICABILITY AND DEFINITIONS

<p>This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License.  Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein.  The &ldquo;Document&rdquo;, below,
refers to any such manual or work.  Any member of the public is a
licensee, and is addressed as &ldquo;you&rdquo;.  You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
</p>
<p>A &ldquo;Modified Version&rdquo; of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
</p>
<p>A &ldquo;Secondary Section&rdquo; is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document&rsquo;s overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject.  (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
</p>
<p>The &ldquo;Invariant Sections&rdquo; are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.  If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant.  The Document may contain zero
Invariant Sections.  If the Document does not identify any Invariant
Sections then there are none.
</p>
<p>The &ldquo;Cover Texts&rdquo; are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.  A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
</p>
<p>A &ldquo;Transparent&rdquo; copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters.  A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text.  A copy that is not &ldquo;Transparent&rdquo; is called &ldquo;Opaque&rdquo;.
</p>
<p>Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input
format, SGML or XML using a publicly available
DTD, and standard-conforming simple HTML,
PostScript or PDF designed for human modification.  Examples
of transparent image formats include PNG, XCF and
JPG.  Opaque formats include proprietary formats that can be
read and edited only by proprietary word processors, SGML or
XML for which the DTD and/or processing tools are
not generally available, and the machine-generated HTML,
PostScript or PDF produced by some word processors for
output purposes only.
</p>
<p>The &ldquo;Title Page&rdquo; means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, &ldquo;Title Page&rdquo; means
the text near the most prominent appearance of the work&rsquo;s title,
preceding the beginning of the body of the text.
</p>
<p>The &ldquo;publisher&rdquo; means any person or entity that distributes copies
of the Document to the public.
</p>
<p>A section &ldquo;Entitled XYZ&rdquo; means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language.  (Here XYZ stands for a
specific section name mentioned below, such as &ldquo;Acknowledgements&rdquo;,
&ldquo;Dedications&rdquo;, &ldquo;Endorsements&rdquo;, or &ldquo;History&rdquo;.)  To &ldquo;Preserve the Title&rdquo;
of such a section when you modify the Document means that it remains a
section &ldquo;Entitled XYZ&rdquo; according to this definition.
</p>
<p>The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document.  These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
</p>
</li><li> VERBATIM COPYING

<p>You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.
</p>
<p>You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
</p>
</li><li> COPYING IN QUANTITY

<p>If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document&rsquo;s license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present
the full title with all words of the title equally prominent and
visible.  You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
</p>
<p>If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
</p>
<p>If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
</p>
<p>It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
</p>
</li><li> MODIFICATIONS

<p>You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it.  In addition, you must do these things in the Modified Version:
</p>
<ol>
<li> Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document).  You may use the same title as a previous version
if the original publisher of that version gives permission.

</li><li> List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.

</li><li> State on the Title page the name of the publisher of the
Modified Version, as the publisher.

</li><li> Preserve all the copyright notices of the Document.

</li><li> Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.

</li><li> Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.

</li><li> Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document&rsquo;s license notice.

</li><li> Include an unaltered copy of this License.

</li><li> Preserve the section Entitled &ldquo;History&rdquo;, Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page.  If
there is no section Entitled &ldquo;History&rdquo; in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.

</li><li> Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on.  These may be placed in the &ldquo;History&rdquo; section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.

</li><li> For any section Entitled &ldquo;Acknowledgements&rdquo; or &ldquo;Dedications&rdquo;, Preserve
the Title of the section, and preserve in the section all the
substance and tone of each of the contributor acknowledgements and/or
dedications given therein.

</li><li> Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles.  Section numbers
or the equivalent are not considered part of the section titles.

</li><li> Delete any section Entitled &ldquo;Endorsements&rdquo;.  Such a section
may not be included in the Modified Version.

</li><li> Do not retitle any existing section to be Entitled &ldquo;Endorsements&rdquo; or
to conflict in title with any Invariant Section.

</li><li> Preserve any Warranty Disclaimers.
</li></ol>

<p>If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version&rsquo;s license notice.
These titles must be distinct from any other section titles.
</p>
<p>You may add a section Entitled &ldquo;Endorsements&rdquo;, provided it contains
nothing but endorsements of your Modified Version by various
parties&mdash;for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
</p>
<p>You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity.  If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
</p>
<p>The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
</p>
</li><li> COMBINING DOCUMENTS

<p>You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
</p>
<p>The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
</p>
<p>In the combination, you must combine any sections Entitled &ldquo;History&rdquo;
in the various original documents, forming one section Entitled
&ldquo;History&rdquo;; likewise combine any sections Entitled &ldquo;Acknowledgements&rdquo;,
and any sections Entitled &ldquo;Dedications&rdquo;.  You must delete all
sections Entitled &ldquo;Endorsements.&rdquo;
</p>
</li><li> COLLECTIONS OF DOCUMENTS

<p>You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
</p>
<p>You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
</p>
</li><li> AGGREGATION WITH INDEPENDENT WORKS

<p>A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an &ldquo;aggregate&rdquo; if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation&rsquo;s users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
</p>
<p>If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document&rsquo;s Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
</p>
</li><li> TRANSLATION

<p>Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers.  In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
</p>
<p>If a section in the Document is Entitled &ldquo;Acknowledgements&rdquo;,
&ldquo;Dedications&rdquo;, or &ldquo;History&rdquo;, the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
</p>
</li><li> TERMINATION

<p>You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense, or distribute it is void, and
will automatically terminate your rights under this License.
</p>
<p>However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
</p>
<p>Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
</p>
<p>Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License.  If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.
</p>
</li><li> FUTURE REVISIONS OF THIS LICENSE

<p>The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time.  Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.  See
<a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>.
</p>
<p>Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License &ldquo;or any later version&rdquo; applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.  If the Document
specifies that a proxy can decide which future versions of this
License can be used, that proxy&rsquo;s public statement of acceptance of a
version permanently authorizes you to choose that version for the
Document.
</p>
</li><li> RELICENSING

<p>&ldquo;Massive Multiauthor Collaboration Site&rdquo; (or &ldquo;MMC Site&rdquo;) means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works.  A
public wiki that anybody can edit is an example of such a server.  A
&ldquo;Massive Multiauthor Collaboration&rdquo; (or &ldquo;MMC&rdquo;) contained in the
site means any set of copyrightable works thus published on the MMC
site.
</p>
<p>&ldquo;CC-BY-SA&rdquo; means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
</p>
<p>&ldquo;Incorporate&rdquo; means to publish or republish a Document, in whole or
in part, as part of another Document.
</p>
<p>An MMC is &ldquo;eligible for relicensing&rdquo; if it is licensed under this
License, and if all works that were first published under this License
somewhere other than this MMC, and subsequently incorporated in whole
or in part into the MMC, (1) had no cover texts or invariant sections,
and (2) were thus incorporated prior to November 1, 2008.
</p>
<p>The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.
</p>
</li></ol>

<a name="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></a>
<h3 class="heading">ADDENDUM: How to use this License for your documents</h3>

<p>To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
</p>
<div class="smallexample">
<pre class="smallexample">  Copyright (C)  <var>year</var>  <var>your name</var>.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.
</pre></div>

<p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the &ldquo;with&hellip;Texts.&rdquo; line with this:
</p>
<div class="smallexample">
<pre class="smallexample">    with the Invariant Sections being <var>list their titles</var>, with
    the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts
    being <var>list</var>.
</pre></div>

<p>If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
</p>
<p>If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
</p>

<hr>
<a name="Concept-Index"></a>
<div class="header">
<p>
Next: <a href="#API-Index" accesskey="n" rel="next">API Index</a>, Previous: <a href="#Copying-Information" accesskey="p" rel="prev">Copying Information</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Concept-Index-1"></a>
<h2 class="unnumbered">Concept Index</h2>

<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-W"><b>W</b></a>
 &nbsp; 
</td></tr></table>
<table class="index-cp" border="0">
<tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-A">A</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-AIX">AIX</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-C">C</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-command-line">command line</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-gss">Invoking gss</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Compiling-your-application">Compiling your application</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Building-the-source">Building the source</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Contributing">Contributing</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Contributing">Contributing</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-D">D</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Debian">Debian</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Debian-1">Debian</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Download">Download</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Downloading-and-Installing">Downloading and Installing</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-F">F</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-FDL_002c-GNU-Free-Documentation-License">FDL, GNU Free Documentation License</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-FreeBSD">FreeBSD</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Future-goals">Future goals</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Planned-Features">Planned Features</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-H">H</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Hacking">Hacking</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Contributing">Contributing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Header-files">Header files</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Header">Header</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-HP_002dUX">HP-UX</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-I">I</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Installation">Installation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Downloading-and-Installing">Downloading and Installing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-invoking-gss">invoking <code>gss</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-gss">Invoking gss</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-IRIX">IRIX</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-M">M</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Mandrake">Mandrake</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-mechanism-status-codes">mechanism status codes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-Handling">Error Handling</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Memory-allocation-failure">Memory allocation failure</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Out-of-Memory-handling">Out of Memory handling</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Motorola-Coldfire">Motorola Coldfire</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-N">N</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-NetBSD">NetBSD</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-O">O</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-OpenBSD">OpenBSD</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Out-of-Memory-handling">Out of Memory handling</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Out-of-Memory-handling">Out of Memory handling</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-R">R</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-RedHat">RedHat</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-RedHat-1">RedHat</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-RedHat-2">RedHat</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-RedHat-Advanced-Server">RedHat Advanced Server</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Reporting-Bugs">Reporting Bugs</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Bug-Reports">Bug Reports</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-S">S</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Solaris">Solaris</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-status-codes">status codes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-Handling">Error Handling</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-SuSE">SuSE</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-SuSE-Linux">SuSE Linux</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-T">T</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Todo-list">Todo list</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Planned-Features">Planned Features</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Tru64">Tru64</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-U">U</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-uClibc">uClibc</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-uClinux">uClinux</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-W">W</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Windows">Windows</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-Platforms">Supported Platforms</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
</table>
<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-W"><b>W</b></a>
 &nbsp; 
</td></tr></table>

<hr>
<a name="API-Index"></a>
<div class="header">
<p>
Previous: <a href="#Concept-Index" accesskey="p" rel="prev">Concept Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="API-Index-1"></a>
<h2 class="unnumbered">API Index</h2>

<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#API-Index_fn_letter-G"><b>G</b></a>
 &nbsp; 
</td></tr></table>
<table class="index-fn" border="0">
<tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="API-Index_fn_letter-G">G</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss"><code>gss</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-gss">Invoking gss</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005faccept_005fsec_005fcontext"><code>gss_accept_sec_context</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Context_002dLevel-Routines">Context-Level Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005facquire_005fcred"><code>gss_acquire_cred</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Credential-Management">Credential Management</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fadd_005fcred"><code>gss_add_cred</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Credential-Management">Credential Management</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fadd_005foid_005fset_005fmember"><code>gss_add_oid_set_member</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Routines">Miscellaneous Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-GSS_005fCALLING_005fERROR"><code>GSS_CALLING_ERROR</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-Handling">Error Handling</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fcanonicalize_005fname"><code>gss_canonicalize_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Manipulation">Name Manipulation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fcheck_005fversion"><code>gss_check_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extended-GSS-API">Extended GSS API</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fcompare_005fname"><code>gss_compare_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Manipulation">Name Manipulation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fcontext_005ftime"><code>gss_context_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Context_002dLevel-Routines">Context-Level Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fcreate_005fempty_005foid_005fset"><code>gss_create_empty_oid_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Routines">Miscellaneous Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fdecapsulate_005ftoken"><code>gss_decapsulate_token</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Routines">Miscellaneous Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fdelete_005fsec_005fcontext"><code>gss_delete_sec_context</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Context_002dLevel-Routines">Context-Level Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fdisplay_005fname"><code>gss_display_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Manipulation">Name Manipulation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fdisplay_005fstatus"><code>gss_display_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Routines">Miscellaneous Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fduplicate_005fname"><code>gss_duplicate_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Manipulation">Name Manipulation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fencapsulate_005ftoken"><code>gss_encapsulate_token</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Routines">Miscellaneous Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-GSS_005fERROR"><code>GSS_ERROR</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-Handling">Error Handling</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fexport_005fname"><code>gss_export_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Manipulation">Name Manipulation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fexport_005fsec_005fcontext"><code>gss_export_sec_context</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Context_002dLevel-Routines">Context-Level Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fget_005fmic"><code>gss_get_mic</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Per_002dMessage-Routines">Per-Message Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fimport_005fname"><code>gss_import_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Manipulation">Name Manipulation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fimport_005fsec_005fcontext"><code>gss_import_sec_context</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Context_002dLevel-Routines">Context-Level Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005findicate_005fmechs"><code>gss_indicate_mechs</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Routines">Miscellaneous Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005finit_005fsec_005fcontext"><code>gss_init_sec_context</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Context_002dLevel-Routines">Context-Level Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005finquire_005fcontext"><code>gss_inquire_context</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Context_002dLevel-Routines">Context-Level Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005finquire_005fcred"><code>gss_inquire_cred</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Credential-Management">Credential Management</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005finquire_005fcred_005fby_005fmech"><code>gss_inquire_cred_by_mech</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Credential-Management">Credential Management</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005finquire_005fmechs_005ffor_005fname"><code>gss_inquire_mechs_for_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Manipulation">Name Manipulation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005finquire_005fmech_005ffor_005fsaslname"><code>gss_inquire_mech_for_saslname</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#SASL-GS2-Routines">SASL GS2 Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005finquire_005fnames_005ffor_005fmech"><code>gss_inquire_names_for_mech</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Manipulation">Name Manipulation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005finquire_005fsaslname_005ffor_005fmech"><code>gss_inquire_saslname_for_mech</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#SASL-GS2-Routines">SASL GS2 Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005foid_005fequal"><code>gss_oid_equal</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Routines">Miscellaneous Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fprocess_005fcontext_005ftoken"><code>gss_process_context_token</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Context_002dLevel-Routines">Context-Level Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005frelease_005fbuffer"><code>gss_release_buffer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Routines">Miscellaneous Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005frelease_005fcred"><code>gss_release_cred</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Credential-Management">Credential Management</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005frelease_005fname"><code>gss_release_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Manipulation">Name Manipulation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005frelease_005foid_005fset"><code>gss_release_oid_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Routines">Miscellaneous Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-GSS_005fROUTINE_005fERROR"><code>GSS_ROUTINE_ERROR</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-Handling">Error Handling</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-GSS_005fSUPPLEMENTARY_005fINFO"><code>GSS_SUPPLEMENTARY_INFO</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-Handling">Error Handling</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-GSS_005fS_005f_002e_002e_002e"><code>GSS_S_...</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-Handling">Error Handling</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005ftest_005foid_005fset_005fmember"><code>gss_test_oid_set_member</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Routines">Miscellaneous Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005funwrap"><code>gss_unwrap</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Per_002dMessage-Routines">Per-Message Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fuserok"><code>gss_userok</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extended-GSS-API">Extended GSS API</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fverify_005fmic"><code>gss_verify_mic</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Per_002dMessage-Routines">Per-Message Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fwrap"><code>gss_wrap</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Per_002dMessage-Routines">Per-Message Routines</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gss_005fwrap_005fsize_005flimit"><code>gss_wrap_size_limit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Context_002dLevel-Routines">Context-Level Routines</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
</table>
<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#API-Index_fn_letter-G"><b>G</b></a>
 &nbsp; 
</td></tr></table>

<hr>



</body>
</html>