lib/libgssapi/gssapi.3

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2005 Doug Rabson
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .Dd January 26, 2010
  28 .Dt GSSAPI 3
  29 .Os
  30 .Sh NAME
  31 .Nm gssapi
  32 .Nd "Generic Security Services API"
  33 .Sh LIBRARY
  34 GSS-API Library (libgssapi, -lgssapi)
  35 .Sh SYNOPSIS
  36 .In gssapi/gssapi.h
  37 .Sh DESCRIPTION
  38 The Generic Security Service Application Programming Interface
  39 provides security services to its callers,
  40 and is intended for implementation atop a variety of underlying
  41 cryptographic mechanisms.
  42 Typically, GSS-API callers will be application protocols into which
  43 security enhancements are integrated through invocation of services
  44 provided by the GSS-API.
  45 The GSS-API allows a caller application to authenticate a principal
  46 identity associated with a peer application, to delegate rights to a
  47 peer,
  48 and to apply security services such as confidentiality and integrity
  49 on a per-message basis.
  50 .Pp
  51 There are four stages to using the GSS-API:
  52 .Bl -tag -width "a)"
  53 .It a)
  54 The application acquires a set of credentials with which it may prove
  55 its identity to other processes.
  56 The application's credentials vouch for its global identity,
  57 which may or may not be related to any local username under which it
  58 may be running.
  59 .It b)
  60 A pair of communicating applications establish a joint security
  61 context using their credentials.
  62 The security context is a pair of GSS-API data structures that contain
  63 shared state information, which is required in order that per-message
  64 security services may be provided.
  65 Examples of state that might be shared between applications as part of
  66 a security context are cryptographic keys,
  67 and message sequence numbers.
  68 As part of the establishment of a security context,
  69 the context initiator is authenticated to the responder,
  70 and may require that the responder is authenticated in turn.
  71 The initiator may optionally give the responder the right to initiate
  72 further security contexts,
  73 acting as an agent or delegate of the initiator.
  74 This transfer of rights is termed delegation,
  75 and is achieved by creating a set of credentials,
  76 similar to those used by the initiating application,
  77 but which may be used by the responder.
  78 .Pp
  79 To establish and maintain the shared information that makes up the
  80 security context,
  81 certain GSS-API calls will return a token data structure,
  82 which is an opaque data type that may contain cryptographically
  83 protected data.
  84 The caller of such a GSS-API routine is responsible for transferring
  85 the token to the peer application,
  86 encapsulated if necessary in an application protocol.
  87 On receipt of such a token, the peer application should pass it to a
  88 corresponding GSS-API routine which will decode the token and extract
  89 the information,
  90 updating the security context state information accordingly.
  91 .It c)
  92 Per-message services are invoked to apply either:
  93 .Pp
  94 integrity and data origin authentication, or confidentiality,
  95 integrity and data origin authentication to application data,
  96 which are treated by GSS-API as arbitrary octet-strings.
  97 An application transmitting a message that it wishes to protect will
  98 call the appropriate GSS-API routine (gss_get_mic or gss_wrap) to
  99 apply protection,
 100 specifying the appropriate security context,
 101 and send the resulting token to the receiving application.
 102 The receiver will pass the received token (and, in the case of data
 103 protected by gss_get_mic, the accompanying message-data) to the
 104 corresponding decoding routine (gss_verify_mic or gss_unwrap) to
 105 remove the protection and validate the data.
 106 .It d)
 107 At the completion of a communications session (which may extend across
 108 several transport connections),
 109 each application calls a GSS-API routine to delete the security
 110 context.
 111 Multiple contexts may also be used (either successively or
 112 simultaneously) within a single communications association, at the
 113 option of the applications.
 114 .El
 115 .Sh GSS-API ROUTINES
 116 This section lists the routines that make up the GSS-API,
 117 and offers a brief description of the purpose of each routine.
 118 .Pp
 119 GSS-API Credential-management Routines:
 120 .Bl -tag -width "gss_inquire_cred_by_mech"
 121 .It gss_acquire_cred
 122 Assume a global identity; Obtain a GSS-API credential handle for
 123 pre-existing credentials.
 124 .It gss_add_cred
 125 Construct credentials incrementally
 126 .It gss_inquire_cred
 127 Obtain information about a credential
 128 .It gss_inquire_cred_by_mech
 129 Obtain per-mechanism information about a credential.
 130 .It gss_release_cred
 131 Discard a credential handle.
 132 .El
 133 .Pp
 134 GSS-API Context-Level Routines:
 135 .Bl -tag -width "gss_inquire_cred_by_mech"
 136 .It gss_init_sec_context
 137 Initiate a security context with a peer application
 138 .It gss_accept_sec_context
 139 Accept a security context initiated by a peer application
 140 .It gss_delete_sec_context
 141 Discard a security context
 142 .It gss_process_context_token
 143 Process a token on a security context from a peer application
 144 .It gss_context_time
 145 Determine for how long a context will remain valid
 146 .It gss_inquire_context
 147 Obtain information about a security context
 148 .It gss_wrap_size_limit
 149 Determine token-size limit for
 150 .Xr gss_wrap 3
 151 on a context
 152 .It gss_export_sec_context
 153 Transfer a security context to another process
 154 .It gss_import_sec_context
 155 Import a transferred context
 156 .El
 157 .Pp
 158 GSS-API Per-message Routines:
 159 .Bl -tag -width "gss_inquire_cred_by_mech"
 160 .It gss_get_mic
 161 Calculate a cryptographic message integrity code (MIC) for a message;
 162 integrity service
 163 .It gss_verify_mic
 164 Check a MIC against a message;
 165 verify integrity of a received message
 166 .It gss_wrap
 167 Attach a MIC to a message, and optionally encrypt the message content;
 168 confidentiality service
 169 .It gss_unwrap
 170 Verify a message with attached MIC, and decrypt message content if
 171 necessary.
 172 .El
 173 .Pp
 174 GSS-API Name manipulation Routines:
 175 .Bl -tag -width "gss_inquire_cred_by_mech"
 176 .It gss_import_name
 177 Convert a contiguous string name to internal-form
 178 .It gss_display_name
 179 Convert internal-form name to text
 180 .It gss_compare_name
 181 Compare two internal-form names
 182 .It gss_release_name
 183 Discard an internal-form name
 184 .It gss_inquire_names_for_mech
 185 List the name-types supported by the specified mechanism
 186 .It gss_inquire_mechs_for_name
 187 List mechanisms that support the specified name-type
 188 .It gss_canonicalize_name
 189 Convert an internal name to an MN
 190 .It gss_export_name
 191 Convert an MN to export form
 192 .It gss_duplicate_name
 193 Create a copy of an internal name
 194 .El
 195 .Pp
 196 GSS-API Miscellaneous Routines
 197 .Bl -tag -width "gss_inquire_cred_by_mech"
 198 .It gss_add_oid_set_member
 199 Add an object identifier to a set
 200 .It gss_display_status
 201 Convert a GSS-API status code to text
 202 .It gss_indicate_mechs
 203 Determine available underlying authentication mechanisms
 204 .It gss_release_buffer
 205 Discard a buffer
 206 .It gss_release_oid_set
 207 Discard a set of object identifiers
 208 .It gss_create_empty_oid_set
 209 Create a set containing no object identifiers
 210 .It gss_test_oid_set_member
 211 Determines whether an object identifier is a member of a set.
 212 .El
 213 .Pp
 214 Individual GSS-API implementations may augment these routines by
 215 providing additional mechanism-specific routines if required
 216 functionality is not available from the generic forms.
 217 Applications are encouraged to use the generic routines wherever
 218 possible on portability grounds.
 219 .Sh STANDARDS
 220 .Bl -tag -width ".It RFC 2743"
 221 .It RFC 2743
 222 Generic Security Service Application Program Interface Version 2, Update 1
 223 .It RFC 2744
 224 Generic Security Service API Version 2 : C-bindings
 225 .El
 226 .Sh HISTORY
 227 The
 228 .Nm
 229 library first appeared in
 230 .Fx 7.0 .
 231 .Sh AUTHORS
 232 John Wray, Iris Associates
 233 .Sh COPYRIGHT
 234 Copyright (C) The Internet Society (2000).  All Rights Reserved.
 235 .Pp
 236 This document and translations of it may be copied and furnished to
 237 others, and derivative works that comment on or otherwise explain it
 238 or assist in its implementation may be prepared, copied, published
 239 and distributed, in whole or in part, without restriction of any
 240 kind, provided that the above copyright notice and this paragraph are
 241 included on all such copies and derivative works.  However, this
 242 document itself may not be modified in any way, such as by removing
 243 the copyright notice or references to the Internet Society or other
 244 Internet organizations, except as needed for the purpose of
 245 developing Internet standards in which case the procedures for
 246 copyrights defined in the Internet Standards process must be
 247 followed, or as required to translate it into languages other than
 248 English.
 249 .Pp
 250 The limited permissions granted above are perpetual and will not be
 251 revoked by the Internet Society or its successors or assigns.
 252 .Pp
 253 This document and the information contained herein is provided on an
 254 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 255 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 256 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 257 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 258 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.