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