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