diff options
Diffstat (limited to 'doc/html/appdev/gssapi.html')
| -rw-r--r-- | doc/html/appdev/gssapi.html | 705 |
1 files changed, 705 insertions, 0 deletions
diff --git a/doc/html/appdev/gssapi.html b/doc/html/appdev/gssapi.html new file mode 100644 index 000000000000..51eb7706a1df --- /dev/null +++ b/doc/html/appdev/gssapi.html @@ -0,0 +1,705 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Developing with GSSAPI — MIT Kerberos Documentation</title> + + <link rel="stylesheet" href="../_static/agogo.css" type="text/css" /> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="../_static/kerb.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '1.15.1', + COLLAPSE_INDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="../_static/jquery.js"></script> + <script type="text/javascript" src="../_static/underscore.js"></script> + <script type="text/javascript" src="../_static/doctools.js"></script> + <link rel="author" title="About these documents" href="../about.html" /> + <link rel="copyright" title="Copyright" href="../copyright.html" /> + <link rel="top" title="MIT Kerberos Documentation" href="../index.html" /> + <link rel="up" title="For application developers" href="index.html" /> + <link rel="next" title="Differences between Heimdal and MIT Kerberos API" href="h5l_mit_apidiff.html" /> + <link rel="prev" title="For application developers" href="index.html" /> + </head> + <body> + <div class="header-wrapper"> + <div class="header"> + + + <h1><a href="../index.html">MIT Kerberos Documentation</a></h1> + + <div class="rel"> + + <a href="../index.html" title="Full Table of Contents" + accesskey="C">Contents</a> | + <a href="index.html" title="For application developers" + accesskey="P">previous</a> | + <a href="h5l_mit_apidiff.html" title="Differences between Heimdal and MIT Kerberos API" + accesskey="N">next</a> | + <a href="../genindex.html" title="General Index" + accesskey="I">index</a> | + <a href="../search.html" title="Enter search criteria" + accesskey="S">Search</a> | + <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__Developing with GSSAPI">feedback</a> + </div> + </div> + </div> + + <div class="content-wrapper"> + <div class="content"> + <div class="document"> + + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="developing-with-gssapi"> +<h1>Developing with GSSAPI<a class="headerlink" href="#developing-with-gssapi" title="Permalink to this headline">¶</a></h1> +<p>The GSSAPI (Generic Security Services API) allows applications to +communicate securely using Kerberos 5 or other security mechanisms. +We recommend using the GSSAPI (or a higher-level framework which +encompasses GSSAPI, such as SASL) for secure network communication +over using the libkrb5 API directly.</p> +<p>GSSAPIv2 is specified in <span class="target" id="index-0"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc2743.html"><strong>RFC 2743</strong></a> and <span class="target" id="index-1"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc2744.html"><strong>RFC 2744</strong></a>. Also see +<span class="target" id="index-2"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc7546.html"><strong>RFC 7546</strong></a> for a description of how to use the GSSAPI in a client or +server program.</p> +<p>This documentation will describe how various ways of using the +GSSAPI will behave with the krb5 mechanism as implemented in MIT krb5, +as well as krb5-specific extensions to the GSSAPI.</p> +<div class="section" id="name-types"> +<h2>Name types<a class="headerlink" href="#name-types" title="Permalink to this headline">¶</a></h2> +<p>A GSSAPI application can name a local or remote entity by calling +<a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.16">gss_import_name</a>, specifying a name type and a value. The following +name types are supported by the krb5 mechanism:</p> +<ul class="simple"> +<li><strong>GSS_C_NT_HOSTBASED_SERVICE</strong>: The value should be a string of the +form <tt class="docutils literal"><span class="pre">service</span></tt> or <tt class="docutils literal"><span class="pre">service@hostname</span></tt>. This is the most common +way to name target services when initiating a security context, and +is the most likely name type to work across multiple mechanisms.</li> +<li><strong>GSS_KRB5_NT_PRINCIPAL_NAME</strong>: The value should be a principal name +string. This name type only works with the krb5 mechanism, and is +defined in the <tt class="docutils literal"><span class="pre"><gssapi/gssapi_krb5.h></span></tt> header.</li> +<li><strong>GSS_C_NT_USER_NAME</strong> or <strong>GSS_C_NULL_OID</strong>: The value is treated +as an unparsed principal name string, as above. These name types +may work with mechanisms other than krb5, but will have different +interpretations in those mechanisms. <strong>GSS_C_NT_USER_NAME</strong> is +intended to be used with a local username, which will parse into a +single-component principal in the default realm.</li> +<li><strong>GSS_C_NT_ANONYMOUS</strong>: The value is ignored. The anonymous +principal is used, allowing a client to authenticate to a server +without asserting a particular identity (which may or may not be +allowed by a particular server or Kerberos realm).</li> +<li><strong>GSS_C_NT_MACHINE_UID_NAME</strong>: The value is uid_t object. On +Unix-like systems, the username of the uid is looked up in the +system user database and the resulting username is parsed as a +principal name.</li> +<li><strong>GSS_C_NT_STRING_UID_NAME</strong>: As above, but the value is a decimal +string representation of the uid.</li> +<li><strong>GSS_C_NT_EXPORT_NAME</strong>: The value must be the result of a +<a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.13">gss_export_name</a> call.</li> +</ul> +</div> +<div class="section" id="initiator-credentials"> +<h2>Initiator credentials<a class="headerlink" href="#initiator-credentials" title="Permalink to this headline">¶</a></h2> +<p>A GSSAPI client application uses <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.19">gss_init_sec_context</a> to establish a +security context. The <em>initiator_cred_handle</em> parameter determines +what tickets are used to establish the connection. An application can +either pass <strong>GSS_C_NO_CREDENTIAL</strong> to use the default client +credential, or it can use <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.2">gss_acquire_cred</a> beforehand to acquire an +initiator credential. The call to <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.2">gss_acquire_cred</a> may include a +<em>desired_name</em> parameter, or it may pass <strong>GSS_C_NO_NAME</strong> if it does +not have a specific name preference.</p> +<p>If the desired name for a krb5 initiator credential is a host-based +name, it is converted to a principal name of the form +<tt class="docutils literal"><span class="pre">service/hostname</span></tt> in the local realm, where <em>hostname</em> is the local +hostname if not specified. The hostname will be canonicalized using +forward name resolution, and possibly also using reverse name +resolution depending on the value of the <strong>rdns</strong> variable in +<a class="reference internal" href="../admin/conf_files/krb5_conf.html#libdefaults"><em>[libdefaults]</em></a>.</p> +<p>If a desired name is specified in the call to <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.2">gss_acquire_cred</a>, the +krb5 mechanism will attempt to find existing tickets for that client +principal name in the default credential cache or collection. If the +default cache type does not support a collection, and the default +cache contains credentials for a different principal than the desired +name, a <strong>GSS_S_CRED_UNAVAIL</strong> error will be returned with a minor +code indicating a mismatch.</p> +<p>If no existing tickets are available for the desired name, but the +name has an entry in the default client <a class="reference internal" href="../basic/keytab_def.html#keytab-definition"><em>keytab</em></a>, the +krb5 mechanism will acquire initial tickets for the name using the +default client keytab.</p> +<p>If no desired name is specified, credential acquisition will be +deferred until the credential is used in a call to +<a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.19">gss_init_sec_context</a> or <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.21">gss_inquire_cred</a>. If the call is to +<a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.19">gss_init_sec_context</a>, the target name will be used to choose a client +principal name using the credential cache selection facility. (This +facility might, for instance, try to choose existing tickets for a +client principal in the same realm as the target service). If there +are no existing tickets for the chosen principal, but it is present in +the default client keytab, the krb5 mechanism will acquire initial +tickets using the keytab.</p> +<p>If the target name cannot be used to select a client principal +(because the credentials are used in a call to <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.21">gss_inquire_cred</a>), or +if the credential cache selection facility cannot choose a principal +for it, the default credential cache will be selected if it exists and +contains tickets.</p> +<p>If the default credential cache does not exist, but the default client +keytab does, the krb5 mechanism will try to acquire initial tickets +for the first principal in the default client keytab.</p> +<p>If the krb5 mechanism acquires initial tickets using the default +client keytab, the resulting tickets will be stored in the default +cache or collection, and will be refreshed by future calls to +<a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.2">gss_acquire_cred</a> as they approach their expire time.</p> +</div> +<div class="section" id="acceptor-names"> +<h2>Acceptor names<a class="headerlink" href="#acceptor-names" title="Permalink to this headline">¶</a></h2> +<p>A GSSAPI server application uses <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.1">gss_accept_sec_context</a> to establish +a security context based on tokens provided by the client. The +<em>acceptor_cred_handle</em> parameter determines what +<a class="reference internal" href="../basic/keytab_def.html#keytab-definition"><em>keytab</em></a> entries may be authenticated to by the +client, if the krb5 mechanism is used.</p> +<p>The simplest choice is to pass <strong>GSS_C_NO_CREDENTIAL</strong> as the acceptor +credential. In this case, clients may authenticate to any service +principal in the default keytab (typically <a class="reference internal" href="../mitK5defaults.html#paths"><em>DEFKTNAME</em></a>, or the value of +the <strong>KRB5_KTNAME</strong> environment variable). This is the recommended +approach if the server application has no specific requirements to the +contrary.</p> +<p>A server may acquire an acceptor credential with <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.2">gss_acquire_cred</a> and +a <em>cred_usage</em> of <strong>GSS_C_ACCEPT</strong> or <strong>GSS_C_BOTH</strong>. If the +<em>desired_name</em> parameter is <strong>GSS_C_NO_NAME</strong>, then clients will be +allowed to authenticate to any service principal in the default +keytab, just as if no acceptor credential was supplied.</p> +<p>If a server wishes to specify a <em>desired_name</em> to <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.2">gss_acquire_cred</a>, +the most common choice is a host-based name. If the host-based +<em>desired_name</em> contains just a <em>service</em>, then clients will be allowed +to authenticate to any host-based service principal (that is, a +principal of the form <tt class="docutils literal"><span class="pre">service/hostname@REALM</span></tt>) for the named +service, regardless of hostname or realm, as long as it is present in +the default keytab. If the input name contains both a <em>service</em> and a +<em>hostname</em>, clients will be allowed to authenticate to any host-based +principal for the named service and hostname, regardless of realm.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">If a <em>hostname</em> is specified, it will be canonicalized +using forward name resolution, and possibly also using +reverse name resolution depending on the value of the +<strong>rdns</strong> variable in <a class="reference internal" href="../admin/conf_files/krb5_conf.html#libdefaults"><em>[libdefaults]</em></a>.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">If the <strong>ignore_acceptor_hostname</strong> variable in +<a class="reference internal" href="../admin/conf_files/krb5_conf.html#libdefaults"><em>[libdefaults]</em></a> is enabled, then <em>hostname</em> will be +ignored even if one is specified in the input name.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">In MIT krb5 versions prior to 1.10, and in Heimdal’s +implementation of the krb5 mechanism, an input name with +just a <em>service</em> is treated like an input name of +<tt class="docutils literal"><span class="pre">service@localhostname</span></tt>, where <em>localhostname</em> is the +string returned by gethostname().</p> +</div> +<p>If the <em>desired_name</em> is a krb5 principal name or a local system name +type which is mapped to a krb5 principal name, clients will only be +allowed to authenticate to that principal in the default keytab.</p> +</div> +<div class="section" id="name-attributes"> +<h2>Name Attributes<a class="headerlink" href="#name-attributes" title="Permalink to this headline">¶</a></h2> +<p>In release 1.8 or later, the <a class="reference external" href="http://tools.ietf.org/html/rfc6680.txt#section-7.4">gss_inquire_name</a> and +<a class="reference external" href="http://tools.ietf.org/html/6680.html#section-7.5">gss_get_name_attribute</a> functions, specified in <span class="target" id="index-3"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc6680.html"><strong>RFC 6680</strong></a>, can be +used to retrieve name attributes from the <em>src_name</em> returned by +<a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.1">gss_accept_sec_context</a>. The following attributes are defined when +the krb5 mechanism is used:</p> +<ul class="simple" id="gssapi-authind-attr"> +<li>“auth-indicators” attribute:</li> +</ul> +<p>This attribute will be included in the <a class="reference external" href="http://tools.ietf.org/html/rfc6680.txt#section-7.4">gss_inquire_name</a> output if the +ticket contains <a class="reference internal" href="../admin/auth_indicator.html#auth-indicator"><em>authentication indicators</em></a>. +One indicator is returned per invocation of <a class="reference external" href="http://tools.ietf.org/html/6680.html#section-7.5">gss_get_name_attribute</a>, +so multiple invocations may be necessary to retrieve all of the +indicators from the ticket. (New in release 1.15.)</p> +</div> +<div class="section" id="importing-and-exporting-credentials"> +<h2>Importing and exporting credentials<a class="headerlink" href="#importing-and-exporting-credentials" title="Permalink to this headline">¶</a></h2> +<p>The following GSSAPI extensions can be used to import and export +credentials (declared in <tt class="docutils literal"><span class="pre"><gssapi/gssapi_ext.h></span></tt>):</p> +<div class="highlight-python"><div class="highlight"><pre>OM_uint32 gss_export_cred(OM_uint32 *minor_status, + gss_cred_id_t cred_handle, + gss_buffer_t token); + +OM_uint32 gss_import_cred(OM_uint32 *minor_status, + gss_buffer_t token, + gss_cred_id_t *cred_handle); +</pre></div> +</div> +<p>The first function serializes a GSSAPI credential handle into a +buffer; the second unseralizes a buffer into a GSSAPI credential +handle. Serializing a credential does not destroy it. If any of the +mechanisms used in <em>cred_handle</em> do not support serialization, +gss_export_cred will return <strong>GSS_S_UNAVAILABLE</strong>. As with other +GSSAPI serialization functions, these extensions are only intended to +work with a matching implementation on the other side; they do not +serialize credentials in a standardized format.</p> +<p>A serialized credential may contain secret information such as ticket +session keys. The serialization format does not protect this +information from eavesdropping or tampering. The calling application +must take care to protect the serialized credential when communicating +it over an insecure channel or to an untrusted party.</p> +<p>A krb5 GSSAPI credential may contain references to a credential cache, +a client keytab, an acceptor keytab, and a replay cache. These +resources are normally serialized as references to their external +locations (such as the filename of the credential cache). Because of +this, a serialized krb5 credential can only be imported by a process +with similar privileges to the exporter. A serialized credential +should not be trusted if it originates from a source with lower +privileges than the importer, as it may contain references to external +credential cache, keytab, or replay cache resources not accessible to +the originator.</p> +<p>An exception to the above rule applies when a krb5 GSSAPI credential +refers to a memory credential cache, as is normally the case for +delegated credentials received by <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.1">gss_accept_sec_context</a>. In this +case, the contents of the credential cache are serialized, so that the +resulting token may be imported even if the original memory credential +cache no longer exists.</p> +</div> +<div class="section" id="constrained-delegation-s4u"> +<h2>Constrained delegation (S4U)<a class="headerlink" href="#constrained-delegation-s4u" title="Permalink to this headline">¶</a></h2> +<p>The Microsoft S4U2Self and S4U2Proxy Kerberos protocol extensions +allow an intermediate service to acquire credentials from a client to +a target service without requiring the client to delegate a +ticket-granting ticket, if the KDC is configured to allow it.</p> +<p>To perform a constrained delegation operation, the intermediate +service must submit to the KDC an “evidence ticket” from the client to +the intermediate service with the forwardable bit set. An evidence +ticket can be acquired when the client authenticates to the +intermediate service with Kerberos, or with an S4U2Self request if the +KDC allows it. The MIT krb5 GSSAPI library represents an evidence +ticket using a “proxy credential”, which is a special kind of +gss_cred_id_t object whose underlying credential cache contains the +evidence ticket and a krbtgt ticket for the intermediate service.</p> +<p>To acquire a proxy credential during client authentication, the +service should first create an acceptor credential using the +<strong>GSS_C_BOTH</strong> usage. The application should then pass this +credential as the <em>acceptor_cred_handle</em> to <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.1">gss_accept_sec_context</a>, +and also pass a <em>delegated_cred_handle</em> output parameter to receive a +proxy credential containing the evidence ticket. The output value of +<em>delegated_cred_handle</em> may be a delegated ticket-granting ticket if +the client sent one, or a proxy credential if the client authenticated +with a forwardable service ticket, or <strong>GSS_C_NO_CREDENTIAL</strong> if +neither is the case.</p> +<p>To acquire a proxy credential using an S4U2Self request, the service +can use the following GSSAPI extension:</p> +<div class="highlight-python"><div class="highlight"><pre>OM_uint32 gss_acquire_cred_impersonate_name(OM_uint32 *minor_status, + gss_cred_id_t icred, + gss_name_t desired_name, + OM_uint32 time_req, + gss_OID_set desired_mechs, + gss_cred_usage_t cred_usage, + gss_cred_id_t *output_cred, + gss_OID_set *actual_mechs, + OM_uint32 *time_rec); +</pre></div> +</div> +<p>The parameters to this function are similar to those of +<a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.2">gss_acquire_cred</a>, except that <em>icred</em> is used to make an S4U2Self +request to the KDC for a ticket from <em>desired_name</em> to the +intermediate service. Both <em>icred</em> and <em>desired_name</em> are required +for this function; passing <strong>GSS_C_NO_CREDENTIAL</strong> or +<strong>GSS_C_NO_NAME</strong> will cause the call to fail. <em>icred</em> must contain a +krbtgt ticket for the intermediate service. If the KDC returns a +forwardable ticket, the result of this operation is a proxy +credential; if it is not forwardable, the result is a regular +credential for <em>desired_name</em>.</p> +<p>A recent KDC will usually allow any service to acquire a ticket from a +client to itself with an S4U2Self request, but the ticket will only be +forwardable if the service has a specific privilege. In the MIT krb5 +KDC, this privilege is determined by the <strong>ok_to_auth_as_delegate</strong> +bit on the intermediate service’s principal entry, which can be +configured with <a class="reference internal" href="../admin/admin_commands/kadmin_local.html#kadmin-1"><em>kadmin</em></a>.</p> +<p>Once the intermediate service has a proxy credential, it can simply +pass it to <a class="reference external" href="http://tools.ietf.org/html/rfc2744.html#section-5.19">gss_init_sec_context</a> as the <em>initiator_cred_handle</em> +parameter, and the desired service as the <em>target_name</em> parameter. +The GSSAPI library will present the krbtgt ticket and evidence ticket +in the proxy credential to the KDC in an S4U2Proxy request; if the +intermediate service has the appropriate permissions, the KDC will +issue a ticket from the client to the target service. The GSSAPI +library will then use this ticket to authenticate to the target +service.</p> +</div> +<div class="section" id="aead-message-wrapping"> +<h2>AEAD message wrapping<a class="headerlink" href="#aead-message-wrapping" title="Permalink to this headline">¶</a></h2> +<p>The following GSSAPI extensions (declared in +<tt class="docutils literal"><span class="pre"><gssapi/gssapi_ext.h></span></tt>) can be used to wrap and unwrap messages +with additional “associated data” which is integrity-checked but is +not included in the output buffer:</p> +<div class="highlight-python"><div class="highlight"><pre>OM_uint32 gss_wrap_aead(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + int conf_req_flag, gss_qop_t qop_req, + gss_buffer_t input_assoc_buffer, + gss_buffer_t input_payload_buffer, + int *conf_state, + gss_buffer_t output_message_buffer); + +OM_uint32 gss_unwrap_aead(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t input_message_buffer, + gss_buffer_t input_assoc_buffer, + gss_buffer_t output_payload_buffer, + int *conf_state, + gss_qop_t *qop_state); +</pre></div> +</div> +<p>Wrap tokens created with gss_wrap_aead will successfully unwrap only +if the same <em>input_assoc_buffer</em> contents are presented to +gss_unwrap_aead.</p> +</div> +<div class="section" id="iov-message-wrapping"> +<h2>IOV message wrapping<a class="headerlink" href="#iov-message-wrapping" title="Permalink to this headline">¶</a></h2> +<p>The following extensions (declared in <tt class="docutils literal"><span class="pre"><gssapi/gssapi_ext.h></span></tt>) can +be used for in-place encryption, fine-grained control over wrap token +layout, and for constructing wrap tokens compatible with Microsoft DCE +RPC:</p> +<div class="highlight-python"><div class="highlight"><pre>typedef struct gss_iov_buffer_desc_struct { + OM_uint32 type; + gss_buffer_desc buffer; +} gss_iov_buffer_desc, *gss_iov_buffer_t; + +OM_uint32 gss_wrap_iov(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + int conf_req_flag, gss_qop_t qop_req, + int *conf_state, + gss_iov_buffer_desc *iov, int iov_count); + +OM_uint32 gss_unwrap_iov(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + int *conf_state, gss_qop_t *qop_state, + gss_iov_buffer_desc *iov, int iov_count); + +OM_uint32 gss_wrap_iov_length(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + int conf_req_flag, + gss_qop_t qop_req, int *conf_state, + gss_iov_buffer_desc *iov, + int iov_count); + +OM_uint32 gss_release_iov_buffer(OM_uint32 *minor_status, + gss_iov_buffer_desc *iov, + int iov_count); +</pre></div> +</div> +<p>The caller of gss_wrap_iov provides an array of gss_iov_buffer_desc +structures, each containing a type and a gss_buffer_desc structure. +Valid types include:</p> +<ul class="simple"> +<li><strong>GSS_C_BUFFER_TYPE_DATA</strong>: A data buffer to be included in the +token, and to be encrypted or decrypted in-place if the token is +confidentiality-protected.</li> +<li><strong>GSS_C_BUFFER_TYPE_HEADER</strong>: The GSSAPI wrap token header and +underlying cryptographic header.</li> +<li><strong>GSS_C_BUFFER_TYPE_TRAILER</strong>: The cryptographic trailer, if one is +required.</li> +<li><strong>GSS_C_BUFFER_TYPE_PADDING</strong>: Padding to be combined with the data +during encryption and decryption. (The implementation may choose to +place padding in the trailer buffer, in which case it will set the +padding buffer length to 0.)</li> +<li><strong>GSS_C_BUFFER_TYPE_STREAM</strong>: For unwrapping only, a buffer +containing a complete wrap token in standard format to be unwrapped.</li> +<li><strong>GSS_C_BUFFER_TYPE_SIGN_ONLY</strong>: A buffer to be included in the +token’s integrity protection checksum, but not to be encrypted or +included in the token itself.</li> +</ul> +<p>For gss_wrap_iov, the IOV list should contain one HEADER buffer, +followed by zero or more SIGN_ONLY buffers, followed by one or more +DATA buffers, followed by a TRAILER buffer. The memory pointed to by +the buffers is not required to be contiguous or in any particular +order. If <em>conf_req_flag</em> is true, DATA buffers will be encrypted +in-place, while SIGN_ONLY buffers will not be modified.</p> +<p>The type of an output buffer may be combined with +<strong>GSS_C_BUFFER_FLAG_ALLOCATE</strong> to request that gss_wrap_iov allocate +the buffer contents. If gss_wrap_iov allocates a buffer, it sets the +<strong>GSS_C_BUFFER_FLAG_ALLOCATED</strong> flag on the buffer type. +gss_release_iov_buffer can be used to release all allocated buffers +within an iov list and unset their allocated flags. Here is an +example of how gss_wrap_iov can be used with allocation requested +(<em>ctx</em> is assumed to be a previously established gss_ctx_id_t):</p> +<div class="highlight-python"><div class="highlight"><pre>OM_uint32 major, minor; +gss_iov_buffer_desc iov[4]; +char str[] = "message"; + +iov[0].type = GSS_IOV_BUFFER_TYPE_HEADER | GSS_IOV_BUFFER_FLAG_ALLOCATE; +iov[1].type = GSS_IOV_BUFFER_TYPE_DATA; +iov[1].buffer.value = str; +iov[1].buffer.length = strlen(str); +iov[2].type = GSS_IOV_BUFFER_TYPE_PADDING | GSS_IOV_BUFFER_FLAG_ALLOCATE; +iov[3].type = GSS_IOV_BUFFER_TYPE_TRAILER | GSS_IOV_BUFFER_FLAG_ALLOCATE; + +major = gss_wrap_iov(&minor, ctx, 1, GSS_C_QOP_DEFAULT, NULL, + iov, 4); +if (GSS_ERROR(major)) + handle_error(major, minor); + +/* Transmit or otherwise use resulting buffers. */ + +(void)gss_release_iov_buffer(&minor, iov, 4); +</pre></div> +</div> +<p>If the caller does not choose to request buffer allocation by +gss_wrap_iov, it should first call gss_wrap_iov_length to query the +lengths of the HEADER, PADDING, and TRAILER buffers. DATA buffers +must be provided in the iov list so that padding length can be +computed correctly, but the output buffers need not be initialized. +Here is an example of using gss_wrap_iov_length and gss_wrap_iov:</p> +<div class="highlight-python"><div class="highlight"><pre>OM_uint32 major, minor; +gss_iov_buffer_desc iov[4]; +char str[1024] = "message", *ptr; + +iov[0].type = GSS_IOV_BUFFER_TYPE_HEADER; +iov[1].type = GSS_IOV_BUFFER_TYPE_DATA; +iov[1].buffer.value = str; +iov[1].buffer.length = strlen(str); + +iov[2].type = GSS_IOV_BUFFER_TYPE_PADDING; +iov[3].type = GSS_IOV_BUFFER_TYPE_TRAILER; + +major = gss_wrap_iov_length(&minor, ctx, 1, GSS_C_QOP_DEFAULT, + NULL, iov, 4); +if (GSS_ERROR(major)) + handle_error(major, minor); +if (strlen(str) + iov[0].buffer.length + iov[2].buffer.length + + iov[3].buffer.length > sizeof(str)) + handle_out_of_space_error(); +ptr = str + strlen(str); +iov[0].buffer.value = ptr; +ptr += iov[0].buffer.length; +iov[2].buffer.value = ptr; +ptr += iov[2].buffer.length; +iov[3].buffer.value = ptr; + +major = gss_wrap_iov(&minor, ctx, 1, GSS_C_QOP_DEFAULT, NULL, + iov, 4); +if (GSS_ERROR(major)) + handle_error(major, minor); +</pre></div> +</div> +<p>If the context was established using the <strong>GSS_C_DCE_STYLE</strong> flag +(described in <span class="target" id="index-4"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc4757.html"><strong>RFC 4757</strong></a>), wrap tokens compatible with Microsoft DCE +RPC can be constructed. In this case, the IOV list must include a +SIGN_ONLY buffer, a DATA buffer, a second SIGN_ONLY buffer, and a +HEADER buffer in that order (the order of the buffer contents remains +arbitrary). The application must pad the DATA buffer to a multiple of +16 bytes as no padding or trailer buffer is used.</p> +<p>gss_unwrap_iov may be called with an IOV list just like one which +would be provided to gss_wrap_iov. DATA buffers will be decrypted +in-place if they were encrypted, and SIGN_ONLY buffers will not be +modified.</p> +<p>Alternatively, gss_unwrap_iov may be called with a single STREAM +buffer, zero or more SIGN_ONLY buffers, and a single DATA buffer. The +STREAM buffer is interpreted as a complete wrap token. The STREAM +buffer will be modified in-place to decrypt its contents. The DATA +buffer will be initialized to point to the decrypted data within the +STREAM buffer, unless it has the <strong>GSS_C_BUFFER_FLAG_ALLOCATE</strong> flag +set, in which case it will be initialized with a copy of the decrypted +data. Here is an example (<em>token</em> and <em>token_len</em> are assumed to be a +pre-existing pointer and length for a modifiable region of data):</p> +<div class="highlight-python"><div class="highlight"><pre>OM_uint32 major, minor; +gss_iov_buffer_desc iov[2]; + +iov[0].type = GSS_IOV_BUFFER_TYPE_STREAM; +iov[0].buffer.value = token; +iov[0].buffer.length = token_len; +iov[1].type = GSS_IOV_BUFFER_TYPE_DATA; +major = gss_unwrap_iov(&minor, ctx, NULL, NULL, iov, 2); +if (GSS_ERROR(major)) + handle_error(major, minor); + +/* Decrypted data is in iov[1].buffer, pointing to a subregion of + * token. */ +</pre></div> +</div> +</div> +<div class="section" id="iov-mic-tokens"> +<span id="gssapi-mic-token"></span><h2>IOV MIC tokens<a class="headerlink" href="#iov-mic-tokens" title="Permalink to this headline">¶</a></h2> +<p>The following extensions (declared in <tt class="docutils literal"><span class="pre"><gssapi/gssapi_ext.h></span></tt>) can +be used in release 1.12 or later to construct and verify MIC tokens +using an IOV list:</p> +<div class="highlight-python"><div class="highlight"><pre>OM_uint32 gss_get_mic_iov(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + gss_qop_t qop_req, + gss_iov_buffer_desc *iov, + int iov_count); + +OM_uint32 gss_get_mic_iov_length(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + gss_qop_t qop_req, + gss_iov_buffer_desc *iov, + iov_count); + +OM_uint32 gss_verify_mic_iov(OM_uint32 *minor_status, + gss_ctx_id_t context_handle, + gss_qop_t *qop_state, + gss_iov_buffer_desc *iov, + int iov_count); +</pre></div> +</div> +<p>The caller of gss_get_mic_iov provides an array of gss_iov_buffer_desc +structures, each containing a type and a gss_buffer_desc structure. +Valid types include:</p> +<ul class="simple"> +<li><strong>GSS_C_BUFFER_TYPE_DATA</strong> and <strong>GSS_C_BUFFER_TYPE_SIGN_ONLY</strong>: The +corresponding buffer for each of these types will be signed for the +MIC token, in the order provided.</li> +<li><strong>GSS_C_BUFFER_TYPE_MIC_TOKEN</strong>: The GSSAPI MIC token.</li> +</ul> +<p>The type of the MIC_TOKEN buffer may be combined with +<strong>GSS_C_BUFFER_FLAG_ALLOCATE</strong> to request that gss_get_mic_iov +allocate the buffer contents. If gss_get_mic_iov allocates the +buffer, it sets the <strong>GSS_C_BUFFER_FLAG_ALLOCATED</strong> flag on the buffer +type. gss_release_iov_buffer can be used to release all allocated +buffers within an iov list and unset their allocated flags. Here is +an example of how gss_get_mic_iov can be used with allocation +requested (<em>ctx</em> is assumed to be a previously established +gss_ctx_id_t):</p> +<div class="highlight-python"><div class="highlight"><pre>OM_uint32 major, minor; +gss_iov_buffer_desc iov[3]; + +iov[0].type = GSS_IOV_BUFFER_TYPE_DATA; +iov[0].buffer.value = "sign1"; +iov[0].buffer.length = 5; +iov[1].type = GSS_IOV_BUFFER_TYPE_SIGN_ONLY; +iov[1].buffer.value = "sign2"; +iov[1].buffer.length = 5; +iov[2].type = GSS_IOV_BUFFER_TYPE_MIC_TOKEN | GSS_IOV_BUFFER_FLAG_ALLOCATE; + +major = gss_get_mic_iov(&minor, ctx, GSS_C_QOP_DEFAULT, iov, 3); +if (GSS_ERROR(major)) + handle_error(major, minor); + +/* Transmit or otherwise use iov[2].buffer. */ + +(void)gss_release_iov_buffer(&minor, iov, 3); +</pre></div> +</div> +<p>If the caller does not choose to request buffer allocation by +gss_get_mic_iov, it should first call gss_get_mic_iov_length to query +the length of the MIC_TOKEN buffer. Here is an example of using +gss_get_mic_iov_length and gss_get_mic_iov:</p> +<div class="highlight-python"><div class="highlight"><pre>OM_uint32 major, minor; +gss_iov_buffer_desc iov[2]; +char data[1024]; + +iov[0].type = GSS_IOV_BUFFER_TYPE_MIC_TOKEN; +iov[1].type = GSS_IOV_BUFFER_TYPE_DATA; +iov[1].buffer.value = "message"; +iov[1].buffer.length = 7; + +major = gss_wrap_iov_length(&minor, ctx, 1, GSS_C_QOP_DEFAULT, + NULL, iov, 2); +if (GSS_ERROR(major)) + handle_error(major, minor); +if (iov[0].buffer.length > sizeof(data)) + handle_out_of_space_error(); +iov[0].buffer.value = data; + +major = gss_wrap_iov(&minor, ctx, 1, GSS_C_QOP_DEFAULT, NULL, + iov, 2); +if (GSS_ERROR(major)) + handle_error(major, minor); +</pre></div> +</div> +</div> +</div> + + + </div> + </div> + </div> + </div> + <div class="sidebar"> + <h2>On this page</h2> + <ul> +<li><a class="reference internal" href="#">Developing with GSSAPI</a><ul> +<li><a class="reference internal" href="#name-types">Name types</a></li> +<li><a class="reference internal" href="#initiator-credentials">Initiator credentials</a></li> +<li><a class="reference internal" href="#acceptor-names">Acceptor names</a></li> +<li><a class="reference internal" href="#name-attributes">Name Attributes</a></li> +<li><a class="reference internal" href="#importing-and-exporting-credentials">Importing and exporting credentials</a></li> +<li><a class="reference internal" href="#constrained-delegation-s4u">Constrained delegation (S4U)</a></li> +<li><a class="reference internal" href="#aead-message-wrapping">AEAD message wrapping</a></li> +<li><a class="reference internal" href="#iov-message-wrapping">IOV message wrapping</a></li> +<li><a class="reference internal" href="#iov-mic-tokens">IOV MIC tokens</a></li> +</ul> +</li> +</ul> + + <br/> + <h2>Table of contents</h2> + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../user/index.html">For users</a></li> +<li class="toctree-l1"><a class="reference internal" href="../admin/index.html">For administrators</a></li> +<li class="toctree-l1 current"><a class="reference internal" href="index.html">For application developers</a><ul class="current"> +<li class="toctree-l2 current"><a class="current reference internal" href="">Developing with GSSAPI</a><ul class="simple"> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="h5l_mit_apidiff.html">Differences between Heimdal and MIT Kerberos API</a></li> +<li class="toctree-l2"><a class="reference internal" href="init_creds.html">Initial credentials</a></li> +<li class="toctree-l2"><a class="reference internal" href="princ_handle.html">Principal manipulation and parsing</a></li> +<li class="toctree-l2"><a class="reference internal" href="refs/index.html">Complete reference - API and datatypes</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../plugindev/index.html">For plugin module developers</a></li> +<li class="toctree-l1"><a class="reference internal" href="../build/index.html">Building Kerberos V5</a></li> +<li class="toctree-l1"><a class="reference internal" href="../basic/index.html">Kerberos V5 concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="../formats/index.html">Protocols and file formats</a></li> +<li class="toctree-l1"><a class="reference internal" href="../mitK5features.html">MIT Kerberos features</a></li> +<li class="toctree-l1"><a class="reference internal" href="../build_this.html">How to build this documentation from the source</a></li> +<li class="toctree-l1"><a class="reference internal" href="../about.html">Contributing to the MIT Kerberos Documentation</a></li> +<li class="toctree-l1"><a class="reference internal" href="../resources.html">Resources</a></li> +</ul> + + <br/> + <h4><a href="../index.html">Full Table of Contents</a></h4> + <h4>Search</h4> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + </div> + <div class="clearer"></div> + </div> + </div> + + <div class="footer-wrapper"> + <div class="footer" > + <div class="right" ><i>Release: 1.15.1</i><br /> + © <a href="../copyright.html">Copyright</a> 1985-2017, MIT. + </div> + <div class="left"> + + <a href="../index.html" title="Full Table of Contents" + >Contents</a> | + <a href="index.html" title="For application developers" + >previous</a> | + <a href="h5l_mit_apidiff.html" title="Differences between Heimdal and MIT Kerberos API" + >next</a> | + <a href="../genindex.html" title="General Index" + >index</a> | + <a href="../search.html" title="Enter search criteria" + >Search</a> | + <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__Developing with GSSAPI">feedback</a> + </div> + </div> + </div> + + </body> +</html>
\ No newline at end of file |