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