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