1 files changed, 261 insertions, 0 deletions
diff --git a/lib/libgssapi/gssapi.3 b/lib/libgssapi/gssapi.3
new file mode 100644
index 0000000..4eae063
--- /dev/null
+++ b/lib/libgssapi/gssapi.3
@@ -0,0 +1,261 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2005 Doug Rabson
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"	$FreeBSD$
+.\"
+.\" Copyright (C) The Internet Society (2000).  All Rights Reserved.
+.\"
+.\" This document and translations of it may be copied and furnished to
+.\" others, and derivative works that comment on or otherwise explain it
+.\" or assist in its implementation may be prepared, copied, published
+.\" and distributed, in whole or in part, without restriction of any
+.\" kind, provided that the above copyright notice and this paragraph are
+.\" included on all such copies and derivative works.  However, this
+.\" document itself may not be modified in any way, such as by removing
+.\" the copyright notice or references to the Internet Society or other
+.\" Internet organizations, except as needed for the purpose of
+.\" developing Internet standards in which case the procedures for
+.\" copyrights defined in the Internet Standards process must be
+.\" followed, or as required to translate it into languages other than
+.\" English.
+.\"
+.\" The limited permissions granted above are perpetual and will not be
+.\" revoked by the Internet Society or its successors or assigns.
+.\"
+.\" This document and the information contained herein is provided on an
+.\" "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+.\" TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+.\" BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+.\" HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.Dd November 30, 2005
+.Dt GSSAPI 3
+.Os
+.Sh NAME
+.Nm gssapi
+.Nd "Generic Security Services API"
+.Sh LIBRARY
+GSS-API Library (libgssapi, -lgssapi)
+.Sh SYNOPSIS
+.In gssapi/gssapi.h
+.Sh DESCRIPTION
+The Generic Security Service Application Programming Interface
+provides security services to its callers,
+and is intended for implementation atop a variety of underlying
+cryptographic mechanisms.
+Typically, GSS-API callers will be application protocols into which
+security enhancements are integrated through invocation of services
+provided by the GSS-API.
+The GSS-API allows a caller application to authenticate a principal
+identity associated with a peer application, to delegate rights to a
+peer,
+and to apply security services such as confidentiality and integrity
+on a per-message basis.
+.Pp
+There are four stages to using the GSS-API:
+.Pp
+.Bl -tag -width "a)"
+.It a)
+The application acquires a set of credentials with which it may prove
+its identity to other processes.
+The application's credentials vouch for its global identity,
+which may or may not be related to any local username under which it
+may be running.
+.It b)
+A pair of communicating applications establish a joint security
+context using their credentials.
+The security context is a pair of GSS-API data structures that contain
+shared state information, which is required in order that per-message
+security services may be provided.
+Examples of state that might be shared between applications as part of
+a security context are cryptographic keys,
+and message sequence numbers.
+As part of the establishment of a security context,
+the context initiator is authenticated to the responder,
+and may require that the responder is authenticated in turn.
+The initiator may optionally give the responder the right to initiate
+further security contexts,
+acting as an agent or delegate of the initiator.
+This transfer of rights is termed delegation,
+and is achieved by creating a set of credentials,
+similar to those used by the initiating application,
+but which may be used by the responder.
+.Pp
+To establish and maintain the shared information that makes up the
+security context,
+certain GSS-API calls will return a token data structure,
+which is an opaque data type that may contain cryptographically
+protected data.
+The caller of such a GSS-API routine is responsible for transferring
+the token to the peer application,
+encapsulated if necessary in an application protocol.
+On receipt of such a token, the peer application should pass it to a
+corresponding GSS-API routine which will decode the token and extract
+the information,
+updating the security context state information accordingly.
+.It c)
+Per-message services are invoked to apply either:
+.Pp
+integrity and data origin authentication, or confidentiality,
+integrity and data origin authentication to application data,
+which are treated by GSS-API as arbitrary octet-strings.
+An application transmitting a message that it wishes to protect will
+call the appropriate GSS-API routine (gss_get_mic or gss_wrap) to
+apply protection,
+specifying the appropriate security context,
+and send the resulting token to the receiving application.
+The receiver will pass the received token (and, in the case of data
+protected by gss_get_mic, the accompanying message-data) to the
+corresponding decoding routine (gss_verify_mic or gss_unwrap) to
+remove the protection and validate the data.
+.It d)
+At the completion of a communications session (which may extend across
+several transport connections),
+each application calls a GSS-API routine to delete the security
+context.
+Multiple contexts may also be used (either successively or
+simultaneously) within a single communications association, at the
+option of the applications.
+.El
+.Sh GSS-API ROUTINES
+This section lists the routines that make up the GSS-API,
+and offers a brief description of the purpose of each routine.
+.Pp
+GSS-API Credential-management Routines:
+.Bl -tag -width "gss_inquire_cred_by_mech"
+.It gss_acquire_cred
+Assume a global identity; Obtain a GSS-API credential handle for
+pre-existing credentials.
+.It gss_add_cred
+Construct credentials incrementally
+.It gss_inquire_cred
+Obtain information about a credential
+.It gss_inquire_cred_by_mech
+Obtain per-mechanism information about a credential.
+.It gss_release_cred
+Discard a credential handle.
+.El
+.Pp
+GSS-API Context-Level Routines:
+.Bl -tag -width "gss_inquire_cred_by_mech"
+.It gss_init_sec_context
+Initiate a security context with a peer application
+.It gss_accept_sec_context
+ Accept a security context initiated by a peer application
+.It gss_delete_sec_context
+Discard a security context
+.It gss_process_context_token
+Process a token on a security context from a peer application
+.It gss_context_time
+Determine for how long a context will remain valid
+.It gss_inquire_context
+Obtain information about a security context
+.It gss_wrap_size_limit
+Determine token-size limit for
+.Xr gss_wrap 3
+on a context
+.It gss_export_sec_context
+Transfer a security context to another process
+.It gss_import_sec_context
+Import a transferred context
+.El
+.Pp
+GSS-API Per-message Routines:
+.Bl -tag -width "gss_inquire_cred_by_mech"
+.It gss_get_mic
+Calculate a cryptographic message integrity code (MIC) for a message;
+integrity service
+.It gss_verify_mic
+Check a MIC against a message;
+verify integrity of a received message
+.It gss_wrap
+Attach a MIC to a message, and optionally encrypt the message content;
+confidentiality service
+.It gss_unwrap
+Verify a message with attached MIC, and decrypt message content if
+necessary.
+.El
+.Pp
+GSS-API Name manipulation Routines:
+.Bl -tag -width "gss_inquire_cred_by_mech"
+.It gss_import_name
+Convert a contiguous string name to internal-form
+.It gss_display_name
+Convert internal-form name to text
+.It gss_compare_name
+Compare two internal-form names
+.It gss_release_name
+Discard an internal-form name
+.It gss_inquire_names_for_mech
+List the name-types supported by the specified mechanism
+.It gss_inquire_mechs_for_name
+List mechanisms that support the specified name-type
+.It gss_canonicalize_name
+Convert an internal name to an MN
+.It gss_export_name
+Convert an MN to export form
+.It gss_duplicate_name
+Create a copy of an internal name
+.El
+.Pp
+GSS-API Miscellaneous Routines
+.Bl -tag -width "gss_inquire_cred_by_mech"
+.It gss_add_oid_set_member
+Add an object identifier to a set
+.It gss_display_status
+Convert a GSS-API status code to text
+.It gss_indicate_mechs
+Determine available underlying authentication mechanisms
+.It gss_release_buffer
+Discard a buffer
+.It gss_release_oid_set
+Discard a set of object identifiers
+.It gss_create_empty_oid_set
+Create a set containing no object identifiers
+.It gss_test_oid_set_member
+Determines whether an object identifier is a member of a set.
+.El
+.Pp
+Individual GSS-API implementations may augment these routines by
+providing additional mechanism-specific routines if required
+functionality is not available from the generic forms.
+Applications are encouraged to use the generic routines wherever
+possible on portability grounds.
+.Sh STANDARDS
+.Bl -tag
+.It RFC 2743
+Generic Security Service Application Program Interface Version 2, Update 1
+.It RFC 2744
+Generic Security Service API Version 2 : C-bindings
+.El
+.Sh HISTORY
+The
+.Nm
+manual page first appeared in
+.Fx 7.0 .
+.Sh AUTHORS
+John Wray, Iris Associates