From 11a75fc89d119bce37f50312638b02ab5adb3287 Mon Sep 17 00:00:00 2001 From: Assar Westerlund Date: Sat, 12 Apr 1997 21:32:36 +0000 Subject: [PATCH] more rfc/drafts git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@1560 ec53bebd-3082-4978-b11e-865c3cabbd6b --- doc/draft-ietf-cat-gssv2-08.txt | 62 + doc/draft-ietf-cat-gssv2-cbind-04.txt | 6188 +++++++++++++++++ doc/draft-ietf-cat-kerb-chg-password-00.txt | 252 + doc/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt | 127 + doc/draft-ietf-cat-kerb-key-derivation-00.txt | 250 + doc/draft-ietf-cat-kerb5gss-07.txt | 61 + doc/draft-ietf-cat-kerberos-err-msg-00.txt | 252 + doc/draft-ietf-cat-kerberos-passwords-02.txt | 16 + doc/draft-ietf-cat-kerberos-pk-cross-01.txt | 282 + doc/draft-ietf-cat-kerberos-pk-init-03.txt | 589 ++ doc/rfc1508.txt | 2747 ++++++++ doc/rfc1509.txt | 2691 +++++++ doc/rfc1964.txt | 1123 +++ .../draft-ietf-cat-gssv2-08.txt | 62 + .../draft-ietf-cat-gssv2-cbind-04.txt | 6188 +++++++++++++++++ .../draft-ietf-cat-kerb-des3-hmac-sha1-00.txt | 127 + .../draft-ietf-cat-kerb-key-derivation-00.txt | 250 + .../draft-ietf-cat-kerberos-err-msg-00.txt | 252 + .../draft-ietf-cat-kerberos-pk-cross-01.txt | 282 + .../draft-ietf-cat-kerberos-pk-init-03.txt | 589 ++ doc/standardisation/rfc1508.txt | 2747 ++++++++ doc/standardisation/rfc1509.txt | 2691 +++++++ doc/standardisation/rfc1964.txt | 1123 +++ 23 files changed, 28951 insertions(+) create mode 100644 doc/draft-ietf-cat-gssv2-08.txt create mode 100644 doc/draft-ietf-cat-gssv2-cbind-04.txt create mode 100644 doc/draft-ietf-cat-kerb-chg-password-00.txt create mode 100644 doc/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt create mode 100644 doc/draft-ietf-cat-kerb-key-derivation-00.txt create mode 100644 doc/draft-ietf-cat-kerb5gss-07.txt create mode 100644 doc/draft-ietf-cat-kerberos-err-msg-00.txt create mode 100644 doc/draft-ietf-cat-kerberos-passwords-02.txt create mode 100644 doc/draft-ietf-cat-kerberos-pk-cross-01.txt create mode 100644 doc/draft-ietf-cat-kerberos-pk-init-03.txt create mode 100644 doc/rfc1508.txt create mode 100644 doc/rfc1509.txt create mode 100644 doc/rfc1964.txt create mode 100644 doc/standardisation/draft-ietf-cat-gssv2-08.txt create mode 100644 doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt create mode 100644 doc/standardisation/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt create mode 100644 doc/standardisation/draft-ietf-cat-kerb-key-derivation-00.txt create mode 100644 doc/standardisation/draft-ietf-cat-kerberos-err-msg-00.txt create mode 100644 doc/standardisation/draft-ietf-cat-kerberos-pk-cross-01.txt create mode 100644 doc/standardisation/draft-ietf-cat-kerberos-pk-init-03.txt create mode 100644 doc/standardisation/rfc1508.txt create mode 100644 doc/standardisation/rfc1509.txt create mode 100644 doc/standardisation/rfc1964.txt diff --git a/doc/draft-ietf-cat-gssv2-08.txt b/doc/draft-ietf-cat-gssv2-08.txt new file mode 100644 index 000000000..ccba35eeb --- /dev/null +++ b/doc/draft-ietf-cat-gssv2-08.txt @@ -0,0 +1,62 @@ + + +A new Request for Comments is now available in online RFC libraries. + + + RFC 2078 + + Title: Generic Security Service Application Program + Interface, Version 2 + Author: J. Linn + Date: January 1997 + Mailbox: John.Linn@ov.com + Pages: 85 + Characters: 185990 + Obsoletes: 1508 + + URL: ftp://ds.internic.net/rfc/rfc2078.txt + + +This memo revises RFC-1508, making specific, incremental changes in +response to implementation experience and liaison requests. It is +intended, therefore, that this memo or a successor version thereto +will become the basis for subsequent progression of the GSS-API +specification on the standards track. This document is a product of +the Common Authentication Technology Working Group. + +This is now a Proposed Standard Protocol. + +This document specifies an Internet standards track protocol for the +Internet community, and requests discussion and suggestions for +improvements. Please refer to the current edition of the "Internet +Official Protocol Standards" (STD 1) for the standardization state and +status of this protocol. Distribution of this memo is unlimited. + +This announcement is sent to the IETF list and the RFC-DIST list. +Requests to be added to or deleted from the IETF distribution list +should be sent to IETF-REQUEST@CNRI.RESTON.VA.US. Requests to be +added to or deleted from the RFC-DIST distribution list should +be sent to RFC-DIST-REQUEST@ISI.EDU. + +Details on obtaining RFCs via FTP or EMAIL may be obtained by sending +an EMAIL message to rfc-info@ISI.EDU with the message body +help: ways_to_get_rfcs. For example: + + To: rfc-info@ISI.EDU + Subject: getting rfcs + + help: ways_to_get_rfcs + +Requests for special distribution should be addressed to either the +author of the RFC in question, or to admin@DS.INTERNIC.NET. Unless +specifically noted otherwise on the RFC itself, all RFCs are for +unlimited distribution. + +Submissions for Requests for Comments should be sent to +RFC-EDITOR@ISI.EDU. Please consult RFC 1543, Instructions to RFC +Authors, for further information. + + +Joyce K. Reynolds and Mary Kennedy +USC/Information Sciences Institute + diff --git a/doc/draft-ietf-cat-gssv2-cbind-04.txt b/doc/draft-ietf-cat-gssv2-cbind-04.txt new file mode 100644 index 000000000..518f4c63d --- /dev/null +++ b/doc/draft-ietf-cat-gssv2-cbind-04.txt @@ -0,0 +1,6188 @@ + + Internet draft J.Wray + IETF Common Authentication Technology WG Digital Equipment Corporation + March 1997 + + + + Generic Security Service API Version 2 : C-bindings + + + 1. STATUS OF THIS MEMO + + This document is an Internet Draft. Internet Drafts are working + documents of the Internet Engineering Task Force (IETF), its Areas, and + its Working Groups. Note that other groups may also distribute working + documents as Internet Drafts. Internet Drafts are draft documents valid + for a maximum of six months. Internet Drafts may be updated, replaced, + or obsoleted by other documents at any time. It is not appropriate to + use Internet Drafts as reference material or to cite them other than as + a "working draft" or "work in progress." Please check the I-D abstract + listing contained in each Internet Draft directory to learn the current + status of this or any other Internet Draft. + + Comments on this document should be sent to "cat-ietf@MIT.EDU", the IETF + Common Authentication Technology WG discussion list. + + + 2. ABSTRACT + + This draft document specifies C language bindings for Version 2 of the + Generic Security Service Application Program Interface (GSSAPI), which + is described at a language-independent conceptual level in other drafts + [GSSAPI]. It revises RFC-1509, making specific incremental changes in + response to implementation experience and liaison requests. It is + intended, therefore, that this draft or a successor version thereof will + become the basis for subsequent progression of the GSS-API specification + on the standards track. + + 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, + GSSAPI callers will be application protocols into which security + enhancements are integrated through invocation of services provided by + the GSSAPI. The GSSAPI 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. + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 1] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 3. INTRODUCTION + + The Generic Security Service Application Programming Interface [GSSAPI] + provides security services to calling applications. It allows a + communicating application to authenticate the user associated with + another application, to delegate rights to another application, and to + apply security services such as confidentiality and integrity on a per- + message basis. + + There are four stages to using the GSSAPI: + + (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. + + (b) A pair of communicating applications establish a joint security + context using their credentials. The security context is a pair + of GSSAPI 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. + + To establish and maintain the shared information that makes up the + security context, certain GSSAPI calls will return a token data + structure, which is a cryptographically protected opaque data + type. The caller of such a GSSAPI routine is responsible for + transferring the token to the peer application, encapsulated if + necessary in an application-application protocol. On receipt of + such a token, the peer application should pass it to a + corresponding GSSAPI routine which will decode the token and + extract the information, updating the security context state + information accordingly. + + (c) Per-message services are invoked to apply either: + + (i) integrity and data origin authentication, or + + (ii) confidentiality, integrity and data origin authentication + + to application data, which are treated by GSSAPI as arbitrary + octet-strings. An application transmitting a message that it + + + + Wray Document Expiration: 1 September 1997 [Page 2] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + wishes to protect will call the appropriate GSSAPI 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. + + (d) At the completion of a communications session (which may extend + across several transport connections), each application calls a + GSSAPI 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. + + + 4. GSSAPI ROUTINES + + This section lists the routines that make up the GSSAPI, and offers a + brief description of the purpose of each routine. Detailed descriptions + of each routine are listed in alphabetical order in section 7. + + Table 4-1 GSSAPI Credential-management Routines + + ROUTINE SECTION FUNCTION + + gss_acquire_cred 7.2 Assume a global identity; + Obtain a GSSAPI credential + handle for pre-existing + credentials. + + gss_add_cred 7.3 Construct credentials + incrementally + + gss_inquire_cred 7.21 Obtain information about + a credential. + + gss_inquire_cred_by_mech 7.22 Obtain per-mechanism information + about a credential. + + gss_release_cred 7.27 Discard a credential handle. + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 3] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Table 4-2 GSSAPI Context-level Routines + + ROUTINE SECTION FUNCTION + + gss_init_sec_context 7.19 Initiate a security context + with a peer application + + + gss_accept_sec_context 7.1 Accept a security context + initiated by a peer + application + + gss_delete_sec_context 7.9 Discard a security context + + gss_process_context_token 7.25 Process a token on a security + context from a peer + application + + gss_context_time 7.7 Determine for how long a + context will remain valid + + gss_inquire_context 7.20 Obtain information about a + security context + + gss_wrap_size_limit 7.33 Determine token-size limit for + gss_wrap on a context + + gss_export_sec_context 7.14 Transfer a security context to + another process + + gss_import_sec_context 7.17 Import a transferred context + + + + + Table 4-3 GSSAPI Per-message Routines + + ROUTINE SECTION FUNCTION + + gss_get_mic 7.15 Calculate a cryptographic + Message Integrity Code (MIC) + for a message; integrity service + + gss_verify_mic 7.32 Check a MIC against a message; + verify integrity of a received + message + + gss_wrap 7.36 Attach a MIC to a message, and + optionally encrypt the message + content; confidentiality service + + + + + Wray Document Expiration: 1 September 1997 [Page 4] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_unwrap 7.31 Verify a message with attached + MIC, and decrypt message + content if necessary. + + + + + Table 4-4 GSSAPI Name manipulation Routines + + ROUTINE SECTION FUNCTION + + gss_import_name 7.16 Convert a contiguous string name + to internal-form + + gss_display_name 7.10 Convert internal-form name + to text + + gss_compare_name 7.6 Compare two internal-form names + + gss_release_name 7.28 Discard an internal-form name + + gss_inquire_names_for_mech 7.24 List the name-types supported + by a specified mechanism + + gss_inquire_mechs_for_name 7.23 List mechanisms that support + a given nametype + + gss_canonicalize_name 7.5 Convert an internal name to + an MN. + + gss_export_name 7.13 Convert an MN to export form + + gss_duplicate_name 7.12 Create a copy of an internal name + + + + + Table 4-5 GSSAPI Miscellaneous Routines + + ROUTINE SECTION FUNCTION + + gss_display_status 7.11 Convert a GSSAPI status code + to text + + gss_indicate_mechs 7.18 Determine available underlying + authentication mechanisms + + gss_release_buffer 7.26 Discard a buffer + + gss_release_oid_set 7.29 Discard a set of object + identifiers + + + + Wray Document Expiration: 1 September 1997 [Page 5] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_create_empty_oid_set 7.8 Create a set containing no + object identifiers + + gss_add_oid_set_member 7.4 Add an object identifier to + a set + + gss_test_oid_set_member 7.30 Determines whether an object + identifier is a member of a set + + + + + + Individual GSSAPI 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. + + + 5. DATA TYPES AND CALLING CONVENTIONS + + The following conventions are used by the GSSAPI C-language bindings: + + 5.1. Integer types + + GSSAPI uses the following integer data type: + + OM_uint32 32-bit unsigned integer + + Where guaranteed minimum bit-count is important, this portable data type + is used by the GSSAPI routine definitions. Individual GSSAPI + implementations will include appropriate typedef definitions to map this + type onto a built-in data type. If the platform supports the X/Open + xom.h header file, the OM_uint32 definition contained therein should be + used; the GSSAPI header file in Appendix A contains logic that will + detect the prior inclusion of xom.h, and will not attempt to re-declare + OM_uint32. If the X/Open header file is not available on the platform, + the GSSAPI implementation should use the smallest natural unsigned + integer type that provides at least 32 bits of precision. + + 5.2. String and similar data + + Many of the GSSAPI routines take arguments and return values that + describe contiguous octet-strings. All such data is passed between the + GSSAPI and the caller using the gss_buffer_t data type. This data type + is a pointer to a buffer descriptor, which consists of a length field + that contains the total number of bytes in the datum, and a value field + which contains a pointer to the actual datum: + + + + + + Wray Document Expiration: 1 September 1997 [Page 6] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + Storage for data returned to the application by a GSSAPI routine using + the gss_buffer_t conventions is allocated by the GSSAPI routine. The + application may free this storage by invoking the gss_release_buffer + routine. Allocation of the gss_buffer_desc object is always the + responsibility of the application; unused gss_buffer_desc objects may + be initialized to the value GSS_C_EMPTY_BUFFER. + + 5.2.1. Opaque data types + + Certain multiple-word data items are considered opaque data types at the + GSSAPI, because their internal structure has no significance either to + the GSSAPI or to the caller. Examples of such opaque data types are the + input_token parameter to gss_init_sec_context (which is opaque to the + caller), and the input_message parameter to gss_wrap (which is opaque to + the GSSAPI). Opaque data is passed between the GSSAPI and the + application using the gss_buffer_t datatype. + + 5.2.2. Character strings + + Certain multiple-word data items may be regarded as simple ISO Latin-1 + character strings. Examples are the printable strings passed to + gss_import_name via the input_name_buffer parameter. Some GSSAPI + routines also return character strings. All such character strings are + passed between the application and the GSSAPI implementation using the + gss_buffer_t datatype, which is a pointer to a gss_buffer_desc object. + + When a gss_buffer_desc object describes a printable string, the length + field of the gss_buffer_desc should only count printable characters + within the string. In particular, a trailing NUL character should NOT + be included in the length count, nor should either the GSSAPI + implementation or the application assume the presence of an uncounted + trailing NUL. + + 5.3. Object Identifiers + + Certain GSSAPI procedures take parameters of the type gss_OID, or Object + identifier. This is a type containing ISO-defined tree-structured + values, and is used by the GSSAPI caller to select an underlying + security mechanism and to specify namespaces. A value of type gss_OID + has the following structure: + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + + + + Wray Document Expiration: 1 September 1997 [Page 7] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + The elements field of this structure points to the first byte of an + octet string containing the ASN.1 BER encoding of the value portion of + the normal BER TLV encoding of the gss_OID. The length field contains + the number of bytes in this value. For example, the gss_OID value + corresponding to {iso(1) identified-organization(3) icd-ecma(12) + member-company(2) dec(1011) cryptoAlgorithms(7) DASS(5)}, meaning the + DASS X.509 authentication mechanism, has a length field of 7 and an + elements field pointing to seven octets containing the following octal + values: 53,14,2,207,163,7,5. GSSAPI implementations should provide + constant gss_OID values to allow applications to request any supported + mechanism, although applications are encouraged on portability grounds + to accept the default mechanism. gss_OID values should also be provided + to allow applications to specify particular name types (see section + 5.10). Applications should treat gss_OID_desc values returned by GSSAPI + routines as read-only. In particular, the application should not + attempt to deallocate them with free(). The gss_OID_desc datatype is + equivalent to the X/Open OM_object_identifier datatype[XOM]. + + 5.4. Object Identifier Sets + + Certain GSSAPI procedures take parameters of the type gss_OID_set. This + type represents one or more object identifiers (section 5.3). A + gss_OID_set object has the following structure: + + typedef struct gss_OID_set_desc_struct { + size_t count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + The count field contains the number of OIDs within the set. The + elements field is a pointer to an array of gss_OID_desc objects, each of + which describes a single OID. gss_OID_set values are used to name the + available mechanisms supported by the GSSAPI, to request the use of + specific mechanisms, and to indicate which mechanisms a given credential + supports. + + All OID sets returned to the application by GSSAPI are dynamic objects + (the gss_OID_set_desc, the "elements" array of the set, and the + "elements" array of each member OID are all dynamically allocated), and + this storage must be deallocated by the application using the + gss_release_oid_set() routine. + + + 5.5. Credentials + + A credential handle is a caller-opaque atomic datum that identifies a + GSSAPI credential data structure. It is represented by the caller- + opaque type gss_cred_id_t, which should be implemented as a pointer or + arithmetic type. If a pointer implementation is chosen, care must be + taken to ensure that two gss_cred_id_t values may be compared with the + == operator. + + + + Wray Document Expiration: 1 September 1997 [Page 8] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSSAPI credentials can contain mechanism-specific principal + authentication data for multiple mechanisms. A GSSAPI credential is + composed of a set of credential-elements, each of which is applicable to + a single mechanism. A credential may contain at most one credential- + element for each supported mechanism. A credential-element identifies + the data needed by a single mechanism to authenticate a single + principal, and conceptually contains two credential-references that + describing the actual mechanism-specific authentication data, one to be + used by GSSAPI for initiating contexts, and one to be used for + accepting contexts. For mechanisms that do not distinguish between + acceptor and initiator credentials, both references would point to the + same underlying mechanism-specific authentication data. + + Credentials describe a set of mechanism-specific principals, and give + their holder the ability to act as any of those principals. All + principal identities asserted by a single GSSAPI credential should + belong to the same entity, although enforcement of this property is an + implementation-specific matter. The GSSAPI does not make the actual + credentials available to applications; instead a credential handle is + used to identify a particular credential, held internally by GSSAPI. + The combination of GSSAPI credential handle and mechanism identifies the + principal whose identity will be asserted by the credential when used + with that mechanism. + + The gss_init_sec_context and gss_accept_sec_context routines allow the + value GSS_C_NO_CREDENTIAL to be specified as their credential handle + parameter. This special credential-handle indicates a desire by the + application to act as a default principal. While individual GSSAPI + implementations are free to determine such default behavior as + appropriate to the mechanism, the following default behavior by these + routines is recommended for portability: + + (a) gss_init_sec_context + + (i) If there is only a single principal capable of initiating + security contexts for the chosen mechanism that the + application is authorized to act on behalf of, then that + principal shall be used, otherwise + + (ii) If the platform maintains a concept of a default network- + identity for the chosen mechanism, and if the application is + authorized to act on behalf of that identity for the purpose + of initiating security contexts, then the principal + corresponding to that identity shall be used, otherwise + + (iii) If the platform maintains a concept of a default local + identity, and provides a means to map local identities into + network-identities for the chosen mechanism, and if the + application is authorized to act on behalf of the network- + identity image of the default local identity for the purpose + of initiating security contexts using the chosen mechanism, + + + + Wray Document Expiration: 1 September 1997 [Page 9] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + then the principal corresponding to that identity shall be + used, otherwise + + (iv) A user-configurable default identity should be used. + + (b) gss_accept_sec_context + + (i) If there is only a single authorized principal identity + capable of accepting security contexts for the chosen + mechanism, then that principal shall be used, otherwise + + (ii) If the mechanism can determine the identity of the target + principal by examining the context-establishment token, and + if the accepting application is authorized to act as that + principal for the purpose of accepting security contexts + using the chosen mechanism, then that principal identity + shall be used, otherwise + + (iii) If the mechanism supports context acceptance by any + principal, and if mutual authentication was not requested, + any principal that the application is authorized to accept + security contexts under using the chosen mechanism may be + used, otherwise + + (iv) A user-configurable default identity shall be used. + + The purpose of the above rules is to allow security contexts to be + established by both initiator and acceptor using the default behavior + wherever possible. Applications requesting default behavior are likely + to be more portable across mechanisms and platforms than ones that use + gss_acquire_cred to request a specific identity. + + 5.6. Contexts + + The gss_ctx_id_t data type contains a caller-opaque atomic value that + identifies one end of a GSSAPI security context. It should be + implemented as a pointer or arithmetic type. If a pointer type is + chosen, care should be taken to ensure that two gss_ctx_id_t values may + be compared with the == operator. + + The security context holds state information about each end of a peer + communication, including cryptographic state information. + + 5.7. Authentication tokens + + A token is a caller-opaque type that GSSAPI uses to maintain + synchronization between the context data structures at each end of a + GSSAPI security context. The token is a cryptographically protected + octet-string, generated by the underlying mechanism at one end of a + GSSAPI security context for use by the peer mechanism at the other end. + Encapsulation (if required) and transfer of the token are the + + + + Wray Document Expiration: 1 September 1997 [Page 10] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + responsibility of the peer applications. A token is passed between the + GSSAPI and the application using the gss_buffer_t conventions. + + 5.8. Interprocess tokens + + Certain GSSAPI routines are intended to transfer data between processes + in multi-process programs. These routines use a caller-opaque octet- + string, generated by the GSSAPI in one process for use by the GSSAPI in + another process. The calling application is responsible for + transferring such tokens between processes in an OS-specific manner. + Note that, while GSSAPI implementors are encouraged to avoid placing + sensitive information within interprocess tokens, or to + cryptographically protect them, many implementations will be unable to + avoid placing key material or other sensitive data within them. It is + the application's responsibility to ensure that interprocess tokens are + protected in transit, and transferred only to processes that are + trustworthy. An interprocess token is passed between the GSSAPI and the + application using the gss_buffer_t conventions. + + 5.9. Status values + + One or more status codes are returned by each GSSAPI routine. Two + distinct sorts of status codes are returned. These are termed GSS + status codes and Mechanism status codes. + + 5.9.1. GSS status codes + + GSSAPI routines return GSS status codes as their OM_uint32 function + value. These codes indicate errors that are independent of the + underlying mechanism(s) used to provide the security service. The + errors that can be indicated via a GSS status code are either generic + API routine errors (errors that are defined in the GSS-API + specification) or calling errors (errors that are specific to these + language bindings). + + A GSS status code can indicate a single fatal generic API error from the + routine and a single calling error. In addition, supplementary status + information may be indicated via the setting of bits in the + supplementary info field of a GSS status code. + + These errors are encoded into the 32-bit GSS status code as follows: + + MSB LSB + |------------------------------------------------------------| + | Calling Error | Routine Error | Supplementary Info | + |------------------------------------------------------------| + Bit 31 24 23 16 15 0 + + + Hence if a GSS-API routine returns a GSS status code whose upper 16 bits + contain a non-zero value, the call failed. If the calling error field + + + + Wray Document Expiration: 1 September 1997 [Page 11] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + is non-zero, the invoking application's call of the routine was + erroneous. Calling errors are defined in table 5-1. If the routine + error field is non-zero, the routine failed for one of the routine- + specific reasons listed below in table 5-2. Whether or not the upper 16 + bits indicate a failure or a success, the routine may indicate + additional information by setting bits in the supplementary info field + of the status code. The meaning of individual bits is listed below in + table 5-3. + + Table 5-1 Calling Errors + + Name Value in Meaning + Field + GSS_S_CALL_INACCESSIBLE_READ 1 A required input + parameter could + not be read. + GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output + parameter could + not be written. + GSS_S_CALL_BAD_STRUCTURE 3 A parameter was + malformed + + + + + Table 5-2 Routine Errors + + Name Value in Meaning + Field + + GSS_S_BAD_MECH 1 An unsupported mechanism was + requested + GSS_S_BAD_NAME 2 An invalid name was supplied + GSS_S_BAD_NAMETYPE 3 A supplied name was of an + unsupported type + GSS_S_BAD_BINDINGS 4 Incorrect channel bindings + were supplied + GSS_S_BAD_STATUS 5 An invalid status code was + supplied + GSS_S_BAD_SIG 6 A token had an invalid + GSS_S_BAD_MIC MIC + GSS_S_NO_CRED 7 No credentials were supplied, + or the credentials were + unavailable or inaccessible. + GSS_S_NO_CONTEXT 8 No context has been + established + GSS_S_DEFECTIVE_TOKEN 9 A token was invalid + GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid + GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials + have expired + + + + + Wray Document Expiration: 1 September 1997 [Page 12] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_CONTEXT_EXPIRED 12 The context has expired + GSS_S_FAILURE 13 Miscellaneous failure + (see text) + GSS_S_BAD_QOP 14 The quality-of-protection + requested could not be + provide + GSS_S_UNAUTHORIZED 15 The operation is forbidden by + local security policy + GSS_S_UNAVAILABLE 16 The operation or option is not + available + GSS_S_DUPLICATE_ELEMENT 17 The requested credential element + already exists + GSS_S_NAME_NOT_MN 18 The provided name was not a + mechanism name. + + + + + + Table 5-3 Supplementary Status Bits + + Name Bit Number Meaning + GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called + again to complete its function. + See routine documentation for + detailed description. + GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of + an earlier token + GSS_S_OLD_TOKEN 2 The token's validity period + has expired + GSS_S_UNSEQ_TOKEN 3 A later token has already been + processed + GSS_S_GAP_TOKEN 4 An expected per-message token + was not received + + + The routine documentation also uses the name GSS_S_COMPLETE, which is a + zero value, to indicate an absence of any API errors or supplementary + information bits. + + All GSS_S_xxx symbols equate to complete OM_uint32 status codes, rather + than to bitfield values. For example, the actual value of the symbol + GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 << 16. + + The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and + GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS status + code and removes all but the relevant field. For example, the value + obtained by applying GSS_ROUTINE_ERROR to a status code removes the + calling errors and supplementary info fields, leaving only the routine + errors field. The values delivered by these macros may be directly + compared with a GSS_S_xxx symbol of the appropriate type. The macro + + + + Wray Document Expiration: 1 September 1997 [Page 13] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_ERROR() is also provided, which when applied to a GSS status code + returns a non-zero value if the status code indicated a calling or + routine error, and a zero value otherwise. All macros defined by GSS- + API evaluate their argument(s) exactly once. + + A GSS-API implementation may choose to signal calling errors in a + platform-specific manner instead of, or in addition to the routine + value; routine errors and supplementary info should be returned via + routine status values only. + + 5.9.2. Mechanism-specific status codes + + GSS-API routines return a minor_status parameter, which is used to + indicate specialized errors from the underlying security mechanism. + This parameter may contain a single mechanism-specific error, indicated + by a OM_uint32 value. + + The minor_status parameter will always be set by a GSS-API routine, even + if it returns a calling error or one of the generic API errors indicated + above as fatal, although most other output parameters may remain unset + in such cases. However, output parameters that are expected to return + pointers to storage allocated by a routine must always be set by the + routine, even in the event of an error, although in such cases the GSS- + API routine may elect to set the returned parameter value to NULL to + indicate that no storage was actually allocated. Any length field + associated with such pointers (as in a gss_buffer_desc structure) should + also be set to zero in such cases. + + The GSS status code GSS_S_FAILURE is used to indicate that the + underlying mechanism detected an error for which no specific GSS status + code is defined. The mechanism status code will provide more details + about the error. + + 5.10. Names + + A name is used to identify a person or entity. GSS-API authenticates + the relationship between a name and the entity claiming the name. + + Since different authentication mechanisms may employ different + namespaces for identifying their principals, GSSAPI's naming support is + necessarily complex in multi-mechanism environments (or even in some + single-mechanism environments where the underlying mechanism supports + multiple namespaces). + + Two distinct representations are defined for names: + + (a) An internal form. This is the GSSAPI "native" format for names, + represented by the implementation-specific gss_name_t type. It is + opaque to GSSAPI callers. A single gss_name_t object may contain + multiple names from different namespaces, but all names should + refer to the same entity. An example of such an internal name + + + + Wray Document Expiration: 1 September 1997 [Page 14] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + would be the name returned from a call to the gss_inquire_cred + routine, when applied to a credential containing credential + elements for multiple authentication mechanisms employing + different namespaces. This gss_name_t object will contain a + distinct name for the entity for each authentication mechanism. + + For GSSAPI implementations supporting multiple namespaces, objects + of type gss_name_t must contain sufficient information to + determine the namespace to which each primitive name belongs. + + (b) Mechanism-specific contiguous octet-string forms. A format + capable of containing a single name (from a single namespace). + Contiguous string names are always accompanied by an object + identifier specifying the namespace to which the name belongs, and + their format is dependent on the authentication mechanism that + employs the name. Many, but not all, contiguous string names will + be printable, and may therefore be used by GSSAPI applications for + communication with their users. + + Routines (gss_import_name and gss_display_name) are provided to convert + names between contiguous string representations and the internal + gss_name_t type. gss_import_name may support multiple syntaxes for each + supported namespace, allowing users the freedom to choose a preferred + name representation. gss_display_name should use an implementation- + chosen printable syntax for each supported name-type. + + If an application calls gss_display_name(), passing the internal name + resulting from a call to gss_import_name(), there is no guarantee the + the resulting contiguous string name will be the same as the original + imported string name. Nor do name-space identifiers necessarily survive + unchanged after a journey through the internal name-form. An example of + this might be a mechanism that authenticates X.500 names, but provides + an algorithmic mapping of Internet DNS names into X.500. That + mechanism's implementation of gss_import_name() might, when presented + with a DNS name, generate an internal name that contained both the + original DNS name and the equivalent X.500 name. Alternatively, it might + only store the X.500 name. In the latter case, gss_display_name() would + most likely generate a printable X.500 name, rather than the original + DNS name. + + The process of authentication delivers to the context acceptor an + internal name. Since this name has been authenticated by a single + mechanism, it contains only a single name (even if the internal name + presented by the context initiator to gss_init_sec_context had multiple + components). Such names are termed internal mechanism names, or "MN"s + and the names emitted by gss_accept_sec_context() are always of this + type. Since some applications may require MNs without wanting to incur + the overhead of an authentication operation, a second function, + gss_canonicalize_name(), is provided to convert a general internal name + into an MN. + + + + + Wray Document Expiration: 1 September 1997 [Page 15] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Comparison of internal-form names may be accomplished via the + gss_compare_name() routine, which returns true if the two names being + compared refer to the same entity. This removes the need for the + application program to understand the syntaxes of the various printable + names that a given GSS-API implementation may support. Since GSSAPI + assumes that all primitive names contained within a given internal name + refer to the same entity, gss_compare_name() can return true if the two + names have at least one primitive name in common. If the implementation + embodies knowledge of equivalence relationships between names taken from + different namespaces, this knowledge may also allow successful + comparison of internal names containing no overlapping primitive + elements. + + When used in large access control lists, the overhead of invoking + gss_import_name() and gss_compare_name() on each name from the ACL may + be prohibitive. As an alternative way of supporting this case, GSSAPI + defines a special form of the contiguous string name which may be + compared directly (e.g. with memcmp()). Contigous names suitable for + comparison are generated by the gss_export_name() routine, which + requires an MN as input. Exported names may be re-imported by the + gss_import_name() routine, and the resulting internal name will also be + an MN. The gss_OID constant GSS_C_NT_EXPORT_NAME indentifies the + "export name" type, and the value of this constant is given in Appendix + A. Structurally, an exported name object consists of a header + containing an OID identifying the mechanism that authenticated the name, + and a trailer containing the name itself, where the syntax of the + trailer is defined by the individual mechanism specification. The + precise format of an export name is defined in the language-independent + GSSAPI specification [GSSAPI]. + + Note that the results obtained by using gss_compare_name() will in + general be different from those obtained by invoking + gss_canonicalize_name() and gss_export_name(), and then comparing the + exported names. The first series of operation determines whether two + (unauthenticated) names identify the same principal; the second whether + a particular mechanism would authenticate them as the same principal. + These two operations will in general give the same results only for MNs. + + The gss_name_t datatype should be implemented as a pointer type. To + allow the compiler to aid the application programmer by performing + type-checking, the use of (void *) is discouraged. A pointer to an + implementation-defined type is the preferred choice. + + Storage is allocated by routines that return gss_name_t values. A + procedure, gss_release_name, is provided to free storage associated with + an internal-form name. + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 16] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 5.11. Channel Bindings + + GSS-API supports the use of user-specified tags to identify a given + context to the peer application. These tags are intended to be used to + identify the particular communications channel that carries the context. + Channel bindings are communicated to the GSS-API using the following + structure: + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + The initiator_addrtype and acceptor_addrtype fields denote the type of + addresses contained in the initiator_address and acceptor_address + buffers. The address type should be one of the following: + + GSS_C_AF_UNSPEC Unspecified address type + GSS_C_AF_LOCAL Host-local address type + GSS_C_AF_INET Internet address type (e.g. IP) + GSS_C_AF_IMPLINK ARPAnet IMP address type + GSS_C_AF_PUP pup protocols (eg BSP) address type + GSS_C_AF_CHAOS MIT CHAOS protocol address type + GSS_C_AF_NS XEROX NS address type + GSS_C_AF_NBS nbs address type + GSS_C_AF_ECMA ECMA address type + GSS_C_AF_DATAKIT datakit protocols address type + GSS_C_AF_CCITT CCITT protocols + GSS_C_AF_SNA IBM SNA address type + GSS_C_AF_DECnet DECnet address type + GSS_C_AF_DLI Direct data link interface address type + GSS_C_AF_LAT LAT address type + GSS_C_AF_HYLINK NSC Hyperchannel address type + GSS_C_AF_APPLETALK AppleTalk address type + GSS_C_AF_BSC BISYNC 2780/3780 address type + GSS_C_AF_DSS Distributed system services address type + GSS_C_AF_OSI OSI TP4 address type + GSS_C_AF_X25 X25 + GSS_C_AF_NULLADDR No address specified + + Note that these symbols name address families rather than specific + addressing formats. For address families that contain several + alternative address forms, the initiator_address and acceptor_address + fields must contain sufficient information to determine which address + form is used. When not otherwise specified, addresses should be + specified in network byte-order (that is, native byte-ordering for the + address family). + + + + + Wray Document Expiration: 1 September 1997 [Page 17] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Conceptually, the GSS-API concatenates the initiator_addrtype, + initiator_address, acceptor_addrtype, acceptor_address and + application_data to form an octet string. The mechanism calculates a + MIC over this octet string, and binds the MIC to the context + establishment token emitted by gss_init_sec_context. The same bindings + are presented by the context acceptor to gss_accept_sec_context, and a + MIC is calculated in the same way. The calculated MIC is compared with + that found in the token, and if the MICs differ, gss_accept_sec_context + will return a GSS_S_BAD_BINDINGS error, and the context will not be + established. Some mechanisms may include the actual channel binding + data in the token (rather than just a MIC); applications should + therefore not use confidential data as channel-binding components. + Individual mechanisms may impose additional constraints on addresses and + address types that may appear in channel bindings. For example, a + mechanism may verify that the initiator_address field of the channel + bindings presented to gss_init_sec_context contains the correct network + address of the host system. Portable applications should therefore + ensure that they either provide correct information for the address + fields, or omit addressing information, specifying GSS_C_AF_NULLADDR as + the address-types. + + 5.12. Optional parameters + + Various parameters are described as optional. This means that they + follow a convention whereby a default value may be requested. The + following conventions are used for omitted parameters. These + conventions apply only to those parameters that are explicitly + documented as optional. + + 5.12.1. gss_buffer_t types + + Specify GSS_C_NO_BUFFER as a value. For an input parameter this + signifies that default behavior is requested, while for an output + parameter it indicates that the information that would be returned via + the parameter is not required by the application. + + 5.12.2. Integer types (input) + + Individual parameter documentation lists values to be used to indicate + default actions. + + 5.12.3. Integer types (output) + + Specify NULL as the value for the pointer. + + 5.12.4. Pointer types + + Specify NULL as the value. + + + + + + + Wray Document Expiration: 1 September 1997 [Page 18] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 5.12.5. Object IDs + + Specify GSS_C_NO_OID as the value. + + 5.12.6. Object ID Sets + + Specify GSS_C_NO_OID_SET as the value. + + 5.12.7. Channel Bindings + + Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings are + not to be used. + + + 6. ADDITIONAL CONTROLS + + This section discusses the optional services that a context initiator + may request of the GSS-API at context establishment. Each of these + services is requested by setting a flag in the req_flags input parameter + to gss_init_sec_context. + + The optional services currently defined are: + + Delegation - The (usually temporary) transfer of rights from initiator + to acceptor, enabling the acceptor to authenticate itself as an + agent of the initiator. + + Mutual Authentication - In addition to the initiator authenticating its + identity to the context acceptor, the context acceptor should also + authenticate itself to the initiator. + + Replay detection - In addition to providing message integrity services, + gss_get_mic and gss_wrap should include message numbering + information to enable gss_verify_mic and gss_unwrap to detect if a + message has been duplicated. + + Out-of-sequence detection - In addition to providing message integrity + services, gss_get_mic and gss_wrap should include message + sequencing information to enable gss_verify_mic and gss_unwrap to + detect if a message has been received out of sequence. + + Anonymous authentication - The establishment of the security context + should not reveal the initiator's identity to the context + acceptor. + + Any currently undefined bits within such flag arguments should be + ignored by GSS-API implementations when presented by an application, and + should be set to zero when returned to the application by the GSS-API + implementation. + + + + + + Wray Document Expiration: 1 September 1997 [Page 19] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Some mechanisms may not support all optional services, and some + mechanisms may only support some services in conjunction with others. + Both gss_init_sec_context and gss_accept_sec_context inform the + applications which services will be available from the context when the + establishment phase is complete, via the ret_flags output parameter. In + general, if the security mechanism is capable of providing a requested + service, it should do so, even if additional services must be enabled in + order to provide the requested service. If the mechanism is incapable + of providing a requested service, it should proceed without the service, + leaving the application to abort the context establishment process if it + considers the requested service to be mandatory. + + Some mechanisms may specify that support for some services is optional, + and that implementors of the mechanism need not provide it. This is + most commonly true of the confidentiality service, often because of + legal restrictions on the use of data-encryption, but may apply to any + of the services. Such mechanisms are required to send at least one + token from acceptor to initiator during context establishment when the + initiator indicates a desire to use such a service, so that the + initiating GSSAPI can correctly indicate whether the service is + supported by the acceptor's GSSAPI. + + 6.1. Delegation + + The GSS-API allows delegation to be controlled by the initiating + application via a boolean parameter to gss_init_sec_context(), the + routine that establishes a security context. Some mechanisms do not + support delegation, and for such mechanisms attempts by an application + to enable delegation are ignored. + + The acceptor of a security context for which the initiator enabled + delegation will receive (via the delegated_cred_handle parameter of + gss_accept_sec_context) a credential handle that contains the delegated + identity, and this credential handle may be used to initiate subsequent + GSSAPI security contexts as an agent or delegate of the initiator. If + the original initiator's identity is "A" and the delegate's identity is + "B", then, depending on the underlying mechanism, the identity embodied + by the delegated credential may be either "A" or "B acting for A". + + For many mechanisms that support delegation, a simple boolean does not + provide enough control. Examples of additional aspects of delegation + control that a mechanism might provide to an application are duration of + delegation, network addresses from which delegation is valid, and + constraints on the tasks that may be performed by a delegate. Such + controls are presently outside the scope of the GSS-API. GSS-API + implementations supporting mechanisms offering additional controls + should provide extension routines that allow these controls to be + exercised (perhaps by modifying the initiator's GSS-API credential prior + to its use in establishing a context). However, the simple delegation + control provided by GSS-API should always be able to over-ride other + mechanism-specific delegation controls - If the application instructs + + + + Wray Document Expiration: 1 September 1997 [Page 20] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_init_sec_context() that delegation is not desired, then the + implementation must not permit delegation to occur. This is an + exception to the general rule that a mechanism may enable services even + if they are not requested - delegation may only be provide at the + explicit request of the application. + + 6.2. Mutual authentication + + Usually, a context acceptor will require that a context initiator + authenticate itself so that the acceptor may make an access-control + decision prior to performing a service for the initiator. In some + cases, the initiator may also request that the acceptor authenticate + itself. GSS-API allows the initiating application to request this + mutual authentication service by setting a flag when calling + gss_init_sec_context. + + The initiating application is informed as to whether or not mutual + authentication is being requested of the context acceptor. Note that + some mechanisms may not support mutual authentication, and other + mechanisms may always perform mutual authentication, whether or not the + initiating application requests it. In particular, mutual + authentication my be required by some mechanisms in order to support + replay or out-of-sequence message detection, and for such mechanisms a + request for either of these services will automatically enable mutual + authentication. + + 6.3. Replay and out-of-sequence detection + + The GSS-API may provide detection of mis-ordered message once a security + context has been established. Protection may be applied to messages by + either application, by calling either gss_get_mic or gss_wrap, and + verified by the peer application by calling gss_verify_mic or + gss_unwrap. + + gss_get_mic calculates a cryptographic checksum of an application + message, and returns that checksum in a token. The application should + pass both the token and the message to the peer application, which + presents them to gss_verify_mic. + + gss_wrap calculates a cryptographic checksum of an application message, + and places both the checksum and the message inside a single token. The + application should pass the token to the peer application, which + presents it to gss_unwrap to extract the message and verify the + checksum. + + Either pair of routines may be capable of detecting out-of-sequence + message delivery, or duplication of messages. Details of such mis- + ordered messages are indicated through supplementary status bits in the + major status code returned by gss_verify_mic or gss_unwrap. The + relevant supplementary bits are: + + + + + Wray Document Expiration: 1 September 1997 [Page 21] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has already + been received and processed. Contexts that do not claim to + provide replay detection may still set this bit if the duplicate + message is processed immediately after the original, with no + intervening messages. + + GSS_S_OLD_TOKEN - The token is too old to determine whether or not it is + a duplicate. Contexts supporting out-of-sequence detection but + not replay detection should always set this bit if + GSS_S_UNSEQ_TOKEN is set; contexts that support replay detection + should only set this bit if the token is so old that it cannot be + checked for duplication. + + GSS_S_UNSEQ_TOKEN - A later token has already been processed. + + GSS_S_GAP_TOKEN - An earlier token has not yet been received. + + A mechanism need not maintain a list of all tokens that have been + processed in order to support these status codes. A typical mechanism + might retain information about only the most recent "N" tokens + processed, allowing it to distinguish duplicates and missing tokens + within the most recent "N" messages; the receipt of a token older than + the most recent "N" would result in a GSS_S_OLD_TOKEN status. + + 6.4. Anonymous Authentication + + In certain situations, an application may wish to initiate the + authentication process to authenticate a peer, without revealing its own + identity. As an example, consider an application providing access to a + database containing medical information, and offering unrestricted + access to the service. A client of such a service might wish to + authenticate the service (in order to establish trust in any information + retrieved from it), but might not wish the service to be able to obtain + the client's identity (perhaps due to privacy concerns about the + specific inquiries, or perhaps simply to avoid being placed on mailing- + lists). + + In normal use of the GSS-API, the initiator's identity is made available + to the acceptor as a result of the context establishment process. + However, context initiators may request that their identity not be + revealed to the context acceptor. Many mechanisms do not support + anonymous authentication, and for such mechanisms the request will not + be honored. An authentication token will be still be generated, but the + application is always informed if a requested service is unavailable, + and has the option to abort context establishment if anonymity is valued + above the other security services that would require a context to be + established. + + In addition to informing the application that a context is established + anonymously (via the ret_flags outputs from gss_init_sec_context and + gss_accept_sec_context), the optional src_name output from + + + + Wray Document Expiration: 1 September 1997 [Page 22] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_accept_sec_context and gss_inquire_context will, for such contexts, + return a reserved internal-form name, defined by the implementation. + When presented to gss_display_name, this reserved internal-form name + will result in a printable name that is syntactically distinguishable + from any valid principal name supported by the implementation, + associated with a name-type object identifier with the value + GSS_C_NT_ANONYMOUS, whose value us given in Appendix A. The printable + form of an anonymous name should be chosen such that it implies + anonymity, since this name may appear in, for example, audit logs. For + example, the string "" might be a good choice, if no valid + printable names supported by the implementation can begin with "<" and + end with ">". + + 6.5. Confidentiality + + If a context supports the confidentiality service, gss_wrap may be used + to encrypt application messages. Messages are selectively encrypted, + under the control of the conf_req_flag input parameter to gss_wrap. + + 6.6. Inter-process context transfer + + GSSAPI V2 provides routines (gss_export_sec_context and + gss_import_sec_context) which allow a security context to be transferred + between processes on a single machine. The most common use for such a + feature is a client-server design where the server is implemented as a + single process that accepts incoming security contexts, which then + launches child processes to deal with the data on these contexts. In + such a design, the child processes must have access to the security + context data structure created within the parent by its call to + gss_accept_sec_context so that they can use per-message protection + services and delete the security context when the communication session + ends. + + Since the security context data structure is expected to contain + sequencing information, it is impractical in general to share a context + between processes. Thus GSSAPI provides a call (gss_export_sec_context) + that the process which currently owns the context can call to declare + that it has no intention to use the context subsequently, and to create + an inter-process token containing information needed by the adopting + process to successfully import the context. After successful completion + of this call, the original security context is made inaccessible to the + calling process by GSSAPI, and any context handles referring to this + context are no longer valid. The originating process transfers the + inter-process token to the adopting process, which passes it to + gss_import_sec_context, and a fresh gss_ctx_id_t is created such that it + is functionally identical to the original context. + + The inter-process token may contain sensitive data from the original + security context (including cryptographic keys). Applications using + inter-process tokens to transfer security contexts must take appropriate + steps to protect these tokens in transit. + + + + Wray Document Expiration: 1 September 1997 [Page 23] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Implementations are not required to support the inter-process transfer + of security contexts. The ability to transfer a security context is + indicated when the context is created, by gss_init_sec_context or + gss_accept_sec_context setting the GSS_C_TRANS_FLAG bit in their + ret_flags parameter. + + + 6.7. The use of incomplete contexts + + Some mechanisms may allow the per-message services to be used before the + context establishment process is complete. For example, a mechanism may + include sufficient information in its initial context-level token for + the context acceptor to immediately decode messages protected with + gss_wrap or gss_get_mic. For such a mechanism, the initiating + application need not wait until subsequent context-level tokens have + been sent and received before invoking the per-message protection + services. + + The ability of a context to provide per-message services in advance of + complete context establishment is indicated by the setting of the + GSS_C_PROT_READY_FLAG bit in the ret_flags parameter from + gss_init_sec_context and gss_accept_sec_context. Applications wishing + to use per-message protection services on partially-established contexts + should check this flag before attempting to invoke gss_wrap or + gss_get_mic. + + + + 7. GSS-API routine descriptions + + In addition to the explicit major status codes documented here, the code + GSS_S_FAILURE may be returned by any routine, indicating an + implementation-specific or mechanism-specific error condition, further + details of which are reported via the minor_status parameter. + + + + + + + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 24] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.1. gss_accept_sec_context + + OM_uint32 gss_accept_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + const gss_cred_id_t acceptor_cred_handle, + const gss_buffer_t input_token_buffer, + const gss_channel_bindings_t + input_chan_bindings, + const gss_name_t * src_name, + gss_OID * mech_type, + gss_buffer_t output_token, + OM_uint32 * ret_flags, + OM_uint32 * time_rec, + gss_cred_id_t * delegated_cred_handle) + + Purpose: + + Allows a remotely initiated security context between the application and + a remote peer to be established. The routine may return a output_token + which should be transferred to the peer application, where the peer + application will present it to gss_init_sec_context. If no token need + be sent, gss_accept_sec_context will indicate this by setting the length + field of the output_token argument to zero. To complete the context + establishment, one or more reply tokens may be required from the peer + application; if so, gss_accept_sec_context will return a status flag of + GSS_S_CONTINUE_NEEDED, in which case it should be called again when the + reply token is received from the peer application, passing the token to + gss_accept_sec_context via the input_token parameters. + + Portable applications should be constructed to use the token length and + return status to determine whether a token needs to be sent or waited + for. Thus a typical portable caller should always invoke + gss_accept_sec_context within a loop: + + gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; + ... + + do { + receive_token_from_peer(input_token); + maj_stat = gss_accept_sec_context(&min_stat, + &context_hdl, + cred_hdl, + input_token, + input_bindings, + &client_name, + &mech_type, + output_token, + &ret_flags, + &time_rec, + &deleg_cred); + + + + Wray Document Expiration: 1 September 1997 [Page 25] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + if (GSS_ERROR(maj_stat)) { + report_error(maj_stat, min_stat); + }; + if (output_token->length != 0) { + send_token_to_peer(output_token); + gss_release_buffer(&min_stat, + output_token) + }; + if (GSS_ERROR(maj_stat)) { + if (context_hdl != GSS_C_NO_CONTEXT) + gss_delete_sec_context(&min_stat, + &context_hdl, + GSS_C_NO_BUFFER); + break; + }; + } while (maj_stat & GSS_S_CONTINUE_NEEDED); + + + Whenever the routine returns a major status that includes the value + GSS_S_CONTINUE_NEEDED, the context is not fully established and the + following restrictions apply to the output parameters: + + (a) The value returned via the time_rec parameter is undefined + + (b) Unless the accompanying ret_flags parameter contains the bit + GSS_C_PROT_READY_FLAG, indicating that per-message services may be + applied in advance of a successful completion status, the value + returned via the mech_type parameter may be undefined until the + routine returns a major status value of GSS_S_COMPLETE. + + (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, + GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, + GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the + ret_flags parameter should contain the values that the + implementation expects would be valid if context establishment + were to succeed. + + The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits + within ret_flags should indicate the actual state at the time + gss_accept_sec_context returns, whether or not the context is + fully established. + + Although this requires that GSSAPI implementations set the + GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller + (i.e. when accompanied by a GSS_S_COMPLETE status code), + applications should not rely on this behavior as the flag was not + defined in Version 1 of the GSSAPI. Instead, applications should + be prepared to use per-message services after a successful context + establishment, according to the GSS_C_INTEG_FLAG and + GSS_C_CONF_FLAG values. + + + + + Wray Document Expiration: 1 September 1997 [Page 26] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + All other bits within the ret_flags argument should be set to + zero. + + + While the routine returns GSS_S_CONTINUE_NEEDED, the values returned via + the ret_flags argument indicate the services that the implementation + expects to be available from the established context. + + If the initial call of gss_accept_sec_context() fails, the + implementation should not create a context object, and should leave the + value of the context_handle parameter set to GSS_C_NO_CONTEXT to + indicate this. In the event of a failure on a subsequent call, the + implementation is permitted to delete the "half-built" security context + (in which case it should set the context_handle parameter to + GSS_C_NO_CONTEXT), but the preferred behavior is to leave the security + context (and the context_handle parameter) untouched for the application + to delete (using gss_delete_sec_context). + + Parameters: + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned in subsequent calls. Once + gss_accept_sec_context() has returned a value + via this parameter, resources have been assigned + to the corresponding context, and must be + freed by the application after use with a call + to gss_delete_sec_context(). + + + acceptor_cred_handle gss_cred_id_t, read + Credential handle claimed by context acceptor. + Specify GSS_C_NO_CREDENTIAL to accept the + context as a default principal. If + GSS_C_NO_CREDENTIAL is specified, but no + default acceptor principal is defined, + GSS_S_NO_CRED will be returned. + + input_token_buffer buffer, opaque, read + token obtained from remote application. + + input_chan_bindings channel bindings, read, optional + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. If channel bindings are not + used, specify GSS_C_NO_CHANNEL_BINDINGS. + + src_name gss_name_t, modify, optional + Authenticated name of context initiator. + + + + Wray Document Expiration: 1 September 1997 [Page 27] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + After use, this name should be deallocated by + passing it to gss_release_name(). If not + required, specify NULL. + + mech_type Object ID, modify, optional + Security mechanism used. The returned + OID value will be a pointer into static + storage, and should be treated as read-only + by the caller (in particular, it does not + need to be freed). If not required, specify + NULL. + + output_token buffer, opaque, modify + Token to be passed to peer application. If the + length field of the returned token buffer is 0, + then no token need be passed to the peer + application. If a non-zero length field is + returned, the associated storage must be freed + after use by the application with a call to + gss_release_buffer(). + + ret_flags bit-mask, modify, optional + Contains various independent flags, each of + which indicates that the context supports a + specific service option. If not needed, + specify NULL. Symbolic names are + provided for each flag, and the symbolic names + corresponding to the required flags + should be logically-ANDed with the ret_flags + value to test whether a given option is + supported by the context. The flags are: + GSS_C_DELEG_FLAG + True - Delegated credentials are available + via the delegated_cred_handle + parameter + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer asked for mutual + authentication + False - Remote peer did not ask for mutual + authentication + GSS_C_REPLAY_FLAG + True - replay of protected messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence protected + messages will be detected + False - out-of-sequence messages will not + be detected + + + + Wray Document Expiration: 1 September 1997 [Page 28] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_C_CONF_FLAG + True - Confidentiality service may be invoked + by calling the gss_wrap routine + False - No confidentiality service (via + gss_wrap) available. gss_wrap will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_get_mic or gss_wrap + routines. + False - Per-message integrity service + unavailable. + GSS_C_ANON_FLAG + True - The initiator does not wish to + be authenticated; the src_name + parameter (if requested) contains + an anonymous internal name. + False - The initiator has been + authenticated normally. + GSS_C_PROT_READY_FLAG + True - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + if the accompanying major status return + value is either GSS_S_COMPLETE or + GSS_S_CONTINUE_NEEDED. + False - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + only if the accompanying major status + return value is GSS_S_COMPLETE. + GSS_C_TRANS_FLAG + True - The resultant security context may + be transferred to other processes via + a call to gss_export_sec_context(). + False - The security context is not + transferrable. + All other bits should be set to zero. + + time_rec Integer, modify, optional + number of seconds for which the context + will remain valid. Specify NULL if not required. + + delegated_cred_handle + gss_cred_id_t, modify, optional + credential handle for credentials received from + context initiator. Only valid if deleg_flag in + ret_flags is true, in which case an explicit + + + + Wray Document Expiration: 1 September 1997 [Page 29] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + credential handle (i.e. not GSS_C_NO_CREDENTIAL) + will be returned; if deleg_flag is false, + gss_accept_context() will set this parameter to + GSS_C_NO_CREDENTIAL. If a credential handle is + returned, the associated resources must be released + by the application after use with a call to + gss_release_cred(). Specify NULL if not required. + + + minor_status Integer, modify + Mechanism specific status code. + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application + is required to complete the context, and that + gss_accept_sec_context must be called again with that + token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the + input_token failed. + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed + on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for context + acceptance, or the credential handle did not reference + any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. + + GSS_S_BAD_BINDINGS The input_token contains different channel bindings + to those specified via the input_chan_bindings + parameter. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did not + refer to a valid context. + + GSS_S_BAD_SIG The input_token contains an invalid MIC. + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error + during context establishment. + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a + token already processed. This is a fatal error during + context establishment. + + + + + + Wray Document Expiration: 1 September 1997 [Page 30] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_BAD_MECH The received token specified a mechanism that is not + supported by the implementation or the provided + credential. + + + + + + + + 7.2. gss_acquire_cred + + + OM_uint32 gss_acquire_cred ( + OM_uint32 * minor_status, + const gss_name_t desired_name, + OM_uint32 time_req, + const gss_OID_set desired_mechs, + gss_cred_usage_t cred_usage, + gss_cred_id_t * output_cred_handle, + gss_OID_set * actual_mechs, + OM_uint32 * time_rec) + + Purpose: + + Allows an application to acquire a handle for a pre-existing credential + by name. GSS-API implementations must impose a local access-control + policy on callers of this routine to prevent unauthorized callers from + acquiring credentials to which they are not entitled. This routine is + not intended to provide a ``login to the network'' function, as such a + function would involve the creation of new credentials rather than + merely acquiring a handle to existing credentials. Such functions, if + required, should be defined in implementation-specific extensions to the + API. + + If desired_name is GSS_C_NO_NAME, the call is interpreted as a request + for a credential handle that will invoke default behavior when passed to + gss_init_sec_context() (if cred_usage is GSS_C_INITIATE or GSS_C_BOTH) + or gss_accept_sec_context() (if cred_usage is GSS_C_ACCEPT or + GSS_C_BOTH). + + This routine is expected to be used primarily by context acceptors, + since implementations are likely to provide mechanism-specific ways of + obtaining GSS-API initiator credentials from the system login process. + Some implementations may therefore not support the acquisition of + GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred for any + name other than an empty name. + + If credential acquisition is time-consuming for a mechanism, the + mechanism may chooses to delay the actual acquisition until the + credential is required (e.g. by gss_init_sec_context or + + + + Wray Document Expiration: 1 September 1997 [Page 31] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_accept_sec_context). Such mechanism-specific implementation + decisions should be invisible to the calling application; thus a call of + gss_inquire_cred immediately following the call of gss_acquire_cred must + return valid credential data, and may therefore incur the overhead of a + deferred credential acquisition. + + Parameters: + + desired_name gss_name_t, read + Name of principal whose credential + should be acquired + + time_req Integer, read, optional + number of seconds that credentials + should remain valid. Specify GSS_C_INDEFINITE + to request that the credentials have the maximum + permitted lifetime. + + desired_mechs Set of Object IDs, read, optional + set of underlying security mechanisms that + may be used. GSS_C_NO_OID_SET may be used + to obtain an implementation-specific default. + + cred_usage gss_cred_usage_t, read + GSS_C_BOTH - Credentials may be used + either to initiate or accept + security contexts. + GSS_C_INITIATE - Credentials will only be + used to initiate security + contexts. + GSS_C_ACCEPT - Credentials will only be used to + accept security contexts. + + output_cred_handle gss_cred_id_t, modify + The returned credential handle. Resources + associated with this credential handle must + be released by the application after use + with a call to gss_release_cred(). + + actual_mechs Set of Object IDs, modify, optional + The set of mechanisms for which the + credential is valid. Storage associated + with the returned OID-set must be released by + the application after use with a call to + gss_release_oid_set(). Specify NULL if not + required. + + time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid. If the + implementation does not support expiration of + + + + Wray Document Expiration: 1 September 1997 [Page 32] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + credentials, the value GSS_C_INDEFINITE will + be returned. Specify NULL if not required + + minor_status Integer, modify + Mechanism specific status code. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Unavailable mechanism requested + + GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not + supported + + GSS_S_BAD_NAME Value supplied for desired_name parameter is ill- + formed. + + GSS_S_CREDENTIALS_EXPIRED The credentials could not be acquired because + they have expired. + + GSS_S_NO_CRED No credentials were found for the specified name. + + + + + + + + 7.3. gss_add_cred + + + OM_uint32 gss_add_cred ( + OM_uint32 * minor_status, + const gss_cred_id_t input_cred_handle, + const gss_name_t desired_name, + const gss_OID desired_mech, + gss_cred_usage_t cred_usage, + OM_uint32 initiator_time_req, + OM_uint32 acceptor_time_req, + gss_cred_id_t * output_cred_handle, + gss_OID_set * actual_mechs, + OM_uint32 * initiator_time_rec, + OM_uint32 * acceptor_time_rec) + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 33] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Purpose: + + Adds a credential-element to a credential. The credential-element is + identified by the name of the principal to which it refers. GSSAPI + implementations must impose a local access-control policy on callers of + this routine to prevent unauthorized callers from acquiring credential- + elements to which they are not entitled. This routine is not intended to + provide a ``login to the network'' function, as such a function would + involve the creation of new mechanism-specific authentication data, + rather than merely acquiring a GSSAPI handle to existing data. Such + functions, if required, should be defined in implementation-specific + extensions to the API. + + This routine is expected to be used primarily by context acceptors, + since implementations are likely to provide mechanism-specific ways of + obtaining GSS-API initiator credentials from the system login process. + Some implementations may therefore not support the acquisition of + GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred. + + If credential acquisition is time-consuming for a mechanism, the + mechanism may chooses to delay the actual acquisition until the + credential is required (e.g. by gss_init_sec_context or + gss_accept_sec_context). Such mechanism-specific implementation + decisions should be invisible to the calling application; thus a call of + gss_inquire_cred immediately following the call of gss_acquire_cred must + return valid credential data, and may therefore incur the overhead of a + deferred credential acquisition. + + This routine can be used to either create a new credential containing + all credential-elements of the original in addition to the newly-acquire + credential-element, or to add the new credential-element to an existing + credential. If NULL is specified for the output_cred_handle parameter + argument, the new credential-element will be added to the credential + identified by input_cred_handle; if a valid pointer is specified for the + output_cred_handle parameter, a new credential and handle will be + created. + + If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, the + gss_add_cred will create its output_cred_handle based on default + behavior. That is, the call will have the same effect as if the + application had first made a call to gss_acquire_cred(), specifying the + same usage and passing GSS_C_NO_NAME as the desired_name parameter to + obtain an explicit credential handle embodying default behavior, passed + this credential handle to gss_add_cred(), and finally called + gss_release_cred() on the first credential handle. + + If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle parameter, + a non-NULL output_cred_handle must be supplied. + + Parameters: + + + + + Wray Document Expiration: 1 September 1997 [Page 34] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + minor_status Integer, modify + Mechanism specific status code. + + input_cred_handle gss_cred_id_t, read, optional + The credential to which a credential-element + will be added. If GSS_C_NO_CREDENTIAL is + specified, the routine will create the new + credential based on default behavior (see + description above). Note that, while the + credential-handle is not modified by + gss_add_cred(), the underlying credential + will be modified if output_credential_handle + is NULL. + + desired_name gss_name_t, read. + Name of principal whose credential + should be acquired. + + desired_mech Object ID, read + Underlying security mechanism with which the + credential may be used. + + cred_usage gss_cred_usage_t, read + GSS_C_BOTH - Credential may be used + either to initiate or accept + security contexts. + GSS_C_INITIATE - Credential will only be + used to initiate security + contexts. + GSS_C_ACCEPT - Credential will only be used to + accept security contexts. + + initiator_time_req Integer, read, optional + number of seconds that the credential + should remain valid for initiating security + contexts. This argument is ignored if the + created credentials are of type GSS_C_ACCEPT. + Specify GSS_C_INDEFINITE to request that the + credentials have the maximum permitted initiator + lifetime. + + acceptor_time_req Integer, read, optional + number of seconds that the credential + should remain valid for accepting security + contexts. This argument is ignored if the + created credentials are of type GSS_C_INITIATE. + Specify GSS_C_INDEFINITE to request that the + credentials have the maximum permitted initiator + lifetime. + + + + + Wray Document Expiration: 1 September 1997 [Page 35] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + output_cred_handle gss_cred_id_t, modify, optional + The returned credential handle, containing + the new credential-element and all the + credential-elements from input_cred_handle. + If a valid pointer to a gss_cred_id_t is + supplied for this parameter, gss_add_cred + creates a new credential handle containing all + credential-elements from the input_cred_handle + and the newly acquired credential-element; if + NULL is specified for this parameter, the newly + acquired credential-element will be added + to the credential identified by input_cred_handle. + The resources associated with any credential + handle returned via this parameter must be + released by the application after use with a + call to gss_release_cred(). + + actual_mechs Set of Object IDs, modify, optional + The complete set of mechanisms for which + the new credential is valid. Storage for + the returned OID-set must be freed by the + application after use with a call to + gss_release_oid_set(). Specify NULL if + not required. + + initiator_time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid for + initiating contexts using the specified + mechanism. If the implementation or mechanism + does not support expiration of credentials, the + value GSS_C_INDEFINITE will be returned. Specify + NULL if not required + + acceptor_time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid for + accepting security contexts using the specified + mechanism. If the implementation or mechanism + does not support expiration of credentials, the + value GSS_C_INDEFINITE will be returned. Specify + NULL if not required + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Unavailable mechanism requested + + GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not + supported + + + + + Wray Document Expiration: 1 September 1997 [Page 36] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_BAD_NAME Value supplied for desired_name parameter is ill- + formed. + + GSS_S_DUPLICATE_ELEMENT The credential already contains an element for + the requested mechanism with overlapping usage and + validity period. + + GSS_S_CREDENTIALS_EXPIRED The required credentials could not be added + because they have expired. + + GSS_S_NO_CRED No credentials were found for the specified name. + + + + + + + + 7.4. gss_add_oid_set_member + + OM_uint32 gss_add_oid_set_member ( + OM_uint32 * minor_status, + const gss_OID member_oid, + gss_OID_set * oid_set) + + Purpose: + + Add an Object Identifier to an Object Identifier set. This routine is + intended for use in conjunction with gss_create_empty_oid_set when + constructing a set of mechanism OIDs for input to gss_acquire_cred. + + The oid_set parameter must refer to an OID-set that was created by + GSSAPI (e.g. a set returned by gss_create_empty_oid_set()). GSSAPI + creates a copy of the member_oid and inserts this copy into the set, + expanding the storage allocated to the OID-set's elements array if + necessary. The routine may add the new member OID anywhere within the + elements array, and implementations should verify that the new + member_oid is not already contained within the elements array. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + member_oid Object ID, read + The object identifier to copied into + the set. + + oid_set Set of Object ID, modify + The set in which the object identifier + should be inserted. + + + + Wray Document Expiration: 1 September 1997 [Page 37] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.5. gss_canonicalize_name + + OM_uint32 gss_canonicalize_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + const gss_OID mech_type, + gss_name_t * output_name) + + Purpose: + + Generate a canonical mechanism name (MN) from an arbitrary internal + name. The mechanism name is the name that would be returned to a + context acceptor on successful authentication of a context where the + initiator used the input_name in a successful call to gss_acquire_cred, + specifying an OID set containing as its only member, + followed by a call to gss_init_sec_context, specifying as + the authentication mechanism. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + input_name gss_name_t, read + The name for which a canonical form is + desired + + mech_type Object ID, read + The authentication mechanism for which the + canonical form of the name is desired. The + desired mechanism must be specified explicitly; + no default is provided. + + output_name gss_name_t, modify + The resultant canonical name. Storage + associated with this name must be freed by + the application after use with a call to + gss_release_name(). + + Function value: GSS status code + + + + + Wray Document Expiration: 1 September 1997 [Page 38] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_COMPLETE Successful completion. + + GSS_S_BAD_MECH The identified mechanism is not supported. + + GSS_S_BAD_NAMETYPE The provided internal name contains no elements that + could be processed by the sepcified mechanism. + + GSS_S_BAD_NAME The provided internal name was ill-formed. + + + + + + + + 7.6. gss_compare_name + + OM_uint32 gss_compare_name ( + OM_uint32 * minor_status, + const gss_name_t name1, + const gss_name_t name2, + int * name_equal) + + Purpose: + + Allows an application to compare two internal-form names to determine + whether they refer to the same entity. + + If either name presented to gss_compare_name denotes an anonymous + principal, the routines should indicate that the two names do not refer + to the same identity. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + name1 gss_name_t, read + internal-form name + + name2 gss_name_t, read + internal-form name + + name_equal boolean, modify + non-zero - names refer to same entity + zero - names refer to different entities + (strictly, the names are not known + to refer to the same identity). + + Function value: GSS status code + + + + + Wray Document Expiration: 1 September 1997 [Page 39] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The two names were of incomparable types. + + GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed + + + + + + + + 7.7. gss_context_time + + OM_uint32 gss_context_time ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + OM_uint32 * time_rec) + + Purpose: + + Determines the number of seconds for which the specified context will + remain valid. + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context to be interrogated. + + time_rec Integer, modify + Number of seconds that the context will remain + valid. If the context has already expired, + zero will be returned. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 40] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.8. gss_create_empty_oid_set + + OM_uint32 gss_create_empty_oid_set ( + OM_uint32 * minor_status, + gss_OID_set * oid_set) + + Purpose: + + Create an object-identifier set containing no object identifiers, to + which members may be subsequently added using the + gss_add_oid_set_member() routine. These routines are intended to be + used to construct sets of mechanism object identifiers, for input to + gss_acquire_cred. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + oid_set Set of Object IDs, modify + The empty object identifier set. + The routine will allocate the + gss_OID_set_desc object, which the + application must free after use with + a call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.9. gss_delete_sec_context + + OM_uint32 gss_delete_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_buffer_t output_token) + + Purpose: + + Delete a security context. gss_delete_sec_context will delete the local + data structures associated with the specified security context, and may + generate an output_token, which when passed to the peer + gss_process_context_token will instruct it to do likewise. If no token + is required by the mechanism, the GSS-API should set the length field of + the output_token (if provided) to zero. No further security services + + + + Wray Document Expiration: 1 September 1997 [Page 41] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + may be obtained using the context specified by context_handle. + + In addition to deleting established security contexts, + gss_delete_sec_context must also be able to delete "half-built" security + contexts resulting from an incomplete sequence of + gss_init_sec_context()/gss_accept_sec_context() calls. + + The output_token parameter is retained for compatibility with version 1 + of the GSS-API. It is recommended that both peer applications invoke + gss_delete_sec_context passing the value GSS_C_NO_BUFFER for the + output_token parameter, indicating that no token is required, and that + gss_delete_sec_context should simply delete local context data + structures. If the application does pass a valid buffer to + gss_delete_sec_context, mechanisms are encouraged to return a zero- + length token, indicating that no peer action is necessary, and that no + token should be transferred by the application. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, modify + context handle identifying context to delete. + After deleting the context, the GSSAPI will set + this context handle to GSS_C_NO_CONTEXT. + + output_token buffer, opaque, modify, optional + token to be sent to remote application to + instruct it to also delete the context. It + is recommended that applications specify + GSS_C_NO_BUFFER for this parameter, requesting + local deletion only. If a buffer parameter is + provided by the application, the mechanism may + return a token in it; mechanisms that implement + only local deletion should set the length field of + this token to zero to indicate to the application + that no token is to be sent to the peer. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CONTEXT No valid context was supplied + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 42] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.10. gss_display_name + + OM_uint32 gss_display_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + gss_buffer_t output_name_buffer, + gss_OID * output_name_type) + + Purpose: + + Allows an application to obtain a textual representation of an opaque + internal-form name for display purposes. The syntax of a printable + name is defined by the GSS-API implementation. + + If input_name denotes an anonymous principal, the implementation should + return the gss_OID value GSS_C_NT_ANONYMOUS as the output_name_type, and + a textual name that is syntactically distinct from all valid supported + printable names in output_name_buffer. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + input_name gss_name_t, read + name to be displayed + + output_name_buffer buffer, character-string, modify + buffer to receive textual name string. + The application must free storage associated + with this name after use with a call to + gss_release_buffer(). + + output_name_type Object ID, modify, optional + The type of the returned name. The returned + gss_OID will be a pointer into static storage, + and should be treated as read-only by the caller + (in particular, it does not need to be freed). + Specify NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME input_name was ill-formed + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 43] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.11. gss_display_status + + OM_uint32 gss_display_status ( + OM_uint32 * minor_status, + OM_uint32 status_value, + int status_type, + const gss_OID mech_type, + OM_uint32 * message_context, + gss_buffer_t status_string) + + Purpose: + + Allows an application to obtain a textual representation of a GSS-API + status code, for display to the user or for logging purposes. Since + some status values may indicate multiple conditions, applications may + need to call gss_display_status multiple times, each call generating a + single text string. The message_context parameter is used by + gss_acquire_cred to store state information about which error messages + have already been extracted from a given status_value; message_context + must be initialized to 0 by the application prior to the first call, and + gss_display_status will return a non-zero value in this parameter if + there are further messages to extract. The message_context parameter + contains all state information required by gss_display_status in order + to extract further messages from the status_value; even when a non-zero + value is returned in this parameter, the application is not required to + call gss_display_status again unless subsequent messages are desired. + The following code extracts all messages from a given status code and + prints them to stderr: + + + OM_uint32 message_context; + OM_uint32 status_code; + OM_uint32 maj_status; + OM_uint32 min_status; + gss_buffer_desc status_string; + + ... + + message_context = 0; + + do { + + maj_status = gss_display_status (&min_status, + status_code, + GSS_C_GSS_CODE, + GSS_C_NO_OID, + &message_context, + &status_string) + + fprintf(stderr, + "%.*s\n", + + + + Wray Document Expiration: 1 September 1997 [Page 44] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + status_string.length, + status_string.value); + + gss_release_buffer(&min_status, + &status_string); + + } while (message_context != 0); + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + status_value Integer, read + Status value to be converted + + status_type Integer, read + GSS_C_GSS_CODE - status_value is a GSS status + code + GSS_C_MECH_CODE - status_value is a mechanism + status code + + mech_type Object ID, read, optional + Underlying mechanism (used to interpret a + minor status value) Supply GSS_C_NO_OID to + obtain the system default. + + message_context Integer, read/modify + Should be initialized to zero by the + application prior to the first call. + On return from gss_display_status(), + a non-zero status_value parameter indicates + that additional messages may be extracted + from the status code via subsequent calls + to gss_display_status(), passing the same + status_value, status_type, mech_type, and + message_context parameters. + + status_string buffer, character string, modify + textual interpretation of the status_value. + Storage associated with this parameter must + be freed by the application after use with + a call to gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + Wray Document Expiration: 1 September 1997 [Page 45] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_BAD_MECH Indicates that translation in accordance with an + unsupported mechanism type was requested + + GSS_S_BAD_STATUS The status value was not recognized, or the status + type was neither GSS_C_GSS_CODE nor GSS_C_MECH_CODE. + + + + + + + + 7.12. gss_duplicate_name + + OM_uint32 gss_duplicate_name ( + OM_uint32 * minor_status, + const gss_name_t src_name, + gss_name_t * dest_name) + + Purpose: + + Create an exact duplicate of the existing internal name src_name. The + new dest_name will be independent of src_name (i.e. src_name and + dest_name must both be released, and the release of one shall not affect + the validity of the other). + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + src_name gss_name_t, read + internal name to be duplicated. + + dest_name gss_name_t, modify + The resultant copy of . + Storage associated with this name must + be freed by the application after use + with a call to gss_release_name(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The src_name parameter was ill-formed. + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 46] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.13. gss_export_name + + OM_uint32 gss_export_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + gss_buffer_t exported_name) + + Purpose: + + To produce a canonical contiguous string representation of a mechanism + name (MN), suitable for direct comparison (e.g. with memcmp) for use in + authorization functions (e.g. matching entries in an access-control + list). + + The parameter must specify a valid MN (i.e. an internal + name generated by gss_accept_sec_context or by gss_canonicalize_name). + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + input_name gss_name_t, read + The MN to be exported + + exported_name gss_buffer_t, octet-string, modify + The canonical contiguous string form of + . Storage associated with + this string must freed by the application + after use with gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NAME_NOT_MN The provided internal name was not a mechanism name. + + GSS_S_BAD_NAME The provide internal name was ill-formed. + + GSS_S_BAD_NAMETYPE The internal name was of a type not supported by the + GSSAPI implementation. + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 47] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.14. gss_export_sec_context + + OM_uint32 gss_export_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_buffer_t interprocess_token) + + Purpose: + + Provided to support the sharing of work between multiple processes. + This routine will typically be used by the context-acceptor, in an + application where a single process receives incoming connection requests + and accepts security contexts over them, then passes the established + context to one or more other processes for message exchange. + gss_export_sec_context() deactivates the security context for the + calling process and creates an interprocess token which, when passed to + gss_import_sec_context in another process, will re-activate the context + in the second process. Only a single instantiation of a given context + may be active at any one time; a subsequent attempt by a context + exporter to access the exported security context will fail. + + The implementation may constrain the set of processes by which the + interprocess token may be imported, either as a function of local + security policy, or as a result of implementation decisions. For + example, some implementations may constrain contexts to be passed only + between processes that run under the same account, or which are part of + the same process group. + + The interprocess token may contain security-sensitive information (for + example cryptographic keys). While mechanisms are encouraged to either + avoid placing such sensitive information within interprocess tokens, or + to encrypt the token before returning it to the application, in a + typical object-library GSSAPI implementation this may not be possible. + Thus the application must take care to protect the interprocess token, + and ensure that any process to which the token is transferred is + trustworthy. + + If creation of the interprocess token is succesful, the implementation + shall deallocate all process-wide resources associated with the security + context, and set the context_handle to GSS_C_NO_CONTEXT. In the event + of an error that makes it impossible to complete the export of the + security context, the implementation must not return an interprocess + token, and should strive to leave the security context referenced by the + context_handle parameter untouched. If this is impossible, it is + permissible for the implementation to delete the security context, + providing it also sets the context_handle parameter to GSS_C_NO_CONTEXT. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + + + Wray Document Expiration: 1 September 1997 [Page 48] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + context_handle gss_ctx_id_t, modify + context handle identifying the context to transfer. + + interprocess_token buffer, opaque, modify + token to be transferred to target process. + Storage associated with this token must be + freed by the application after use with a + call to gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has expired + + GSS_S_NO_CONTEXT The context was invalid + + GSS_S_UNAVAILABLE The operation is not supported. + + + + + + + + 7.15. gss_get_mic + + OM_uint32 gss_get_mic ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + gss_qop_t qop_req, + const gss_buffer_t message_buffer, + gss_buffer_t msg_token) + + Purpose: + + Generates a cryptographic MIC for the supplied message, and places the + MIC in a token for transfer to the peer application. The qop_req + parameter allows a choice between several cryptographic algorithms, if + supported by the chosen mechanism. + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + will be sent + + + + + Wray Document Expiration: 1 September 1997 [Page 49] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + qop_req gss_qop_t, read, optional + Specifies requested quality of protection. + Callers are encouraged, on portability grounds, + to accept the default quality of protection + offered by the chosen mechanism, which may be + requested by specifying GSS_C_QOP_DEFAULT for + this parameter. If an unsupported protection + strength is requested, gss_get_mic will return a + major_status of GSS_S_BAD_QOP. + + message_buffer buffer, opaque, read + message to be protected + + msg_token buffer, opaque, modify + buffer to receive token. The application must + free storage associated with this buffer after + use with a call to gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. + + + + + + + + 7.16. gss_import_name + + OM_uint32 gss_import_name ( + OM_uint32 * minor_status, + const gss_buffer_t input_name_buffer, + const gss_OID input_name_type, + gss_name_t * output_name) + + Purpose: + + Convert a contiguous string name to internal form. In general, the + internal name returned (via the parameter) will not be an + MN; the exception to this is if the indicates that the + contiguous string provided via the parameter is of + type GSS_C_NT_EXPORT_NAME, in which case the returned internal name will + be an MN for the mechanism that exported the name. + + + + + Wray Document Expiration: 1 September 1997 [Page 50] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + input_name_buffer buffer, octet-string, read + buffer containing contiguous string name to convert + + input_name_type Object ID, read, optional + Object ID specifying type of printable + name. Applications may specify either + GSS_C_NO_OID to use a mechanism-specific + default printable syntax, or an OID registered + by the GSS-API implementation to name a + specific namespace. + + output_name gss_name_t, modify + returned name in internal form. Storage + associated with this name must be freed + by the application after use with a call + to gss_release_name(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The input_name_type was unrecognized + + GSS_S_BAD_NAME The input_name parameter could not be interpreted as a + name of the specified type + + + + + + + + + 7.17. gss_import_sec_context + + OM_uint32 gss_import_sec_context ( + OM_uint32 * minor_status, + const gss_buffer_t interprocess_token, + gss_ctx_id_t * context_handle) + + Purpose: + + Allows a process to import a security context established by another + process. A given interprocess token may be imported only once. See + gss_export_sec_context. + + + + + Wray Document Expiration: 1 September 1997 [Page 51] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + interprocess_token buffer, opaque, modify + token received from exporting process + + context_handle gss_ctx_id_t, modify + context handle of newly reactivated context. + Resources associated with this context handle + must be released by the application after use + with a call to gss_delete_sec_context(). + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion. + + GSS_S_NO_CONTEXT The token did not contain a valid context reference. + + GSS_S_DEFECTIVE_TOKEN The token was invalid. + + GSS_S_UNAVAILABLE The operation is unavailable. + + GSS_S_UNAUTHORIZED Local policy prevents the import of this context by + the current process.. + + + + + + + + 7.18. gss_indicate_mechs + + OM_uint32 gss_indicate_mechs ( + OM_uint32 * minor_status, + gss_OID_set * mech_set) + + Purpose: + + Allows an application to determine which underlying security mechanisms + are available. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + + + + Wray Document Expiration: 1 September 1997 [Page 52] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + mech_set set of Object IDs, modify + set of implementation-supported mechanisms. + The returned gss_OID_set value will be a + dynamically-allocated OID set, that should + be released by the caller after use with a + call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.19. gss_init_sec_context + + OM_uint32 gss_init_sec_context ( + OM_uint32 * minor_status, + const gss_cred_id_t initiator_cred_handle, + gss_ctx_id_t * context_handle, + const gss_name_t target_name, + const gss_OID mech_type, + OM_uint32 req_flags, + OM_uint32 time_req, + const gss_channel_bindings_t + input_chan_bindings, + const gss_buffer_t input_token + gss_OID * actual_mech_type, + gss_buffer_t output_token, + OM_uint32 * ret_flags, + OM_uint32 * time_rec ) + + Purpose: + + Initiates the establishment of a security context between the + application and a remote peer. Initially, the input_token parameter + should be specified either as GSS_C_NO_BUFFER, or as a pointer to a + gss_buffer_desc object whose length field contains the value zero. The + routine may return a output_token which should be transferred to the + peer application, where the peer application will present it to + gss_accept_sec_context. If no token need be sent, gss_init_sec_context + will indicate this by setting the length field of the output_token + argument to zero. To complete the context establishment, one or more + reply tokens may be required from the peer application; if so, + gss_init_sec_context will return a status containing the supplementary + information bit GSS_S_CONTINUE_NEEDED. In this case, + gss_init_sec_context should be called again when the reply token is + received from the peer application, passing the reply token to + gss_init_sec_context via the input_token parameters. + + + + Wray Document Expiration: 1 September 1997 [Page 53] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Portable applications should be constructed to use the token length and + return status to determine whether a token needs to be sent or waited + for. Thus a typical portable caller should always invoke + gss_init_sec_context within a loop: + + int context_established = 0; + gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; + ... + input_token->length = 0; + + while (!context_established) { + maj_stat = gss_init_sec_context(&min_stat, + cred_hdl, + &context_hdl, + target_name, + desired_mech, + desired_services, + desired_time, + input_bindings, + input_token, + &actual_mech, + output_token, + &actual_services, + &actual_time); + if (GSS_ERROR(maj_stat)) { + report_error(maj_stat, min_stat); + }; + if (output_token->length != 0) { + send_token_to_peer(output_token); + gss_release_buffer(&min_stat, + output_token) + }; + if (GSS_ERROR(maj_stat)) { + if (context_hdl != GSS_C_NO_CONTEXT) + gss_delete_sec_context(&min_stat, + &context_hdl, + GSS_C_NO_BUFFER); + break; + }; + if (maj_stat & GSS_S_CONTINUE_NEEDED) { + receive_token_from_peer(input_token); + } else { + context_established = 1; + }; + }; + + Whenever the routine returns a major status that includes the value + GSS_S_CONTINUE_NEEDED, the context is not fully established and the + following restrictions apply to the output parameters: + + + + + + Wray Document Expiration: 1 September 1997 [Page 54] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + (a) The value returned via the time_rec parameter is undefined + + (b) Unless the accompanying ret_flags parameter contains the bit + GSS_C_PROT_READY_FLAG, indicating that per-message services may be + applied in advance of a successful completion status, the value + returned via the actual_mech_type parameter is undefined until the + routine returns a major status value of GSS_S_COMPLETE. + + (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, + GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, + GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the + ret_flags parameter should contain the values that the + implementation expects would be valid if context establishment + were to succeed. In particular, if the application has requested + a service such as delegation or anonymous authentication via the + req_flags argument, and such a service is unavailable from the + underlying mechanism, gss_init_sec_context should generate a token + that will not provide the service, and indicate via the ret_flags + argument that the service will not be supported. The application + may choose to abort the context establishment by calling + gss_delete_sec_context (if it cannot continue in the absence of + the service), or it may choose to transmit the token and continue + context establishment (if the service was merely desired but not + mandatory). + + The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits + within ret_flags should indicate the actual state at the time + gss_init_sec_context returns, whether or not the context is fully + established. + + Although this requires that GSSAPI implementations set the + GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller + (i.e. when accompanied by a GSS_S_COMPLETE status code), + applications should not rely on this behavior as the flag was not + defined in Version 1 of the GSSAPI. Instead, applications should + be prepared to use per-message services after a successful context + establishment, according to the GSS_C_INTEG_FLAG and + GSS_C_CONF_FLAG values. + + All other bits within the ret_flags argument should be set to + zero. + + If the initial call of gss_init_sec_context() fails, the implementation + should not create a context object, and should leave the value of the + context_handle parameter set to GSS_C_NO_CONTEXT to indicate this. In + the event of a failure on a subsequent call, the implementation is + permitted to delete the "half-built" security context (in which case it + should set the context_handle parameter to GSS_C_NO_CONTEXT), but the + preferred behavior is to leave the security context untouched for the + application to delete (using gss_delete_sec_context). + + + + + Wray Document Expiration: 1 September 1997 [Page 55] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + initiator_cred_handle gss_cred_id_t, read, optional + handle for credentials claimed. Supply + GSS_C_NO_CREDENTIAL to act as a default + initiator principal. If no default + initiator is defined, the function will + return GSS_S_NO_CRED. + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned by first call in continuation calls. + Resources associated with this context-handle + must be released by the application after use + with a call to gee_delete_sec_context(). + + target_name gss_name_t, read + Name of target + + mech_type OID, read, optional + Object ID of desired mechanism. Supply + GSS_C_NO_OID to obtain an implementation + specific default + + req_flags bit-mask, read + Contains various independent flags, each of + which requests that the context support a + specific service option. Symbolic + names are provided for each flag, and the + symbolic names corresponding to the required + flags should be logically-ORed + together to form the bit-mask value. The + flags are: + + GSS_C_DELEG_FLAG + True - Delegate credentials to remote peer + False - Don't delegate + GSS_C_MUTUAL_FLAG + True - Request that remote peer + authenticate itself + False - Authenticate self to remote peer + only + GSS_C_REPLAY_FLAG + True - Enable replay detection for + messages protected with gss_wrap + or gss_get_mic + False - Don't attempt to detect + replayed messages + + + Wray Document Expiration: 1 September 1997 [Page 56] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_C_SEQUENCE_FLAG + True - Enable detection of out-of-sequence + protected messages + False - Don't attempt to detect + out-of-sequence messages + GSS_C_ANON_FLAG + True - Do not reveal the initiator's + identity to the acceptor. + False - Authenticate normally. + + time_req Integer, read, optional + Desired number of seconds for which context + should remain valid. Supply 0 to request a + default validity period. + + input_chan_bindings channel bindings, read, optional + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. Specify GSS_C_NO_CHANNEL_BINDINGS + if channel bindings are not used. + + input_token buffer, opaque, read, optional (see text) + Token received from peer application. + Supply GSS_C_NO_BUFFER, or a pointer to + a buffer containing the value GSS_C_EMPTY_BUFFER + on initial call. + + actual_mech_type OID, modify, optional + Actual mechanism used. The OID returned via + this parameter will be a pointer to static + storage that should be treated as read-only; + In particular the application should not attempt + to free it. Specify NULL if not required. + + output_token buffer, opaque, modify + token to be sent to peer application. If + the length field of the returned buffer is + zero, no token need be sent to the peer + application. Storage associated with this + buffer must be freed by the application + after use with a call to gss_release_buffer(). + + ret_flags bit-mask, modify, optional + Contains various independent flags, each of which + indicates that the context supports a specific + service option. Specify NULL if not + required. Symbolic names are provided + for each flag, and the symbolic names + corresponding to the required flags should be + + + + Wray Document Expiration: 1 September 1997 [Page 57] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + logically-ANDed with the ret_flags value to test + whether a given option is supported by the + context. The flags are: + + GSS_C_DELEG_FLAG + True - Credentials were delegated to + the remote peer + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer has been asked to + authenticated itself + False - Remote peer has not been asked to + authenticate itself + GSS_C_REPLAY_FLAG + True - replay of protected messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence protected + messages will be detected + False - out-of-sequence messages will + not be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be + invoked by calling gss_wrap routine + False - No confidentiality service (via + gss_wrap) available. gss_wrap will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_get_mic or gss_wrap + routines. + False - Per-message integrity service + unavailable. + GSS_C_ANON_FLAG + True - The initiator's identity has not been + revealed, and will not be revealed if + any emitted token is passed to the + acceptor. + False - The initiator's identity has been or + will be authenticated normally. + GSS_C_PROT_READY_FLAG + True - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available for + use if the accompanying major status + return value is either GSS_S_COMPLETE or + GSS_S_CONTINUE_NEEDED. + + + + Wray Document Expiration: 1 September 1997 [Page 58] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + False - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + only if the accompanying major status + return value is GSS_S_COMPLETE. + GSS_C_TRANS_FLAG + True - The resultant security context may + be transferred to other processes via + a call to gss_export_sec_context(). + False - The security context is not + transferrable. + All other bits should be set to zero. + + time_rec Integer, modify, optional + number of seconds for which the context + will remain valid. If the implementation does + not support context expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application + is required to complete the context, and that + gss_init_sec_context must be called again with that + token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the + input_token failed + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed + on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for context + initiation, or the credential handle did not reference + any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired + + GSS_S_BAD_BINDINGS The input_token contains different channel bindings + to those specified via the input_chan_bindings + parameter + + GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC that + could not be verified + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error + during context establishment + + + + + Wray Document Expiration: 1 September 1997 [Page 59] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a + token already processed. This is a fatal error during + context establishment. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did not + refer to a valid context + + GSS_S_BAD_NAMETYPE The provided target_name parameter contained an + invalid or unsupported type of name + + GSS_S_BAD_NAME The provided target_name parameter was ill-formed. + + GSS_S_BAD_MECH The specified mechanism is not supported by the + provided credential, or is unrecognized by the + implementation. + + + + + + + + 7.20. gss_inquire_context + + OM_uint32 gss_inquire_context ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + gss_name_t * src_name, + gss_name_t * targ_name, + OM_uint32 * lifetime_rec, + gss_OID * mech_type, + OM_uint32 * ctx_flags, + int * locally_initiated, + int * open ) + + Purpose: + + Obtains information about a security context. The caller must already + have obtained a handle that refers to the context, although the context + need not be fully established. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + context_handle gss_ctx_id_t, read + A handle that refers to the security context. + + src_name gss_name_t, modify, optional + The name of the context initiator. + + + + Wray Document Expiration: 1 September 1997 [Page 60] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + If the context was established using anonymous + authentication, and if the application invoking + gss_inquire_context is the context acceptor, + an anonymous name will be returned. Storage + associated with this name must be freed by the + application after use with a call to + gss_release_name(). Specify NULL if not + required. + + targ_name gss_name_t, modify, optional + The name of the context acceptor. + Storage associated with this name must be + freed by the application after use with a call + to gss_release_name(). Specify NULL if not + Specify NULL if not required. + + lifetime_rec Integer, modify, optional + The number of seconds for which the context + will remain valid. If the context has + expired, this parameter will be set to zero. + If the implementation does not support + context expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + mech_type gss_OID, modify, optional + The security mechanism providing the + context. The returned OID will be a + pointer to static storage that should + be treated as read-only by the application; + in particular the application should not + attempt to free it. Specify NULL if not + required. + + ctx_flags bit-mask, modify, optional + Contains various independent flags, each of + which indicates that the context supports + (or is expected to support, if ctx_open is + false) a specific service option. If not + needed, specify NULL. Symbolic names are + provided for each flag, and the symbolic names + corresponding to the required flags + should be logically-ANDed with the ret_flags + value to test whether a given option is + supported by the context. The flags are: + + GSS_C_DELEG_FLAG + True - Credentials were delegated from + the initiator to the acceptor. + False - No credentials were delegated + + + + Wray Document Expiration: 1 September 1997 [Page 61] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + GSS_C_MUTUAL_FLAG + True - The acceptor was authenticated + to the initiator + False - The acceptor did not authenticate + itself. + GSS_C_REPLAY_FLAG + True - replay of protected messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence protected + messages will be detected + False - out-of-sequence messages will not + be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be invoked + by calling gss_wrap routine + False - No confidentiality service (via + gss_wrap) available. gss_wrap will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_get_mic or gss_wrap + routines. + False - Per-message integrity service + unavailable. + GSS_C_ANON_FLAG + True - The initiator's identity will not + be revealed to the acceptor. + The src_name parameter (if + requested) contains an anonymous + internal name. + False - The initiator has been + authenticated normally. + GSS_C_PROT_READY_FLAG + True - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + for use. + False - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + only if the context is fully + established (i.e. if the open parameter + is non-zero). + GSS_C_TRANS_FLAG + True - The resultant security context may + be transferred to other processes via + a call to gss_export_sec_context(). + False - The security context is not + transferrable. + + Wray Document Expiration: 1 September 1997 [Page 62] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + + + locally_initiated Boolean, modify + Non-zero if the invoking application is the + context initiator. + Specify NULL if not required. + + open Boolean, modify + Non-zero if the context is fully established; + Zero if a context-establishment token + is expected from the peer application. + Specify NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CONTEXT The referenced context could not be accessed. + + GSS_S_CONTEXT_EXPIRED The context has expired. If the lifetime_rec + parameter was requested, it will be set to 0. + + + + + + + + 7.21. gss_inquire_cred + + OM_uint32 gss_inquire_cred ( + OM_uint32 * minor_status, + const gss_cred_id_t cred_handle, + gss_name_t * name, + OM_uint32 * lifetime, + gss_cred_usage_t * cred_usage, + gss_OID_set * mechanisms ) + + Purpose: + + Obtains information about a credential. The caller must already have + obtained a handle that refers to the credential. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + cred_handle gss_cred_id_t, read + A handle that refers to the target credential. + Specify GSS_C_NO_CREDENTIAL to inquire about + the default initiator principal. + + + Wray Document Expiration: 1 September 1997 [Page 63] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + + name gss_name_t, modify, optional + The name whose identity the credential asserts. + Storage associated with this name should be freed + by the application after use with a call to + gss_release_name(). Specify NULL if not required. + + lifetime Integer, modify, optional + The number of seconds for which the credential + will remain valid. If the credential has + expired, this parameter will be set to zero. + If the implementation does not support + credential expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + cred_usage gss_cred_usage_t, modify, optional + How the credential may be used. One of the + following: + GSS_C_INITIATE + GSS_C_ACCEPT + GSS_C_BOTH + Specify NULL if not required. + + mechanisms gss_OID_set, modify, optional + Set of mechanisms supported by the credential. + Storage associated with this OID set must be + freed by the application after use with a call + to gss_release_oid_set(). Specify NULL if not + required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED The referenced credentials could not be accessed. + + GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. If + the lifetime parameter was not passed as NULL, it will + be set to 0. + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 64] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.22. gss_inquire_cred_by_mech + + OM_uint32 gss_inquire_cred_by_mech ( + OM_uint32 * minor_status, + const gss_cred_id_t cred_handle, + const gss_OID mech_type, + gss_name_t * name, + OM_uint32 * initiator_lifetime, + OM_uint32 * acceptor_lifetime, + gss_cred_usage_t * cred_usage ) + + Purpose: + + Obtains per-mechanism information about a credential. The caller must + already have obtained a handle that refers to the credential. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + cred_handle gss_cred_id_t, read + A handle that refers to the target credential. + Specify GSS_C_NO_CREDENTIAL to inquire about + the default initiator principal. + + mech_type gss_OID, read + The mechanism for which information should be + returned. + + name gss_name_t, modify, optional + The name whose identity the credential asserts. + Storage associated with this name must be + freed by the application after use with a call + to gss_release_name(). Specify NULL if not + required. + + initiator_lifetime Integer, modify, optional + The number of seconds for which the credential + will remain capable of initiating security contexts + under the specified mechanism. If the credential + can no longer be used to initiate contexts, or if + the credential usage for this mechanism is + GSS_C_ACCEPT, + this parameter will be set to zero. If the + implementation does not support expiration of + initiator credentials, the value GSS_C_INDEFINITE + will be returned. Specify NULL if not required. + + acceptor_lifetime Integer, modify, optional + The number of seconds for which the credential + + + + Wray Document Expiration: 1 September 1997 [Page 65] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + will remain capable of accepting security contexts + under the specified mechanism. If the credential + can no longer be used to accept contexts, or if + the credential usage for this mechanism is + GSS_C_INITIATE, this parameter will be set to zero. + If the implementation does not support expiration + of acceptor credentials, the value GSS_C_INDEFINITE + will be returned. Specify NULL if not required. + + cred_usage gss_cred_usage_t, modify, optional + How the credential may be used with the specified + mechanism. One of the following: + GSS_C_INITIATE + GSS_C_ACCEPT + GSS_C_BOTH + Specify NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED The referenced credentials could not be accessed. + + GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. If + the lifetime parameter was not passed as NULL, it will + be set to 0. + + + + + + + + 7.23. gss_inquire_mechs_for_name + + OM_uint32 gss_inquire_mechs_for_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + gss_OID_set * mech_types ) + + Purpose: + + Returns the set of mechanisms supported by the GSSAPI implementation + that may be able to process the specified name. + + Each mechanism returned will recognize at least one element within the + name. It is permissible for this routine to be implemented within a + mechanism-independent GSSAPI layer, using the type information contained + within the presented name, and based on registration information + + + + Wray Document Expiration: 1 September 1997 [Page 66] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + provided by individual mechanism implementations. This means that the + returned mech_types set may indicate that a particular mechanism will + understand the name when in fact it would refuse to accept the name as + input to gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred + or gss_add_cred (due to some property of the specific name, as opposed + to the name type). Thus this routine should be used only as a pre- + filter for a call to a subsequent mechanism-specific routine. + + + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + input_name gss_name_t, read + The name to which the inquiry relates. + + mech_types gss_OID_set, modify + Set of mechanisms that may support the + specified name. The returned OID set + must be freed by the caller after use + with a call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The input_name parameter was ill-formed. + + GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or + unsupported type of name + + + + + + + 7.24. gss_inquire_names_for_mech + + OM_uint32 gss_inquire_names_for_mech ( + OM_uint32 * minor_status, + const gss_OID mechanism, + gss_OID_set * name_types) + + Purpose: + + Returns the set of nametypes supported by the specified mechanism. + + + + + + + Wray Document Expiration: 1 September 1997 [Page 67] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + mechanism gss_OID, read + The mechanism to be interrogated. + + name_types gss_OID_set, modify + Set of name-types supported by the specified + mechanism. The returned OID set must be + freed by the application after use with a + call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.25. gss_process_context_token + + OM_uint32 gss_process_context_token ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + const gss_buffer_t token_buffer) + + Purpose: + + Provides a way to pass a token to the security service. Used with + tokens emitted by gss_delete_sec_context. Note that mechanisms are + encouraged to perform local deletion, and not emit tokens from + gss_delete_sec_context. This routine, therefore, is primarily for + backwards compatibility with V1 applications. + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + context handle of context on which token is to + be processed + + token_buffer buffer, opaque, read + token to process + + + + + Wray Document Expiration: 1 September 1997 [Page 68] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the + token failed + + GSS_S_NO_CONTEXT The context_handle did not refer to a valid context + + + + + + + + 7.26. gss_release_buffer + + OM_uint32 gss_release_buffer ( + OM_uint32 * minor_status, + gss_buffer_t buffer) + + Purpose: + + Free storage associated with a buffer. The storage must have been + allocated by a GSS-API routine. In addition to freeing the associated + storage, the routine will zero the length field in the descriptor to + which the buffer parameter refers. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + buffer buffer, modify + The storage associated with the buffer will be + deleted. The gss_buffer_desc object will not + be freed, but its length field will be zeroed. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 69] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.27. gss_release_cred + + OM_uint32 gss_release_cred ( + OM_uint32 * minor_status, + gss_cred_id_t * cred_handle) + + Purpose: + + Informs GSS-API that the specified credential handle is no longer + required by the application, and frees associated resources. + + Parameters: + + cred_handle gss_cred_id_t, modify, optional + Opaque handle identifying credential + to be released. If GSS_C_NO_CREDENTIAL + is supplied, the routine will complete + successfully, but will do nothing. + + minor_status Integer, modify + Mechanism specific status code. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED Credentials could not be accessed. + + + + + + + + 7.28. gss_release_name + + OM_uint32 gss_release_name ( + OM_uint32 * minor_status, + gss_name_t * name) + + Purpose: + + Free GSSAPI-allocated storage by associated with an internal-form name. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + name gss_name_t, modify + The name to be deleted + + + + Wray Document Expiration: 1 September 1997 [Page 70] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The name parameter did not contain a valid name + + + + + + + + 7.29. gss_release_oid_set + + OM_uint32 gss_release_oid_set ( + OM_uint32 * minor_status, + gss_OID_set * set) + + Purpose: + + Free storage associated with a GSSAPI-generated gss_OID_set object. The + set parameter must refer to an OID-set that was returned from a GSSAPI + routine. gss_release_oid_set() will free the storage associated with + each individual member OID, the OID set's elements array, and the + gss_OID_set_desc. + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + set Set of Object IDs, modify + The storage associated with the gss_OID_set + will be deleted. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 71] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.30. gss_test_oid_set_member + + OM_uint32 gss_test_oid_set_member ( + OM_uint32 * minor_status, + const gss_OID member, + const gss_OID_set set, + int * present) + + Purpose: + + Interrogate an Object Identifier set to determine whether a specified + Object Identifier is a member. This routine is intended to be used with + OID sets returned by gss_indicate_mechs(), gss_acquire_cred(), and + gss_inquire_cred(), but will also work with user-generated sets. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + member Object ID, read + The object identifier whose presence + is to be tested. + + set Set of Object ID, read + The Object Identifier set. + + present Boolean, modify + non-zero if the specified OID is a member + of the set, zero if not. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.31. gss_unwrap + + OM_uint32 gss_unwrap ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + const gss_buffer_t input_message_buffer, + gss_buffer_t output_message_buffer, + int * conf_state, + gss_qop_t * qop_state) + + + + + Wray Document Expiration: 1 September 1997 [Page 72] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Purpose: + + Converts a message previously protected by gss_wrap back to a usable + form, verifying the embedded MIC. The conf_state parameter indicates + whether the message was encrypted; the qop_state parameter indicates the + strength of protection that was used to provide the confidentiality and + integrity services. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context on which the message + arrived + + input_message_buffer buffer, opaque, read + protected message + + output_message_buffer buffer, opaque, modify + Buffer to receive unwrapped message. + Storage associated with this buffer must + be freed by the application after use use + with a call to gss_release_buffer(). + + conf_state boolean, modify, optional + Non-zero - Confidentiality and integrity protection + were used + Zero - Integrity service only was used + Specify NULL if not required + + qop_state gss_qop_t, modify, optional + Quality of protection gained from MIC. + Specify NULL if not required + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The MIC was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct MIC + for the message, but it had already been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC for + the message, but it is too old to check for + duplication. + + + + + Wray Document Expiration: 1 September 1997 [Page 73] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; a + later token has already been received. + + GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; + an earlier expected token has not yet been received. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + + + + + + + 7.32. gss_verify_mic + + OM_uint32 gss_verify_mic ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + const gss_buffer_t message_buffer, + const gss_buffer_t token_buffer, + gss_qop_t * qop_state) + + Purpose: + + Verifies that a cryptographic MIC, contained in the token parameter, + fits the supplied message. The qop_state parameter allows a message + recipient to determine the strength of protection that was applied to + the message. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context on which the message + arrived + + message_buffer buffer, opaque, read + Message to be verified + + token_buffer buffer, opaque, read + Token associated with message + + + + + Wray Document Expiration: 1 September 1997 [Page 74] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + qop_state gss_qop_t, modify, optional + quality of protection gained from MIC + Specify NULL if not required + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The MIC was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct MIC + for the message, but it had already been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC for + the message, but it is too old to check for + duplication. + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; a + later token has already been received. + + GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; + an earlier expected token has not yet been received. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + + + + + + + 7.33. gss_wrap + + OM_uint32 gss_wrap ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + int conf_req_flag, + gss_qop_t qop_req + const gss_buffer_t input_message_buffer, + int * conf_state, + gss_buffer_t output_message_buffer ) + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 75] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Purpose: + + Attaches a cryptographic MIC and optionally encrypts the specified + input_message. The output_message contains both the MIC and the + message. The qop_req parameter allows a choice between several + cryptographic algorithms, if supported by the chosen mechanism. + + Since some application-level protocols may wish to use tokens emitted by + gss_wrap() to provide "secure framing", implementations should support + the wrapping of zero-length messages. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context on which the message + will be sent + + conf_req_flag boolean, read + Non-zero - Both confidentiality and integrity + services are requested + Zero - Only integrity service is requested + + qop_req gss_qop_t, read, optional + Specifies required quality of protection. A + mechanism-specific default may be requested by + setting qop_req to GSS_C_QOP_DEFAULT. If an + unsupported protection strength is requested, + gss_wrap will return a major_status of + GSS_S_BAD_QOP. + + input_message_buffer buffer, opaque, read + Message to be protected + + conf_state boolean, modify, optional + Non-zero - Confidentiality, data origin + authentication and integrity + services have been applied + Zero - Integrity and data origin services only + has been applied. + Specify NULL if not required + + output_message_buffer buffer, opaque, modify + Buffer to receive protected message. + Storage associated with this message must + be freed by the application after use with + a call to gss_release_buffer(). + + Function value: GSS status code + + + + Wray Document Expiration: 1 September 1997 [Page 76] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. + + + + + + + + 7.34. gss_wrap_size_limit + + OM_uint32 gss_wrap_size_limit ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + int conf_req_flag, + gss_qop_t qop_req, + OM_uint32 req_output_size, + OM_uint32 * max_input_size) + + Purpose: + + Allows an application to determine the maximum message size that, if + presented to gss_wrap with the same conf_req_flag and qop_req + parameters, will result in an output token containing no more than + req_output_size bytes. + + This call is intended for use by applications that communicate over + protocols that impose a maximum message size. It enables the + application to fragment messages prior to applying protection. + + Successful completion of this call does not guarantee that gss_wrap will + be able to protect a message of length max_input_size bytes, since this + ability may depend on the availability of system resources at the time + that gss_wrap is called. However, if the implementation itself imposes + an upper limit on the length of messages that may be processed by + gss_wrap, the implementation should not return a value via + max_input_bytes that is greater than this length. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + context_handle gss_ctx_id_t, read + A handle that refers to the security over + + + + Wray Document Expiration: 1 September 1997 [Page 77] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + which the messages will be sent. + + conf_req_flag Boolean, read + Indicates whether gss_wrap will be asked + to apply confidentiality protection in + addition to integrity protection. See + the routine description for gss_wrap + for more details. + + qop_req gss_qop_t, read + Indicates the level of protection that + gss_wrap will be asked to provide. See + the routine description for gss_wrap for + more details. + + req_output_size Integer, read + The desired maximum size for tokens emitted + by gss_wrap. + + max_input_size Integer, modify + The maximum input message size that may + be presented to gss_wrap in order to + guarantee that the emitted token shall + be no larger than req_output_size bytes. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CONTEXT The referenced context could not be accessed. + + GSS_S_CONTEXT_EXPIRED The context has expired. + + GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. + + + + + + + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 78] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + APPENDIX A. GSS-API C header file gssapi.h + + C-language GSS-API implementations should include a copy of the + following header-file. + + #ifndef GSSAPI_H_ + #define GSSAPI_H_ + + + + /* + * First, include stddef.h to get size_t defined. + */ + #include + + /* + * If the platform supports the xom.h header file, it should be + * included here. + */ + #include + + + + /* + * Now define the three implementation-dependent types. + */ + typedef gss_ctx_id_t; + typedef gss_cred_id_t; + typedef gss_name_t; + + /* + * The following type must be defined as the smallest natural + * unsigned integer supported by the platform that has at least + * 32 bits of precision. + */ + typedef gss_uint32; + + + #ifdef OM_STRING + /* + * We have included the xom.h header file. Verify that OM_uint32 + * is defined correctly. + */ + + #if sizeof(gss_uint32) != sizeof(OM_uint32) + #error Incompatible definition of OM_uint32 from xom.h + #endif + + typedef OM_object_identifier gss_OID_desc, *gss_OID; + + #else + + + + Wray Document Expiration: 1 September 1997 [Page 79] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* + * We can't use X/Open definitions, so roll our own. + */ + + typedef gss_uint32 OM_uint32; + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + #endif + + typedef struct gss_OID_set_desc_struct { + size_t count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + + /* + * For now, define a QOP-type as an OM_uint32 + */ + typedef OM_uint32 gss_qop_t; + + typedef int gss_cred_usage_t; + + /* + * Flag bits for context-level services. + */ + #define GSS_C_DELEG_FLAG 1 + #define GSS_C_MUTUAL_FLAG 2 + #define GSS_C_REPLAY_FLAG 4 + #define GSS_C_SEQUENCE_FLAG 8 + #define GSS_C_CONF_FLAG 16 + #define GSS_C_INTEG_FLAG 32 + #define GSS_C_ANON_FLAG 64 + #define GSS_C_PROT_READY_FLAG 128 + #define GSS_C_TRANS_FLAG 256 + + + + Wray Document Expiration: 1 September 1997 [Page 80] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* + * Credential usage options + */ + #define GSS_C_BOTH 0 + #define GSS_C_INITIATE 1 + #define GSS_C_ACCEPT 2 + + /* + * Status code types for gss_display_status + */ + #define GSS_C_GSS_CODE 1 + #define GSS_C_MECH_CODE 2 + + /* + * The constant definitions for channel-bindings address families + */ + #define GSS_C_AF_UNSPEC 0 + #define GSS_C_AF_LOCAL 1 + #define GSS_C_AF_INET 2 + #define GSS_C_AF_IMPLINK 3 + #define GSS_C_AF_PUP 4 + #define GSS_C_AF_CHAOS 5 + #define GSS_C_AF_NS 6 + #define GSS_C_AF_NBS 7 + #define GSS_C_AF_ECMA 8 + #define GSS_C_AF_DATAKIT 9 + #define GSS_C_AF_CCITT 10 + #define GSS_C_AF_SNA 11 + #define GSS_C_AF_DECnet 12 + #define GSS_C_AF_DLI 13 + #define GSS_C_AF_LAT 14 + #define GSS_C_AF_HYLINK 15 + #define GSS_C_AF_APPLETALK 16 + #define GSS_C_AF_BSC 17 + #define GSS_C_AF_DSS 18 + #define GSS_C_AF_OSI 19 + #define GSS_C_AF_X25 21 + + #define GSS_C_AF_NULLADDR 255 + + /* + * Various Null values + */ + #define GSS_C_NO_NAME ((gss_name_t) 0) + #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) + #define GSS_C_NO_OID ((gss_OID) 0) + #define GSS_C_NO_OID_SET ((gss_OID_set) 0) + #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) + #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) + #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) + #define GSS_C_EMPTY_BUFFER {0, NULL} + + + + Wray Document Expiration: 1 September 1997 [Page 81] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* + * Some alternate names for a couple of the above + * values. These are defined for V1 compatibility. + */ + #define GSS_C_NULL_OID GSS_C_NO_OID + #define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET + + /* + * Define the default Quality of Protection for per-message + * services. Note that an implementation that offers multiple + * levels of QOP may define GSS_C_QOP_DEFAULT to be either zero + * (as done here) to mean "default protection", or to a specific + * explicit QOP value. However, a value of 0 should always be + * interpreted by a GSSAPI implementation as a request for the + * default protection level. + */ + #define GSS_C_QOP_DEFAULT 0 + + /* + * Expiration time of 2^32-1 seconds means infinite lifetime for a + * credential or security context + */ + #define GSS_C_INDEFINITE 0xfffffffful + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" + * "\x01\x02\x01\x01"}, + * corresponding to an object-identifier value of + * {iso(1) member-body(2) United States(840) mit(113554) + * infosys(1) gssapi(2) generic(1) user_name(1)}. The constant + * GSS_C_NT_USER_NAME should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_USER_NAME; + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" + * "\x01\x02\x01\x02"}, + * corresponding to an object-identifier value of + * {iso(1) member-body(2) United States(840) mit(113554) + * infosys(1) gssapi(2) generic(1) machine_uid_name(2)}. + * The constant GSS_C_NT_MACHINE_UID_NAME should be + * initialized to point to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_MACHINE_UID_NAME; + + /* + + + + Wray Document Expiration: 1 September 1997 [Page 82] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" + * "\x01\x02\x01\x03"}, + * corresponding to an object-identifier value of + * {iso(1) member-body(2) United States(840) mit(113554) + * infosys(1) gssapi(2) generic(1) string_uid_name(3)}. + * The constant GSS_C_NT_STRING_UID_NAME should be + * initialized to point to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_STRING_UID_NAME; + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {6, (void *)"\x2b\x06\x01\x05\x06\x02"}, + * corresponding to an object-identifier value of + * {1(iso), 3(org), 6(dod), 1(internet), 5(security), + * 6(nametypes), 2(gss-host-based-services)}. The constant + * GSS_C_NT_HOSTBASED_SERVICE should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_HOSTBASED_SERVICE; + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {6, (void *)"\x2b\x06\01\x05\x06\x03"}, + * corresponding to an object identifier value of + * {1(iso), 3(org), 6(dod), 1(internet), 5(security), + * 6(nametypes), 3(gss-anonymous-name)}. The constant + * and GSS_C_NT_ANONYMOUS should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_ANONYMOUS; + + + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {6, (void *)"\x2b\x06\x01\x05\x06\x04"}, + * corresponding to an object-identifier value of + * {1(iso), 3(org), 6(dod), 1(internet), 5(security), + * 6(nametypes), 4(gss-api-exported-name)}. The constant + * GSS_C_NT_EXPORT_NAME should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_EXPORT_NAME; + + + + + + Wray Document Expiration: 1 September 1997 [Page 83] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* Major status codes */ + + #define GSS_S_COMPLETE 0 + + /* + * Some "helper" definitions to make the status code macros obvious. + */ + #define GSS_C_CALLING_ERROR_OFFSET 24 + #define GSS_C_ROUTINE_ERROR_OFFSET 16 + #define GSS_C_SUPPLEMENTARY_OFFSET 0 + #define GSS_C_CALLING_ERROR_MASK 0377ul + #define GSS_C_ROUTINE_ERROR_MASK 0377ul + #define GSS_C_SUPPLEMENTARY_MASK 0177777ul + + /* + * The macros that test status codes for error conditions. + * Note that the GSS_ERROR() macro has changed slightly from + * the V1 GSSAPI so that it now evaluates its argument + * only once. + */ + #define GSS_CALLING_ERROR(x) \ + (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) + #define GSS_ROUTINE_ERROR(x) \ + (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) + #define GSS_SUPPLEMENTARY_INFO(x) \ + (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) + #define GSS_ERROR(x) \ + (x & ((GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET) | \ + (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))) + + + /* + * Now the actual status code definitions + */ + + /* + * Calling errors: + */ + #define GSS_S_CALL_INACCESSIBLE_READ \ + (1ul << GSS_C_CALLING_ERROR_OFFSET) + #define GSS_S_CALL_INACCESSIBLE_WRITE \ + (2ul << GSS_C_CALLING_ERROR_OFFSET) + #define GSS_S_CALL_BAD_STRUCTURE \ + (3ul << GSS_C_CALLING_ERROR_OFFSET) + + /* + * Routine errors: + */ + #define GSS_S_BAD_MECH (1ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAME (2ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAMETYPE (3ul << GSS_C_ROUTINE_ERROR_OFFSET) + + + + Wray Document Expiration: 1 September 1997 [Page 84] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + #define GSS_S_BAD_BINDINGS (4ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_STATUS (5ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_SIG (6ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_MIC GSS_S_BAD_SIG + #define GSS_S_NO_CRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NO_CONTEXT (8ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_TOKEN (9ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CREDENTIALS_EXPIRED (11ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CONTEXT_EXPIRED (12ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_FAILURE (13ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_QOP (14ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_UNAUTHORIZED (15ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_UNAVAILABLE (16ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DUPLICATE_ELEMENT (17ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NAME_NOT_MN (18ul << GSS_C_ROUTINE_ERROR_OFFSET) + + /* + * Supplementary info bits: + */ + #define GSS_S_CONTINUE_NEEDED (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) + #define GSS_S_DUPLICATE_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) + #define GSS_S_OLD_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) + #define GSS_S_UNSEQ_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) + #define GSS_S_GAP_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4)) + + + /* + * Finally, function prototypes for the GSS-API routines. + */ + + OM_uint32 gss_acquire_cred + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* desired_name */ + OM_uint32, /* time_req */ + const gss_OID_set, /* desired_mechs */ + gss_cred_usage_t, /* cred_usage */ + gss_cred_id_t *, /* output_cred_handle */ + gss_OID_set *, /* actual_mechs */ + OM_uint32 * /* time_rec */ + ); + + OM_uint32 gss_release_cred + (OM_uint32 *, /* minor_status */ + gss_cred_id_t * /* cred_handle */ + ); + + OM_uint32 gss_init_sec_context + (OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* initiator_cred_handle */ + gss_ctx_id_t *, /* context_handle */ + + + + Wray Document Expiration: 1 September 1997 [Page 85] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + const gss_name_t, /* target_name */ + const gss_OID, /* mech_type */ + OM_uint32, /* req_flags */ + OM_uint32, /* time_req */ + const gss_channel_bindings_t, + /* input_chan_bindings */ + const gss_buffer_t, /* input_token */ + gss_OID *, /* actual_mech_type */ + gss_buffer_t, /* output_token */ + OM_uint32 *, /* ret_flags */ + OM_uint32 * /* time_rec */ + ); + + OM_uint32 gss_accept_sec_context + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t *, /* context_handle */ + const gss_cred_id_t, /* acceptor_cred_handle */ + const gss_buffer_t, /* input_token_buffer */ + const gss_channel_bindings_t, + /* input_chan_bindings */ + gss_name_t *, /* src_name */ + gss_OID *, /* mech_type */ + gss_buffer_t, /* output_token */ + OM_uint32 *, /* ret_flags */ + OM_uint32 *, /* time_rec */ + gss_cred_id_t * /* delegated_cred_handle */ + ); + + OM_uint32 gss_process_context_token + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + const gss_buffer_t /* token_buffer */ + ); + + OM_uint32 gss_delete_sec_context + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t *, /* context_handle */ + gss_buffer_t /* output_token */ + ); + + OM_uint32 gss_context_time + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + OM_uint32 * /* time_rec */ + ); + + OM_uint32 gss_get_mic + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + gss_qop_t, /* qop_req */ + const gss_buffer_t, /* message_buffer */ + + + + Wray Document Expiration: 1 September 1997 [Page 86] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_buffer_t /* message_token */ + ); + + + OM_uint32 gss_verify_mic + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + const gss_buffer_t, /* message_buffer */ + const gss_buffer_t, /* token_buffer */ + gss_qop_t * /* qop_state */ + ); + + OM_uint32 gss_wrap + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + gss_qop_t, /* qop_req */ + const gss_buffer_t, /* input_message_buffer */ + int *, /* conf_state */ + gss_buffer_t /* output_message_buffer */ + ); + + + OM_uint32 gss_unwrap + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + const gss_buffer_t, /* input_message_buffer */ + gss_buffer_t, /* output_message_buffer */ + int *, /* conf_state */ + gss_qop_t * /* qop_state */ + ); + + + + OM_uint32 gss_display_status + (OM_uint32 *, /* minor_status */ + OM_uint32, /* status_value */ + int, /* status_type */ + const gss_OID, /* mech_type */ + OM_uint32 *, /* message_context */ + gss_buffer_t /* status_string */ + ); + + OM_uint32 gss_indicate_mechs + (OM_uint32 *, /* minor_status */ + gss_OID_set * /* mech_set */ + ); + + OM_uint32 gss_compare_name + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* name1 */ + + + + Wray Document Expiration: 1 September 1997 [Page 87] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + const gss_name_t, /* name2 */ + int * /* name_equal */ + ); + + OM_uint32 gss_display_name + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + gss_buffer_t, /* output_name_buffer */ + gss_OID * /* output_name_type */ + ); + + OM_uint32 gss_import_name + (OM_uint32 *, /* minor_status */ + const gss_buffer_t, /* input_name_buffer */ + const gss_OID, /* input_name_type */ + gss_name_t * /* output_name */ + ); + + OM_uint32 gss_export_name + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + gss_buffer_t /* exported_name */ + ); + + OM_uint32 gss_release_name + (OM_uint32 *, /* minor_status */ + gss_name_t * /* input_name */ + ); + + OM_uint32 gss_release_buffer + (OM_uint32 *, /* minor_status */ + gss_buffer_t /* buffer */ + ); + + OM_uint32 gss_release_oid_set + (OM_uint32 *, /* minor_status */ + gss_OID_set * /* set */ + ); + + OM_uint32 gss_inquire_cred + (OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* cred_handle */ + gss_name_t *, /* name */ + OM_uint32 *, /* lifetime */ + gss_cred_usage_t *, /* cred_usage */ + gss_OID_set * /* mechanisms */ + ); + + OM_uint32 gss_inquire_context ( + OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + + + + Wray Document Expiration: 1 September 1997 [Page 88] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_name_t *, /* src_name */ + gss_name_t *, /* targ_name */ + OM_uint32 *, /* lifetime_rec */ + gss_OID *, /* mech_type */ + OM_uint32 *, /* ctx_flags */ + int *, /* locally_initiated */ + int * /* open */ + ); + + OM_uint32 gss_wrap_size_limit ( + OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + gss_qop_t, /* qop_req */ + OM_uint32, /* req_output_size */ + OM_uint32 * /* max_input_size */ + ); + + + OM_uint32 gss_add_cred ( + OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* input_cred_handle */ + const gss_name_t, /* desired_name */ + const gss_OID, /* desired_mech */ + gss_cred_usage_t, /* cred_usage */ + OM_uint32, /* initiator_time_req */ + OM_uint32, /* acceptor_time_req */ + gss_cred_id_t *, /* output_cred_handle */ + gss_OID_set *, /* actual_mechs */ + OM_uint32 *, /* initiator_time_rec */ + OM_uint32 * /* acceptor_time_rec */ + ); + + + OM_uint32 gss_inquire_cred_by_mech ( + OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* cred_handle */ + const gss_OID, /* mech_type */ + gss_name_t *, /* name */ + OM_uint32 *, /* initiator_lifetime */ + OM_uint32 *, /* acceptor_lifetime */ + gss_cred_usage_t * /* cred_usage */ + ); + + OM_uint32 gss_export_sec_context ( + OM_uint32 *, /* minor_status */ + gss_ctx_id_t *, /* context_handle */ + gss_buffer_t /* interprocess_token */ + ); + + OM_uint32 gss_import_sec_context ( + + + + Wray Document Expiration: 1 September 1997 [Page 89] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + OM_uint32 *, /* minor_status */ + const gss_buffer_t, /* interprocess_token */ + gss_ctx_id_t * /* context_handle */ + ); + + OM_uint32 gss_create_empty_oid_set ( + OM_uint32 *, /* minor_status */ + gss_OID_set * /* oid_set */ + ); + + OM_uint32 gss_add_oid_set_member ( + OM_uint32 *, /* minor_status */ + const gss_OID, /* member_oid */ + gss_OID_set * /* oid_set */ + ); + + OM_uint32 gss_test_oid_set_member ( + OM_uint32 *, /* minor_status */ + const gss_OID, /* member */ + const gss_OID_set, /* set */ + int * /* present */ + ); + + OM_uint32 gss_inquire_names_for_mech ( + OM_uint32 *, /* minor_status */ + const gss_OID, /* mechanism */ + gss_OID_set * /* name_types */ + ); + + OM_uint32 gss_inquire_mechs_for_name ( + OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + gss_OID_set * /* mech_types */ + ); + + OM_uint32 gss_canonicalize_name ( + OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + const gss_OID, /* mech_type */ + gss_name_t * /* output_name */ + ); + + OM_uint32 gss_duplicate_name ( + OM_uint32 *, /* minor_status */ + const gss_name_t, /* src_name */ + gss_name_t * /* dest_name */ + ); + + /* + * The following routines are obsolete variants of gss_get_mic, + * gss_verify_mic, gss_wrap and gss_unwrap. They should be + + + + Wray Document Expiration: 1 September 1997 [Page 90] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + * provided by GSSAPI V2 implementations for backwards + * compatibility with V1 applications. Distinct entrypoints + * (as opposed to #defines) should be provided, both to allow + * GSSAPI V1 applications to link against GSSAPI V2 implementations, + * and to retain the slight parameter type differences between the + * obsolete versions of these routines and their current forms. + */ + + OM_uint32 gss_sign + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* qop_req */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t /* message_token */ + ); + + + OM_uint32 gss_verify + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t, /* token_buffer */ + int * /* qop_state */ + ); + + OM_uint32 gss_seal + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + int, /* qop_req */ + gss_buffer_t, /* input_message_buffer */ + int *, /* conf_state */ + gss_buffer_t /* output_message_buffer */ + ); + + + OM_uint32 gss_unseal + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* input_message_buffer */ + gss_buffer_t, /* output_message_buffer */ + int *, /* conf_state */ + int * /* qop_state */ + ); + + + + + #endif /* GSSAPI_H_ */ + + + + + + Wray Document Expiration: 1 September 1997 [Page 91] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + APPENDIX B. Additional constraints for application binary portability + + The purpose of this C-bindings document is to encourage source-level + portability of applications across GSS-API implementations on different + platforms and atop different mechanisms. Additional goals that have not + been explicitly addressed by this document are link-time and run-time + portability. + + Link-time portability provides the ability to compile an application + against one implementation of GSS-API, and then link it against a + different implementation on the same platform. It is a stricter + requirement than source-level portability. + + Run-time portability differs from link-time portability only on those + platforms that implement dynamically loadable GSS-API implementations, + but do not offer load-time symbol resolution. On such platforms, run- + time portability is a stricter requirement than link-time portability, + and will typically include the precise placement of the various GSS-API + routines within library entrypoint vectors. + + Individual platforms will impose their own rules that must be followed + to achieve link-time (and run-time, if different) portability. In order + to ensure either form of binary portability, an ABI specification must + be written for GSS-API implementations on that platform. However, it is + recognized that there are some issues that are likely to be common to + all such ABI specifications. This appendix is intended to be a + repository for such common issues, and contains some suggestions that + individual ABI specifications may choose to reference. Since machine + architectures vary greatly, it may not be possible or desirable to + follow these suggestions on all platforms. + + B.1. Pointers + + While ANSI-C provides a single pointer type for each declared type, plus + a single (void *) type, some platforms (notably those using segmented + memory architectures) augment this with various modified pointer types + (e.g. far pointers, near pointers). These language bindings assume + ANSI-C, and thus do not address such non-standard implementations. + GSS-API implementations for such platforms must choose an appropriate + memory model, and should use it consistently throughout. For example, + if a memory model is chosen that requires the use of far pointers when + passing routine parameters, then far pointers should also be used within + the structures defined by GSS-API. + + B.2. Internal structure alignment + + GSS-API defines several data-structures containing differently-sized + fields. An ABI specification should include a detailed description of + how the fields of such structures are aligned, and if there is any + internal padding in these data structures. The use of compiler defaults + for the platform is recommended. + + + + Wray Document Expiration: 1 September 1997 [Page 92] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + B.3. Handle types + + The C bindings specify that the gss_cred_id_t and gss_ctx_id_t types + should be implemented as either pointer or arithmetic types, and that if + pointer types are used, care should be taken to ensure that two handles + may be compared with the == operator. Note that ANSI-C does not + guarantee that two pointer values may be compared with the == operator + unless either the two pointers point to members of a single array, or at + least one of the pointers contains a NULL value. + + For binary portability, additional constraints are required. The + following is an attempt at defining platform-independent constraints. + + (a) The size of the handle type must be the same as sizeof(void *), + using the appropriate memory model. + + (b) The == operator for the chosen type must be a simple bit-wise + comparison. That is, for two in-memory handle objects h1 and h2, + the boolean value of the expression + + (h1 == h2) + + should always be the same as the boolean value of the expression + + (memcmp(&h1, &h2, sizeof(h1)) == 0) + + (c) The actual use of the type (void *) for handle types is + discouraged, not for binary portability reasons, but since it + effectively disables much of the compile-time type-checking that + the compiler can otherwise perform, and is therefore not + "programmer-friendly". If a pointer implementation is desired, + and if the platform's implementation of pointers permits, the + handles should be implemented as pointers to distinct + implementation-defined types. + + B.4. The gss_name_t type + + The gss_name_t type, representing the internal name object, should be + implemented as a pointer type. The use of the (void *) type is + discouraged as it does not allow the compiler to perform strong type- + checking. However, the pointer type chosen should be of the same size + as the (void *) type. Provided this rule is obeyed, ABI specifications + need not further constrain the implementation of gss_name_t objects. + + B.5. The int and size_t types + + Some platforms may support differently sized implementations of the + "int" and "size_t" types, perhaps chosen through compiler switches, and + perhaps dependent on memory model. An ABI specification for such a + platform should include required implementations for these types. It is + recommended that the default implementation (for the chosen memory + + + + Wray Document Expiration: 1 September 1997 [Page 93] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + model, if appropriate) is chosen. + + B.6. Procedure-calling conventions + + Some platforms support a variety of different binary conventions for + calling procedures. Such conventions cover things like the format of + the stack frame, the order in which the routine parameters are pushed + onto the stack, whether or not a parameter count is pushed onto the + stack, whether some argument(s) or return values are to be passed in + registers, and whether the called routine or the caller is responsible + for removing the stack frame on return. For such platforms, an ABI + specification should specify which calling convention is to be used for + GSSAPI implementations. + + + REFERENCES + + [GSSAPI] J. Linn, "Generic Security Service Application Program + Interface, Version 2", Internet-Draft draft-ietf-cat-gssv2- + 08, 26 August 1996. (This Internet-Draft, like all other + Internet-Drafts, is not an archival document and is subject + to change or deletion. It is available at the time of this + writing by anonymous ftp from ds.internic.net, directory + internet-drafts. Would-be readers should check for successor + Internet-Draft versions or Internet RFCs before relying on + this document.) + + [XOM] OSI Object Management API Specification, Version 2.0 t", + X.400 API Association & X/Open Company Limited, August 24, + 1990. Specification of datatypes and routines for + manipulating information objects. + + + AUTHOR'S ADDRESS + + John Wray Internet email: Wray@tuxedo.enet.dec.com + Digital Equipment Corporation Telephone: +1-508-486-5210 + 550 King Street, LKG2-2/Z7 + Littleton, MA 01460 + USA + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 94] + + + diff --git a/doc/draft-ietf-cat-kerb-chg-password-00.txt b/doc/draft-ietf-cat-kerb-chg-password-00.txt new file mode 100644 index 000000000..b34a98ce9 --- /dev/null +++ b/doc/draft-ietf-cat-kerb-chg-password-00.txt @@ -0,0 +1,252 @@ + + + + + + +Network Working Group M. Horowitz + Cygnus Solutions +Internet-Draft March, 1997 +Expire in six months + + Kerberos Change Password Protocol + +Status of this Memo + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its areas, + and its working groups. Note that other groups may also distribute + working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as ``work in progress.'' + + To learn the current status of any Internet-Draft, please check the + ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow + Directories on ds.internic.net (US East Coast), nic.nordu.net + (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific + Rim). + + Distribution of this memo is unlimited. Please send comments to the + mailing list. + +Abstract + + The Kerberos V5 protocol [RFC1510] does not describe any mechanism + for users to change their own passwords. In order to promote + interoperability between workstations, personal computers, terminal + servers, routers, and KDC's from multiple vendors, a common password + changing protocol is required. + + + +Overview + + When a user wishes to change his own password, or is required to by + local policy, a simple request of a password changing service is + necessary. This service must be implemented on at least one host for + each Kerberos realm, probably on one of the kdc's for that realm. + The service must accept requests on UDP port 464 (kpasswd), and may + accept requests on TCP port 464 as well. + + The protocol itself consists of a single request message followed by + a single reply message. For UDP transport, each message must be + fully contained in a single UDP packet. + + + + + + + + +Horowitz [Page 1] + +Internet Draft Kerberos Change Password Protocol March, 1997 + + +Request Message + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | message length | protocol version number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | AP_REQ length | AP-REQ data / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + / KRB-PRIV message / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + message length (16 bits) + Contains the length of the message, including this field, in bytes + (big-endian integer) + protocol version number (16 bits) + Contains the hex constant 0x0001 (big-endian integer) + AP-REQ length (16 bits) + length (big-endian integer) of AP-REQ data, in bytes. + AP-REQ data, as described in RFC1510 (variable length) + This AP-REQ must be for the service principal + kadmin/changepw@REALM, where REALM is the REALM of the user who + wishes to change his password. The Ticket in the AP-REQ must be + derived from an AS request (thus having the INITIAL flag set), and + must include a subkey in the Authenticator. + KRB-PRIV message, as described in RFC1510 (variable length) + This KRB-PRIV message must be generated using the subkey in the + Authenticator in the AP-REQ data. The user-data component of the + message must consist of the user's new password. + + The server must verify the AP-REQ message, decrypt the new password, + perform any local policy checks (such as password quality, history, + authorization, etc.) required, then set the password to the new value + specified. + + The principal whose password is to be changed is the principal which + authenticated to the password changing service. This protocol does + not address administrators who want to change passwords of principal + besides their own. + + +Reply Message + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | message length | protocol version number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | AP_REP length | AP-REP data / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + / KRB-PRIV or KRB-ERROR message / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + message length (16 bits) + + + +Horowitz [Page 2] + +Internet Draft Kerberos Change Password Protocol March, 1997 + + + Contains the length of the message, including this field, in bytes + (big-endian integer), + protocol version number (16 bits) + Contains the hex constant 0x0001 (big-endian integer) + AP-REP length (16 bits) + length of AP-REP data, in bytes. If the the length is zero, then + the last field will contain a KRB-ERROR message instead of a KRB- + PRIV message. + AP-REP data, as described in RFC1510 (variable length) + The AP-REP corresponding to the AP-REQ in the request packet. + KRB-PRIV or KRB-ERROR message, as described in RFC1510 (variable + length) + If the AP-REP length is zero, then this field contains a KRB-ERROR + message. Otherwise, it contains a KRB-PRIV message. This KRB- + PRIV message must be generated using the subkey in the + Authenticator in the AP-REQ data. + + The user-data component of the KRB-PRIV message, or e-data + component of the KRB-ERROR message, must consist of the following + data: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | result code | result string / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + result code (16 bits) + The result code must have one of the following values (big- + endian integer): + 0x0000 if the request succeeds. (This value is not permitted + in a KRB-ERROR message.) + 0x0001 if the request fails due to being malformed + 0x0002 if the request fails due to a "hard" error processing + the request (for example, there is a resource or other + problem causing the request to fail) + 0x0003 if the request fails due to an error in authentication + processing + 0x0004 if the request fails due to a "soft" error processing + the request (for example, some policy or other similar + consideration is causing the request to be rejected). + 0xFFFF if the request fails for some other reason. + Although only four non-zero result codes are specified here, + the client should accept any non-zero result code as indicating + failure. + result string (variable length) + This field should contain information which the server thinks + might be useful to the user. No particular format is mandated, + and the field may be omitted if the server does not wish to + include it. This field is analogous to the string which + follows the numeric code in SMTP, FTP, and similar protocols. + + + + + + +Horowitz [Page 3] + +Internet Draft Kerberos Change Password Protocol March, 1997 + + +Security Considerations + + This document deals with changing passwords for Kerberos. Because + Kerberos is used for authentication and key distribution, it is + important that this protocol use the highest level of security + services available to a particular installation. Mutual + authentication is performed, so that the server knows the request is + valid, and the client knows that the request has been received and + processed by the server. + + There are also security issues relating to dropped, stolen, or + modified messages. An attacker (or simply a lossy network) could + cause either the request or reply to be dropped, or substitute a KRB- + ERROR message in the reply. + + If a reply is dropped, it is reasonable for the client to construct a + new authenticator, re-encrypt the request, and retransmit. If the + request was lost, the server will treat this as a valid request, and + all should work normally. If the reply was lost, then the server + should take care to notice that the request was a duplicate of the + prior request, and indicate success without actually changing the + password or any other information (such as modification timestamps). + + If a success reply was replaced with an error reply, then one would + expect that the user would attempt the operation again. Again, the + server should recognize the request as a duplicate and indicate + success without changing the password. If the user is required to + provide the old password again, but the password was actually changed + successfully, then some user confusion could result. This is, + unfortunately, impossible to prevent. + + +References + + [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network + Authentication Service (V5)", RFC 1510, September 1993. + + +Author's Address + + Marc Horowitz + Cygnus Solutions + 955 Massachusetts Avenue + Cambridge, MA 02139 + + Phone: +1 617 354 7688 + Email: marc@cygnus.com + + + + + + + + + + +Horowitz [Page 4] + diff --git a/doc/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt b/doc/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt new file mode 100644 index 000000000..2583a84da --- /dev/null +++ b/doc/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt @@ -0,0 +1,127 @@ + + + + + + +Network Working Group M. Horowitz + Cygnus Solutions +Internet-Draft November, 1996 + + + Triple DES with HMAC-SHA1 Kerberos Encryption Type + +Status of this Memo + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its areas, + and its working groups. Note that other groups may also distribute + working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as ``work in progress.'' + + To learn the current status of any Internet-Draft, please check the + ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow + Directories on ds.internic.net (US East Coast), nic.nordu.net + (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific + Rim). + + Distribution of this memo is unlimited. Please send comments to the + mailing list. + +Abstract + + This document defines a new encryption type and a new checksum type + for use with Kerberos V5 [RFC1510]. This encryption type is based on + the Triple DES cryptosystem and the HMAC-SHA1 [Krawczyk96] message + authentication algorithm. + + The des3-cbc-hmac-sha1 encryption type has been assigned the value 7. + The hmac-sha1-des3 checksum type has been assigned the value 12. + + +Encryption Type des3-cbc-hmac-sha1 + + EncryptedData using this type must be generated as described in + [Horowitz96]. The encryption algorithm is Triple DES in Outer-CBC + mode. The keyed hash algorithm is HMAC-SHA1. Unless otherwise + specified, a zero IV must be used. If the length of the input data + is not a multiple of the block size, zero octets must be used to pad + the plaintext to the next eight-octet boundary. The counfounder must + be eight random octets (one block). + + +Checksum Type hmac-sha1-des3 + + Checksums using this type must be generated as described in + [Horowitz96]. The keyed hash algorithm is HMAC-SHA1. + + + +Horowitz [Page 1] + +Internet Draft Kerberos Triple DES with HMAC-SHA1 November, 1996 + + +Common Requirements + + Where the Triple DES key is represented as an EncryptionKey, it shall + be represented as three DES keys, with parity bits, concatenated + together. The key shall be represented with the most significant bit + first. + + When keys are generated by the derivation function, a key length of + 168 bits shall be used. The output bit string will be converted to a + valid Triple DES key by inserting DES parity bits after every seventh + bit. + + Any implementation which implements either of the encryption or + checksum types in this document must support both. + + +Security Considerations + + This entire document defines encryption and checksum types for use + with Kerberos V5. + + +References + + [Horowitz96] Horowitz, M., "Key Derivation for Kerberos V5", draft- + horowitz-kerb-key-derivation-00.txt, November 1996. + [Krawczyk96] Krawczyk, H., Bellare, and M., Canetti, R., "HMAC: + Keyed-Hashing for Message Authentication", draft-ietf-ipsec-hmac- + md5-01.txt, August, 1996. + [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network + Authentication Service (V5)", RFC 1510, September 1993. + + +Author's Address + + Marc Horowitz + Cygnus Solutions + 955 Massachusetts Avenue + Cambridge, MA 02139 + + Phone: +1 617 354 7688 + Email: marc@cygnus.com + + + + + + + + + + + + + + + +Horowitz [Page 2] + diff --git a/doc/draft-ietf-cat-kerb-key-derivation-00.txt b/doc/draft-ietf-cat-kerb-key-derivation-00.txt new file mode 100644 index 000000000..46a415852 --- /dev/null +++ b/doc/draft-ietf-cat-kerb-key-derivation-00.txt @@ -0,0 +1,250 @@ + + + + + +Network Working Group M. Horowitz + Cygnus Solutions +Internet-Draft November, 1996 + + + Key Derivation for Kerberos V5 + +Status of this Memo + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its areas, + and its working groups. Note that other groups may also distribute + working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as ``work in progress.'' + + To learn the current status of any Internet-Draft, please check the + ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow + Directories on ds.internic.net (US East Coast), nic.nordu.net + (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific + Rim). + + Distribution of this memo is unlimited. Please send comments to the + mailing list. + +Abstract + + In the Kerberos protocol [RFC1510], cryptographic keys are used in a + number of places. In order to minimize the effect of compromising a + key, it is desirable to use a different key for each of these places. + Key derivation [Horowitz96] can be used to construct different keys + for each operation from the keys transported on the network. For + this to be possible, a small change to the specification is + necessary. + + +Overview + + Under RFC1510 as stated, key derivation could be specified as a set + of encryption types which share the same key type. The constant for + each derivation would be a function of the encryption type. However, + it is generally accepted that, for interoperability, key types and + encryption types must map one-to-one onto each other. (RFC 1510 is + being revised to address this issue.) Therefore, to use key + derivcation with Kerberos V5 requires a small change to the + specification. + + For each place where a key is used in Kerberos, a ``key usage'' must + be specified for that purpose. The key, key usage, and + encryption/checksum type together describe the transformation from + plaintext to ciphertext, or plaintext to checksum. For backward + + + +Horowitz [Page 1] + +Internet Draft Key Derivation for Kerberos V5 November, 1996 + + + compatibility, old encryption types would be defined independently of + the key usage. + + +Key Usage Values + + This is a complete list of places keys are used in the kerberos + protocol, with key usage values and RFC 1510 section numbers: + + 1. AS-REQ PA-ENC-TIMESTAMP padata timestamp, encrypted with the + client key (section 5.4.1) + 2. AS-REP Ticket and TGS-REP Ticket (includes tgs session key or + application session key), encrypted with the service key + (section 5.4.2) + 3. AS-REP encrypted part (includes tgs session key or application + session key), encrypted with the client key (section 5.4.2) + + 4. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + session key (section 5.4.1) + 5. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + authenticator subkey (section 5.4.1) + 6. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator cksum, keyed + with the tgs session key (sections 5.3.2, 5.4.1) + 7. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator (includes tgs + authenticator subkey), encrypted with the tgs session key + (section 5.3.2) + 8. TGS-REP encrypted part (includes application session key), + encrypted with the tgs session key (section 5.4.2) + 9. TGS-REP encrypted part (includes application session key), + encrypted with the tgs authenticator subkey (section 5.4.2) + + 10. AP-REQ Authenticator cksum, keyed with the application session + key (section 5.3.2) + 11. AP-REQ Authenticator (includes application authenticator + subkey), encrypted with the application session key (section + 5.3.2) + 12. AP-REP encrypted part (includes application session subkey), + encrypted with the application session key (section 5.5.2) + + 13. KRB-PRIV encrypted part, encrypted with a key chosen by the + application (section 5.7.1) + 14. KRB-CRED encrypted part, encrypted with a key chosen by the + application (section 5.6.1) + 15. KRB-SAVE cksum, keyed with a key chosen by the application + (section 5.8.1) + + 16. Data which is defined in some specification outside of + Kerberos to be encrypted using an RFC1510 encryption type. + 17. Data which is defined in some specification outside of + Kerberos to be checksummed using an RFC1510 checksum type. + + A few of these key usages need a little clarification. A service + which receives an AP-REQ has no way to know if the enclosed Ticket + was part of an AS-REP or TGS-REP. Therefore, key usage 2 must always + + + +Horowitz [Page 2] + +Internet Draft Key Derivation for Kerberos V5 November, 1996 + + + be used for generating a Ticket, whether it is in response to an AS- + REQ or TGS-REQ. + + There might exist other documents which define protocols in terms of + the RFC1510 encryption types or checksum types. Such documents would + not know about key usages. In order that these documents continue to + be meaningful until they are updated, key usages 16 and 17 must be + used to derive keys for encryption and checksums, respectively. New + protocols defined in terms of the Kerberos encryption and checksum + types should use their own key usages. Key usages may be registered + with IANA to avoid conflicts. Key usages shall be unsigned 32 bit + integers. Zero is not permitted. + + +Defining Cryptosystems Using Key Derivation + + Kerberos requires that the ciphertext component of EncryptedData be + tamper-resistant as well as confidential. This implies encryption + and integrity functions, which must each use their own separate keys. + So, for each key usage, two keys must be generated, one for + encryption (Ke), and one for integrity (Ki): + + Ke = DK(protocol key, key usage | 0xAA) + Ki = DK(protocol key, key usage | 0x55) + + where the key usage is represented as a 32 bit integer in network + byte order. The ciphertest must be generated from the plaintext as + follows: + + ciphertext = E(Ke, confounder | length | plaintext | padding) | + H(Ki, confounder | length | plaintext | padding) + + The confounder and padding are specific to the encryption algorithm + E. + + When generating a checksum only, there is no need for a confounder or + padding. Again, a new key (Kc) must be used. Checksums must be + generated from the plaintext as follows: + + Kc = DK(protocol key, key usage | 0x99) + + MAC = H(Kc, length | plaintext) + + Note that each enctype is described by an encryption algorithm E and + a keyed hash algorithm H, and each checksum type is described by a + keyed hash algorithm H. HMAC, with an appropriate hash, is + recommended for use as H. + + +Security Considerations + + This entire document addresses shortcomings in the use of + cryptographic keys in Kerberos V5. + + + + +Horowitz [Page 3] + +Internet Draft Key Derivation for Kerberos V5 November, 1996 + + +Acknowledgements + + I would like to thank Uri Blumenthal, Sam Hartman, and Bill + Sommerfeld for their contributions to this document. + + +References + + [Horowitz96] Horowitz, M., "Key Derivation for Authentication, + Integrity, and Privacy", draft-horowitz-key-derivation-00.txt, + November 1996. [RFC1510] Kohl, J. and Neuman, C., "The Kerberos + Network Authentication Service (V5)", RFC 1510, September 1993. + + +Author's Address + + Marc Horowitz + Cygnus Solutions + 955 Massachusetts Avenue + Cambridge, MA 02139 + + Phone: +1 617 354 7688 + Email: marc@cygnus.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Horowitz [Page 4] + diff --git a/doc/draft-ietf-cat-kerb5gss-07.txt b/doc/draft-ietf-cat-kerb5gss-07.txt new file mode 100644 index 000000000..daac4f0b3 --- /dev/null +++ b/doc/draft-ietf-cat-kerb5gss-07.txt @@ -0,0 +1,61 @@ + + +A new Request for Comments is now available in online RFC libraries. + + + RFC 1964: + + Title: The Kerberos Version 5 GSS-API Mechanism + Author: J. Linn + Date: June 1996 + Mailbox: John.Linn@ov.com + Pages: 20 + Characters: 47,413 + Updates/Obsoletes: none + + URL: ftp://ds.internic.net/rfc/rfc1964.txt + + +This specification defines protocols, procedures, and conventions to +be employed by peers implementing the Generic Security Service +Application Program Interface (as specified in RFCs 1508 and 1509) +when using Kerberos Version 5 technology (as specified in RFC 1510). +This RFC is the product of the Common Authentication Technology +Working Group of the IETF. + +This now a Proposed Standard Protocol. + +This document specifies an Internet standards track protocol for the +Internet community, and requests discussion and suggestions for +improvements. Please refer to the current edition of the "Internet +Official Protocol Standards" (STD 1) for the standardization state and +status of this protocol. Distribution of this memo is unlimited. + +This announcement is sent to the IETF list and the RFC-DIST list. +Requests to be added to or deleted from the IETF distribution list +should be sent to IETF-REQUEST@CNRI.RESTON.VA.US. Requests to be +added to or deleted from the RFC-DIST distribution list should +be sent to RFC-DIST-REQUEST@ISI.EDU. + +Details on obtaining RFCs via FTP or EMAIL may be obtained by sending +an EMAIL message to rfc-info@ISI.EDU with the message body +help: ways_to_get_rfcs. For example: + + To: rfc-info@ISI.EDU + Subject: getting rfcs + + help: ways_to_get_rfcs + +Requests for special distribution should be addressed to either the +author of the RFC in question, or to admin@DS.INTERNIC.NET. Unless +specifically noted otherwise on the RFC itself, all RFCs are for +unlimited distribution. + +Submissions for Requests for Comments should be sent to +RFC-EDITOR@ISI.EDU. Please consult RFC 1543, Instructions to RFC +Authors, for further information. + + +Joyce K. Reynolds +USC/Information Sciences Institute + diff --git a/doc/draft-ietf-cat-kerberos-err-msg-00.txt b/doc/draft-ietf-cat-kerberos-err-msg-00.txt new file mode 100644 index 000000000..c5e4d05e7 --- /dev/null +++ b/doc/draft-ietf-cat-kerberos-err-msg-00.txt @@ -0,0 +1,252 @@ + +INTERNET-DRAFT Ari Medvinsky +draft-ietf-cat-kerberos-err-msg-00.txt Matt Hur +Updates: RFC 1510 Dominique Brezinski +expires September 30, 1997 CyberSafe Corporation + Gene Tsudik + Brian Tung + ISI + +Integrity Protection for the Kerberos Error Message + +0. Status Of this Memo + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its + areas, and its working groups. Note that other groups may also + distribute working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six + months and may be updated, replaced, or obsoleted by other + documents at any time. It is inappropriate to use Internet-Drafts + as reference material or to cite them other than as "work in + progress." + + To learn the current status of any Internet-Draft, please check + the "1id-abstracts.txt" listing contained in the Internet-Drafts + Shadow Directories on ds.internic.net (US East Coast), + nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or + munnari.oz.au (Pacific Rim). + + The distribution of this memo is unlimited. It is filed as + draft-ietf-cat-kerberos-pk-init-03.txt, and expires June xx, 1997. + Please send comments to the authors. + +1. Abstract + + The Kerberos error message, as defined in RFC 1510, is transmitted + to the client without any integrity assurance. Therefore, the + client has no means to distinguish between a valid error message + sent from the KDC and one sent by an attacker. This draft describes + a method for assuring the integrity of Kerberos error messages, and + proposes a consistent format for the e-data field in the KRB_ERROR + message. This e-data format enables the storage of cryptographic + checksums by providing an extensible mechanism for specifying e-data + types. + + +2. Motivation + + In the Kerberos protocol [1], if an error occurs for AS_REQ, + TGS_REQ, or AP_REQ, a clear text error message is returned to the + client. An attacker may exploit this vulnerability by sending a + false error message as a reply to any of the above requests. For + example, an attacker may send the KDC_ERR_KEY_EXPIRED error message + in order to force a user to change their password in hope that the + new key will not be as strong as the current key, and thus, easier + to break. + + Since false error messages may be utilized by an attacker, a + Kerberos client should have a means for determining how much trust + to place in a given error message. The rest of this draft + describes a method for assuring the integrity of Kerberos error + messages. + + +3. Approach + + We propose taking a cryptographic checksum over the entire KRB-ERROR + message. This checksum would be returned as part of the error + message and would enable the client to verify the integrity of the + error message. For interoperability reasons, no new fields are + added to the KRB-ERROR message. Instead, the e-data field (see + figure 1) is utilized to carry the cryptographic checksum. + + +3.1 Cryptographic checksums in error messages for AS_REQ, + TGS_REQ & AP_REQ + + If an error occurs for the AS request, the only key that is + available to the KDC is the shared secret (the key derived from the + clients password) registered in the KDCs database. The KDC will + use this key to sign the error message, if and only if, the client + already proved knowledge of the shared secret in the AS request + (e.g. via PA-ENC-TIMESTAMP in preauth data). This policy is needed + to prevent an attacker from getting the KDC to send a signed error + message and then launching an off-line attack in order to obtain a + key of a given principal. + + If an error occurs for a TGS or an AP request, the server will use + the session key sealed in the clients ticket granting ticket to + compute the checksum over the error message. If the checksum could + not be computed (e.g. error while decrypting the ticket) the error + message is returned to the client without the checksum. The client + then has the option to treat unprotected error messages differently. + + + KRB-ERROR ::= [APPLICATION 30] SEQUENCE { + pvno [0] integer, + msg-type [1] integer, + ctime [2] KerberosTime OPTIONAL, + cusec [3] INTEGER OPTIONAL, + stime [4] KerberosTime, + susec [5] INTEGER, + error-code [6] INTEGER, + crealm [7] Realm OPTIONAL, + cname [8] PrincipalName OPTIONAL, + realm [9] Realm, --Correct realm + sname [10] PrincipalName, --Correct name + e-text [11] GeneralString OPTIONAL, + e-data [12] OCTET STRING OPTIONAL + } + Figure 1 + + +3.2 Format of the e-data field + + We propose to place the cryptographic checksum in the e-data field. + First, we review the format of the e-data field, as specified in + RFC 1510. The format of e-data is specified only in two cases [2]. + "If the error code is KDC_ERR_PREAUTH_REQUIRED, then the e-data + field will contain an encoding of a sequence of padata fields": + + METHOD-DATA ::= SEQUENCE of PA-DATA + PA-DATA ::= SEQUENCE { + padata-type [1] INTEGER, + padata-value [2] OCTET STRING + } + + The second case deals with the KRB_AP_ERR_METHOD error code. The + e-data field will contain an encoding of the following sequence: + + METHOD-DATA ::= SEQUENCE { + method-type [0] INTEGER, + method-data [1] OCTET STRING OPTIONAL + } + + method-type indicates the required alternate authentication method. + + It should be noted that, in the case of KRB_AP_ERR_METHOD, a signed + checksum is not returned as part of the error message, since the + error code indicates that the Kerberos credentials provided in the + AP_REQ message are unacceptable. + + We propose that the e-data field have the following format for all + error-codes (except KRB_AP_ERR_METHOD): + + E-DATA ::= SEQUENCE { + data-type [1] INTEGER, + data-value [2] OCTET STRING, + } + + The data-type field specifies the type of information that is + carried in the data-value field. Thus, to send a cryptographic + checksum back to the client, the data-type is set to CHECKSUM, the + data-value is set to the ASN.1 encoding of the following sequence: + + Checksum ::= SEQUENCE { + cksumtype [0] INTEGER, + checksum [1] OCTET STRING + } + + +3.3 Computing the checksum + + After the error message is filled out, the error structure is + converted into ASN.1 representation. A cryptographic checksum is + then taken over the encoded error message; the result is placed in + the error message structure, as the last item in the e-data field. + To send the error message, ASN.1 encoding is again performed over + the error message, which now includes the cryptographic checksum. + + +3.4 Verifying the integrity of the error message + + In addition to verifying the cryptographic checksum for the error + message, the client must verify that the error message is bound to + its request. This is done by comparing the ctime field in the + error message to its counterpart in the request message. + + +4. E-DATA types + + Since the e-data types must not conflict with preauthentication data + types, we propose that the preauthentication data types in the range + of 2048 and above be reserved for use as e-data types. + + We define the following e-data type in support of integrity checking + for the Kerberos error message: + + CHECKSUM = 2048 -- the keyed checksum described above + + +5. Discussion + + +5.1 e-data types + + The extension for Kerberos error messages, as outlined above, is + extensible to allow for definition of other error data types. + We propose that the following e-data types be reserved: + + KDCTIME = 2049 + The error data would consist of the KDCs time in KerberosTime. + This data would be used by the client to adjust for clock skew. + + REDIRECT = 2050 + The error data would consist of a hostname. The hostname would + indicate the authoritative KDC from which to obtain a TGT. + + +5.2 e-data types vs. error code specific data formats + + Since RFC 1510 does not define an error data type, the data format + must be explicitly specified for each error code. This draft has + proposed an extension to RFC 1510 that would introduce the concept + of error data types. This would allow for a manageable set of data + types to be used for any error message. The authors assume that + the introduction of this e-data structure will not break any + existing Kerberos implementations. + + +6. Bibliography + + [1] J. Kohl, C. Neuman. The Kerberos Network Authentication + Service (V5). Request for Comments: 1510 + [2] J. Kohl, C. Neuman. The Kerberos Network Authentication + Service (V5). Request for Comments: 1510 p.67 + + +7. Authors + + Ari Medvinsky + Matthew Hur + Dominique Brezinski + + CyberSafe Corporation + 1605 NW Sammamish Road + Suite 310 + Issaquah, WA 98027-5378 + Phone: (206) 391-6000 + Fax: (206) 391-0508 + http:/www.cybersafe.com + + + Brian Tung + Gene Tsudik + + USC Information Sciences Institute + 4676 Admiralty Way Suite 1001 + Marina del Rey CA 90292-6695 + Phone: (310) 822-1511 + diff --git a/doc/draft-ietf-cat-kerberos-passwords-02.txt b/doc/draft-ietf-cat-kerberos-passwords-02.txt new file mode 100644 index 000000000..aaa618400 --- /dev/null +++ b/doc/draft-ietf-cat-kerberos-passwords-02.txt @@ -0,0 +1,16 @@ + +This Internet-Draft has been deleted. Unrevised documents placed in the +Internet-Drafts directories have a maximum life of six months. After +that time, they are deleted. This Internet-Draft was not published as +an RFC. + +Internet-Drafts are not an archival document series, and expired +drafts, such as this one, are not available; please do not ask for +copies... they are not available. The Secretariat does not have +information as to future plans of the authors or working groups WRT the +deleted Internet-Draft. + + +To learn the current status of any Internet-Draft, please check the +``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow +Directories. diff --git a/doc/draft-ietf-cat-kerberos-pk-cross-01.txt b/doc/draft-ietf-cat-kerberos-pk-cross-01.txt new file mode 100644 index 000000000..4b193c573 --- /dev/null +++ b/doc/draft-ietf-cat-kerberos-pk-cross-01.txt @@ -0,0 +1,282 @@ +INTERNET-DRAFT Brian Tung +draft-ietf-cat-kerberos-pk-cross-01.txt Tatyana Ryutov +Updates: RFC 1510 Clifford Neuman +expires September 30, 1997 Gene Tsudik + ISI + Bill Sommerfeld + Hewlett-Packard + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + + + Public Key Cryptography for Cross-Realm Authentication in Kerberos + + +0. Status Of this Memo + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its + areas, and its working groups. Note that other groups may also + distribute working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six + months and may be updated, replaced, or obsoleted by other + documents at any time. It is inappropriate to use Internet-Drafts + as reference material or to cite them other than as ``work in + progress.'' + + To learn the current status of any Internet-Draft, please check + the ``1id-abstracts.txt'' listing contained in the Internet-Drafts + Shadow Directories on ds.internic.net (US East Coast), + nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or + munnari.oz.au (Pacific Rim). + + The distribution of this memo is unlimited. It is filed as + draft-ietf-cat-kerberos-pk-cross-01.txt, and expires September 30, + 1997. Please send comments to the authors. + + +1. Abstract + + This document defines extensions to the Kerberos protocol + specification (RFC 1510, "The Kerberos Network Authentication + Service (V5)", September 1993) to provide a method for using + public key cryptography during cross-realm authentication. The + methods defined here specify the way in which message exchanges + are to be used to transport cross-realm secret keys protected by + encryption under public keys certified as belonging to KDCs. + + +2. Motivation + + The advantages provided by public key cryptography--ease of + recoverability in the event of a compromise, the possibility of + an autonomous authentication infrastructure, to name a few--have + produced a demand for use by Kerberos authentication protocol. A + draft describing the use of public key cryptography in the initial + authentication exchange in Kerberos has already been submitted. + This draft describes its use in cross-realm authentication. + + The principal advantage provided by public key cryptography in + cross-realm authentication lies in the ability to leverage the + existing public key infrastructure. It frees the Kerberos realm + administrator from having to maintain separate keys for each other + realm with which it wishes to exchange authentication information, + or to utilize a hierarchical arrangement, which may pose problems + of trust. + + Even with the multi-hop cross-realm authentication, there must be + some way to locate the path by which separate realms are to be + transited. The current method, which makes use of the DNS-like + realm names typical to Kerberos, requires trust of the intermediate + KDCs. + + The methods described in this draft allow a realm to specify, at + the time of authentication, which certification paths it will + trust. A shared key for cross-realm authentication can be + established, for a period of time. Furthermore, these methods are + transparent to the client, so that only the KDC's need to be + modified to use them. + + It is not necessary to implement the changes described in the + "Public Key Cryptography for Initial Authentication" draft to make + use of the changes in this draft. We solicit comments about the + interaction between the two protocol changes, but as of this + writing, the authors do not perceive any obstacles to using both. + + +3. Protocol Amendments + + We assume that the user has already obtained a TGT. To perform + cross-realm authentication, the user sends a request to the local + KDC as per RFC 1510. If the two realms share a secret key, then + cross-realm authentication proceeds as usual. Otherwise, the + local KDC may attempt to establish a shared key with the remote + KDC using public key cryptography, and exchange this key through + the cross-realm ticket granting ticket. + + We will consider the specific channel on which the message + exchanges take place in Section 5 below. + + +3.1. Changes to the Cross-Realm Ticket Granting Ticket + + In order to avoid the need for changes to the "installed base" of + Kerberos application clients and servers, the only protocol change + is to the way in which cross-realm ticket granting tickets (TGTs) + are encrypted; as these tickets are opaque to clients and servers, + the only change visible to them will be the increased size of the + tickets. + + Cross-realm TGTs are granted by a local KDC to authenticate a user + to a remote KDC's ticket granting service. In standard Kerberos, + they are encrypted using a shared secret key manually configured + into each KDC. + + In order to incorporate public key cryptography, we define a new + encryption type, "ENCTYPE_PK_CROSS". Operationally, this encryption + type transforms an OCTET STRING of plaintext (normally an EncTktPart) + into the following SEQUENCE: + + PKCrossOutput ::= SEQUENCE { + certificate [0] OCTET STRING OPTIONAL, + -- public key certificate + -- of local KDC + encSharedKey [1] EncryptedData, + -- of type EncryptionKey + -- containing random symmetric key + -- encrypted using public key + -- of remote KDC + sigSharedKey [2] Signature, + -- of encSharedKey + -- using signature key + -- of local KDC + pkEncData [3] EncryptedData, + -- (normally) of type EncTktPart + -- encrypted using encryption key + -- found in encSharedKey + } + + PKCROSS operates as follows: when a client submits a request for + cross-realm authentication, the local KDC checks to see if it has + a long-term shared key established for that realm. If so, it uses + this key as per RFC 1510. + + If not, it sends a request for information to the remote KDC. The + content of this message is immaterial, as it does not need to be + processed by the remote KDC; for the sake of consistency, we define + it as follows: + + RemoteRequest ::= [APPLICATION 41] SEQUENCE { + nonce [0] INTEGER + } + + The remote KDC replies with a list of all trusted certifiers and + all its (the remote KDC's) certificates. We note that this response + is universal and does not depend on which KDC makes the request: + + RemoteReply ::= [APPLICATION 42] SEQUENCE { + trustedCertifiers [0] SEQUENCE OF PrincipalName, + certificates[1] SEQUENCE OF Certificate, + encTypeToUse [1] SEQUENCE OF INTEGER + -- encryption types usable + -- for encrypting pkEncData + } + + Certificate ::= SEQUENCE { + CertType [0] INTEGER, + -- type of certificate + -- 1 = X.509v3 (DER encoding) + -- 2 = PGP (per PGP draft) + CertData [1] OCTET STRING + -- actual certificate + -- type determined by CertType + } -- from pk-init draft + + Upon receiving this reply, the local KDC determines whether it has + a certificate the remote KDC trusts, and whether the remote KDC has + a certificate the local KDC trusts. If so, it issues a ticket + encrypted using the ENCTYPE_PK_CROSS encryption type defined above. + + +3.2. Profile Caches + + We observe that using PKCROSS as specified above requires two + private key operations: a signature generation by the local KDC and + a decryption by the remote KDC. This cost can be reduced in the + long term by judicious caching of the encSharedKey and the + sigSharedKey. + + Let us define a "profile" as the encSharedKey and sigSharedKey, in + conjunction with the associated remote realm name and decrypted + shared key (the key encrypted in the encSharedKey). + + To optimize these interactions, each KDC maintains two caches, one + for outbound profiles and one for inbound profiles. When generating + an outbound TGT for another realm, the local KDC first checks to see + if the corresponding entry exists in the outbound profile cache; if + so, it uses its contents to form the first three fields of the + PKCrossOutput; the shared key is used to encrypt the data for the + fourth field. If not, the components are generated fresh and stored + in the outbound profile cache. + + Upon receipt of the TGT, the remote realm checks its inbound profile + cache for the corresponding entry. If it exists, then it uses the + contents of the entry to decrypt the data encrypted in the pkEncData. + If not, then it goes through the full process of verifying and + extracting the shared key; if this is successful, then a new entry + is created in the inbound profile cache. + + The inbound profile cache should support multiple entries per realm, + in the event that the initiating realm is replicated. + + +4. Finding Realms Supporting PKCROSS + + If either the local realm or the destination realm does not support + PKCROSS, or both do not, the mechanism specified in Section 3 can + still be used in obtaining the desired remote TGT. + + In the reference Kerberos implementations, the default behavior is + to traverse a path up and down the realm name hierarchy, if the + two realms do not share a key. There is, however, the possibility + of using cross links--i.e., keys shared between two realms that + are non-contiguous in the realm name hierarchy--to shorten the + path, both to minimize delay and the number of intermediate realms + that need to be trusted. + + PKCROSS can be used as a way to provide cross-links even in the + absence of shared keys. If the client is aware that one or two + intermediate realms support PKCROSS, then a combination of + PKCROSS and conventional cross-realm authentication can be used + to reach the final destination realm. + + We solicit discussion on the best methods for clients and KDCs to + determine or advertise support for PKCROSS. + + +5. Message Ports + + We have not specified the port on which KDCs supporting PKCROSS + should listen to receive the request for information messages noted + above. We solicit discussion on which port should be used. We + propose to use the standard Kerberos ports (well-known 88 or 750), + but another possibility is to use a completely different port. + + We also solicit discussion on what other approaches can be taken to + obtain the information in the RemoteReply (e.g., secure DNS or some + other repository). + + +6. Expiration Date + + This Internet-Draft will expire on September 30, 1997. + + +7. Authors' Addresses + + Brian Tung + Tatyana Ryutov + Clifford Neuman + Gene Tsudik + USC/Information Sciences Institute + 4676 Admiralty Way Suite 1001 + Marina del Rey, CA 90292-6695 + Phone: +1 310 822 1511 + E-Mail: {brian, tryutov, bcn, gts}@isi.edu + + Bill Sommerfeld + Hewlett Packard + 300 Apollo Drive + Chelmsford MA 01824 + Phone: +1 508 436 4352 + E-Mail: sommerfeld@apollo.hp.com + + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + 1605 NW Sammamish Road Suite 310 + Issaquah WA 98027-5378 + Phone: +1 206 391 6000 + E-mail: {ari.medvinsky, matt.hur}@cybersafe.com diff --git a/doc/draft-ietf-cat-kerberos-pk-init-03.txt b/doc/draft-ietf-cat-kerberos-pk-init-03.txt new file mode 100644 index 000000000..d91c087dd --- /dev/null +++ b/doc/draft-ietf-cat-kerberos-pk-init-03.txt @@ -0,0 +1,589 @@ + +INTERNET-DRAFT Clifford Neuman +draft-ietf-cat-kerberos-pk-init-03.txt Brian Tung +Updates: RFC 1510 ISI +expires September 30, 1997 John Wray + Digital Equipment Corporation + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + Jonathan Trostle + Novell + + + Public Key Cryptography for Initial Authentication in Kerberos + + +0. Status Of this Memo + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its + areas, and its working groups. Note that other groups may also + distribute working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six + months and may be updated, replaced, or obsoleted by other + documents at any time. It is inappropriate to use Internet-Drafts + as reference material or to cite them other than as "work in + progress." + + To learn the current status of any Internet-Draft, please check + the "1id-abstracts.txt" listing contained in the Internet-Drafts + Shadow Directories on ds.internic.net (US East Coast), + nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or + munnari.oz.au (Pacific Rim). + + The distribution of this memo is unlimited. It is filed as + draft-ietf-cat-kerberos-pk-init-03.txt, and expires September 30, + 1997. Please send comments to the authors. + + +1. Abstract + + This document defines extensions (PKINIT) to the Kerberos protocol + specification (RFC 1510 [1]) to provide a method for using public + key cryptography during initial authentication. The methods + defined specify the ways in which preauthentication data fields and + error data fields in Kerberos messages are to be used to transport + public key data. + + +2. Introduction + + The popularity of public key cryptography has produced a desire for + its support in Kerberos [2]. The advantages provided by public key + cryptography include simplified key management (from the Kerberos + perspective) and the ability to leverage existing and developing + public key certification infrastructures. + + Public key cryptography can be integrated into Kerberos in a number + of ways. One is to to associate a key pair with each realm, which + can then be used to facilitate cross-realm authentication; this is + the topic of another draft proposal. Another way is to allow users + with public key certificates to use them in initial authentication. + This is the concern of the current document. + + One of the guiding principles in the design of PKINIT is that + changes should be as minimal as possible. As a result, the basic + mechanism of PKINIT is as follows: The user sends a request to the + KDC as before, except that if that user is to use public key + cryptography in the initial authentication step, his certificate + accompanies the initial request, in the preauthentication fields. + + Upon receipt of this request, the KDC verifies the certificate and + issues a ticket granting ticket (TGT) as before, except that instead + of being encrypted in the user's long-term key (which is derived + from a password), it is encrypted in a randomly-generated key. This + random key is in turn encrypted using the public key certificate + that came with the request and signed using the KDC's signature key, + and accompanies the reply, in the preauthentication fields. + + PKINIT also allows for users with only digital signature keys to + authenticate using those keys, and for users to store and retrieve + private keys on the KDC. + + The PKINIT specification may also be used for direct peer to peer + authentication without contacting a central KDC. This application + of PKINIT is described in PKTAPP [4] and is based on concepts + introduced in [5, 6]. For direct client-to-server authentication, + the client uses PKINIT to authenticate to the end server (instead + of a central KDC), which then issues a ticket for itself. This + approach has an advantage over SSL [7] in that the server does not + need to save state (cache session keys). Furthermore, an + additional benefit is that Kerberos tickets can facilitate + delegation (see [8]). + + +3. Proposed Extensions + + This section describes extensions to RFC 1510 for supporting the + use of public key cryptography in the initial request for a ticket + granting ticket (TGT). + + In summary, the following changes to RFC 1510 are proposed: + + --> Users may authenticate using either a public key pair or a + conventional (symmetric) key. If public key cryptography is + used, public key data is transported in preauthentication + data fields to help establish identity. + --> Users may store private keys on the KDC for retrieval during + Kerberos initial authentication. + + This proposal addresses two ways that users may use public key + cryptography for initial authentication. Users may present public + key certificates, or they may generate their own session key, + signed by their digital signature key. In either case, the end + result is that the user obtains an ordinary TGT that may be used for + subsequent authentication, with such authentication using only + conventional cryptography. + + Section 3.1 provides definitions to help specify message formats. + Section 3.2 and 3.3 describe the extensions for the two initial + authentication methods. Section 3.3 describes a way for the user to + store and retrieve his private key on the KDC. + + +3.1. Definitions + + Hash and encryption types will be specified using ENCTYPE tags; we + propose the addition of the following types: + + #define ENCTYPE_SIGN_DSA_GENERATE 0x0011 + #define ENCTYPE_SIGN_DSA_VERIFY 0x0012 + #define ENCTYPE_ENCRYPT_RSA_PRIV 0x0021 + #define ENCTYPE_ENCRYPT_RSA_PUB 0x0022 + + allowing further signature types to be defined in the range 0x0011 + through 0x001f, and further encryption types to be defined in the + range 0x0021 through 0x002f. + + The extensions involve new preauthentication fields. The + preauthentication data types are in the range 17 through 21. + These values are also specified along with their corresponding + ASN.1 definition. + + #define PA-PK-AS-REQ 17 + #define PA-PK-AS-REP 18 + #define PA-PK-AS-SIGN 19 + #define PA-PK-KEY-REQ 20 + #define PA-PK-KEY-REP 21 + + The extensions also involve new error types. The new error types + are in the range 227 through 229. They are: + + #define KDC_ERROR_CLIENT_NOT_TRUSTED 227 + #define KDC_ERROR_KDC_NOT_TRUSTED 228 + #define KDC_ERROR_INVALID_SIG 229 + + In the exposition below, we use the following terms: encryption key, + decryption key, signature key, verification key. It should be + understood that encryption and verification keys are essentially + public keys, and decryption and signature keys are essentially + private keys. The fact that they are logically distinct does + not preclude the assignment of bitwise identical keys. + + +3.2. Standard Public Key Authentication + + Implementation of the changes in this section is REQUIRED for + compliance with pk-init. + + It is assumed that all public keys are signed by some certification + authority (CA). The initial authentication request is sent as per + RFC 1510, except that a preauthentication field containing data + signed by the user's signature key accompanies the request: + + PA-PK-AS-REQ ::- SEQUENCE { + -- PA TYPE 17 + signedPKAuth [0] SignedPKAuthenticator, + userCert [1] SEQUENCE OF Certificate OPTIONAL, + -- the user's certificate + -- optionally followed by that + -- certificate's certifier chain + trustedCertifiers [2] SEQUENCE OF PrincipalName OPTIONAL + -- CAs that the client trusts + } + + SignedPKAuthenticator ::= SEQUENCE { + pkAuth [0] PKAuthenticator, + pkAuthSig [1] Signature, + -- of pkAuth + -- using user's signature key + } + + PKAuthenticator ::= SEQUENCE { + cusec [0] INTEGER, + -- for replay prevention + ctime [1] KerberosTime, + -- for replay prevention + nonce [2] INTEGER, + -- binds response to this request + kdcName [3] PrincipalName, + clientPubValue [4] SubjectPublicKeyInfo OPTIONAL, + -- for Diffie-Hellman algorithm + } + + Signature ::= SEQUENCE { + signedHash [0] EncryptedData + -- of type Checksum + -- encrypted under signature key + } + + Checksum ::= SEQUENCE { + cksumtype [0] INTEGER, + checksum [1] OCTET STRING + } -- as specified by RFC 1510 + + SubjectPublicKeyInfo ::= SEQUENCE { + algorithm [0] algorithmIdentifier, + subjectPublicKey [1] BIT STRING + } -- as specified by the X.509 recommendation [9] + + Certificate ::= SEQUENCE { + CertType [0] INTEGER, + -- type of certificate + -- 1 = X.509v3 (DER encoding) + -- 2 = PGP (per PGP draft) + CertData [1] OCTET STRING + -- actual certificate + -- type determined by CertType + } + + Note: If the signature uses RSA keys, then it is to be performed + as per PKCS #1. + + The PKAuthenticator carries information to foil replay attacks, + to bind the request and response, and to optionally pass the + client's Diffie-Hellman public value (i.e. for using DSA in + combination with Diffie-Hellman). The PKAuthenticator is signed + with the private key corresponding to the public key in the + certificate found in userCert (or cached by the KDC). + + In the PKAuthenticator, the client may specify the KDC name in one + of two ways: 1) a Kerberos principal name, or 2) the name in the + KDC's certificate (e.g., an X.500 name, or a PGP name). Note that + case #1 requires that the certificate name and the Kerberos principal + name be bound together (e.g., via an X.509v3 extension). + + The userCert field is a sequence of certificates, the first of which + must be the user's public key certificate. Any subsequent + certificates will be certificates of the certifiers of the user's + certificate. These cerificates may be used by the KDC to verify the + user's public key. This field is empty if the KDC already has the + user's certifcate. + + The trustedCertifiers field contains a list of certification + authorities trusted by the client, in the case that the client does + not possess the KDC's public key certificate. + + Upon receipt of the AS_REQ with PA-PK-AS-REQ pre-authentication + type, the KDC attempts to verify the user's certificate chain + (userCert), if one is provided in the request. This is done by + verifying the certification path against the KDC's policy of + legitimate certifiers. This may be based on a certification + hierarchy, or it may be simply a list of recognized certifiers in a + system like PGP. If the certification path does not match one of + the KDC's trusted certifiers, the KDC sends back an error message of + type KDC_ERROR_CLIENT_NOT_TRUSTED, and it includes in the error data + field a list of its own trusted certifiers, upon which the client + resends the request. + + If trustedCertifiers is provided in the PA-PK-AS-REQ, the KDC + verifies that it has a certificate issued by one of the certifiers + trusted by the client. If it does not have a suitable certificate, + the KDC returns an error message of type KDC_ERROR_KDC_NOT_TRUSTED + to the client. + + If a trust relationship exists, the KDC then verifies the client's + signature on PKAuthenticator. If that fails, the KDC returns an + error message of type KDC_ERROR_INVALID_SIG. Otherwise, the KDC + uses the timestamp in the PKAuthenticator to assure that the request + is not a replay. The KDC also verifies that its name is specified + in PKAuthenticator. + + Assuming no errors, the KDC replies as per RFC 1510, except that it + encrypts the reply not with the user's key, but with a random key + generated only for this particular response. This random key + is sealed in the preauthentication field: + + PA-PK-AS-REP ::= SEQUENCE { + -- PA TYPE 18 + kdcCert [0] SEQUENCE OF Certificate OPTIONAL, + -- the KDC's certificate + -- optionally followed by that + -- certificate's certifier chain + encPaReply [1] EncryptedData, + -- of type PaReply + -- using either the client public + -- key or the Diffie-Hellman key + -- specified by SignedDHPublicValue + signedDHPublicValue [2] SignedDHPublicValue OPTIONAL + } + + + PaReply ::= SEQUENCE { + replyEncKeyPack [0] ReplyEncKeyPack, + replyEncKeyPackSig [1] Signature, + -- of replyEncKeyPack + -- using KDC's signature key + } + + ReplyEncKeyPack ::= SEQUENCE { + replyEncKey [0] EncryptionKey, + -- used to encrypt main reply + nonce [1] INTEGER + -- binds response to the request + -- passed in the PKAuthenticator + } + + SignedDHPublicValue ::= SEQUENCE { + dhPublicValue [0] SubjectPublicKeyInfo, + dhPublicValueSig [1] Signature + -- of dhPublicValue + -- using KDC's signature key + } + + The kdcCert field is a sequence of certificates, the first of which + must have as its root certifier one of the certifiers sent to the + KDC in the PA-PK-AS-REQ. Any subsequent certificates will be + certificates of the certifiers of the KDC's certificate. These + cerificates may be used by the client to verify the KDC's public + key. This field is empty if the client did not send to the KDC a + list of trusted certifiers (the trustedCertifiers field was empty). + + Since each certifier in the certification path of a user's + certificate is essentially a separate realm, the name of each + certifier shall be added to the transited field of the ticket. The + format of these realm names shall follow the naming constraints set + forth in RFC 1510 (sections 7.1 and 3.3.3.1). Note that this will + require new nametypes to be defined for PGP certifiers and other + types of realms as they arise. + + The KDC's certificate must bind the public key to a name derivable + from the name of the realm for that KDC. The client then extracts + the random key used to encrypt the main reply. This random key (in + encPaReply) is encrypted with either the client's public key or + with a key derived from the DH values exchanged between the client + and the KDC. + + +3.3. Digital Signature + + Implementation of the changes in this section are OPTIONAL for + compliance with pk-init. + + We offer this option with the warning that it requires the client to + generate a random key; the client may not be able to guarantee the + same level of randomness as the KDC. + + If the user registered a digital signature key with the KDC instead + of an encryption key, then a separate exchange must be used. The + client sends a request for a TGT as usual, except that it (rather + than the KDC) generates the random key that will be used to encrypt + the KDC response. This key is sent to the KDC along with the + request in a preauthentication field: + + PA-PK-AS-SIGN ::= SEQUENCE { + -- PA TYPE 19 + encSignedKeyPack [0] EncryptedData + -- of SignedKeyPack + -- using the KDC's public key + } + + SignedKeyPack ::= SEQUENCE { + signedKey [0] KeyPack, + signedKeyAuth [1] PKAuthenticator, + signedKeySig [2] Signature + -- of signedKey.signedKeyAuth + -- using user's signature key + } + + KeyPack ::= SEQUENCE { + randomKey [0] EncryptionKey, + -- will be used to encrypt reply + nonce [1] INTEGER + } + + where the nonce is copied from the request. + + Upon receipt of the PA-PK-AS-SIGN, the KDC decrypts then verifies + the randomKey. It then replies as per RFC 1510, except that the + reply is encrypted not with a password-derived user key, but with + the randomKey sent in the request. Since the client already knows + this key, there is no need to accompany the reply with an extra + preauthentication field. The transited field of the ticket should + specify the certification path as described in Section 3.2. + + +3.4. Retrieving the Private Key From the KDC + + Implementation of the changes in this section is RECOMMENDED for + compliance with pk-init. + + When the user's private key is not stored local to the user, he may + choose to store the private key (normally encrypted using a + password-derived key) on the KDC. We provide this option to present + the user with an alternative to storing the private key on local + disk at each machine where he expects to authenticate himself using + pk-init. It should be noted that it replaces the added risk of + long-term storage of the private key on possibly many workstations + with the added risk of storing the private key on the KDC in a + form vulnerable to brute-force attack. + + In order to obtain a private key, the client includes a + preauthentication field with the AS-REQ message: + + PA-PK-KEY-REQ ::= SEQUENCE { + -- PA TYPE 20 + patimestamp [0] KerberosTime OPTIONAL, + -- used to address replay attacks. + pausec [1] INTEGER OPTIONAL, + -- used to address replay attacks. + nonce [2] INTEGER, + -- binds the reply to this request + privkeyID [3] SEQUENCE OF KeyID OPTIONAL + -- constructed as a hash of + -- public key corresponding to + -- desired private key + } + + KeyID ::= SEQUENCE { + KeyIdentifier [0] OCTET STRING + } + + The client may request a specific private key by sending the + corresponding ID. If this field is left empty, then all + private keys are returned. + + If all checks out, the KDC responds as described in the above + sections, except that an additional preauthentication field, + containing the user's private key, accompanies the reply: + + PA-PK-KEY-REP ::= SEQUENCE { + -- PA TYPE 21 + nonce [0] INTEGER, + -- binds the reply to the request + KeyData [1] SEQUENCE OF KeyPair + } + + KeyPair ::= SEQUENCE { + privKeyID [0] OCTET STRING, + -- corresponding to encPrivKey + encPrivKey [1] OCTET STRING + } + + +3.4.1. Additional Protection of Retrieved Private Keys + + We solicit discussion on the following proposal: that the client may + optionally include in its request additional data to encrypt the + private key, which is currently only protected by the user's + password. One possibility is that the client might generate a + random string of bits, encrypt it with the public key of the KDC (as + in the SignedKeyPack, but with an ordinary OCTET STRING in place of + an EncryptionKey), and include this with the request. The KDC then + XORs each returned key with this random bit string. (If the bit + string is too short, the KDC could either return an error, or XOR + the returned key with a repetition of the bit string.) + + In order to make this work, additional means of preauthentication + need to be devised in order to prevent attackers from simply + inserting their own bit string. One way to do this is to store + a hash of the password-derived key (the one used to encrypt the + private key). This hash is then used in turn to derive a second + key (called the hash-key); the hash-key is used to encrypt an ASN.1 + structure containing the generated bit string and a nonce value + that binds it to the request. + + Since the KDC possesses the hash, it can generate the hash-key and + verify this (weaker) preauthentication, and yet cannot reproduce + the private key itself, since the hash is a one-way function. + + +4. Logistics and Policy Issues + + We solicit discussion on how clients and KDCs should be configured + in order to determine which of the options described above (if any) + should be used. One possibility is to set the user's database + record to indicate that authentication is to use public key + cryptography; this will not work, however, in the event that the + client needs to know before making the initial request. + +5. Compatibility with One-Time Passcodes + + We solicit discussion on how the protocol changes proposed in this + draft will interact with the proposed use of one-time passcodes + discussed in draft-ietf-cat-kerberos-passwords-00.txt. + + +6. Strength of Cryptographic Schemes + + In light of recent findings on the strength of MD5 and DES, + we solicit discussion on which encryption types to incorporate + into the protocol changes. + + +7. Bibliography + + [1] J. Kohl, C. Neuman. The Kerberos Network Authentication + Service (V5). Request for Comments: 1510 + + [2] B.C. Neuman, Theodore Ts'o. Kerberos: An Authentication Service + for Computer Networks, IEEE Communications, 32(9):33-38. + September 1994. + + [3] A. Medvinsky, M. Hur. Addition of Kerberos Cipher Suites to + Transport Layer Security (TLS). + draft-ietf-tls-kerb-cipher-suites-00.txt + + [4] A. Medvinsky, M. Hur, B. Clifford Neuman. Public Key Utilizing + Tickets for Application Servers (PKTAPP). + draft-ietf-cat-pktapp-00.txt + + [5] M. Sirbu, J. Chuang. Distributed Authentication in Kerberos Using + Public Key Cryptography. Symposium On Network and Distributed System + Security, 1997. + + [6] B. Cox, J.D. Tygar, M. Sirbu. NetBill Security and Transaction + Protocol. In Proceedings of the USENIX Workshop on Electronic Commerce, + July 1995. + + [7] Alan O. Freier, Philip Karlton and Paul C. Kocher. + The SSL Protocol, Version 3.0 - IETF Draft. + + [8] B.C. Neuman, Proxy-Based Authorization and Accounting for + Distributed Systems. In Proceedings of the 13th International + Conference on Distributed Computing Systems, May 1993 + + [9] ITU-T (formerly CCITT) + Information technology - Open Systems Interconnection - + The Directory: Authentication Framework Recommendation X.509 + ISO/IEC 9594-8 + + +8. Acknowledgements + + Some of the ideas on which this proposal is based arose during + discussions over several years between members of the SAAG, the IETF + CAT working group, and the PSRG, regarding integration of Kerberos + and SPX. Some ideas have also been drawn from the DASS system. + These changes are by no means endorsed by these groups. This is an + attempt to revive some of the goals of those groups, and this + proposal approaches those goals primarily from the Kerberos + perspective. Lastly, comments from groups working on similar ideas + in DCE have been invaluable. + + +9. Expiration Date + + This draft expires September 30, 1997. + + +10. Authors + + Clifford Neuman + Brian Tung + USC Information Sciences Institute + 4676 Admiralty Way Suite 1001 + Marina del Rey CA 90292-6695 + Phone: +1 310 822 1511 + E-mail: {bcn, brian}@isi.edu + + John Wray + Digital Equipment Corporation + 550 King Street, LKG2-2/Z7 + Littleton, MA 01460 + Phone: +1 508 486 5210 + E-mail: wray@tuxedo.enet.dec.com + + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + 1605 NW Sammamish Road Suite 310 + Issaquah WA 98027-5378 + Phone: +1 206 391 6000 + E-mail: {ari.medvinsky, matt.hur}@cybersafe.com + + Jonathan Trostle + Novell + E-mail: jonathan.trostle@novell.com diff --git a/doc/rfc1508.txt b/doc/rfc1508.txt new file mode 100644 index 000000000..132b855e0 --- /dev/null +++ b/doc/rfc1508.txt @@ -0,0 +1,2747 @@ + + + + + + +Network Working Group J. Linn +Request for Comments: 1508 Geer Zolot Associates + September 1993 + + + Generic Security Service Application Program Interface + +Status of this Memo + + This RFC specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" for the standardization state and status + of this protocol. Distribution of this memo is unlimited. + +Abstract + + This Generic Security Service Application Program Interface (GSS-API) + definition provides security services to callers in a generic + fashion, supportable with a range of underlying mechanisms and + technologies and hence allowing source-level portability of + applications to different environments. This specification defines + GSS-API services and primitives at a level independent of underlying + mechanism and programming language environment, and is to be + complemented by other, related specifications: + + documents defining specific parameter bindings for particular + language environments + + documents defining token formats, protocols, and procedures to + be implemented in order to realize GSS-API services atop + particular security mechanisms + +Table of Contents + + 1. GSS-API Characteristics and Concepts ....................... 2 + 1.1. GSS-API Constructs ....................................... 5 + 1.1.1. Credentials ........................................... 5 + 1.1.2. Tokens ................................................ 6 + 1.1.3. Security Contexts ..................................... 7 + 1.1.4. Mechanism Types ....................................... 8 + 1.1.5. Naming ................................................ 9 + 1.1.6. Channel Bindings ...................................... 10 + 1.2. GSS-API Features and Issues ............................. 11 + 1.2.1. Status Reporting ...................................... 11 + 1.2.2. Per-Message Security Service Availability ............. 12 + 1.2.3. Per-Message Replay Detection and Sequencing ........... 13 + 1.2.4. Quality of Protection ................................. 15 + + + +Linn [Page 1] + +RFC 1508 Generic Security Interface September 1993 + + + 2. Interface Descriptions ..................................... 15 + 2.1. Credential management calls ............................. 17 + 2.1.1. GSS_Acquire_cred call ................................. 17 + 2.1.2. GSS_Release_cred call ................................. 19 + 2.1.3. GSS_Inquire_cred call ................................. 20 + 2.2. Context-level calls ..................................... 21 + 2.2.1. GSS_Init_sec_context call ............................. 21 + 2.2.2. GSS_Accept_sec_context call ........................... 26 + 2.2.3. GSS_Delete_sec_context call ........................... 29 + 2.2.4. GSS_Process_context_token call ........................ 30 + 2.2.5. GSS_Context_time call ................................. 31 + 2.3. Per-message calls ....................................... 32 + 2.3.1. GSS_Sign call ......................................... 32 + 2.3.2. GSS_Verify call ....................................... 33 + 2.3.3. GSS_Seal call ......................................... 35 + 2.3.4. GSS_Unseal call ....................................... 36 + 2.4. Support calls ........................................... 37 + 2.4.1. GSS_Display_status call ............................... 37 + 2.4.2. GSS_Indicate_mechs call ............................... 38 + 2.4.3. GSS_Compare_name call ................................. 38 + 2.4.4. GSS_Display_name call ................................. 39 + 2.4.5. GSS_Import_name call .................................. 40 + 2.4.6. GSS_Release_name call ................................. 41 + 2.4.7. GSS_Release_buffer call ............................... 41 + 2.4.8. GSS_Release_oid_set call .............................. 42 + 3. Mechanism-Specific Example Scenarios ....................... 42 + 3.1. Kerberos V5, single-TGT ................................. 43 + 3.2. Kerberos V5, double-TGT ................................. 43 + 3.3. X.509 Authentication Framework .......................... 44 + 4. Related Activities ......................................... 45 + 5. Acknowledgments ............................................ 46 + 6. Security Considerations .................................... 46 + 7. Author's Address ........................................... 46 + Appendix A .................................................... 47 + Appendix B .................................................... 48 + Appendix C .................................................... 49 + +1. GSS-API Characteristics and Concepts + + The operational paradigm in which GSS-API operates is as follows. A + typical GSS-API caller is itself a communications protocol, calling + on GSS-API in order to protect its communications with + authentication, integrity, and/or confidentiality security services. + A GSS-API caller accepts tokens provided to it by its local GSS-API + implementation and transfers the tokens to a peer on a remote system; + that peer passes the received tokens to its local GSS-API + implementation for processing. The security services available + through GSS-API in this fashion are implementable (and have been + + + +Linn [Page 2] + +RFC 1508 Generic Security Interface September 1993 + + + implemented) over a range of underlying mechanisms based on secret- + key and public-key cryptographic technologies. + + The GSS-API separates the operations of initializing a security + context between peers, achieving peer entity authentication (This + security service definition, and other definitions used in this + document, corresponds to that provided in International Standard ISO + 7498-2-1988(E), Security Architecture.) (GSS_Init_sec_context() and + GSS_Accept_sec_context() calls), from the operations of providing + per-message data origin authentication and data integrity protection + (GSS_Sign() and GSS_Verify() calls) for messages subsequently + transferred in conjunction with that context. Per-message GSS_Seal() + and GSS_Unseal() calls provide the data origin authentication and + data integrity services which GSS_Sign() and GSS_Verify() offer, and + also support selection of confidentiality services as a caller + option. Additional calls provide supportive functions to the GSS- + API's users. + + The following paragraphs provide an example illustrating the + dataflows involved in use of the GSS-API by a client and server in a + mechanism-independent fashion, establishing a security context and + transferring a protected message. The example assumes that credential + acquisition has already been completed. The example assumes that the + underlying authentication technology is capable of authenticating a + client to a server using elements carried within a single token, and + of authenticating the server to the client (mutual authentication) + with a single returned token; this assumption holds for presently- + documented CAT mechanisms but is not necessarily true for other + cryptographic technologies and associated protocols. + + The client calls GSS_Init_sec_context() to establish a security + context to the server identified by targ_name, and elects to set the + mutual_req_flag so that mutual authentication is performed in the + course of context establishment. GSS_Init_sec_context() returns an + output_token to be passed to the server, and indicates + GSS_CONTINUE_NEEDED status pending completion of the mutual + authentication sequence. Had mutual_req_flag not been set, the + initial call to GSS_Init_sec_context() would have returned + GSS_COMPLETE status. The client sends the output_token to the server. + + The server passes the received token as the input_token parameter to + GSS_Accept_sec_context(). GSS_Accept_sec_context indicates + GSS_COMPLETE status, provides the client's authenticated identity in + the src_name result, and provides an output_token to be passed to the + client. The server sends the output_token to the client. + + The client passes the received token as the input_token parameter to + a successor call to GSS_Init_sec_context(), which processes data + + + +Linn [Page 3] + +RFC 1508 Generic Security Interface September 1993 + + + included in the token in order to achieve mutual authentication from + the client's viewpoint. This call to GSS_Init_sec_context() returns + GSS_COMPLETE status, indicating successful mutual authentication and + the completion of context establishment for this example. + + The client generates a data message and passes it to GSS_Seal(). + GSS_Seal() performs data origin authentication, data integrity, and + (optionally) confidentiality processing on the message and + encapsulates the result into output_message, indicating GSS_COMPLETE + status. The client sends the output_message to the server. + + The server passes the received message to GSS_Unseal(). GSS_Unseal + inverts the encapsulation performed by GSS_Seal(), deciphers the + message if the optional confidentiality feature was applied, and + validates the data origin authentication and data integrity checking + quantities. GSS_Unseal() indicates successful validation by + returning GSS_COMPLETE status along with the resultant + output_message. + + For purposes of this example, we assume that the server knows by + out-of-band means that this context will have no further use after + one protected message is transferred from client to server. Given + this premise, the server now calls GSS_Delete_sec_context() to flush + context-level information. GSS_Delete_sec_context() returns a + context_token for the server to pass to the client. + + The client passes the returned context_token to + GSS_Process_context_token(), which returns GSS_COMPLETE status after + deleting context-level information at the client system. + + The GSS-API design assumes and addresses several basic goals, + including: + + Mechanism independence: The GSS-API defines an interface to + cryptographically implemented strong authentication and other + security services at a generic level which is independent of + particular underlying mechanisms. For example, GSS-API-provided + services can be implemented by secret-key technologies (e.g., + Kerberos) or public-key approaches (e.g., X.509). + + Protocol environment independence: The GSS-API is independent of + the communications protocol suites with which it is employed, + permitting use in a broad range of protocol environments. In + appropriate environments, an intermediate implementation "veneer" + which is oriented to a particular communication protocol (e.g., + Remote Procedure Call (RPC)) may be interposed between + applications which call that protocol and the GSS-API, thereby + invoking GSS-API facilities in conjunction with that protocol's + + + +Linn [Page 4] + +RFC 1508 Generic Security Interface September 1993 + + + communications invocations. + + Protocol association independence: The GSS-API's security context + construct is independent of communications protocol association + constructs. This characteristic allows a single GSS-API + implementation to be utilized by a variety of invoking protocol + modules on behalf of those modules' calling applications. GSS-API + services can also be invoked directly by applications, wholly + independent of protocol associations. + + Suitability to a range of implementation placements: GSS-API + clients are not constrained to reside within any Trusted Computing + Base (TCB) perimeter defined on a system where the GSS-API is + implemented; security services are specified in a manner suitable + to both intra-TCB and extra-TCB callers. + +1.1. GSS-API Constructs + + This section describes the basic elements comprising the GSS-API. + +1.1.1. Credentials + + Credentials structures provide the prerequisites enabling peers to + establish security contexts with each other. A caller may designate + that its default credential be used for context establishment calls + without presenting an explicit handle to that credential. + Alternately, those GSS-API callers which need to make explicit + selection of particular credentials structures may make references to + those credentials through GSS-API-provided credential handles + ("cred_handles"). + + A single credential structure may be used for initiation of outbound + contexts and acceptance of inbound contexts. Callers needing to + operate in only one of these modes may designate this fact when + credentials are acquired for use, allowing underlying mechanisms to + optimize their processing and storage requirements. The credential + elements defined by a particular mechanism may contain multiple + cryptographic keys, e.g., to enable authentication and message + encryption to be performed with different algorithms. + + A single credential structure may accommodate credential information + associated with multiple underlying mechanisms (mech_types); a + credential structure's contents will vary depending on the set of + mech_types supported by a particular GSS-API implementation. + Commonly, a single mech_type will be used for all security contexts + established by a particular initiator to a particular target; the + primary motivation for supporting credential sets representing + multiple mech_types is to allow initiators on systems which are + + + +Linn [Page 5] + +RFC 1508 Generic Security Interface September 1993 + + + equipped to handle multiple types to initiate contexts to targets on + other systems which can accommodate only a subset of the set + supported at the initiator's system. + + It is the responsibility of underlying system-specific mechanisms and + OS functions below the GSS-API to ensure that the ability to acquire + and use credentials associated with a given identity is constrained + to appropriate processes within a system. This responsibility should + be taken seriously by implementors, as the ability for an entity to + utilize a principal's credentials is equivalent to the entity's + ability to successfully assert that principal's identity. + + Once a set of GSS-API credentials is established, the transferability + of that credentials set to other processes or analogous constructs + within a system is a local matter, not defined by the GSS-API. An + example local policy would be one in which any credentials received + as a result of login to a given user account, or of delegation of + rights to that account, are accessible by, or transferable to, + processes running under that account. + + The credential establishment process (particularly when performed on + behalf of users rather than server processes) is likely to require + access to passwords or other quantities which should be protected + locally and exposed for the shortest time possible. As a result, it + will often be appropriate for preliminary credential establishment to + be performed through local means at user login time, with the + result(s) cached for subsequent reference. These preliminary + credentials would be set aside (in a system-specific fashion) for + subsequent use, either: + + to be accessed by an invocation of the GSS-API GSS_Acquire_cred() + call, returning an explicit handle to reference that credential + + as the default credentials installed on behalf of a process + +1.1.2. Tokens + + Tokens are data elements transferred between GSS-API callers, and are + divided into two classes. Context-level tokens are exchanged in order + to establish and manage a security context between peers. Per-message + tokens are exchanged in conjunction with an established context to + provide protective security services for corresponding data messages. + The internal contents of both classes of tokens are specific to the + particular underlying mechanism used to support the GSS-API; Appendix + B of this document provides a uniform recommendation for designers of + GSS-API support mechanisms, encapsulating mechanism-specific + information along with a globally-interpretable mechanism identifier. + + + + +Linn [Page 6] + +RFC 1508 Generic Security Interface September 1993 + + + Tokens are opaque from the viewpoint of GSS-API callers. They are + generated within the GSS-API implementation at an end system, + provided to a GSS-API caller to be transferred to the peer GSS-API + caller at a remote end system, and processed by the GSS-API + implementation at that remote end system. Tokens may be output by + GSS-API primitives (and are to be transferred to GSS-API peers) + independent of the status indications which those primitives + indicate. Token transfer may take place in an in-band manner, + integrated into the same protocol stream used by the GSS-API callers + for other data transfers, or in an out-of-band manner across a + logically separate channel. + + Development of GSS-API support primitives based on a particular + underlying cryptographic technique and protocol does not necessarily + imply that GSS-API callers invoking that GSS-API mechanism type will + be able to interoperate with peers invoking the same technique and + protocol outside the GSS-API paradigm. For example, the format of + GSS-API tokens defined in conjunction with a particular mechanism, + and the techniques used to integrate those tokens into callers' + protocols, may not be the same as those used by non-GSS-API callers + of the same underlying technique. + +1.1.3. Security Contexts + + Security contexts are established between peers, using credentials + established locally in conjunction with each peer or received by + peers via delegation. Multiple contexts may exist simultaneously + between a pair of peers, using the same or different sets of + credentials. Coexistence of multiple contexts using different + credentials allows graceful rollover when credentials expire. + Distinction among multiple contexts based on the same credentials + serves applications by distinguishing different message streams in a + security sense. + + The GSS-API is independent of underlying protocols and addressing + structure, and depends on its callers to transport GSS-API-provided + data elements. As a result of these factors, it is a caller + responsibility to parse communicated messages, separating GSS-API- + related data elements from caller-provided data. The GSS-API is + independent of connection vs. connectionless orientation of the + underlying communications service. + + No correlation between security context and communications protocol + association is dictated. (The optional channel binding facility, + discussed in Section 1.1.6 of this document, represents an + intentional exception to this rule, supporting additional protection + features within GSS-API supporting mechanisms.) This separation + allows the GSS-API to be used in a wide range of communications + + + +Linn [Page 7] + +RFC 1508 Generic Security Interface September 1993 + + + environments, and also simplifies the calling sequences of the + individual calls. In many cases (depending on underlying security + protocol, associated mechanism, and availability of cached + information), the state information required for context setup can be + sent concurrently with initial signed user data, without interposing + additional message exchanges. + +1.1.4. Mechanism Types + + In order to successfully establish a security context with a target + peer, it is necessary to identify an appropriate underlying mechanism + type (mech_type) which both initiator and target peers support. The + definition of a mechanism embodies not only the use of a particular + cryptographic technology (or a hybrid or choice among alternative + cryptographic technologies), but also definition of the syntax and + semantics of data element exchanges which that mechanism will employ + in order to support security services. + + It is recommended that callers initiating contexts specify the + "default" mech_type value, allowing system-specific functions within + or invoked by the GSS-API implementation to select the appropriate + mech_type, but callers may direct that a particular mech_type be + employed when necessary. + + The means for identifying a shared mech_type to establish a security + context with a peer will vary in different environments and + circumstances; examples include (but are not limited to): + + use of a fixed mech_type, defined by configuration, within an + environment + + syntactic convention on a target-specific basis, through + examination of a target's name + + lookup of a target's name in a naming service or other database in + order to identify mech_types supported by that target + + explicit negotiation between GSS-API callers in advance of + security context setup + + When transferred between GSS-API peers, mech_type specifiers (per + Appendix B, represented as Object Identifiers (OIDs)) serve to + qualify the interpretation of associated tokens. (The structure and + encoding of Object Identifiers is defined in ISO/IEC 8824, + "Specification of Abstract Syntax Notation One (ASN.1)" and in + ISO/IEC 8825, "Specification of Basic Encoding Rules for Abstract + Syntax Notation One (ASN.1)".) Use of hierarchically structured OIDs + serves to preclude ambiguous interpretation of mech_type specifiers. + + + +Linn [Page 8] + +RFC 1508 Generic Security Interface September 1993 + + + The OID representing the DASS MechType, for example, is + 1.3.12.2.1011.7.5. + +1.1.5. Naming + + The GSS-API avoids prescription of naming structures, treating the + names transferred across the interface in order to initiate and + accept security contexts as opaque octet string quantities. This + approach supports the GSS-API's goal of implementability atop a range + of underlying security mechanisms, recognizing the fact that + different mechanisms process and authenticate names which are + presented in different forms. Generalized services offering + translation functions among arbitrary sets of naming environments are + outside the scope of the GSS-API; availability and use of local + conversion functions to translate among the naming formats supported + within a given end system is anticipated. + + Two distinct classes of name representations are used in conjunction + with different GSS-API parameters: + + a printable form (denoted by OCTET STRING), for acceptance from + and presentation to users; printable name forms are accompanied by + OID tags identifying the namespace to which they correspond + + an internal form (denoted by INTERNAL NAME), opaque to callers and + defined by individual GSS-API implementations; GSS-API + implementations supporting multiple namespace types are + responsible for maintaining internal tags to disambiguate the + interpretation of particular names + + Tagging of printable names allows GSS-API callers and underlying + GSS-API mechanisms to disambiguate name types and to determine + whether an associated name's type is one which they are capable of + processing, avoiding aliasing problems which could result from + misinterpreting a name of one type as a name of another type. + + In addition to providing means for names to be tagged with types, + this specification defines primitives to support a level of naming + environment independence for certain calling applications. To provide + basic services oriented towards the requirements of callers which + need not themselves interpret the internal syntax and semantics of + names, GSS-API calls for name comparison (GSS_Compare_name()), + human-readable display (GSS_Display_name()), input conversion + (GSS_Import_name()), and internal name deallocation + (GSS_Release_name()) functions are defined. (It is anticipated that + these proposed GSS-API calls will be implemented in many end systems + based on system-specific name manipulation primitives already extant + within those end systems; inclusion within the GSS-API is intended to + + + +Linn [Page 9] + +RFC 1508 Generic Security Interface September 1993 + + + offer GSS-API callers a portable means to perform specific + operations, supportive of authorization and audit requirements, on + authenticated names.) + + GSS_Import_name() implementations can, where appropriate, support + more than one printable syntax corresponding to a given namespace + (e.g., alternative printable representations for X.500 Distinguished + Names), allowing flexibility for their callers to select among + alternative representations. GSS_Display_name() implementations + output a printable syntax selected as appropriate to their + operational environments; this selection is a local matter. Callers + desiring portability across alternative printable syntaxes should + refrain from implementing comparisons based on printable name forms + and should instead use the GSS_Compare_name() call to determine + whether or not one internal-format name matches another. + +1.1.6. Channel Bindings + + The GSS-API accommodates the concept of caller-provided channel + binding ("chan_binding") information, used by GSS-API callers to bind + the establishment of a security context to relevant characteristics + (e.g., addresses, transformed representations of encryption keys) of + the underlying communications channel and of protection mechanisms + applied to that communications channel. Verification by one peer of + chan_binding information provided by the other peer to a context + serves to protect against various active attacks. The caller + initiating a security context must determine the chan_binding values + before making the GSS_Init_sec_context() call, and consistent values + must be provided by both peers to a context. Callers should not + assume that underlying mechanisms provide confidentiality protection + for channel binding information. + + Use or non-use of the GSS-API channel binding facility is a caller + option, and GSS-API supporting mechanisms can support operation in an + environment where NULL channel bindings are presented. When non-NULL + channel bindings are used, certain mechanisms will offer enhanced + security value by interpreting the bindings' content (rather than + simply representing those bindings, or signatures computed on them, + within tokens) and will therefore depend on presentation of specific + data in a defined format. To this end, agreements among mechanism + implementors are defining conventional interpretations for the + contents of channel binding arguments, including address specifiers + (with content dependent on communications protocol environment) for + context initiators and acceptors. (These conventions are being + incorporated into related documents.) In order for GSS-API callers to + be portable across multiple mechanisms and achieve the full security + functionality available from each mechanism, it is strongly + recommended that GSS-API callers provide channel bindings consistent + + + +Linn [Page 10] + +RFC 1508 Generic Security Interface September 1993 + + + with these conventions and those of the networking environment in + which they operate. + +1.2. GSS-API Features and Issues + + This section describes aspects of GSS-API operations, of the security + services which the GSS-API provides, and provides commentary on + design issues. + +1.2.1. Status Reporting + + Each GSS-API call provides two status return values. Major_status + values provide a mechanism-independent indication of call status + (e.g., GSS_COMPLETE, GSS_FAILURE, GSS_CONTINUE_NEEDED), sufficient to + drive normal control flow within the caller in a generic fashion. + Table 1 summarizes the defined major_status return codes in tabular + fashion. + + Table 1: GSS-API Major Status Codes + + FATAL ERROR CODES + + GSS_BAD_BINDINGS channel binding mismatch + GSS_BAD_MECH unsupported mechanism requested + GSS_BAD_NAME invalid name provided + GSS_BAD_NAMETYPE name of unsupported type provided + GSS_BAD_STATUS invalid input status selector + GSS_BAD_SIG token had invalid signature + GSS_CONTEXT_EXPIRED specified security context expired + GSS_CREDENTIALS_EXPIRED expired credentials detected + GSS_DEFECTIVE_CREDENTIAL defective credential detected + GSS_DEFECTIVE_TOKEN defective token detected + GSS_FAILURE failure, unspecified at GSS-API + level + GSS_NO_CONTEXT no valid security context specified + GSS_NO_CRED no valid credentials provided + + INFORMATORY STATUS CODES + + GSS_COMPLETE normal completion + GSS_CONTINUE_NEEDED continuation call to routine + required + GSS_DUPLICATE_TOKEN duplicate per-message token + detected + GSS_OLD_TOKEN timed-out per-message token + detected + GSS_UNSEQ_TOKEN out-of-order per-message token + detected + + + +Linn [Page 11] + +RFC 1508 Generic Security Interface September 1993 + + + Minor_status provides more detailed status information which may + include status codes specific to the underlying security mechanism. + Minor_status values are not specified in this document. + + GSS_CONTINUE_NEEDED major_status returns, and optional message + outputs, are provided in GSS_Init_sec_context() and + GSS_Accept_sec_context() calls so that different mechanisms' + employment of different numbers of messages within their + authentication sequences need not be reflected in separate code paths + within calling applications. Instead, such cases are accomodated with + sequences of continuation calls to GSS_Init_sec_context() and + GSS_Accept_sec_context(). The same mechanism is used to encapsulate + mutual authentication within the GSS-API's context initiation calls. + + For mech_types which require interactions with third-party servers in + order to establish a security context, GSS-API context establishment + calls may block pending completion of such third-party interactions. + On the other hand, no GSS-API calls pend on serialized interactions + with GSS-API peer entities. As a result, local GSS-API status + returns cannot reflect unpredictable or asynchronous exceptions + occurring at remote peers, and reflection of such status information + is a caller responsibility outside the GSS-API. + +1.2.2. Per-Message Security Service Availability + + When a context is established, two flags are returned to indicate the + set of per-message protection security services which will be + available on the context: + + the integ_avail flag indicates whether per-message integrity and + data origin authentication services are available + + the conf_avail flag indicates whether per-message confidentiality + services are available, and will never be returned TRUE unless the + integ_avail flag is also returned TRUE + + GSS-API callers desiring per-message security services should + check the values of these flags at context establishment time, and + must be aware that a returned FALSE value for integ_avail means + that invocation of GSS_Sign() or GSS_Seal() primitives on the + associated context will apply no cryptographic protection to user + data messages. + + The GSS-API per-message protection service primitives, as the + category name implies, are oriented to operation at the granularity + of protocol data units. They perform cryptographic operations on the + data units, transfer cryptographic control information in tokens, + and, in the case of GSS_Seal(), encapsulate the protected data unit. + + + +Linn [Page 12] + +RFC 1508 Generic Security Interface September 1993 + + + As such, these primitives are not oriented to efficient data + protection for stream-paradigm protocols (e.g., Telnet) if + cryptography must be applied on an octet-by-octet basis. + +1.2.3. Per-Message Replay Detection and Sequencing + + Certain underlying mech_types are expected to offer support for + replay detection and/or sequencing of messages transferred on the + contexts they support. These optionally-selectable protection + features are distinct from replay detection and sequencing features + applied to the context establishment operation itself; the presence + or absence of context-level replay or sequencing features is wholly a + function of the underlying mech_type's capabilities, and is not + selected or omitted as a caller option. + + The caller initiating a context provides flags (replay_det_req_flag + and sequence_req_flag) to specify whether the use of per-message + replay detection and sequencing features is desired on the context + being established. The GSS-API implementation at the initiator system + can determine whether these features are supported (and whether they + are optionally selectable) as a function of mech_type, without need + for bilateral negotiation with the target. When enabled, these + features provide recipients with indicators as a result of GSS-API + processing of incoming messages, identifying whether those messages + were detected as duplicates or out-of-sequence. Detection of such + events does not prevent a suspect message from being provided to a + recipient; the appropriate course of action on a suspect message is a + matter of caller policy. + + The semantics of the replay detection and sequencing services applied + to received messages, as visible across the interface which the GSS- + API provides to its clients, are as follows: + + When replay_det_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_COMPLETE indicates that the message was within the window + (of time or sequence space) allowing replay events to be detected, + and that the message was not a replay of a previously-processed + message within that window. + + 2. GSS_DUPLICATE_TOKEN indicates that the signature on the + received message was correct, but that the message was recognized + as a duplicate of a previously-processed message. + + 3. GSS_OLD_TOKEN indicates that the signature on the received + message was correct, but that the message is too old to be checked + for duplication. + + + +Linn [Page 13] + +RFC 1508 Generic Security Interface September 1993 + + + When sequence_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_COMPLETE indicates that the message was within the window + (of time or sequence space) allowing replay events to be detected, + and that the message was not a replay of a previously-processed + message within that window. + + 2. GSS_DUPLICATE_TOKEN indicates that the signature on the + received message was correct, but that the message was recognized + as a duplicate of a previously-processed message. + + 3. GSS_OLD_TOKEN indicates that the signature on the received + message was correct, but that the token is too old to be checked + for duplication. + + 4. GSS_UNSEQ_TOKEN indicates that the signature on the received + message was correct, but that it is earlier in a sequenced stream + than a message already processed on the context. [Note: + Mechanisms can be architected to provide a stricter form of + sequencing service, delivering particular messages to recipients + only after all predecessor messages in an ordered stream have been + delivered. This type of support is incompatible with the GSS-API + paradigm in which recipients receive all messages, whether in + order or not, and provide them (one at a time, without intra-GSS- + API message buffering) to GSS-API routines for validation. GSS- + API facilities provide supportive functions, aiding clients to + achieve strict message stream integrity in an efficient manner in + conjunction with sequencing provisions in communications + protocols, but the GSS-API does not offer this level of message + stream integrity service by itself.] + + As the message stream integrity features (especially sequencing) may + interfere with certain applications' intended communications + paradigms, and since support for such features is likely to be + resource intensive, it is highly recommended that mech_types + supporting these features allow them to be activated selectively on + initiator request when a context is established. A context initiator + and target are provided with corresponding indicators + (replay_det_state and sequence_state), signifying whether these + features are active on a given context. + + An example mech_type supporting per-message replay detection could + (when replay_det_state is TRUE) implement the feature as follows: The + underlying mechanism would insert timestamps in data elements output + by GSS_Sign() and GSS_Seal(), and would maintain (within a time- + limited window) a cache (qualified by originator-recipient pair) + identifying received data elements processed by GSS_Verify() and + + + +Linn [Page 14] + +RFC 1508 Generic Security Interface September 1993 + + + GSS_Unseal(). When this feature is active, exception status returns + (GSS_DUPLICATE_TOKEN, GSS_ OLD_TOKEN) will be provided when + GSS_Verify() or GSS_Unseal() is presented with a message which is + either a detected duplicate of a prior message or which is too old to + validate against a cache of recently received messages. + +1.2.4. Quality of Protection + + Some mech_types will provide their users with fine granularity + control over the means used to provide per-message protection, + allowing callers to trade off security processing overhead + dynamically against the protection requirements of particular + messages. A per-message quality-of-protection parameter (analogous to + quality-of-service, or QOS) selects among different QOP options + supported by that mechanism. On context establishment for a multi-QOP + mech_type, context-level data provides the prerequisite data for a + range of protection qualities. + + It is expected that the majority of callers will not wish to exert + explicit mechanism-specific QOP control and will therefore request + selection of a default QOP. Definitions of, and choices among, non- + default QOP values are mechanism-specific, and no ordered sequences + of QOP values can be assumed equivalent across different mechanisms. + Meaningful use of non-default QOP values demands that callers be + familiar with the QOP definitions of an underlying mechanism or + mechanisms, and is therefore a non-portable construct. + +2. Interface Descriptions + + This section describes the GSS-API's service interface, dividing the + set of calls offered into four groups. Credential management calls + are related to the acquisition and release of credentials by + principals. Context-level calls are related to the management of + security contexts between principals. Per-message calls are related + to the protection of individual messages on established security + contexts. Support calls provide ancillary functions useful to GSS-API + callers. Table 2 groups and summarizes the calls in tabular fashion. + + + + + + + + + + + + + + +Linn [Page 15] + +RFC 1508 Generic Security Interface September 1993 + + + Table 2: GSS-API Calls + + CREDENTIAL MANAGEMENT + + GSS_Acquire_cred acquire credentials for use + GSS_Release_cred release credentials after use + GSS_Inquire_cred display information about + credentials + + CONTEXT-LEVEL CALLS + + GSS_Init_sec_context initiate outbound security context + GSS_Accept_sec_context accept inbound security context + GSS_Delete_sec_context flush context when no longer needed + GSS_Process_context_token process received control token on + context + GSS_Context_time indicate validity time remaining on + context + + PER-MESSAGE CALLS + + GSS_Sign apply signature, receive as token + separate from message + GSS_Verify validate signature token along with + message + GSS_Seal sign, optionally encrypt, + encapsulate + GSS_Unseal decapsulate, decrypt if needed, + validate signature + + SUPPORT CALLS + + GSS_Display_status translate status codes to printable + form + GSS_Indicate_mechs indicate mech_types supported on + local system + GSS_Compare_name compare two names for equality + GSS_Display_name translate name to printable form + GSS_Import_name convert printable name to + normalized form + GSS_Release_name free storage of normalized-form + name + GSS_Release_buffer free storage of printable name + GSS_Release_oid_set free storage of OID set object + + + + + + + +Linn [Page 16] + +RFC 1508 Generic Security Interface September 1993 + + +2.1. Credential management calls + + These GSS-API calls provide functions related to the management of + credentials. Their characterization with regard to whether or not + they may block pending exchanges with other network entities (e.g., + directories or authentication servers) depends in part on OS-specific + (extra-GSS-API) issues, so is not specified in this document. + + The GSS_Acquire_cred() call is defined within the GSS-API in support + of application portability, with a particular orientation towards + support of portable server applications. It is recognized that (for + certain systems and mechanisms) credentials for interactive users may + be managed differently from credentials for server processes; in such + environments, it is the GSS-API implementation's responsibility to + distinguish these cases and the procedures for making this + distinction are a local matter. The GSS_Release_cred() call provides + a means for callers to indicate to the GSS-API that use of a + credentials structure is no longer required. The GSS_Inquire_cred() + call allows callers to determine information about a credentials + structure. + +2.1.1. GSS_Acquire_cred call + + Inputs: + + o desired_name INTERNAL NAME, -NULL requests locally-determined + default + + o lifetime_req INTEGER,-in seconds; 0 requests default + + o desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests + system-selected default + + o cred_usage INTEGER-0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_cred_handle OCTET STRING, + + o actual_mechs SET OF OBJECT IDENTIFIER, + + o lifetime_rec INTEGER -in seconds, or reserved value for + INDEFINITE + + + +Linn [Page 17] + +RFC 1508 Generic Security Interface September 1993 + + + Return major_status codes: + + o GSS_COMPLETE indicates that requested credentials were + successfully established, for the duration indicated in + lifetime_rec, suitable for the usage requested in cred_usage, for + the set of mech_types indicated in actual_mechs, and that those + credentials can be referenced for subsequent use with the handle + returned in output_cred_handle. + + o GSS_BAD_MECH indicates that a mech_type unsupported by the GSS-API + implementation type was requested, causing the credential + establishment operation to fail. + + o GSS_BAD_NAMETYPE indicates that the provided desired_name is + uninterpretable or of a type unsupported by the supporting GSS-API + implementation, so no credentials could be established for the + accompanying desired_name. + + o GSS_BAD_NAME indicates that the provided desired_name is + inconsistent in terms of internally-incorporated type specifier + information, so no credentials could be established for the + accompanying desired_name. + + o GSS_FAILURE indicates that credential establishment failed for + reasons unspecified at the GSS-API level, including lack of + authorization to establish and use credentials associated with the + identity named in the input desired_name argument. + + GSS_Acquire_cred() is used to acquire credentials so that a + principal can (as a function of the input cred_usage parameter) + initiate and/or accept security contexts under the identity + represented by the desired_name input argument. On successful + completion, the returned output_cred_handle result provides a handle + for subsequent references to the acquired credentials. Typically, + single-user client processes using only default credentials for + context establishment purposes will have no need to invoke this call. + + A caller may provide the value NULL for desired_name, signifying a + request for credentials corresponding to a default principal + identity. The procedures used by GSS-API implementations to select + the appropriate principal identity in response to this form of + request are local matters. It is possible that multiple pre- + established credentials may exist for the same principal identity + (for example, as a result of multiple user login sessions) when + GSS_Acquire_cred() is called; the means used in such cases to select + a specific credential are local matters. The input lifetime_req + argument to GSS_Acquire_cred() may provide useful information for + local GSS-API implementations to employ in making this disambiguation + + + +Linn [Page 18] + +RFC 1508 Generic Security Interface September 1993 + + + in a manner which will best satisfy a caller's intent. + + The lifetime_rec result indicates the length of time for which the + acquired credentials will be valid, as an offset from the present. A + mechanism may return a reserved value indicating INDEFINITE if no + constraints on credential lifetime are imposed. A caller of + GSS_Acquire_cred() can request a length of time for which acquired + credentials are to be valid (lifetime_req argument), beginning at the + present, or can request credentials with a default validity interval. + (Requests for postdated credentials are not supported within the + GSS-API.) Certain mechanisms and implementations may bind in + credential validity period specifiers at a point preliminary to + invocation of the GSS_Acquire_cred() call (e.g., in conjunction with + user login procedures). As a result, callers requesting non-default + values for lifetime_req must recognize that such requests cannot + always be honored and must be prepared to accommodate the use of + returned credentials with different lifetimes as indicated in + lifetime_rec. + + The caller of GSS_Acquire_cred() can explicitly specify a set of + mech_types which are to be accommodated in the returned credentials + (desired_mechs argument), or can request credentials for a system- + defined default set of mech_types. Selection of the system-specified + default set is recommended in the interests of application + portability. The actual_mechs return value may be interrogated by the + caller to determine the set of mechanisms with which the returned + credentials may be used. + +2.1.2. GSS_Release_cred call + + Input: + + o cred_handle OCTET STRING-NULL specifies default credentials + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the credentials referenced by the + input cred_handle were released for purposes of subsequent access + by the caller. The effect on other processes which may be + authorized shared access to such credentials is a local matter. + + + + + +Linn [Page 19] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CRED indicates that no release operation was performed, + either because the input cred_handle was invalid or because the + caller lacks authorization to access the referenced credentials. + + o GSS_FAILURE indicates that the release operation failed for + reasons unspecified at the GSS-API level. + + Provides a means for a caller to explicitly request that credentials + be released when their use is no longer required. Note that system- + specific credential management functions are also likely to exist, + for example to assure that credentials shared among processes are + properly deleted when all affected processes terminate, even if no + explicit release requests are issued by those processes. Given the + fact that multiple callers are not precluded from gaining authorized + access to the same credentials, invocation of GSS_Release_cred() + cannot be assumed to delete a particular set of credentials on a + system-wide basis. + +2.1.3. GSS_Inquire_cred call + + Input: + + o cred_handle OCTET STRING -NULL specifies default credentials + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o cred_name INTERNAL NAME, + + o lifetime_rec INTEGER -in seconds, or reserved value for + INDEFINITE + + o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + o mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that the credentials referenced by the + input cred_handle argument were valid, and that the output + cred_name, lifetime_rec, and cred_usage values represent, + respectively, the credentials' associated principal name, + remaining lifetime, suitable usage modes, and supported + mechanism types. + + + +Linn [Page 20] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CRED indicates that no information could be returned + about the referenced credentials, either because the input + cred_handle was invalid or because the caller lacks + authorization to access the referenced credentials. + + o GSS_FAILURE indicates that the release operation failed for + reasons unspecified at the GSS-API level. + + The GSS_Inquire_cred() call is defined primarily for the use of + those callers which make use of default credentials rather than + acquiring credentials explicitly with GSS_Acquire_cred(). It enables + callers to determine a credential structure's associated principal + name, remaining validity period, usability for security context + initiation and/or acceptance, and supported mechanisms. + +2.2. Context-level calls + + This group of calls is devoted to the establishment and management of + security contexts between peers. A context's initiator calls + GSS_Init_sec_context(), resulting in generation of a token which the + caller passes to the target. At the target, that token is passed to + GSS_Accept_sec_context(). Depending on the underlying mech_type and + specified options, additional token exchanges may be performed in the + course of context establishment; such exchanges are accommodated by + GSS_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and + GSS_Accept_sec_context(). Either party to an established context may + invoke GSS_Delete_sec_context() to flush context information when a + context is no longer required. GSS_Process_context_token() is used + to process received tokens carrying context-level control + information. GSS_Context_time() allows a caller to determine the + length of time for which an established context will remain valid. + +2.2.1. GSS_Init_sec_context call + + Inputs: + + o claimant_cred_handle OCTET STRING, -NULL specifies "use + default" + + o input_context_handle INTEGER, -0 specifies "none assigned + yet" + + o targ_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use + default" + + o deleg_req_flag BOOLEAN, + + + +Linn [Page 21] + +RFC 1508 Generic Security Interface September 1993 + + + o mutual_req_flag BOOLEAN, + + o replay_det_req_flag BOOLEAN, + + o sequence_req_flag BOOLEAN, + + o lifetime_req INTEGER,-0 specifies default lifetime + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING-NULL or token received from target + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_context_handle INTEGER, + + o mech_type OBJECT IDENTIFIER, -actual mechanism always + indicated, never NULL + + o output_token OCTET STRING, -NULL or token to pass to context + target + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o lifetime_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + This call may block pending network interactions for those mech_types + in which an authentication server or other network entity must be + consulted on behalf of a context initiator in order to generate an + output_token suitable for presentation to a specified target. + + Return major_status codes: + + + + +Linn [Page 22] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_COMPLETE indicates that context-level information was + successfully initialized, and that the returned output_token will + provide sufficient information for the target to perform per- + message processing on the newly-established context. + + o GSS_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the target, and that a reply + must be received and passed as the input_token argument to a + continuation call to GSS_Init_sec_context(), before per-message + processing can be performed in conjunction with this context. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the input_token failed, preventing further processing from being + performed based on that token. + + o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + claimant_cred_handle failed, preventing further processing from + being performed using that credential structure. + + o GSS_BAD_SIG indicates that the received input_token contains an + incorrect signature, so context setup cannot be accomplished. + + o GSS_NO_CRED indicates that no context was established, either + because the input cred_handle was invalid, because the referenced + credentials are valid for context acceptor use only, or because + the caller lacks authorization to access the referenced + credentials. + + o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided + through the input claimant_cred_handle argument are no longer + valid, so context establishment cannot be completed. + + o GSS_BAD_BINDINGS indicates that a mismatch between the caller- + provided chan_bindings and those extracted from the input_token + was detected, signifying a security-relevant event and preventing + context establishment. (This result will be returned by + GSS_Init_sec_context only for contexts where mutual_state is + TRUE.) + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided; this major status will be + returned only for successor calls following GSS_CONTINUE_NEEDED + status returns. + + o GSS_BAD_NAMETYPE indicates that the provided targ_name is of a + type uninterpretable or unsupported by the supporting GSS-API + implementation, so context establishment cannot be completed. + + + +Linn [Page 23] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_BAD_NAME indicates that the provided targ_name is inconsistent + in terms of internally-incorporated type specifier information, so + context establishment cannot be accomplished. + + o GSS_FAILURE indicates that context setup could not be accomplished + for reasons unspecified at the GSS-API level, and that no + interface-defined recovery action is available. + + This routine is used by a context initiator, and ordinarily emits one + (or, for the case of a multi-step exchange, more than one) + output_token suitable for use by the target within the selected + mech_type's protocol. Using information in the credentials structure + referenced by claimant_cred_handle, GSS_Init_sec_context() + initializes the data structures required to establish a security + context with target targ_name. The claimant_cred_handle must + correspond to the same valid credentials structure on the initial + call to GSS_Init_sec_context() and on any successor calls resulting + from GSS_CONTINUE_NEEDED status returns; different protocol sequences + modeled by the GSS_CONTINUE_NEEDED mechanism will require access to + credentials at different points in the context establishment + sequence. + + The input_context_handle argument is 0, specifying "not yet + assigned", on the first GSS_Init_sec_context() call relating to a + given context. That call returns an output_context_handle for future + references to this context. When continuation attempts to + GSS_Init_sec_context() are needed to perform context establishment, + the previously-returned non-zero handle value is entered into the + input_context_handle argument and will be echoed in the returned + output_context_handle argument. On such continuation attempts (and + only on continuation attempts) the input_token value is used, to + provide the token returned from the context's target. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The input_token argument contains a message received from the target, + and is significant only on a call to GSS_Init_sec_context() which + follows a previous return indicating GSS_CONTINUE_NEEDED + major_status. + + It is the caller's responsibility to establish a communications path + to the target, and to transmit any returned output_token (independent + of the accompanying returned major_status value) to the target over + that path. The output_token can, however, be transmitted along with + + + +Linn [Page 24] + +RFC 1508 Generic Security Interface September 1993 + + + the first application-provided input message to be processed by + GSS_Sign() or GSS_Seal() in conjunction with a successfully- + established context. + + The initiator may request various context-level functions through + input flags: the deleg_req_flag requests delegation of access rights, + the mutual_req_flag requests mutual authentication, the + replay_det_req_flag requests that replay detection features be + applied to messages transferred on the established context, and the + sequence_req_flag requests that sequencing be enforced. (See Section + 1.2.3 for more information on replay detection and sequencing + features.) + + Not all of the optionally-requestable features will be available in + all underlying mech_types; the corresponding return state values + (deleg_state, mutual_state, replay_det_state, sequence_state) + indicate, as a function of mech_type processing capabilities and + initiator-provided input flags, the set of features which will be + active on the context. These state indicators' values are undefined + unless the routine's major_status indicates COMPLETE. Failure to + provide the precise set of features requested by the caller does not + cause context establishment to fail; it is the caller's prerogative + to delete the context if the feature set provided is unsuitable for + the caller's use. The returned mech_type value indicates the + specific mechanism employed on the context, and will never indicate + the value for "default". + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + input to GSS_Seal() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_Sign() or GSS_Seal()) on + the established context. + + The lifetime_req input specifies a desired upper bound for the + lifetime of the context to be established, with a value of 0 used to + request a default lifetime. The lifetime_rec return value indicates + the length of time for which the context will be valid, expressed as + an offset from the present; depending on mechanism capabilities, + credential lifetimes, and local policy, it may not correspond to the + value requested in lifetime_req. If no constraints on context + lifetime are imposed, this may be indicated by returning a reserved + value representing INDEFINITE lifetime_req. The values of conf_avail, + integ_avail, and lifetime_rec are undefined unless the routine's + major_status indicates COMPLETE. + + If the mutual_state is TRUE, this fact will be reflected within the + + + +Linn [Page 25] + +RFC 1508 Generic Security Interface September 1993 + + + output_token. A call to GSS_Accept_sec_context() at the target in + conjunction with such a context will return a token, to be processed + by a continuation call to GSS_Init_sec_context(), in order to achieve + mutual authentication. + +2.2.2. GSS_Accept_sec_context call + + Inputs: + + o acceptor_cred_handle OCTET STRING,-NULL specifies "use + default" + + o input_context_handle INTEGER, -0 specifies "not yet assigned" + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o src_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER, + + o output_context_handle INTEGER, + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o lifetime_rec INTEGER, - in seconds, or reserved value for + INDEFINITE + + o delegated_cred_handle OCTET STRING, + + o output_token OCTET STRING -NULL or token to pass to context + + + +Linn [Page 26] + +RFC 1508 Generic Security Interface September 1993 + + + initiator + + This call may block pending network interactions for those mech_types + in which a directory service or other network entity must be + consulted on behalf of a context acceptor in order to validate a + received input_token. + + Return major_status codes: + + o GSS_COMPLETE indicates that context-level data structures were + successfully initialized, and that per-message processing can now + be performed in conjunction with this context. + + o GSS_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the initiator, and that a + response must be received and passed as the input_token argument + to a continuation call to GSS_Accept_sec_context(), before per- + message processing can be performed in conjunction with this + context. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the input_token failed, preventing further processing from being + performed based on that token. + + o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + acceptor_cred_handle failed, preventing further processing from + being performed using that credential structure. + + o GSS_BAD_SIG indicates that the received input_token contains an + incorrect signature, so context setup cannot be accomplished. + + o GSS_DUPLICATE_TOKEN indicates that the signature on the received + input_token was correct, but that the input_token was recognized + as a duplicate of an input_token already processed. No new context + is established. + + o GSS_OLD_TOKEN indicates that the signature on the received + input_token was correct, but that the input_token is too old to be + checked for duplication against previously-processed input_tokens. + No new context is established. + + o GSS_NO_CRED indicates that no context was established, either + because the input cred_handle was invalid, because the referenced + credentials are valid for context initiator use only, or because + the caller lacks authorization to access the referenced + credentials. + + + + +Linn [Page 27] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided + through the input acceptor_cred_handle argument are no longer + valid, so context establishment cannot be completed. + + o GSS_BAD_BINDINGS indicates that a mismatch between the caller- + provided chan_bindings and those extracted from the input_token + was detected, signifying a security-relevant event and preventing + context establishment. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided; this major status will be + returned only for successor calls following GSS_CONTINUE_NEEDED + status returns. + + o GSS_FAILURE indicates that context setup could not be accomplished + for reasons unspecified at the GSS-API level, and that no + interface-defined recovery action is available. + + The GSS_Accept_sec_context() routine is used by a context target. + Using information in the credentials structure referenced by the + input acceptor_cred_handle, it verifies the incoming input_token and + (following the successful completion of a context establishment + sequence) returns the authenticated src_name and the mech_type used. + The acceptor_cred_handle must correspond to the same valid + credentials structure on the initial call to GSS_Accept_sec_context() + and on any successor calls resulting from GSS_CONTINUE_NEEDED status + returns; different protocol sequences modeled by the + GSS_CONTINUE_NEEDED mechanism will require access to credentials at + different points in the context establishment sequence. + + The input_context_handle argument is 0, specifying "not yet + assigned", on the first GSS_Accept_sec_context() call relating to a + given context. That call returns an output_context_handle for future + references to this context; when continuation attempts to + GSS_Accept_sec_context() are needed to perform context + establishment, that handle value will be entered into the + input_context_handle argument. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The returned state results (deleg_state, mutual_state, + replay_det_state, and sequence_state) reflect the same context state + values as returned to GSS_Init_sec_context()'s caller at the + initiator system. + + + +Linn [Page 28] + +RFC 1508 Generic Security Interface September 1993 + + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + input to GSS_Seal() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_Sign() or GSS_Seal()) on + the established context. + + The lifetime_rec return value indicates the length of time for which + the context will be valid, expressed as an offset from the present. + The values of deleg_state, mutual_state, replay_det_state, + sequence_state, conf_avail, integ_avail, and lifetime_rec are + undefined unless the accompanying major_status indicates COMPLETE. + + The delegated_cred_handle result is significant only when deleg_state + is TRUE, and provides a means for the target to reference the + delegated credentials. The output_token result, when non-NULL, + provides a context-level token to be returned to the context + initiator to continue a multi-step context establishment sequence. As + noted with GSS_Init_sec_context(), any returned token should be + transferred to the context's peer (in this case, the context + initiator), independent of the value of the accompanying returned + major_status. + + Note: A target must be able to distinguish a context-level + input_token, which is passed to GSS_Accept_sec_context(), from the + per-message data elements passed to GSS_Verify() or GSS_Unseal(). + These data elements may arrive in a single application message, and + GSS_Accept_sec_context() must be performed before per-message + processing can be performed successfully. + +2.2.3. GSS_Delete_sec_context call + + Input: + + o context_handle INTEGER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_context_token OCTET STRING + + Return major_status codes: + + + + + +Linn [Page 29] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_COMPLETE indicates that the context was recognized, that + relevant context-specific information was flushed, and that the + returned output_context_token is ready for transfer to the + context's peer. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provide, so no deletion was performed. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Delete_sec_context() operation could not be performed for + reasons unspecified at the GSS-API level. + + This call may block pending network interactions for mech_types in + which active notification must be made to a central server when a + security context is to be deleted. + + This call can be made by either peer in a security context, to flush + context-specific information and to return an output_context_token + which can be passed to the context's peer informing it that the + peer's corresponding context information can also be flushed. (Once a + context is established, the peers involved are expected to retain + cached credential and context-related information until the + information's expiration time is reached or until a + GSS_Delete_sec_context() call is made.) Attempts to perform per- + message processing on a deleted context will result in error returns. + +2.2.4. GSS_Process_context_token call + + Inputs: + + o context_handle INTEGER, + + o input_context_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_context_token was + successfully processed in conjunction with the context referenced + by context_handle. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the received context_token failed, preventing further processing + + + +Linn [Page 30] + +RFC 1508 Generic Security Interface September 1993 + + + from being performed with that token. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Process_context_token() operation could not be performed for + reasons unspecified at the GSS-API level. + + This call is used to process context_tokens received from a peer once + a context has been established, with corresponding impact on + context-level state information. One use for this facility is + processing of the context_tokens generated by + GSS_Delete_sec_context(); GSS_Process_context_token() will not block + pending network interactions for that purpose. Another use is to + process tokens indicating remote-peer context establishment failures + after the point where the local GSS-API implementation has already + indicated GSS_COMPLETE status. + +2.2.5. GSS_Context_time call + + Input: + + o context_handle INTEGER, + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o lifetime_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + Return major_status codes: + + o GSS_COMPLETE indicates that the referenced context is valid, and + will remain valid for the amount of time indicated in + lifetime_rec. + + o GSS_CONTEXT_EXPIRED indicates that data items related to the + referenced context have expired. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + + +Linn [Page 31] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. + + This call is used to determine the amount of time for which a + currently established context will remain valid. + +2.3. Per-message calls + + This group of calls is used to perform per-message protection + processing on an established security context. None of these calls + block pending network interactions. These calls may be invoked by a + context's initiator or by the context's target. The four members of + this group should be considered as two pairs; the output from + GSS_Sign() is properly input to GSS_Verify(), and the output from + GSS_Seal() is properly input to GSS_Unseal(). + + GSS_Sign() and GSS_Verify() support data origin authentication and + data integrity services. When GSS_Sign() is invoked on an input + message, it yields a per-message token containing data items which + allow underlying mechanisms to provide the specified security + services. The original message, along with the generated per-message + token, is passed to the remote peer; these two data elements are + processed by GSS_Verify(), which validates the message in + conjunction with the separate token. + + GSS_Seal() and GSS_Unseal() support caller-requested confidentiality + in addition to the data origin authentication and data integrity + services offered by GSS_Sign() and GSS_Verify(). GSS_Seal() outputs + a single data element, encapsulating optionally enciphered user data + as well as associated token data items. The data element output from + GSS_Seal() is passed to the remote peer and processed by + GSS_Unseal() at that system. GSS_Unseal() combines decipherment (as + required) with validation of data items related to authentication and + integrity. + +2.3.1. GSS_Sign call + + Inputs: + + o context_handle INTEGER, + + o qop_req INTEGER,-0 specifies default QOP + + o message OCTET STRING + + Outputs: + + o major_status INTEGER, + + + +Linn [Page 32] + +RFC 1508 Generic Security Interface September 1993 + + + o minor_status INTEGER, + + o per_msg_token OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that a signature, suitable for an + established security context, was successfully applied and that + the message and corresponding per_msg_token are ready for + transmission. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + requested operation could not be performed for reasons unspecified + at the GSS-API level. + + Using the security context referenced by context_handle, apply a + signature to the input message (along with timestamps and/or other + data included in support of mech_type-specific mechanisms) and return + the result in per_msg_token. The qop_req parameter allows quality- + of-protection control. The caller passes the message and the + per_msg_token to the target. + + The GSS_Sign() function completes before the message and + per_msg_token is sent to the peer; successful application of + GSS_Sign() does not guarantee that a corresponding GSS_Verify() has + been (or can necessarily be) performed successfully when the message + arrives at the destination. + +2.3.2. GSS_Verify call + + Inputs: + + o context_handle INTEGER, + + o message OCTET STRING, + + o per_msg_token OCTET STRING + + + + +Linn [Page 33] + +RFC 1508 Generic Security Interface September 1993 + + + Outputs: + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_COMPLETE indicates that the message was successfully verified. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the received per_msg_token failed, preventing further processing + from being performed with that token. + + o GSS_BAD_SIG indicates that the received per_msg_token contains an + incorrect signature for the message. + + o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values + appear in conjunction with the optional per-message replay + detection features described in Section 1.2.3; their semantics are + described in that section. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Verify() operation could not be performed for reasons + unspecified at the GSS-API level. + + Using the security context referenced by context_handle, verify that + the input per_msg_token contains an appropriate signature for the + input message, and apply any active replay detection or sequencing + features. Return an indication of the quality-of-protection applied + to the processed message in the qop_state result. + + + + + + + + +Linn [Page 34] + +RFC 1508 Generic Security Interface September 1993 + + +2.3.3. GSS_Seal call + + Inputs: + + o context_handle INTEGER, + + o conf_req_flag BOOLEAN, + + o qop_req INTEGER,-0 specifies default QOP + + o input_message OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o conf_state BOOLEAN, + + o output_message OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_message was successfully + processed and that the output_message is ready for transmission. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Seal() operation could not be performed for reasons + unspecified at the GSS-API level. + + Performs the data origin authentication and data integrity functions + of GSS_Sign(). If the input conf_req_flag is TRUE, requests that + confidentiality be applied to the input_message. Confidentiality may + not be supported in all mech_types or by all implementations; the + returned conf_state flag indicates whether confidentiality was + provided for the input_message. The qop_req parameter allows + quality-of-protection control. + + + +Linn [Page 35] + +RFC 1508 Generic Security Interface September 1993 + + + In all cases, the GSS_Seal() call yields a single output_message + data element containing (optionally enciphered) user data as well as + control information. + +2.3.4. GSS_Unseal call + + Inputs: + + o context_handle INTEGER, + + o input_message OCTET STRING + + Outputs: + + o conf_state BOOLEAN, + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_message OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_message was successfully + processed and that the resulting output_message is available. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the per_msg_token extracted from the input_message failed, + preventing further processing from being performed. + + o GSS_BAD_SIG indicates that an incorrect signature was detected for + the message. + + o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values + appear in conjunction with the optional per-message replay + detection features described in Section 1.2.3; their semantics are + described in that section. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + + + +Linn [Page 36] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Unseal() operation could not be performed for reasons + unspecified at the GSS-API level. + + Processes a data element generated (and optionally enciphered) by + GSS_Seal(), provided as input_message. The returned conf_state value + indicates whether confidentiality was applied to the input_message. + If conf_state is TRUE, GSS_Unseal() deciphers the input_message. + Returns an indication of the quality-of-protection applied to the + processed message in the qop_state result. GSS_Seal() performs the + data integrity and data origin authentication checking functions of + GSS_Verify() on the plaintext data. Plaintext data is returned in + output_message. + +2.4. Support calls + + This group of calls provides support functions useful to GSS-API + callers, independent of the state of established contexts. Their + characterization with regard to blocking or non-blocking status in + terms of network interactions is unspecified. + +2.4.1. GSS_Display_status call + + Inputs: + + o status_value INTEGER,-GSS-API major_status or minor_status + return value + + o status_type INTEGER,-1 if major_status, 2 if minor_status + + o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_ + status translation + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o status_string_set SET OF OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid printable status + representation (possibly representing more than one status event + + + +Linn [Page 37] + +RFC 1508 Generic Security Interface September 1993 + + + encoded within the status_value) is available in the returned + status_string_set. + + o GSS_BAD_MECH indicates that translation in accordance with an + unsupported mech_type was requested, so translation could not be + performed. + + o GSS_BAD_STATUS indicates that the input status_value was invalid, + or that the input status_type carried a value other than 1 or 2, + so translation could not be performed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Provides a means for callers to translate GSS-API-returned major and + minor status codes into printable string representations. + +2.4.2. GSS_Indicate_mechs call + + Input: + + o (none) + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that a set of available mechanisms has + been returned in mech_set. + + o GSS_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to determine the set of mechanism types available on + the local system. This call is intended for support of specialized + callers who need to request non-default mech_type sets from + GSS_Acquire_cred(), and should not be needed by other callers. + +2.4.3. GSS_Compare_name call + + Inputs: + + + + +Linn [Page 38] + +RFC 1508 Generic Security Interface September 1993 + + + o name1 INTERNAL NAME, + + o name2 INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_equal BOOLEAN + + Return major_status codes: + + o GSS_COMPLETE indicates that name1 and name2 were comparable, and + that the name_equal result indicates whether name1 and name2 were + equal or unequal. + + o GSS_BAD_NAMETYPE indicates that one or both of name1 and name2 + contained internal type specifiers uninterpretable by the + supporting GSS-API implementation, or that the two names' types + are different and incomparable, so the equality comparison could + not be completed. + + o GSS_BAD_NAME indicates that one or both of the input names was + ill-formed in terms of its internal type specifier, so the + equality comparison could not be completed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to compare two internal name representations for + equality. + +2.4.4. GSS_Display_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_string OCTET STRING, + + + + +Linn [Page 39] + +RFC 1508 Generic Security Interface September 1993 + + + o name_type OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid printable name representation + is available in the returned name_string. + + o GSS_BAD_NAMETYPE indicates that the provided name was of a type + uninterpretable by the supporting GSS-API implementation, so no + printable representation could be generated. + + o GSS_BAD_NAME indicates that the contents of the provided name were + inconsistent with the internally-indicated name type, so no + printable representation could be generated. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to translate an internal name representation into a + printable form with associated namespace type descriptor. The syntax + of the printable form is a local matter. + +2.4.5. GSS_Import_name call + + Inputs: + + o input_name_string OCTET STRING, + + o input_name_type OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_name INTERNAL NAME + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid name representation is output + in output_name and described by the type value in + output_name_type. + + o GSS_BAD_NAMETYPE indicates that the input_name_type is unsupported + by the GSS-API implementation, so the import operation could not + be completed. + + + + +Linn [Page 40] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_BAD_NAME indicates that the provided input_name_string is + ill-formed in terms of the input_name_type, so the import + operation could not be completed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to provide a printable name representation, designate + the type of namespace in conjunction with which it should be parsed, + and convert that printable representation to an internal form + suitable for input to other GSS-API routines. The syntax of the + input_name is a local matter. + +2.4.6. GSS_Release_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + name was successfully released. + + o GSS_BAD_NAME indicates that the input name argument did not + contain a valid name. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an internal + name representation. + +2.4.7. GSS_Release_buffer call + + Inputs: + + o buffer OCTET STRING + + Outputs: + + o major_status INTEGER, + + + +Linn [Page 41] + +RFC 1508 Generic Security Interface September 1993 + + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + buffer was successfully released. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an OCTET STRING + buffer allocated by another GSS-API call. + +2.4.8. GSS_Release_oid_set call + + Inputs: + + o buffer SET OF OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + object identifier set was successfully released. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an object + identifier set object allocated by another GSS-API call. + +3. Mechanism-Specific Example Scenarios + + This section provides illustrative overviews of the use of various + candidate mechanism types to support the GSS-API. These discussions + are intended primarily for readers familiar with specific security + technologies, demonstrating how GSS-API functions can be used and + implemented by candidate underlying mechanisms. They should not be + regarded as constrictive to implementations or as defining the only + means through which GSS-API functions can be realized with a + particular underlying technology, and do not demonstrate all GSS-API + features with each technology. + + + + +Linn [Page 42] + +RFC 1508 Generic Security Interface September 1993 + + +3.1. Kerberos V5, single-TGT + + OS-specific login functions yield a TGT to the local realm Kerberos + server; TGT is placed in a credentials structure for the client. + Client calls GSS_Acquire_cred() to acquire a cred_handle in order to + reference the credentials for use in establishing security contexts. + + Client calls GSS_Init_sec_context(). If the requested service is + located in a different realm, GSS_Init_sec_context() gets the + necessary TGT/key pairs needed to traverse the path from local to + target realm; these data are placed in the owner's TGT cache. After + any needed remote realm resolution, GSS_Init_sec_context() yields a + service ticket to the requested service with a corresponding session + key; these data are stored in conjunction with the context. GSS-API + code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP + response(s) (in the successful case) or KRB_ERROR. + + Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted + KRB_AP_REQ message, and returns it in output_token. The client sends + the output_token to the service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which verifies the authenticator, provides + the service with the client's authenticated name, and returns an + output_context_handle. + + Both parties now hold the session key associated with the service + ticket, and can use this key in subsequent GSS_Sign(), GSS_Verify(), + GSS_Seal(), and GSS_Unseal() operations. + +3.2. Kerberos V5, double-TGT + + TGT acquisition as above. + + Note: To avoid unnecessary frequent invocations of error paths when + implementing the GSS-API atop Kerberos V5, it seems appropriate to + represent "single-TGT K-V5" and "double-TGT K-V5" with separate + mech_types, and this discussion makes that assumption. + + Based on the (specified or defaulted) mech_type, + GSS_Init_sec_context() determines that the double-TGT protocol + should be employed for the specified target. GSS_Init_sec_context() + returns GSS_CONTINUE_NEEDED major_status, and its returned + output_token contains a request to the service for the service's TGT. + (If a service TGT with suitably long remaining lifetime already + exists in a cache, it may be usable, obviating the need for this + step.) The client passes the output_token to the service. Note: this + scenario illustrates a different use for the GSS_CONTINUE_NEEDED + + + +Linn [Page 43] + +RFC 1508 Generic Security Interface September 1993 + + + status return facility than for support of mutual authentication; + note that both uses can coexist as successive operations within a + single context establishment operation. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which recognizes it as a request for TGT. + (Note that current Kerberos V5 defines no intra-protocol mechanism to + represent such a request.) GSS_Accept_sec_context() returns + GSS_CONTINUE_NEEDED major_status and provides the service's TGT in + its output_token. The service sends the output_token to the client. + + The client passes the received token as the input_token argument to a + continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches + the received service TGT and uses it as part of a service ticket + request to the Kerberos authentication server, storing the returned + service ticket and session key in conjunction with the context. + GSS_Init_sec_context() builds a Kerberos-formatted authenticator, + and returns it in output_token along with GSS_COMPLETE return + major_status. The client sends the output_token to the service. + + Service passes the received token as the input_token argument to a + continuation call to GSS_Accept_sec_context(). + GSS_Accept_sec_context() verifies the authenticator, provides the + service with the client's authenticated name, and returns + major_status GSS_COMPLETE. + + GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() as above. + +3.3. X.509 Authentication Framework + + This example illustrates use of the GSS-API in conjunction with + public-key mechanisms, consistent with the X.509 Directory + Authentication Framework. + + The GSS_Acquire_cred() call establishes a credentials structure, + making the client's private key accessible for use on behalf of the + client. + + The client calls GSS_Init_sec_context(), which interrogates the + Directory to acquire (and validate) a chain of public-key + certificates, thereby collecting the public key of the service. The + certificate validation operation determines that suitable signatures + were applied by trusted authorities and that those certificates have + not expired. GSS_Init_sec_context() generates a secret key for use + in per-message protection operations on the context, and enciphers + that secret key under the service's public key. + + The enciphered secret key, along with an authenticator quantity + + + +Linn [Page 44] + +RFC 1508 Generic Security Interface September 1993 + + + signed with the client's private key, is included in the output_token + from GSS_Init_sec_context(). The output_token also carries a + certification path, consisting of a certificate chain leading from + the service to the client; a variant approach would defer this path + resolution to be performed by the service instead of being asserted + by the client. The client application sends the output_token to the + service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the + certification path, and as a result determines a certified binding + between the client's distinguished name and the client's public key. + Given that public key, GSS_Accept_sec_context() can process the + input_token's authenticator quantity and verify that the client's + private key was used to sign the input_token. At this point, the + client is authenticated to the service. The service uses its private + key to decipher the enciphered secret key provided to it for per- + message protection operations on the context. + + The client calls GSS_Sign() or GSS_Seal() on a data message, which + causes per-message authentication, integrity, and (optional) + confidentiality facilities to be applied to that message. The service + uses the context's shared secret key to perform corresponding + GSS_Verify() and GSS_Unseal() calls. + +4. Related Activities + + In order to implement the GSS-API atop existing, emerging, and future + security mechanisms: + + object identifiers must be assigned to candidate GSS-API + mechanisms and the name types which they support + + concrete data element formats must be defined for candidate + mechanisms + + Calling applications must implement formatting conventions which will + enable them to distinguish GSS-API tokens from other data carried in + their application protocols. + + Concrete language bindings are required for the programming + environments in which the GSS-API is to be employed; such bindings + for the C language are available in an associated RFC. + + + + + + + + +Linn [Page 45] + +RFC 1508 Generic Security Interface September 1993 + + +5. Acknowledgments + + This proposal is the result of a collaborative effort. + Acknowledgments are due to the many members of the IETF Security Area + Advisory Group (SAAG) and the Common Authentication Technology (CAT) + Working Group for their contributions at meetings and by electronic + mail. Acknowledgments are also due to Kannan Alagappan, Doug Barlow, + Bill Brown, Cliff Kahn, Charlie Kaufman, Butler Lampson, Richard + Pitkin, Joe Tardo, and John Wray of Digital Equipment Corporation, + and John Carr, John Kohl, Jon Rochlis, Jeff Schiller, and Ted T'so of + MIT and Project Athena. Joe Pato and Bill Sommerfeld of HP/Apollo, + Walt Tuvell of OSF, and Bill Griffith and Mike Merritt of AT&T, + provided inputs which helped to focus and clarify directions. + Precursor work by Richard Pitkin, presented to meetings of the + Trusted Systems Interoperability Group (TSIG), helped to demonstrate + the value of a generic, mechanism-independent security service API. + +6. Security Considerations + + Security issues are discussed throughout this memo. + +7. Author's Address + + John Linn + Geer Zolot Associates + One Main St. + Cambridge, MA 02142 USA + + Phone: +1 617.374.3700 + Email: Linn@gza.com + + + + + + + + + + + + + + + + + + + + + +Linn [Page 46] + +RFC 1508 Generic Security Interface September 1993 + + +APPENDIX A + +PACS AND AUTHORIZATION SERVICES + + Consideration has been given to modifying the GSS-API service + interface to recognize and manipulate Privilege Attribute + Certificates (PACs) as in ECMA 138, carrying authorization data as a + side effect of establishing a security context, but no such + modifications have been incorporated at this time. This appendix + provides rationale for this decision and discusses compatibility + alternatives between PACs and the GSS-API which do not require that + PACs be made visible to GSS-API callers. + + Existing candidate mechanism types such as Kerberos and X.509 do not + incorporate PAC manipulation features, and exclusion of such + mechanisms from the set of candidates equipped to fully support the + GSS-API seems inappropriate. Inclusion (and GSS-API visibility) of a + feature supported by only a limited number of mechanisms could + encourage the development of ostensibly portable applications which + would in fact have only limited portability. + + The status quo, in which PACs are not visible across the GSS-API + interface, does not preclude implementations in which PACs are + carried transparently, within the tokens defined and used for certain + mech_types, and stored within peers' credentials and context-level + data structures. While invisible to API callers, such PACs could be + used by operating system or other local functions as inputs in the + course of mediating access requests made by callers. This course of + action allows dynamic selection of PAC contents, if such selection is + administratively-directed rather than caller-directed. + + In a distributed computing environment, authentication must span + different systems; the need for such authentication provides + motivation for GSS-API definition and usage. Heterogeneous systems in + a network can intercommunicate, with globally authenticated names + comprising the common bond between locally defined access control + policies. Access control policies to which authentication provides + inputs are often local, or specific to particular operating systems + or environments. If the GSS-API made particular authorization models + visible across its service interface, its scope of application would + become less general. The current GSS-API paradigm is consistent with + the precedent set by Kerberos, neither defining the interpretation of + authorization-related data nor enforcing access controls based on + such data. + + The GSS-API is a general interface, whose callers may reside inside + or outside any defined TCB or NTCB boundaries. Given this + characteristic, it appears more realistic to provide facilities which + + + +Linn [Page 47] + +RFC 1508 Generic Security Interface September 1993 + + + provide "value-added" security services to its callers than to offer + facilities which enforce restrictions on those callers. Authorization + decisions must often be mediated below the GSS-API level in a local + manner against (or in spite of) applications, and cannot be + selectively invoked or omitted at those applications' discretion. + Given that the GSS-API's placement prevents it from providing a + comprehensive solution to the authorization issue, the value of a + partial contribution specific to particular authorization models is + debatable. + +APPENDIX B + +MECHANISM-INDEPENDENT TOKEN FORMAT + + This appendix specifies a mechanism-independent level of + encapsulating representation for the initial token of a GSS-API + context establishment sequence, incorporating an identifier of the + mechanism type to be used on that context. Use of this format (with + ASN.1-encoded data elements represented in BER, constrained in the + interests of parsing simplicity to the Distinguished Encoding Rule + (DER) BER subset defined in X.509, clause 8.7) is recommended to the + designers of GSS-API implementations based on various mechanisms, so + that tokens can be interpreted unambiguously at GSS-API peers. There + is no requirement that the mechanism-specific innerContextToken, + innerMsgToken, and sealedUserData data elements be encoded in ASN.1 + BER. + + -- optional top-level token definitions to + -- frame different mechanisms + + GSS-API DEFINITIONS ::= + + BEGIN + + MechType ::= OBJECT IDENTIFIER + -- data structure definitions + + -- callers must be able to distinguish among + -- InitialContextToken, SubsequentContextToken, + -- PerMsgToken, and SealedMessage data elements + -- based on the usage in which they occur + + InitialContextToken ::= + -- option indication (delegation, etc.) indicated within + -- mechanism-specific token + [APPLICATION 0] IMPLICIT SEQUENCE { + thisMech MechType, + innerContextToken ANY DEFINED BY thisMech + + + +Linn [Page 48] + +RFC 1508 Generic Security Interface September 1993 + + + -- contents mechanism-specific + } + + SubsequentContextToken ::= innerContextToken ANY + -- interpretation based on predecessor InitialContextToken + + PerMsgToken ::= + -- as emitted by GSS_Sign and processed by GSS_Verify + innerMsgToken ANY + + SealedMessage ::= + -- as emitted by GSS_Seal and processed by GSS_Unseal + -- includes internal, mechanism-defined indicator + -- of whether or not encrypted + sealedUserData ANY + + END + +APPENDIX C + +MECHANISM DESIGN CONSTRAINTS + + The following constraints on GSS-API mechanism designs are adopted in + response to observed caller protocol requirements, and adherence + thereto is anticipated in subsequent descriptions of GSS-API + mechanisms to be documented in standards-track Internet + specifications. + + Use of the approach defined in Appendix B of this specification, + applying a mechanism type tag to the InitialContextToken, is + required. + + It is strongly recommended that mechanisms offering per-message + protection services also offer at least one of the replay detection + and sequencing services, as mechanisms offering neither of the latter + will fail to satisfy recognized requirements of certain candidate + caller protocols. + + + + + + + + + + + + + + +Linn [Page 49] + \ No newline at end of file diff --git a/doc/rfc1509.txt b/doc/rfc1509.txt new file mode 100644 index 000000000..f36cd80e6 --- /dev/null +++ b/doc/rfc1509.txt @@ -0,0 +1,2691 @@ + + + + + + +Network Working Group J. Wray +Request for Comments: 1509 Digital Equipment Corporation + September 1993 + + + Generic Security Service API : C-bindings + +Status of this Memo + + This RFC specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" for the standardization state and status + of this protocol. Distribution of this memo is unlimited. + +Abstract + + This document specifies C language bindings for the Generic Security + Service Application Program Interface (GSS-API), which is described + at a language-independent conceptual level in other documents. + + The Generic Security Service Application Programming Interface (GSS- + API) provides security services to its callers, and is intended for + implementation atop alternative 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. + +1. INTRODUCTION + + The Generic Security Service Application Programming Interface [1] + provides security services to calling applications. It allows a + communicating application to authenticate the user associated with + another application, to delegate rights to another application, and + to apply security services such as confidentiality and integrity on a + per-message basis. + + There are four stages to using the GSSAPI: + + (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 the local username under which it is running. + + + + + +Wray [Page 1] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + (b) A pair of communicating applications establish a joint security + context using their credentials. The security context is a + pair of GSSAPI data structures that contain shared state + information, which is required in order that per-message + security services may be provided. 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. This transfer of rights is termed + delegation, and is achieved by creating a set of credentials, + similar to those used by the originating application, but which + may be used by the responder. To establish and maintain the + shared information that makes up the security context, certain + GSSAPI calls will return a token data structure, which is a + cryptographically protected opaque data type. The caller of + such a GSSAPI routine is responsible for transferring the token + to the peer application, which should then pass it to a + corresponding GSSAPI routine which will decode it and extract + the information. + + (c) Per-message services are invoked to apply either: + + (i) integrity and data origin authentication, or + + (ii) confidentiality, integrity and data origin authentication + to application data, which are treated by GSSAPI as + arbitrary octet-strings. The application transmitting a + message that it wishes to protect will call the appropriate + GSSAPI routine (sign or seal) to apply protection, specifying + the appropriate security context, and send the result to the + receiving application. The receiver will pass the received + data to the corresponding decoding routine (verify or unseal) + to remove the protection and validate the data. + + (d) At the completion of a communications session (which may extend + across several connections), the peer applications call GSSAPI + routines to delete the security context. Multiple contexts may + also be used (either successively or simultaneously) within a + single communications association. + +2. GSSAPI Routines + + This section lists the functions performed by each of the GSSAPI + routines and discusses their major parameters, describing how they + are to be passed to the routines. The routines are listed in figure + 4-1. + + + + +Wray [Page 2] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Figure 4-1 GSSAPI Routines + + + Routine Function + + gss_acquire_cred Assume a global identity + + gss_release_cred Discard credentials + + gss_init_sec_context Initiate a security context + with a peer application + + gss_accept_sec_context Accept a security context + initiated by a peer + application + + gss_process_context_token Process a token on a security + context from a peer + application + + gss_delete_sec_context Discard a security context + + gss_context_time Determine for how long a + context will remain valid + + gss_sign Sign a message; integrity + service + + gss_verify Check signature on a message + + gss_seal Sign (optionally encrypt) a + message; confidentiality + service + + gss_unseal Verify (optionally decrypt) + message + + gss_display_status Convert an API status code + to text + + gss_indicate_mechs Determine underlying + authentication mechanism + + gss_compare_name Compare two internal-form + names + + gss_display_name Convert opaque name to text + + + + +Wray [Page 3] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + gss_import_name Convert a textual name to + internal-form + + gss_release_name Discard an internal-form + name + + gss_release_buffer Discard a buffer + + gss_release_oid_set Discard a set of object + identifiers + + gss_inquire_cred Determine information about + a credential + + Individual GSSAPI 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. + +2.1. Data Types and Calling Conventions + + The following conventions are used by the GSSAPI: + +2.1.1. Structured data types + + Wherever these GSSAPI C-bindings describe structured data, only + fields that must be provided by all GSSAPI implementation are + documented. Individual implementations may provide additional + fields, either for internal use within GSSAPI routines, or for use by + non-portable applications. + +2.1.2. Integer types + + GSSAPI defines the following integer data type: + + OM_uint32 32-bit unsigned integer + + Where guaranteed minimum bit-count is important, this portable data + type is used by the GSSAPI routine definitions. Individual GSSAPI + implementations will include appropriate typedef definitions to map + this type onto a built-in data type. + +2.1.3. String and similar data + + Many of the GSSAPI routines take arguments and return values that + describe contiguous multiple-byte data. All such data is passed + between the GSSAPI and the caller using the gss_buffer_t data type. + + + +Wray [Page 4] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + This data type is a pointer to a buffer descriptor, which consists of + a length field that contains the total number of bytes in the datum, + and a value field which contains a pointer to the actual datum: + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + Storage for data passed to the application by a GSSAPI routine using + the gss_buffer_t conventions is allocated by the GSSAPI routine. The + application may free this storage by invoking the gss_release_buffer + routine. Allocation of the gss_buffer_desc object is always the + responsibility of the application; Unused gss_buffer_desc objects + may be initialized to the value GSS_C_EMPTY_BUFFER. + +2.1.3.1. Opaque data types + + Certain multiple-word data items are considered opaque data types at + the GSSAPI, because their internal structure has no significance + either to the GSSAPI or to the caller. Examples of such opaque data + types are the input_token parameter to gss_init_sec_context (which is + opaque to the caller), and the input_message parameter to gss_seal + (which is opaque to the GSSAPI). Opaque data is passed between the + GSSAPI and the application using the gss_buffer_t datatype. + +2.1.3.2. Character strings + + Certain multiple-word data items may be regarded as simple ISO + Latin-1 character strings. An example of this is the + input_name_buffer parameter to gss_import_name. Some GSSAPI routines + also return character strings. Character strings are passed between + the application and the GSSAPI using the gss_buffer_t datatype, + defined earlier. + +2.1.4. Object Identifiers + + Certain GSSAPI procedures take parameters of the type gss_OID, or + Object identifier. This is a type containing ISO-defined tree- + structured values, and is used by the GSSAPI caller to select an + underlying security mechanism. A value of type gss_OID has the + following structure: + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + + + +Wray [Page 5] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The elements field of this structure points to the first byte of an + octet string containing the ASN.1 BER encoding of the value of the + gss_OID. The length field contains the number of bytes in this + value. For example, the gss_OID value corresponding to {iso(1) + identified- oganization(3) icd-ecma(12) member-company(2) dec(1011) + cryptoAlgorithms(7) SPX(5)} meaning SPX (Digital's X.509 + authentication mechanism) has a length field of 7 and an elements + field pointing to seven octets containing the following octal values: + 53,14,2,207,163,7,5. GSSAPI implementations should provide constant + gss_OID values to allow callers to request any supported mechanism, + although applications are encouraged on portability grounds to accept + the default mechanism. gss_OID values should also be provided to + allow applications to specify particular name types (see section + 2.1.10). Applications should treat gss_OID_desc values returned by + GSSAPI routines as read-only. In particular, the application should + not attempt to deallocate them. The gss_OID_desc datatype is + equivalent to the X/Open OM_object_identifier datatype [2]. + +2.1.5. Object Identifier Sets + + Certain GSSAPI procedures take parameters of the type gss_OID_set. + This type represents one or more object identifiers (section 2.1.4). + A gss_OID_set object has the following structure: + + typedef struct gss_OID_set_desc_struct { + int count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + The count field contains the number of OIDs within the set. The + elements field is a pointer to an array of gss_OID_desc objects, each + of which describes a single OID. gss_OID_set values are used to name + the available mechanisms supported by the GSSAPI, to request the use + of specific mechanisms, and to indicate which mechanisms a given + credential supports. Storage associated with gss_OID_set values + returned to the application by the GSSAPI may be deallocated by the + gss_release_oid_set routine. + +2.1.6. Credentials + + A credential handle is a caller-opaque atomic datum that identifies a + GSSAPI credential data structure. It is represented by the caller- + opaque type gss_cred_id_t, which may be implemented as either an + arithmetic or a pointer type. Credentials describe a principal, and + they give their holder the ability to act as that principal. The + GSSAPI does not make the actual credentials available to + applications; instead the credential handle is used to identify a + particular credential, held internally by GSSAPI or underlying + + + +Wray [Page 6] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + mechanism. Thus the credential handle contains no security-relavent + information, and requires no special protection by the application. + Depending on the implementation, a given credential handle may refer + to different credentials when presented to the GSSAPI by different + callers. Individual GSSAPI implementations should define both the + scope of a credential handle and the scope of a credential itself + (which must be at least as wide as that of a handle). Possibilities + for credential handle scope include the process that acquired the + handle, the acquiring process and its children, or all processes + sharing some local identification information (e.g., UID). If no + handles exist by which a given credential may be reached, the GSSAPI + may delete the credential. + + Certain routines allow credential handle parameters to be omitted to + indicate the use of a default credential. The mechanism by which a + default credential is established and its scope should be defined by + the individual GSSAPI implementation. + +2.1.7. Contexts + + The gss_ctx_id_t data type contains a caller-opaque atomic value that + identifies one end of a GSSAPI security context. It may be + implemented as either an arithmetic or a pointer type. Depending on + the implementation, a given gss_ctx_id_t value may refer to different + GSSAPI security contexts when presented to the GSSAPI by different + callers. The security context holds state information about each end + of a peer communication, including cryptographic state information. + Individual GSSAPI implementations should define the scope of a + context. Since no way is provided by which a new gss_ctx_id_t value + may be obtained for an existing context, the scope of a context + should be the same as the scope of a gss_ctx_id_t. + +2.1.8. Authentication tokens + + A token is a caller-opaque type that GSSAPI uses to maintain + synchronization between the context data structures at each end of a + GSSAPI security context. The token is a cryptographically protected + bit-string, generated by the underlying mechanism at one end of a + GSSAPI security context for use by the peer mechanism at the other + end. Encapsulation (if required) and transfer of the token are the + responsibility of the peer applications. A token is passed between + the GSSAPI and the application using the gss_buffer_t conventions. + +2.1.9. Status values + + One or more status codes are returned by each GSSAPI routine. Two + distinct sorts of status codes are returned. These are termed GSS + status codes and Mechanism status codes. + + + +Wray [Page 7] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +2.1.9.1. GSS status codes + + GSSAPI routines return GSS status codes as their OM_uint32 function + value. These codes indicate errors that are independent of the + underlying mechanism used to provide the security service. The + errors that can be indicated via a GSS status code are either generic + API routine errors (errors that are defined in the GSSAPI + specification) or calling errors (errors that are specific to these + bindings). + + A GSS status code can indicate a single fatal generic API error from + the routine and a single calling error. In addition, supplementary + status information may be indicated via the setting of bits in the + supplementary info field of a GSS status code. + + These errors are encoded into the 32-bit GSS status code as follows: + + MSB LSB + |------------------------------------------------------------| + | Calling Error | Routine Error | Supplementary Info | + |------------------------------------------------------------| + Bit 31 24 23 16 15 0 + + Hence if a GSSAPI routine returns a GSS status code whose upper 16 + bits contain a non-zero value, the call failed. If the calling error + field is non-zero, the invoking application's call of the routine was + erroneous. Calling errors are defined in table 5-1. If the routine + error field is non-zero, the routine failed for one of the routine- + specific reasons listed below in table 5-2. Whether or not the upper + 16 bits indicate a failure or a success, the routine may indicate + additional information by setting bits in the supplementary info + field of the status code. The meaning of individual bits is listed + below in table 5-3. + + Table 5-1 Calling Errors + + Name Value in Meaning + Field + GSS_S_CALL_INACCESSIBLE_READ 1 A required input + parameter could + not be read. + GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output + parameter could + not be written. + GSS_S_CALL_BAD_STRUCTURE 3 A parameter was + malformed + + + + + +Wray [Page 8] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Table 5-2 Routine Errors + + Name Value in Meaning + Field + + GSS_S_BAD_MECH 1 An unsupported mechanism was + requested + GSS_S_BAD_NAME 2 An invalid name was supplied + GSS_S_BAD_NAMETYPE 3 A supplied name was of an + unsupported type + GSS_S_BAD_BINDINGS 4 Incorrect channel bindings + were supplied + GSS_S_BAD_STATUS 5 An invalid status code was + supplied + + GSS_S_BAD_SIG 6 A token had an invalid + signature + GSS_S_NO_CRED 7 No credentials were supplied + GSS_S_NO_CONTEXT 8 No context has been + established + GSS_S_DEFECTIVE_TOKEN 9 A token was invalid + GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid + GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials + have expired + GSS_S_CONTEXT_EXPIRED 12 The context has expired + GSS_S_FAILURE 13 Miscellaneous failure + (see text) + + Table 5-3 Supplementary Status Bits + + Name Bit Number Meaning + GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called + again to complete its + function. + See routine documentation for + detailed description. + GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of + an earlier token + GSS_S_OLD_TOKEN 2 The token's validity period + has expired + GSS_S_UNSEQ_TOKEN 3 A later token has already been + processed + + The routine documentation also uses the name GSS_S_COMPLETE, which is + a zero value, to indicate an absence of any API errors or + supplementary information bits. + + + + + +Wray [Page 9] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + All GSS_S_xxx symbols equate to complete OM_uint32 status codes, + rather than to bitfield values. For example, the actual value of the + symbol GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 + << 16. + + The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and + GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS + status code and removes all but the relevant field. For example, the + value obtained by applying GSS_ROUTINE_ERROR to a status code removes + the calling errors and supplementary info fields, leaving only the + routine errors field. The values delivered by these macros may be + directly compared with a GSS_S_xxx symbol of the appropriate type. + The macro GSS_ERROR() is also provided, which when applied to a GSS + status code returns a non-zero value if the status code indicated a + calling or routine error, and a zero value otherwise. + + A GSSAPI implementation may choose to signal calling errors in a + platform-specific manner instead of, or in addition to the routine + value; routine errors and supplementary info should be returned via + routine status values only. + +2.1.9.2. Mechanism-specific status codes + + GSSAPI routines return a minor_status parameter, which is used to + indicate specialized errors from the underlying security mechanism. + This parameter may contain a single mechanism-specific error, + indicated by a OM_uint32 value. + + The minor_status parameter will always be set by a GSSAPI routine, + even if it returns a calling error or one of the generic API errors + indicated above as fatal, although other output parameters may remain + unset in such cases. However, output parameters that are expected to + return pointers to storage allocated by a routine must always set set + by the routine, even in the event of an error, although in such cases + the GSSAPI routine may elect to set the returned parameter value to + NULL to indicate that no storage was actually allocated. Any length + field associated with such pointers (as in a gss_buffer_desc + structure) should also be set to zero in such cases. + + The GSS status code GSS_S_FAILURE is used to indicate that the + underlying mechanism detected an error for which no specific GSS + status code is defined. The mechanism status code will provide more + details about the error. + +2.1.10. Names + + A name is used to identify a person or entity. GSSAPI authenticates + the relationship between a name and the entity claiming the name. + + + +Wray [Page 10] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Two distinct representations are defined for names: + + (a) A printable form, for presentation to a user + + (b) An internal form, for presentation at the API + + The syntax of a printable name is defined by the GSSAPI + implementation, and may be dependent on local system configuration, + or on individual user preference. The internal form provides a + canonical representation of the name that is independent of + configuration. + + A given GSSAPI implementation may support names drawn from multiple + namespaces. In such an implementation, the internal form of the name + must include fields that identify the namespace from which the name + is drawn. The namespace from which a printable name is drawn is + specified by an accompanying object identifier. + + Routines (gss_import_name and gss_display_name) are provided to + convert names between their printable representations and the + gss_name_t type. gss_import_name may support multiple syntaxes for + each supported namespace, allowing users the freedom to choose a + preferred name representation. gss_display_name should use an + implementation-chosen preferred syntax for each supported name-type. + + Comparison of internal-form names is accomplished via the + gss_compare_names routine. This removes the need for the application + program to understand the syntaxes of the various printable names + that a given GSSAPI implementation may support. + + Storage is allocated by routines that return gss_name_t values. A + procedure, gss_release_name, is provided to free storage associated + with a name. + +2.1.11. Channel Bindings + + GSSAPI supports the use of user-specified tags to identify a given + context to the peer application. These tags are used to identify the + particular communications channel that carries the context. Channel + bindings are communicated to the GSSAPI using the following + structure: + + + + + + + + + + +Wray [Page 11] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + The initiator_addrtype and acceptor_addrtype fields denote the type + of addresses contained in the initiator_address and acceptor_address + buffers. The address type should be one of the following: + + GSS_C_AF_UNSPEC Unspecified address type + GSS_C_AF_LOCAL Host-local address type + GSS_C_AF_INET DARPA Internet address type + GSS_C_AF_IMPLINK ARPAnet IMP address type (eg IP) + GSS_C_AF_PUP pup protocols (eg BSP) address type + GSS_C_AF_CHAOS MIT CHAOS protocol address type + GSS_C_AF_NS XEROX NS address type + GSS_C_AF_NBS nbs address type + GSS_C_AF_ECMA ECMA address type + GSS_C_AF_DATAKIT datakit protocols address type + GSS_C_AF_CCITT CCITT protocols (eg X.25) + GSS_C_AF_SNA IBM SNA address type + GSS_C_AF_DECnet DECnet address type + GSS_C_AF_DLI Direct data link interface address type + GSS_C_AF_LAT LAT address type + GSS_C_AF_HYLINK NSC Hyperchannel address type + GSS_C_AF_APPLETALK AppleTalk address type + GSS_C_AF_BSC BISYNC 2780/3780 address type + GSS_C_AF_DSS Distributed system services address type + GSS_C_AF_OSI OSI TP4 address type + GSS_C_AF_X25 X25 + GSS_C_AF_NULLADDR No address specified + + Note that these name address families rather than specific addressing + formats. For address families that contain several alternative + address forms, the initiator_address and acceptor_address fields must + contain sufficient information to determine which address form is + used. When not otherwise specified, addresses should be specified in + network byte-order. + + Conceptually, the GSSAPI concatenates the initiator_addrtype, + initiator_address, acceptor_addrtype, acceptor_address and + application_data to form an octet string. The mechanism signs this + octet string, and binds the signature to the context establishment + token emitted by gss_init_sec_context. The same bindings are + presented by the context acceptor to gss_accept_sec_context, and a + + + +Wray [Page 12] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + signature is calculated in the same way. The calculated signature is + compared with that found in the token, and if the signatures differ, + gss_accept_sec_context will return a GSS_S_BAD_BINDINGS error, and + the context will not be established. Some mechanisms may include the + actual channel binding data in the token (rather than just a + signature); applications should therefore not use confidential data + as channel-binding components. Individual mechanisms may impose + additional constraints on addresses and address types that may appear + in channel bindings. For example, a mechanism may verify that the + initiator_address field of the channel bindings presented to + gss_init_sec_context contains the correct network address of the host + system. + +2.1.12. Optional parameters + + Various parameters are described as optional. This means that they + follow a convention whereby a default value may be requested. The + following conventions are used for omitted parameters. These + conventions apply only to those parameters that are explicitly + documented as optional. + +2.1.12.1. gss_buffer_t types + + Specify GSS_C_NO_BUFFER as a value. For an input parameter this + signifies that default behavior is requested, while for an output + parameter it indicates that the information that would be returned + via the parameter is not required by the application. + +2.1.12.2. Integer types (input) + + Individual parameter documentation lists values to be used to + indicate default actions. + +2.1.12.3. Integer types (output) + + Specify NULL as the value for the pointer. + +2.1.12.4. Pointer types + + Specify NULL as the value. + +2.1.12.5. Object IDs + + Specify GSS_C_NULL_OID as the value. + +2.1.12.6. Object ID Sets + + Specify GSS_C_NULL_OID_SET as the value. + + + +Wray [Page 13] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +2.1.12.7. Credentials + + Specify GSS_C_NO_CREDENTIAL to use the default credential handle. + +2.1.12.8. Channel Bindings + + Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings + are not to be used. + +3. GSSAPI routine descriptions + +2.1. gss_acquire_cred + + OM_uint32 gss_acquire_cred ( + OM_uint32 * minor_status, + gss_name_t desired_name, + OM_uint32 time_req, + gss_OID_set desired_mechs, + int cred_usage, + gss_cred_id_t * output_cred_handle, + gss_OID_set * actual_mechs, + OM_int32 * time_rec) + Purpose: + + Allows an application to acquire a handle for a pre-existing + credential by name. GSSAPI implementations must impose a local + access-control policy on callers of this routine to prevent + unauthorized callers from acquiring credentials to which they are not + entitled. This routine is not intended to provide a "login to the + network" function, as such a function would result in the creation of + new credentials rather than merely acquiring a handle to existing + credentials. Such functions, if required, should be defined in + implementation-specific extensions to the API. + + If credential acquisition is time-consuming for a mechanism, the + mechanism may chooses to delay the actual acquisition until the + credential is required (e.g., by gss_init_sec_context or + gss_accept_sec_context). Such mechanism-specific implementation + decisions should be invisible to the calling application; thus a call + of gss_inquire_cred immediately following the call of + gss_acquire_cred must return valid credential data, and may therefore + incur the overhead of a deferred credential acquisition. + + Parameters: + + desired_name gss_name_t, read + Name of principal whose credential + should be acquired + + + +Wray [Page 14] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + time_req integer, read + number of seconds that credentials + should remain valid + + desired_mechs Set of Object IDs, read + set of underlying security mechanisms that + may be used. GSS_C_NULL_OID_SET may be used + to obtain an implementation-specific default. + + cred_usage integer, read + GSS_C_BOTH - Credentials may be used + either to initiate or accept + security contexts. + GSS_C_INITIATE - Credentials will only be + used to initiate security + contexts. + GSS_C_ACCEPT - Credentials will only be used to + accept security contexts. + + output_cred_handle gss_cred_id_t, modify + The returned credential handle. + + actual_mechs Set of Object IDs, modify, optional + The set of mechanisms for which the + credential is valid. Specify NULL + if not required. + + time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid. If the + implementation does not support expiration of + credentials, the value GSS_C_INDEFINITE will + be returned. Specify NULL if not required + + minor_status Integer, modify + Mechanism specific status code. + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Unavailable mechanism requested + + GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is + not supported + + GSS_S_BAD_NAME Value supplied for desired_name parameter is + + + +Wray [Page 15] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ill-formed. + + GSS_S_FAILURE Unspecified failure. The minor_status parameter + contains more detailed information + +3.2. gss_release_cred + + OM_uint32 gss_release_cred ( + OM_uint32 * minor_status, + gss_cred_id_t * cred_handle) + + Purpose: + + Informs GSSAPI that the specified credential handle is no longer + required by the process. When all processes have released a + credential, it will be deleted. + + Parameters: + + cred_handle gss_cred_id_t, modify, optional + buffer containing opaque credential + handle. If GSS_C_NO_CREDENTIAL is supplied, + the default credential will be released + + minor_status integer, modify + Mechanism specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED Credentials could not be accessed. + + + + + + + + + + + + + + + + + +Wray [Page 16] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.3. gss_init_sec_context + + OM_uint32 gss_init_sec_context ( + OM_uint32 * minor_status, + gss_cred_id_t claimant_cred_handle, + gss_ctx_id_t * context_handle, + gss_name_t target_name, + gss_OID mech_type, + int req_flags, + int time_req, + gss_channel_bindings_t + input_chan_bindings, + gss_buffer_t input_token + gss_OID * actual_mech_type, + gss_buffer_t output_token, + int * ret_flags, + OM_uint32 * time_rec ) + + Purpose: + + Initiates the establishment of a security context between the + application and a remote peer. Initially, the input_token parameter + should be specified as GSS_C_NO_BUFFER. The routine may return a + output_token which should be transferred to the peer application, + where the peer application will present it to gss_accept_sec_context. + If no token need be sent, gss_init_sec_context will indicate this by + setting the length field of the output_token argument to zero. To + complete the context establishment, one or more reply tokens may be + required from the peer application; if so, gss_init_sec_context will + return a status indicating GSS_S_CONTINUE_NEEDED in which case it + should be called again when the reply token is received from the peer + application, passing the token to gss_init_sec_context via the + input_token parameters. + + The values returned via the ret_flags and time_rec parameters are not + defined unless the routine returns GSS_S_COMPLETE. + + Parameters: + + claimant_cred_handle gss_cred_id_t, read, optional + handle for credentials claimed. Supply + GSS_C_NO_CREDENTIAL to use default + credentials. + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned by first call in continuation calls. + + + +Wray [Page 17] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + target_name gss_name_t, read + Name of target + + mech_type OID, read, optional + Object ID of desired mechanism. Supply + GSS_C_NULL_OID to obtain an implementation + specific default + + req_flags bit-mask, read + Contains four independent flags, each of + which requests that the context support a + specific service option. Symbolic + names are provided for each flag, and the + symbolic names corresponding to the required + flags should be logically-ORed + together to form the bit-mask value. The + flags are: + + GSS_C_DELEG_FLAG + True - Delegate credentials to remote peer + False - Don't delegate + GSS_C_MUTUAL_FLAG + True - Request that remote peer + authenticate itself + False - Authenticate self to remote peer + only + GSS_C_REPLAY_FLAG + True - Enable replay detection for signed + or sealed messages + False - Don't attempt to detect + replayed messages + GSS_C_SEQUENCE_FLAG + True - Enable detection of out-of-sequence + signed or sealed messages + False - Don't attempt to detect + out-of-sequence messages + + time_req integer, read + Desired number of seconds for which context + should remain valid. Supply 0 to request a + default validity period. + + input_chan_bindings channel bindings, read + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. + + + + +Wray [Page 18] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + input_token buffer, opaque, read, optional (see text) + Token received from peer application. + Supply GSS_C_NO_BUFFER on initial call. + + actual_mech_type OID, modify + actual mechanism used. + + output_token buffer, opaque, modify + token to be sent to peer application. If + the length field of the returned buffer is + zero, no token need be sent to the peer + application. + + ret_flags bit-mask, modify + Contains six independent flags, each of which + indicates that the context supports a specific + service option. Symbolic names are provided + for each flag, and the symbolic names + corresponding to the required flags should be + logically-ANDed with the ret_flags value to test + whether a given option is supported by the + context. The flags are: + + GSS_C_DELEG_FLAG + True - Credentials were delegated to + the remote peer + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer has been asked to + authenticated itself + False - Remote peer has not been asked to + authenticate itself + GSS_C_REPLAY_FLAG + True - replay of signed or sealed messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence signed or sealed + messages will be detected + False - out-of-sequence messages will not + be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be + invoked by calling seal routine + False - No confidentiality service (via + seal) available. seal will provide + message encapsulation, data-origin + + + +Wray [Page 19] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + authentication and integrity + services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_sign or gss_seal + routines. + False - Per-message integrity service + unavailable. + + time_rec integer, modify, optional + number of seconds for which the context + will remain valid. If the implementation does + not support credential expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + minor_status integer, modify + Mechanism specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer + application is required to complete thecontext, and + that gss_init_sec_context must be called again with + that token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on + the input_token failed + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks + performed on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for context + initiation, or the credential handle did not + reference any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired + + GSS_S_BAD_BINDINGS The input_token contains different channel + bindings to those specified via the + input_chan_bindings parameter + + GSS_S_BAD_SIG The input_token contains an invalid signature, or a + signature that could not be verified + + + +Wray [Page 20] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error + during context establishment + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of + a token already processed. This is a fatal error + during context establishment. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did not + refer to a valid context + + GSS_S_BAD_NAMETYPE The provided target_name parameter contained an + invalid or unsupported type of name + + GSS_S_BAD_NAME The provided target_name parameter was ill-formed. + + GSS_S_FAILURE Failure. See minor_status for more information + +3.4. gss_accept_sec_context + + OM_uint32 gss_accept_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_cred_id_t verifier_cred_handle, + gss_buffer_t input_token_buffer + gss_channel_bindings_t + input_chan_bindings, + gss_name_t * src_name, + gss_OID * mech_type, + gss_buffer_t output_token, + int * ret_flags, + OM_uint32 * time_rec, + gss_cred_id_t * delegated_cred_handle) + + Purpose: + + Allows a remotely initiated security context between the application + and a remote peer to be established. The routine may return a + output_token which should be transferred to the peer application, + where the peer application will present it to gss_init_sec_context. + If no token need be sent, gss_accept_sec_context will indicate this + by setting the length field of the output_token argument to zero. To + complete the context establishment, one or more reply tokens may be + required from the peer application; if so, gss_accept_sec_context + will return a status flag of GSS_S_CONTINUE_NEEDED, in which case it + should be called again when the reply token is received from the peer + application, passing the token to gss_accept_sec_context via the + input_token parameters. + + + + +Wray [Page 21] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The values returned via the src_name, ret_flags, time_rec, and + delegated_cred_handle parameters are not defined unless the routine + returns GSS_S_COMPLETE. + + Parameters: + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned in subsequent calls. + + verifier_cred_handle gss_cred_id_t, read, optional + Credential handle claimed by context + acceptor. + Specify GSS_C_NO_CREDENTIAL to use default + credentials. If GSS_C_NO_CREDENTIAL is + specified, but the caller has no default + credentials established, an + implementation-defined default credential + may be used. + + input_token_buffer buffer, opaque, read + token obtained from remote application + + input_chan_bindings channel bindings, read + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. + + src_name gss_name_t, modify, optional + Authenticated name of context initiator. + After use, this name should be deallocated by + passing it to gss_release_name. If not required, + specify NULL. + + mech_type Object ID, modify + Security mechanism used. The returned + OID value will be a pointer into static + storage, and should be treated as read-only + by the caller. + + output_token buffer, opaque, modify + Token to be passed to peer application. If the + length field of the returned token buffer is 0, + then no token need be passed to the peer + application. + + + + +Wray [Page 22] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ret_flags bit-mask, modify + Contains six independent flags, each of + which indicates that the context supports a + specific service option. Symbolic names are + provided for each flag, and the symbolic names + corresponding to the required flags + should be logically-ANDed with the ret_flags + value to test whether a given option is + supported by the context. The flags are: + GSS_C_DELEG_FLAG + True - Delegated credentials are available + via the delegated_cred_handle + parameter + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer asked for mutual + authentication + False - Remote peer did not ask for mutual + authentication + GSS_C_REPLAY_FLAG + True - replay of signed or sealed messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence signed or sealed + messages will be detected + False - out-of-sequence messages will not + be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be + invoked by calling seal routine + False - No confidentiality service (via + seal) available. seal will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked + by calling either gss_sign or + gss_seal routines. + False - Per-message integrity service + unavailable. + + time_rec integer, modify, optional + number of seconds for which the context + will remain valid. Specify NULL if not required. + + + + +Wray [Page 23] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + delegated_cred_handle + gss_cred_id_t, modify + credential handle for credentials received from + context initiator. Only valid if deleg_flag in + ret_flags is true. + + minor_status integer, modify + Mechanism specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer + application is required to complete the context, + and that gss_accept_sec_context must be called + again with that token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks + performed on the input_token failed. + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks + performed on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for + context acceptance, or the credential handle + did not reference any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have + expired. + + GSS_S_BAD_BINDINGS The input_token contains different channel + bindings to those specified via the + input_chan_bindings parameter. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did + not refer to a valid context. + + GSS_S_BAD_SIG The input_token contains an invalid signature. + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal + error during context establishment. + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a + duplicate of a token already processed. This + is a fatal error during context establishment. + + + +Wray [Page 24] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.5. gss_process_context_token + + OM_uint32 gss_process_context_token ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t token_buffer) + + Purpose: + + Provides a way to pass a token to the security service. Usually, + tokens are associated either with context establishment (when they + would be passed to gss_init_sec_context or gss_accept_sec_context) or + with per-message security service (when they would be passed to + gss_verify or gss_unseal). Occasionally, tokens may be received at + other times, and gss_process_context_token allows such tokens to be + passed to the underlying security service for processing. At + present, such additional tokens may only be generated by + gss_delete_sec_context. GSSAPI implementation may use this service + to implement deletion of the security context. + + Parameters: + + context_handle gss_ctx_id_t, read + context handle of context on which token is to + be processed + + token_buffer buffer, opaque, read + pointer to first byte of token to process + + minor_status integer, modify + Implementation specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks + performed on the token failed + + GSS_S_FAILURE Failure. See minor_status for more information + + GSS_S_NO_CONTEXT The context_handle did not refer to a valid + context + + + + +Wray [Page 25] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.6. gss_delete_sec_context + + OM_uint32 gss_delete_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_buffer_t output_token) + + Purpose: + + Delete a security context. gss_delete_sec_context will delete the + local data structures associated with the specified security context, + and generate an output_token, which when passed to the peer + gss_process_context_token will instruct it to do likewise. No + further security services may be obtained using the context specified + by context_handle. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, modify + context handle identifying context to delete. + + output_token buffer, opaque, modify + token to be sent to remote application to + instruct it to also delete the context + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_FAILURE Failure, see minor_status for more information + + GSS_S_NO_CONTEXT No valid context was supplied + +3.7. gss_context_time + + OM_uint32 gss_context_time ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + OM_uint32 * time_rec) + Purpose: + + Determines the number of seconds for which the specified context will + remain valid. + + + +Wray [Page 26] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Parameters: + + minor_status integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context to be interrogated. + + time_rec integer, modify + Number of seconds that the context will remain + valid. If the context has already expired, + zero will be returned. + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + +3.8. gss_sign + + OM_uint32 gss_sign ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + int qop_req, + gss_buffer_t message_buffer, + gss_buffer_t msg_token) + Purpose: + + Generates a cryptographic signature for the supplied message, and + places the signature in a token for transfer to the peer application. + The qop_req parameter allows a choice between several cryptographic + algorithms, if supported by the chosen mechanism. + + Parameters: + + minor_status integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + + + +Wray [Page 27] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + will be sent + + qop_req integer, read, optional + Specifies requested quality of protection. + Callers are encouraged, on portability grounds, + to accept the default quality of protection + offered by the chosen mechanism, which may be + requested by specifying GSS_C_QOP_DEFAULT for + this parameter. If an unsupported protection + strength is requested, gss_sign will return a + major_status of GSS_S_FAILURE. + + message_buffer buffer, opaque, read + message to be signed + + msg_token buffer, opaque, modify + buffer to receive token + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.9. gss_verify + + OM_uint32 gss_verify ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t message_buffer, + gss_buffer_t token_buffer, + int * qop_state) + Purpose: + + Verifies that a cryptographic signature, contained in the token + parameter, fits the supplied message. The qop_state parameter allows + a message recipient to determine the strength of protection that was + applied to the message. + + + +Wray [Page 28] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + arrived + + message_buffer buffer, opaque, read + message to be verified + + token_buffer buffer, opaque, read + token associated with message + + qop_state integer, modify + quality of protection gained from signature + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The signature was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct + signature for the message, but it had already + been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct + signature for the message, but it is too old + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct + signature for the message, but has been + verified out of sequence; an earlier token has + been signed or sealed by the remote + application, but not yet been processed + locally. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + + + + +Wray [Page 29] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.10. gss_seal + + OM_uint32 gss_seal ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + int conf_req_flag, + int qop_req + gss_buffer_t input_message_buffer, + int * conf_state, + gss_buffer_t output_message_buffer) + + Purpose: + + Cryptographically signs and optionally encrypts the specified + input_message. The output_message contains both the signature and + the message. The qop_req parameter allows a choice between several + cryptographic algorithms, if supported by the chosen mechanism. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + will be sent + + conf_req_flag boolean, read + True - Both confidentiality and integrity + services are requested + False - Only integrity service is requested + + qop_req integer, read, optional + Specifies required quality of protection. A + mechanism-specific default may be requested by + setting qop_req to GSS_C_QOP_DEFAULT. If an + unsupported protection strength is requested, + gss_seal will return a major_status of + GSS_S_FAILURE. + + input_message_buffer buffer, opaque, read + message to be sealed + + + + +Wray [Page 30] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + conf_state boolean, modify + True - Confidentiality, data origin + authentication and integrity services + have been applied + False - Integrity and data origin services only + has been applied. + + output_message_buffer buffer, opaque, modify + buffer to receive sealed message + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.11. gss_unseal + + OM_uint32 gss_unseal ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t input_message_buffer, + gss_buffer_t output_message_buffer, + int * conf_state, + int * qop_state) + + Purpose: + + Converts a previously sealed message back to a usable form, verifying + the embedded signature. The conf_state parameter indicates whether + the message was encrypted; the qop_state parameter indicates the + strength of protection that was used to provide the confidentiality + and integrity services. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + + +Wray [Page 31] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + context_handle gss_ctx_id_t, read + identifies the context on which the message + arrived + + input_message_buffer buffer, opaque, read + sealed message + + output_message_buffer buffer, opaque, modify + buffer to receive unsealed message + + conf_state boolean, modify + True - Confidentiality and integrity protection + were used + False - Inteegrity service only was used + + qop_state integer, modify + quality of protection gained from signature + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The signature was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a + correct signature for the message, but it had + already been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct + signature for the message, but it is too old + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct + signature for the message, but has been + verified out of sequence; an earlier token has + been signed or sealed by the remote + application, but not yet been processed + locally. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + + + + +Wray [Page 32] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.12. gss_display_status + + OM_uint32 gss_display_status ( + OM_uint32 * minor_status, + int status_value, + int status_type, + gss_OID mech_type, + int * message_context, + gss_buffer_t status_string) + + Purpose: + + Allows an application to obtain a textual representation of a GSSAPI + status code, for display to the user or for logging purposes. Since + some status values may indicate multiple errors, applications may + need to call gss_display_status multiple times, each call generating + a single text string. The message_context parameter is used to + indicate which error message should be extracted from a given + status_value; message_context should be initialized to 0, and + gss_display_status will return a non-zero value if there are further + messages to extract. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + status_value integer, read + Status value to be converted + + status_type integer, read + GSS_C_GSS_CODE - status_value is a GSS status + code + GSS_C_MECH_CODE - status_value is a mechanism + status code + + mech_type Object ID, read, optional + Underlying mechanism (used to interpret a + minor status value) Supply GSS_C_NULL_OID to + obtain the system default. + + message_context integer, read/modify + Should be initialized to zero by caller + + + +Wray [Page 33] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + on first call. If further messages are + contained in the status_value parameter, + message_context will be non-zero on return, + and this value should be passed back to + subsequent calls, along with the same + status_value, status_type and mech_type + parameters. + + status_string buffer, character string, modify + textual interpretation of the status_value + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Indicates that translation in accordance with + an unsupported mechanism type was requested + + GSS_S_BAD_STATUS The status value was not recognized, or the + status type was neither GSS_C_GSS_CODE nor + GSS_C_MECH_CODE. + + +3.13. gss_indicate_mechs + + OM_uint32 gss_indicate_mechs ( + OM_uint32 * minor_status, + gss_OID_set * mech_set) + + Purpose: + + Allows an application to determine which underlying security + mechanisms are available. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + mech_set set of Object IDs, modify + set of implementation-supported mechanisms. + The returned gss_OID_set value will be a + pointer into static storage, and should be + treated as read-only by the caller. + + + + + +Wray [Page 34] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + +3.14. gss_compare_name + + OM_uint32 gss_compare_name ( + OM_uint32 * minor_status, + gss_name_t name1, + gss_name_t name2, + int * name_equal) + + Purpose: + + Allows an application to compare two internal-form names to determine + whether they refer to the same entity. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + name1 gss_name_t, read + internal-form name + + name2 gss_name_t, read + internal-form name + + name_equal boolean, modify + True - names refer to same entity + False - names refer to different entities + (strictly, the names are not known to + refer to the same identity). + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The type contained within either name1 or + name2 was unrecognized, or the names were of + incomparable types. + + GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed + + + + + +Wray [Page 35] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.15. gss_display_name + + OM_uint32 gss_display_name ( + OM_uint32 * minor_status, + gss_name_t input_name, + gss_buffer_t output_name_buffer, + gss_OID * output_name_type) + + Purpose: + + Allows an application to obtain a textual representation of an opaque + internal-form name for display purposes. The syntax of a printable + name is defined by the GSSAPI implementation. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + input_name gss_name_t, read + name to be displayed + + output_name_buffer buffer, character-string, modify + buffer to receive textual name string + + output_name_type Object ID, modify + The type of the returned name. The returned + gss_OID will be a pointer into static storage, + and should be treated as read-only by the caller + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The type of input_name was not recognized + + GSS_S_BAD_NAME input_name was ill-formed + +3.16. gss_import_name + + OM_uint32 gss_import_name ( + OM_uint32 * minor_status, + gss_buffer_t input_name_buffer, + gss_OID input_name_type, + gss_name_t * output_name) + + + + +Wray [Page 36] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Purpose: + + Convert a printable name to internal form. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + input_name_buffer buffer, character-string, read + buffer containing printable name to convert + + input_name_type Object ID, read, optional + Object Id specifying type of printable + name. Applications may specify either + GSS_C_NULL_OID to use a local system-specific + printable syntax, or an OID registered by the + GSSAPI implementation to name a particular + namespace. + + output_name gss_name_t, modify + returned name in internal form + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The input_name_type was unrecognized + + GSS_S_BAD_NAME The input_name parameter could not be + interpreted as a name of the specified type + +3.17. gss_release_name + + OM_uint32 gss_release_name ( + OM_uint32 * minor_status, + gss_name_t * name) + + Purpose: + + Free GSSAPI-allocated storage associated with an internal form name. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + + +Wray [Page 37] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + name gss_name_t, modify + The name to be deleted + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The name parameter did not contain a valid name + +3.18. gss_release_buffer + + OM_uint32 gss_release_buffer ( + OM_uint32 * minor_status, + gss_buffer_t buffer) + + Purpose: + + Free storage associated with a buffer format name. The storage must + have been allocated by a GSSAPI routine. In addition to freeing the + associated storage, the routine will zero the length field in the + buffer parameter. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + buffer buffer, modify + The storage associated with the buffer will be + deleted. The gss_buffer_desc object will not + be freed, but its length field will be zeroed. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + +3.19. gss_release_oid_set + + OM_uint32 gss_release_oid_set ( + OM_uint32 * minor_status, + gss_OID_set * set) + + Purpose: + + + + +Wray [Page 38] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Free storage associated with a gss_OID_set object. The storage must + have been allocated by a GSSAPI routine. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + set Set of Object IDs, modify + The storage associated with the gss_OID_set + will be deleted. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + +3.20. gss_inquire_cred + + OM_uint32 gss_inquire_cred ( + OM_uint32 * minor_status, + gss_cred_id_t cred_handle, + gss_name_t * name, + OM_uint32 * lifetime, + int * cred_usage, + gss_OID_set * mechanisms ) + + Purpose: + + Obtains information about a credential. The caller must already have + obtained a handle that refers to the credential. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + cred_handle gss_cred_id_t, read + A handle that refers to the target credential. + Specify GSS_C_NO_CREDENTIAL to inquire about + the default credential. + + name gss_name_t, modify + The name whose identity the credential asserts. + Specify NULL if not required. + + lifetime Integer, modify + + + +Wray [Page 39] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The number of seconds for which the credential + will remain valid. If the credential has + expired, this parameter will be set to zero. + If the implementation does not support + credential expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + cred_usage Integer, modify + How the credential may be used. One of the + following: + GSS_C_INITIATE + GSS_C_ACCEPT + GSS_C_BOTH + Specify NULL if not required. + + mechanisms gss_OID_set, modify + Set of mechanisms supported by the credential. + Specify NULL if not required. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED The referenced credentials could not be + accessed. + + GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were + invalid. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. + If the lifetime parameter was not passed as + NULL, it will be set to 0. + + + #ifndef GSSAPI_H_ + #define GSSAPI_H_ + + /* + * First, define the platform-dependent types. + */ + typedef OM_uint32; + typedef gss_ctx_id_t; + typedef gss_cred_id_t; + typedef gss_name_t; + + + + +Wray [Page 40] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + /* + * Note that a platform supporting the xom.h X/Open header file + * may make use of that header for the definitions of OM_uint32 + * and the structure to which gss_OID_desc equates. + */ + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + typedef struct gss_OID_set_desc_struct { + int count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + + /* + * Six independent flags each of which indicates that a context + * supports a specific service option. + */ + #define GSS_C_DELEG_FLAG 1 + #define GSS_C_MUTUAL_FLAG 2 + #define GSS_C_REPLAY_FLAG 4 + #define GSS_C_SEQUENCE_FLAG 8 + #define GSS_C_CONF_FLAG 16 + #define GSS_C_INTEG_FLAG 32 + + + /* + * Credential usage options + */ + #define GSS_C_BOTH 0 + #define GSS_C_INITIATE 1 + #define GSS_C_ACCEPT 2 + + + +Wray [Page 41] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + /* + * Status code types for gss_display_status + */ + #define GSS_C_GSS_CODE 1 + #define GSS_C_MECH_CODE 2 + + /* + * The constant definitions for channel-bindings address families + */ + #define GSS_C_AF_UNSPEC 0; + #define GSS_C_AF_LOCAL 1; + #define GSS_C_AF_INET 2; + #define GSS_C_AF_IMPLINK 3; + #define GSS_C_AF_PUP 4; + #define GSS_C_AF_CHAOS 5; + #define GSS_C_AF_NS 6; + #define GSS_C_AF_NBS 7; + #define GSS_C_AF_ECMA 8; + #define GSS_C_AF_DATAKIT 9; + #define GSS_C_AF_CCITT 10; + #define GSS_C_AF_SNA 11; + #define GSS_C_AF_DECnet 12; + #define GSS_C_AF_DLI 13; + #define GSS_C_AF_LAT 14; + #define GSS_C_AF_HYLINK 15; + #define GSS_C_AF_APPLETALK 16; + #define GSS_C_AF_BSC 17; + #define GSS_C_AF_DSS 18; + #define GSS_C_AF_OSI 19; + #define GSS_C_AF_X25 21; + + #define GSS_C_AF_NULLADDR 255; + + #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) + #define GSS_C_NULL_OID ((gss_OID) 0) + #define GSS_C_NULL_OID_SET ((gss_OID_set) 0) + #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) + #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) + #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) + #define GSS_C_EMPTY_BUFFER {0, NULL} + + /* + * Define the default Quality of Protection for per-message + * services. Note that an implementation that offers multiple + * levels of QOP may either reserve a value (for example zero, + * as assumed here) to mean "default protection", or alternatively + * may simply equate GSS_C_QOP_DEFAULT to a specific explicit QOP + * value. + + + +Wray [Page 42] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + */ + #define GSS_C_QOP_DEFAULT 0 + + /* + * Expiration time of 2^32-1 seconds means infinite lifetime for a + * credential or security context + */ + #define GSS_C_INDEFINITE 0xfffffffful + + + /* Major status codes */ + + #define GSS_S_COMPLETE 0 + + /* + * Some "helper" definitions to make the status code macros obvious. + */ + #define GSS_C_CALLING_ERROR_OFFSET 24 + #define GSS_C_ROUTINE_ERROR_OFFSET 16 + #define GSS_C_SUPPLEMENTARY_OFFSET 0 + #define GSS_C_CALLING_ERROR_MASK 0377ul + #define GSS_C_ROUTINE_ERROR_MASK 0377ul + #define GSS_C_SUPPLEMENTARY_MASK 0177777ul + + /* + * The macros that test status codes for error conditions + */ + #define GSS_CALLING_ERROR(x) \ + (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) + #define GSS_ROUTINE_ERROR(x) \ + (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) + #define GSS_SUPPLEMENTARY_INFO(x) \ + (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) + #define GSS_ERROR(x) \ + ((GSS_CALLING_ERROR(x) != 0) || (GSS_ROUTINE_ERROR(x) != 0)) + + + /* + * Now the actual status code definitions + */ + + /* + * Calling errors: + */ + #define GSS_S_CALL_INACCESSIBLE_READ \ + (1ul << GSS_C_CALLING_ERROR_OFFSET) + #define GSS_S_CALL_INACCESSIBLE_WRITE \ + (2ul << GSS_C_CALLING_ERROR_OFFSET) + + + +Wray [Page 43] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + #define GSS_S_CALL_BAD_STRUCTURE \ + (3ul << GSS_C_CALLING_ERROR_OFFSET) + + /* + * Routine errors: + */ + #define GSS_S_BAD_MECH (1ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAME (2ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAMETYPE (3ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_BINDINGS (4ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_STATUS (5ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_SIG (6ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NO_CRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NO_CONTEXT (8ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_TOKEN (9ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CREDENTIALS_EXPIRED (11ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CONTEXT_EXPIRED (12ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_FAILURE (13ul << GSS_C_ROUTINE_ERROR_OFFSET) + + /* + * Supplementary info bits: + */ + #define GSS_S_CONTINUE_NEEDED (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) + #define GSS_S_DUPLICATE_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) + #define GSS_S_OLD_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) + #define GSS_S_UNSEQ_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) + + + /* + * Finally, function prototypes for the GSSAPI routines. + */ + + OM_uint32 gss_acquire_cred + (OM_uint32*, /* minor_status */ + gss_name_t, /* desired_name */ + OM_uint32, /* time_req */ + gss_OID_set, /* desired_mechs */ + int, /* cred_usage */ + gss_cred_id_t*, /* output_cred_handle */ + gss_OID_set*, /* actual_mechs */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_release_cred, + (OM_uint32*, /* minor_status */ + gss_cred_id_t* /* cred_handle */ + ); + + + +Wray [Page 44] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_init_sec_context + (OM_uint32*, /* minor_status */ + gss_cred_id_t, /* claimant_cred_handle */ + gss_ctx_id_t*, /* context_handle */ + gss_name_t, /* target_name */ + gss_OID, /* mech_type */ + int, /* req_flags */ + OM_uint32, /* time_req */ + gss_channel_bindings_t, + /* input_chan_bindings */ + gss_buffer_t, /* input_token */ + gss_OID*, /* actual_mech_type */ + gss_buffer_t, /* output_token */ + int*, /* ret_flags */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_accept_sec_context + (OM_uint32*, /* minor_status */ + gss_ctx_id_t*, /* context_handle */ + gss_cred_id_t, /* verifier_cred_handle */ + gss_buffer_t, /* input_token_buffer */ + gss_channel_bindings_t, + /* input_chan_bindings */ + gss_name_t*, /* src_name */ + gss_OID*, /* mech_type */ + gss_buffer_t, /* output_token */ + int*, /* ret_flags */ + OM_uint32*, /* time_rec */ + gss_cred_id_t* /* delegated_cred_handle */ + ); + + OM_uint32 gss_process_context_token + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t /* token_buffer */ + ); + + OM_uint32 gss_delete_sec_context + (OM_uint32*, /* minor_status */ + gss_ctx_id_t*, /* context_handle */ + gss_buffer_t /* output_token */ + ); + + + + + + + + +Wray [Page 45] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_context_time + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_sign + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* qop_req */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t /* message_token */ + ); + + OM_uitn32 gss_verify + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t, /* token_buffer */ + int* /* qop_state */ + ); + + OM_uint32 gss_seal + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + int, /* qop_req */ + gss_buffer_t, /* input_message_buffer */ + int*, /* conf_state */ + gss_buffer_t /* output_message_buffer */ + ); + + OM_uint32 gss_unseal + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* input_message_buffer */ + gss_buffer_t, /* output_message_buffer */ + int*, /* conf_state */ + int* /* qop_state */ + ); + + + + + + + + + + + +Wray [Page 46] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_display_status + (OM_uint32*, /* minor_status */ + OM_uint32, /* status_value */ + int, /* status_type */ + gss_OID, /* mech_type */ + int*, /* message_context */ + gss_buffer_t /* status_string */ + ); + + OM_uint32 gss_indicate_mechs + (OM_uint32*, /* minor_status */ + gss_OID_set* /* mech_set */ + ); + + OM_uint32 gss_compare_name + (OM_uint32*, /* minor_status */ + gss_name_t, /* name1 */ + gss_name_t, /* name2 */ + int* /* name_equal */ + ); + + OM_uint32 gss_display_name, + (OM_uint32*, /* minor_status */ + gss_name_t, /* input_name */ + gss_buffer_t, /* output_name_buffer */ + gss_OID* /* output_name_type */ + ); + + OM_uint32 gss_import_name + (OM_uint32*, /* minor_status */ + gss_buffer_t, /* input_name_buffer */ + gss_OID, /* input_name_type */ + gss_name_t* /* output_name */ + ); + + OM_uint32 gss_release_name + (OM_uint32*, /* minor_status */ + gss_name_t* /* input_name */ + ); + + OM_uint32 gss_release_buffer + (OM_uint32*, /* minor_status */ + gss_buffer_t /* buffer */ + ); + + OM_uint32 gss_release_oid_set + (OM_uint32*, /* minor_status */ + gss_OID_set* /* set */ + + + +Wray [Page 47] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ); + + OM_uint32 gss_inquire_cred + (OM_uint32 *, /* minor_status */ + gss_cred_id_t, /* cred_handle */ + gss_name_t *, /* name */ + OM_uint32 *, /* lifetime */ + int *, /* cred_usage */ + gss_OID_set * /* mechanisms */ + ); + + + + #endif /* GSSAPI_H_ */ + +References + + [1] Linn, J., "Generic Security Service Application Program + Interface", RFC 1508, Geer Zolot Associate, September 1993. + + [2] "OSI Object Management API Specification, Version 2.0 t", X.400 + API Association & X/Open Company Limited, August 24, 1990. + Specification of datatypes and routines for manipulating + information objects. + +Security Considerations + + Security issues are discussed throughout this memo. + +Author's Address + + John Wray + Digital Equipment Corporation + 550 King Street, LKG2-2/AA6 + Littleton, MA 01460 + USA + + Phone: +1-508-486-5210 + EMail: Wray@tuxedo.enet.dec.com + + + + + + + + + + + + +Wray [Page 48] + \ No newline at end of file diff --git a/doc/rfc1964.txt b/doc/rfc1964.txt new file mode 100644 index 000000000..f2960b961 --- /dev/null +++ b/doc/rfc1964.txt @@ -0,0 +1,1123 @@ + + + + + + +Network Working Group J. Linn +Request for Comments: 1964 OpenVision Technologies +Category: Standards Track June 1996 + + + The Kerberos Version 5 GSS-API Mechanism + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +ABSTRACT + + This specification defines protocols, procedures, and conventions to + be employed by peers implementing the Generic Security Service + Application Program Interface (as specified in RFCs 1508 and 1509) + when using Kerberos Version 5 technology (as specified in RFC 1510). + +ACKNOWLEDGMENTS + + Much of the material in this memo is based on working documents + drafted by John Wray of Digital Equipment Corporation and on + discussions, implementation activities, and interoperability testing + involving Marc Horowitz, Ted Ts'o, and John Wray. Particular thanks + are due to each of these individuals for their contributions towards + development and availability of GSS-API support within the Kerberos + Version 5 code base. + +1. Token Formats + + This section discusses protocol-visible characteristics of the GSS- + API mechanism to be implemented atop Kerberos V5 security technology + per RFC-1508 and RFC-1510; it defines elements of protocol for + interoperability and is independent of language bindings per RFC- + 1509. + + Tokens transferred between GSS-API peers (for security context + management and per-message protection purposes) are defined. The + data elements exchanged between a GSS-API endpoint implementation and + the Kerberos KDC are not specific to GSS-API usage and are therefore + defined within RFC-1510 rather than within this specification. + + + + + + +Linn Standards Track [Page 1] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + To support ongoing experimentation, testing, and evolution of the + specification, the Kerberos V5 GSS-API mechanism as defined in this + and any successor memos will be identified with the following Object + Identifier, as defined in RFC-1510, until the specification is + advanced to the level of Proposed Standard RFC: + + {iso(1), org(3), dod(5), internet(1), security(5), kerberosv5(2)} + + Upon advancement to the level of Proposed Standard RFC, the Kerberos + V5 GSS-API mechanism will be identified by an Object Identifier + having the value: + + {iso(1) member-body(2) United States(840) mit(113554) infosys(1) + gssapi(2) krb5(2)} + +1.1. Context Establishment Tokens + + Per RFC-1508, Appendix B, the initial context establishment token + will be enclosed within framing as follows: + + InitialContextToken ::= + [APPLICATION 0] IMPLICIT SEQUENCE { + thisMech MechType + -- MechType is OBJECT IDENTIFIER + -- representing "Kerberos V5" + innerContextToken ANY DEFINED BY thisMech + -- contents mechanism-specific; + -- ASN.1 usage within innerContextToken + -- is not required + } + + The innerContextToken of the initial context token will consist of a + Kerberos V5 KRB_AP_REQ message, preceded by a two-byte token-id + (TOK_ID) field, which shall contain the value 01 00. + + The above GSS-API framing shall be applied to all tokens emitted by + the Kerberos V5 GSS-API mechanism, including KRB_AP_REP, KRB_ERROR, + context-deletion, and per-message tokens, not just to the initial + token in a context establishment sequence. While not required by + RFC-1508, this enables implementations to perform enhanced error- + checking. The innerContextToken field of context establishment tokens + for the Kerberos V5 GSS-API mechanism will contain a Kerberos message + (KRB_AP_REQ, KRB_AP_REP or KRB_ERROR), preceded by a 2-byte TOK_ID + field containing 01 00 for KRB_AP_REQ messages, 02 00 for KRB_AP_REP + messages and 03 00 for KRB_ERROR messages. + + + + + + +Linn Standards Track [Page 2] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +1.1.1. Initial Token + + Relevant KRB_AP_REQ syntax (from RFC-1510) is as follows: + + AP-REQ ::= [APPLICATION 14] SEQUENCE { + pvno [0] INTEGER, -- indicates Version 5 + msg-type [1] INTEGER, -- indicates KRB_AP_REQ + ap-options[2] APOptions, + ticket[3] Ticket, + authenticator[4] EncryptedData + } + + APOptions ::= BIT STRING { + reserved (0), + use-session-key (1), + mutual-required (2) + } + + Ticket ::= [APPLICATION 1] SEQUENCE { + tkt-vno [0] INTEGER, -- indicates Version 5 + realm [1] Realm, + sname [2] PrincipalName, + enc-part [3] EncryptedData + } + + -- Encrypted part of ticket + EncTicketPart ::= [APPLICATION 3] SEQUENCE { + flags[0] TicketFlags, + key[1] EncryptionKey, + crealm[2] Realm, + cname[3] PrincipalName, + transited[4] TransitedEncoding, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + caddr[9] HostAddresses OPTIONAL, + authorization-data[10] AuthorizationData OPTIONAL + } + + -- Unencrypted authenticator + Authenticator ::= [APPLICATION 2] SEQUENCE { + authenticator-vno[0] INTEGER, + crealm[1] Realm, + cname[2] PrincipalName, + cksum[3] Checksum OPTIONAL, + cusec[4] INTEGER, + ctime[5] KerberosTime, + + + +Linn Standards Track [Page 3] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + subkey[6] EncryptionKey OPTIONAL, + seq-number[7] INTEGER OPTIONAL, + authorization-data[8] AuthorizationData OPTIONAL + } + + For purposes of this specification, the authenticator shall include + the optional sequence number, and the checksum field shall be used to + convey channel binding, service flags, and optional delegation + information. The checksum will have a type of 0x8003 (a value being + registered within the Kerberos protocol specification), and a value + field of at least 24 bytes in length. The length of the value field + is extended beyond 24 bytes if and only if an optional facility to + carry a Kerberos-defined KRB_CRED message for delegation purposes is + supported by an implementation and active on a context. When + delegation is active, a TGT with its FORWARDABLE flag set will be + transferred within the KRB_CRED message. + + The checksum value field's format is as follows: + + Byte Name Description + 0..3 Lgth Number of bytes in Bnd field; + Currently contains hex 10 00 00 00 + (16, represented in little-endian form) + 4..19 Bnd MD5 hash of channel bindings, taken over all non-null + components of bindings, in order of declaration. + Integer fields within channel bindings are represented + in little-endian order for the purposes of the MD5 + calculation. + 20..23 Flags Bit vector of context-establishment flags, + with values consistent with RFC-1509, p. 41: + GSS_C_DELEG_FLAG: 1 + GSS_C_MUTUAL_FLAG: 2 + GSS_C_REPLAY_FLAG: 4 + GSS_C_SEQUENCE_FLAG: 8 + GSS_C_CONF_FLAG: 16 + GSS_C_INTEG_FLAG: 32 + The resulting bit vector is encoded into bytes 20..23 + in little-endian form. + 24..25 DlgOpt The Delegation Option identifier (=1) [optional] + 26..27 Dlgth The length of the Deleg field. [optional] + 28..n Deleg A KRB_CRED message (n = Dlgth + 29) [optional] + + In computing the contents of the "Bnd" field, the following detailed + points apply: + + (1) Each integer field shall be formatted into four bytes, using + little-endian byte ordering, for purposes of MD5 hash + computation. + + + +Linn Standards Track [Page 4] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + (2) All input length fields within gss_buffer_desc elements of a + gss_channel_bindings_struct, even those which are zero-valued, + shall be included in the hash calculation; the value elements of + gss_buffer_desc elements shall be dereferenced, and the + resulting data shall be included within the hash computation, + only for the case of gss_buffer_desc elements having non-zero + length specifiers. + + (3) If the caller passes the value GSS_C_NO_BINDINGS instead of + a valid channel bindings structure, the Bnd field shall be set + to 16 zero-valued bytes. + + In the initial Kerberos V5 GSS-API mechanism token (KRB_AP_REQ token) + from initiator to target, the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, + GSS_C_REPLAY_FLAG, and GSS_C_SEQUENCE_FLAG values shall each be set + as the logical AND of the initiator's corresponding request flag to + GSS_Init_sec_context() and a Boolean indicator of whether that + optional service is available to GSS_Init_sec_context()'s caller. + GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG, for which no corresponding + context-level input indicator flags to GSS_Init_sec_context() exist, + shall each be set to indicate whether their respective per-message + protection services are available for use on the context being + established. + + When input source address channel binding values are provided by a + caller (i.e., unless the input argument is GSS_C_NO_BINDINGS or the + source address specifier value within the input structure is + GSS_C_NULL_ADDRTYPE), and the corresponding token received from the + context's peer bears address restrictions, it is recommended that an + implementation of the Kerberos V5 GSS-API mechanism should check that + the source address as provided by the caller matches that in the + received token, and should return the GSS_S_BAD_BINDINGS major_status + value if a mismatch is detected. Note: discussion is ongoing about + the strength of recommendation to be made in this area, and on the + circumstances under which such a recommendation should be applicable; + implementors are therefore advised that changes on this matter may be + included in subsequent versions of this specification. + +1.1.2. Response Tokens + + A context establishment sequence based on the Kerberos V5 mechanism + will perform one-way authentication (without confirmation or any + return token from target to initiator in response to the initiator's + KRB_AP_REQ) if the mutual_req bit is not set in the application's + call to GSS_Init_sec_context(). Applications requiring confirmation + that their authentication was successful should request mutual + authentication, resulting in a "mutual-required" indication within + KRB_AP_REQ APoptions and the setting of the mutual_req bit in the + + + +Linn Standards Track [Page 5] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + flags field of the authenticator checksum. In response to such a + request, the context target will reply to the initiator with a token + containing either a KRB_AP_REP or KRB_ERROR, completing the mutual + context establishment exchange. + + Relevant KRB_AP_REP syntax is as follows: + + AP-REP ::= [APPLICATION 15] SEQUENCE { + pvno [0] INTEGER, -- represents Kerberos V5 + msg-type [1] INTEGER, -- represents KRB_AP_REP + enc-part [2] EncryptedData + } + + EncAPRepPart ::= [APPLICATION 27] SEQUENCE { + ctime [0] KerberosTime, + cusec [1] INTEGER, + subkey [2] EncryptionKey OPTIONAL, + seq-number [3] INTEGER OPTIONAL + } + + The optional seq-number element within the AP-REP's EncAPRepPart + shall be included. + + The syntax of KRB_ERROR is as follows: + + KRB-ERROR ::= [APPLICATION 30] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ctime[2] KerberosTime OPTIONAL, + cusec[3] INTEGER OPTIONAL, + stime[4] KerberosTime, + susec[5] INTEGER, + error-code[6] INTEGER, + crealm[7] Realm OPTIONAL, + cname[8] PrincipalName OPTIONAL, + realm[9] Realm, -- Correct realm + sname[10] PrincipalName, -- Correct name + e-text[11] GeneralString OPTIONAL, + e-data[12] OCTET STRING OPTIONAL + } + + Values to be transferred in the error-code field of a KRB-ERROR + message are defined in [RFC-1510], not in this specification. + + + + + + + + +Linn Standards Track [Page 6] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +1.2. Per-Message and Context Deletion Tokens + + Three classes of tokens are defined in this section: "MIC" tokens, + emitted by calls to GSS_GetMIC() (formerly GSS_Sign()) and consumed + by calls to GSS_VerifyMIC() (formerly GSS_Verify()), "Wrap" tokens, + emitted by calls to GSS_Wrap() (formerly GSS_Seal()) and consumed by + calls to GSS_Unwrap() (formerly GSS_Unseal()), and context deletion + tokens, emitted by calls to GSS_Delete_sec_context() and consumed by + calls to GSS_Process_context_token(). Note: References to GSS-API + per-message routines in the remainder of this specification will be + based on those routines' newer recommended names rather than those + names' predecessors. + + Several variants of cryptographic keys are used in generation and + processing of per-message tokens: + + (1) context key: uses Kerberos session key (or subkey, if + present in authenticator emitted by context initiator) directly + + (2) confidentiality key: forms variant of context key by + exclusive-OR with the hexadecimal constant f0f0f0f0f0f0f0f0. + + (3) MD2.5 seed key: forms variant of context key by reversing + the bytes of the context key (i.e. if the original key is the + 8-byte sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the seed key + will be {hh, gg, ff, ee, dd, cc, bb, aa}). + +1.2.1. Per-message Tokens - MIC + +Use of the GSS_GetMIC() call yields a token, separate from the user +data being protected, which can be used to verify the integrity of +that data as received. The token has the following format: + + Byte no Name Description + 0..1 TOK_ID Identification field. + Tokens emitted by GSS_GetMIC() contain + the hex value 01 01 in this field. + 2..3 SGN_ALG Integrity algorithm indicator. + 00 00 - DES MAC MD5 + 01 00 - MD2.5 + 02 00 - DES MAC + 4..7 Filler Contains ff ff ff ff + 8..15 SND_SEQ Sequence number field. + 16..23 SGN_CKSUM Checksum of "to-be-signed data", + calculated according to algorithm + specified in SGN_ALG field. + + + + + +Linn Standards Track [Page 7] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + GSS-API tokens must be encapsulated within the higher-level protocol + by the application; no embedded length field is necessary. + +1.2.1.1. Checksum + + Checksum calculation procedure (common to all algorithms): Checksums + are calculated over the data field, logically prepended by the first + 8 bytes of the plaintext packet header. The resulting value binds + the data to the packet type and signature algorithm identifier + fields. + + DES MAC MD5 algorithm: The checksum is formed by computing an MD5 + [RFC-1321] hash over the plaintext data, and then computing a DES-CBC + MAC on the 16-byte MD5 result. A standard 64-bit DES-CBC MAC is + computed per [FIPS-PUB-113], employing the context key and a zero IV. + The 8-byte result is stored in the SGN_CKSUM field. + + MD2.5 algorithm: The checksum is formed by first DES-CBC encrypting a + 16-byte zero-block, using a zero IV and a key formed by reversing the + bytes of the context key (i.e. if the original key is the 8-byte + sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the checksum key will be + {hh, gg, ff, ee, dd, cc, bb, aa}). The resulting 16-byte value is + logically prepended to the to-be-signed data. A standard MD5 + checksum is calculated over the combined data, and the first 8 bytes + of the result are stored in the SGN_CKSUM field. Note 1: we refer to + this algorithm informally as "MD2.5" to connote the fact that it uses + half of the 128 bits generated by MD5; use of only a subset of the + MD5 bits is intended to protect against the prospect that data could + be postfixed to an existing message with corresponding modifications + being made to the checksum. Note 2: This algorithm is fairly novel + and has received more limited evaluation than that to which other + integrity algorithms have been subjected. An initial, limited + evaluation indicates that it may be significantly weaker than DES MAC + MD5. + + DES-MAC algorithm: A standard 64-bit DES-CBC MAC is computed on the + plaintext data per [FIPS-PUB-113], employing the context key and a + zero IV. Padding procedures to accomodate plaintext data lengths + which may not be integral multiples of 8 bytes are defined in [FIPS- + PUB-113]. The result is an 8-byte value, which is stored in the + SGN_CKSUM field. Support for this algorithm may not be present in + all implementations. + +1.2.1.2. Sequence Number + + Sequence number field: The 8 byte plaintext sequence number field is + formed from the sender's four-byte sequence number as follows. If + the four bytes of the sender's sequence number are named s0, s1, s2 + + + +Linn Standards Track [Page 8] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + and s3 (from least to most significant), the plaintext sequence + number field is the 8 byte sequence: (s0, s1, s2, s3, di, di, di, + di), where 'di' is the direction-indicator (Hex 0 - sender is the + context initiator, Hex FF - sender is the context acceptor). The + field is then DES-CBC encrypted using the context key and an IV + formed from the first 8 bytes of the previously calculated SGN_CKSUM + field. After sending a GSS_GetMIC() or GSS_Wrap() token, the sender's + sequence number is incremented by one. + + The receiver of the token will first verify the SGN_CKSUM field. If + valid, the sequence number field may be decrypted and compared to the + expected sequence number. The repetition of the (effectively 1-bit) + direction indicator within the sequence number field provides + redundancy so that the receiver may verify that the decryption + succeeded. + + Since the checksum computation is used as an IV to the sequence + number decryption, attempts to splice a checksum and sequence number + from different messages will be detected. The direction indicator + will detect packets that have been maliciously reflected. + + The sequence number provides a basis for detection of replayed + tokens. Replay detection can be performed using state information + retained on received sequence numbers, interpreted in conjunction + with the security context on which they arrive. + + Provision of per-message replay and out-of-sequence detection + services is optional for implementations of the Kerberos V5 GSS-API + mechanism. Further, it is recommended that implementations of the + Kerberos V5 GSS-API mechanism which offer these services should honor + a caller's request that the services be disabled on a context. + Specifically, if replay_det_req_flag is input FALSE, replay_det_state + should be returned FALSE and the GSS_DUPLICATE_TOKEN and + GSS_OLD_TOKEN stati should not be indicated as a result of duplicate + detection when tokens are processed; if sequence_req_flag is input + FALSE, sequence_state should be returned FALSE and + GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN stati should + not be indicated as a result of out-of-sequence detection when tokens + are processed. + +1.2.2. Per-message Tokens - Wrap + + Use of the GSS_Wrap() call yields a token which encapsulates the + input user data (optionally encrypted) along with associated + integrity check quantities. The token emitted by GSS_Wrap() consists + of an integrity header whose format is identical to that emitted by + GSS_GetMIC() (except that the TOK_ID field contains the value 02 01), + followed by a body portion that contains either the plaintext data + + + +Linn Standards Track [Page 9] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + (if SEAL_ALG = ff ff) or encrypted data for any other supported value + of SEAL_ALG. Currently, only SEAL_ALG = 00 00 is supported, and + means that DES-CBC encryption is being used to protect the data. + + The GSS_Wrap() token has the following format: + + Byte no Name Description + 0..1 TOK_ID Identification field. + Tokens emitted by GSS_Wrap() contain + the hex value 02 01 in this field. + 2..3 SGN_ALG Checksum algorithm indicator. + 00 00 - DES MAC MD5 + 01 00 - MD2.5 + 02 00 - DES MAC + 4..5 SEAL_ALG ff ff - none + 00 00 - DES + 6..7 Filler Contains ff ff + 8..15 SND_SEQ Encrypted sequence number field. + 16..23 SGN_CKSUM Checksum of plaintext padded data, + calculated according to algorithm + specified in SGN_ALG field. + 24..last Data encrypted or plaintext padded data + + GSS-API tokens must be encapsulated within the higher-level protocol + by the application; no embedded length field is necessary. + +1.2.2.1. Checksum + + Checksum calculation procedure (common to all algorithms): Checksums + are calculated over the plaintext padded data field, logically + prepended by the first 8 bytes of the plaintext packet header. The + resulting signature binds the data to the packet type, protocol + version, and signature algorithm identifier fields. + + DES MAC MD5 algorithm: The checksum is formed by computing an MD5 + hash over the plaintext padded data, and then computing a DES-CBC MAC + on the 16-byte MD5 result. A standard 64-bit DES-CBC MAC is computed + per [FIPS-PUB-113], employing the context key and a zero IV. The 8- + byte result is stored in the SGN_CKSUM field. + + MD2.5 algorithm: The checksum is formed by first DES-CBC encrypting a + 16-byte zero-block, using a zero IV and a key formed by reversing the + bytes of the context key (i.e., if the original key is the 8-byte + sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the checksum key will be + {hh, gg, ff, ee, dd, cc, bb, aa}). The resulting 16-byte value is + logically pre-pended to the "to-be-signed data". A standard MD5 + checksum is calculated over the combined data, and the first 8 bytes + of the result are stored in the SGN_CKSUM field. + + + +Linn Standards Track [Page 10] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + DES-MAC algorithm: A standard 64-bit DES-CBC MAC is computed on the + plaintext padded data per [FIPS-PUB-113], employing the context key + and a zero IV. The plaintext padded data is already assured to be an + integral multiple of 8 bytes; no additional padding is required or + applied in order to accomplish MAC calculation. The result is an 8- + byte value, which is stored in the SGN_CKSUM field. Support for this + lgorithm may not be present in all implementations. + +1.2.2.2. Sequence Number + + Sequence number field: The 8 byte plaintext sequence number field is + formed from the sender's four-byte sequence number as follows. If + the four bytes of the sender's sequence number are named s0, s1, s2 + and s3 (from least to most significant), the plaintext sequence + number field is the 8 byte sequence: (s0, s1, s2, s3, di, di, di, + di), where 'di' is the direction-indicator (Hex 0 - sender is the + context initiator, Hex FF - sender is the context acceptor). + + The field is then DES-CBC encrypted using the context key and an IV + formed from the first 8 bytes of the SEAL_CKSUM field. + + After sending a GSS_GetMIC() or GSS_Wrap() token, the sender's + sequence numbers are incremented by one. + +1.2.2.3. Padding + + Data padding: Before encryption and/or signature calculation, + plaintext data is padded to the next highest multiple of 8 bytes, by + appending between 1 and 8 bytes, the value of each such byte being + the total number of pad bytes. For example, given data of length 20 + bytes, four pad bytes will be appended, and each byte will contain + the hex value 04. An 8-byte random confounder is prepended to the + data, and signatures are calculated over the resulting padded + plaintext. + + After padding, the data is encrypted according to the algorithm + specified in the SEAL_ALG field. For SEAL_ALG=DES (the only non-null + algorithm currently supported), the data is encrypted using DES-CBC, + with an IV of zero. The key used is derived from the established + context key by XOR-ing the context key with the hexadecimal constant + f0f0f0f0f0f0f0f0. + +1.2.3. Context deletion token + + The token emitted by GSS_Delete_sec_context() is based on the packet + format for tokens emitted by GSS_GetMIC(). The context-deletion + token has the following format: + + + + +Linn Standards Track [Page 11] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + Byte no Name Description + 0..1 TOK_ID Identification field. + Tokens emitted by + GSS_Delete_sec_context() contain + the hex value 01 02 in this field. + 2..3 SGN_ALG Integrity algorithm indicator. + 00 00 - DES MAC MD5 + 01 00 - MD2.5 + 02 00 - DES MAC + 4..7 Filler Contains ff ff ff ff + 8..15 SND_SEQ Sequence number field. + 16..23 SGN_CKSUM Checksum of "to-be-signed data", + calculated according to algorithm + specified in SGN_ALG field. + + SGN_ALG and SND_SEQ will be calculated as for tokens emitted by + GSS_GetMIC(). The SGN_CKSUM will be calculated as for tokens emitted + by GSS_GetMIC(), except that the user-data component of the "to-be- + signed" data will be a zero-length string. + +2. Name Types and Object Identifiers + + This section discusses the name types which may be passed as input to + the Kerberos V5 GSS-API mechanism's GSS_Import_name() call, and their + associated identifier values. It defines interface elements in + support of portability, and assumes use of C language bindings per + RFC-1509. In addition to specifying OID values for name type + identifiers, symbolic names are included and recommended to GSS-API + implementors in the interests of convenience to callers. It is + understood that not all implementations of the Kerberos V5 GSS-API + mechanism need support all name types in this list, and that + additional name forms will likely be added to this list over time. + Further, the definitions of some or all name types may later migrate + to other, mechanism-independent, specifications. The occurrence of a + name type in this specification is specifically not intended to + suggest that the type may be supported only by an implementation of + the Kerberos V5 mechanism. In particular, the occurrence of the + string "_KRB5_" in the symbolic name strings constitutes a means to + unambiguously register the name strings, avoiding collision with + other documents; it is not meant to limit the name types' usage or + applicability. + + For purposes of clarification to GSS-API implementors, this section's + discussion of some name forms describes means through which those + forms can be supported with existing Kerberos technology. These + discussions are not intended to preclude alternative implementation + strategies for support of the name forms within Kerberos mechanisms + or mechanisms based on other technologies. To enhance application + + + +Linn Standards Track [Page 12] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + portability, implementors of mechanisms are encouraged to support + name forms as defined in this section, even if their mechanisms are + independent of Kerberos V5. + +2.1. Mandatory Name Forms + + This section discusses name forms which are to be supported by all + conformant implementations of the Kerberos V5 GSS-API mechanism. + +2.1.1. Kerberos Principal Name Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + krb5(2) krb5_name(1)}. The recommended symbolic name for this type + is "GSS_KRB5_NT_PRINCIPAL_NAME". + + This name type corresponds to the single-string representation of a + Kerberos name. (Within the MIT Kerberos V5 implementation, such + names are parseable with the krb5_parse_name() function.) The + elements included within this name representation are as follows, + proceeding from the beginning of the string: + + (1) One or more principal name components; if more than one + principal name component is included, the components are + separated by `/`. Arbitrary octets may be included within + principal name components, with the following constraints and + special considerations: + + (1a) Any occurrence of the characters `@` or `/` within a + name component must be immediately preceded by the `\` + quoting character, to prevent interpretation as a component + or realm separator. + + (1b) The ASCII newline, tab, backspace, and null characters + may occur directly within the component or may be + represented, respectively, by `\n`, `\t`, `\b`, or `\0`. + + (1c) If the `\` quoting character occurs outside the contexts + described in (1a) and (1b) above, the following character is + interpreted literally. As a special case, this allows the + doubled representation `\\` to represent a single occurrence + of the quoting character. + + (1d) An occurrence of the `\` quoting character as the last + character of a component is illegal. + + + + + + +Linn Standards Track [Page 13] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + (2) Optionally, a `@` character, signifying that a realm name + immediately follows. If no realm name element is included, the + local realm name is assumed. The `/` , `:`, and null characters + may not occur within a realm name; the `@`, newline, tab, and + backspace characters may be included using the quoting + conventions described in (1a), (1b), and (1c) above. + +2.1.2. Host-Based Service Name Form + + This name form has been incorporated at the mechanism-independent + GSS-API level as of GSS-API, Version 2. This subsection retains the + Object Identifier and symbolic name assignments previously made at + the Kerberos V5 GSS-API mechanism level, and adopts the definition as + promoted to the mechanism-independent level. + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) service_name(4)}. The previously recommended symbolic + name for this type is "GSS_KRB5_NT_HOSTBASED_SERVICE_NAME". The + currently preferred symbolic name for this type is + "GSS_C_NT_HOSTBASED_SERVICE". + + This name type is used to represent services associated with host + computers. This name form is constructed using two elements, + "service" and "hostname", as follows: + + service@hostname + + When a reference to a name of this type is resolved, the "hostname" + is canonicalized by attempting a DNS lookup and using the fully- + qualified domain name which is returned, or by using the "hostname" + as provided if the DNS lookup fails. The canonicalization operation + also maps the host's name into lower-case characters. + + The "hostname" element may be omitted. If no "@" separator is + included, the entire name is interpreted as the service specifier, + with the "hostname" defaulted to the canonicalized name of the local + host. + + Values for the "service" element will be registered with the IANA. + +2.1.3. Exported Name Object Form for Kerberos V5 Mechanism + + Support for this name form is not required for GSS-V1 + implementations, but will be required for use in conjunction with the + GSS_Export_name() call planned for GSS-API Version 2. Use of this + name form will be signified by a "GSS-API Exported Name Object" OID + value which will be defined at the mechanism-independent level for + + + +Linn Standards Track [Page 14] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + GSS-API Version 2. + + This name type represents a self-describing object, whose framing + structure will be defined at the mechanism-independent level for + GSS-API Version 2. When generated by the Kerberos V5 mechanism, the + Mechanism OID within the exportable name shall be that of the + Kerberos V5 mechanism. The name component within the exportable name + shall be a contiguous string with structure as defined for the + Kerberos Principal Name Form. + + In order to achieve a distinguished encoding for comparison purposes, + the following additional constraints are imposed on the export + operation: + + (1) all occurrences of the characters `@`, `/`, and `\` within + principal components or realm names shall be quoted with an + immediately-preceding `\`. + + (2) all occurrences of the null, backspace, tab, or newline + characters within principal components or realm names will be + represented, respectively, with `\0`, `\b`, `\t`, or `\n`. + + (3) the `\` quoting character shall not be emitted within an + exported name except to accomodate cases (1) and (2). + +2.2. Optional Name Forms + + This section discusses additional name forms which may optionally be + supported by implementations of the Kerberos V5 GSS-API mechanism. + It is recognized that some of the name forms cited here are derived + from UNIX(tm) operating system platforms; some listed forms may be + irrelevant to non-UNIX platforms, and definition of additional forms + corresponding to such platforms may also be appropriate. It is also + recognized that OS-specific functions outside GSS-API are likely to + exist in order to perform translations among these forms, and that + GSS-API implementations supporting these forms may themselves be + layered atop such OS-specific functions. Inclusion of this support + within GSS-API implementations is intended as a convenience to + applications. + +2.2.1. User Name Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) user_name(1)}. The recommended symbolic name for this + type is "GSS_KRB5_NT_USER_NAME". + + This name type is used to indicate a named user on a local system. + + + +Linn Standards Track [Page 15] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + Its interpretation is OS-specific. This name form is constructed as: + + username + + Assuming that users' principal names are the same as their local + operating system names, an implementation of GSS_Import_name() based + on Kerberos V5 technology can process names of this form by + postfixing an "@" sign and the name of the local realm. + +2.2.2. Machine UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) machine_uid_name(2)}. The recommended symbolic name for + this type is "GSS_KRB5_NT_MACHINE_UID_NAME". + + This name type is used to indicate a numeric user identifier + corresponding to a user on a local system. Its interpretation is + OS-specific. The gss_buffer_desc representing a name of this type + should contain a locally-significant uid_t, represented in host byte + order. The GSS_Import_name() operation resolves this uid into a + username, which is then treated as the User Name Form. + +2.2.3. String UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) string_uid_name(3)}. The recommended symbolic name for + this type is "GSS_KRB5_NT_STRING_UID_NAME". + + This name type is used to indicate a string of digits representing + the numeric user identifier of a user on a local system. Its + interpretation is OS-specific. This name type is similar to the + Machine UID Form, except that the buffer contains a string + representing the uid_t. + +3. Credentials Management + + The Kerberos V5 protocol uses different credentials (in the GSSAPI + sense) for initiating and accepting security contexts. Normal + clients receive a ticket-granting ticket (TGT) and an associated + session key at "login" time; the pair of a TGT and its corresponding + session key forms a credential which is suitable for initiating + security contexts. A ticket-granting ticket, its session key, and + any other (ticket, key) pairs obtained through use of the ticket- + granting-ticket, are typically stored in a Kerberos V5 credentials + cache, sometimes known as a ticket file. + + + + +Linn Standards Track [Page 16] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + The encryption key used by the Kerberos server to seal tickets for a + particular application service forms the credentials suitable for + accepting security contexts. These service keys are typically stored + in a Kerberos V5 key table, or srvtab file. In addition to their use + as accepting credentials, these service keys may also be used to + obtain initiating credentials for their service principal. + + The Kerberos V5 mechanism's credential handle may contain references + to either or both types of credentials. It is a local matter how the + Kerberos V5 mechanism implementation finds the appropriate Kerberos + V5 credentials cache or key table. + + However, when the Kerberos V5 mechanism attempts to obtain initiating + credentials for a service principal which are not available in a + credentials cache, and the key for that service principal is + available in a Kerberos V5 key table, the mechanism should use the + service key to obtain initiating credentials for that service. This + should be accomplished by requesting a ticket-granting-ticket from + the Kerberos Key Distribution Center (KDC), and decrypting the KDC's + reply using the service key. + +4. Parameter Definitions + + This section defines parameter values used by the Kerberos V5 GSS-API + mechanism. It defines interface elements in support of portability, + and assumes use of C language bindings per RFC-1509. + +4.1. Minor Status Codes + + This section recommends common symbolic names for minor_status values + to be returned by the Kerberos V5 GSS-API mechanism. Use of these + definitions will enable independent implementors to enhance + application portability across different implementations of the + mechanism defined in this specification. (In all cases, + implementations of GSS_Display_status() will enable callers to + convert minor_status indicators to text representations.) Each + implementation should make available, through include files or other + means, a facility to translate these symbolic names into the concrete + values which a particular GSS-API implementation uses to represent + the minor_status values specified in this section. + + It is recognized that this list may grow over time, and that the need + for additional minor_status codes specific to particular + implementations may arise. It is recommended, however, that + implementations should return a minor_status value as defined on a + mechanism-wide basis within this section when that code is accurately + representative of reportable status rather than using a separate, + implementation-defined code. + + + +Linn Standards Track [Page 17] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +4.1.1. Non-Kerberos-specific codes + + GSS_KRB5_S_G_BAD_SERVICE_NAME + /* "No @ in SERVICE-NAME name string" */ + GSS_KRB5_S_G_BAD_STRING_UID + /* "STRING-UID-NAME contains nondigits" */ + GSS_KRB5_S_G_NOUSER + /* "UID does not resolve to username" */ + GSS_KRB5_S_G_VALIDATE_FAILED + /* "Validation error" */ + GSS_KRB5_S_G_BUFFER_ALLOC + /* "Couldn't allocate gss_buffer_t data" */ + GSS_KRB5_S_G_BAD_MSG_CTX + /* "Message context invalid" */ + GSS_KRB5_S_G_WRONG_SIZE + /* "Buffer is the wrong size" */ + GSS_KRB5_S_G_BAD_USAGE + /* "Credential usage type is unknown" */ + GSS_KRB5_S_G_UNKNOWN_QOP + /* "Unknown quality of protection specified" */ + +4.1.2. Kerberos-specific-codes + + GSS_KRB5_S_KG_CCACHE_NOMATCH + /* "Principal in credential cache does not match desired name" */ + GSS_KRB5_S_KG_KEYTAB_NOMATCH + /* "No principal in keytab matches desired name" */ + GSS_KRB5_S_KG_TGT_MISSING + /* "Credential cache has no TGT" */ + GSS_KRB5_S_KG_NO_SUBKEY + /* "Authenticator has no subkey" */ + GSS_KRB5_S_KG_CONTEXT_ESTABLISHED + /* "Context is already fully established" */ + GSS_KRB5_S_KG_BAD_SIGN_TYPE + /* "Unknown signature type in token" */ + GSS_KRB5_S_KG_BAD_LENGTH + /* "Invalid field length in token" */ + GSS_KRB5_S_KG_CTX_INCOMPLETE + /* "Attempt to use incomplete security context" */ + +4.2. Quality of Protection Values + + This section defines Quality of Protection (QOP) values to be used + with the Kerberos V5 GSS-API mechanism as input to GSS_Wrap() and + GSS_GetMIC() routines in order to select among alternate integrity + and confidentiality algorithms. Additional QOP values may be added in + future versions of this specification. Non-overlapping bit positions + are and will be employed in order that both integrity and + + + +Linn Standards Track [Page 18] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + confidentiality QOP may be selected within a single parameter, via + inclusive-OR of the specified integrity and confidentiality values. + +4.2.1. Integrity Algorithms + + The following Quality of Protection (QOP) values are currently + defined for the Kerberos V5 GSS-API mechanism, and are used to select + among alternate integrity checking algorithms. + + GSS_KRB5_INTEG_C_QOP_MD5 (numeric value: 1) + /* Integrity using partial MD5 ("MD2.5") of plaintext */ + + GSS_KRB5_INTEG_C_QOP_DES_MD5 (numeric value: 2) + /* Integrity using DES MAC of MD5 of plaintext */ + + GSS_KRB5_INTEG_C_QOP_DES_MAC (numeric value: 3) + /* Integrity using DES MAC of plaintext */ + +4.2.2. Confidentiality Algorithms + + Only one confidentiality QOP value is currently defined for the + Kerberos V5 GSS-API mechanism: + + GSS_KRB5_CONF_C_QOP_DES (numeric value: 0) + /* Confidentiality with DES */ + + Note: confidentiality QOP should be indicated only by GSS-API calls + capable of providing confidentiality services. If non-zero + confidentiality QOP values are defined in future to represent + different algorithms, therefore, the bit positions containing those + values should be cleared before being returned by implementations of + GSS_GetMIC() and GSS_VerifyMIC(). + +4.3. Buffer Sizes + + All implementations of this specification shall be capable of + accepting buffers of at least 16 Kbytes as input to GSS_GetMIC(), + GSS_VerifyMIC(), and GSS_Wrap(), and shall be capable of accepting + the output_token generated by GSS_Wrap() for a 16 Kbyte input buffer + as input to GSS_Unwrap(). Support for larger buffer sizes is optional + but recommended. + + + + + + + + + + +Linn Standards Track [Page 19] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +5. Security Considerations + + Security issues are discussed throughout this memo. + +6. References + + + [RFC-1321]: Rivest, R., "The MD5 Message-Digest Algorithm", RFC + 1321, April 1992. + + [RFC-1508]: Linn, J., "Generic Security Service Application Program + Interface", RFC 1508, September 1993. + + [RFC-1509]: Wray, J., "Generic Security Service Application Program + Interface: C-bindings", RFC 1509, September 1993. + + [RFC-1510]: Kohl, J., and C. Neuman, "The Kerberos Network + Authentication Service (V5)", RFC 1510, September 1993. + + [FIPS-PUB-113]: National Bureau of Standards, Federal Information + Processing Standard 113, "Computer Data Authentication", May 1985. + +AUTHOR'S ADDRESS + + John Linn + OpenVision Technologies + One Main St. + Cambridge, MA 02142 USA + + Phone: +1 617.374.2245 + EMail: John.Linn@ov.com + + + + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 20] + diff --git a/doc/standardisation/draft-ietf-cat-gssv2-08.txt b/doc/standardisation/draft-ietf-cat-gssv2-08.txt new file mode 100644 index 000000000..ccba35eeb --- /dev/null +++ b/doc/standardisation/draft-ietf-cat-gssv2-08.txt @@ -0,0 +1,62 @@ + + +A new Request for Comments is now available in online RFC libraries. + + + RFC 2078 + + Title: Generic Security Service Application Program + Interface, Version 2 + Author: J. Linn + Date: January 1997 + Mailbox: John.Linn@ov.com + Pages: 85 + Characters: 185990 + Obsoletes: 1508 + + URL: ftp://ds.internic.net/rfc/rfc2078.txt + + +This memo revises RFC-1508, making specific, incremental changes in +response to implementation experience and liaison requests. It is +intended, therefore, that this memo or a successor version thereto +will become the basis for subsequent progression of the GSS-API +specification on the standards track. This document is a product of +the Common Authentication Technology Working Group. + +This is now a Proposed Standard Protocol. + +This document specifies an Internet standards track protocol for the +Internet community, and requests discussion and suggestions for +improvements. Please refer to the current edition of the "Internet +Official Protocol Standards" (STD 1) for the standardization state and +status of this protocol. Distribution of this memo is unlimited. + +This announcement is sent to the IETF list and the RFC-DIST list. +Requests to be added to or deleted from the IETF distribution list +should be sent to IETF-REQUEST@CNRI.RESTON.VA.US. Requests to be +added to or deleted from the RFC-DIST distribution list should +be sent to RFC-DIST-REQUEST@ISI.EDU. + +Details on obtaining RFCs via FTP or EMAIL may be obtained by sending +an EMAIL message to rfc-info@ISI.EDU with the message body +help: ways_to_get_rfcs. For example: + + To: rfc-info@ISI.EDU + Subject: getting rfcs + + help: ways_to_get_rfcs + +Requests for special distribution should be addressed to either the +author of the RFC in question, or to admin@DS.INTERNIC.NET. Unless +specifically noted otherwise on the RFC itself, all RFCs are for +unlimited distribution. + +Submissions for Requests for Comments should be sent to +RFC-EDITOR@ISI.EDU. Please consult RFC 1543, Instructions to RFC +Authors, for further information. + + +Joyce K. Reynolds and Mary Kennedy +USC/Information Sciences Institute + diff --git a/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt b/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt new file mode 100644 index 000000000..518f4c63d --- /dev/null +++ b/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt @@ -0,0 +1,6188 @@ + + Internet draft J.Wray + IETF Common Authentication Technology WG Digital Equipment Corporation + March 1997 + + + + Generic Security Service API Version 2 : C-bindings + + + 1. STATUS OF THIS MEMO + + This document is an Internet Draft. Internet Drafts are working + documents of the Internet Engineering Task Force (IETF), its Areas, and + its Working Groups. Note that other groups may also distribute working + documents as Internet Drafts. Internet Drafts are draft documents valid + for a maximum of six months. Internet Drafts may be updated, replaced, + or obsoleted by other documents at any time. It is not appropriate to + use Internet Drafts as reference material or to cite them other than as + a "working draft" or "work in progress." Please check the I-D abstract + listing contained in each Internet Draft directory to learn the current + status of this or any other Internet Draft. + + Comments on this document should be sent to "cat-ietf@MIT.EDU", the IETF + Common Authentication Technology WG discussion list. + + + 2. ABSTRACT + + This draft document specifies C language bindings for Version 2 of the + Generic Security Service Application Program Interface (GSSAPI), which + is described at a language-independent conceptual level in other drafts + [GSSAPI]. It revises RFC-1509, making specific incremental changes in + response to implementation experience and liaison requests. It is + intended, therefore, that this draft or a successor version thereof will + become the basis for subsequent progression of the GSS-API specification + on the standards track. + + 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, + GSSAPI callers will be application protocols into which security + enhancements are integrated through invocation of services provided by + the GSSAPI. The GSSAPI 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. + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 1] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 3. INTRODUCTION + + The Generic Security Service Application Programming Interface [GSSAPI] + provides security services to calling applications. It allows a + communicating application to authenticate the user associated with + another application, to delegate rights to another application, and to + apply security services such as confidentiality and integrity on a per- + message basis. + + There are four stages to using the GSSAPI: + + (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. + + (b) A pair of communicating applications establish a joint security + context using their credentials. The security context is a pair + of GSSAPI 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. + + To establish and maintain the shared information that makes up the + security context, certain GSSAPI calls will return a token data + structure, which is a cryptographically protected opaque data + type. The caller of such a GSSAPI routine is responsible for + transferring the token to the peer application, encapsulated if + necessary in an application-application protocol. On receipt of + such a token, the peer application should pass it to a + corresponding GSSAPI routine which will decode the token and + extract the information, updating the security context state + information accordingly. + + (c) Per-message services are invoked to apply either: + + (i) integrity and data origin authentication, or + + (ii) confidentiality, integrity and data origin authentication + + to application data, which are treated by GSSAPI as arbitrary + octet-strings. An application transmitting a message that it + + + + Wray Document Expiration: 1 September 1997 [Page 2] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + wishes to protect will call the appropriate GSSAPI 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. + + (d) At the completion of a communications session (which may extend + across several transport connections), each application calls a + GSSAPI 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. + + + 4. GSSAPI ROUTINES + + This section lists the routines that make up the GSSAPI, and offers a + brief description of the purpose of each routine. Detailed descriptions + of each routine are listed in alphabetical order in section 7. + + Table 4-1 GSSAPI Credential-management Routines + + ROUTINE SECTION FUNCTION + + gss_acquire_cred 7.2 Assume a global identity; + Obtain a GSSAPI credential + handle for pre-existing + credentials. + + gss_add_cred 7.3 Construct credentials + incrementally + + gss_inquire_cred 7.21 Obtain information about + a credential. + + gss_inquire_cred_by_mech 7.22 Obtain per-mechanism information + about a credential. + + gss_release_cred 7.27 Discard a credential handle. + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 3] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Table 4-2 GSSAPI Context-level Routines + + ROUTINE SECTION FUNCTION + + gss_init_sec_context 7.19 Initiate a security context + with a peer application + + + gss_accept_sec_context 7.1 Accept a security context + initiated by a peer + application + + gss_delete_sec_context 7.9 Discard a security context + + gss_process_context_token 7.25 Process a token on a security + context from a peer + application + + gss_context_time 7.7 Determine for how long a + context will remain valid + + gss_inquire_context 7.20 Obtain information about a + security context + + gss_wrap_size_limit 7.33 Determine token-size limit for + gss_wrap on a context + + gss_export_sec_context 7.14 Transfer a security context to + another process + + gss_import_sec_context 7.17 Import a transferred context + + + + + Table 4-3 GSSAPI Per-message Routines + + ROUTINE SECTION FUNCTION + + gss_get_mic 7.15 Calculate a cryptographic + Message Integrity Code (MIC) + for a message; integrity service + + gss_verify_mic 7.32 Check a MIC against a message; + verify integrity of a received + message + + gss_wrap 7.36 Attach a MIC to a message, and + optionally encrypt the message + content; confidentiality service + + + + + Wray Document Expiration: 1 September 1997 [Page 4] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_unwrap 7.31 Verify a message with attached + MIC, and decrypt message + content if necessary. + + + + + Table 4-4 GSSAPI Name manipulation Routines + + ROUTINE SECTION FUNCTION + + gss_import_name 7.16 Convert a contiguous string name + to internal-form + + gss_display_name 7.10 Convert internal-form name + to text + + gss_compare_name 7.6 Compare two internal-form names + + gss_release_name 7.28 Discard an internal-form name + + gss_inquire_names_for_mech 7.24 List the name-types supported + by a specified mechanism + + gss_inquire_mechs_for_name 7.23 List mechanisms that support + a given nametype + + gss_canonicalize_name 7.5 Convert an internal name to + an MN. + + gss_export_name 7.13 Convert an MN to export form + + gss_duplicate_name 7.12 Create a copy of an internal name + + + + + Table 4-5 GSSAPI Miscellaneous Routines + + ROUTINE SECTION FUNCTION + + gss_display_status 7.11 Convert a GSSAPI status code + to text + + gss_indicate_mechs 7.18 Determine available underlying + authentication mechanisms + + gss_release_buffer 7.26 Discard a buffer + + gss_release_oid_set 7.29 Discard a set of object + identifiers + + + + Wray Document Expiration: 1 September 1997 [Page 5] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_create_empty_oid_set 7.8 Create a set containing no + object identifiers + + gss_add_oid_set_member 7.4 Add an object identifier to + a set + + gss_test_oid_set_member 7.30 Determines whether an object + identifier is a member of a set + + + + + + Individual GSSAPI 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. + + + 5. DATA TYPES AND CALLING CONVENTIONS + + The following conventions are used by the GSSAPI C-language bindings: + + 5.1. Integer types + + GSSAPI uses the following integer data type: + + OM_uint32 32-bit unsigned integer + + Where guaranteed minimum bit-count is important, this portable data type + is used by the GSSAPI routine definitions. Individual GSSAPI + implementations will include appropriate typedef definitions to map this + type onto a built-in data type. If the platform supports the X/Open + xom.h header file, the OM_uint32 definition contained therein should be + used; the GSSAPI header file in Appendix A contains logic that will + detect the prior inclusion of xom.h, and will not attempt to re-declare + OM_uint32. If the X/Open header file is not available on the platform, + the GSSAPI implementation should use the smallest natural unsigned + integer type that provides at least 32 bits of precision. + + 5.2. String and similar data + + Many of the GSSAPI routines take arguments and return values that + describe contiguous octet-strings. All such data is passed between the + GSSAPI and the caller using the gss_buffer_t data type. This data type + is a pointer to a buffer descriptor, which consists of a length field + that contains the total number of bytes in the datum, and a value field + which contains a pointer to the actual datum: + + + + + + Wray Document Expiration: 1 September 1997 [Page 6] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + Storage for data returned to the application by a GSSAPI routine using + the gss_buffer_t conventions is allocated by the GSSAPI routine. The + application may free this storage by invoking the gss_release_buffer + routine. Allocation of the gss_buffer_desc object is always the + responsibility of the application; unused gss_buffer_desc objects may + be initialized to the value GSS_C_EMPTY_BUFFER. + + 5.2.1. Opaque data types + + Certain multiple-word data items are considered opaque data types at the + GSSAPI, because their internal structure has no significance either to + the GSSAPI or to the caller. Examples of such opaque data types are the + input_token parameter to gss_init_sec_context (which is opaque to the + caller), and the input_message parameter to gss_wrap (which is opaque to + the GSSAPI). Opaque data is passed between the GSSAPI and the + application using the gss_buffer_t datatype. + + 5.2.2. Character strings + + Certain multiple-word data items may be regarded as simple ISO Latin-1 + character strings. Examples are the printable strings passed to + gss_import_name via the input_name_buffer parameter. Some GSSAPI + routines also return character strings. All such character strings are + passed between the application and the GSSAPI implementation using the + gss_buffer_t datatype, which is a pointer to a gss_buffer_desc object. + + When a gss_buffer_desc object describes a printable string, the length + field of the gss_buffer_desc should only count printable characters + within the string. In particular, a trailing NUL character should NOT + be included in the length count, nor should either the GSSAPI + implementation or the application assume the presence of an uncounted + trailing NUL. + + 5.3. Object Identifiers + + Certain GSSAPI procedures take parameters of the type gss_OID, or Object + identifier. This is a type containing ISO-defined tree-structured + values, and is used by the GSSAPI caller to select an underlying + security mechanism and to specify namespaces. A value of type gss_OID + has the following structure: + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + + + + Wray Document Expiration: 1 September 1997 [Page 7] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + The elements field of this structure points to the first byte of an + octet string containing the ASN.1 BER encoding of the value portion of + the normal BER TLV encoding of the gss_OID. The length field contains + the number of bytes in this value. For example, the gss_OID value + corresponding to {iso(1) identified-organization(3) icd-ecma(12) + member-company(2) dec(1011) cryptoAlgorithms(7) DASS(5)}, meaning the + DASS X.509 authentication mechanism, has a length field of 7 and an + elements field pointing to seven octets containing the following octal + values: 53,14,2,207,163,7,5. GSSAPI implementations should provide + constant gss_OID values to allow applications to request any supported + mechanism, although applications are encouraged on portability grounds + to accept the default mechanism. gss_OID values should also be provided + to allow applications to specify particular name types (see section + 5.10). Applications should treat gss_OID_desc values returned by GSSAPI + routines as read-only. In particular, the application should not + attempt to deallocate them with free(). The gss_OID_desc datatype is + equivalent to the X/Open OM_object_identifier datatype[XOM]. + + 5.4. Object Identifier Sets + + Certain GSSAPI procedures take parameters of the type gss_OID_set. This + type represents one or more object identifiers (section 5.3). A + gss_OID_set object has the following structure: + + typedef struct gss_OID_set_desc_struct { + size_t count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + The count field contains the number of OIDs within the set. The + elements field is a pointer to an array of gss_OID_desc objects, each of + which describes a single OID. gss_OID_set values are used to name the + available mechanisms supported by the GSSAPI, to request the use of + specific mechanisms, and to indicate which mechanisms a given credential + supports. + + All OID sets returned to the application by GSSAPI are dynamic objects + (the gss_OID_set_desc, the "elements" array of the set, and the + "elements" array of each member OID are all dynamically allocated), and + this storage must be deallocated by the application using the + gss_release_oid_set() routine. + + + 5.5. Credentials + + A credential handle is a caller-opaque atomic datum that identifies a + GSSAPI credential data structure. It is represented by the caller- + opaque type gss_cred_id_t, which should be implemented as a pointer or + arithmetic type. If a pointer implementation is chosen, care must be + taken to ensure that two gss_cred_id_t values may be compared with the + == operator. + + + + Wray Document Expiration: 1 September 1997 [Page 8] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSSAPI credentials can contain mechanism-specific principal + authentication data for multiple mechanisms. A GSSAPI credential is + composed of a set of credential-elements, each of which is applicable to + a single mechanism. A credential may contain at most one credential- + element for each supported mechanism. A credential-element identifies + the data needed by a single mechanism to authenticate a single + principal, and conceptually contains two credential-references that + describing the actual mechanism-specific authentication data, one to be + used by GSSAPI for initiating contexts, and one to be used for + accepting contexts. For mechanisms that do not distinguish between + acceptor and initiator credentials, both references would point to the + same underlying mechanism-specific authentication data. + + Credentials describe a set of mechanism-specific principals, and give + their holder the ability to act as any of those principals. All + principal identities asserted by a single GSSAPI credential should + belong to the same entity, although enforcement of this property is an + implementation-specific matter. The GSSAPI does not make the actual + credentials available to applications; instead a credential handle is + used to identify a particular credential, held internally by GSSAPI. + The combination of GSSAPI credential handle and mechanism identifies the + principal whose identity will be asserted by the credential when used + with that mechanism. + + The gss_init_sec_context and gss_accept_sec_context routines allow the + value GSS_C_NO_CREDENTIAL to be specified as their credential handle + parameter. This special credential-handle indicates a desire by the + application to act as a default principal. While individual GSSAPI + implementations are free to determine such default behavior as + appropriate to the mechanism, the following default behavior by these + routines is recommended for portability: + + (a) gss_init_sec_context + + (i) If there is only a single principal capable of initiating + security contexts for the chosen mechanism that the + application is authorized to act on behalf of, then that + principal shall be used, otherwise + + (ii) If the platform maintains a concept of a default network- + identity for the chosen mechanism, and if the application is + authorized to act on behalf of that identity for the purpose + of initiating security contexts, then the principal + corresponding to that identity shall be used, otherwise + + (iii) If the platform maintains a concept of a default local + identity, and provides a means to map local identities into + network-identities for the chosen mechanism, and if the + application is authorized to act on behalf of the network- + identity image of the default local identity for the purpose + of initiating security contexts using the chosen mechanism, + + + + Wray Document Expiration: 1 September 1997 [Page 9] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + then the principal corresponding to that identity shall be + used, otherwise + + (iv) A user-configurable default identity should be used. + + (b) gss_accept_sec_context + + (i) If there is only a single authorized principal identity + capable of accepting security contexts for the chosen + mechanism, then that principal shall be used, otherwise + + (ii) If the mechanism can determine the identity of the target + principal by examining the context-establishment token, and + if the accepting application is authorized to act as that + principal for the purpose of accepting security contexts + using the chosen mechanism, then that principal identity + shall be used, otherwise + + (iii) If the mechanism supports context acceptance by any + principal, and if mutual authentication was not requested, + any principal that the application is authorized to accept + security contexts under using the chosen mechanism may be + used, otherwise + + (iv) A user-configurable default identity shall be used. + + The purpose of the above rules is to allow security contexts to be + established by both initiator and acceptor using the default behavior + wherever possible. Applications requesting default behavior are likely + to be more portable across mechanisms and platforms than ones that use + gss_acquire_cred to request a specific identity. + + 5.6. Contexts + + The gss_ctx_id_t data type contains a caller-opaque atomic value that + identifies one end of a GSSAPI security context. It should be + implemented as a pointer or arithmetic type. If a pointer type is + chosen, care should be taken to ensure that two gss_ctx_id_t values may + be compared with the == operator. + + The security context holds state information about each end of a peer + communication, including cryptographic state information. + + 5.7. Authentication tokens + + A token is a caller-opaque type that GSSAPI uses to maintain + synchronization between the context data structures at each end of a + GSSAPI security context. The token is a cryptographically protected + octet-string, generated by the underlying mechanism at one end of a + GSSAPI security context for use by the peer mechanism at the other end. + Encapsulation (if required) and transfer of the token are the + + + + Wray Document Expiration: 1 September 1997 [Page 10] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + responsibility of the peer applications. A token is passed between the + GSSAPI and the application using the gss_buffer_t conventions. + + 5.8. Interprocess tokens + + Certain GSSAPI routines are intended to transfer data between processes + in multi-process programs. These routines use a caller-opaque octet- + string, generated by the GSSAPI in one process for use by the GSSAPI in + another process. The calling application is responsible for + transferring such tokens between processes in an OS-specific manner. + Note that, while GSSAPI implementors are encouraged to avoid placing + sensitive information within interprocess tokens, or to + cryptographically protect them, many implementations will be unable to + avoid placing key material or other sensitive data within them. It is + the application's responsibility to ensure that interprocess tokens are + protected in transit, and transferred only to processes that are + trustworthy. An interprocess token is passed between the GSSAPI and the + application using the gss_buffer_t conventions. + + 5.9. Status values + + One or more status codes are returned by each GSSAPI routine. Two + distinct sorts of status codes are returned. These are termed GSS + status codes and Mechanism status codes. + + 5.9.1. GSS status codes + + GSSAPI routines return GSS status codes as their OM_uint32 function + value. These codes indicate errors that are independent of the + underlying mechanism(s) used to provide the security service. The + errors that can be indicated via a GSS status code are either generic + API routine errors (errors that are defined in the GSS-API + specification) or calling errors (errors that are specific to these + language bindings). + + A GSS status code can indicate a single fatal generic API error from the + routine and a single calling error. In addition, supplementary status + information may be indicated via the setting of bits in the + supplementary info field of a GSS status code. + + These errors are encoded into the 32-bit GSS status code as follows: + + MSB LSB + |------------------------------------------------------------| + | Calling Error | Routine Error | Supplementary Info | + |------------------------------------------------------------| + Bit 31 24 23 16 15 0 + + + Hence if a GSS-API routine returns a GSS status code whose upper 16 bits + contain a non-zero value, the call failed. If the calling error field + + + + Wray Document Expiration: 1 September 1997 [Page 11] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + is non-zero, the invoking application's call of the routine was + erroneous. Calling errors are defined in table 5-1. If the routine + error field is non-zero, the routine failed for one of the routine- + specific reasons listed below in table 5-2. Whether or not the upper 16 + bits indicate a failure or a success, the routine may indicate + additional information by setting bits in the supplementary info field + of the status code. The meaning of individual bits is listed below in + table 5-3. + + Table 5-1 Calling Errors + + Name Value in Meaning + Field + GSS_S_CALL_INACCESSIBLE_READ 1 A required input + parameter could + not be read. + GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output + parameter could + not be written. + GSS_S_CALL_BAD_STRUCTURE 3 A parameter was + malformed + + + + + Table 5-2 Routine Errors + + Name Value in Meaning + Field + + GSS_S_BAD_MECH 1 An unsupported mechanism was + requested + GSS_S_BAD_NAME 2 An invalid name was supplied + GSS_S_BAD_NAMETYPE 3 A supplied name was of an + unsupported type + GSS_S_BAD_BINDINGS 4 Incorrect channel bindings + were supplied + GSS_S_BAD_STATUS 5 An invalid status code was + supplied + GSS_S_BAD_SIG 6 A token had an invalid + GSS_S_BAD_MIC MIC + GSS_S_NO_CRED 7 No credentials were supplied, + or the credentials were + unavailable or inaccessible. + GSS_S_NO_CONTEXT 8 No context has been + established + GSS_S_DEFECTIVE_TOKEN 9 A token was invalid + GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid + GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials + have expired + + + + + Wray Document Expiration: 1 September 1997 [Page 12] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_CONTEXT_EXPIRED 12 The context has expired + GSS_S_FAILURE 13 Miscellaneous failure + (see text) + GSS_S_BAD_QOP 14 The quality-of-protection + requested could not be + provide + GSS_S_UNAUTHORIZED 15 The operation is forbidden by + local security policy + GSS_S_UNAVAILABLE 16 The operation or option is not + available + GSS_S_DUPLICATE_ELEMENT 17 The requested credential element + already exists + GSS_S_NAME_NOT_MN 18 The provided name was not a + mechanism name. + + + + + + Table 5-3 Supplementary Status Bits + + Name Bit Number Meaning + GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called + again to complete its function. + See routine documentation for + detailed description. + GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of + an earlier token + GSS_S_OLD_TOKEN 2 The token's validity period + has expired + GSS_S_UNSEQ_TOKEN 3 A later token has already been + processed + GSS_S_GAP_TOKEN 4 An expected per-message token + was not received + + + The routine documentation also uses the name GSS_S_COMPLETE, which is a + zero value, to indicate an absence of any API errors or supplementary + information bits. + + All GSS_S_xxx symbols equate to complete OM_uint32 status codes, rather + than to bitfield values. For example, the actual value of the symbol + GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 << 16. + + The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and + GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS status + code and removes all but the relevant field. For example, the value + obtained by applying GSS_ROUTINE_ERROR to a status code removes the + calling errors and supplementary info fields, leaving only the routine + errors field. The values delivered by these macros may be directly + compared with a GSS_S_xxx symbol of the appropriate type. The macro + + + + Wray Document Expiration: 1 September 1997 [Page 13] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_ERROR() is also provided, which when applied to a GSS status code + returns a non-zero value if the status code indicated a calling or + routine error, and a zero value otherwise. All macros defined by GSS- + API evaluate their argument(s) exactly once. + + A GSS-API implementation may choose to signal calling errors in a + platform-specific manner instead of, or in addition to the routine + value; routine errors and supplementary info should be returned via + routine status values only. + + 5.9.2. Mechanism-specific status codes + + GSS-API routines return a minor_status parameter, which is used to + indicate specialized errors from the underlying security mechanism. + This parameter may contain a single mechanism-specific error, indicated + by a OM_uint32 value. + + The minor_status parameter will always be set by a GSS-API routine, even + if it returns a calling error or one of the generic API errors indicated + above as fatal, although most other output parameters may remain unset + in such cases. However, output parameters that are expected to return + pointers to storage allocated by a routine must always be set by the + routine, even in the event of an error, although in such cases the GSS- + API routine may elect to set the returned parameter value to NULL to + indicate that no storage was actually allocated. Any length field + associated with such pointers (as in a gss_buffer_desc structure) should + also be set to zero in such cases. + + The GSS status code GSS_S_FAILURE is used to indicate that the + underlying mechanism detected an error for which no specific GSS status + code is defined. The mechanism status code will provide more details + about the error. + + 5.10. Names + + A name is used to identify a person or entity. GSS-API authenticates + the relationship between a name and the entity claiming the name. + + Since different authentication mechanisms may employ different + namespaces for identifying their principals, GSSAPI's naming support is + necessarily complex in multi-mechanism environments (or even in some + single-mechanism environments where the underlying mechanism supports + multiple namespaces). + + Two distinct representations are defined for names: + + (a) An internal form. This is the GSSAPI "native" format for names, + represented by the implementation-specific gss_name_t type. It is + opaque to GSSAPI callers. A single gss_name_t object may contain + multiple names from different namespaces, but all names should + refer to the same entity. An example of such an internal name + + + + Wray Document Expiration: 1 September 1997 [Page 14] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + would be the name returned from a call to the gss_inquire_cred + routine, when applied to a credential containing credential + elements for multiple authentication mechanisms employing + different namespaces. This gss_name_t object will contain a + distinct name for the entity for each authentication mechanism. + + For GSSAPI implementations supporting multiple namespaces, objects + of type gss_name_t must contain sufficient information to + determine the namespace to which each primitive name belongs. + + (b) Mechanism-specific contiguous octet-string forms. A format + capable of containing a single name (from a single namespace). + Contiguous string names are always accompanied by an object + identifier specifying the namespace to which the name belongs, and + their format is dependent on the authentication mechanism that + employs the name. Many, but not all, contiguous string names will + be printable, and may therefore be used by GSSAPI applications for + communication with their users. + + Routines (gss_import_name and gss_display_name) are provided to convert + names between contiguous string representations and the internal + gss_name_t type. gss_import_name may support multiple syntaxes for each + supported namespace, allowing users the freedom to choose a preferred + name representation. gss_display_name should use an implementation- + chosen printable syntax for each supported name-type. + + If an application calls gss_display_name(), passing the internal name + resulting from a call to gss_import_name(), there is no guarantee the + the resulting contiguous string name will be the same as the original + imported string name. Nor do name-space identifiers necessarily survive + unchanged after a journey through the internal name-form. An example of + this might be a mechanism that authenticates X.500 names, but provides + an algorithmic mapping of Internet DNS names into X.500. That + mechanism's implementation of gss_import_name() might, when presented + with a DNS name, generate an internal name that contained both the + original DNS name and the equivalent X.500 name. Alternatively, it might + only store the X.500 name. In the latter case, gss_display_name() would + most likely generate a printable X.500 name, rather than the original + DNS name. + + The process of authentication delivers to the context acceptor an + internal name. Since this name has been authenticated by a single + mechanism, it contains only a single name (even if the internal name + presented by the context initiator to gss_init_sec_context had multiple + components). Such names are termed internal mechanism names, or "MN"s + and the names emitted by gss_accept_sec_context() are always of this + type. Since some applications may require MNs without wanting to incur + the overhead of an authentication operation, a second function, + gss_canonicalize_name(), is provided to convert a general internal name + into an MN. + + + + + Wray Document Expiration: 1 September 1997 [Page 15] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Comparison of internal-form names may be accomplished via the + gss_compare_name() routine, which returns true if the two names being + compared refer to the same entity. This removes the need for the + application program to understand the syntaxes of the various printable + names that a given GSS-API implementation may support. Since GSSAPI + assumes that all primitive names contained within a given internal name + refer to the same entity, gss_compare_name() can return true if the two + names have at least one primitive name in common. If the implementation + embodies knowledge of equivalence relationships between names taken from + different namespaces, this knowledge may also allow successful + comparison of internal names containing no overlapping primitive + elements. + + When used in large access control lists, the overhead of invoking + gss_import_name() and gss_compare_name() on each name from the ACL may + be prohibitive. As an alternative way of supporting this case, GSSAPI + defines a special form of the contiguous string name which may be + compared directly (e.g. with memcmp()). Contigous names suitable for + comparison are generated by the gss_export_name() routine, which + requires an MN as input. Exported names may be re-imported by the + gss_import_name() routine, and the resulting internal name will also be + an MN. The gss_OID constant GSS_C_NT_EXPORT_NAME indentifies the + "export name" type, and the value of this constant is given in Appendix + A. Structurally, an exported name object consists of a header + containing an OID identifying the mechanism that authenticated the name, + and a trailer containing the name itself, where the syntax of the + trailer is defined by the individual mechanism specification. The + precise format of an export name is defined in the language-independent + GSSAPI specification [GSSAPI]. + + Note that the results obtained by using gss_compare_name() will in + general be different from those obtained by invoking + gss_canonicalize_name() and gss_export_name(), and then comparing the + exported names. The first series of operation determines whether two + (unauthenticated) names identify the same principal; the second whether + a particular mechanism would authenticate them as the same principal. + These two operations will in general give the same results only for MNs. + + The gss_name_t datatype should be implemented as a pointer type. To + allow the compiler to aid the application programmer by performing + type-checking, the use of (void *) is discouraged. A pointer to an + implementation-defined type is the preferred choice. + + Storage is allocated by routines that return gss_name_t values. A + procedure, gss_release_name, is provided to free storage associated with + an internal-form name. + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 16] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 5.11. Channel Bindings + + GSS-API supports the use of user-specified tags to identify a given + context to the peer application. These tags are intended to be used to + identify the particular communications channel that carries the context. + Channel bindings are communicated to the GSS-API using the following + structure: + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + The initiator_addrtype and acceptor_addrtype fields denote the type of + addresses contained in the initiator_address and acceptor_address + buffers. The address type should be one of the following: + + GSS_C_AF_UNSPEC Unspecified address type + GSS_C_AF_LOCAL Host-local address type + GSS_C_AF_INET Internet address type (e.g. IP) + GSS_C_AF_IMPLINK ARPAnet IMP address type + GSS_C_AF_PUP pup protocols (eg BSP) address type + GSS_C_AF_CHAOS MIT CHAOS protocol address type + GSS_C_AF_NS XEROX NS address type + GSS_C_AF_NBS nbs address type + GSS_C_AF_ECMA ECMA address type + GSS_C_AF_DATAKIT datakit protocols address type + GSS_C_AF_CCITT CCITT protocols + GSS_C_AF_SNA IBM SNA address type + GSS_C_AF_DECnet DECnet address type + GSS_C_AF_DLI Direct data link interface address type + GSS_C_AF_LAT LAT address type + GSS_C_AF_HYLINK NSC Hyperchannel address type + GSS_C_AF_APPLETALK AppleTalk address type + GSS_C_AF_BSC BISYNC 2780/3780 address type + GSS_C_AF_DSS Distributed system services address type + GSS_C_AF_OSI OSI TP4 address type + GSS_C_AF_X25 X25 + GSS_C_AF_NULLADDR No address specified + + Note that these symbols name address families rather than specific + addressing formats. For address families that contain several + alternative address forms, the initiator_address and acceptor_address + fields must contain sufficient information to determine which address + form is used. When not otherwise specified, addresses should be + specified in network byte-order (that is, native byte-ordering for the + address family). + + + + + Wray Document Expiration: 1 September 1997 [Page 17] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Conceptually, the GSS-API concatenates the initiator_addrtype, + initiator_address, acceptor_addrtype, acceptor_address and + application_data to form an octet string. The mechanism calculates a + MIC over this octet string, and binds the MIC to the context + establishment token emitted by gss_init_sec_context. The same bindings + are presented by the context acceptor to gss_accept_sec_context, and a + MIC is calculated in the same way. The calculated MIC is compared with + that found in the token, and if the MICs differ, gss_accept_sec_context + will return a GSS_S_BAD_BINDINGS error, and the context will not be + established. Some mechanisms may include the actual channel binding + data in the token (rather than just a MIC); applications should + therefore not use confidential data as channel-binding components. + Individual mechanisms may impose additional constraints on addresses and + address types that may appear in channel bindings. For example, a + mechanism may verify that the initiator_address field of the channel + bindings presented to gss_init_sec_context contains the correct network + address of the host system. Portable applications should therefore + ensure that they either provide correct information for the address + fields, or omit addressing information, specifying GSS_C_AF_NULLADDR as + the address-types. + + 5.12. Optional parameters + + Various parameters are described as optional. This means that they + follow a convention whereby a default value may be requested. The + following conventions are used for omitted parameters. These + conventions apply only to those parameters that are explicitly + documented as optional. + + 5.12.1. gss_buffer_t types + + Specify GSS_C_NO_BUFFER as a value. For an input parameter this + signifies that default behavior is requested, while for an output + parameter it indicates that the information that would be returned via + the parameter is not required by the application. + + 5.12.2. Integer types (input) + + Individual parameter documentation lists values to be used to indicate + default actions. + + 5.12.3. Integer types (output) + + Specify NULL as the value for the pointer. + + 5.12.4. Pointer types + + Specify NULL as the value. + + + + + + + Wray Document Expiration: 1 September 1997 [Page 18] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 5.12.5. Object IDs + + Specify GSS_C_NO_OID as the value. + + 5.12.6. Object ID Sets + + Specify GSS_C_NO_OID_SET as the value. + + 5.12.7. Channel Bindings + + Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings are + not to be used. + + + 6. ADDITIONAL CONTROLS + + This section discusses the optional services that a context initiator + may request of the GSS-API at context establishment. Each of these + services is requested by setting a flag in the req_flags input parameter + to gss_init_sec_context. + + The optional services currently defined are: + + Delegation - The (usually temporary) transfer of rights from initiator + to acceptor, enabling the acceptor to authenticate itself as an + agent of the initiator. + + Mutual Authentication - In addition to the initiator authenticating its + identity to the context acceptor, the context acceptor should also + authenticate itself to the initiator. + + Replay detection - In addition to providing message integrity services, + gss_get_mic and gss_wrap should include message numbering + information to enable gss_verify_mic and gss_unwrap to detect if a + message has been duplicated. + + Out-of-sequence detection - In addition to providing message integrity + services, gss_get_mic and gss_wrap should include message + sequencing information to enable gss_verify_mic and gss_unwrap to + detect if a message has been received out of sequence. + + Anonymous authentication - The establishment of the security context + should not reveal the initiator's identity to the context + acceptor. + + Any currently undefined bits within such flag arguments should be + ignored by GSS-API implementations when presented by an application, and + should be set to zero when returned to the application by the GSS-API + implementation. + + + + + + Wray Document Expiration: 1 September 1997 [Page 19] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Some mechanisms may not support all optional services, and some + mechanisms may only support some services in conjunction with others. + Both gss_init_sec_context and gss_accept_sec_context inform the + applications which services will be available from the context when the + establishment phase is complete, via the ret_flags output parameter. In + general, if the security mechanism is capable of providing a requested + service, it should do so, even if additional services must be enabled in + order to provide the requested service. If the mechanism is incapable + of providing a requested service, it should proceed without the service, + leaving the application to abort the context establishment process if it + considers the requested service to be mandatory. + + Some mechanisms may specify that support for some services is optional, + and that implementors of the mechanism need not provide it. This is + most commonly true of the confidentiality service, often because of + legal restrictions on the use of data-encryption, but may apply to any + of the services. Such mechanisms are required to send at least one + token from acceptor to initiator during context establishment when the + initiator indicates a desire to use such a service, so that the + initiating GSSAPI can correctly indicate whether the service is + supported by the acceptor's GSSAPI. + + 6.1. Delegation + + The GSS-API allows delegation to be controlled by the initiating + application via a boolean parameter to gss_init_sec_context(), the + routine that establishes a security context. Some mechanisms do not + support delegation, and for such mechanisms attempts by an application + to enable delegation are ignored. + + The acceptor of a security context for which the initiator enabled + delegation will receive (via the delegated_cred_handle parameter of + gss_accept_sec_context) a credential handle that contains the delegated + identity, and this credential handle may be used to initiate subsequent + GSSAPI security contexts as an agent or delegate of the initiator. If + the original initiator's identity is "A" and the delegate's identity is + "B", then, depending on the underlying mechanism, the identity embodied + by the delegated credential may be either "A" or "B acting for A". + + For many mechanisms that support delegation, a simple boolean does not + provide enough control. Examples of additional aspects of delegation + control that a mechanism might provide to an application are duration of + delegation, network addresses from which delegation is valid, and + constraints on the tasks that may be performed by a delegate. Such + controls are presently outside the scope of the GSS-API. GSS-API + implementations supporting mechanisms offering additional controls + should provide extension routines that allow these controls to be + exercised (perhaps by modifying the initiator's GSS-API credential prior + to its use in establishing a context). However, the simple delegation + control provided by GSS-API should always be able to over-ride other + mechanism-specific delegation controls - If the application instructs + + + + Wray Document Expiration: 1 September 1997 [Page 20] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_init_sec_context() that delegation is not desired, then the + implementation must not permit delegation to occur. This is an + exception to the general rule that a mechanism may enable services even + if they are not requested - delegation may only be provide at the + explicit request of the application. + + 6.2. Mutual authentication + + Usually, a context acceptor will require that a context initiator + authenticate itself so that the acceptor may make an access-control + decision prior to performing a service for the initiator. In some + cases, the initiator may also request that the acceptor authenticate + itself. GSS-API allows the initiating application to request this + mutual authentication service by setting a flag when calling + gss_init_sec_context. + + The initiating application is informed as to whether or not mutual + authentication is being requested of the context acceptor. Note that + some mechanisms may not support mutual authentication, and other + mechanisms may always perform mutual authentication, whether or not the + initiating application requests it. In particular, mutual + authentication my be required by some mechanisms in order to support + replay or out-of-sequence message detection, and for such mechanisms a + request for either of these services will automatically enable mutual + authentication. + + 6.3. Replay and out-of-sequence detection + + The GSS-API may provide detection of mis-ordered message once a security + context has been established. Protection may be applied to messages by + either application, by calling either gss_get_mic or gss_wrap, and + verified by the peer application by calling gss_verify_mic or + gss_unwrap. + + gss_get_mic calculates a cryptographic checksum of an application + message, and returns that checksum in a token. The application should + pass both the token and the message to the peer application, which + presents them to gss_verify_mic. + + gss_wrap calculates a cryptographic checksum of an application message, + and places both the checksum and the message inside a single token. The + application should pass the token to the peer application, which + presents it to gss_unwrap to extract the message and verify the + checksum. + + Either pair of routines may be capable of detecting out-of-sequence + message delivery, or duplication of messages. Details of such mis- + ordered messages are indicated through supplementary status bits in the + major status code returned by gss_verify_mic or gss_unwrap. The + relevant supplementary bits are: + + + + + Wray Document Expiration: 1 September 1997 [Page 21] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has already + been received and processed. Contexts that do not claim to + provide replay detection may still set this bit if the duplicate + message is processed immediately after the original, with no + intervening messages. + + GSS_S_OLD_TOKEN - The token is too old to determine whether or not it is + a duplicate. Contexts supporting out-of-sequence detection but + not replay detection should always set this bit if + GSS_S_UNSEQ_TOKEN is set; contexts that support replay detection + should only set this bit if the token is so old that it cannot be + checked for duplication. + + GSS_S_UNSEQ_TOKEN - A later token has already been processed. + + GSS_S_GAP_TOKEN - An earlier token has not yet been received. + + A mechanism need not maintain a list of all tokens that have been + processed in order to support these status codes. A typical mechanism + might retain information about only the most recent "N" tokens + processed, allowing it to distinguish duplicates and missing tokens + within the most recent "N" messages; the receipt of a token older than + the most recent "N" would result in a GSS_S_OLD_TOKEN status. + + 6.4. Anonymous Authentication + + In certain situations, an application may wish to initiate the + authentication process to authenticate a peer, without revealing its own + identity. As an example, consider an application providing access to a + database containing medical information, and offering unrestricted + access to the service. A client of such a service might wish to + authenticate the service (in order to establish trust in any information + retrieved from it), but might not wish the service to be able to obtain + the client's identity (perhaps due to privacy concerns about the + specific inquiries, or perhaps simply to avoid being placed on mailing- + lists). + + In normal use of the GSS-API, the initiator's identity is made available + to the acceptor as a result of the context establishment process. + However, context initiators may request that their identity not be + revealed to the context acceptor. Many mechanisms do not support + anonymous authentication, and for such mechanisms the request will not + be honored. An authentication token will be still be generated, but the + application is always informed if a requested service is unavailable, + and has the option to abort context establishment if anonymity is valued + above the other security services that would require a context to be + established. + + In addition to informing the application that a context is established + anonymously (via the ret_flags outputs from gss_init_sec_context and + gss_accept_sec_context), the optional src_name output from + + + + Wray Document Expiration: 1 September 1997 [Page 22] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_accept_sec_context and gss_inquire_context will, for such contexts, + return a reserved internal-form name, defined by the implementation. + When presented to gss_display_name, this reserved internal-form name + will result in a printable name that is syntactically distinguishable + from any valid principal name supported by the implementation, + associated with a name-type object identifier with the value + GSS_C_NT_ANONYMOUS, whose value us given in Appendix A. The printable + form of an anonymous name should be chosen such that it implies + anonymity, since this name may appear in, for example, audit logs. For + example, the string "" might be a good choice, if no valid + printable names supported by the implementation can begin with "<" and + end with ">". + + 6.5. Confidentiality + + If a context supports the confidentiality service, gss_wrap may be used + to encrypt application messages. Messages are selectively encrypted, + under the control of the conf_req_flag input parameter to gss_wrap. + + 6.6. Inter-process context transfer + + GSSAPI V2 provides routines (gss_export_sec_context and + gss_import_sec_context) which allow a security context to be transferred + between processes on a single machine. The most common use for such a + feature is a client-server design where the server is implemented as a + single process that accepts incoming security contexts, which then + launches child processes to deal with the data on these contexts. In + such a design, the child processes must have access to the security + context data structure created within the parent by its call to + gss_accept_sec_context so that they can use per-message protection + services and delete the security context when the communication session + ends. + + Since the security context data structure is expected to contain + sequencing information, it is impractical in general to share a context + between processes. Thus GSSAPI provides a call (gss_export_sec_context) + that the process which currently owns the context can call to declare + that it has no intention to use the context subsequently, and to create + an inter-process token containing information needed by the adopting + process to successfully import the context. After successful completion + of this call, the original security context is made inaccessible to the + calling process by GSSAPI, and any context handles referring to this + context are no longer valid. The originating process transfers the + inter-process token to the adopting process, which passes it to + gss_import_sec_context, and a fresh gss_ctx_id_t is created such that it + is functionally identical to the original context. + + The inter-process token may contain sensitive data from the original + security context (including cryptographic keys). Applications using + inter-process tokens to transfer security contexts must take appropriate + steps to protect these tokens in transit. + + + + Wray Document Expiration: 1 September 1997 [Page 23] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Implementations are not required to support the inter-process transfer + of security contexts. The ability to transfer a security context is + indicated when the context is created, by gss_init_sec_context or + gss_accept_sec_context setting the GSS_C_TRANS_FLAG bit in their + ret_flags parameter. + + + 6.7. The use of incomplete contexts + + Some mechanisms may allow the per-message services to be used before the + context establishment process is complete. For example, a mechanism may + include sufficient information in its initial context-level token for + the context acceptor to immediately decode messages protected with + gss_wrap or gss_get_mic. For such a mechanism, the initiating + application need not wait until subsequent context-level tokens have + been sent and received before invoking the per-message protection + services. + + The ability of a context to provide per-message services in advance of + complete context establishment is indicated by the setting of the + GSS_C_PROT_READY_FLAG bit in the ret_flags parameter from + gss_init_sec_context and gss_accept_sec_context. Applications wishing + to use per-message protection services on partially-established contexts + should check this flag before attempting to invoke gss_wrap or + gss_get_mic. + + + + 7. GSS-API routine descriptions + + In addition to the explicit major status codes documented here, the code + GSS_S_FAILURE may be returned by any routine, indicating an + implementation-specific or mechanism-specific error condition, further + details of which are reported via the minor_status parameter. + + + + + + + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 24] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.1. gss_accept_sec_context + + OM_uint32 gss_accept_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + const gss_cred_id_t acceptor_cred_handle, + const gss_buffer_t input_token_buffer, + const gss_channel_bindings_t + input_chan_bindings, + const gss_name_t * src_name, + gss_OID * mech_type, + gss_buffer_t output_token, + OM_uint32 * ret_flags, + OM_uint32 * time_rec, + gss_cred_id_t * delegated_cred_handle) + + Purpose: + + Allows a remotely initiated security context between the application and + a remote peer to be established. The routine may return a output_token + which should be transferred to the peer application, where the peer + application will present it to gss_init_sec_context. If no token need + be sent, gss_accept_sec_context will indicate this by setting the length + field of the output_token argument to zero. To complete the context + establishment, one or more reply tokens may be required from the peer + application; if so, gss_accept_sec_context will return a status flag of + GSS_S_CONTINUE_NEEDED, in which case it should be called again when the + reply token is received from the peer application, passing the token to + gss_accept_sec_context via the input_token parameters. + + Portable applications should be constructed to use the token length and + return status to determine whether a token needs to be sent or waited + for. Thus a typical portable caller should always invoke + gss_accept_sec_context within a loop: + + gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; + ... + + do { + receive_token_from_peer(input_token); + maj_stat = gss_accept_sec_context(&min_stat, + &context_hdl, + cred_hdl, + input_token, + input_bindings, + &client_name, + &mech_type, + output_token, + &ret_flags, + &time_rec, + &deleg_cred); + + + + Wray Document Expiration: 1 September 1997 [Page 25] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + if (GSS_ERROR(maj_stat)) { + report_error(maj_stat, min_stat); + }; + if (output_token->length != 0) { + send_token_to_peer(output_token); + gss_release_buffer(&min_stat, + output_token) + }; + if (GSS_ERROR(maj_stat)) { + if (context_hdl != GSS_C_NO_CONTEXT) + gss_delete_sec_context(&min_stat, + &context_hdl, + GSS_C_NO_BUFFER); + break; + }; + } while (maj_stat & GSS_S_CONTINUE_NEEDED); + + + Whenever the routine returns a major status that includes the value + GSS_S_CONTINUE_NEEDED, the context is not fully established and the + following restrictions apply to the output parameters: + + (a) The value returned via the time_rec parameter is undefined + + (b) Unless the accompanying ret_flags parameter contains the bit + GSS_C_PROT_READY_FLAG, indicating that per-message services may be + applied in advance of a successful completion status, the value + returned via the mech_type parameter may be undefined until the + routine returns a major status value of GSS_S_COMPLETE. + + (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, + GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, + GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the + ret_flags parameter should contain the values that the + implementation expects would be valid if context establishment + were to succeed. + + The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits + within ret_flags should indicate the actual state at the time + gss_accept_sec_context returns, whether or not the context is + fully established. + + Although this requires that GSSAPI implementations set the + GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller + (i.e. when accompanied by a GSS_S_COMPLETE status code), + applications should not rely on this behavior as the flag was not + defined in Version 1 of the GSSAPI. Instead, applications should + be prepared to use per-message services after a successful context + establishment, according to the GSS_C_INTEG_FLAG and + GSS_C_CONF_FLAG values. + + + + + Wray Document Expiration: 1 September 1997 [Page 26] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + All other bits within the ret_flags argument should be set to + zero. + + + While the routine returns GSS_S_CONTINUE_NEEDED, the values returned via + the ret_flags argument indicate the services that the implementation + expects to be available from the established context. + + If the initial call of gss_accept_sec_context() fails, the + implementation should not create a context object, and should leave the + value of the context_handle parameter set to GSS_C_NO_CONTEXT to + indicate this. In the event of a failure on a subsequent call, the + implementation is permitted to delete the "half-built" security context + (in which case it should set the context_handle parameter to + GSS_C_NO_CONTEXT), but the preferred behavior is to leave the security + context (and the context_handle parameter) untouched for the application + to delete (using gss_delete_sec_context). + + Parameters: + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned in subsequent calls. Once + gss_accept_sec_context() has returned a value + via this parameter, resources have been assigned + to the corresponding context, and must be + freed by the application after use with a call + to gss_delete_sec_context(). + + + acceptor_cred_handle gss_cred_id_t, read + Credential handle claimed by context acceptor. + Specify GSS_C_NO_CREDENTIAL to accept the + context as a default principal. If + GSS_C_NO_CREDENTIAL is specified, but no + default acceptor principal is defined, + GSS_S_NO_CRED will be returned. + + input_token_buffer buffer, opaque, read + token obtained from remote application. + + input_chan_bindings channel bindings, read, optional + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. If channel bindings are not + used, specify GSS_C_NO_CHANNEL_BINDINGS. + + src_name gss_name_t, modify, optional + Authenticated name of context initiator. + + + + Wray Document Expiration: 1 September 1997 [Page 27] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + After use, this name should be deallocated by + passing it to gss_release_name(). If not + required, specify NULL. + + mech_type Object ID, modify, optional + Security mechanism used. The returned + OID value will be a pointer into static + storage, and should be treated as read-only + by the caller (in particular, it does not + need to be freed). If not required, specify + NULL. + + output_token buffer, opaque, modify + Token to be passed to peer application. If the + length field of the returned token buffer is 0, + then no token need be passed to the peer + application. If a non-zero length field is + returned, the associated storage must be freed + after use by the application with a call to + gss_release_buffer(). + + ret_flags bit-mask, modify, optional + Contains various independent flags, each of + which indicates that the context supports a + specific service option. If not needed, + specify NULL. Symbolic names are + provided for each flag, and the symbolic names + corresponding to the required flags + should be logically-ANDed with the ret_flags + value to test whether a given option is + supported by the context. The flags are: + GSS_C_DELEG_FLAG + True - Delegated credentials are available + via the delegated_cred_handle + parameter + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer asked for mutual + authentication + False - Remote peer did not ask for mutual + authentication + GSS_C_REPLAY_FLAG + True - replay of protected messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence protected + messages will be detected + False - out-of-sequence messages will not + be detected + + + + Wray Document Expiration: 1 September 1997 [Page 28] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_C_CONF_FLAG + True - Confidentiality service may be invoked + by calling the gss_wrap routine + False - No confidentiality service (via + gss_wrap) available. gss_wrap will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_get_mic or gss_wrap + routines. + False - Per-message integrity service + unavailable. + GSS_C_ANON_FLAG + True - The initiator does not wish to + be authenticated; the src_name + parameter (if requested) contains + an anonymous internal name. + False - The initiator has been + authenticated normally. + GSS_C_PROT_READY_FLAG + True - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + if the accompanying major status return + value is either GSS_S_COMPLETE or + GSS_S_CONTINUE_NEEDED. + False - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + only if the accompanying major status + return value is GSS_S_COMPLETE. + GSS_C_TRANS_FLAG + True - The resultant security context may + be transferred to other processes via + a call to gss_export_sec_context(). + False - The security context is not + transferrable. + All other bits should be set to zero. + + time_rec Integer, modify, optional + number of seconds for which the context + will remain valid. Specify NULL if not required. + + delegated_cred_handle + gss_cred_id_t, modify, optional + credential handle for credentials received from + context initiator. Only valid if deleg_flag in + ret_flags is true, in which case an explicit + + + + Wray Document Expiration: 1 September 1997 [Page 29] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + credential handle (i.e. not GSS_C_NO_CREDENTIAL) + will be returned; if deleg_flag is false, + gss_accept_context() will set this parameter to + GSS_C_NO_CREDENTIAL. If a credential handle is + returned, the associated resources must be released + by the application after use with a call to + gss_release_cred(). Specify NULL if not required. + + + minor_status Integer, modify + Mechanism specific status code. + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application + is required to complete the context, and that + gss_accept_sec_context must be called again with that + token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the + input_token failed. + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed + on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for context + acceptance, or the credential handle did not reference + any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. + + GSS_S_BAD_BINDINGS The input_token contains different channel bindings + to those specified via the input_chan_bindings + parameter. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did not + refer to a valid context. + + GSS_S_BAD_SIG The input_token contains an invalid MIC. + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error + during context establishment. + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a + token already processed. This is a fatal error during + context establishment. + + + + + + Wray Document Expiration: 1 September 1997 [Page 30] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_BAD_MECH The received token specified a mechanism that is not + supported by the implementation or the provided + credential. + + + + + + + + 7.2. gss_acquire_cred + + + OM_uint32 gss_acquire_cred ( + OM_uint32 * minor_status, + const gss_name_t desired_name, + OM_uint32 time_req, + const gss_OID_set desired_mechs, + gss_cred_usage_t cred_usage, + gss_cred_id_t * output_cred_handle, + gss_OID_set * actual_mechs, + OM_uint32 * time_rec) + + Purpose: + + Allows an application to acquire a handle for a pre-existing credential + by name. GSS-API implementations must impose a local access-control + policy on callers of this routine to prevent unauthorized callers from + acquiring credentials to which they are not entitled. This routine is + not intended to provide a ``login to the network'' function, as such a + function would involve the creation of new credentials rather than + merely acquiring a handle to existing credentials. Such functions, if + required, should be defined in implementation-specific extensions to the + API. + + If desired_name is GSS_C_NO_NAME, the call is interpreted as a request + for a credential handle that will invoke default behavior when passed to + gss_init_sec_context() (if cred_usage is GSS_C_INITIATE or GSS_C_BOTH) + or gss_accept_sec_context() (if cred_usage is GSS_C_ACCEPT or + GSS_C_BOTH). + + This routine is expected to be used primarily by context acceptors, + since implementations are likely to provide mechanism-specific ways of + obtaining GSS-API initiator credentials from the system login process. + Some implementations may therefore not support the acquisition of + GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred for any + name other than an empty name. + + If credential acquisition is time-consuming for a mechanism, the + mechanism may chooses to delay the actual acquisition until the + credential is required (e.g. by gss_init_sec_context or + + + + Wray Document Expiration: 1 September 1997 [Page 31] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_accept_sec_context). Such mechanism-specific implementation + decisions should be invisible to the calling application; thus a call of + gss_inquire_cred immediately following the call of gss_acquire_cred must + return valid credential data, and may therefore incur the overhead of a + deferred credential acquisition. + + Parameters: + + desired_name gss_name_t, read + Name of principal whose credential + should be acquired + + time_req Integer, read, optional + number of seconds that credentials + should remain valid. Specify GSS_C_INDEFINITE + to request that the credentials have the maximum + permitted lifetime. + + desired_mechs Set of Object IDs, read, optional + set of underlying security mechanisms that + may be used. GSS_C_NO_OID_SET may be used + to obtain an implementation-specific default. + + cred_usage gss_cred_usage_t, read + GSS_C_BOTH - Credentials may be used + either to initiate or accept + security contexts. + GSS_C_INITIATE - Credentials will only be + used to initiate security + contexts. + GSS_C_ACCEPT - Credentials will only be used to + accept security contexts. + + output_cred_handle gss_cred_id_t, modify + The returned credential handle. Resources + associated with this credential handle must + be released by the application after use + with a call to gss_release_cred(). + + actual_mechs Set of Object IDs, modify, optional + The set of mechanisms for which the + credential is valid. Storage associated + with the returned OID-set must be released by + the application after use with a call to + gss_release_oid_set(). Specify NULL if not + required. + + time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid. If the + implementation does not support expiration of + + + + Wray Document Expiration: 1 September 1997 [Page 32] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + credentials, the value GSS_C_INDEFINITE will + be returned. Specify NULL if not required + + minor_status Integer, modify + Mechanism specific status code. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Unavailable mechanism requested + + GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not + supported + + GSS_S_BAD_NAME Value supplied for desired_name parameter is ill- + formed. + + GSS_S_CREDENTIALS_EXPIRED The credentials could not be acquired because + they have expired. + + GSS_S_NO_CRED No credentials were found for the specified name. + + + + + + + + 7.3. gss_add_cred + + + OM_uint32 gss_add_cred ( + OM_uint32 * minor_status, + const gss_cred_id_t input_cred_handle, + const gss_name_t desired_name, + const gss_OID desired_mech, + gss_cred_usage_t cred_usage, + OM_uint32 initiator_time_req, + OM_uint32 acceptor_time_req, + gss_cred_id_t * output_cred_handle, + gss_OID_set * actual_mechs, + OM_uint32 * initiator_time_rec, + OM_uint32 * acceptor_time_rec) + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 33] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Purpose: + + Adds a credential-element to a credential. The credential-element is + identified by the name of the principal to which it refers. GSSAPI + implementations must impose a local access-control policy on callers of + this routine to prevent unauthorized callers from acquiring credential- + elements to which they are not entitled. This routine is not intended to + provide a ``login to the network'' function, as such a function would + involve the creation of new mechanism-specific authentication data, + rather than merely acquiring a GSSAPI handle to existing data. Such + functions, if required, should be defined in implementation-specific + extensions to the API. + + This routine is expected to be used primarily by context acceptors, + since implementations are likely to provide mechanism-specific ways of + obtaining GSS-API initiator credentials from the system login process. + Some implementations may therefore not support the acquisition of + GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred. + + If credential acquisition is time-consuming for a mechanism, the + mechanism may chooses to delay the actual acquisition until the + credential is required (e.g. by gss_init_sec_context or + gss_accept_sec_context). Such mechanism-specific implementation + decisions should be invisible to the calling application; thus a call of + gss_inquire_cred immediately following the call of gss_acquire_cred must + return valid credential data, and may therefore incur the overhead of a + deferred credential acquisition. + + This routine can be used to either create a new credential containing + all credential-elements of the original in addition to the newly-acquire + credential-element, or to add the new credential-element to an existing + credential. If NULL is specified for the output_cred_handle parameter + argument, the new credential-element will be added to the credential + identified by input_cred_handle; if a valid pointer is specified for the + output_cred_handle parameter, a new credential and handle will be + created. + + If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, the + gss_add_cred will create its output_cred_handle based on default + behavior. That is, the call will have the same effect as if the + application had first made a call to gss_acquire_cred(), specifying the + same usage and passing GSS_C_NO_NAME as the desired_name parameter to + obtain an explicit credential handle embodying default behavior, passed + this credential handle to gss_add_cred(), and finally called + gss_release_cred() on the first credential handle. + + If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle parameter, + a non-NULL output_cred_handle must be supplied. + + Parameters: + + + + + Wray Document Expiration: 1 September 1997 [Page 34] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + minor_status Integer, modify + Mechanism specific status code. + + input_cred_handle gss_cred_id_t, read, optional + The credential to which a credential-element + will be added. If GSS_C_NO_CREDENTIAL is + specified, the routine will create the new + credential based on default behavior (see + description above). Note that, while the + credential-handle is not modified by + gss_add_cred(), the underlying credential + will be modified if output_credential_handle + is NULL. + + desired_name gss_name_t, read. + Name of principal whose credential + should be acquired. + + desired_mech Object ID, read + Underlying security mechanism with which the + credential may be used. + + cred_usage gss_cred_usage_t, read + GSS_C_BOTH - Credential may be used + either to initiate or accept + security contexts. + GSS_C_INITIATE - Credential will only be + used to initiate security + contexts. + GSS_C_ACCEPT - Credential will only be used to + accept security contexts. + + initiator_time_req Integer, read, optional + number of seconds that the credential + should remain valid for initiating security + contexts. This argument is ignored if the + created credentials are of type GSS_C_ACCEPT. + Specify GSS_C_INDEFINITE to request that the + credentials have the maximum permitted initiator + lifetime. + + acceptor_time_req Integer, read, optional + number of seconds that the credential + should remain valid for accepting security + contexts. This argument is ignored if the + created credentials are of type GSS_C_INITIATE. + Specify GSS_C_INDEFINITE to request that the + credentials have the maximum permitted initiator + lifetime. + + + + + Wray Document Expiration: 1 September 1997 [Page 35] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + output_cred_handle gss_cred_id_t, modify, optional + The returned credential handle, containing + the new credential-element and all the + credential-elements from input_cred_handle. + If a valid pointer to a gss_cred_id_t is + supplied for this parameter, gss_add_cred + creates a new credential handle containing all + credential-elements from the input_cred_handle + and the newly acquired credential-element; if + NULL is specified for this parameter, the newly + acquired credential-element will be added + to the credential identified by input_cred_handle. + The resources associated with any credential + handle returned via this parameter must be + released by the application after use with a + call to gss_release_cred(). + + actual_mechs Set of Object IDs, modify, optional + The complete set of mechanisms for which + the new credential is valid. Storage for + the returned OID-set must be freed by the + application after use with a call to + gss_release_oid_set(). Specify NULL if + not required. + + initiator_time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid for + initiating contexts using the specified + mechanism. If the implementation or mechanism + does not support expiration of credentials, the + value GSS_C_INDEFINITE will be returned. Specify + NULL if not required + + acceptor_time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid for + accepting security contexts using the specified + mechanism. If the implementation or mechanism + does not support expiration of credentials, the + value GSS_C_INDEFINITE will be returned. Specify + NULL if not required + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Unavailable mechanism requested + + GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not + supported + + + + + Wray Document Expiration: 1 September 1997 [Page 36] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_BAD_NAME Value supplied for desired_name parameter is ill- + formed. + + GSS_S_DUPLICATE_ELEMENT The credential already contains an element for + the requested mechanism with overlapping usage and + validity period. + + GSS_S_CREDENTIALS_EXPIRED The required credentials could not be added + because they have expired. + + GSS_S_NO_CRED No credentials were found for the specified name. + + + + + + + + 7.4. gss_add_oid_set_member + + OM_uint32 gss_add_oid_set_member ( + OM_uint32 * minor_status, + const gss_OID member_oid, + gss_OID_set * oid_set) + + Purpose: + + Add an Object Identifier to an Object Identifier set. This routine is + intended for use in conjunction with gss_create_empty_oid_set when + constructing a set of mechanism OIDs for input to gss_acquire_cred. + + The oid_set parameter must refer to an OID-set that was created by + GSSAPI (e.g. a set returned by gss_create_empty_oid_set()). GSSAPI + creates a copy of the member_oid and inserts this copy into the set, + expanding the storage allocated to the OID-set's elements array if + necessary. The routine may add the new member OID anywhere within the + elements array, and implementations should verify that the new + member_oid is not already contained within the elements array. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + member_oid Object ID, read + The object identifier to copied into + the set. + + oid_set Set of Object ID, modify + The set in which the object identifier + should be inserted. + + + + Wray Document Expiration: 1 September 1997 [Page 37] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.5. gss_canonicalize_name + + OM_uint32 gss_canonicalize_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + const gss_OID mech_type, + gss_name_t * output_name) + + Purpose: + + Generate a canonical mechanism name (MN) from an arbitrary internal + name. The mechanism name is the name that would be returned to a + context acceptor on successful authentication of a context where the + initiator used the input_name in a successful call to gss_acquire_cred, + specifying an OID set containing as its only member, + followed by a call to gss_init_sec_context, specifying as + the authentication mechanism. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + input_name gss_name_t, read + The name for which a canonical form is + desired + + mech_type Object ID, read + The authentication mechanism for which the + canonical form of the name is desired. The + desired mechanism must be specified explicitly; + no default is provided. + + output_name gss_name_t, modify + The resultant canonical name. Storage + associated with this name must be freed by + the application after use with a call to + gss_release_name(). + + Function value: GSS status code + + + + + Wray Document Expiration: 1 September 1997 [Page 38] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_COMPLETE Successful completion. + + GSS_S_BAD_MECH The identified mechanism is not supported. + + GSS_S_BAD_NAMETYPE The provided internal name contains no elements that + could be processed by the sepcified mechanism. + + GSS_S_BAD_NAME The provided internal name was ill-formed. + + + + + + + + 7.6. gss_compare_name + + OM_uint32 gss_compare_name ( + OM_uint32 * minor_status, + const gss_name_t name1, + const gss_name_t name2, + int * name_equal) + + Purpose: + + Allows an application to compare two internal-form names to determine + whether they refer to the same entity. + + If either name presented to gss_compare_name denotes an anonymous + principal, the routines should indicate that the two names do not refer + to the same identity. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + name1 gss_name_t, read + internal-form name + + name2 gss_name_t, read + internal-form name + + name_equal boolean, modify + non-zero - names refer to same entity + zero - names refer to different entities + (strictly, the names are not known + to refer to the same identity). + + Function value: GSS status code + + + + + Wray Document Expiration: 1 September 1997 [Page 39] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The two names were of incomparable types. + + GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed + + + + + + + + 7.7. gss_context_time + + OM_uint32 gss_context_time ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + OM_uint32 * time_rec) + + Purpose: + + Determines the number of seconds for which the specified context will + remain valid. + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context to be interrogated. + + time_rec Integer, modify + Number of seconds that the context will remain + valid. If the context has already expired, + zero will be returned. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 40] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.8. gss_create_empty_oid_set + + OM_uint32 gss_create_empty_oid_set ( + OM_uint32 * minor_status, + gss_OID_set * oid_set) + + Purpose: + + Create an object-identifier set containing no object identifiers, to + which members may be subsequently added using the + gss_add_oid_set_member() routine. These routines are intended to be + used to construct sets of mechanism object identifiers, for input to + gss_acquire_cred. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + oid_set Set of Object IDs, modify + The empty object identifier set. + The routine will allocate the + gss_OID_set_desc object, which the + application must free after use with + a call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.9. gss_delete_sec_context + + OM_uint32 gss_delete_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_buffer_t output_token) + + Purpose: + + Delete a security context. gss_delete_sec_context will delete the local + data structures associated with the specified security context, and may + generate an output_token, which when passed to the peer + gss_process_context_token will instruct it to do likewise. If no token + is required by the mechanism, the GSS-API should set the length field of + the output_token (if provided) to zero. No further security services + + + + Wray Document Expiration: 1 September 1997 [Page 41] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + may be obtained using the context specified by context_handle. + + In addition to deleting established security contexts, + gss_delete_sec_context must also be able to delete "half-built" security + contexts resulting from an incomplete sequence of + gss_init_sec_context()/gss_accept_sec_context() calls. + + The output_token parameter is retained for compatibility with version 1 + of the GSS-API. It is recommended that both peer applications invoke + gss_delete_sec_context passing the value GSS_C_NO_BUFFER for the + output_token parameter, indicating that no token is required, and that + gss_delete_sec_context should simply delete local context data + structures. If the application does pass a valid buffer to + gss_delete_sec_context, mechanisms are encouraged to return a zero- + length token, indicating that no peer action is necessary, and that no + token should be transferred by the application. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, modify + context handle identifying context to delete. + After deleting the context, the GSSAPI will set + this context handle to GSS_C_NO_CONTEXT. + + output_token buffer, opaque, modify, optional + token to be sent to remote application to + instruct it to also delete the context. It + is recommended that applications specify + GSS_C_NO_BUFFER for this parameter, requesting + local deletion only. If a buffer parameter is + provided by the application, the mechanism may + return a token in it; mechanisms that implement + only local deletion should set the length field of + this token to zero to indicate to the application + that no token is to be sent to the peer. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CONTEXT No valid context was supplied + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 42] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.10. gss_display_name + + OM_uint32 gss_display_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + gss_buffer_t output_name_buffer, + gss_OID * output_name_type) + + Purpose: + + Allows an application to obtain a textual representation of an opaque + internal-form name for display purposes. The syntax of a printable + name is defined by the GSS-API implementation. + + If input_name denotes an anonymous principal, the implementation should + return the gss_OID value GSS_C_NT_ANONYMOUS as the output_name_type, and + a textual name that is syntactically distinct from all valid supported + printable names in output_name_buffer. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + input_name gss_name_t, read + name to be displayed + + output_name_buffer buffer, character-string, modify + buffer to receive textual name string. + The application must free storage associated + with this name after use with a call to + gss_release_buffer(). + + output_name_type Object ID, modify, optional + The type of the returned name. The returned + gss_OID will be a pointer into static storage, + and should be treated as read-only by the caller + (in particular, it does not need to be freed). + Specify NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME input_name was ill-formed + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 43] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.11. gss_display_status + + OM_uint32 gss_display_status ( + OM_uint32 * minor_status, + OM_uint32 status_value, + int status_type, + const gss_OID mech_type, + OM_uint32 * message_context, + gss_buffer_t status_string) + + Purpose: + + Allows an application to obtain a textual representation of a GSS-API + status code, for display to the user or for logging purposes. Since + some status values may indicate multiple conditions, applications may + need to call gss_display_status multiple times, each call generating a + single text string. The message_context parameter is used by + gss_acquire_cred to store state information about which error messages + have already been extracted from a given status_value; message_context + must be initialized to 0 by the application prior to the first call, and + gss_display_status will return a non-zero value in this parameter if + there are further messages to extract. The message_context parameter + contains all state information required by gss_display_status in order + to extract further messages from the status_value; even when a non-zero + value is returned in this parameter, the application is not required to + call gss_display_status again unless subsequent messages are desired. + The following code extracts all messages from a given status code and + prints them to stderr: + + + OM_uint32 message_context; + OM_uint32 status_code; + OM_uint32 maj_status; + OM_uint32 min_status; + gss_buffer_desc status_string; + + ... + + message_context = 0; + + do { + + maj_status = gss_display_status (&min_status, + status_code, + GSS_C_GSS_CODE, + GSS_C_NO_OID, + &message_context, + &status_string) + + fprintf(stderr, + "%.*s\n", + + + + Wray Document Expiration: 1 September 1997 [Page 44] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + status_string.length, + status_string.value); + + gss_release_buffer(&min_status, + &status_string); + + } while (message_context != 0); + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + status_value Integer, read + Status value to be converted + + status_type Integer, read + GSS_C_GSS_CODE - status_value is a GSS status + code + GSS_C_MECH_CODE - status_value is a mechanism + status code + + mech_type Object ID, read, optional + Underlying mechanism (used to interpret a + minor status value) Supply GSS_C_NO_OID to + obtain the system default. + + message_context Integer, read/modify + Should be initialized to zero by the + application prior to the first call. + On return from gss_display_status(), + a non-zero status_value parameter indicates + that additional messages may be extracted + from the status code via subsequent calls + to gss_display_status(), passing the same + status_value, status_type, mech_type, and + message_context parameters. + + status_string buffer, character string, modify + textual interpretation of the status_value. + Storage associated with this parameter must + be freed by the application after use with + a call to gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + Wray Document Expiration: 1 September 1997 [Page 45] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_BAD_MECH Indicates that translation in accordance with an + unsupported mechanism type was requested + + GSS_S_BAD_STATUS The status value was not recognized, or the status + type was neither GSS_C_GSS_CODE nor GSS_C_MECH_CODE. + + + + + + + + 7.12. gss_duplicate_name + + OM_uint32 gss_duplicate_name ( + OM_uint32 * minor_status, + const gss_name_t src_name, + gss_name_t * dest_name) + + Purpose: + + Create an exact duplicate of the existing internal name src_name. The + new dest_name will be independent of src_name (i.e. src_name and + dest_name must both be released, and the release of one shall not affect + the validity of the other). + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + src_name gss_name_t, read + internal name to be duplicated. + + dest_name gss_name_t, modify + The resultant copy of . + Storage associated with this name must + be freed by the application after use + with a call to gss_release_name(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The src_name parameter was ill-formed. + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 46] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.13. gss_export_name + + OM_uint32 gss_export_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + gss_buffer_t exported_name) + + Purpose: + + To produce a canonical contiguous string representation of a mechanism + name (MN), suitable for direct comparison (e.g. with memcmp) for use in + authorization functions (e.g. matching entries in an access-control + list). + + The parameter must specify a valid MN (i.e. an internal + name generated by gss_accept_sec_context or by gss_canonicalize_name). + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + input_name gss_name_t, read + The MN to be exported + + exported_name gss_buffer_t, octet-string, modify + The canonical contiguous string form of + . Storage associated with + this string must freed by the application + after use with gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NAME_NOT_MN The provided internal name was not a mechanism name. + + GSS_S_BAD_NAME The provide internal name was ill-formed. + + GSS_S_BAD_NAMETYPE The internal name was of a type not supported by the + GSSAPI implementation. + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 47] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.14. gss_export_sec_context + + OM_uint32 gss_export_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_buffer_t interprocess_token) + + Purpose: + + Provided to support the sharing of work between multiple processes. + This routine will typically be used by the context-acceptor, in an + application where a single process receives incoming connection requests + and accepts security contexts over them, then passes the established + context to one or more other processes for message exchange. + gss_export_sec_context() deactivates the security context for the + calling process and creates an interprocess token which, when passed to + gss_import_sec_context in another process, will re-activate the context + in the second process. Only a single instantiation of a given context + may be active at any one time; a subsequent attempt by a context + exporter to access the exported security context will fail. + + The implementation may constrain the set of processes by which the + interprocess token may be imported, either as a function of local + security policy, or as a result of implementation decisions. For + example, some implementations may constrain contexts to be passed only + between processes that run under the same account, or which are part of + the same process group. + + The interprocess token may contain security-sensitive information (for + example cryptographic keys). While mechanisms are encouraged to either + avoid placing such sensitive information within interprocess tokens, or + to encrypt the token before returning it to the application, in a + typical object-library GSSAPI implementation this may not be possible. + Thus the application must take care to protect the interprocess token, + and ensure that any process to which the token is transferred is + trustworthy. + + If creation of the interprocess token is succesful, the implementation + shall deallocate all process-wide resources associated with the security + context, and set the context_handle to GSS_C_NO_CONTEXT. In the event + of an error that makes it impossible to complete the export of the + security context, the implementation must not return an interprocess + token, and should strive to leave the security context referenced by the + context_handle parameter untouched. If this is impossible, it is + permissible for the implementation to delete the security context, + providing it also sets the context_handle parameter to GSS_C_NO_CONTEXT. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + + + Wray Document Expiration: 1 September 1997 [Page 48] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + context_handle gss_ctx_id_t, modify + context handle identifying the context to transfer. + + interprocess_token buffer, opaque, modify + token to be transferred to target process. + Storage associated with this token must be + freed by the application after use with a + call to gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has expired + + GSS_S_NO_CONTEXT The context was invalid + + GSS_S_UNAVAILABLE The operation is not supported. + + + + + + + + 7.15. gss_get_mic + + OM_uint32 gss_get_mic ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + gss_qop_t qop_req, + const gss_buffer_t message_buffer, + gss_buffer_t msg_token) + + Purpose: + + Generates a cryptographic MIC for the supplied message, and places the + MIC in a token for transfer to the peer application. The qop_req + parameter allows a choice between several cryptographic algorithms, if + supported by the chosen mechanism. + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + will be sent + + + + + Wray Document Expiration: 1 September 1997 [Page 49] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + qop_req gss_qop_t, read, optional + Specifies requested quality of protection. + Callers are encouraged, on portability grounds, + to accept the default quality of protection + offered by the chosen mechanism, which may be + requested by specifying GSS_C_QOP_DEFAULT for + this parameter. If an unsupported protection + strength is requested, gss_get_mic will return a + major_status of GSS_S_BAD_QOP. + + message_buffer buffer, opaque, read + message to be protected + + msg_token buffer, opaque, modify + buffer to receive token. The application must + free storage associated with this buffer after + use with a call to gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. + + + + + + + + 7.16. gss_import_name + + OM_uint32 gss_import_name ( + OM_uint32 * minor_status, + const gss_buffer_t input_name_buffer, + const gss_OID input_name_type, + gss_name_t * output_name) + + Purpose: + + Convert a contiguous string name to internal form. In general, the + internal name returned (via the parameter) will not be an + MN; the exception to this is if the indicates that the + contiguous string provided via the parameter is of + type GSS_C_NT_EXPORT_NAME, in which case the returned internal name will + be an MN for the mechanism that exported the name. + + + + + Wray Document Expiration: 1 September 1997 [Page 50] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + input_name_buffer buffer, octet-string, read + buffer containing contiguous string name to convert + + input_name_type Object ID, read, optional + Object ID specifying type of printable + name. Applications may specify either + GSS_C_NO_OID to use a mechanism-specific + default printable syntax, or an OID registered + by the GSS-API implementation to name a + specific namespace. + + output_name gss_name_t, modify + returned name in internal form. Storage + associated with this name must be freed + by the application after use with a call + to gss_release_name(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The input_name_type was unrecognized + + GSS_S_BAD_NAME The input_name parameter could not be interpreted as a + name of the specified type + + + + + + + + + 7.17. gss_import_sec_context + + OM_uint32 gss_import_sec_context ( + OM_uint32 * minor_status, + const gss_buffer_t interprocess_token, + gss_ctx_id_t * context_handle) + + Purpose: + + Allows a process to import a security context established by another + process. A given interprocess token may be imported only once. See + gss_export_sec_context. + + + + + Wray Document Expiration: 1 September 1997 [Page 51] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + interprocess_token buffer, opaque, modify + token received from exporting process + + context_handle gss_ctx_id_t, modify + context handle of newly reactivated context. + Resources associated with this context handle + must be released by the application after use + with a call to gss_delete_sec_context(). + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion. + + GSS_S_NO_CONTEXT The token did not contain a valid context reference. + + GSS_S_DEFECTIVE_TOKEN The token was invalid. + + GSS_S_UNAVAILABLE The operation is unavailable. + + GSS_S_UNAUTHORIZED Local policy prevents the import of this context by + the current process.. + + + + + + + + 7.18. gss_indicate_mechs + + OM_uint32 gss_indicate_mechs ( + OM_uint32 * minor_status, + gss_OID_set * mech_set) + + Purpose: + + Allows an application to determine which underlying security mechanisms + are available. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + + + + Wray Document Expiration: 1 September 1997 [Page 52] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + mech_set set of Object IDs, modify + set of implementation-supported mechanisms. + The returned gss_OID_set value will be a + dynamically-allocated OID set, that should + be released by the caller after use with a + call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.19. gss_init_sec_context + + OM_uint32 gss_init_sec_context ( + OM_uint32 * minor_status, + const gss_cred_id_t initiator_cred_handle, + gss_ctx_id_t * context_handle, + const gss_name_t target_name, + const gss_OID mech_type, + OM_uint32 req_flags, + OM_uint32 time_req, + const gss_channel_bindings_t + input_chan_bindings, + const gss_buffer_t input_token + gss_OID * actual_mech_type, + gss_buffer_t output_token, + OM_uint32 * ret_flags, + OM_uint32 * time_rec ) + + Purpose: + + Initiates the establishment of a security context between the + application and a remote peer. Initially, the input_token parameter + should be specified either as GSS_C_NO_BUFFER, or as a pointer to a + gss_buffer_desc object whose length field contains the value zero. The + routine may return a output_token which should be transferred to the + peer application, where the peer application will present it to + gss_accept_sec_context. If no token need be sent, gss_init_sec_context + will indicate this by setting the length field of the output_token + argument to zero. To complete the context establishment, one or more + reply tokens may be required from the peer application; if so, + gss_init_sec_context will return a status containing the supplementary + information bit GSS_S_CONTINUE_NEEDED. In this case, + gss_init_sec_context should be called again when the reply token is + received from the peer application, passing the reply token to + gss_init_sec_context via the input_token parameters. + + + + Wray Document Expiration: 1 September 1997 [Page 53] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Portable applications should be constructed to use the token length and + return status to determine whether a token needs to be sent or waited + for. Thus a typical portable caller should always invoke + gss_init_sec_context within a loop: + + int context_established = 0; + gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; + ... + input_token->length = 0; + + while (!context_established) { + maj_stat = gss_init_sec_context(&min_stat, + cred_hdl, + &context_hdl, + target_name, + desired_mech, + desired_services, + desired_time, + input_bindings, + input_token, + &actual_mech, + output_token, + &actual_services, + &actual_time); + if (GSS_ERROR(maj_stat)) { + report_error(maj_stat, min_stat); + }; + if (output_token->length != 0) { + send_token_to_peer(output_token); + gss_release_buffer(&min_stat, + output_token) + }; + if (GSS_ERROR(maj_stat)) { + if (context_hdl != GSS_C_NO_CONTEXT) + gss_delete_sec_context(&min_stat, + &context_hdl, + GSS_C_NO_BUFFER); + break; + }; + if (maj_stat & GSS_S_CONTINUE_NEEDED) { + receive_token_from_peer(input_token); + } else { + context_established = 1; + }; + }; + + Whenever the routine returns a major status that includes the value + GSS_S_CONTINUE_NEEDED, the context is not fully established and the + following restrictions apply to the output parameters: + + + + + + Wray Document Expiration: 1 September 1997 [Page 54] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + (a) The value returned via the time_rec parameter is undefined + + (b) Unless the accompanying ret_flags parameter contains the bit + GSS_C_PROT_READY_FLAG, indicating that per-message services may be + applied in advance of a successful completion status, the value + returned via the actual_mech_type parameter is undefined until the + routine returns a major status value of GSS_S_COMPLETE. + + (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, + GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, + GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the + ret_flags parameter should contain the values that the + implementation expects would be valid if context establishment + were to succeed. In particular, if the application has requested + a service such as delegation or anonymous authentication via the + req_flags argument, and such a service is unavailable from the + underlying mechanism, gss_init_sec_context should generate a token + that will not provide the service, and indicate via the ret_flags + argument that the service will not be supported. The application + may choose to abort the context establishment by calling + gss_delete_sec_context (if it cannot continue in the absence of + the service), or it may choose to transmit the token and continue + context establishment (if the service was merely desired but not + mandatory). + + The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits + within ret_flags should indicate the actual state at the time + gss_init_sec_context returns, whether or not the context is fully + established. + + Although this requires that GSSAPI implementations set the + GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller + (i.e. when accompanied by a GSS_S_COMPLETE status code), + applications should not rely on this behavior as the flag was not + defined in Version 1 of the GSSAPI. Instead, applications should + be prepared to use per-message services after a successful context + establishment, according to the GSS_C_INTEG_FLAG and + GSS_C_CONF_FLAG values. + + All other bits within the ret_flags argument should be set to + zero. + + If the initial call of gss_init_sec_context() fails, the implementation + should not create a context object, and should leave the value of the + context_handle parameter set to GSS_C_NO_CONTEXT to indicate this. In + the event of a failure on a subsequent call, the implementation is + permitted to delete the "half-built" security context (in which case it + should set the context_handle parameter to GSS_C_NO_CONTEXT), but the + preferred behavior is to leave the security context untouched for the + application to delete (using gss_delete_sec_context). + + + + + Wray Document Expiration: 1 September 1997 [Page 55] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + initiator_cred_handle gss_cred_id_t, read, optional + handle for credentials claimed. Supply + GSS_C_NO_CREDENTIAL to act as a default + initiator principal. If no default + initiator is defined, the function will + return GSS_S_NO_CRED. + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned by first call in continuation calls. + Resources associated with this context-handle + must be released by the application after use + with a call to gee_delete_sec_context(). + + target_name gss_name_t, read + Name of target + + mech_type OID, read, optional + Object ID of desired mechanism. Supply + GSS_C_NO_OID to obtain an implementation + specific default + + req_flags bit-mask, read + Contains various independent flags, each of + which requests that the context support a + specific service option. Symbolic + names are provided for each flag, and the + symbolic names corresponding to the required + flags should be logically-ORed + together to form the bit-mask value. The + flags are: + + GSS_C_DELEG_FLAG + True - Delegate credentials to remote peer + False - Don't delegate + GSS_C_MUTUAL_FLAG + True - Request that remote peer + authenticate itself + False - Authenticate self to remote peer + only + GSS_C_REPLAY_FLAG + True - Enable replay detection for + messages protected with gss_wrap + or gss_get_mic + False - Don't attempt to detect + replayed messages + + + Wray Document Expiration: 1 September 1997 [Page 56] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_C_SEQUENCE_FLAG + True - Enable detection of out-of-sequence + protected messages + False - Don't attempt to detect + out-of-sequence messages + GSS_C_ANON_FLAG + True - Do not reveal the initiator's + identity to the acceptor. + False - Authenticate normally. + + time_req Integer, read, optional + Desired number of seconds for which context + should remain valid. Supply 0 to request a + default validity period. + + input_chan_bindings channel bindings, read, optional + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. Specify GSS_C_NO_CHANNEL_BINDINGS + if channel bindings are not used. + + input_token buffer, opaque, read, optional (see text) + Token received from peer application. + Supply GSS_C_NO_BUFFER, or a pointer to + a buffer containing the value GSS_C_EMPTY_BUFFER + on initial call. + + actual_mech_type OID, modify, optional + Actual mechanism used. The OID returned via + this parameter will be a pointer to static + storage that should be treated as read-only; + In particular the application should not attempt + to free it. Specify NULL if not required. + + output_token buffer, opaque, modify + token to be sent to peer application. If + the length field of the returned buffer is + zero, no token need be sent to the peer + application. Storage associated with this + buffer must be freed by the application + after use with a call to gss_release_buffer(). + + ret_flags bit-mask, modify, optional + Contains various independent flags, each of which + indicates that the context supports a specific + service option. Specify NULL if not + required. Symbolic names are provided + for each flag, and the symbolic names + corresponding to the required flags should be + + + + Wray Document Expiration: 1 September 1997 [Page 57] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + logically-ANDed with the ret_flags value to test + whether a given option is supported by the + context. The flags are: + + GSS_C_DELEG_FLAG + True - Credentials were delegated to + the remote peer + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer has been asked to + authenticated itself + False - Remote peer has not been asked to + authenticate itself + GSS_C_REPLAY_FLAG + True - replay of protected messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence protected + messages will be detected + False - out-of-sequence messages will + not be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be + invoked by calling gss_wrap routine + False - No confidentiality service (via + gss_wrap) available. gss_wrap will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_get_mic or gss_wrap + routines. + False - Per-message integrity service + unavailable. + GSS_C_ANON_FLAG + True - The initiator's identity has not been + revealed, and will not be revealed if + any emitted token is passed to the + acceptor. + False - The initiator's identity has been or + will be authenticated normally. + GSS_C_PROT_READY_FLAG + True - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available for + use if the accompanying major status + return value is either GSS_S_COMPLETE or + GSS_S_CONTINUE_NEEDED. + + + + Wray Document Expiration: 1 September 1997 [Page 58] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + False - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + only if the accompanying major status + return value is GSS_S_COMPLETE. + GSS_C_TRANS_FLAG + True - The resultant security context may + be transferred to other processes via + a call to gss_export_sec_context(). + False - The security context is not + transferrable. + All other bits should be set to zero. + + time_rec Integer, modify, optional + number of seconds for which the context + will remain valid. If the implementation does + not support context expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application + is required to complete the context, and that + gss_init_sec_context must be called again with that + token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the + input_token failed + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed + on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for context + initiation, or the credential handle did not reference + any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired + + GSS_S_BAD_BINDINGS The input_token contains different channel bindings + to those specified via the input_chan_bindings + parameter + + GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC that + could not be verified + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error + during context establishment + + + + + Wray Document Expiration: 1 September 1997 [Page 59] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a + token already processed. This is a fatal error during + context establishment. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did not + refer to a valid context + + GSS_S_BAD_NAMETYPE The provided target_name parameter contained an + invalid or unsupported type of name + + GSS_S_BAD_NAME The provided target_name parameter was ill-formed. + + GSS_S_BAD_MECH The specified mechanism is not supported by the + provided credential, or is unrecognized by the + implementation. + + + + + + + + 7.20. gss_inquire_context + + OM_uint32 gss_inquire_context ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + gss_name_t * src_name, + gss_name_t * targ_name, + OM_uint32 * lifetime_rec, + gss_OID * mech_type, + OM_uint32 * ctx_flags, + int * locally_initiated, + int * open ) + + Purpose: + + Obtains information about a security context. The caller must already + have obtained a handle that refers to the context, although the context + need not be fully established. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + context_handle gss_ctx_id_t, read + A handle that refers to the security context. + + src_name gss_name_t, modify, optional + The name of the context initiator. + + + + Wray Document Expiration: 1 September 1997 [Page 60] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + If the context was established using anonymous + authentication, and if the application invoking + gss_inquire_context is the context acceptor, + an anonymous name will be returned. Storage + associated with this name must be freed by the + application after use with a call to + gss_release_name(). Specify NULL if not + required. + + targ_name gss_name_t, modify, optional + The name of the context acceptor. + Storage associated with this name must be + freed by the application after use with a call + to gss_release_name(). Specify NULL if not + Specify NULL if not required. + + lifetime_rec Integer, modify, optional + The number of seconds for which the context + will remain valid. If the context has + expired, this parameter will be set to zero. + If the implementation does not support + context expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + mech_type gss_OID, modify, optional + The security mechanism providing the + context. The returned OID will be a + pointer to static storage that should + be treated as read-only by the application; + in particular the application should not + attempt to free it. Specify NULL if not + required. + + ctx_flags bit-mask, modify, optional + Contains various independent flags, each of + which indicates that the context supports + (or is expected to support, if ctx_open is + false) a specific service option. If not + needed, specify NULL. Symbolic names are + provided for each flag, and the symbolic names + corresponding to the required flags + should be logically-ANDed with the ret_flags + value to test whether a given option is + supported by the context. The flags are: + + GSS_C_DELEG_FLAG + True - Credentials were delegated from + the initiator to the acceptor. + False - No credentials were delegated + + + + Wray Document Expiration: 1 September 1997 [Page 61] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + GSS_C_MUTUAL_FLAG + True - The acceptor was authenticated + to the initiator + False - The acceptor did not authenticate + itself. + GSS_C_REPLAY_FLAG + True - replay of protected messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence protected + messages will be detected + False - out-of-sequence messages will not + be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be invoked + by calling gss_wrap routine + False - No confidentiality service (via + gss_wrap) available. gss_wrap will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_get_mic or gss_wrap + routines. + False - Per-message integrity service + unavailable. + GSS_C_ANON_FLAG + True - The initiator's identity will not + be revealed to the acceptor. + The src_name parameter (if + requested) contains an anonymous + internal name. + False - The initiator has been + authenticated normally. + GSS_C_PROT_READY_FLAG + True - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + for use. + False - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + only if the context is fully + established (i.e. if the open parameter + is non-zero). + GSS_C_TRANS_FLAG + True - The resultant security context may + be transferred to other processes via + a call to gss_export_sec_context(). + False - The security context is not + transferrable. + + Wray Document Expiration: 1 September 1997 [Page 62] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + + + locally_initiated Boolean, modify + Non-zero if the invoking application is the + context initiator. + Specify NULL if not required. + + open Boolean, modify + Non-zero if the context is fully established; + Zero if a context-establishment token + is expected from the peer application. + Specify NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CONTEXT The referenced context could not be accessed. + + GSS_S_CONTEXT_EXPIRED The context has expired. If the lifetime_rec + parameter was requested, it will be set to 0. + + + + + + + + 7.21. gss_inquire_cred + + OM_uint32 gss_inquire_cred ( + OM_uint32 * minor_status, + const gss_cred_id_t cred_handle, + gss_name_t * name, + OM_uint32 * lifetime, + gss_cred_usage_t * cred_usage, + gss_OID_set * mechanisms ) + + Purpose: + + Obtains information about a credential. The caller must already have + obtained a handle that refers to the credential. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + cred_handle gss_cred_id_t, read + A handle that refers to the target credential. + Specify GSS_C_NO_CREDENTIAL to inquire about + the default initiator principal. + + + Wray Document Expiration: 1 September 1997 [Page 63] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + + name gss_name_t, modify, optional + The name whose identity the credential asserts. + Storage associated with this name should be freed + by the application after use with a call to + gss_release_name(). Specify NULL if not required. + + lifetime Integer, modify, optional + The number of seconds for which the credential + will remain valid. If the credential has + expired, this parameter will be set to zero. + If the implementation does not support + credential expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + cred_usage gss_cred_usage_t, modify, optional + How the credential may be used. One of the + following: + GSS_C_INITIATE + GSS_C_ACCEPT + GSS_C_BOTH + Specify NULL if not required. + + mechanisms gss_OID_set, modify, optional + Set of mechanisms supported by the credential. + Storage associated with this OID set must be + freed by the application after use with a call + to gss_release_oid_set(). Specify NULL if not + required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED The referenced credentials could not be accessed. + + GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. If + the lifetime parameter was not passed as NULL, it will + be set to 0. + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 64] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.22. gss_inquire_cred_by_mech + + OM_uint32 gss_inquire_cred_by_mech ( + OM_uint32 * minor_status, + const gss_cred_id_t cred_handle, + const gss_OID mech_type, + gss_name_t * name, + OM_uint32 * initiator_lifetime, + OM_uint32 * acceptor_lifetime, + gss_cred_usage_t * cred_usage ) + + Purpose: + + Obtains per-mechanism information about a credential. The caller must + already have obtained a handle that refers to the credential. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + cred_handle gss_cred_id_t, read + A handle that refers to the target credential. + Specify GSS_C_NO_CREDENTIAL to inquire about + the default initiator principal. + + mech_type gss_OID, read + The mechanism for which information should be + returned. + + name gss_name_t, modify, optional + The name whose identity the credential asserts. + Storage associated with this name must be + freed by the application after use with a call + to gss_release_name(). Specify NULL if not + required. + + initiator_lifetime Integer, modify, optional + The number of seconds for which the credential + will remain capable of initiating security contexts + under the specified mechanism. If the credential + can no longer be used to initiate contexts, or if + the credential usage for this mechanism is + GSS_C_ACCEPT, + this parameter will be set to zero. If the + implementation does not support expiration of + initiator credentials, the value GSS_C_INDEFINITE + will be returned. Specify NULL if not required. + + acceptor_lifetime Integer, modify, optional + The number of seconds for which the credential + + + + Wray Document Expiration: 1 September 1997 [Page 65] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + will remain capable of accepting security contexts + under the specified mechanism. If the credential + can no longer be used to accept contexts, or if + the credential usage for this mechanism is + GSS_C_INITIATE, this parameter will be set to zero. + If the implementation does not support expiration + of acceptor credentials, the value GSS_C_INDEFINITE + will be returned. Specify NULL if not required. + + cred_usage gss_cred_usage_t, modify, optional + How the credential may be used with the specified + mechanism. One of the following: + GSS_C_INITIATE + GSS_C_ACCEPT + GSS_C_BOTH + Specify NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED The referenced credentials could not be accessed. + + GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. If + the lifetime parameter was not passed as NULL, it will + be set to 0. + + + + + + + + 7.23. gss_inquire_mechs_for_name + + OM_uint32 gss_inquire_mechs_for_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + gss_OID_set * mech_types ) + + Purpose: + + Returns the set of mechanisms supported by the GSSAPI implementation + that may be able to process the specified name. + + Each mechanism returned will recognize at least one element within the + name. It is permissible for this routine to be implemented within a + mechanism-independent GSSAPI layer, using the type information contained + within the presented name, and based on registration information + + + + Wray Document Expiration: 1 September 1997 [Page 66] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + provided by individual mechanism implementations. This means that the + returned mech_types set may indicate that a particular mechanism will + understand the name when in fact it would refuse to accept the name as + input to gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred + or gss_add_cred (due to some property of the specific name, as opposed + to the name type). Thus this routine should be used only as a pre- + filter for a call to a subsequent mechanism-specific routine. + + + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + input_name gss_name_t, read + The name to which the inquiry relates. + + mech_types gss_OID_set, modify + Set of mechanisms that may support the + specified name. The returned OID set + must be freed by the caller after use + with a call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The input_name parameter was ill-formed. + + GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or + unsupported type of name + + + + + + + 7.24. gss_inquire_names_for_mech + + OM_uint32 gss_inquire_names_for_mech ( + OM_uint32 * minor_status, + const gss_OID mechanism, + gss_OID_set * name_types) + + Purpose: + + Returns the set of nametypes supported by the specified mechanism. + + + + + + + Wray Document Expiration: 1 September 1997 [Page 67] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + mechanism gss_OID, read + The mechanism to be interrogated. + + name_types gss_OID_set, modify + Set of name-types supported by the specified + mechanism. The returned OID set must be + freed by the application after use with a + call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.25. gss_process_context_token + + OM_uint32 gss_process_context_token ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + const gss_buffer_t token_buffer) + + Purpose: + + Provides a way to pass a token to the security service. Used with + tokens emitted by gss_delete_sec_context. Note that mechanisms are + encouraged to perform local deletion, and not emit tokens from + gss_delete_sec_context. This routine, therefore, is primarily for + backwards compatibility with V1 applications. + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + context handle of context on which token is to + be processed + + token_buffer buffer, opaque, read + token to process + + + + + Wray Document Expiration: 1 September 1997 [Page 68] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the + token failed + + GSS_S_NO_CONTEXT The context_handle did not refer to a valid context + + + + + + + + 7.26. gss_release_buffer + + OM_uint32 gss_release_buffer ( + OM_uint32 * minor_status, + gss_buffer_t buffer) + + Purpose: + + Free storage associated with a buffer. The storage must have been + allocated by a GSS-API routine. In addition to freeing the associated + storage, the routine will zero the length field in the descriptor to + which the buffer parameter refers. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + buffer buffer, modify + The storage associated with the buffer will be + deleted. The gss_buffer_desc object will not + be freed, but its length field will be zeroed. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 69] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.27. gss_release_cred + + OM_uint32 gss_release_cred ( + OM_uint32 * minor_status, + gss_cred_id_t * cred_handle) + + Purpose: + + Informs GSS-API that the specified credential handle is no longer + required by the application, and frees associated resources. + + Parameters: + + cred_handle gss_cred_id_t, modify, optional + Opaque handle identifying credential + to be released. If GSS_C_NO_CREDENTIAL + is supplied, the routine will complete + successfully, but will do nothing. + + minor_status Integer, modify + Mechanism specific status code. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED Credentials could not be accessed. + + + + + + + + 7.28. gss_release_name + + OM_uint32 gss_release_name ( + OM_uint32 * minor_status, + gss_name_t * name) + + Purpose: + + Free GSSAPI-allocated storage by associated with an internal-form name. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + name gss_name_t, modify + The name to be deleted + + + + Wray Document Expiration: 1 September 1997 [Page 70] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The name parameter did not contain a valid name + + + + + + + + 7.29. gss_release_oid_set + + OM_uint32 gss_release_oid_set ( + OM_uint32 * minor_status, + gss_OID_set * set) + + Purpose: + + Free storage associated with a GSSAPI-generated gss_OID_set object. The + set parameter must refer to an OID-set that was returned from a GSSAPI + routine. gss_release_oid_set() will free the storage associated with + each individual member OID, the OID set's elements array, and the + gss_OID_set_desc. + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + set Set of Object IDs, modify + The storage associated with the gss_OID_set + will be deleted. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 71] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.30. gss_test_oid_set_member + + OM_uint32 gss_test_oid_set_member ( + OM_uint32 * minor_status, + const gss_OID member, + const gss_OID_set set, + int * present) + + Purpose: + + Interrogate an Object Identifier set to determine whether a specified + Object Identifier is a member. This routine is intended to be used with + OID sets returned by gss_indicate_mechs(), gss_acquire_cred(), and + gss_inquire_cred(), but will also work with user-generated sets. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + member Object ID, read + The object identifier whose presence + is to be tested. + + set Set of Object ID, read + The Object Identifier set. + + present Boolean, modify + non-zero if the specified OID is a member + of the set, zero if not. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.31. gss_unwrap + + OM_uint32 gss_unwrap ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + const gss_buffer_t input_message_buffer, + gss_buffer_t output_message_buffer, + int * conf_state, + gss_qop_t * qop_state) + + + + + Wray Document Expiration: 1 September 1997 [Page 72] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Purpose: + + Converts a message previously protected by gss_wrap back to a usable + form, verifying the embedded MIC. The conf_state parameter indicates + whether the message was encrypted; the qop_state parameter indicates the + strength of protection that was used to provide the confidentiality and + integrity services. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context on which the message + arrived + + input_message_buffer buffer, opaque, read + protected message + + output_message_buffer buffer, opaque, modify + Buffer to receive unwrapped message. + Storage associated with this buffer must + be freed by the application after use use + with a call to gss_release_buffer(). + + conf_state boolean, modify, optional + Non-zero - Confidentiality and integrity protection + were used + Zero - Integrity service only was used + Specify NULL if not required + + qop_state gss_qop_t, modify, optional + Quality of protection gained from MIC. + Specify NULL if not required + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The MIC was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct MIC + for the message, but it had already been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC for + the message, but it is too old to check for + duplication. + + + + + Wray Document Expiration: 1 September 1997 [Page 73] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; a + later token has already been received. + + GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; + an earlier expected token has not yet been received. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + + + + + + + 7.32. gss_verify_mic + + OM_uint32 gss_verify_mic ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + const gss_buffer_t message_buffer, + const gss_buffer_t token_buffer, + gss_qop_t * qop_state) + + Purpose: + + Verifies that a cryptographic MIC, contained in the token parameter, + fits the supplied message. The qop_state parameter allows a message + recipient to determine the strength of protection that was applied to + the message. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context on which the message + arrived + + message_buffer buffer, opaque, read + Message to be verified + + token_buffer buffer, opaque, read + Token associated with message + + + + + Wray Document Expiration: 1 September 1997 [Page 74] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + qop_state gss_qop_t, modify, optional + quality of protection gained from MIC + Specify NULL if not required + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The MIC was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct MIC + for the message, but it had already been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC for + the message, but it is too old to check for + duplication. + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; a + later token has already been received. + + GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; + an earlier expected token has not yet been received. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + + + + + + + 7.33. gss_wrap + + OM_uint32 gss_wrap ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + int conf_req_flag, + gss_qop_t qop_req + const gss_buffer_t input_message_buffer, + int * conf_state, + gss_buffer_t output_message_buffer ) + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 75] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Purpose: + + Attaches a cryptographic MIC and optionally encrypts the specified + input_message. The output_message contains both the MIC and the + message. The qop_req parameter allows a choice between several + cryptographic algorithms, if supported by the chosen mechanism. + + Since some application-level protocols may wish to use tokens emitted by + gss_wrap() to provide "secure framing", implementations should support + the wrapping of zero-length messages. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context on which the message + will be sent + + conf_req_flag boolean, read + Non-zero - Both confidentiality and integrity + services are requested + Zero - Only integrity service is requested + + qop_req gss_qop_t, read, optional + Specifies required quality of protection. A + mechanism-specific default may be requested by + setting qop_req to GSS_C_QOP_DEFAULT. If an + unsupported protection strength is requested, + gss_wrap will return a major_status of + GSS_S_BAD_QOP. + + input_message_buffer buffer, opaque, read + Message to be protected + + conf_state boolean, modify, optional + Non-zero - Confidentiality, data origin + authentication and integrity + services have been applied + Zero - Integrity and data origin services only + has been applied. + Specify NULL if not required + + output_message_buffer buffer, opaque, modify + Buffer to receive protected message. + Storage associated with this message must + be freed by the application after use with + a call to gss_release_buffer(). + + Function value: GSS status code + + + + Wray Document Expiration: 1 September 1997 [Page 76] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. + + + + + + + + 7.34. gss_wrap_size_limit + + OM_uint32 gss_wrap_size_limit ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + int conf_req_flag, + gss_qop_t qop_req, + OM_uint32 req_output_size, + OM_uint32 * max_input_size) + + Purpose: + + Allows an application to determine the maximum message size that, if + presented to gss_wrap with the same conf_req_flag and qop_req + parameters, will result in an output token containing no more than + req_output_size bytes. + + This call is intended for use by applications that communicate over + protocols that impose a maximum message size. It enables the + application to fragment messages prior to applying protection. + + Successful completion of this call does not guarantee that gss_wrap will + be able to protect a message of length max_input_size bytes, since this + ability may depend on the availability of system resources at the time + that gss_wrap is called. However, if the implementation itself imposes + an upper limit on the length of messages that may be processed by + gss_wrap, the implementation should not return a value via + max_input_bytes that is greater than this length. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + context_handle gss_ctx_id_t, read + A handle that refers to the security over + + + + Wray Document Expiration: 1 September 1997 [Page 77] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + which the messages will be sent. + + conf_req_flag Boolean, read + Indicates whether gss_wrap will be asked + to apply confidentiality protection in + addition to integrity protection. See + the routine description for gss_wrap + for more details. + + qop_req gss_qop_t, read + Indicates the level of protection that + gss_wrap will be asked to provide. See + the routine description for gss_wrap for + more details. + + req_output_size Integer, read + The desired maximum size for tokens emitted + by gss_wrap. + + max_input_size Integer, modify + The maximum input message size that may + be presented to gss_wrap in order to + guarantee that the emitted token shall + be no larger than req_output_size bytes. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CONTEXT The referenced context could not be accessed. + + GSS_S_CONTEXT_EXPIRED The context has expired. + + GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. + + + + + + + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 78] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + APPENDIX A. GSS-API C header file gssapi.h + + C-language GSS-API implementations should include a copy of the + following header-file. + + #ifndef GSSAPI_H_ + #define GSSAPI_H_ + + + + /* + * First, include stddef.h to get size_t defined. + */ + #include + + /* + * If the platform supports the xom.h header file, it should be + * included here. + */ + #include + + + + /* + * Now define the three implementation-dependent types. + */ + typedef gss_ctx_id_t; + typedef gss_cred_id_t; + typedef gss_name_t; + + /* + * The following type must be defined as the smallest natural + * unsigned integer supported by the platform that has at least + * 32 bits of precision. + */ + typedef gss_uint32; + + + #ifdef OM_STRING + /* + * We have included the xom.h header file. Verify that OM_uint32 + * is defined correctly. + */ + + #if sizeof(gss_uint32) != sizeof(OM_uint32) + #error Incompatible definition of OM_uint32 from xom.h + #endif + + typedef OM_object_identifier gss_OID_desc, *gss_OID; + + #else + + + + Wray Document Expiration: 1 September 1997 [Page 79] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* + * We can't use X/Open definitions, so roll our own. + */ + + typedef gss_uint32 OM_uint32; + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + #endif + + typedef struct gss_OID_set_desc_struct { + size_t count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + + /* + * For now, define a QOP-type as an OM_uint32 + */ + typedef OM_uint32 gss_qop_t; + + typedef int gss_cred_usage_t; + + /* + * Flag bits for context-level services. + */ + #define GSS_C_DELEG_FLAG 1 + #define GSS_C_MUTUAL_FLAG 2 + #define GSS_C_REPLAY_FLAG 4 + #define GSS_C_SEQUENCE_FLAG 8 + #define GSS_C_CONF_FLAG 16 + #define GSS_C_INTEG_FLAG 32 + #define GSS_C_ANON_FLAG 64 + #define GSS_C_PROT_READY_FLAG 128 + #define GSS_C_TRANS_FLAG 256 + + + + Wray Document Expiration: 1 September 1997 [Page 80] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* + * Credential usage options + */ + #define GSS_C_BOTH 0 + #define GSS_C_INITIATE 1 + #define GSS_C_ACCEPT 2 + + /* + * Status code types for gss_display_status + */ + #define GSS_C_GSS_CODE 1 + #define GSS_C_MECH_CODE 2 + + /* + * The constant definitions for channel-bindings address families + */ + #define GSS_C_AF_UNSPEC 0 + #define GSS_C_AF_LOCAL 1 + #define GSS_C_AF_INET 2 + #define GSS_C_AF_IMPLINK 3 + #define GSS_C_AF_PUP 4 + #define GSS_C_AF_CHAOS 5 + #define GSS_C_AF_NS 6 + #define GSS_C_AF_NBS 7 + #define GSS_C_AF_ECMA 8 + #define GSS_C_AF_DATAKIT 9 + #define GSS_C_AF_CCITT 10 + #define GSS_C_AF_SNA 11 + #define GSS_C_AF_DECnet 12 + #define GSS_C_AF_DLI 13 + #define GSS_C_AF_LAT 14 + #define GSS_C_AF_HYLINK 15 + #define GSS_C_AF_APPLETALK 16 + #define GSS_C_AF_BSC 17 + #define GSS_C_AF_DSS 18 + #define GSS_C_AF_OSI 19 + #define GSS_C_AF_X25 21 + + #define GSS_C_AF_NULLADDR 255 + + /* + * Various Null values + */ + #define GSS_C_NO_NAME ((gss_name_t) 0) + #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) + #define GSS_C_NO_OID ((gss_OID) 0) + #define GSS_C_NO_OID_SET ((gss_OID_set) 0) + #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) + #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) + #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) + #define GSS_C_EMPTY_BUFFER {0, NULL} + + + + Wray Document Expiration: 1 September 1997 [Page 81] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* + * Some alternate names for a couple of the above + * values. These are defined for V1 compatibility. + */ + #define GSS_C_NULL_OID GSS_C_NO_OID + #define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET + + /* + * Define the default Quality of Protection for per-message + * services. Note that an implementation that offers multiple + * levels of QOP may define GSS_C_QOP_DEFAULT to be either zero + * (as done here) to mean "default protection", or to a specific + * explicit QOP value. However, a value of 0 should always be + * interpreted by a GSSAPI implementation as a request for the + * default protection level. + */ + #define GSS_C_QOP_DEFAULT 0 + + /* + * Expiration time of 2^32-1 seconds means infinite lifetime for a + * credential or security context + */ + #define GSS_C_INDEFINITE 0xfffffffful + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" + * "\x01\x02\x01\x01"}, + * corresponding to an object-identifier value of + * {iso(1) member-body(2) United States(840) mit(113554) + * infosys(1) gssapi(2) generic(1) user_name(1)}. The constant + * GSS_C_NT_USER_NAME should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_USER_NAME; + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" + * "\x01\x02\x01\x02"}, + * corresponding to an object-identifier value of + * {iso(1) member-body(2) United States(840) mit(113554) + * infosys(1) gssapi(2) generic(1) machine_uid_name(2)}. + * The constant GSS_C_NT_MACHINE_UID_NAME should be + * initialized to point to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_MACHINE_UID_NAME; + + /* + + + + Wray Document Expiration: 1 September 1997 [Page 82] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" + * "\x01\x02\x01\x03"}, + * corresponding to an object-identifier value of + * {iso(1) member-body(2) United States(840) mit(113554) + * infosys(1) gssapi(2) generic(1) string_uid_name(3)}. + * The constant GSS_C_NT_STRING_UID_NAME should be + * initialized to point to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_STRING_UID_NAME; + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {6, (void *)"\x2b\x06\x01\x05\x06\x02"}, + * corresponding to an object-identifier value of + * {1(iso), 3(org), 6(dod), 1(internet), 5(security), + * 6(nametypes), 2(gss-host-based-services)}. The constant + * GSS_C_NT_HOSTBASED_SERVICE should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_HOSTBASED_SERVICE; + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {6, (void *)"\x2b\x06\01\x05\x06\x03"}, + * corresponding to an object identifier value of + * {1(iso), 3(org), 6(dod), 1(internet), 5(security), + * 6(nametypes), 3(gss-anonymous-name)}. The constant + * and GSS_C_NT_ANONYMOUS should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_ANONYMOUS; + + + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {6, (void *)"\x2b\x06\x01\x05\x06\x04"}, + * corresponding to an object-identifier value of + * {1(iso), 3(org), 6(dod), 1(internet), 5(security), + * 6(nametypes), 4(gss-api-exported-name)}. The constant + * GSS_C_NT_EXPORT_NAME should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_EXPORT_NAME; + + + + + + Wray Document Expiration: 1 September 1997 [Page 83] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* Major status codes */ + + #define GSS_S_COMPLETE 0 + + /* + * Some "helper" definitions to make the status code macros obvious. + */ + #define GSS_C_CALLING_ERROR_OFFSET 24 + #define GSS_C_ROUTINE_ERROR_OFFSET 16 + #define GSS_C_SUPPLEMENTARY_OFFSET 0 + #define GSS_C_CALLING_ERROR_MASK 0377ul + #define GSS_C_ROUTINE_ERROR_MASK 0377ul + #define GSS_C_SUPPLEMENTARY_MASK 0177777ul + + /* + * The macros that test status codes for error conditions. + * Note that the GSS_ERROR() macro has changed slightly from + * the V1 GSSAPI so that it now evaluates its argument + * only once. + */ + #define GSS_CALLING_ERROR(x) \ + (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) + #define GSS_ROUTINE_ERROR(x) \ + (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) + #define GSS_SUPPLEMENTARY_INFO(x) \ + (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) + #define GSS_ERROR(x) \ + (x & ((GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET) | \ + (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))) + + + /* + * Now the actual status code definitions + */ + + /* + * Calling errors: + */ + #define GSS_S_CALL_INACCESSIBLE_READ \ + (1ul << GSS_C_CALLING_ERROR_OFFSET) + #define GSS_S_CALL_INACCESSIBLE_WRITE \ + (2ul << GSS_C_CALLING_ERROR_OFFSET) + #define GSS_S_CALL_BAD_STRUCTURE \ + (3ul << GSS_C_CALLING_ERROR_OFFSET) + + /* + * Routine errors: + */ + #define GSS_S_BAD_MECH (1ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAME (2ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAMETYPE (3ul << GSS_C_ROUTINE_ERROR_OFFSET) + + + + Wray Document Expiration: 1 September 1997 [Page 84] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + #define GSS_S_BAD_BINDINGS (4ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_STATUS (5ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_SIG (6ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_MIC GSS_S_BAD_SIG + #define GSS_S_NO_CRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NO_CONTEXT (8ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_TOKEN (9ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CREDENTIALS_EXPIRED (11ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CONTEXT_EXPIRED (12ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_FAILURE (13ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_QOP (14ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_UNAUTHORIZED (15ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_UNAVAILABLE (16ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DUPLICATE_ELEMENT (17ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NAME_NOT_MN (18ul << GSS_C_ROUTINE_ERROR_OFFSET) + + /* + * Supplementary info bits: + */ + #define GSS_S_CONTINUE_NEEDED (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) + #define GSS_S_DUPLICATE_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) + #define GSS_S_OLD_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) + #define GSS_S_UNSEQ_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) + #define GSS_S_GAP_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4)) + + + /* + * Finally, function prototypes for the GSS-API routines. + */ + + OM_uint32 gss_acquire_cred + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* desired_name */ + OM_uint32, /* time_req */ + const gss_OID_set, /* desired_mechs */ + gss_cred_usage_t, /* cred_usage */ + gss_cred_id_t *, /* output_cred_handle */ + gss_OID_set *, /* actual_mechs */ + OM_uint32 * /* time_rec */ + ); + + OM_uint32 gss_release_cred + (OM_uint32 *, /* minor_status */ + gss_cred_id_t * /* cred_handle */ + ); + + OM_uint32 gss_init_sec_context + (OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* initiator_cred_handle */ + gss_ctx_id_t *, /* context_handle */ + + + + Wray Document Expiration: 1 September 1997 [Page 85] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + const gss_name_t, /* target_name */ + const gss_OID, /* mech_type */ + OM_uint32, /* req_flags */ + OM_uint32, /* time_req */ + const gss_channel_bindings_t, + /* input_chan_bindings */ + const gss_buffer_t, /* input_token */ + gss_OID *, /* actual_mech_type */ + gss_buffer_t, /* output_token */ + OM_uint32 *, /* ret_flags */ + OM_uint32 * /* time_rec */ + ); + + OM_uint32 gss_accept_sec_context + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t *, /* context_handle */ + const gss_cred_id_t, /* acceptor_cred_handle */ + const gss_buffer_t, /* input_token_buffer */ + const gss_channel_bindings_t, + /* input_chan_bindings */ + gss_name_t *, /* src_name */ + gss_OID *, /* mech_type */ + gss_buffer_t, /* output_token */ + OM_uint32 *, /* ret_flags */ + OM_uint32 *, /* time_rec */ + gss_cred_id_t * /* delegated_cred_handle */ + ); + + OM_uint32 gss_process_context_token + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + const gss_buffer_t /* token_buffer */ + ); + + OM_uint32 gss_delete_sec_context + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t *, /* context_handle */ + gss_buffer_t /* output_token */ + ); + + OM_uint32 gss_context_time + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + OM_uint32 * /* time_rec */ + ); + + OM_uint32 gss_get_mic + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + gss_qop_t, /* qop_req */ + const gss_buffer_t, /* message_buffer */ + + + + Wray Document Expiration: 1 September 1997 [Page 86] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_buffer_t /* message_token */ + ); + + + OM_uint32 gss_verify_mic + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + const gss_buffer_t, /* message_buffer */ + const gss_buffer_t, /* token_buffer */ + gss_qop_t * /* qop_state */ + ); + + OM_uint32 gss_wrap + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + gss_qop_t, /* qop_req */ + const gss_buffer_t, /* input_message_buffer */ + int *, /* conf_state */ + gss_buffer_t /* output_message_buffer */ + ); + + + OM_uint32 gss_unwrap + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + const gss_buffer_t, /* input_message_buffer */ + gss_buffer_t, /* output_message_buffer */ + int *, /* conf_state */ + gss_qop_t * /* qop_state */ + ); + + + + OM_uint32 gss_display_status + (OM_uint32 *, /* minor_status */ + OM_uint32, /* status_value */ + int, /* status_type */ + const gss_OID, /* mech_type */ + OM_uint32 *, /* message_context */ + gss_buffer_t /* status_string */ + ); + + OM_uint32 gss_indicate_mechs + (OM_uint32 *, /* minor_status */ + gss_OID_set * /* mech_set */ + ); + + OM_uint32 gss_compare_name + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* name1 */ + + + + Wray Document Expiration: 1 September 1997 [Page 87] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + const gss_name_t, /* name2 */ + int * /* name_equal */ + ); + + OM_uint32 gss_display_name + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + gss_buffer_t, /* output_name_buffer */ + gss_OID * /* output_name_type */ + ); + + OM_uint32 gss_import_name + (OM_uint32 *, /* minor_status */ + const gss_buffer_t, /* input_name_buffer */ + const gss_OID, /* input_name_type */ + gss_name_t * /* output_name */ + ); + + OM_uint32 gss_export_name + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + gss_buffer_t /* exported_name */ + ); + + OM_uint32 gss_release_name + (OM_uint32 *, /* minor_status */ + gss_name_t * /* input_name */ + ); + + OM_uint32 gss_release_buffer + (OM_uint32 *, /* minor_status */ + gss_buffer_t /* buffer */ + ); + + OM_uint32 gss_release_oid_set + (OM_uint32 *, /* minor_status */ + gss_OID_set * /* set */ + ); + + OM_uint32 gss_inquire_cred + (OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* cred_handle */ + gss_name_t *, /* name */ + OM_uint32 *, /* lifetime */ + gss_cred_usage_t *, /* cred_usage */ + gss_OID_set * /* mechanisms */ + ); + + OM_uint32 gss_inquire_context ( + OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + + + + Wray Document Expiration: 1 September 1997 [Page 88] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_name_t *, /* src_name */ + gss_name_t *, /* targ_name */ + OM_uint32 *, /* lifetime_rec */ + gss_OID *, /* mech_type */ + OM_uint32 *, /* ctx_flags */ + int *, /* locally_initiated */ + int * /* open */ + ); + + OM_uint32 gss_wrap_size_limit ( + OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + gss_qop_t, /* qop_req */ + OM_uint32, /* req_output_size */ + OM_uint32 * /* max_input_size */ + ); + + + OM_uint32 gss_add_cred ( + OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* input_cred_handle */ + const gss_name_t, /* desired_name */ + const gss_OID, /* desired_mech */ + gss_cred_usage_t, /* cred_usage */ + OM_uint32, /* initiator_time_req */ + OM_uint32, /* acceptor_time_req */ + gss_cred_id_t *, /* output_cred_handle */ + gss_OID_set *, /* actual_mechs */ + OM_uint32 *, /* initiator_time_rec */ + OM_uint32 * /* acceptor_time_rec */ + ); + + + OM_uint32 gss_inquire_cred_by_mech ( + OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* cred_handle */ + const gss_OID, /* mech_type */ + gss_name_t *, /* name */ + OM_uint32 *, /* initiator_lifetime */ + OM_uint32 *, /* acceptor_lifetime */ + gss_cred_usage_t * /* cred_usage */ + ); + + OM_uint32 gss_export_sec_context ( + OM_uint32 *, /* minor_status */ + gss_ctx_id_t *, /* context_handle */ + gss_buffer_t /* interprocess_token */ + ); + + OM_uint32 gss_import_sec_context ( + + + + Wray Document Expiration: 1 September 1997 [Page 89] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + OM_uint32 *, /* minor_status */ + const gss_buffer_t, /* interprocess_token */ + gss_ctx_id_t * /* context_handle */ + ); + + OM_uint32 gss_create_empty_oid_set ( + OM_uint32 *, /* minor_status */ + gss_OID_set * /* oid_set */ + ); + + OM_uint32 gss_add_oid_set_member ( + OM_uint32 *, /* minor_status */ + const gss_OID, /* member_oid */ + gss_OID_set * /* oid_set */ + ); + + OM_uint32 gss_test_oid_set_member ( + OM_uint32 *, /* minor_status */ + const gss_OID, /* member */ + const gss_OID_set, /* set */ + int * /* present */ + ); + + OM_uint32 gss_inquire_names_for_mech ( + OM_uint32 *, /* minor_status */ + const gss_OID, /* mechanism */ + gss_OID_set * /* name_types */ + ); + + OM_uint32 gss_inquire_mechs_for_name ( + OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + gss_OID_set * /* mech_types */ + ); + + OM_uint32 gss_canonicalize_name ( + OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + const gss_OID, /* mech_type */ + gss_name_t * /* output_name */ + ); + + OM_uint32 gss_duplicate_name ( + OM_uint32 *, /* minor_status */ + const gss_name_t, /* src_name */ + gss_name_t * /* dest_name */ + ); + + /* + * The following routines are obsolete variants of gss_get_mic, + * gss_verify_mic, gss_wrap and gss_unwrap. They should be + + + + Wray Document Expiration: 1 September 1997 [Page 90] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + * provided by GSSAPI V2 implementations for backwards + * compatibility with V1 applications. Distinct entrypoints + * (as opposed to #defines) should be provided, both to allow + * GSSAPI V1 applications to link against GSSAPI V2 implementations, + * and to retain the slight parameter type differences between the + * obsolete versions of these routines and their current forms. + */ + + OM_uint32 gss_sign + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* qop_req */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t /* message_token */ + ); + + + OM_uint32 gss_verify + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t, /* token_buffer */ + int * /* qop_state */ + ); + + OM_uint32 gss_seal + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + int, /* qop_req */ + gss_buffer_t, /* input_message_buffer */ + int *, /* conf_state */ + gss_buffer_t /* output_message_buffer */ + ); + + + OM_uint32 gss_unseal + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* input_message_buffer */ + gss_buffer_t, /* output_message_buffer */ + int *, /* conf_state */ + int * /* qop_state */ + ); + + + + + #endif /* GSSAPI_H_ */ + + + + + + Wray Document Expiration: 1 September 1997 [Page 91] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + APPENDIX B. Additional constraints for application binary portability + + The purpose of this C-bindings document is to encourage source-level + portability of applications across GSS-API implementations on different + platforms and atop different mechanisms. Additional goals that have not + been explicitly addressed by this document are link-time and run-time + portability. + + Link-time portability provides the ability to compile an application + against one implementation of GSS-API, and then link it against a + different implementation on the same platform. It is a stricter + requirement than source-level portability. + + Run-time portability differs from link-time portability only on those + platforms that implement dynamically loadable GSS-API implementations, + but do not offer load-time symbol resolution. On such platforms, run- + time portability is a stricter requirement than link-time portability, + and will typically include the precise placement of the various GSS-API + routines within library entrypoint vectors. + + Individual platforms will impose their own rules that must be followed + to achieve link-time (and run-time, if different) portability. In order + to ensure either form of binary portability, an ABI specification must + be written for GSS-API implementations on that platform. However, it is + recognized that there are some issues that are likely to be common to + all such ABI specifications. This appendix is intended to be a + repository for such common issues, and contains some suggestions that + individual ABI specifications may choose to reference. Since machine + architectures vary greatly, it may not be possible or desirable to + follow these suggestions on all platforms. + + B.1. Pointers + + While ANSI-C provides a single pointer type for each declared type, plus + a single (void *) type, some platforms (notably those using segmented + memory architectures) augment this with various modified pointer types + (e.g. far pointers, near pointers). These language bindings assume + ANSI-C, and thus do not address such non-standard implementations. + GSS-API implementations for such platforms must choose an appropriate + memory model, and should use it consistently throughout. For example, + if a memory model is chosen that requires the use of far pointers when + passing routine parameters, then far pointers should also be used within + the structures defined by GSS-API. + + B.2. Internal structure alignment + + GSS-API defines several data-structures containing differently-sized + fields. An ABI specification should include a detailed description of + how the fields of such structures are aligned, and if there is any + internal padding in these data structures. The use of compiler defaults + for the platform is recommended. + + + + Wray Document Expiration: 1 September 1997 [Page 92] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + B.3. Handle types + + The C bindings specify that the gss_cred_id_t and gss_ctx_id_t types + should be implemented as either pointer or arithmetic types, and that if + pointer types are used, care should be taken to ensure that two handles + may be compared with the == operator. Note that ANSI-C does not + guarantee that two pointer values may be compared with the == operator + unless either the two pointers point to members of a single array, or at + least one of the pointers contains a NULL value. + + For binary portability, additional constraints are required. The + following is an attempt at defining platform-independent constraints. + + (a) The size of the handle type must be the same as sizeof(void *), + using the appropriate memory model. + + (b) The == operator for the chosen type must be a simple bit-wise + comparison. That is, for two in-memory handle objects h1 and h2, + the boolean value of the expression + + (h1 == h2) + + should always be the same as the boolean value of the expression + + (memcmp(&h1, &h2, sizeof(h1)) == 0) + + (c) The actual use of the type (void *) for handle types is + discouraged, not for binary portability reasons, but since it + effectively disables much of the compile-time type-checking that + the compiler can otherwise perform, and is therefore not + "programmer-friendly". If a pointer implementation is desired, + and if the platform's implementation of pointers permits, the + handles should be implemented as pointers to distinct + implementation-defined types. + + B.4. The gss_name_t type + + The gss_name_t type, representing the internal name object, should be + implemented as a pointer type. The use of the (void *) type is + discouraged as it does not allow the compiler to perform strong type- + checking. However, the pointer type chosen should be of the same size + as the (void *) type. Provided this rule is obeyed, ABI specifications + need not further constrain the implementation of gss_name_t objects. + + B.5. The int and size_t types + + Some platforms may support differently sized implementations of the + "int" and "size_t" types, perhaps chosen through compiler switches, and + perhaps dependent on memory model. An ABI specification for such a + platform should include required implementations for these types. It is + recommended that the default implementation (for the chosen memory + + + + Wray Document Expiration: 1 September 1997 [Page 93] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + model, if appropriate) is chosen. + + B.6. Procedure-calling conventions + + Some platforms support a variety of different binary conventions for + calling procedures. Such conventions cover things like the format of + the stack frame, the order in which the routine parameters are pushed + onto the stack, whether or not a parameter count is pushed onto the + stack, whether some argument(s) or return values are to be passed in + registers, and whether the called routine or the caller is responsible + for removing the stack frame on return. For such platforms, an ABI + specification should specify which calling convention is to be used for + GSSAPI implementations. + + + REFERENCES + + [GSSAPI] J. Linn, "Generic Security Service Application Program + Interface, Version 2", Internet-Draft draft-ietf-cat-gssv2- + 08, 26 August 1996. (This Internet-Draft, like all other + Internet-Drafts, is not an archival document and is subject + to change or deletion. It is available at the time of this + writing by anonymous ftp from ds.internic.net, directory + internet-drafts. Would-be readers should check for successor + Internet-Draft versions or Internet RFCs before relying on + this document.) + + [XOM] OSI Object Management API Specification, Version 2.0 t", + X.400 API Association & X/Open Company Limited, August 24, + 1990. Specification of datatypes and routines for + manipulating information objects. + + + AUTHOR'S ADDRESS + + John Wray Internet email: Wray@tuxedo.enet.dec.com + Digital Equipment Corporation Telephone: +1-508-486-5210 + 550 King Street, LKG2-2/Z7 + Littleton, MA 01460 + USA + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 94] + + + diff --git a/doc/standardisation/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt b/doc/standardisation/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt new file mode 100644 index 000000000..2583a84da --- /dev/null +++ b/doc/standardisation/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt @@ -0,0 +1,127 @@ + + + + + + +Network Working Group M. Horowitz + Cygnus Solutions +Internet-Draft November, 1996 + + + Triple DES with HMAC-SHA1 Kerberos Encryption Type + +Status of this Memo + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its areas, + and its working groups. Note that other groups may also distribute + working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as ``work in progress.'' + + To learn the current status of any Internet-Draft, please check the + ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow + Directories on ds.internic.net (US East Coast), nic.nordu.net + (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific + Rim). + + Distribution of this memo is unlimited. Please send comments to the + mailing list. + +Abstract + + This document defines a new encryption type and a new checksum type + for use with Kerberos V5 [RFC1510]. This encryption type is based on + the Triple DES cryptosystem and the HMAC-SHA1 [Krawczyk96] message + authentication algorithm. + + The des3-cbc-hmac-sha1 encryption type has been assigned the value 7. + The hmac-sha1-des3 checksum type has been assigned the value 12. + + +Encryption Type des3-cbc-hmac-sha1 + + EncryptedData using this type must be generated as described in + [Horowitz96]. The encryption algorithm is Triple DES in Outer-CBC + mode. The keyed hash algorithm is HMAC-SHA1. Unless otherwise + specified, a zero IV must be used. If the length of the input data + is not a multiple of the block size, zero octets must be used to pad + the plaintext to the next eight-octet boundary. The counfounder must + be eight random octets (one block). + + +Checksum Type hmac-sha1-des3 + + Checksums using this type must be generated as described in + [Horowitz96]. The keyed hash algorithm is HMAC-SHA1. + + + +Horowitz [Page 1] + +Internet Draft Kerberos Triple DES with HMAC-SHA1 November, 1996 + + +Common Requirements + + Where the Triple DES key is represented as an EncryptionKey, it shall + be represented as three DES keys, with parity bits, concatenated + together. The key shall be represented with the most significant bit + first. + + When keys are generated by the derivation function, a key length of + 168 bits shall be used. The output bit string will be converted to a + valid Triple DES key by inserting DES parity bits after every seventh + bit. + + Any implementation which implements either of the encryption or + checksum types in this document must support both. + + +Security Considerations + + This entire document defines encryption and checksum types for use + with Kerberos V5. + + +References + + [Horowitz96] Horowitz, M., "Key Derivation for Kerberos V5", draft- + horowitz-kerb-key-derivation-00.txt, November 1996. + [Krawczyk96] Krawczyk, H., Bellare, and M., Canetti, R., "HMAC: + Keyed-Hashing for Message Authentication", draft-ietf-ipsec-hmac- + md5-01.txt, August, 1996. + [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network + Authentication Service (V5)", RFC 1510, September 1993. + + +Author's Address + + Marc Horowitz + Cygnus Solutions + 955 Massachusetts Avenue + Cambridge, MA 02139 + + Phone: +1 617 354 7688 + Email: marc@cygnus.com + + + + + + + + + + + + + + + +Horowitz [Page 2] + diff --git a/doc/standardisation/draft-ietf-cat-kerb-key-derivation-00.txt b/doc/standardisation/draft-ietf-cat-kerb-key-derivation-00.txt new file mode 100644 index 000000000..46a415852 --- /dev/null +++ b/doc/standardisation/draft-ietf-cat-kerb-key-derivation-00.txt @@ -0,0 +1,250 @@ + + + + + +Network Working Group M. Horowitz + Cygnus Solutions +Internet-Draft November, 1996 + + + Key Derivation for Kerberos V5 + +Status of this Memo + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its areas, + and its working groups. Note that other groups may also distribute + working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as ``work in progress.'' + + To learn the current status of any Internet-Draft, please check the + ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow + Directories on ds.internic.net (US East Coast), nic.nordu.net + (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific + Rim). + + Distribution of this memo is unlimited. Please send comments to the + mailing list. + +Abstract + + In the Kerberos protocol [RFC1510], cryptographic keys are used in a + number of places. In order to minimize the effect of compromising a + key, it is desirable to use a different key for each of these places. + Key derivation [Horowitz96] can be used to construct different keys + for each operation from the keys transported on the network. For + this to be possible, a small change to the specification is + necessary. + + +Overview + + Under RFC1510 as stated, key derivation could be specified as a set + of encryption types which share the same key type. The constant for + each derivation would be a function of the encryption type. However, + it is generally accepted that, for interoperability, key types and + encryption types must map one-to-one onto each other. (RFC 1510 is + being revised to address this issue.) Therefore, to use key + derivcation with Kerberos V5 requires a small change to the + specification. + + For each place where a key is used in Kerberos, a ``key usage'' must + be specified for that purpose. The key, key usage, and + encryption/checksum type together describe the transformation from + plaintext to ciphertext, or plaintext to checksum. For backward + + + +Horowitz [Page 1] + +Internet Draft Key Derivation for Kerberos V5 November, 1996 + + + compatibility, old encryption types would be defined independently of + the key usage. + + +Key Usage Values + + This is a complete list of places keys are used in the kerberos + protocol, with key usage values and RFC 1510 section numbers: + + 1. AS-REQ PA-ENC-TIMESTAMP padata timestamp, encrypted with the + client key (section 5.4.1) + 2. AS-REP Ticket and TGS-REP Ticket (includes tgs session key or + application session key), encrypted with the service key + (section 5.4.2) + 3. AS-REP encrypted part (includes tgs session key or application + session key), encrypted with the client key (section 5.4.2) + + 4. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + session key (section 5.4.1) + 5. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + authenticator subkey (section 5.4.1) + 6. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator cksum, keyed + with the tgs session key (sections 5.3.2, 5.4.1) + 7. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator (includes tgs + authenticator subkey), encrypted with the tgs session key + (section 5.3.2) + 8. TGS-REP encrypted part (includes application session key), + encrypted with the tgs session key (section 5.4.2) + 9. TGS-REP encrypted part (includes application session key), + encrypted with the tgs authenticator subkey (section 5.4.2) + + 10. AP-REQ Authenticator cksum, keyed with the application session + key (section 5.3.2) + 11. AP-REQ Authenticator (includes application authenticator + subkey), encrypted with the application session key (section + 5.3.2) + 12. AP-REP encrypted part (includes application session subkey), + encrypted with the application session key (section 5.5.2) + + 13. KRB-PRIV encrypted part, encrypted with a key chosen by the + application (section 5.7.1) + 14. KRB-CRED encrypted part, encrypted with a key chosen by the + application (section 5.6.1) + 15. KRB-SAVE cksum, keyed with a key chosen by the application + (section 5.8.1) + + 16. Data which is defined in some specification outside of + Kerberos to be encrypted using an RFC1510 encryption type. + 17. Data which is defined in some specification outside of + Kerberos to be checksummed using an RFC1510 checksum type. + + A few of these key usages need a little clarification. A service + which receives an AP-REQ has no way to know if the enclosed Ticket + was part of an AS-REP or TGS-REP. Therefore, key usage 2 must always + + + +Horowitz [Page 2] + +Internet Draft Key Derivation for Kerberos V5 November, 1996 + + + be used for generating a Ticket, whether it is in response to an AS- + REQ or TGS-REQ. + + There might exist other documents which define protocols in terms of + the RFC1510 encryption types or checksum types. Such documents would + not know about key usages. In order that these documents continue to + be meaningful until they are updated, key usages 16 and 17 must be + used to derive keys for encryption and checksums, respectively. New + protocols defined in terms of the Kerberos encryption and checksum + types should use their own key usages. Key usages may be registered + with IANA to avoid conflicts. Key usages shall be unsigned 32 bit + integers. Zero is not permitted. + + +Defining Cryptosystems Using Key Derivation + + Kerberos requires that the ciphertext component of EncryptedData be + tamper-resistant as well as confidential. This implies encryption + and integrity functions, which must each use their own separate keys. + So, for each key usage, two keys must be generated, one for + encryption (Ke), and one for integrity (Ki): + + Ke = DK(protocol key, key usage | 0xAA) + Ki = DK(protocol key, key usage | 0x55) + + where the key usage is represented as a 32 bit integer in network + byte order. The ciphertest must be generated from the plaintext as + follows: + + ciphertext = E(Ke, confounder | length | plaintext | padding) | + H(Ki, confounder | length | plaintext | padding) + + The confounder and padding are specific to the encryption algorithm + E. + + When generating a checksum only, there is no need for a confounder or + padding. Again, a new key (Kc) must be used. Checksums must be + generated from the plaintext as follows: + + Kc = DK(protocol key, key usage | 0x99) + + MAC = H(Kc, length | plaintext) + + Note that each enctype is described by an encryption algorithm E and + a keyed hash algorithm H, and each checksum type is described by a + keyed hash algorithm H. HMAC, with an appropriate hash, is + recommended for use as H. + + +Security Considerations + + This entire document addresses shortcomings in the use of + cryptographic keys in Kerberos V5. + + + + +Horowitz [Page 3] + +Internet Draft Key Derivation for Kerberos V5 November, 1996 + + +Acknowledgements + + I would like to thank Uri Blumenthal, Sam Hartman, and Bill + Sommerfeld for their contributions to this document. + + +References + + [Horowitz96] Horowitz, M., "Key Derivation for Authentication, + Integrity, and Privacy", draft-horowitz-key-derivation-00.txt, + November 1996. [RFC1510] Kohl, J. and Neuman, C., "The Kerberos + Network Authentication Service (V5)", RFC 1510, September 1993. + + +Author's Address + + Marc Horowitz + Cygnus Solutions + 955 Massachusetts Avenue + Cambridge, MA 02139 + + Phone: +1 617 354 7688 + Email: marc@cygnus.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Horowitz [Page 4] + diff --git a/doc/standardisation/draft-ietf-cat-kerberos-err-msg-00.txt b/doc/standardisation/draft-ietf-cat-kerberos-err-msg-00.txt new file mode 100644 index 000000000..c5e4d05e7 --- /dev/null +++ b/doc/standardisation/draft-ietf-cat-kerberos-err-msg-00.txt @@ -0,0 +1,252 @@ + +INTERNET-DRAFT Ari Medvinsky +draft-ietf-cat-kerberos-err-msg-00.txt Matt Hur +Updates: RFC 1510 Dominique Brezinski +expires September 30, 1997 CyberSafe Corporation + Gene Tsudik + Brian Tung + ISI + +Integrity Protection for the Kerberos Error Message + +0. Status Of this Memo + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its + areas, and its working groups. Note that other groups may also + distribute working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six + months and may be updated, replaced, or obsoleted by other + documents at any time. It is inappropriate to use Internet-Drafts + as reference material or to cite them other than as "work in + progress." + + To learn the current status of any Internet-Draft, please check + the "1id-abstracts.txt" listing contained in the Internet-Drafts + Shadow Directories on ds.internic.net (US East Coast), + nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or + munnari.oz.au (Pacific Rim). + + The distribution of this memo is unlimited. It is filed as + draft-ietf-cat-kerberos-pk-init-03.txt, and expires June xx, 1997. + Please send comments to the authors. + +1. Abstract + + The Kerberos error message, as defined in RFC 1510, is transmitted + to the client without any integrity assurance. Therefore, the + client has no means to distinguish between a valid error message + sent from the KDC and one sent by an attacker. This draft describes + a method for assuring the integrity of Kerberos error messages, and + proposes a consistent format for the e-data field in the KRB_ERROR + message. This e-data format enables the storage of cryptographic + checksums by providing an extensible mechanism for specifying e-data + types. + + +2. Motivation + + In the Kerberos protocol [1], if an error occurs for AS_REQ, + TGS_REQ, or AP_REQ, a clear text error message is returned to the + client. An attacker may exploit this vulnerability by sending a + false error message as a reply to any of the above requests. For + example, an attacker may send the KDC_ERR_KEY_EXPIRED error message + in order to force a user to change their password in hope that the + new key will not be as strong as the current key, and thus, easier + to break. + + Since false error messages may be utilized by an attacker, a + Kerberos client should have a means for determining how much trust + to place in a given error message. The rest of this draft + describes a method for assuring the integrity of Kerberos error + messages. + + +3. Approach + + We propose taking a cryptographic checksum over the entire KRB-ERROR + message. This checksum would be returned as part of the error + message and would enable the client to verify the integrity of the + error message. For interoperability reasons, no new fields are + added to the KRB-ERROR message. Instead, the e-data field (see + figure 1) is utilized to carry the cryptographic checksum. + + +3.1 Cryptographic checksums in error messages for AS_REQ, + TGS_REQ & AP_REQ + + If an error occurs for the AS request, the only key that is + available to the KDC is the shared secret (the key derived from the + clients password) registered in the KDCs database. The KDC will + use this key to sign the error message, if and only if, the client + already proved knowledge of the shared secret in the AS request + (e.g. via PA-ENC-TIMESTAMP in preauth data). This policy is needed + to prevent an attacker from getting the KDC to send a signed error + message and then launching an off-line attack in order to obtain a + key of a given principal. + + If an error occurs for a TGS or an AP request, the server will use + the session key sealed in the clients ticket granting ticket to + compute the checksum over the error message. If the checksum could + not be computed (e.g. error while decrypting the ticket) the error + message is returned to the client without the checksum. The client + then has the option to treat unprotected error messages differently. + + + KRB-ERROR ::= [APPLICATION 30] SEQUENCE { + pvno [0] integer, + msg-type [1] integer, + ctime [2] KerberosTime OPTIONAL, + cusec [3] INTEGER OPTIONAL, + stime [4] KerberosTime, + susec [5] INTEGER, + error-code [6] INTEGER, + crealm [7] Realm OPTIONAL, + cname [8] PrincipalName OPTIONAL, + realm [9] Realm, --Correct realm + sname [10] PrincipalName, --Correct name + e-text [11] GeneralString OPTIONAL, + e-data [12] OCTET STRING OPTIONAL + } + Figure 1 + + +3.2 Format of the e-data field + + We propose to place the cryptographic checksum in the e-data field. + First, we review the format of the e-data field, as specified in + RFC 1510. The format of e-data is specified only in two cases [2]. + "If the error code is KDC_ERR_PREAUTH_REQUIRED, then the e-data + field will contain an encoding of a sequence of padata fields": + + METHOD-DATA ::= SEQUENCE of PA-DATA + PA-DATA ::= SEQUENCE { + padata-type [1] INTEGER, + padata-value [2] OCTET STRING + } + + The second case deals with the KRB_AP_ERR_METHOD error code. The + e-data field will contain an encoding of the following sequence: + + METHOD-DATA ::= SEQUENCE { + method-type [0] INTEGER, + method-data [1] OCTET STRING OPTIONAL + } + + method-type indicates the required alternate authentication method. + + It should be noted that, in the case of KRB_AP_ERR_METHOD, a signed + checksum is not returned as part of the error message, since the + error code indicates that the Kerberos credentials provided in the + AP_REQ message are unacceptable. + + We propose that the e-data field have the following format for all + error-codes (except KRB_AP_ERR_METHOD): + + E-DATA ::= SEQUENCE { + data-type [1] INTEGER, + data-value [2] OCTET STRING, + } + + The data-type field specifies the type of information that is + carried in the data-value field. Thus, to send a cryptographic + checksum back to the client, the data-type is set to CHECKSUM, the + data-value is set to the ASN.1 encoding of the following sequence: + + Checksum ::= SEQUENCE { + cksumtype [0] INTEGER, + checksum [1] OCTET STRING + } + + +3.3 Computing the checksum + + After the error message is filled out, the error structure is + converted into ASN.1 representation. A cryptographic checksum is + then taken over the encoded error message; the result is placed in + the error message structure, as the last item in the e-data field. + To send the error message, ASN.1 encoding is again performed over + the error message, which now includes the cryptographic checksum. + + +3.4 Verifying the integrity of the error message + + In addition to verifying the cryptographic checksum for the error + message, the client must verify that the error message is bound to + its request. This is done by comparing the ctime field in the + error message to its counterpart in the request message. + + +4. E-DATA types + + Since the e-data types must not conflict with preauthentication data + types, we propose that the preauthentication data types in the range + of 2048 and above be reserved for use as e-data types. + + We define the following e-data type in support of integrity checking + for the Kerberos error message: + + CHECKSUM = 2048 -- the keyed checksum described above + + +5. Discussion + + +5.1 e-data types + + The extension for Kerberos error messages, as outlined above, is + extensible to allow for definition of other error data types. + We propose that the following e-data types be reserved: + + KDCTIME = 2049 + The error data would consist of the KDCs time in KerberosTime. + This data would be used by the client to adjust for clock skew. + + REDIRECT = 2050 + The error data would consist of a hostname. The hostname would + indicate the authoritative KDC from which to obtain a TGT. + + +5.2 e-data types vs. error code specific data formats + + Since RFC 1510 does not define an error data type, the data format + must be explicitly specified for each error code. This draft has + proposed an extension to RFC 1510 that would introduce the concept + of error data types. This would allow for a manageable set of data + types to be used for any error message. The authors assume that + the introduction of this e-data structure will not break any + existing Kerberos implementations. + + +6. Bibliography + + [1] J. Kohl, C. Neuman. The Kerberos Network Authentication + Service (V5). Request for Comments: 1510 + [2] J. Kohl, C. Neuman. The Kerberos Network Authentication + Service (V5). Request for Comments: 1510 p.67 + + +7. Authors + + Ari Medvinsky + Matthew Hur + Dominique Brezinski + + CyberSafe Corporation + 1605 NW Sammamish Road + Suite 310 + Issaquah, WA 98027-5378 + Phone: (206) 391-6000 + Fax: (206) 391-0508 + http:/www.cybersafe.com + + + Brian Tung + Gene Tsudik + + USC Information Sciences Institute + 4676 Admiralty Way Suite 1001 + Marina del Rey CA 90292-6695 + Phone: (310) 822-1511 + diff --git a/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-01.txt b/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-01.txt new file mode 100644 index 000000000..4b193c573 --- /dev/null +++ b/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-01.txt @@ -0,0 +1,282 @@ +INTERNET-DRAFT Brian Tung +draft-ietf-cat-kerberos-pk-cross-01.txt Tatyana Ryutov +Updates: RFC 1510 Clifford Neuman +expires September 30, 1997 Gene Tsudik + ISI + Bill Sommerfeld + Hewlett-Packard + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + + + Public Key Cryptography for Cross-Realm Authentication in Kerberos + + +0. Status Of this Memo + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its + areas, and its working groups. Note that other groups may also + distribute working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six + months and may be updated, replaced, or obsoleted by other + documents at any time. It is inappropriate to use Internet-Drafts + as reference material or to cite them other than as ``work in + progress.'' + + To learn the current status of any Internet-Draft, please check + the ``1id-abstracts.txt'' listing contained in the Internet-Drafts + Shadow Directories on ds.internic.net (US East Coast), + nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or + munnari.oz.au (Pacific Rim). + + The distribution of this memo is unlimited. It is filed as + draft-ietf-cat-kerberos-pk-cross-01.txt, and expires September 30, + 1997. Please send comments to the authors. + + +1. Abstract + + This document defines extensions to the Kerberos protocol + specification (RFC 1510, "The Kerberos Network Authentication + Service (V5)", September 1993) to provide a method for using + public key cryptography during cross-realm authentication. The + methods defined here specify the way in which message exchanges + are to be used to transport cross-realm secret keys protected by + encryption under public keys certified as belonging to KDCs. + + +2. Motivation + + The advantages provided by public key cryptography--ease of + recoverability in the event of a compromise, the possibility of + an autonomous authentication infrastructure, to name a few--have + produced a demand for use by Kerberos authentication protocol. A + draft describing the use of public key cryptography in the initial + authentication exchange in Kerberos has already been submitted. + This draft describes its use in cross-realm authentication. + + The principal advantage provided by public key cryptography in + cross-realm authentication lies in the ability to leverage the + existing public key infrastructure. It frees the Kerberos realm + administrator from having to maintain separate keys for each other + realm with which it wishes to exchange authentication information, + or to utilize a hierarchical arrangement, which may pose problems + of trust. + + Even with the multi-hop cross-realm authentication, there must be + some way to locate the path by which separate realms are to be + transited. The current method, which makes use of the DNS-like + realm names typical to Kerberos, requires trust of the intermediate + KDCs. + + The methods described in this draft allow a realm to specify, at + the time of authentication, which certification paths it will + trust. A shared key for cross-realm authentication can be + established, for a period of time. Furthermore, these methods are + transparent to the client, so that only the KDC's need to be + modified to use them. + + It is not necessary to implement the changes described in the + "Public Key Cryptography for Initial Authentication" draft to make + use of the changes in this draft. We solicit comments about the + interaction between the two protocol changes, but as of this + writing, the authors do not perceive any obstacles to using both. + + +3. Protocol Amendments + + We assume that the user has already obtained a TGT. To perform + cross-realm authentication, the user sends a request to the local + KDC as per RFC 1510. If the two realms share a secret key, then + cross-realm authentication proceeds as usual. Otherwise, the + local KDC may attempt to establish a shared key with the remote + KDC using public key cryptography, and exchange this key through + the cross-realm ticket granting ticket. + + We will consider the specific channel on which the message + exchanges take place in Section 5 below. + + +3.1. Changes to the Cross-Realm Ticket Granting Ticket + + In order to avoid the need for changes to the "installed base" of + Kerberos application clients and servers, the only protocol change + is to the way in which cross-realm ticket granting tickets (TGTs) + are encrypted; as these tickets are opaque to clients and servers, + the only change visible to them will be the increased size of the + tickets. + + Cross-realm TGTs are granted by a local KDC to authenticate a user + to a remote KDC's ticket granting service. In standard Kerberos, + they are encrypted using a shared secret key manually configured + into each KDC. + + In order to incorporate public key cryptography, we define a new + encryption type, "ENCTYPE_PK_CROSS". Operationally, this encryption + type transforms an OCTET STRING of plaintext (normally an EncTktPart) + into the following SEQUENCE: + + PKCrossOutput ::= SEQUENCE { + certificate [0] OCTET STRING OPTIONAL, + -- public key certificate + -- of local KDC + encSharedKey [1] EncryptedData, + -- of type EncryptionKey + -- containing random symmetric key + -- encrypted using public key + -- of remote KDC + sigSharedKey [2] Signature, + -- of encSharedKey + -- using signature key + -- of local KDC + pkEncData [3] EncryptedData, + -- (normally) of type EncTktPart + -- encrypted using encryption key + -- found in encSharedKey + } + + PKCROSS operates as follows: when a client submits a request for + cross-realm authentication, the local KDC checks to see if it has + a long-term shared key established for that realm. If so, it uses + this key as per RFC 1510. + + If not, it sends a request for information to the remote KDC. The + content of this message is immaterial, as it does not need to be + processed by the remote KDC; for the sake of consistency, we define + it as follows: + + RemoteRequest ::= [APPLICATION 41] SEQUENCE { + nonce [0] INTEGER + } + + The remote KDC replies with a list of all trusted certifiers and + all its (the remote KDC's) certificates. We note that this response + is universal and does not depend on which KDC makes the request: + + RemoteReply ::= [APPLICATION 42] SEQUENCE { + trustedCertifiers [0] SEQUENCE OF PrincipalName, + certificates[1] SEQUENCE OF Certificate, + encTypeToUse [1] SEQUENCE OF INTEGER + -- encryption types usable + -- for encrypting pkEncData + } + + Certificate ::= SEQUENCE { + CertType [0] INTEGER, + -- type of certificate + -- 1 = X.509v3 (DER encoding) + -- 2 = PGP (per PGP draft) + CertData [1] OCTET STRING + -- actual certificate + -- type determined by CertType + } -- from pk-init draft + + Upon receiving this reply, the local KDC determines whether it has + a certificate the remote KDC trusts, and whether the remote KDC has + a certificate the local KDC trusts. If so, it issues a ticket + encrypted using the ENCTYPE_PK_CROSS encryption type defined above. + + +3.2. Profile Caches + + We observe that using PKCROSS as specified above requires two + private key operations: a signature generation by the local KDC and + a decryption by the remote KDC. This cost can be reduced in the + long term by judicious caching of the encSharedKey and the + sigSharedKey. + + Let us define a "profile" as the encSharedKey and sigSharedKey, in + conjunction with the associated remote realm name and decrypted + shared key (the key encrypted in the encSharedKey). + + To optimize these interactions, each KDC maintains two caches, one + for outbound profiles and one for inbound profiles. When generating + an outbound TGT for another realm, the local KDC first checks to see + if the corresponding entry exists in the outbound profile cache; if + so, it uses its contents to form the first three fields of the + PKCrossOutput; the shared key is used to encrypt the data for the + fourth field. If not, the components are generated fresh and stored + in the outbound profile cache. + + Upon receipt of the TGT, the remote realm checks its inbound profile + cache for the corresponding entry. If it exists, then it uses the + contents of the entry to decrypt the data encrypted in the pkEncData. + If not, then it goes through the full process of verifying and + extracting the shared key; if this is successful, then a new entry + is created in the inbound profile cache. + + The inbound profile cache should support multiple entries per realm, + in the event that the initiating realm is replicated. + + +4. Finding Realms Supporting PKCROSS + + If either the local realm or the destination realm does not support + PKCROSS, or both do not, the mechanism specified in Section 3 can + still be used in obtaining the desired remote TGT. + + In the reference Kerberos implementations, the default behavior is + to traverse a path up and down the realm name hierarchy, if the + two realms do not share a key. There is, however, the possibility + of using cross links--i.e., keys shared between two realms that + are non-contiguous in the realm name hierarchy--to shorten the + path, both to minimize delay and the number of intermediate realms + that need to be trusted. + + PKCROSS can be used as a way to provide cross-links even in the + absence of shared keys. If the client is aware that one or two + intermediate realms support PKCROSS, then a combination of + PKCROSS and conventional cross-realm authentication can be used + to reach the final destination realm. + + We solicit discussion on the best methods for clients and KDCs to + determine or advertise support for PKCROSS. + + +5. Message Ports + + We have not specified the port on which KDCs supporting PKCROSS + should listen to receive the request for information messages noted + above. We solicit discussion on which port should be used. We + propose to use the standard Kerberos ports (well-known 88 or 750), + but another possibility is to use a completely different port. + + We also solicit discussion on what other approaches can be taken to + obtain the information in the RemoteReply (e.g., secure DNS or some + other repository). + + +6. Expiration Date + + This Internet-Draft will expire on September 30, 1997. + + +7. Authors' Addresses + + Brian Tung + Tatyana Ryutov + Clifford Neuman + Gene Tsudik + USC/Information Sciences Institute + 4676 Admiralty Way Suite 1001 + Marina del Rey, CA 90292-6695 + Phone: +1 310 822 1511 + E-Mail: {brian, tryutov, bcn, gts}@isi.edu + + Bill Sommerfeld + Hewlett Packard + 300 Apollo Drive + Chelmsford MA 01824 + Phone: +1 508 436 4352 + E-Mail: sommerfeld@apollo.hp.com + + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + 1605 NW Sammamish Road Suite 310 + Issaquah WA 98027-5378 + Phone: +1 206 391 6000 + E-mail: {ari.medvinsky, matt.hur}@cybersafe.com diff --git a/doc/standardisation/draft-ietf-cat-kerberos-pk-init-03.txt b/doc/standardisation/draft-ietf-cat-kerberos-pk-init-03.txt new file mode 100644 index 000000000..d91c087dd --- /dev/null +++ b/doc/standardisation/draft-ietf-cat-kerberos-pk-init-03.txt @@ -0,0 +1,589 @@ + +INTERNET-DRAFT Clifford Neuman +draft-ietf-cat-kerberos-pk-init-03.txt Brian Tung +Updates: RFC 1510 ISI +expires September 30, 1997 John Wray + Digital Equipment Corporation + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + Jonathan Trostle + Novell + + + Public Key Cryptography for Initial Authentication in Kerberos + + +0. Status Of this Memo + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its + areas, and its working groups. Note that other groups may also + distribute working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six + months and may be updated, replaced, or obsoleted by other + documents at any time. It is inappropriate to use Internet-Drafts + as reference material or to cite them other than as "work in + progress." + + To learn the current status of any Internet-Draft, please check + the "1id-abstracts.txt" listing contained in the Internet-Drafts + Shadow Directories on ds.internic.net (US East Coast), + nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or + munnari.oz.au (Pacific Rim). + + The distribution of this memo is unlimited. It is filed as + draft-ietf-cat-kerberos-pk-init-03.txt, and expires September 30, + 1997. Please send comments to the authors. + + +1. Abstract + + This document defines extensions (PKINIT) to the Kerberos protocol + specification (RFC 1510 [1]) to provide a method for using public + key cryptography during initial authentication. The methods + defined specify the ways in which preauthentication data fields and + error data fields in Kerberos messages are to be used to transport + public key data. + + +2. Introduction + + The popularity of public key cryptography has produced a desire for + its support in Kerberos [2]. The advantages provided by public key + cryptography include simplified key management (from the Kerberos + perspective) and the ability to leverage existing and developing + public key certification infrastructures. + + Public key cryptography can be integrated into Kerberos in a number + of ways. One is to to associate a key pair with each realm, which + can then be used to facilitate cross-realm authentication; this is + the topic of another draft proposal. Another way is to allow users + with public key certificates to use them in initial authentication. + This is the concern of the current document. + + One of the guiding principles in the design of PKINIT is that + changes should be as minimal as possible. As a result, the basic + mechanism of PKINIT is as follows: The user sends a request to the + KDC as before, except that if that user is to use public key + cryptography in the initial authentication step, his certificate + accompanies the initial request, in the preauthentication fields. + + Upon receipt of this request, the KDC verifies the certificate and + issues a ticket granting ticket (TGT) as before, except that instead + of being encrypted in the user's long-term key (which is derived + from a password), it is encrypted in a randomly-generated key. This + random key is in turn encrypted using the public key certificate + that came with the request and signed using the KDC's signature key, + and accompanies the reply, in the preauthentication fields. + + PKINIT also allows for users with only digital signature keys to + authenticate using those keys, and for users to store and retrieve + private keys on the KDC. + + The PKINIT specification may also be used for direct peer to peer + authentication without contacting a central KDC. This application + of PKINIT is described in PKTAPP [4] and is based on concepts + introduced in [5, 6]. For direct client-to-server authentication, + the client uses PKINIT to authenticate to the end server (instead + of a central KDC), which then issues a ticket for itself. This + approach has an advantage over SSL [7] in that the server does not + need to save state (cache session keys). Furthermore, an + additional benefit is that Kerberos tickets can facilitate + delegation (see [8]). + + +3. Proposed Extensions + + This section describes extensions to RFC 1510 for supporting the + use of public key cryptography in the initial request for a ticket + granting ticket (TGT). + + In summary, the following changes to RFC 1510 are proposed: + + --> Users may authenticate using either a public key pair or a + conventional (symmetric) key. If public key cryptography is + used, public key data is transported in preauthentication + data fields to help establish identity. + --> Users may store private keys on the KDC for retrieval during + Kerberos initial authentication. + + This proposal addresses two ways that users may use public key + cryptography for initial authentication. Users may present public + key certificates, or they may generate their own session key, + signed by their digital signature key. In either case, the end + result is that the user obtains an ordinary TGT that may be used for + subsequent authentication, with such authentication using only + conventional cryptography. + + Section 3.1 provides definitions to help specify message formats. + Section 3.2 and 3.3 describe the extensions for the two initial + authentication methods. Section 3.3 describes a way for the user to + store and retrieve his private key on the KDC. + + +3.1. Definitions + + Hash and encryption types will be specified using ENCTYPE tags; we + propose the addition of the following types: + + #define ENCTYPE_SIGN_DSA_GENERATE 0x0011 + #define ENCTYPE_SIGN_DSA_VERIFY 0x0012 + #define ENCTYPE_ENCRYPT_RSA_PRIV 0x0021 + #define ENCTYPE_ENCRYPT_RSA_PUB 0x0022 + + allowing further signature types to be defined in the range 0x0011 + through 0x001f, and further encryption types to be defined in the + range 0x0021 through 0x002f. + + The extensions involve new preauthentication fields. The + preauthentication data types are in the range 17 through 21. + These values are also specified along with their corresponding + ASN.1 definition. + + #define PA-PK-AS-REQ 17 + #define PA-PK-AS-REP 18 + #define PA-PK-AS-SIGN 19 + #define PA-PK-KEY-REQ 20 + #define PA-PK-KEY-REP 21 + + The extensions also involve new error types. The new error types + are in the range 227 through 229. They are: + + #define KDC_ERROR_CLIENT_NOT_TRUSTED 227 + #define KDC_ERROR_KDC_NOT_TRUSTED 228 + #define KDC_ERROR_INVALID_SIG 229 + + In the exposition below, we use the following terms: encryption key, + decryption key, signature key, verification key. It should be + understood that encryption and verification keys are essentially + public keys, and decryption and signature keys are essentially + private keys. The fact that they are logically distinct does + not preclude the assignment of bitwise identical keys. + + +3.2. Standard Public Key Authentication + + Implementation of the changes in this section is REQUIRED for + compliance with pk-init. + + It is assumed that all public keys are signed by some certification + authority (CA). The initial authentication request is sent as per + RFC 1510, except that a preauthentication field containing data + signed by the user's signature key accompanies the request: + + PA-PK-AS-REQ ::- SEQUENCE { + -- PA TYPE 17 + signedPKAuth [0] SignedPKAuthenticator, + userCert [1] SEQUENCE OF Certificate OPTIONAL, + -- the user's certificate + -- optionally followed by that + -- certificate's certifier chain + trustedCertifiers [2] SEQUENCE OF PrincipalName OPTIONAL + -- CAs that the client trusts + } + + SignedPKAuthenticator ::= SEQUENCE { + pkAuth [0] PKAuthenticator, + pkAuthSig [1] Signature, + -- of pkAuth + -- using user's signature key + } + + PKAuthenticator ::= SEQUENCE { + cusec [0] INTEGER, + -- for replay prevention + ctime [1] KerberosTime, + -- for replay prevention + nonce [2] INTEGER, + -- binds response to this request + kdcName [3] PrincipalName, + clientPubValue [4] SubjectPublicKeyInfo OPTIONAL, + -- for Diffie-Hellman algorithm + } + + Signature ::= SEQUENCE { + signedHash [0] EncryptedData + -- of type Checksum + -- encrypted under signature key + } + + Checksum ::= SEQUENCE { + cksumtype [0] INTEGER, + checksum [1] OCTET STRING + } -- as specified by RFC 1510 + + SubjectPublicKeyInfo ::= SEQUENCE { + algorithm [0] algorithmIdentifier, + subjectPublicKey [1] BIT STRING + } -- as specified by the X.509 recommendation [9] + + Certificate ::= SEQUENCE { + CertType [0] INTEGER, + -- type of certificate + -- 1 = X.509v3 (DER encoding) + -- 2 = PGP (per PGP draft) + CertData [1] OCTET STRING + -- actual certificate + -- type determined by CertType + } + + Note: If the signature uses RSA keys, then it is to be performed + as per PKCS #1. + + The PKAuthenticator carries information to foil replay attacks, + to bind the request and response, and to optionally pass the + client's Diffie-Hellman public value (i.e. for using DSA in + combination with Diffie-Hellman). The PKAuthenticator is signed + with the private key corresponding to the public key in the + certificate found in userCert (or cached by the KDC). + + In the PKAuthenticator, the client may specify the KDC name in one + of two ways: 1) a Kerberos principal name, or 2) the name in the + KDC's certificate (e.g., an X.500 name, or a PGP name). Note that + case #1 requires that the certificate name and the Kerberos principal + name be bound together (e.g., via an X.509v3 extension). + + The userCert field is a sequence of certificates, the first of which + must be the user's public key certificate. Any subsequent + certificates will be certificates of the certifiers of the user's + certificate. These cerificates may be used by the KDC to verify the + user's public key. This field is empty if the KDC already has the + user's certifcate. + + The trustedCertifiers field contains a list of certification + authorities trusted by the client, in the case that the client does + not possess the KDC's public key certificate. + + Upon receipt of the AS_REQ with PA-PK-AS-REQ pre-authentication + type, the KDC attempts to verify the user's certificate chain + (userCert), if one is provided in the request. This is done by + verifying the certification path against the KDC's policy of + legitimate certifiers. This may be based on a certification + hierarchy, or it may be simply a list of recognized certifiers in a + system like PGP. If the certification path does not match one of + the KDC's trusted certifiers, the KDC sends back an error message of + type KDC_ERROR_CLIENT_NOT_TRUSTED, and it includes in the error data + field a list of its own trusted certifiers, upon which the client + resends the request. + + If trustedCertifiers is provided in the PA-PK-AS-REQ, the KDC + verifies that it has a certificate issued by one of the certifiers + trusted by the client. If it does not have a suitable certificate, + the KDC returns an error message of type KDC_ERROR_KDC_NOT_TRUSTED + to the client. + + If a trust relationship exists, the KDC then verifies the client's + signature on PKAuthenticator. If that fails, the KDC returns an + error message of type KDC_ERROR_INVALID_SIG. Otherwise, the KDC + uses the timestamp in the PKAuthenticator to assure that the request + is not a replay. The KDC also verifies that its name is specified + in PKAuthenticator. + + Assuming no errors, the KDC replies as per RFC 1510, except that it + encrypts the reply not with the user's key, but with a random key + generated only for this particular response. This random key + is sealed in the preauthentication field: + + PA-PK-AS-REP ::= SEQUENCE { + -- PA TYPE 18 + kdcCert [0] SEQUENCE OF Certificate OPTIONAL, + -- the KDC's certificate + -- optionally followed by that + -- certificate's certifier chain + encPaReply [1] EncryptedData, + -- of type PaReply + -- using either the client public + -- key or the Diffie-Hellman key + -- specified by SignedDHPublicValue + signedDHPublicValue [2] SignedDHPublicValue OPTIONAL + } + + + PaReply ::= SEQUENCE { + replyEncKeyPack [0] ReplyEncKeyPack, + replyEncKeyPackSig [1] Signature, + -- of replyEncKeyPack + -- using KDC's signature key + } + + ReplyEncKeyPack ::= SEQUENCE { + replyEncKey [0] EncryptionKey, + -- used to encrypt main reply + nonce [1] INTEGER + -- binds response to the request + -- passed in the PKAuthenticator + } + + SignedDHPublicValue ::= SEQUENCE { + dhPublicValue [0] SubjectPublicKeyInfo, + dhPublicValueSig [1] Signature + -- of dhPublicValue + -- using KDC's signature key + } + + The kdcCert field is a sequence of certificates, the first of which + must have as its root certifier one of the certifiers sent to the + KDC in the PA-PK-AS-REQ. Any subsequent certificates will be + certificates of the certifiers of the KDC's certificate. These + cerificates may be used by the client to verify the KDC's public + key. This field is empty if the client did not send to the KDC a + list of trusted certifiers (the trustedCertifiers field was empty). + + Since each certifier in the certification path of a user's + certificate is essentially a separate realm, the name of each + certifier shall be added to the transited field of the ticket. The + format of these realm names shall follow the naming constraints set + forth in RFC 1510 (sections 7.1 and 3.3.3.1). Note that this will + require new nametypes to be defined for PGP certifiers and other + types of realms as they arise. + + The KDC's certificate must bind the public key to a name derivable + from the name of the realm for that KDC. The client then extracts + the random key used to encrypt the main reply. This random key (in + encPaReply) is encrypted with either the client's public key or + with a key derived from the DH values exchanged between the client + and the KDC. + + +3.3. Digital Signature + + Implementation of the changes in this section are OPTIONAL for + compliance with pk-init. + + We offer this option with the warning that it requires the client to + generate a random key; the client may not be able to guarantee the + same level of randomness as the KDC. + + If the user registered a digital signature key with the KDC instead + of an encryption key, then a separate exchange must be used. The + client sends a request for a TGT as usual, except that it (rather + than the KDC) generates the random key that will be used to encrypt + the KDC response. This key is sent to the KDC along with the + request in a preauthentication field: + + PA-PK-AS-SIGN ::= SEQUENCE { + -- PA TYPE 19 + encSignedKeyPack [0] EncryptedData + -- of SignedKeyPack + -- using the KDC's public key + } + + SignedKeyPack ::= SEQUENCE { + signedKey [0] KeyPack, + signedKeyAuth [1] PKAuthenticator, + signedKeySig [2] Signature + -- of signedKey.signedKeyAuth + -- using user's signature key + } + + KeyPack ::= SEQUENCE { + randomKey [0] EncryptionKey, + -- will be used to encrypt reply + nonce [1] INTEGER + } + + where the nonce is copied from the request. + + Upon receipt of the PA-PK-AS-SIGN, the KDC decrypts then verifies + the randomKey. It then replies as per RFC 1510, except that the + reply is encrypted not with a password-derived user key, but with + the randomKey sent in the request. Since the client already knows + this key, there is no need to accompany the reply with an extra + preauthentication field. The transited field of the ticket should + specify the certification path as described in Section 3.2. + + +3.4. Retrieving the Private Key From the KDC + + Implementation of the changes in this section is RECOMMENDED for + compliance with pk-init. + + When the user's private key is not stored local to the user, he may + choose to store the private key (normally encrypted using a + password-derived key) on the KDC. We provide this option to present + the user with an alternative to storing the private key on local + disk at each machine where he expects to authenticate himself using + pk-init. It should be noted that it replaces the added risk of + long-term storage of the private key on possibly many workstations + with the added risk of storing the private key on the KDC in a + form vulnerable to brute-force attack. + + In order to obtain a private key, the client includes a + preauthentication field with the AS-REQ message: + + PA-PK-KEY-REQ ::= SEQUENCE { + -- PA TYPE 20 + patimestamp [0] KerberosTime OPTIONAL, + -- used to address replay attacks. + pausec [1] INTEGER OPTIONAL, + -- used to address replay attacks. + nonce [2] INTEGER, + -- binds the reply to this request + privkeyID [3] SEQUENCE OF KeyID OPTIONAL + -- constructed as a hash of + -- public key corresponding to + -- desired private key + } + + KeyID ::= SEQUENCE { + KeyIdentifier [0] OCTET STRING + } + + The client may request a specific private key by sending the + corresponding ID. If this field is left empty, then all + private keys are returned. + + If all checks out, the KDC responds as described in the above + sections, except that an additional preauthentication field, + containing the user's private key, accompanies the reply: + + PA-PK-KEY-REP ::= SEQUENCE { + -- PA TYPE 21 + nonce [0] INTEGER, + -- binds the reply to the request + KeyData [1] SEQUENCE OF KeyPair + } + + KeyPair ::= SEQUENCE { + privKeyID [0] OCTET STRING, + -- corresponding to encPrivKey + encPrivKey [1] OCTET STRING + } + + +3.4.1. Additional Protection of Retrieved Private Keys + + We solicit discussion on the following proposal: that the client may + optionally include in its request additional data to encrypt the + private key, which is currently only protected by the user's + password. One possibility is that the client might generate a + random string of bits, encrypt it with the public key of the KDC (as + in the SignedKeyPack, but with an ordinary OCTET STRING in place of + an EncryptionKey), and include this with the request. The KDC then + XORs each returned key with this random bit string. (If the bit + string is too short, the KDC could either return an error, or XOR + the returned key with a repetition of the bit string.) + + In order to make this work, additional means of preauthentication + need to be devised in order to prevent attackers from simply + inserting their own bit string. One way to do this is to store + a hash of the password-derived key (the one used to encrypt the + private key). This hash is then used in turn to derive a second + key (called the hash-key); the hash-key is used to encrypt an ASN.1 + structure containing the generated bit string and a nonce value + that binds it to the request. + + Since the KDC possesses the hash, it can generate the hash-key and + verify this (weaker) preauthentication, and yet cannot reproduce + the private key itself, since the hash is a one-way function. + + +4. Logistics and Policy Issues + + We solicit discussion on how clients and KDCs should be configured + in order to determine which of the options described above (if any) + should be used. One possibility is to set the user's database + record to indicate that authentication is to use public key + cryptography; this will not work, however, in the event that the + client needs to know before making the initial request. + +5. Compatibility with One-Time Passcodes + + We solicit discussion on how the protocol changes proposed in this + draft will interact with the proposed use of one-time passcodes + discussed in draft-ietf-cat-kerberos-passwords-00.txt. + + +6. Strength of Cryptographic Schemes + + In light of recent findings on the strength of MD5 and DES, + we solicit discussion on which encryption types to incorporate + into the protocol changes. + + +7. Bibliography + + [1] J. Kohl, C. Neuman. The Kerberos Network Authentication + Service (V5). Request for Comments: 1510 + + [2] B.C. Neuman, Theodore Ts'o. Kerberos: An Authentication Service + for Computer Networks, IEEE Communications, 32(9):33-38. + September 1994. + + [3] A. Medvinsky, M. Hur. Addition of Kerberos Cipher Suites to + Transport Layer Security (TLS). + draft-ietf-tls-kerb-cipher-suites-00.txt + + [4] A. Medvinsky, M. Hur, B. Clifford Neuman. Public Key Utilizing + Tickets for Application Servers (PKTAPP). + draft-ietf-cat-pktapp-00.txt + + [5] M. Sirbu, J. Chuang. Distributed Authentication in Kerberos Using + Public Key Cryptography. Symposium On Network and Distributed System + Security, 1997. + + [6] B. Cox, J.D. Tygar, M. Sirbu. NetBill Security and Transaction + Protocol. In Proceedings of the USENIX Workshop on Electronic Commerce, + July 1995. + + [7] Alan O. Freier, Philip Karlton and Paul C. Kocher. + The SSL Protocol, Version 3.0 - IETF Draft. + + [8] B.C. Neuman, Proxy-Based Authorization and Accounting for + Distributed Systems. In Proceedings of the 13th International + Conference on Distributed Computing Systems, May 1993 + + [9] ITU-T (formerly CCITT) + Information technology - Open Systems Interconnection - + The Directory: Authentication Framework Recommendation X.509 + ISO/IEC 9594-8 + + +8. Acknowledgements + + Some of the ideas on which this proposal is based arose during + discussions over several years between members of the SAAG, the IETF + CAT working group, and the PSRG, regarding integration of Kerberos + and SPX. Some ideas have also been drawn from the DASS system. + These changes are by no means endorsed by these groups. This is an + attempt to revive some of the goals of those groups, and this + proposal approaches those goals primarily from the Kerberos + perspective. Lastly, comments from groups working on similar ideas + in DCE have been invaluable. + + +9. Expiration Date + + This draft expires September 30, 1997. + + +10. Authors + + Clifford Neuman + Brian Tung + USC Information Sciences Institute + 4676 Admiralty Way Suite 1001 + Marina del Rey CA 90292-6695 + Phone: +1 310 822 1511 + E-mail: {bcn, brian}@isi.edu + + John Wray + Digital Equipment Corporation + 550 King Street, LKG2-2/Z7 + Littleton, MA 01460 + Phone: +1 508 486 5210 + E-mail: wray@tuxedo.enet.dec.com + + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + 1605 NW Sammamish Road Suite 310 + Issaquah WA 98027-5378 + Phone: +1 206 391 6000 + E-mail: {ari.medvinsky, matt.hur}@cybersafe.com + + Jonathan Trostle + Novell + E-mail: jonathan.trostle@novell.com diff --git a/doc/standardisation/rfc1508.txt b/doc/standardisation/rfc1508.txt new file mode 100644 index 000000000..132b855e0 --- /dev/null +++ b/doc/standardisation/rfc1508.txt @@ -0,0 +1,2747 @@ + + + + + + +Network Working Group J. Linn +Request for Comments: 1508 Geer Zolot Associates + September 1993 + + + Generic Security Service Application Program Interface + +Status of this Memo + + This RFC specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" for the standardization state and status + of this protocol. Distribution of this memo is unlimited. + +Abstract + + This Generic Security Service Application Program Interface (GSS-API) + definition provides security services to callers in a generic + fashion, supportable with a range of underlying mechanisms and + technologies and hence allowing source-level portability of + applications to different environments. This specification defines + GSS-API services and primitives at a level independent of underlying + mechanism and programming language environment, and is to be + complemented by other, related specifications: + + documents defining specific parameter bindings for particular + language environments + + documents defining token formats, protocols, and procedures to + be implemented in order to realize GSS-API services atop + particular security mechanisms + +Table of Contents + + 1. GSS-API Characteristics and Concepts ....................... 2 + 1.1. GSS-API Constructs ....................................... 5 + 1.1.1. Credentials ........................................... 5 + 1.1.2. Tokens ................................................ 6 + 1.1.3. Security Contexts ..................................... 7 + 1.1.4. Mechanism Types ....................................... 8 + 1.1.5. Naming ................................................ 9 + 1.1.6. Channel Bindings ...................................... 10 + 1.2. GSS-API Features and Issues ............................. 11 + 1.2.1. Status Reporting ...................................... 11 + 1.2.2. Per-Message Security Service Availability ............. 12 + 1.2.3. Per-Message Replay Detection and Sequencing ........... 13 + 1.2.4. Quality of Protection ................................. 15 + + + +Linn [Page 1] + +RFC 1508 Generic Security Interface September 1993 + + + 2. Interface Descriptions ..................................... 15 + 2.1. Credential management calls ............................. 17 + 2.1.1. GSS_Acquire_cred call ................................. 17 + 2.1.2. GSS_Release_cred call ................................. 19 + 2.1.3. GSS_Inquire_cred call ................................. 20 + 2.2. Context-level calls ..................................... 21 + 2.2.1. GSS_Init_sec_context call ............................. 21 + 2.2.2. GSS_Accept_sec_context call ........................... 26 + 2.2.3. GSS_Delete_sec_context call ........................... 29 + 2.2.4. GSS_Process_context_token call ........................ 30 + 2.2.5. GSS_Context_time call ................................. 31 + 2.3. Per-message calls ....................................... 32 + 2.3.1. GSS_Sign call ......................................... 32 + 2.3.2. GSS_Verify call ....................................... 33 + 2.3.3. GSS_Seal call ......................................... 35 + 2.3.4. GSS_Unseal call ....................................... 36 + 2.4. Support calls ........................................... 37 + 2.4.1. GSS_Display_status call ............................... 37 + 2.4.2. GSS_Indicate_mechs call ............................... 38 + 2.4.3. GSS_Compare_name call ................................. 38 + 2.4.4. GSS_Display_name call ................................. 39 + 2.4.5. GSS_Import_name call .................................. 40 + 2.4.6. GSS_Release_name call ................................. 41 + 2.4.7. GSS_Release_buffer call ............................... 41 + 2.4.8. GSS_Release_oid_set call .............................. 42 + 3. Mechanism-Specific Example Scenarios ....................... 42 + 3.1. Kerberos V5, single-TGT ................................. 43 + 3.2. Kerberos V5, double-TGT ................................. 43 + 3.3. X.509 Authentication Framework .......................... 44 + 4. Related Activities ......................................... 45 + 5. Acknowledgments ............................................ 46 + 6. Security Considerations .................................... 46 + 7. Author's Address ........................................... 46 + Appendix A .................................................... 47 + Appendix B .................................................... 48 + Appendix C .................................................... 49 + +1. GSS-API Characteristics and Concepts + + The operational paradigm in which GSS-API operates is as follows. A + typical GSS-API caller is itself a communications protocol, calling + on GSS-API in order to protect its communications with + authentication, integrity, and/or confidentiality security services. + A GSS-API caller accepts tokens provided to it by its local GSS-API + implementation and transfers the tokens to a peer on a remote system; + that peer passes the received tokens to its local GSS-API + implementation for processing. The security services available + through GSS-API in this fashion are implementable (and have been + + + +Linn [Page 2] + +RFC 1508 Generic Security Interface September 1993 + + + implemented) over a range of underlying mechanisms based on secret- + key and public-key cryptographic technologies. + + The GSS-API separates the operations of initializing a security + context between peers, achieving peer entity authentication (This + security service definition, and other definitions used in this + document, corresponds to that provided in International Standard ISO + 7498-2-1988(E), Security Architecture.) (GSS_Init_sec_context() and + GSS_Accept_sec_context() calls), from the operations of providing + per-message data origin authentication and data integrity protection + (GSS_Sign() and GSS_Verify() calls) for messages subsequently + transferred in conjunction with that context. Per-message GSS_Seal() + and GSS_Unseal() calls provide the data origin authentication and + data integrity services which GSS_Sign() and GSS_Verify() offer, and + also support selection of confidentiality services as a caller + option. Additional calls provide supportive functions to the GSS- + API's users. + + The following paragraphs provide an example illustrating the + dataflows involved in use of the GSS-API by a client and server in a + mechanism-independent fashion, establishing a security context and + transferring a protected message. The example assumes that credential + acquisition has already been completed. The example assumes that the + underlying authentication technology is capable of authenticating a + client to a server using elements carried within a single token, and + of authenticating the server to the client (mutual authentication) + with a single returned token; this assumption holds for presently- + documented CAT mechanisms but is not necessarily true for other + cryptographic technologies and associated protocols. + + The client calls GSS_Init_sec_context() to establish a security + context to the server identified by targ_name, and elects to set the + mutual_req_flag so that mutual authentication is performed in the + course of context establishment. GSS_Init_sec_context() returns an + output_token to be passed to the server, and indicates + GSS_CONTINUE_NEEDED status pending completion of the mutual + authentication sequence. Had mutual_req_flag not been set, the + initial call to GSS_Init_sec_context() would have returned + GSS_COMPLETE status. The client sends the output_token to the server. + + The server passes the received token as the input_token parameter to + GSS_Accept_sec_context(). GSS_Accept_sec_context indicates + GSS_COMPLETE status, provides the client's authenticated identity in + the src_name result, and provides an output_token to be passed to the + client. The server sends the output_token to the client. + + The client passes the received token as the input_token parameter to + a successor call to GSS_Init_sec_context(), which processes data + + + +Linn [Page 3] + +RFC 1508 Generic Security Interface September 1993 + + + included in the token in order to achieve mutual authentication from + the client's viewpoint. This call to GSS_Init_sec_context() returns + GSS_COMPLETE status, indicating successful mutual authentication and + the completion of context establishment for this example. + + The client generates a data message and passes it to GSS_Seal(). + GSS_Seal() performs data origin authentication, data integrity, and + (optionally) confidentiality processing on the message and + encapsulates the result into output_message, indicating GSS_COMPLETE + status. The client sends the output_message to the server. + + The server passes the received message to GSS_Unseal(). GSS_Unseal + inverts the encapsulation performed by GSS_Seal(), deciphers the + message if the optional confidentiality feature was applied, and + validates the data origin authentication and data integrity checking + quantities. GSS_Unseal() indicates successful validation by + returning GSS_COMPLETE status along with the resultant + output_message. + + For purposes of this example, we assume that the server knows by + out-of-band means that this context will have no further use after + one protected message is transferred from client to server. Given + this premise, the server now calls GSS_Delete_sec_context() to flush + context-level information. GSS_Delete_sec_context() returns a + context_token for the server to pass to the client. + + The client passes the returned context_token to + GSS_Process_context_token(), which returns GSS_COMPLETE status after + deleting context-level information at the client system. + + The GSS-API design assumes and addresses several basic goals, + including: + + Mechanism independence: The GSS-API defines an interface to + cryptographically implemented strong authentication and other + security services at a generic level which is independent of + particular underlying mechanisms. For example, GSS-API-provided + services can be implemented by secret-key technologies (e.g., + Kerberos) or public-key approaches (e.g., X.509). + + Protocol environment independence: The GSS-API is independent of + the communications protocol suites with which it is employed, + permitting use in a broad range of protocol environments. In + appropriate environments, an intermediate implementation "veneer" + which is oriented to a particular communication protocol (e.g., + Remote Procedure Call (RPC)) may be interposed between + applications which call that protocol and the GSS-API, thereby + invoking GSS-API facilities in conjunction with that protocol's + + + +Linn [Page 4] + +RFC 1508 Generic Security Interface September 1993 + + + communications invocations. + + Protocol association independence: The GSS-API's security context + construct is independent of communications protocol association + constructs. This characteristic allows a single GSS-API + implementation to be utilized by a variety of invoking protocol + modules on behalf of those modules' calling applications. GSS-API + services can also be invoked directly by applications, wholly + independent of protocol associations. + + Suitability to a range of implementation placements: GSS-API + clients are not constrained to reside within any Trusted Computing + Base (TCB) perimeter defined on a system where the GSS-API is + implemented; security services are specified in a manner suitable + to both intra-TCB and extra-TCB callers. + +1.1. GSS-API Constructs + + This section describes the basic elements comprising the GSS-API. + +1.1.1. Credentials + + Credentials structures provide the prerequisites enabling peers to + establish security contexts with each other. A caller may designate + that its default credential be used for context establishment calls + without presenting an explicit handle to that credential. + Alternately, those GSS-API callers which need to make explicit + selection of particular credentials structures may make references to + those credentials through GSS-API-provided credential handles + ("cred_handles"). + + A single credential structure may be used for initiation of outbound + contexts and acceptance of inbound contexts. Callers needing to + operate in only one of these modes may designate this fact when + credentials are acquired for use, allowing underlying mechanisms to + optimize their processing and storage requirements. The credential + elements defined by a particular mechanism may contain multiple + cryptographic keys, e.g., to enable authentication and message + encryption to be performed with different algorithms. + + A single credential structure may accommodate credential information + associated with multiple underlying mechanisms (mech_types); a + credential structure's contents will vary depending on the set of + mech_types supported by a particular GSS-API implementation. + Commonly, a single mech_type will be used for all security contexts + established by a particular initiator to a particular target; the + primary motivation for supporting credential sets representing + multiple mech_types is to allow initiators on systems which are + + + +Linn [Page 5] + +RFC 1508 Generic Security Interface September 1993 + + + equipped to handle multiple types to initiate contexts to targets on + other systems which can accommodate only a subset of the set + supported at the initiator's system. + + It is the responsibility of underlying system-specific mechanisms and + OS functions below the GSS-API to ensure that the ability to acquire + and use credentials associated with a given identity is constrained + to appropriate processes within a system. This responsibility should + be taken seriously by implementors, as the ability for an entity to + utilize a principal's credentials is equivalent to the entity's + ability to successfully assert that principal's identity. + + Once a set of GSS-API credentials is established, the transferability + of that credentials set to other processes or analogous constructs + within a system is a local matter, not defined by the GSS-API. An + example local policy would be one in which any credentials received + as a result of login to a given user account, or of delegation of + rights to that account, are accessible by, or transferable to, + processes running under that account. + + The credential establishment process (particularly when performed on + behalf of users rather than server processes) is likely to require + access to passwords or other quantities which should be protected + locally and exposed for the shortest time possible. As a result, it + will often be appropriate for preliminary credential establishment to + be performed through local means at user login time, with the + result(s) cached for subsequent reference. These preliminary + credentials would be set aside (in a system-specific fashion) for + subsequent use, either: + + to be accessed by an invocation of the GSS-API GSS_Acquire_cred() + call, returning an explicit handle to reference that credential + + as the default credentials installed on behalf of a process + +1.1.2. Tokens + + Tokens are data elements transferred between GSS-API callers, and are + divided into two classes. Context-level tokens are exchanged in order + to establish and manage a security context between peers. Per-message + tokens are exchanged in conjunction with an established context to + provide protective security services for corresponding data messages. + The internal contents of both classes of tokens are specific to the + particular underlying mechanism used to support the GSS-API; Appendix + B of this document provides a uniform recommendation for designers of + GSS-API support mechanisms, encapsulating mechanism-specific + information along with a globally-interpretable mechanism identifier. + + + + +Linn [Page 6] + +RFC 1508 Generic Security Interface September 1993 + + + Tokens are opaque from the viewpoint of GSS-API callers. They are + generated within the GSS-API implementation at an end system, + provided to a GSS-API caller to be transferred to the peer GSS-API + caller at a remote end system, and processed by the GSS-API + implementation at that remote end system. Tokens may be output by + GSS-API primitives (and are to be transferred to GSS-API peers) + independent of the status indications which those primitives + indicate. Token transfer may take place in an in-band manner, + integrated into the same protocol stream used by the GSS-API callers + for other data transfers, or in an out-of-band manner across a + logically separate channel. + + Development of GSS-API support primitives based on a particular + underlying cryptographic technique and protocol does not necessarily + imply that GSS-API callers invoking that GSS-API mechanism type will + be able to interoperate with peers invoking the same technique and + protocol outside the GSS-API paradigm. For example, the format of + GSS-API tokens defined in conjunction with a particular mechanism, + and the techniques used to integrate those tokens into callers' + protocols, may not be the same as those used by non-GSS-API callers + of the same underlying technique. + +1.1.3. Security Contexts + + Security contexts are established between peers, using credentials + established locally in conjunction with each peer or received by + peers via delegation. Multiple contexts may exist simultaneously + between a pair of peers, using the same or different sets of + credentials. Coexistence of multiple contexts using different + credentials allows graceful rollover when credentials expire. + Distinction among multiple contexts based on the same credentials + serves applications by distinguishing different message streams in a + security sense. + + The GSS-API is independent of underlying protocols and addressing + structure, and depends on its callers to transport GSS-API-provided + data elements. As a result of these factors, it is a caller + responsibility to parse communicated messages, separating GSS-API- + related data elements from caller-provided data. The GSS-API is + independent of connection vs. connectionless orientation of the + underlying communications service. + + No correlation between security context and communications protocol + association is dictated. (The optional channel binding facility, + discussed in Section 1.1.6 of this document, represents an + intentional exception to this rule, supporting additional protection + features within GSS-API supporting mechanisms.) This separation + allows the GSS-API to be used in a wide range of communications + + + +Linn [Page 7] + +RFC 1508 Generic Security Interface September 1993 + + + environments, and also simplifies the calling sequences of the + individual calls. In many cases (depending on underlying security + protocol, associated mechanism, and availability of cached + information), the state information required for context setup can be + sent concurrently with initial signed user data, without interposing + additional message exchanges. + +1.1.4. Mechanism Types + + In order to successfully establish a security context with a target + peer, it is necessary to identify an appropriate underlying mechanism + type (mech_type) which both initiator and target peers support. The + definition of a mechanism embodies not only the use of a particular + cryptographic technology (or a hybrid or choice among alternative + cryptographic technologies), but also definition of the syntax and + semantics of data element exchanges which that mechanism will employ + in order to support security services. + + It is recommended that callers initiating contexts specify the + "default" mech_type value, allowing system-specific functions within + or invoked by the GSS-API implementation to select the appropriate + mech_type, but callers may direct that a particular mech_type be + employed when necessary. + + The means for identifying a shared mech_type to establish a security + context with a peer will vary in different environments and + circumstances; examples include (but are not limited to): + + use of a fixed mech_type, defined by configuration, within an + environment + + syntactic convention on a target-specific basis, through + examination of a target's name + + lookup of a target's name in a naming service or other database in + order to identify mech_types supported by that target + + explicit negotiation between GSS-API callers in advance of + security context setup + + When transferred between GSS-API peers, mech_type specifiers (per + Appendix B, represented as Object Identifiers (OIDs)) serve to + qualify the interpretation of associated tokens. (The structure and + encoding of Object Identifiers is defined in ISO/IEC 8824, + "Specification of Abstract Syntax Notation One (ASN.1)" and in + ISO/IEC 8825, "Specification of Basic Encoding Rules for Abstract + Syntax Notation One (ASN.1)".) Use of hierarchically structured OIDs + serves to preclude ambiguous interpretation of mech_type specifiers. + + + +Linn [Page 8] + +RFC 1508 Generic Security Interface September 1993 + + + The OID representing the DASS MechType, for example, is + 1.3.12.2.1011.7.5. + +1.1.5. Naming + + The GSS-API avoids prescription of naming structures, treating the + names transferred across the interface in order to initiate and + accept security contexts as opaque octet string quantities. This + approach supports the GSS-API's goal of implementability atop a range + of underlying security mechanisms, recognizing the fact that + different mechanisms process and authenticate names which are + presented in different forms. Generalized services offering + translation functions among arbitrary sets of naming environments are + outside the scope of the GSS-API; availability and use of local + conversion functions to translate among the naming formats supported + within a given end system is anticipated. + + Two distinct classes of name representations are used in conjunction + with different GSS-API parameters: + + a printable form (denoted by OCTET STRING), for acceptance from + and presentation to users; printable name forms are accompanied by + OID tags identifying the namespace to which they correspond + + an internal form (denoted by INTERNAL NAME), opaque to callers and + defined by individual GSS-API implementations; GSS-API + implementations supporting multiple namespace types are + responsible for maintaining internal tags to disambiguate the + interpretation of particular names + + Tagging of printable names allows GSS-API callers and underlying + GSS-API mechanisms to disambiguate name types and to determine + whether an associated name's type is one which they are capable of + processing, avoiding aliasing problems which could result from + misinterpreting a name of one type as a name of another type. + + In addition to providing means for names to be tagged with types, + this specification defines primitives to support a level of naming + environment independence for certain calling applications. To provide + basic services oriented towards the requirements of callers which + need not themselves interpret the internal syntax and semantics of + names, GSS-API calls for name comparison (GSS_Compare_name()), + human-readable display (GSS_Display_name()), input conversion + (GSS_Import_name()), and internal name deallocation + (GSS_Release_name()) functions are defined. (It is anticipated that + these proposed GSS-API calls will be implemented in many end systems + based on system-specific name manipulation primitives already extant + within those end systems; inclusion within the GSS-API is intended to + + + +Linn [Page 9] + +RFC 1508 Generic Security Interface September 1993 + + + offer GSS-API callers a portable means to perform specific + operations, supportive of authorization and audit requirements, on + authenticated names.) + + GSS_Import_name() implementations can, where appropriate, support + more than one printable syntax corresponding to a given namespace + (e.g., alternative printable representations for X.500 Distinguished + Names), allowing flexibility for their callers to select among + alternative representations. GSS_Display_name() implementations + output a printable syntax selected as appropriate to their + operational environments; this selection is a local matter. Callers + desiring portability across alternative printable syntaxes should + refrain from implementing comparisons based on printable name forms + and should instead use the GSS_Compare_name() call to determine + whether or not one internal-format name matches another. + +1.1.6. Channel Bindings + + The GSS-API accommodates the concept of caller-provided channel + binding ("chan_binding") information, used by GSS-API callers to bind + the establishment of a security context to relevant characteristics + (e.g., addresses, transformed representations of encryption keys) of + the underlying communications channel and of protection mechanisms + applied to that communications channel. Verification by one peer of + chan_binding information provided by the other peer to a context + serves to protect against various active attacks. The caller + initiating a security context must determine the chan_binding values + before making the GSS_Init_sec_context() call, and consistent values + must be provided by both peers to a context. Callers should not + assume that underlying mechanisms provide confidentiality protection + for channel binding information. + + Use or non-use of the GSS-API channel binding facility is a caller + option, and GSS-API supporting mechanisms can support operation in an + environment where NULL channel bindings are presented. When non-NULL + channel bindings are used, certain mechanisms will offer enhanced + security value by interpreting the bindings' content (rather than + simply representing those bindings, or signatures computed on them, + within tokens) and will therefore depend on presentation of specific + data in a defined format. To this end, agreements among mechanism + implementors are defining conventional interpretations for the + contents of channel binding arguments, including address specifiers + (with content dependent on communications protocol environment) for + context initiators and acceptors. (These conventions are being + incorporated into related documents.) In order for GSS-API callers to + be portable across multiple mechanisms and achieve the full security + functionality available from each mechanism, it is strongly + recommended that GSS-API callers provide channel bindings consistent + + + +Linn [Page 10] + +RFC 1508 Generic Security Interface September 1993 + + + with these conventions and those of the networking environment in + which they operate. + +1.2. GSS-API Features and Issues + + This section describes aspects of GSS-API operations, of the security + services which the GSS-API provides, and provides commentary on + design issues. + +1.2.1. Status Reporting + + Each GSS-API call provides two status return values. Major_status + values provide a mechanism-independent indication of call status + (e.g., GSS_COMPLETE, GSS_FAILURE, GSS_CONTINUE_NEEDED), sufficient to + drive normal control flow within the caller in a generic fashion. + Table 1 summarizes the defined major_status return codes in tabular + fashion. + + Table 1: GSS-API Major Status Codes + + FATAL ERROR CODES + + GSS_BAD_BINDINGS channel binding mismatch + GSS_BAD_MECH unsupported mechanism requested + GSS_BAD_NAME invalid name provided + GSS_BAD_NAMETYPE name of unsupported type provided + GSS_BAD_STATUS invalid input status selector + GSS_BAD_SIG token had invalid signature + GSS_CONTEXT_EXPIRED specified security context expired + GSS_CREDENTIALS_EXPIRED expired credentials detected + GSS_DEFECTIVE_CREDENTIAL defective credential detected + GSS_DEFECTIVE_TOKEN defective token detected + GSS_FAILURE failure, unspecified at GSS-API + level + GSS_NO_CONTEXT no valid security context specified + GSS_NO_CRED no valid credentials provided + + INFORMATORY STATUS CODES + + GSS_COMPLETE normal completion + GSS_CONTINUE_NEEDED continuation call to routine + required + GSS_DUPLICATE_TOKEN duplicate per-message token + detected + GSS_OLD_TOKEN timed-out per-message token + detected + GSS_UNSEQ_TOKEN out-of-order per-message token + detected + + + +Linn [Page 11] + +RFC 1508 Generic Security Interface September 1993 + + + Minor_status provides more detailed status information which may + include status codes specific to the underlying security mechanism. + Minor_status values are not specified in this document. + + GSS_CONTINUE_NEEDED major_status returns, and optional message + outputs, are provided in GSS_Init_sec_context() and + GSS_Accept_sec_context() calls so that different mechanisms' + employment of different numbers of messages within their + authentication sequences need not be reflected in separate code paths + within calling applications. Instead, such cases are accomodated with + sequences of continuation calls to GSS_Init_sec_context() and + GSS_Accept_sec_context(). The same mechanism is used to encapsulate + mutual authentication within the GSS-API's context initiation calls. + + For mech_types which require interactions with third-party servers in + order to establish a security context, GSS-API context establishment + calls may block pending completion of such third-party interactions. + On the other hand, no GSS-API calls pend on serialized interactions + with GSS-API peer entities. As a result, local GSS-API status + returns cannot reflect unpredictable or asynchronous exceptions + occurring at remote peers, and reflection of such status information + is a caller responsibility outside the GSS-API. + +1.2.2. Per-Message Security Service Availability + + When a context is established, two flags are returned to indicate the + set of per-message protection security services which will be + available on the context: + + the integ_avail flag indicates whether per-message integrity and + data origin authentication services are available + + the conf_avail flag indicates whether per-message confidentiality + services are available, and will never be returned TRUE unless the + integ_avail flag is also returned TRUE + + GSS-API callers desiring per-message security services should + check the values of these flags at context establishment time, and + must be aware that a returned FALSE value for integ_avail means + that invocation of GSS_Sign() or GSS_Seal() primitives on the + associated context will apply no cryptographic protection to user + data messages. + + The GSS-API per-message protection service primitives, as the + category name implies, are oriented to operation at the granularity + of protocol data units. They perform cryptographic operations on the + data units, transfer cryptographic control information in tokens, + and, in the case of GSS_Seal(), encapsulate the protected data unit. + + + +Linn [Page 12] + +RFC 1508 Generic Security Interface September 1993 + + + As such, these primitives are not oriented to efficient data + protection for stream-paradigm protocols (e.g., Telnet) if + cryptography must be applied on an octet-by-octet basis. + +1.2.3. Per-Message Replay Detection and Sequencing + + Certain underlying mech_types are expected to offer support for + replay detection and/or sequencing of messages transferred on the + contexts they support. These optionally-selectable protection + features are distinct from replay detection and sequencing features + applied to the context establishment operation itself; the presence + or absence of context-level replay or sequencing features is wholly a + function of the underlying mech_type's capabilities, and is not + selected or omitted as a caller option. + + The caller initiating a context provides flags (replay_det_req_flag + and sequence_req_flag) to specify whether the use of per-message + replay detection and sequencing features is desired on the context + being established. The GSS-API implementation at the initiator system + can determine whether these features are supported (and whether they + are optionally selectable) as a function of mech_type, without need + for bilateral negotiation with the target. When enabled, these + features provide recipients with indicators as a result of GSS-API + processing of incoming messages, identifying whether those messages + were detected as duplicates or out-of-sequence. Detection of such + events does not prevent a suspect message from being provided to a + recipient; the appropriate course of action on a suspect message is a + matter of caller policy. + + The semantics of the replay detection and sequencing services applied + to received messages, as visible across the interface which the GSS- + API provides to its clients, are as follows: + + When replay_det_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_COMPLETE indicates that the message was within the window + (of time or sequence space) allowing replay events to be detected, + and that the message was not a replay of a previously-processed + message within that window. + + 2. GSS_DUPLICATE_TOKEN indicates that the signature on the + received message was correct, but that the message was recognized + as a duplicate of a previously-processed message. + + 3. GSS_OLD_TOKEN indicates that the signature on the received + message was correct, but that the message is too old to be checked + for duplication. + + + +Linn [Page 13] + +RFC 1508 Generic Security Interface September 1993 + + + When sequence_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_COMPLETE indicates that the message was within the window + (of time or sequence space) allowing replay events to be detected, + and that the message was not a replay of a previously-processed + message within that window. + + 2. GSS_DUPLICATE_TOKEN indicates that the signature on the + received message was correct, but that the message was recognized + as a duplicate of a previously-processed message. + + 3. GSS_OLD_TOKEN indicates that the signature on the received + message was correct, but that the token is too old to be checked + for duplication. + + 4. GSS_UNSEQ_TOKEN indicates that the signature on the received + message was correct, but that it is earlier in a sequenced stream + than a message already processed on the context. [Note: + Mechanisms can be architected to provide a stricter form of + sequencing service, delivering particular messages to recipients + only after all predecessor messages in an ordered stream have been + delivered. This type of support is incompatible with the GSS-API + paradigm in which recipients receive all messages, whether in + order or not, and provide them (one at a time, without intra-GSS- + API message buffering) to GSS-API routines for validation. GSS- + API facilities provide supportive functions, aiding clients to + achieve strict message stream integrity in an efficient manner in + conjunction with sequencing provisions in communications + protocols, but the GSS-API does not offer this level of message + stream integrity service by itself.] + + As the message stream integrity features (especially sequencing) may + interfere with certain applications' intended communications + paradigms, and since support for such features is likely to be + resource intensive, it is highly recommended that mech_types + supporting these features allow them to be activated selectively on + initiator request when a context is established. A context initiator + and target are provided with corresponding indicators + (replay_det_state and sequence_state), signifying whether these + features are active on a given context. + + An example mech_type supporting per-message replay detection could + (when replay_det_state is TRUE) implement the feature as follows: The + underlying mechanism would insert timestamps in data elements output + by GSS_Sign() and GSS_Seal(), and would maintain (within a time- + limited window) a cache (qualified by originator-recipient pair) + identifying received data elements processed by GSS_Verify() and + + + +Linn [Page 14] + +RFC 1508 Generic Security Interface September 1993 + + + GSS_Unseal(). When this feature is active, exception status returns + (GSS_DUPLICATE_TOKEN, GSS_ OLD_TOKEN) will be provided when + GSS_Verify() or GSS_Unseal() is presented with a message which is + either a detected duplicate of a prior message or which is too old to + validate against a cache of recently received messages. + +1.2.4. Quality of Protection + + Some mech_types will provide their users with fine granularity + control over the means used to provide per-message protection, + allowing callers to trade off security processing overhead + dynamically against the protection requirements of particular + messages. A per-message quality-of-protection parameter (analogous to + quality-of-service, or QOS) selects among different QOP options + supported by that mechanism. On context establishment for a multi-QOP + mech_type, context-level data provides the prerequisite data for a + range of protection qualities. + + It is expected that the majority of callers will not wish to exert + explicit mechanism-specific QOP control and will therefore request + selection of a default QOP. Definitions of, and choices among, non- + default QOP values are mechanism-specific, and no ordered sequences + of QOP values can be assumed equivalent across different mechanisms. + Meaningful use of non-default QOP values demands that callers be + familiar with the QOP definitions of an underlying mechanism or + mechanisms, and is therefore a non-portable construct. + +2. Interface Descriptions + + This section describes the GSS-API's service interface, dividing the + set of calls offered into four groups. Credential management calls + are related to the acquisition and release of credentials by + principals. Context-level calls are related to the management of + security contexts between principals. Per-message calls are related + to the protection of individual messages on established security + contexts. Support calls provide ancillary functions useful to GSS-API + callers. Table 2 groups and summarizes the calls in tabular fashion. + + + + + + + + + + + + + + +Linn [Page 15] + +RFC 1508 Generic Security Interface September 1993 + + + Table 2: GSS-API Calls + + CREDENTIAL MANAGEMENT + + GSS_Acquire_cred acquire credentials for use + GSS_Release_cred release credentials after use + GSS_Inquire_cred display information about + credentials + + CONTEXT-LEVEL CALLS + + GSS_Init_sec_context initiate outbound security context + GSS_Accept_sec_context accept inbound security context + GSS_Delete_sec_context flush context when no longer needed + GSS_Process_context_token process received control token on + context + GSS_Context_time indicate validity time remaining on + context + + PER-MESSAGE CALLS + + GSS_Sign apply signature, receive as token + separate from message + GSS_Verify validate signature token along with + message + GSS_Seal sign, optionally encrypt, + encapsulate + GSS_Unseal decapsulate, decrypt if needed, + validate signature + + SUPPORT CALLS + + GSS_Display_status translate status codes to printable + form + GSS_Indicate_mechs indicate mech_types supported on + local system + GSS_Compare_name compare two names for equality + GSS_Display_name translate name to printable form + GSS_Import_name convert printable name to + normalized form + GSS_Release_name free storage of normalized-form + name + GSS_Release_buffer free storage of printable name + GSS_Release_oid_set free storage of OID set object + + + + + + + +Linn [Page 16] + +RFC 1508 Generic Security Interface September 1993 + + +2.1. Credential management calls + + These GSS-API calls provide functions related to the management of + credentials. Their characterization with regard to whether or not + they may block pending exchanges with other network entities (e.g., + directories or authentication servers) depends in part on OS-specific + (extra-GSS-API) issues, so is not specified in this document. + + The GSS_Acquire_cred() call is defined within the GSS-API in support + of application portability, with a particular orientation towards + support of portable server applications. It is recognized that (for + certain systems and mechanisms) credentials for interactive users may + be managed differently from credentials for server processes; in such + environments, it is the GSS-API implementation's responsibility to + distinguish these cases and the procedures for making this + distinction are a local matter. The GSS_Release_cred() call provides + a means for callers to indicate to the GSS-API that use of a + credentials structure is no longer required. The GSS_Inquire_cred() + call allows callers to determine information about a credentials + structure. + +2.1.1. GSS_Acquire_cred call + + Inputs: + + o desired_name INTERNAL NAME, -NULL requests locally-determined + default + + o lifetime_req INTEGER,-in seconds; 0 requests default + + o desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests + system-selected default + + o cred_usage INTEGER-0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_cred_handle OCTET STRING, + + o actual_mechs SET OF OBJECT IDENTIFIER, + + o lifetime_rec INTEGER -in seconds, or reserved value for + INDEFINITE + + + +Linn [Page 17] + +RFC 1508 Generic Security Interface September 1993 + + + Return major_status codes: + + o GSS_COMPLETE indicates that requested credentials were + successfully established, for the duration indicated in + lifetime_rec, suitable for the usage requested in cred_usage, for + the set of mech_types indicated in actual_mechs, and that those + credentials can be referenced for subsequent use with the handle + returned in output_cred_handle. + + o GSS_BAD_MECH indicates that a mech_type unsupported by the GSS-API + implementation type was requested, causing the credential + establishment operation to fail. + + o GSS_BAD_NAMETYPE indicates that the provided desired_name is + uninterpretable or of a type unsupported by the supporting GSS-API + implementation, so no credentials could be established for the + accompanying desired_name. + + o GSS_BAD_NAME indicates that the provided desired_name is + inconsistent in terms of internally-incorporated type specifier + information, so no credentials could be established for the + accompanying desired_name. + + o GSS_FAILURE indicates that credential establishment failed for + reasons unspecified at the GSS-API level, including lack of + authorization to establish and use credentials associated with the + identity named in the input desired_name argument. + + GSS_Acquire_cred() is used to acquire credentials so that a + principal can (as a function of the input cred_usage parameter) + initiate and/or accept security contexts under the identity + represented by the desired_name input argument. On successful + completion, the returned output_cred_handle result provides a handle + for subsequent references to the acquired credentials. Typically, + single-user client processes using only default credentials for + context establishment purposes will have no need to invoke this call. + + A caller may provide the value NULL for desired_name, signifying a + request for credentials corresponding to a default principal + identity. The procedures used by GSS-API implementations to select + the appropriate principal identity in response to this form of + request are local matters. It is possible that multiple pre- + established credentials may exist for the same principal identity + (for example, as a result of multiple user login sessions) when + GSS_Acquire_cred() is called; the means used in such cases to select + a specific credential are local matters. The input lifetime_req + argument to GSS_Acquire_cred() may provide useful information for + local GSS-API implementations to employ in making this disambiguation + + + +Linn [Page 18] + +RFC 1508 Generic Security Interface September 1993 + + + in a manner which will best satisfy a caller's intent. + + The lifetime_rec result indicates the length of time for which the + acquired credentials will be valid, as an offset from the present. A + mechanism may return a reserved value indicating INDEFINITE if no + constraints on credential lifetime are imposed. A caller of + GSS_Acquire_cred() can request a length of time for which acquired + credentials are to be valid (lifetime_req argument), beginning at the + present, or can request credentials with a default validity interval. + (Requests for postdated credentials are not supported within the + GSS-API.) Certain mechanisms and implementations may bind in + credential validity period specifiers at a point preliminary to + invocation of the GSS_Acquire_cred() call (e.g., in conjunction with + user login procedures). As a result, callers requesting non-default + values for lifetime_req must recognize that such requests cannot + always be honored and must be prepared to accommodate the use of + returned credentials with different lifetimes as indicated in + lifetime_rec. + + The caller of GSS_Acquire_cred() can explicitly specify a set of + mech_types which are to be accommodated in the returned credentials + (desired_mechs argument), or can request credentials for a system- + defined default set of mech_types. Selection of the system-specified + default set is recommended in the interests of application + portability. The actual_mechs return value may be interrogated by the + caller to determine the set of mechanisms with which the returned + credentials may be used. + +2.1.2. GSS_Release_cred call + + Input: + + o cred_handle OCTET STRING-NULL specifies default credentials + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the credentials referenced by the + input cred_handle were released for purposes of subsequent access + by the caller. The effect on other processes which may be + authorized shared access to such credentials is a local matter. + + + + + +Linn [Page 19] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CRED indicates that no release operation was performed, + either because the input cred_handle was invalid or because the + caller lacks authorization to access the referenced credentials. + + o GSS_FAILURE indicates that the release operation failed for + reasons unspecified at the GSS-API level. + + Provides a means for a caller to explicitly request that credentials + be released when their use is no longer required. Note that system- + specific credential management functions are also likely to exist, + for example to assure that credentials shared among processes are + properly deleted when all affected processes terminate, even if no + explicit release requests are issued by those processes. Given the + fact that multiple callers are not precluded from gaining authorized + access to the same credentials, invocation of GSS_Release_cred() + cannot be assumed to delete a particular set of credentials on a + system-wide basis. + +2.1.3. GSS_Inquire_cred call + + Input: + + o cred_handle OCTET STRING -NULL specifies default credentials + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o cred_name INTERNAL NAME, + + o lifetime_rec INTEGER -in seconds, or reserved value for + INDEFINITE + + o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + o mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that the credentials referenced by the + input cred_handle argument were valid, and that the output + cred_name, lifetime_rec, and cred_usage values represent, + respectively, the credentials' associated principal name, + remaining lifetime, suitable usage modes, and supported + mechanism types. + + + +Linn [Page 20] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CRED indicates that no information could be returned + about the referenced credentials, either because the input + cred_handle was invalid or because the caller lacks + authorization to access the referenced credentials. + + o GSS_FAILURE indicates that the release operation failed for + reasons unspecified at the GSS-API level. + + The GSS_Inquire_cred() call is defined primarily for the use of + those callers which make use of default credentials rather than + acquiring credentials explicitly with GSS_Acquire_cred(). It enables + callers to determine a credential structure's associated principal + name, remaining validity period, usability for security context + initiation and/or acceptance, and supported mechanisms. + +2.2. Context-level calls + + This group of calls is devoted to the establishment and management of + security contexts between peers. A context's initiator calls + GSS_Init_sec_context(), resulting in generation of a token which the + caller passes to the target. At the target, that token is passed to + GSS_Accept_sec_context(). Depending on the underlying mech_type and + specified options, additional token exchanges may be performed in the + course of context establishment; such exchanges are accommodated by + GSS_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and + GSS_Accept_sec_context(). Either party to an established context may + invoke GSS_Delete_sec_context() to flush context information when a + context is no longer required. GSS_Process_context_token() is used + to process received tokens carrying context-level control + information. GSS_Context_time() allows a caller to determine the + length of time for which an established context will remain valid. + +2.2.1. GSS_Init_sec_context call + + Inputs: + + o claimant_cred_handle OCTET STRING, -NULL specifies "use + default" + + o input_context_handle INTEGER, -0 specifies "none assigned + yet" + + o targ_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use + default" + + o deleg_req_flag BOOLEAN, + + + +Linn [Page 21] + +RFC 1508 Generic Security Interface September 1993 + + + o mutual_req_flag BOOLEAN, + + o replay_det_req_flag BOOLEAN, + + o sequence_req_flag BOOLEAN, + + o lifetime_req INTEGER,-0 specifies default lifetime + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING-NULL or token received from target + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_context_handle INTEGER, + + o mech_type OBJECT IDENTIFIER, -actual mechanism always + indicated, never NULL + + o output_token OCTET STRING, -NULL or token to pass to context + target + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o lifetime_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + This call may block pending network interactions for those mech_types + in which an authentication server or other network entity must be + consulted on behalf of a context initiator in order to generate an + output_token suitable for presentation to a specified target. + + Return major_status codes: + + + + +Linn [Page 22] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_COMPLETE indicates that context-level information was + successfully initialized, and that the returned output_token will + provide sufficient information for the target to perform per- + message processing on the newly-established context. + + o GSS_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the target, and that a reply + must be received and passed as the input_token argument to a + continuation call to GSS_Init_sec_context(), before per-message + processing can be performed in conjunction with this context. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the input_token failed, preventing further processing from being + performed based on that token. + + o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + claimant_cred_handle failed, preventing further processing from + being performed using that credential structure. + + o GSS_BAD_SIG indicates that the received input_token contains an + incorrect signature, so context setup cannot be accomplished. + + o GSS_NO_CRED indicates that no context was established, either + because the input cred_handle was invalid, because the referenced + credentials are valid for context acceptor use only, or because + the caller lacks authorization to access the referenced + credentials. + + o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided + through the input claimant_cred_handle argument are no longer + valid, so context establishment cannot be completed. + + o GSS_BAD_BINDINGS indicates that a mismatch between the caller- + provided chan_bindings and those extracted from the input_token + was detected, signifying a security-relevant event and preventing + context establishment. (This result will be returned by + GSS_Init_sec_context only for contexts where mutual_state is + TRUE.) + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided; this major status will be + returned only for successor calls following GSS_CONTINUE_NEEDED + status returns. + + o GSS_BAD_NAMETYPE indicates that the provided targ_name is of a + type uninterpretable or unsupported by the supporting GSS-API + implementation, so context establishment cannot be completed. + + + +Linn [Page 23] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_BAD_NAME indicates that the provided targ_name is inconsistent + in terms of internally-incorporated type specifier information, so + context establishment cannot be accomplished. + + o GSS_FAILURE indicates that context setup could not be accomplished + for reasons unspecified at the GSS-API level, and that no + interface-defined recovery action is available. + + This routine is used by a context initiator, and ordinarily emits one + (or, for the case of a multi-step exchange, more than one) + output_token suitable for use by the target within the selected + mech_type's protocol. Using information in the credentials structure + referenced by claimant_cred_handle, GSS_Init_sec_context() + initializes the data structures required to establish a security + context with target targ_name. The claimant_cred_handle must + correspond to the same valid credentials structure on the initial + call to GSS_Init_sec_context() and on any successor calls resulting + from GSS_CONTINUE_NEEDED status returns; different protocol sequences + modeled by the GSS_CONTINUE_NEEDED mechanism will require access to + credentials at different points in the context establishment + sequence. + + The input_context_handle argument is 0, specifying "not yet + assigned", on the first GSS_Init_sec_context() call relating to a + given context. That call returns an output_context_handle for future + references to this context. When continuation attempts to + GSS_Init_sec_context() are needed to perform context establishment, + the previously-returned non-zero handle value is entered into the + input_context_handle argument and will be echoed in the returned + output_context_handle argument. On such continuation attempts (and + only on continuation attempts) the input_token value is used, to + provide the token returned from the context's target. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The input_token argument contains a message received from the target, + and is significant only on a call to GSS_Init_sec_context() which + follows a previous return indicating GSS_CONTINUE_NEEDED + major_status. + + It is the caller's responsibility to establish a communications path + to the target, and to transmit any returned output_token (independent + of the accompanying returned major_status value) to the target over + that path. The output_token can, however, be transmitted along with + + + +Linn [Page 24] + +RFC 1508 Generic Security Interface September 1993 + + + the first application-provided input message to be processed by + GSS_Sign() or GSS_Seal() in conjunction with a successfully- + established context. + + The initiator may request various context-level functions through + input flags: the deleg_req_flag requests delegation of access rights, + the mutual_req_flag requests mutual authentication, the + replay_det_req_flag requests that replay detection features be + applied to messages transferred on the established context, and the + sequence_req_flag requests that sequencing be enforced. (See Section + 1.2.3 for more information on replay detection and sequencing + features.) + + Not all of the optionally-requestable features will be available in + all underlying mech_types; the corresponding return state values + (deleg_state, mutual_state, replay_det_state, sequence_state) + indicate, as a function of mech_type processing capabilities and + initiator-provided input flags, the set of features which will be + active on the context. These state indicators' values are undefined + unless the routine's major_status indicates COMPLETE. Failure to + provide the precise set of features requested by the caller does not + cause context establishment to fail; it is the caller's prerogative + to delete the context if the feature set provided is unsuitable for + the caller's use. The returned mech_type value indicates the + specific mechanism employed on the context, and will never indicate + the value for "default". + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + input to GSS_Seal() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_Sign() or GSS_Seal()) on + the established context. + + The lifetime_req input specifies a desired upper bound for the + lifetime of the context to be established, with a value of 0 used to + request a default lifetime. The lifetime_rec return value indicates + the length of time for which the context will be valid, expressed as + an offset from the present; depending on mechanism capabilities, + credential lifetimes, and local policy, it may not correspond to the + value requested in lifetime_req. If no constraints on context + lifetime are imposed, this may be indicated by returning a reserved + value representing INDEFINITE lifetime_req. The values of conf_avail, + integ_avail, and lifetime_rec are undefined unless the routine's + major_status indicates COMPLETE. + + If the mutual_state is TRUE, this fact will be reflected within the + + + +Linn [Page 25] + +RFC 1508 Generic Security Interface September 1993 + + + output_token. A call to GSS_Accept_sec_context() at the target in + conjunction with such a context will return a token, to be processed + by a continuation call to GSS_Init_sec_context(), in order to achieve + mutual authentication. + +2.2.2. GSS_Accept_sec_context call + + Inputs: + + o acceptor_cred_handle OCTET STRING,-NULL specifies "use + default" + + o input_context_handle INTEGER, -0 specifies "not yet assigned" + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o src_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER, + + o output_context_handle INTEGER, + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o lifetime_rec INTEGER, - in seconds, or reserved value for + INDEFINITE + + o delegated_cred_handle OCTET STRING, + + o output_token OCTET STRING -NULL or token to pass to context + + + +Linn [Page 26] + +RFC 1508 Generic Security Interface September 1993 + + + initiator + + This call may block pending network interactions for those mech_types + in which a directory service or other network entity must be + consulted on behalf of a context acceptor in order to validate a + received input_token. + + Return major_status codes: + + o GSS_COMPLETE indicates that context-level data structures were + successfully initialized, and that per-message processing can now + be performed in conjunction with this context. + + o GSS_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the initiator, and that a + response must be received and passed as the input_token argument + to a continuation call to GSS_Accept_sec_context(), before per- + message processing can be performed in conjunction with this + context. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the input_token failed, preventing further processing from being + performed based on that token. + + o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + acceptor_cred_handle failed, preventing further processing from + being performed using that credential structure. + + o GSS_BAD_SIG indicates that the received input_token contains an + incorrect signature, so context setup cannot be accomplished. + + o GSS_DUPLICATE_TOKEN indicates that the signature on the received + input_token was correct, but that the input_token was recognized + as a duplicate of an input_token already processed. No new context + is established. + + o GSS_OLD_TOKEN indicates that the signature on the received + input_token was correct, but that the input_token is too old to be + checked for duplication against previously-processed input_tokens. + No new context is established. + + o GSS_NO_CRED indicates that no context was established, either + because the input cred_handle was invalid, because the referenced + credentials are valid for context initiator use only, or because + the caller lacks authorization to access the referenced + credentials. + + + + +Linn [Page 27] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided + through the input acceptor_cred_handle argument are no longer + valid, so context establishment cannot be completed. + + o GSS_BAD_BINDINGS indicates that a mismatch between the caller- + provided chan_bindings and those extracted from the input_token + was detected, signifying a security-relevant event and preventing + context establishment. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided; this major status will be + returned only for successor calls following GSS_CONTINUE_NEEDED + status returns. + + o GSS_FAILURE indicates that context setup could not be accomplished + for reasons unspecified at the GSS-API level, and that no + interface-defined recovery action is available. + + The GSS_Accept_sec_context() routine is used by a context target. + Using information in the credentials structure referenced by the + input acceptor_cred_handle, it verifies the incoming input_token and + (following the successful completion of a context establishment + sequence) returns the authenticated src_name and the mech_type used. + The acceptor_cred_handle must correspond to the same valid + credentials structure on the initial call to GSS_Accept_sec_context() + and on any successor calls resulting from GSS_CONTINUE_NEEDED status + returns; different protocol sequences modeled by the + GSS_CONTINUE_NEEDED mechanism will require access to credentials at + different points in the context establishment sequence. + + The input_context_handle argument is 0, specifying "not yet + assigned", on the first GSS_Accept_sec_context() call relating to a + given context. That call returns an output_context_handle for future + references to this context; when continuation attempts to + GSS_Accept_sec_context() are needed to perform context + establishment, that handle value will be entered into the + input_context_handle argument. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The returned state results (deleg_state, mutual_state, + replay_det_state, and sequence_state) reflect the same context state + values as returned to GSS_Init_sec_context()'s caller at the + initiator system. + + + +Linn [Page 28] + +RFC 1508 Generic Security Interface September 1993 + + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + input to GSS_Seal() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_Sign() or GSS_Seal()) on + the established context. + + The lifetime_rec return value indicates the length of time for which + the context will be valid, expressed as an offset from the present. + The values of deleg_state, mutual_state, replay_det_state, + sequence_state, conf_avail, integ_avail, and lifetime_rec are + undefined unless the accompanying major_status indicates COMPLETE. + + The delegated_cred_handle result is significant only when deleg_state + is TRUE, and provides a means for the target to reference the + delegated credentials. The output_token result, when non-NULL, + provides a context-level token to be returned to the context + initiator to continue a multi-step context establishment sequence. As + noted with GSS_Init_sec_context(), any returned token should be + transferred to the context's peer (in this case, the context + initiator), independent of the value of the accompanying returned + major_status. + + Note: A target must be able to distinguish a context-level + input_token, which is passed to GSS_Accept_sec_context(), from the + per-message data elements passed to GSS_Verify() or GSS_Unseal(). + These data elements may arrive in a single application message, and + GSS_Accept_sec_context() must be performed before per-message + processing can be performed successfully. + +2.2.3. GSS_Delete_sec_context call + + Input: + + o context_handle INTEGER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_context_token OCTET STRING + + Return major_status codes: + + + + + +Linn [Page 29] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_COMPLETE indicates that the context was recognized, that + relevant context-specific information was flushed, and that the + returned output_context_token is ready for transfer to the + context's peer. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provide, so no deletion was performed. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Delete_sec_context() operation could not be performed for + reasons unspecified at the GSS-API level. + + This call may block pending network interactions for mech_types in + which active notification must be made to a central server when a + security context is to be deleted. + + This call can be made by either peer in a security context, to flush + context-specific information and to return an output_context_token + which can be passed to the context's peer informing it that the + peer's corresponding context information can also be flushed. (Once a + context is established, the peers involved are expected to retain + cached credential and context-related information until the + information's expiration time is reached or until a + GSS_Delete_sec_context() call is made.) Attempts to perform per- + message processing on a deleted context will result in error returns. + +2.2.4. GSS_Process_context_token call + + Inputs: + + o context_handle INTEGER, + + o input_context_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_context_token was + successfully processed in conjunction with the context referenced + by context_handle. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the received context_token failed, preventing further processing + + + +Linn [Page 30] + +RFC 1508 Generic Security Interface September 1993 + + + from being performed with that token. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Process_context_token() operation could not be performed for + reasons unspecified at the GSS-API level. + + This call is used to process context_tokens received from a peer once + a context has been established, with corresponding impact on + context-level state information. One use for this facility is + processing of the context_tokens generated by + GSS_Delete_sec_context(); GSS_Process_context_token() will not block + pending network interactions for that purpose. Another use is to + process tokens indicating remote-peer context establishment failures + after the point where the local GSS-API implementation has already + indicated GSS_COMPLETE status. + +2.2.5. GSS_Context_time call + + Input: + + o context_handle INTEGER, + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o lifetime_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + Return major_status codes: + + o GSS_COMPLETE indicates that the referenced context is valid, and + will remain valid for the amount of time indicated in + lifetime_rec. + + o GSS_CONTEXT_EXPIRED indicates that data items related to the + referenced context have expired. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + + +Linn [Page 31] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. + + This call is used to determine the amount of time for which a + currently established context will remain valid. + +2.3. Per-message calls + + This group of calls is used to perform per-message protection + processing on an established security context. None of these calls + block pending network interactions. These calls may be invoked by a + context's initiator or by the context's target. The four members of + this group should be considered as two pairs; the output from + GSS_Sign() is properly input to GSS_Verify(), and the output from + GSS_Seal() is properly input to GSS_Unseal(). + + GSS_Sign() and GSS_Verify() support data origin authentication and + data integrity services. When GSS_Sign() is invoked on an input + message, it yields a per-message token containing data items which + allow underlying mechanisms to provide the specified security + services. The original message, along with the generated per-message + token, is passed to the remote peer; these two data elements are + processed by GSS_Verify(), which validates the message in + conjunction with the separate token. + + GSS_Seal() and GSS_Unseal() support caller-requested confidentiality + in addition to the data origin authentication and data integrity + services offered by GSS_Sign() and GSS_Verify(). GSS_Seal() outputs + a single data element, encapsulating optionally enciphered user data + as well as associated token data items. The data element output from + GSS_Seal() is passed to the remote peer and processed by + GSS_Unseal() at that system. GSS_Unseal() combines decipherment (as + required) with validation of data items related to authentication and + integrity. + +2.3.1. GSS_Sign call + + Inputs: + + o context_handle INTEGER, + + o qop_req INTEGER,-0 specifies default QOP + + o message OCTET STRING + + Outputs: + + o major_status INTEGER, + + + +Linn [Page 32] + +RFC 1508 Generic Security Interface September 1993 + + + o minor_status INTEGER, + + o per_msg_token OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that a signature, suitable for an + established security context, was successfully applied and that + the message and corresponding per_msg_token are ready for + transmission. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + requested operation could not be performed for reasons unspecified + at the GSS-API level. + + Using the security context referenced by context_handle, apply a + signature to the input message (along with timestamps and/or other + data included in support of mech_type-specific mechanisms) and return + the result in per_msg_token. The qop_req parameter allows quality- + of-protection control. The caller passes the message and the + per_msg_token to the target. + + The GSS_Sign() function completes before the message and + per_msg_token is sent to the peer; successful application of + GSS_Sign() does not guarantee that a corresponding GSS_Verify() has + been (or can necessarily be) performed successfully when the message + arrives at the destination. + +2.3.2. GSS_Verify call + + Inputs: + + o context_handle INTEGER, + + o message OCTET STRING, + + o per_msg_token OCTET STRING + + + + +Linn [Page 33] + +RFC 1508 Generic Security Interface September 1993 + + + Outputs: + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_COMPLETE indicates that the message was successfully verified. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the received per_msg_token failed, preventing further processing + from being performed with that token. + + o GSS_BAD_SIG indicates that the received per_msg_token contains an + incorrect signature for the message. + + o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values + appear in conjunction with the optional per-message replay + detection features described in Section 1.2.3; their semantics are + described in that section. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Verify() operation could not be performed for reasons + unspecified at the GSS-API level. + + Using the security context referenced by context_handle, verify that + the input per_msg_token contains an appropriate signature for the + input message, and apply any active replay detection or sequencing + features. Return an indication of the quality-of-protection applied + to the processed message in the qop_state result. + + + + + + + + +Linn [Page 34] + +RFC 1508 Generic Security Interface September 1993 + + +2.3.3. GSS_Seal call + + Inputs: + + o context_handle INTEGER, + + o conf_req_flag BOOLEAN, + + o qop_req INTEGER,-0 specifies default QOP + + o input_message OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o conf_state BOOLEAN, + + o output_message OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_message was successfully + processed and that the output_message is ready for transmission. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Seal() operation could not be performed for reasons + unspecified at the GSS-API level. + + Performs the data origin authentication and data integrity functions + of GSS_Sign(). If the input conf_req_flag is TRUE, requests that + confidentiality be applied to the input_message. Confidentiality may + not be supported in all mech_types or by all implementations; the + returned conf_state flag indicates whether confidentiality was + provided for the input_message. The qop_req parameter allows + quality-of-protection control. + + + +Linn [Page 35] + +RFC 1508 Generic Security Interface September 1993 + + + In all cases, the GSS_Seal() call yields a single output_message + data element containing (optionally enciphered) user data as well as + control information. + +2.3.4. GSS_Unseal call + + Inputs: + + o context_handle INTEGER, + + o input_message OCTET STRING + + Outputs: + + o conf_state BOOLEAN, + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_message OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_message was successfully + processed and that the resulting output_message is available. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the per_msg_token extracted from the input_message failed, + preventing further processing from being performed. + + o GSS_BAD_SIG indicates that an incorrect signature was detected for + the message. + + o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values + appear in conjunction with the optional per-message replay + detection features described in Section 1.2.3; their semantics are + described in that section. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + + + +Linn [Page 36] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Unseal() operation could not be performed for reasons + unspecified at the GSS-API level. + + Processes a data element generated (and optionally enciphered) by + GSS_Seal(), provided as input_message. The returned conf_state value + indicates whether confidentiality was applied to the input_message. + If conf_state is TRUE, GSS_Unseal() deciphers the input_message. + Returns an indication of the quality-of-protection applied to the + processed message in the qop_state result. GSS_Seal() performs the + data integrity and data origin authentication checking functions of + GSS_Verify() on the plaintext data. Plaintext data is returned in + output_message. + +2.4. Support calls + + This group of calls provides support functions useful to GSS-API + callers, independent of the state of established contexts. Their + characterization with regard to blocking or non-blocking status in + terms of network interactions is unspecified. + +2.4.1. GSS_Display_status call + + Inputs: + + o status_value INTEGER,-GSS-API major_status or minor_status + return value + + o status_type INTEGER,-1 if major_status, 2 if minor_status + + o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_ + status translation + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o status_string_set SET OF OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid printable status + representation (possibly representing more than one status event + + + +Linn [Page 37] + +RFC 1508 Generic Security Interface September 1993 + + + encoded within the status_value) is available in the returned + status_string_set. + + o GSS_BAD_MECH indicates that translation in accordance with an + unsupported mech_type was requested, so translation could not be + performed. + + o GSS_BAD_STATUS indicates that the input status_value was invalid, + or that the input status_type carried a value other than 1 or 2, + so translation could not be performed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Provides a means for callers to translate GSS-API-returned major and + minor status codes into printable string representations. + +2.4.2. GSS_Indicate_mechs call + + Input: + + o (none) + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that a set of available mechanisms has + been returned in mech_set. + + o GSS_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to determine the set of mechanism types available on + the local system. This call is intended for support of specialized + callers who need to request non-default mech_type sets from + GSS_Acquire_cred(), and should not be needed by other callers. + +2.4.3. GSS_Compare_name call + + Inputs: + + + + +Linn [Page 38] + +RFC 1508 Generic Security Interface September 1993 + + + o name1 INTERNAL NAME, + + o name2 INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_equal BOOLEAN + + Return major_status codes: + + o GSS_COMPLETE indicates that name1 and name2 were comparable, and + that the name_equal result indicates whether name1 and name2 were + equal or unequal. + + o GSS_BAD_NAMETYPE indicates that one or both of name1 and name2 + contained internal type specifiers uninterpretable by the + supporting GSS-API implementation, or that the two names' types + are different and incomparable, so the equality comparison could + not be completed. + + o GSS_BAD_NAME indicates that one or both of the input names was + ill-formed in terms of its internal type specifier, so the + equality comparison could not be completed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to compare two internal name representations for + equality. + +2.4.4. GSS_Display_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_string OCTET STRING, + + + + +Linn [Page 39] + +RFC 1508 Generic Security Interface September 1993 + + + o name_type OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid printable name representation + is available in the returned name_string. + + o GSS_BAD_NAMETYPE indicates that the provided name was of a type + uninterpretable by the supporting GSS-API implementation, so no + printable representation could be generated. + + o GSS_BAD_NAME indicates that the contents of the provided name were + inconsistent with the internally-indicated name type, so no + printable representation could be generated. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to translate an internal name representation into a + printable form with associated namespace type descriptor. The syntax + of the printable form is a local matter. + +2.4.5. GSS_Import_name call + + Inputs: + + o input_name_string OCTET STRING, + + o input_name_type OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_name INTERNAL NAME + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid name representation is output + in output_name and described by the type value in + output_name_type. + + o GSS_BAD_NAMETYPE indicates that the input_name_type is unsupported + by the GSS-API implementation, so the import operation could not + be completed. + + + + +Linn [Page 40] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_BAD_NAME indicates that the provided input_name_string is + ill-formed in terms of the input_name_type, so the import + operation could not be completed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to provide a printable name representation, designate + the type of namespace in conjunction with which it should be parsed, + and convert that printable representation to an internal form + suitable for input to other GSS-API routines. The syntax of the + input_name is a local matter. + +2.4.6. GSS_Release_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + name was successfully released. + + o GSS_BAD_NAME indicates that the input name argument did not + contain a valid name. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an internal + name representation. + +2.4.7. GSS_Release_buffer call + + Inputs: + + o buffer OCTET STRING + + Outputs: + + o major_status INTEGER, + + + +Linn [Page 41] + +RFC 1508 Generic Security Interface September 1993 + + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + buffer was successfully released. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an OCTET STRING + buffer allocated by another GSS-API call. + +2.4.8. GSS_Release_oid_set call + + Inputs: + + o buffer SET OF OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + object identifier set was successfully released. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an object + identifier set object allocated by another GSS-API call. + +3. Mechanism-Specific Example Scenarios + + This section provides illustrative overviews of the use of various + candidate mechanism types to support the GSS-API. These discussions + are intended primarily for readers familiar with specific security + technologies, demonstrating how GSS-API functions can be used and + implemented by candidate underlying mechanisms. They should not be + regarded as constrictive to implementations or as defining the only + means through which GSS-API functions can be realized with a + particular underlying technology, and do not demonstrate all GSS-API + features with each technology. + + + + +Linn [Page 42] + +RFC 1508 Generic Security Interface September 1993 + + +3.1. Kerberos V5, single-TGT + + OS-specific login functions yield a TGT to the local realm Kerberos + server; TGT is placed in a credentials structure for the client. + Client calls GSS_Acquire_cred() to acquire a cred_handle in order to + reference the credentials for use in establishing security contexts. + + Client calls GSS_Init_sec_context(). If the requested service is + located in a different realm, GSS_Init_sec_context() gets the + necessary TGT/key pairs needed to traverse the path from local to + target realm; these data are placed in the owner's TGT cache. After + any needed remote realm resolution, GSS_Init_sec_context() yields a + service ticket to the requested service with a corresponding session + key; these data are stored in conjunction with the context. GSS-API + code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP + response(s) (in the successful case) or KRB_ERROR. + + Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted + KRB_AP_REQ message, and returns it in output_token. The client sends + the output_token to the service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which verifies the authenticator, provides + the service with the client's authenticated name, and returns an + output_context_handle. + + Both parties now hold the session key associated with the service + ticket, and can use this key in subsequent GSS_Sign(), GSS_Verify(), + GSS_Seal(), and GSS_Unseal() operations. + +3.2. Kerberos V5, double-TGT + + TGT acquisition as above. + + Note: To avoid unnecessary frequent invocations of error paths when + implementing the GSS-API atop Kerberos V5, it seems appropriate to + represent "single-TGT K-V5" and "double-TGT K-V5" with separate + mech_types, and this discussion makes that assumption. + + Based on the (specified or defaulted) mech_type, + GSS_Init_sec_context() determines that the double-TGT protocol + should be employed for the specified target. GSS_Init_sec_context() + returns GSS_CONTINUE_NEEDED major_status, and its returned + output_token contains a request to the service for the service's TGT. + (If a service TGT with suitably long remaining lifetime already + exists in a cache, it may be usable, obviating the need for this + step.) The client passes the output_token to the service. Note: this + scenario illustrates a different use for the GSS_CONTINUE_NEEDED + + + +Linn [Page 43] + +RFC 1508 Generic Security Interface September 1993 + + + status return facility than for support of mutual authentication; + note that both uses can coexist as successive operations within a + single context establishment operation. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which recognizes it as a request for TGT. + (Note that current Kerberos V5 defines no intra-protocol mechanism to + represent such a request.) GSS_Accept_sec_context() returns + GSS_CONTINUE_NEEDED major_status and provides the service's TGT in + its output_token. The service sends the output_token to the client. + + The client passes the received token as the input_token argument to a + continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches + the received service TGT and uses it as part of a service ticket + request to the Kerberos authentication server, storing the returned + service ticket and session key in conjunction with the context. + GSS_Init_sec_context() builds a Kerberos-formatted authenticator, + and returns it in output_token along with GSS_COMPLETE return + major_status. The client sends the output_token to the service. + + Service passes the received token as the input_token argument to a + continuation call to GSS_Accept_sec_context(). + GSS_Accept_sec_context() verifies the authenticator, provides the + service with the client's authenticated name, and returns + major_status GSS_COMPLETE. + + GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() as above. + +3.3. X.509 Authentication Framework + + This example illustrates use of the GSS-API in conjunction with + public-key mechanisms, consistent with the X.509 Directory + Authentication Framework. + + The GSS_Acquire_cred() call establishes a credentials structure, + making the client's private key accessible for use on behalf of the + client. + + The client calls GSS_Init_sec_context(), which interrogates the + Directory to acquire (and validate) a chain of public-key + certificates, thereby collecting the public key of the service. The + certificate validation operation determines that suitable signatures + were applied by trusted authorities and that those certificates have + not expired. GSS_Init_sec_context() generates a secret key for use + in per-message protection operations on the context, and enciphers + that secret key under the service's public key. + + The enciphered secret key, along with an authenticator quantity + + + +Linn [Page 44] + +RFC 1508 Generic Security Interface September 1993 + + + signed with the client's private key, is included in the output_token + from GSS_Init_sec_context(). The output_token also carries a + certification path, consisting of a certificate chain leading from + the service to the client; a variant approach would defer this path + resolution to be performed by the service instead of being asserted + by the client. The client application sends the output_token to the + service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the + certification path, and as a result determines a certified binding + between the client's distinguished name and the client's public key. + Given that public key, GSS_Accept_sec_context() can process the + input_token's authenticator quantity and verify that the client's + private key was used to sign the input_token. At this point, the + client is authenticated to the service. The service uses its private + key to decipher the enciphered secret key provided to it for per- + message protection operations on the context. + + The client calls GSS_Sign() or GSS_Seal() on a data message, which + causes per-message authentication, integrity, and (optional) + confidentiality facilities to be applied to that message. The service + uses the context's shared secret key to perform corresponding + GSS_Verify() and GSS_Unseal() calls. + +4. Related Activities + + In order to implement the GSS-API atop existing, emerging, and future + security mechanisms: + + object identifiers must be assigned to candidate GSS-API + mechanisms and the name types which they support + + concrete data element formats must be defined for candidate + mechanisms + + Calling applications must implement formatting conventions which will + enable them to distinguish GSS-API tokens from other data carried in + their application protocols. + + Concrete language bindings are required for the programming + environments in which the GSS-API is to be employed; such bindings + for the C language are available in an associated RFC. + + + + + + + + +Linn [Page 45] + +RFC 1508 Generic Security Interface September 1993 + + +5. Acknowledgments + + This proposal is the result of a collaborative effort. + Acknowledgments are due to the many members of the IETF Security Area + Advisory Group (SAAG) and the Common Authentication Technology (CAT) + Working Group for their contributions at meetings and by electronic + mail. Acknowledgments are also due to Kannan Alagappan, Doug Barlow, + Bill Brown, Cliff Kahn, Charlie Kaufman, Butler Lampson, Richard + Pitkin, Joe Tardo, and John Wray of Digital Equipment Corporation, + and John Carr, John Kohl, Jon Rochlis, Jeff Schiller, and Ted T'so of + MIT and Project Athena. Joe Pato and Bill Sommerfeld of HP/Apollo, + Walt Tuvell of OSF, and Bill Griffith and Mike Merritt of AT&T, + provided inputs which helped to focus and clarify directions. + Precursor work by Richard Pitkin, presented to meetings of the + Trusted Systems Interoperability Group (TSIG), helped to demonstrate + the value of a generic, mechanism-independent security service API. + +6. Security Considerations + + Security issues are discussed throughout this memo. + +7. Author's Address + + John Linn + Geer Zolot Associates + One Main St. + Cambridge, MA 02142 USA + + Phone: +1 617.374.3700 + Email: Linn@gza.com + + + + + + + + + + + + + + + + + + + + + +Linn [Page 46] + +RFC 1508 Generic Security Interface September 1993 + + +APPENDIX A + +PACS AND AUTHORIZATION SERVICES + + Consideration has been given to modifying the GSS-API service + interface to recognize and manipulate Privilege Attribute + Certificates (PACs) as in ECMA 138, carrying authorization data as a + side effect of establishing a security context, but no such + modifications have been incorporated at this time. This appendix + provides rationale for this decision and discusses compatibility + alternatives between PACs and the GSS-API which do not require that + PACs be made visible to GSS-API callers. + + Existing candidate mechanism types such as Kerberos and X.509 do not + incorporate PAC manipulation features, and exclusion of such + mechanisms from the set of candidates equipped to fully support the + GSS-API seems inappropriate. Inclusion (and GSS-API visibility) of a + feature supported by only a limited number of mechanisms could + encourage the development of ostensibly portable applications which + would in fact have only limited portability. + + The status quo, in which PACs are not visible across the GSS-API + interface, does not preclude implementations in which PACs are + carried transparently, within the tokens defined and used for certain + mech_types, and stored within peers' credentials and context-level + data structures. While invisible to API callers, such PACs could be + used by operating system or other local functions as inputs in the + course of mediating access requests made by callers. This course of + action allows dynamic selection of PAC contents, if such selection is + administratively-directed rather than caller-directed. + + In a distributed computing environment, authentication must span + different systems; the need for such authentication provides + motivation for GSS-API definition and usage. Heterogeneous systems in + a network can intercommunicate, with globally authenticated names + comprising the common bond between locally defined access control + policies. Access control policies to which authentication provides + inputs are often local, or specific to particular operating systems + or environments. If the GSS-API made particular authorization models + visible across its service interface, its scope of application would + become less general. The current GSS-API paradigm is consistent with + the precedent set by Kerberos, neither defining the interpretation of + authorization-related data nor enforcing access controls based on + such data. + + The GSS-API is a general interface, whose callers may reside inside + or outside any defined TCB or NTCB boundaries. Given this + characteristic, it appears more realistic to provide facilities which + + + +Linn [Page 47] + +RFC 1508 Generic Security Interface September 1993 + + + provide "value-added" security services to its callers than to offer + facilities which enforce restrictions on those callers. Authorization + decisions must often be mediated below the GSS-API level in a local + manner against (or in spite of) applications, and cannot be + selectively invoked or omitted at those applications' discretion. + Given that the GSS-API's placement prevents it from providing a + comprehensive solution to the authorization issue, the value of a + partial contribution specific to particular authorization models is + debatable. + +APPENDIX B + +MECHANISM-INDEPENDENT TOKEN FORMAT + + This appendix specifies a mechanism-independent level of + encapsulating representation for the initial token of a GSS-API + context establishment sequence, incorporating an identifier of the + mechanism type to be used on that context. Use of this format (with + ASN.1-encoded data elements represented in BER, constrained in the + interests of parsing simplicity to the Distinguished Encoding Rule + (DER) BER subset defined in X.509, clause 8.7) is recommended to the + designers of GSS-API implementations based on various mechanisms, so + that tokens can be interpreted unambiguously at GSS-API peers. There + is no requirement that the mechanism-specific innerContextToken, + innerMsgToken, and sealedUserData data elements be encoded in ASN.1 + BER. + + -- optional top-level token definitions to + -- frame different mechanisms + + GSS-API DEFINITIONS ::= + + BEGIN + + MechType ::= OBJECT IDENTIFIER + -- data structure definitions + + -- callers must be able to distinguish among + -- InitialContextToken, SubsequentContextToken, + -- PerMsgToken, and SealedMessage data elements + -- based on the usage in which they occur + + InitialContextToken ::= + -- option indication (delegation, etc.) indicated within + -- mechanism-specific token + [APPLICATION 0] IMPLICIT SEQUENCE { + thisMech MechType, + innerContextToken ANY DEFINED BY thisMech + + + +Linn [Page 48] + +RFC 1508 Generic Security Interface September 1993 + + + -- contents mechanism-specific + } + + SubsequentContextToken ::= innerContextToken ANY + -- interpretation based on predecessor InitialContextToken + + PerMsgToken ::= + -- as emitted by GSS_Sign and processed by GSS_Verify + innerMsgToken ANY + + SealedMessage ::= + -- as emitted by GSS_Seal and processed by GSS_Unseal + -- includes internal, mechanism-defined indicator + -- of whether or not encrypted + sealedUserData ANY + + END + +APPENDIX C + +MECHANISM DESIGN CONSTRAINTS + + The following constraints on GSS-API mechanism designs are adopted in + response to observed caller protocol requirements, and adherence + thereto is anticipated in subsequent descriptions of GSS-API + mechanisms to be documented in standards-track Internet + specifications. + + Use of the approach defined in Appendix B of this specification, + applying a mechanism type tag to the InitialContextToken, is + required. + + It is strongly recommended that mechanisms offering per-message + protection services also offer at least one of the replay detection + and sequencing services, as mechanisms offering neither of the latter + will fail to satisfy recognized requirements of certain candidate + caller protocols. + + + + + + + + + + + + + + +Linn [Page 49] + \ No newline at end of file diff --git a/doc/standardisation/rfc1509.txt b/doc/standardisation/rfc1509.txt new file mode 100644 index 000000000..f36cd80e6 --- /dev/null +++ b/doc/standardisation/rfc1509.txt @@ -0,0 +1,2691 @@ + + + + + + +Network Working Group J. Wray +Request for Comments: 1509 Digital Equipment Corporation + September 1993 + + + Generic Security Service API : C-bindings + +Status of this Memo + + This RFC specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" for the standardization state and status + of this protocol. Distribution of this memo is unlimited. + +Abstract + + This document specifies C language bindings for the Generic Security + Service Application Program Interface (GSS-API), which is described + at a language-independent conceptual level in other documents. + + The Generic Security Service Application Programming Interface (GSS- + API) provides security services to its callers, and is intended for + implementation atop alternative 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. + +1. INTRODUCTION + + The Generic Security Service Application Programming Interface [1] + provides security services to calling applications. It allows a + communicating application to authenticate the user associated with + another application, to delegate rights to another application, and + to apply security services such as confidentiality and integrity on a + per-message basis. + + There are four stages to using the GSSAPI: + + (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 the local username under which it is running. + + + + + +Wray [Page 1] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + (b) A pair of communicating applications establish a joint security + context using their credentials. The security context is a + pair of GSSAPI data structures that contain shared state + information, which is required in order that per-message + security services may be provided. 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. This transfer of rights is termed + delegation, and is achieved by creating a set of credentials, + similar to those used by the originating application, but which + may be used by the responder. To establish and maintain the + shared information that makes up the security context, certain + GSSAPI calls will return a token data structure, which is a + cryptographically protected opaque data type. The caller of + such a GSSAPI routine is responsible for transferring the token + to the peer application, which should then pass it to a + corresponding GSSAPI routine which will decode it and extract + the information. + + (c) Per-message services are invoked to apply either: + + (i) integrity and data origin authentication, or + + (ii) confidentiality, integrity and data origin authentication + to application data, which are treated by GSSAPI as + arbitrary octet-strings. The application transmitting a + message that it wishes to protect will call the appropriate + GSSAPI routine (sign or seal) to apply protection, specifying + the appropriate security context, and send the result to the + receiving application. The receiver will pass the received + data to the corresponding decoding routine (verify or unseal) + to remove the protection and validate the data. + + (d) At the completion of a communications session (which may extend + across several connections), the peer applications call GSSAPI + routines to delete the security context. Multiple contexts may + also be used (either successively or simultaneously) within a + single communications association. + +2. GSSAPI Routines + + This section lists the functions performed by each of the GSSAPI + routines and discusses their major parameters, describing how they + are to be passed to the routines. The routines are listed in figure + 4-1. + + + + +Wray [Page 2] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Figure 4-1 GSSAPI Routines + + + Routine Function + + gss_acquire_cred Assume a global identity + + gss_release_cred Discard credentials + + gss_init_sec_context Initiate a security context + with a peer application + + gss_accept_sec_context Accept a security context + initiated by a peer + application + + gss_process_context_token Process a token on a security + context from a peer + application + + gss_delete_sec_context Discard a security context + + gss_context_time Determine for how long a + context will remain valid + + gss_sign Sign a message; integrity + service + + gss_verify Check signature on a message + + gss_seal Sign (optionally encrypt) a + message; confidentiality + service + + gss_unseal Verify (optionally decrypt) + message + + gss_display_status Convert an API status code + to text + + gss_indicate_mechs Determine underlying + authentication mechanism + + gss_compare_name Compare two internal-form + names + + gss_display_name Convert opaque name to text + + + + +Wray [Page 3] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + gss_import_name Convert a textual name to + internal-form + + gss_release_name Discard an internal-form + name + + gss_release_buffer Discard a buffer + + gss_release_oid_set Discard a set of object + identifiers + + gss_inquire_cred Determine information about + a credential + + Individual GSSAPI 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. + +2.1. Data Types and Calling Conventions + + The following conventions are used by the GSSAPI: + +2.1.1. Structured data types + + Wherever these GSSAPI C-bindings describe structured data, only + fields that must be provided by all GSSAPI implementation are + documented. Individual implementations may provide additional + fields, either for internal use within GSSAPI routines, or for use by + non-portable applications. + +2.1.2. Integer types + + GSSAPI defines the following integer data type: + + OM_uint32 32-bit unsigned integer + + Where guaranteed minimum bit-count is important, this portable data + type is used by the GSSAPI routine definitions. Individual GSSAPI + implementations will include appropriate typedef definitions to map + this type onto a built-in data type. + +2.1.3. String and similar data + + Many of the GSSAPI routines take arguments and return values that + describe contiguous multiple-byte data. All such data is passed + between the GSSAPI and the caller using the gss_buffer_t data type. + + + +Wray [Page 4] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + This data type is a pointer to a buffer descriptor, which consists of + a length field that contains the total number of bytes in the datum, + and a value field which contains a pointer to the actual datum: + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + Storage for data passed to the application by a GSSAPI routine using + the gss_buffer_t conventions is allocated by the GSSAPI routine. The + application may free this storage by invoking the gss_release_buffer + routine. Allocation of the gss_buffer_desc object is always the + responsibility of the application; Unused gss_buffer_desc objects + may be initialized to the value GSS_C_EMPTY_BUFFER. + +2.1.3.1. Opaque data types + + Certain multiple-word data items are considered opaque data types at + the GSSAPI, because their internal structure has no significance + either to the GSSAPI or to the caller. Examples of such opaque data + types are the input_token parameter to gss_init_sec_context (which is + opaque to the caller), and the input_message parameter to gss_seal + (which is opaque to the GSSAPI). Opaque data is passed between the + GSSAPI and the application using the gss_buffer_t datatype. + +2.1.3.2. Character strings + + Certain multiple-word data items may be regarded as simple ISO + Latin-1 character strings. An example of this is the + input_name_buffer parameter to gss_import_name. Some GSSAPI routines + also return character strings. Character strings are passed between + the application and the GSSAPI using the gss_buffer_t datatype, + defined earlier. + +2.1.4. Object Identifiers + + Certain GSSAPI procedures take parameters of the type gss_OID, or + Object identifier. This is a type containing ISO-defined tree- + structured values, and is used by the GSSAPI caller to select an + underlying security mechanism. A value of type gss_OID has the + following structure: + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + + + +Wray [Page 5] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The elements field of this structure points to the first byte of an + octet string containing the ASN.1 BER encoding of the value of the + gss_OID. The length field contains the number of bytes in this + value. For example, the gss_OID value corresponding to {iso(1) + identified- oganization(3) icd-ecma(12) member-company(2) dec(1011) + cryptoAlgorithms(7) SPX(5)} meaning SPX (Digital's X.509 + authentication mechanism) has a length field of 7 and an elements + field pointing to seven octets containing the following octal values: + 53,14,2,207,163,7,5. GSSAPI implementations should provide constant + gss_OID values to allow callers to request any supported mechanism, + although applications are encouraged on portability grounds to accept + the default mechanism. gss_OID values should also be provided to + allow applications to specify particular name types (see section + 2.1.10). Applications should treat gss_OID_desc values returned by + GSSAPI routines as read-only. In particular, the application should + not attempt to deallocate them. The gss_OID_desc datatype is + equivalent to the X/Open OM_object_identifier datatype [2]. + +2.1.5. Object Identifier Sets + + Certain GSSAPI procedures take parameters of the type gss_OID_set. + This type represents one or more object identifiers (section 2.1.4). + A gss_OID_set object has the following structure: + + typedef struct gss_OID_set_desc_struct { + int count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + The count field contains the number of OIDs within the set. The + elements field is a pointer to an array of gss_OID_desc objects, each + of which describes a single OID. gss_OID_set values are used to name + the available mechanisms supported by the GSSAPI, to request the use + of specific mechanisms, and to indicate which mechanisms a given + credential supports. Storage associated with gss_OID_set values + returned to the application by the GSSAPI may be deallocated by the + gss_release_oid_set routine. + +2.1.6. Credentials + + A credential handle is a caller-opaque atomic datum that identifies a + GSSAPI credential data structure. It is represented by the caller- + opaque type gss_cred_id_t, which may be implemented as either an + arithmetic or a pointer type. Credentials describe a principal, and + they give their holder the ability to act as that principal. The + GSSAPI does not make the actual credentials available to + applications; instead the credential handle is used to identify a + particular credential, held internally by GSSAPI or underlying + + + +Wray [Page 6] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + mechanism. Thus the credential handle contains no security-relavent + information, and requires no special protection by the application. + Depending on the implementation, a given credential handle may refer + to different credentials when presented to the GSSAPI by different + callers. Individual GSSAPI implementations should define both the + scope of a credential handle and the scope of a credential itself + (which must be at least as wide as that of a handle). Possibilities + for credential handle scope include the process that acquired the + handle, the acquiring process and its children, or all processes + sharing some local identification information (e.g., UID). If no + handles exist by which a given credential may be reached, the GSSAPI + may delete the credential. + + Certain routines allow credential handle parameters to be omitted to + indicate the use of a default credential. The mechanism by which a + default credential is established and its scope should be defined by + the individual GSSAPI implementation. + +2.1.7. Contexts + + The gss_ctx_id_t data type contains a caller-opaque atomic value that + identifies one end of a GSSAPI security context. It may be + implemented as either an arithmetic or a pointer type. Depending on + the implementation, a given gss_ctx_id_t value may refer to different + GSSAPI security contexts when presented to the GSSAPI by different + callers. The security context holds state information about each end + of a peer communication, including cryptographic state information. + Individual GSSAPI implementations should define the scope of a + context. Since no way is provided by which a new gss_ctx_id_t value + may be obtained for an existing context, the scope of a context + should be the same as the scope of a gss_ctx_id_t. + +2.1.8. Authentication tokens + + A token is a caller-opaque type that GSSAPI uses to maintain + synchronization between the context data structures at each end of a + GSSAPI security context. The token is a cryptographically protected + bit-string, generated by the underlying mechanism at one end of a + GSSAPI security context for use by the peer mechanism at the other + end. Encapsulation (if required) and transfer of the token are the + responsibility of the peer applications. A token is passed between + the GSSAPI and the application using the gss_buffer_t conventions. + +2.1.9. Status values + + One or more status codes are returned by each GSSAPI routine. Two + distinct sorts of status codes are returned. These are termed GSS + status codes and Mechanism status codes. + + + +Wray [Page 7] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +2.1.9.1. GSS status codes + + GSSAPI routines return GSS status codes as their OM_uint32 function + value. These codes indicate errors that are independent of the + underlying mechanism used to provide the security service. The + errors that can be indicated via a GSS status code are either generic + API routine errors (errors that are defined in the GSSAPI + specification) or calling errors (errors that are specific to these + bindings). + + A GSS status code can indicate a single fatal generic API error from + the routine and a single calling error. In addition, supplementary + status information may be indicated via the setting of bits in the + supplementary info field of a GSS status code. + + These errors are encoded into the 32-bit GSS status code as follows: + + MSB LSB + |------------------------------------------------------------| + | Calling Error | Routine Error | Supplementary Info | + |------------------------------------------------------------| + Bit 31 24 23 16 15 0 + + Hence if a GSSAPI routine returns a GSS status code whose upper 16 + bits contain a non-zero value, the call failed. If the calling error + field is non-zero, the invoking application's call of the routine was + erroneous. Calling errors are defined in table 5-1. If the routine + error field is non-zero, the routine failed for one of the routine- + specific reasons listed below in table 5-2. Whether or not the upper + 16 bits indicate a failure or a success, the routine may indicate + additional information by setting bits in the supplementary info + field of the status code. The meaning of individual bits is listed + below in table 5-3. + + Table 5-1 Calling Errors + + Name Value in Meaning + Field + GSS_S_CALL_INACCESSIBLE_READ 1 A required input + parameter could + not be read. + GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output + parameter could + not be written. + GSS_S_CALL_BAD_STRUCTURE 3 A parameter was + malformed + + + + + +Wray [Page 8] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Table 5-2 Routine Errors + + Name Value in Meaning + Field + + GSS_S_BAD_MECH 1 An unsupported mechanism was + requested + GSS_S_BAD_NAME 2 An invalid name was supplied + GSS_S_BAD_NAMETYPE 3 A supplied name was of an + unsupported type + GSS_S_BAD_BINDINGS 4 Incorrect channel bindings + were supplied + GSS_S_BAD_STATUS 5 An invalid status code was + supplied + + GSS_S_BAD_SIG 6 A token had an invalid + signature + GSS_S_NO_CRED 7 No credentials were supplied + GSS_S_NO_CONTEXT 8 No context has been + established + GSS_S_DEFECTIVE_TOKEN 9 A token was invalid + GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid + GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials + have expired + GSS_S_CONTEXT_EXPIRED 12 The context has expired + GSS_S_FAILURE 13 Miscellaneous failure + (see text) + + Table 5-3 Supplementary Status Bits + + Name Bit Number Meaning + GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called + again to complete its + function. + See routine documentation for + detailed description. + GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of + an earlier token + GSS_S_OLD_TOKEN 2 The token's validity period + has expired + GSS_S_UNSEQ_TOKEN 3 A later token has already been + processed + + The routine documentation also uses the name GSS_S_COMPLETE, which is + a zero value, to indicate an absence of any API errors or + supplementary information bits. + + + + + +Wray [Page 9] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + All GSS_S_xxx symbols equate to complete OM_uint32 status codes, + rather than to bitfield values. For example, the actual value of the + symbol GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 + << 16. + + The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and + GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS + status code and removes all but the relevant field. For example, the + value obtained by applying GSS_ROUTINE_ERROR to a status code removes + the calling errors and supplementary info fields, leaving only the + routine errors field. The values delivered by these macros may be + directly compared with a GSS_S_xxx symbol of the appropriate type. + The macro GSS_ERROR() is also provided, which when applied to a GSS + status code returns a non-zero value if the status code indicated a + calling or routine error, and a zero value otherwise. + + A GSSAPI implementation may choose to signal calling errors in a + platform-specific manner instead of, or in addition to the routine + value; routine errors and supplementary info should be returned via + routine status values only. + +2.1.9.2. Mechanism-specific status codes + + GSSAPI routines return a minor_status parameter, which is used to + indicate specialized errors from the underlying security mechanism. + This parameter may contain a single mechanism-specific error, + indicated by a OM_uint32 value. + + The minor_status parameter will always be set by a GSSAPI routine, + even if it returns a calling error or one of the generic API errors + indicated above as fatal, although other output parameters may remain + unset in such cases. However, output parameters that are expected to + return pointers to storage allocated by a routine must always set set + by the routine, even in the event of an error, although in such cases + the GSSAPI routine may elect to set the returned parameter value to + NULL to indicate that no storage was actually allocated. Any length + field associated with such pointers (as in a gss_buffer_desc + structure) should also be set to zero in such cases. + + The GSS status code GSS_S_FAILURE is used to indicate that the + underlying mechanism detected an error for which no specific GSS + status code is defined. The mechanism status code will provide more + details about the error. + +2.1.10. Names + + A name is used to identify a person or entity. GSSAPI authenticates + the relationship between a name and the entity claiming the name. + + + +Wray [Page 10] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Two distinct representations are defined for names: + + (a) A printable form, for presentation to a user + + (b) An internal form, for presentation at the API + + The syntax of a printable name is defined by the GSSAPI + implementation, and may be dependent on local system configuration, + or on individual user preference. The internal form provides a + canonical representation of the name that is independent of + configuration. + + A given GSSAPI implementation may support names drawn from multiple + namespaces. In such an implementation, the internal form of the name + must include fields that identify the namespace from which the name + is drawn. The namespace from which a printable name is drawn is + specified by an accompanying object identifier. + + Routines (gss_import_name and gss_display_name) are provided to + convert names between their printable representations and the + gss_name_t type. gss_import_name may support multiple syntaxes for + each supported namespace, allowing users the freedom to choose a + preferred name representation. gss_display_name should use an + implementation-chosen preferred syntax for each supported name-type. + + Comparison of internal-form names is accomplished via the + gss_compare_names routine. This removes the need for the application + program to understand the syntaxes of the various printable names + that a given GSSAPI implementation may support. + + Storage is allocated by routines that return gss_name_t values. A + procedure, gss_release_name, is provided to free storage associated + with a name. + +2.1.11. Channel Bindings + + GSSAPI supports the use of user-specified tags to identify a given + context to the peer application. These tags are used to identify the + particular communications channel that carries the context. Channel + bindings are communicated to the GSSAPI using the following + structure: + + + + + + + + + + +Wray [Page 11] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + The initiator_addrtype and acceptor_addrtype fields denote the type + of addresses contained in the initiator_address and acceptor_address + buffers. The address type should be one of the following: + + GSS_C_AF_UNSPEC Unspecified address type + GSS_C_AF_LOCAL Host-local address type + GSS_C_AF_INET DARPA Internet address type + GSS_C_AF_IMPLINK ARPAnet IMP address type (eg IP) + GSS_C_AF_PUP pup protocols (eg BSP) address type + GSS_C_AF_CHAOS MIT CHAOS protocol address type + GSS_C_AF_NS XEROX NS address type + GSS_C_AF_NBS nbs address type + GSS_C_AF_ECMA ECMA address type + GSS_C_AF_DATAKIT datakit protocols address type + GSS_C_AF_CCITT CCITT protocols (eg X.25) + GSS_C_AF_SNA IBM SNA address type + GSS_C_AF_DECnet DECnet address type + GSS_C_AF_DLI Direct data link interface address type + GSS_C_AF_LAT LAT address type + GSS_C_AF_HYLINK NSC Hyperchannel address type + GSS_C_AF_APPLETALK AppleTalk address type + GSS_C_AF_BSC BISYNC 2780/3780 address type + GSS_C_AF_DSS Distributed system services address type + GSS_C_AF_OSI OSI TP4 address type + GSS_C_AF_X25 X25 + GSS_C_AF_NULLADDR No address specified + + Note that these name address families rather than specific addressing + formats. For address families that contain several alternative + address forms, the initiator_address and acceptor_address fields must + contain sufficient information to determine which address form is + used. When not otherwise specified, addresses should be specified in + network byte-order. + + Conceptually, the GSSAPI concatenates the initiator_addrtype, + initiator_address, acceptor_addrtype, acceptor_address and + application_data to form an octet string. The mechanism signs this + octet string, and binds the signature to the context establishment + token emitted by gss_init_sec_context. The same bindings are + presented by the context acceptor to gss_accept_sec_context, and a + + + +Wray [Page 12] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + signature is calculated in the same way. The calculated signature is + compared with that found in the token, and if the signatures differ, + gss_accept_sec_context will return a GSS_S_BAD_BINDINGS error, and + the context will not be established. Some mechanisms may include the + actual channel binding data in the token (rather than just a + signature); applications should therefore not use confidential data + as channel-binding components. Individual mechanisms may impose + additional constraints on addresses and address types that may appear + in channel bindings. For example, a mechanism may verify that the + initiator_address field of the channel bindings presented to + gss_init_sec_context contains the correct network address of the host + system. + +2.1.12. Optional parameters + + Various parameters are described as optional. This means that they + follow a convention whereby a default value may be requested. The + following conventions are used for omitted parameters. These + conventions apply only to those parameters that are explicitly + documented as optional. + +2.1.12.1. gss_buffer_t types + + Specify GSS_C_NO_BUFFER as a value. For an input parameter this + signifies that default behavior is requested, while for an output + parameter it indicates that the information that would be returned + via the parameter is not required by the application. + +2.1.12.2. Integer types (input) + + Individual parameter documentation lists values to be used to + indicate default actions. + +2.1.12.3. Integer types (output) + + Specify NULL as the value for the pointer. + +2.1.12.4. Pointer types + + Specify NULL as the value. + +2.1.12.5. Object IDs + + Specify GSS_C_NULL_OID as the value. + +2.1.12.6. Object ID Sets + + Specify GSS_C_NULL_OID_SET as the value. + + + +Wray [Page 13] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +2.1.12.7. Credentials + + Specify GSS_C_NO_CREDENTIAL to use the default credential handle. + +2.1.12.8. Channel Bindings + + Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings + are not to be used. + +3. GSSAPI routine descriptions + +2.1. gss_acquire_cred + + OM_uint32 gss_acquire_cred ( + OM_uint32 * minor_status, + gss_name_t desired_name, + OM_uint32 time_req, + gss_OID_set desired_mechs, + int cred_usage, + gss_cred_id_t * output_cred_handle, + gss_OID_set * actual_mechs, + OM_int32 * time_rec) + Purpose: + + Allows an application to acquire a handle for a pre-existing + credential by name. GSSAPI implementations must impose a local + access-control policy on callers of this routine to prevent + unauthorized callers from acquiring credentials to which they are not + entitled. This routine is not intended to provide a "login to the + network" function, as such a function would result in the creation of + new credentials rather than merely acquiring a handle to existing + credentials. Such functions, if required, should be defined in + implementation-specific extensions to the API. + + If credential acquisition is time-consuming for a mechanism, the + mechanism may chooses to delay the actual acquisition until the + credential is required (e.g., by gss_init_sec_context or + gss_accept_sec_context). Such mechanism-specific implementation + decisions should be invisible to the calling application; thus a call + of gss_inquire_cred immediately following the call of + gss_acquire_cred must return valid credential data, and may therefore + incur the overhead of a deferred credential acquisition. + + Parameters: + + desired_name gss_name_t, read + Name of principal whose credential + should be acquired + + + +Wray [Page 14] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + time_req integer, read + number of seconds that credentials + should remain valid + + desired_mechs Set of Object IDs, read + set of underlying security mechanisms that + may be used. GSS_C_NULL_OID_SET may be used + to obtain an implementation-specific default. + + cred_usage integer, read + GSS_C_BOTH - Credentials may be used + either to initiate or accept + security contexts. + GSS_C_INITIATE - Credentials will only be + used to initiate security + contexts. + GSS_C_ACCEPT - Credentials will only be used to + accept security contexts. + + output_cred_handle gss_cred_id_t, modify + The returned credential handle. + + actual_mechs Set of Object IDs, modify, optional + The set of mechanisms for which the + credential is valid. Specify NULL + if not required. + + time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid. If the + implementation does not support expiration of + credentials, the value GSS_C_INDEFINITE will + be returned. Specify NULL if not required + + minor_status Integer, modify + Mechanism specific status code. + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Unavailable mechanism requested + + GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is + not supported + + GSS_S_BAD_NAME Value supplied for desired_name parameter is + + + +Wray [Page 15] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ill-formed. + + GSS_S_FAILURE Unspecified failure. The minor_status parameter + contains more detailed information + +3.2. gss_release_cred + + OM_uint32 gss_release_cred ( + OM_uint32 * minor_status, + gss_cred_id_t * cred_handle) + + Purpose: + + Informs GSSAPI that the specified credential handle is no longer + required by the process. When all processes have released a + credential, it will be deleted. + + Parameters: + + cred_handle gss_cred_id_t, modify, optional + buffer containing opaque credential + handle. If GSS_C_NO_CREDENTIAL is supplied, + the default credential will be released + + minor_status integer, modify + Mechanism specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED Credentials could not be accessed. + + + + + + + + + + + + + + + + + +Wray [Page 16] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.3. gss_init_sec_context + + OM_uint32 gss_init_sec_context ( + OM_uint32 * minor_status, + gss_cred_id_t claimant_cred_handle, + gss_ctx_id_t * context_handle, + gss_name_t target_name, + gss_OID mech_type, + int req_flags, + int time_req, + gss_channel_bindings_t + input_chan_bindings, + gss_buffer_t input_token + gss_OID * actual_mech_type, + gss_buffer_t output_token, + int * ret_flags, + OM_uint32 * time_rec ) + + Purpose: + + Initiates the establishment of a security context between the + application and a remote peer. Initially, the input_token parameter + should be specified as GSS_C_NO_BUFFER. The routine may return a + output_token which should be transferred to the peer application, + where the peer application will present it to gss_accept_sec_context. + If no token need be sent, gss_init_sec_context will indicate this by + setting the length field of the output_token argument to zero. To + complete the context establishment, one or more reply tokens may be + required from the peer application; if so, gss_init_sec_context will + return a status indicating GSS_S_CONTINUE_NEEDED in which case it + should be called again when the reply token is received from the peer + application, passing the token to gss_init_sec_context via the + input_token parameters. + + The values returned via the ret_flags and time_rec parameters are not + defined unless the routine returns GSS_S_COMPLETE. + + Parameters: + + claimant_cred_handle gss_cred_id_t, read, optional + handle for credentials claimed. Supply + GSS_C_NO_CREDENTIAL to use default + credentials. + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned by first call in continuation calls. + + + +Wray [Page 17] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + target_name gss_name_t, read + Name of target + + mech_type OID, read, optional + Object ID of desired mechanism. Supply + GSS_C_NULL_OID to obtain an implementation + specific default + + req_flags bit-mask, read + Contains four independent flags, each of + which requests that the context support a + specific service option. Symbolic + names are provided for each flag, and the + symbolic names corresponding to the required + flags should be logically-ORed + together to form the bit-mask value. The + flags are: + + GSS_C_DELEG_FLAG + True - Delegate credentials to remote peer + False - Don't delegate + GSS_C_MUTUAL_FLAG + True - Request that remote peer + authenticate itself + False - Authenticate self to remote peer + only + GSS_C_REPLAY_FLAG + True - Enable replay detection for signed + or sealed messages + False - Don't attempt to detect + replayed messages + GSS_C_SEQUENCE_FLAG + True - Enable detection of out-of-sequence + signed or sealed messages + False - Don't attempt to detect + out-of-sequence messages + + time_req integer, read + Desired number of seconds for which context + should remain valid. Supply 0 to request a + default validity period. + + input_chan_bindings channel bindings, read + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. + + + + +Wray [Page 18] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + input_token buffer, opaque, read, optional (see text) + Token received from peer application. + Supply GSS_C_NO_BUFFER on initial call. + + actual_mech_type OID, modify + actual mechanism used. + + output_token buffer, opaque, modify + token to be sent to peer application. If + the length field of the returned buffer is + zero, no token need be sent to the peer + application. + + ret_flags bit-mask, modify + Contains six independent flags, each of which + indicates that the context supports a specific + service option. Symbolic names are provided + for each flag, and the symbolic names + corresponding to the required flags should be + logically-ANDed with the ret_flags value to test + whether a given option is supported by the + context. The flags are: + + GSS_C_DELEG_FLAG + True - Credentials were delegated to + the remote peer + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer has been asked to + authenticated itself + False - Remote peer has not been asked to + authenticate itself + GSS_C_REPLAY_FLAG + True - replay of signed or sealed messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence signed or sealed + messages will be detected + False - out-of-sequence messages will not + be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be + invoked by calling seal routine + False - No confidentiality service (via + seal) available. seal will provide + message encapsulation, data-origin + + + +Wray [Page 19] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + authentication and integrity + services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_sign or gss_seal + routines. + False - Per-message integrity service + unavailable. + + time_rec integer, modify, optional + number of seconds for which the context + will remain valid. If the implementation does + not support credential expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + minor_status integer, modify + Mechanism specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer + application is required to complete thecontext, and + that gss_init_sec_context must be called again with + that token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on + the input_token failed + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks + performed on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for context + initiation, or the credential handle did not + reference any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired + + GSS_S_BAD_BINDINGS The input_token contains different channel + bindings to those specified via the + input_chan_bindings parameter + + GSS_S_BAD_SIG The input_token contains an invalid signature, or a + signature that could not be verified + + + +Wray [Page 20] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error + during context establishment + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of + a token already processed. This is a fatal error + during context establishment. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did not + refer to a valid context + + GSS_S_BAD_NAMETYPE The provided target_name parameter contained an + invalid or unsupported type of name + + GSS_S_BAD_NAME The provided target_name parameter was ill-formed. + + GSS_S_FAILURE Failure. See minor_status for more information + +3.4. gss_accept_sec_context + + OM_uint32 gss_accept_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_cred_id_t verifier_cred_handle, + gss_buffer_t input_token_buffer + gss_channel_bindings_t + input_chan_bindings, + gss_name_t * src_name, + gss_OID * mech_type, + gss_buffer_t output_token, + int * ret_flags, + OM_uint32 * time_rec, + gss_cred_id_t * delegated_cred_handle) + + Purpose: + + Allows a remotely initiated security context between the application + and a remote peer to be established. The routine may return a + output_token which should be transferred to the peer application, + where the peer application will present it to gss_init_sec_context. + If no token need be sent, gss_accept_sec_context will indicate this + by setting the length field of the output_token argument to zero. To + complete the context establishment, one or more reply tokens may be + required from the peer application; if so, gss_accept_sec_context + will return a status flag of GSS_S_CONTINUE_NEEDED, in which case it + should be called again when the reply token is received from the peer + application, passing the token to gss_accept_sec_context via the + input_token parameters. + + + + +Wray [Page 21] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The values returned via the src_name, ret_flags, time_rec, and + delegated_cred_handle parameters are not defined unless the routine + returns GSS_S_COMPLETE. + + Parameters: + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned in subsequent calls. + + verifier_cred_handle gss_cred_id_t, read, optional + Credential handle claimed by context + acceptor. + Specify GSS_C_NO_CREDENTIAL to use default + credentials. If GSS_C_NO_CREDENTIAL is + specified, but the caller has no default + credentials established, an + implementation-defined default credential + may be used. + + input_token_buffer buffer, opaque, read + token obtained from remote application + + input_chan_bindings channel bindings, read + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. + + src_name gss_name_t, modify, optional + Authenticated name of context initiator. + After use, this name should be deallocated by + passing it to gss_release_name. If not required, + specify NULL. + + mech_type Object ID, modify + Security mechanism used. The returned + OID value will be a pointer into static + storage, and should be treated as read-only + by the caller. + + output_token buffer, opaque, modify + Token to be passed to peer application. If the + length field of the returned token buffer is 0, + then no token need be passed to the peer + application. + + + + +Wray [Page 22] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ret_flags bit-mask, modify + Contains six independent flags, each of + which indicates that the context supports a + specific service option. Symbolic names are + provided for each flag, and the symbolic names + corresponding to the required flags + should be logically-ANDed with the ret_flags + value to test whether a given option is + supported by the context. The flags are: + GSS_C_DELEG_FLAG + True - Delegated credentials are available + via the delegated_cred_handle + parameter + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer asked for mutual + authentication + False - Remote peer did not ask for mutual + authentication + GSS_C_REPLAY_FLAG + True - replay of signed or sealed messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence signed or sealed + messages will be detected + False - out-of-sequence messages will not + be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be + invoked by calling seal routine + False - No confidentiality service (via + seal) available. seal will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked + by calling either gss_sign or + gss_seal routines. + False - Per-message integrity service + unavailable. + + time_rec integer, modify, optional + number of seconds for which the context + will remain valid. Specify NULL if not required. + + + + +Wray [Page 23] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + delegated_cred_handle + gss_cred_id_t, modify + credential handle for credentials received from + context initiator. Only valid if deleg_flag in + ret_flags is true. + + minor_status integer, modify + Mechanism specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer + application is required to complete the context, + and that gss_accept_sec_context must be called + again with that token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks + performed on the input_token failed. + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks + performed on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for + context acceptance, or the credential handle + did not reference any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have + expired. + + GSS_S_BAD_BINDINGS The input_token contains different channel + bindings to those specified via the + input_chan_bindings parameter. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did + not refer to a valid context. + + GSS_S_BAD_SIG The input_token contains an invalid signature. + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal + error during context establishment. + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a + duplicate of a token already processed. This + is a fatal error during context establishment. + + + +Wray [Page 24] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.5. gss_process_context_token + + OM_uint32 gss_process_context_token ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t token_buffer) + + Purpose: + + Provides a way to pass a token to the security service. Usually, + tokens are associated either with context establishment (when they + would be passed to gss_init_sec_context or gss_accept_sec_context) or + with per-message security service (when they would be passed to + gss_verify or gss_unseal). Occasionally, tokens may be received at + other times, and gss_process_context_token allows such tokens to be + passed to the underlying security service for processing. At + present, such additional tokens may only be generated by + gss_delete_sec_context. GSSAPI implementation may use this service + to implement deletion of the security context. + + Parameters: + + context_handle gss_ctx_id_t, read + context handle of context on which token is to + be processed + + token_buffer buffer, opaque, read + pointer to first byte of token to process + + minor_status integer, modify + Implementation specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks + performed on the token failed + + GSS_S_FAILURE Failure. See minor_status for more information + + GSS_S_NO_CONTEXT The context_handle did not refer to a valid + context + + + + +Wray [Page 25] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.6. gss_delete_sec_context + + OM_uint32 gss_delete_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_buffer_t output_token) + + Purpose: + + Delete a security context. gss_delete_sec_context will delete the + local data structures associated with the specified security context, + and generate an output_token, which when passed to the peer + gss_process_context_token will instruct it to do likewise. No + further security services may be obtained using the context specified + by context_handle. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, modify + context handle identifying context to delete. + + output_token buffer, opaque, modify + token to be sent to remote application to + instruct it to also delete the context + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_FAILURE Failure, see minor_status for more information + + GSS_S_NO_CONTEXT No valid context was supplied + +3.7. gss_context_time + + OM_uint32 gss_context_time ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + OM_uint32 * time_rec) + Purpose: + + Determines the number of seconds for which the specified context will + remain valid. + + + +Wray [Page 26] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Parameters: + + minor_status integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context to be interrogated. + + time_rec integer, modify + Number of seconds that the context will remain + valid. If the context has already expired, + zero will be returned. + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + +3.8. gss_sign + + OM_uint32 gss_sign ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + int qop_req, + gss_buffer_t message_buffer, + gss_buffer_t msg_token) + Purpose: + + Generates a cryptographic signature for the supplied message, and + places the signature in a token for transfer to the peer application. + The qop_req parameter allows a choice between several cryptographic + algorithms, if supported by the chosen mechanism. + + Parameters: + + minor_status integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + + + +Wray [Page 27] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + will be sent + + qop_req integer, read, optional + Specifies requested quality of protection. + Callers are encouraged, on portability grounds, + to accept the default quality of protection + offered by the chosen mechanism, which may be + requested by specifying GSS_C_QOP_DEFAULT for + this parameter. If an unsupported protection + strength is requested, gss_sign will return a + major_status of GSS_S_FAILURE. + + message_buffer buffer, opaque, read + message to be signed + + msg_token buffer, opaque, modify + buffer to receive token + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.9. gss_verify + + OM_uint32 gss_verify ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t message_buffer, + gss_buffer_t token_buffer, + int * qop_state) + Purpose: + + Verifies that a cryptographic signature, contained in the token + parameter, fits the supplied message. The qop_state parameter allows + a message recipient to determine the strength of protection that was + applied to the message. + + + +Wray [Page 28] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + arrived + + message_buffer buffer, opaque, read + message to be verified + + token_buffer buffer, opaque, read + token associated with message + + qop_state integer, modify + quality of protection gained from signature + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The signature was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct + signature for the message, but it had already + been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct + signature for the message, but it is too old + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct + signature for the message, but has been + verified out of sequence; an earlier token has + been signed or sealed by the remote + application, but not yet been processed + locally. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + + + + +Wray [Page 29] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.10. gss_seal + + OM_uint32 gss_seal ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + int conf_req_flag, + int qop_req + gss_buffer_t input_message_buffer, + int * conf_state, + gss_buffer_t output_message_buffer) + + Purpose: + + Cryptographically signs and optionally encrypts the specified + input_message. The output_message contains both the signature and + the message. The qop_req parameter allows a choice between several + cryptographic algorithms, if supported by the chosen mechanism. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + will be sent + + conf_req_flag boolean, read + True - Both confidentiality and integrity + services are requested + False - Only integrity service is requested + + qop_req integer, read, optional + Specifies required quality of protection. A + mechanism-specific default may be requested by + setting qop_req to GSS_C_QOP_DEFAULT. If an + unsupported protection strength is requested, + gss_seal will return a major_status of + GSS_S_FAILURE. + + input_message_buffer buffer, opaque, read + message to be sealed + + + + +Wray [Page 30] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + conf_state boolean, modify + True - Confidentiality, data origin + authentication and integrity services + have been applied + False - Integrity and data origin services only + has been applied. + + output_message_buffer buffer, opaque, modify + buffer to receive sealed message + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.11. gss_unseal + + OM_uint32 gss_unseal ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t input_message_buffer, + gss_buffer_t output_message_buffer, + int * conf_state, + int * qop_state) + + Purpose: + + Converts a previously sealed message back to a usable form, verifying + the embedded signature. The conf_state parameter indicates whether + the message was encrypted; the qop_state parameter indicates the + strength of protection that was used to provide the confidentiality + and integrity services. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + + +Wray [Page 31] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + context_handle gss_ctx_id_t, read + identifies the context on which the message + arrived + + input_message_buffer buffer, opaque, read + sealed message + + output_message_buffer buffer, opaque, modify + buffer to receive unsealed message + + conf_state boolean, modify + True - Confidentiality and integrity protection + were used + False - Inteegrity service only was used + + qop_state integer, modify + quality of protection gained from signature + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The signature was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a + correct signature for the message, but it had + already been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct + signature for the message, but it is too old + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct + signature for the message, but has been + verified out of sequence; an earlier token has + been signed or sealed by the remote + application, but not yet been processed + locally. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + + + + +Wray [Page 32] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.12. gss_display_status + + OM_uint32 gss_display_status ( + OM_uint32 * minor_status, + int status_value, + int status_type, + gss_OID mech_type, + int * message_context, + gss_buffer_t status_string) + + Purpose: + + Allows an application to obtain a textual representation of a GSSAPI + status code, for display to the user or for logging purposes. Since + some status values may indicate multiple errors, applications may + need to call gss_display_status multiple times, each call generating + a single text string. The message_context parameter is used to + indicate which error message should be extracted from a given + status_value; message_context should be initialized to 0, and + gss_display_status will return a non-zero value if there are further + messages to extract. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + status_value integer, read + Status value to be converted + + status_type integer, read + GSS_C_GSS_CODE - status_value is a GSS status + code + GSS_C_MECH_CODE - status_value is a mechanism + status code + + mech_type Object ID, read, optional + Underlying mechanism (used to interpret a + minor status value) Supply GSS_C_NULL_OID to + obtain the system default. + + message_context integer, read/modify + Should be initialized to zero by caller + + + +Wray [Page 33] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + on first call. If further messages are + contained in the status_value parameter, + message_context will be non-zero on return, + and this value should be passed back to + subsequent calls, along with the same + status_value, status_type and mech_type + parameters. + + status_string buffer, character string, modify + textual interpretation of the status_value + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Indicates that translation in accordance with + an unsupported mechanism type was requested + + GSS_S_BAD_STATUS The status value was not recognized, or the + status type was neither GSS_C_GSS_CODE nor + GSS_C_MECH_CODE. + + +3.13. gss_indicate_mechs + + OM_uint32 gss_indicate_mechs ( + OM_uint32 * minor_status, + gss_OID_set * mech_set) + + Purpose: + + Allows an application to determine which underlying security + mechanisms are available. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + mech_set set of Object IDs, modify + set of implementation-supported mechanisms. + The returned gss_OID_set value will be a + pointer into static storage, and should be + treated as read-only by the caller. + + + + + +Wray [Page 34] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + +3.14. gss_compare_name + + OM_uint32 gss_compare_name ( + OM_uint32 * minor_status, + gss_name_t name1, + gss_name_t name2, + int * name_equal) + + Purpose: + + Allows an application to compare two internal-form names to determine + whether they refer to the same entity. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + name1 gss_name_t, read + internal-form name + + name2 gss_name_t, read + internal-form name + + name_equal boolean, modify + True - names refer to same entity + False - names refer to different entities + (strictly, the names are not known to + refer to the same identity). + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The type contained within either name1 or + name2 was unrecognized, or the names were of + incomparable types. + + GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed + + + + + +Wray [Page 35] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.15. gss_display_name + + OM_uint32 gss_display_name ( + OM_uint32 * minor_status, + gss_name_t input_name, + gss_buffer_t output_name_buffer, + gss_OID * output_name_type) + + Purpose: + + Allows an application to obtain a textual representation of an opaque + internal-form name for display purposes. The syntax of a printable + name is defined by the GSSAPI implementation. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + input_name gss_name_t, read + name to be displayed + + output_name_buffer buffer, character-string, modify + buffer to receive textual name string + + output_name_type Object ID, modify + The type of the returned name. The returned + gss_OID will be a pointer into static storage, + and should be treated as read-only by the caller + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The type of input_name was not recognized + + GSS_S_BAD_NAME input_name was ill-formed + +3.16. gss_import_name + + OM_uint32 gss_import_name ( + OM_uint32 * minor_status, + gss_buffer_t input_name_buffer, + gss_OID input_name_type, + gss_name_t * output_name) + + + + +Wray [Page 36] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Purpose: + + Convert a printable name to internal form. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + input_name_buffer buffer, character-string, read + buffer containing printable name to convert + + input_name_type Object ID, read, optional + Object Id specifying type of printable + name. Applications may specify either + GSS_C_NULL_OID to use a local system-specific + printable syntax, or an OID registered by the + GSSAPI implementation to name a particular + namespace. + + output_name gss_name_t, modify + returned name in internal form + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The input_name_type was unrecognized + + GSS_S_BAD_NAME The input_name parameter could not be + interpreted as a name of the specified type + +3.17. gss_release_name + + OM_uint32 gss_release_name ( + OM_uint32 * minor_status, + gss_name_t * name) + + Purpose: + + Free GSSAPI-allocated storage associated with an internal form name. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + + +Wray [Page 37] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + name gss_name_t, modify + The name to be deleted + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The name parameter did not contain a valid name + +3.18. gss_release_buffer + + OM_uint32 gss_release_buffer ( + OM_uint32 * minor_status, + gss_buffer_t buffer) + + Purpose: + + Free storage associated with a buffer format name. The storage must + have been allocated by a GSSAPI routine. In addition to freeing the + associated storage, the routine will zero the length field in the + buffer parameter. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + buffer buffer, modify + The storage associated with the buffer will be + deleted. The gss_buffer_desc object will not + be freed, but its length field will be zeroed. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + +3.19. gss_release_oid_set + + OM_uint32 gss_release_oid_set ( + OM_uint32 * minor_status, + gss_OID_set * set) + + Purpose: + + + + +Wray [Page 38] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Free storage associated with a gss_OID_set object. The storage must + have been allocated by a GSSAPI routine. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + set Set of Object IDs, modify + The storage associated with the gss_OID_set + will be deleted. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + +3.20. gss_inquire_cred + + OM_uint32 gss_inquire_cred ( + OM_uint32 * minor_status, + gss_cred_id_t cred_handle, + gss_name_t * name, + OM_uint32 * lifetime, + int * cred_usage, + gss_OID_set * mechanisms ) + + Purpose: + + Obtains information about a credential. The caller must already have + obtained a handle that refers to the credential. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + cred_handle gss_cred_id_t, read + A handle that refers to the target credential. + Specify GSS_C_NO_CREDENTIAL to inquire about + the default credential. + + name gss_name_t, modify + The name whose identity the credential asserts. + Specify NULL if not required. + + lifetime Integer, modify + + + +Wray [Page 39] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The number of seconds for which the credential + will remain valid. If the credential has + expired, this parameter will be set to zero. + If the implementation does not support + credential expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + cred_usage Integer, modify + How the credential may be used. One of the + following: + GSS_C_INITIATE + GSS_C_ACCEPT + GSS_C_BOTH + Specify NULL if not required. + + mechanisms gss_OID_set, modify + Set of mechanisms supported by the credential. + Specify NULL if not required. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED The referenced credentials could not be + accessed. + + GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were + invalid. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. + If the lifetime parameter was not passed as + NULL, it will be set to 0. + + + #ifndef GSSAPI_H_ + #define GSSAPI_H_ + + /* + * First, define the platform-dependent types. + */ + typedef OM_uint32; + typedef gss_ctx_id_t; + typedef gss_cred_id_t; + typedef gss_name_t; + + + + +Wray [Page 40] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + /* + * Note that a platform supporting the xom.h X/Open header file + * may make use of that header for the definitions of OM_uint32 + * and the structure to which gss_OID_desc equates. + */ + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + typedef struct gss_OID_set_desc_struct { + int count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + + /* + * Six independent flags each of which indicates that a context + * supports a specific service option. + */ + #define GSS_C_DELEG_FLAG 1 + #define GSS_C_MUTUAL_FLAG 2 + #define GSS_C_REPLAY_FLAG 4 + #define GSS_C_SEQUENCE_FLAG 8 + #define GSS_C_CONF_FLAG 16 + #define GSS_C_INTEG_FLAG 32 + + + /* + * Credential usage options + */ + #define GSS_C_BOTH 0 + #define GSS_C_INITIATE 1 + #define GSS_C_ACCEPT 2 + + + +Wray [Page 41] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + /* + * Status code types for gss_display_status + */ + #define GSS_C_GSS_CODE 1 + #define GSS_C_MECH_CODE 2 + + /* + * The constant definitions for channel-bindings address families + */ + #define GSS_C_AF_UNSPEC 0; + #define GSS_C_AF_LOCAL 1; + #define GSS_C_AF_INET 2; + #define GSS_C_AF_IMPLINK 3; + #define GSS_C_AF_PUP 4; + #define GSS_C_AF_CHAOS 5; + #define GSS_C_AF_NS 6; + #define GSS_C_AF_NBS 7; + #define GSS_C_AF_ECMA 8; + #define GSS_C_AF_DATAKIT 9; + #define GSS_C_AF_CCITT 10; + #define GSS_C_AF_SNA 11; + #define GSS_C_AF_DECnet 12; + #define GSS_C_AF_DLI 13; + #define GSS_C_AF_LAT 14; + #define GSS_C_AF_HYLINK 15; + #define GSS_C_AF_APPLETALK 16; + #define GSS_C_AF_BSC 17; + #define GSS_C_AF_DSS 18; + #define GSS_C_AF_OSI 19; + #define GSS_C_AF_X25 21; + + #define GSS_C_AF_NULLADDR 255; + + #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) + #define GSS_C_NULL_OID ((gss_OID) 0) + #define GSS_C_NULL_OID_SET ((gss_OID_set) 0) + #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) + #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) + #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) + #define GSS_C_EMPTY_BUFFER {0, NULL} + + /* + * Define the default Quality of Protection for per-message + * services. Note that an implementation that offers multiple + * levels of QOP may either reserve a value (for example zero, + * as assumed here) to mean "default protection", or alternatively + * may simply equate GSS_C_QOP_DEFAULT to a specific explicit QOP + * value. + + + +Wray [Page 42] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + */ + #define GSS_C_QOP_DEFAULT 0 + + /* + * Expiration time of 2^32-1 seconds means infinite lifetime for a + * credential or security context + */ + #define GSS_C_INDEFINITE 0xfffffffful + + + /* Major status codes */ + + #define GSS_S_COMPLETE 0 + + /* + * Some "helper" definitions to make the status code macros obvious. + */ + #define GSS_C_CALLING_ERROR_OFFSET 24 + #define GSS_C_ROUTINE_ERROR_OFFSET 16 + #define GSS_C_SUPPLEMENTARY_OFFSET 0 + #define GSS_C_CALLING_ERROR_MASK 0377ul + #define GSS_C_ROUTINE_ERROR_MASK 0377ul + #define GSS_C_SUPPLEMENTARY_MASK 0177777ul + + /* + * The macros that test status codes for error conditions + */ + #define GSS_CALLING_ERROR(x) \ + (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) + #define GSS_ROUTINE_ERROR(x) \ + (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) + #define GSS_SUPPLEMENTARY_INFO(x) \ + (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) + #define GSS_ERROR(x) \ + ((GSS_CALLING_ERROR(x) != 0) || (GSS_ROUTINE_ERROR(x) != 0)) + + + /* + * Now the actual status code definitions + */ + + /* + * Calling errors: + */ + #define GSS_S_CALL_INACCESSIBLE_READ \ + (1ul << GSS_C_CALLING_ERROR_OFFSET) + #define GSS_S_CALL_INACCESSIBLE_WRITE \ + (2ul << GSS_C_CALLING_ERROR_OFFSET) + + + +Wray [Page 43] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + #define GSS_S_CALL_BAD_STRUCTURE \ + (3ul << GSS_C_CALLING_ERROR_OFFSET) + + /* + * Routine errors: + */ + #define GSS_S_BAD_MECH (1ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAME (2ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAMETYPE (3ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_BINDINGS (4ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_STATUS (5ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_SIG (6ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NO_CRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NO_CONTEXT (8ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_TOKEN (9ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CREDENTIALS_EXPIRED (11ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CONTEXT_EXPIRED (12ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_FAILURE (13ul << GSS_C_ROUTINE_ERROR_OFFSET) + + /* + * Supplementary info bits: + */ + #define GSS_S_CONTINUE_NEEDED (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) + #define GSS_S_DUPLICATE_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) + #define GSS_S_OLD_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) + #define GSS_S_UNSEQ_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) + + + /* + * Finally, function prototypes for the GSSAPI routines. + */ + + OM_uint32 gss_acquire_cred + (OM_uint32*, /* minor_status */ + gss_name_t, /* desired_name */ + OM_uint32, /* time_req */ + gss_OID_set, /* desired_mechs */ + int, /* cred_usage */ + gss_cred_id_t*, /* output_cred_handle */ + gss_OID_set*, /* actual_mechs */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_release_cred, + (OM_uint32*, /* minor_status */ + gss_cred_id_t* /* cred_handle */ + ); + + + +Wray [Page 44] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_init_sec_context + (OM_uint32*, /* minor_status */ + gss_cred_id_t, /* claimant_cred_handle */ + gss_ctx_id_t*, /* context_handle */ + gss_name_t, /* target_name */ + gss_OID, /* mech_type */ + int, /* req_flags */ + OM_uint32, /* time_req */ + gss_channel_bindings_t, + /* input_chan_bindings */ + gss_buffer_t, /* input_token */ + gss_OID*, /* actual_mech_type */ + gss_buffer_t, /* output_token */ + int*, /* ret_flags */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_accept_sec_context + (OM_uint32*, /* minor_status */ + gss_ctx_id_t*, /* context_handle */ + gss_cred_id_t, /* verifier_cred_handle */ + gss_buffer_t, /* input_token_buffer */ + gss_channel_bindings_t, + /* input_chan_bindings */ + gss_name_t*, /* src_name */ + gss_OID*, /* mech_type */ + gss_buffer_t, /* output_token */ + int*, /* ret_flags */ + OM_uint32*, /* time_rec */ + gss_cred_id_t* /* delegated_cred_handle */ + ); + + OM_uint32 gss_process_context_token + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t /* token_buffer */ + ); + + OM_uint32 gss_delete_sec_context + (OM_uint32*, /* minor_status */ + gss_ctx_id_t*, /* context_handle */ + gss_buffer_t /* output_token */ + ); + + + + + + + + +Wray [Page 45] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_context_time + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_sign + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* qop_req */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t /* message_token */ + ); + + OM_uitn32 gss_verify + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t, /* token_buffer */ + int* /* qop_state */ + ); + + OM_uint32 gss_seal + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + int, /* qop_req */ + gss_buffer_t, /* input_message_buffer */ + int*, /* conf_state */ + gss_buffer_t /* output_message_buffer */ + ); + + OM_uint32 gss_unseal + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* input_message_buffer */ + gss_buffer_t, /* output_message_buffer */ + int*, /* conf_state */ + int* /* qop_state */ + ); + + + + + + + + + + + +Wray [Page 46] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_display_status + (OM_uint32*, /* minor_status */ + OM_uint32, /* status_value */ + int, /* status_type */ + gss_OID, /* mech_type */ + int*, /* message_context */ + gss_buffer_t /* status_string */ + ); + + OM_uint32 gss_indicate_mechs + (OM_uint32*, /* minor_status */ + gss_OID_set* /* mech_set */ + ); + + OM_uint32 gss_compare_name + (OM_uint32*, /* minor_status */ + gss_name_t, /* name1 */ + gss_name_t, /* name2 */ + int* /* name_equal */ + ); + + OM_uint32 gss_display_name, + (OM_uint32*, /* minor_status */ + gss_name_t, /* input_name */ + gss_buffer_t, /* output_name_buffer */ + gss_OID* /* output_name_type */ + ); + + OM_uint32 gss_import_name + (OM_uint32*, /* minor_status */ + gss_buffer_t, /* input_name_buffer */ + gss_OID, /* input_name_type */ + gss_name_t* /* output_name */ + ); + + OM_uint32 gss_release_name + (OM_uint32*, /* minor_status */ + gss_name_t* /* input_name */ + ); + + OM_uint32 gss_release_buffer + (OM_uint32*, /* minor_status */ + gss_buffer_t /* buffer */ + ); + + OM_uint32 gss_release_oid_set + (OM_uint32*, /* minor_status */ + gss_OID_set* /* set */ + + + +Wray [Page 47] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ); + + OM_uint32 gss_inquire_cred + (OM_uint32 *, /* minor_status */ + gss_cred_id_t, /* cred_handle */ + gss_name_t *, /* name */ + OM_uint32 *, /* lifetime */ + int *, /* cred_usage */ + gss_OID_set * /* mechanisms */ + ); + + + + #endif /* GSSAPI_H_ */ + +References + + [1] Linn, J., "Generic Security Service Application Program + Interface", RFC 1508, Geer Zolot Associate, September 1993. + + [2] "OSI Object Management API Specification, Version 2.0 t", X.400 + API Association & X/Open Company Limited, August 24, 1990. + Specification of datatypes and routines for manipulating + information objects. + +Security Considerations + + Security issues are discussed throughout this memo. + +Author's Address + + John Wray + Digital Equipment Corporation + 550 King Street, LKG2-2/AA6 + Littleton, MA 01460 + USA + + Phone: +1-508-486-5210 + EMail: Wray@tuxedo.enet.dec.com + + + + + + + + + + + + +Wray [Page 48] + \ No newline at end of file diff --git a/doc/standardisation/rfc1964.txt b/doc/standardisation/rfc1964.txt new file mode 100644 index 000000000..f2960b961 --- /dev/null +++ b/doc/standardisation/rfc1964.txt @@ -0,0 +1,1123 @@ + + + + + + +Network Working Group J. Linn +Request for Comments: 1964 OpenVision Technologies +Category: Standards Track June 1996 + + + The Kerberos Version 5 GSS-API Mechanism + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +ABSTRACT + + This specification defines protocols, procedures, and conventions to + be employed by peers implementing the Generic Security Service + Application Program Interface (as specified in RFCs 1508 and 1509) + when using Kerberos Version 5 technology (as specified in RFC 1510). + +ACKNOWLEDGMENTS + + Much of the material in this memo is based on working documents + drafted by John Wray of Digital Equipment Corporation and on + discussions, implementation activities, and interoperability testing + involving Marc Horowitz, Ted Ts'o, and John Wray. Particular thanks + are due to each of these individuals for their contributions towards + development and availability of GSS-API support within the Kerberos + Version 5 code base. + +1. Token Formats + + This section discusses protocol-visible characteristics of the GSS- + API mechanism to be implemented atop Kerberos V5 security technology + per RFC-1508 and RFC-1510; it defines elements of protocol for + interoperability and is independent of language bindings per RFC- + 1509. + + Tokens transferred between GSS-API peers (for security context + management and per-message protection purposes) are defined. The + data elements exchanged between a GSS-API endpoint implementation and + the Kerberos KDC are not specific to GSS-API usage and are therefore + defined within RFC-1510 rather than within this specification. + + + + + + +Linn Standards Track [Page 1] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + To support ongoing experimentation, testing, and evolution of the + specification, the Kerberos V5 GSS-API mechanism as defined in this + and any successor memos will be identified with the following Object + Identifier, as defined in RFC-1510, until the specification is + advanced to the level of Proposed Standard RFC: + + {iso(1), org(3), dod(5), internet(1), security(5), kerberosv5(2)} + + Upon advancement to the level of Proposed Standard RFC, the Kerberos + V5 GSS-API mechanism will be identified by an Object Identifier + having the value: + + {iso(1) member-body(2) United States(840) mit(113554) infosys(1) + gssapi(2) krb5(2)} + +1.1. Context Establishment Tokens + + Per RFC-1508, Appendix B, the initial context establishment token + will be enclosed within framing as follows: + + InitialContextToken ::= + [APPLICATION 0] IMPLICIT SEQUENCE { + thisMech MechType + -- MechType is OBJECT IDENTIFIER + -- representing "Kerberos V5" + innerContextToken ANY DEFINED BY thisMech + -- contents mechanism-specific; + -- ASN.1 usage within innerContextToken + -- is not required + } + + The innerContextToken of the initial context token will consist of a + Kerberos V5 KRB_AP_REQ message, preceded by a two-byte token-id + (TOK_ID) field, which shall contain the value 01 00. + + The above GSS-API framing shall be applied to all tokens emitted by + the Kerberos V5 GSS-API mechanism, including KRB_AP_REP, KRB_ERROR, + context-deletion, and per-message tokens, not just to the initial + token in a context establishment sequence. While not required by + RFC-1508, this enables implementations to perform enhanced error- + checking. The innerContextToken field of context establishment tokens + for the Kerberos V5 GSS-API mechanism will contain a Kerberos message + (KRB_AP_REQ, KRB_AP_REP or KRB_ERROR), preceded by a 2-byte TOK_ID + field containing 01 00 for KRB_AP_REQ messages, 02 00 for KRB_AP_REP + messages and 03 00 for KRB_ERROR messages. + + + + + + +Linn Standards Track [Page 2] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +1.1.1. Initial Token + + Relevant KRB_AP_REQ syntax (from RFC-1510) is as follows: + + AP-REQ ::= [APPLICATION 14] SEQUENCE { + pvno [0] INTEGER, -- indicates Version 5 + msg-type [1] INTEGER, -- indicates KRB_AP_REQ + ap-options[2] APOptions, + ticket[3] Ticket, + authenticator[4] EncryptedData + } + + APOptions ::= BIT STRING { + reserved (0), + use-session-key (1), + mutual-required (2) + } + + Ticket ::= [APPLICATION 1] SEQUENCE { + tkt-vno [0] INTEGER, -- indicates Version 5 + realm [1] Realm, + sname [2] PrincipalName, + enc-part [3] EncryptedData + } + + -- Encrypted part of ticket + EncTicketPart ::= [APPLICATION 3] SEQUENCE { + flags[0] TicketFlags, + key[1] EncryptionKey, + crealm[2] Realm, + cname[3] PrincipalName, + transited[4] TransitedEncoding, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + caddr[9] HostAddresses OPTIONAL, + authorization-data[10] AuthorizationData OPTIONAL + } + + -- Unencrypted authenticator + Authenticator ::= [APPLICATION 2] SEQUENCE { + authenticator-vno[0] INTEGER, + crealm[1] Realm, + cname[2] PrincipalName, + cksum[3] Checksum OPTIONAL, + cusec[4] INTEGER, + ctime[5] KerberosTime, + + + +Linn Standards Track [Page 3] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + subkey[6] EncryptionKey OPTIONAL, + seq-number[7] INTEGER OPTIONAL, + authorization-data[8] AuthorizationData OPTIONAL + } + + For purposes of this specification, the authenticator shall include + the optional sequence number, and the checksum field shall be used to + convey channel binding, service flags, and optional delegation + information. The checksum will have a type of 0x8003 (a value being + registered within the Kerberos protocol specification), and a value + field of at least 24 bytes in length. The length of the value field + is extended beyond 24 bytes if and only if an optional facility to + carry a Kerberos-defined KRB_CRED message for delegation purposes is + supported by an implementation and active on a context. When + delegation is active, a TGT with its FORWARDABLE flag set will be + transferred within the KRB_CRED message. + + The checksum value field's format is as follows: + + Byte Name Description + 0..3 Lgth Number of bytes in Bnd field; + Currently contains hex 10 00 00 00 + (16, represented in little-endian form) + 4..19 Bnd MD5 hash of channel bindings, taken over all non-null + components of bindings, in order of declaration. + Integer fields within channel bindings are represented + in little-endian order for the purposes of the MD5 + calculation. + 20..23 Flags Bit vector of context-establishment flags, + with values consistent with RFC-1509, p. 41: + GSS_C_DELEG_FLAG: 1 + GSS_C_MUTUAL_FLAG: 2 + GSS_C_REPLAY_FLAG: 4 + GSS_C_SEQUENCE_FLAG: 8 + GSS_C_CONF_FLAG: 16 + GSS_C_INTEG_FLAG: 32 + The resulting bit vector is encoded into bytes 20..23 + in little-endian form. + 24..25 DlgOpt The Delegation Option identifier (=1) [optional] + 26..27 Dlgth The length of the Deleg field. [optional] + 28..n Deleg A KRB_CRED message (n = Dlgth + 29) [optional] + + In computing the contents of the "Bnd" field, the following detailed + points apply: + + (1) Each integer field shall be formatted into four bytes, using + little-endian byte ordering, for purposes of MD5 hash + computation. + + + +Linn Standards Track [Page 4] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + (2) All input length fields within gss_buffer_desc elements of a + gss_channel_bindings_struct, even those which are zero-valued, + shall be included in the hash calculation; the value elements of + gss_buffer_desc elements shall be dereferenced, and the + resulting data shall be included within the hash computation, + only for the case of gss_buffer_desc elements having non-zero + length specifiers. + + (3) If the caller passes the value GSS_C_NO_BINDINGS instead of + a valid channel bindings structure, the Bnd field shall be set + to 16 zero-valued bytes. + + In the initial Kerberos V5 GSS-API mechanism token (KRB_AP_REQ token) + from initiator to target, the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, + GSS_C_REPLAY_FLAG, and GSS_C_SEQUENCE_FLAG values shall each be set + as the logical AND of the initiator's corresponding request flag to + GSS_Init_sec_context() and a Boolean indicator of whether that + optional service is available to GSS_Init_sec_context()'s caller. + GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG, for which no corresponding + context-level input indicator flags to GSS_Init_sec_context() exist, + shall each be set to indicate whether their respective per-message + protection services are available for use on the context being + established. + + When input source address channel binding values are provided by a + caller (i.e., unless the input argument is GSS_C_NO_BINDINGS or the + source address specifier value within the input structure is + GSS_C_NULL_ADDRTYPE), and the corresponding token received from the + context's peer bears address restrictions, it is recommended that an + implementation of the Kerberos V5 GSS-API mechanism should check that + the source address as provided by the caller matches that in the + received token, and should return the GSS_S_BAD_BINDINGS major_status + value if a mismatch is detected. Note: discussion is ongoing about + the strength of recommendation to be made in this area, and on the + circumstances under which such a recommendation should be applicable; + implementors are therefore advised that changes on this matter may be + included in subsequent versions of this specification. + +1.1.2. Response Tokens + + A context establishment sequence based on the Kerberos V5 mechanism + will perform one-way authentication (without confirmation or any + return token from target to initiator in response to the initiator's + KRB_AP_REQ) if the mutual_req bit is not set in the application's + call to GSS_Init_sec_context(). Applications requiring confirmation + that their authentication was successful should request mutual + authentication, resulting in a "mutual-required" indication within + KRB_AP_REQ APoptions and the setting of the mutual_req bit in the + + + +Linn Standards Track [Page 5] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + flags field of the authenticator checksum. In response to such a + request, the context target will reply to the initiator with a token + containing either a KRB_AP_REP or KRB_ERROR, completing the mutual + context establishment exchange. + + Relevant KRB_AP_REP syntax is as follows: + + AP-REP ::= [APPLICATION 15] SEQUENCE { + pvno [0] INTEGER, -- represents Kerberos V5 + msg-type [1] INTEGER, -- represents KRB_AP_REP + enc-part [2] EncryptedData + } + + EncAPRepPart ::= [APPLICATION 27] SEQUENCE { + ctime [0] KerberosTime, + cusec [1] INTEGER, + subkey [2] EncryptionKey OPTIONAL, + seq-number [3] INTEGER OPTIONAL + } + + The optional seq-number element within the AP-REP's EncAPRepPart + shall be included. + + The syntax of KRB_ERROR is as follows: + + KRB-ERROR ::= [APPLICATION 30] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ctime[2] KerberosTime OPTIONAL, + cusec[3] INTEGER OPTIONAL, + stime[4] KerberosTime, + susec[5] INTEGER, + error-code[6] INTEGER, + crealm[7] Realm OPTIONAL, + cname[8] PrincipalName OPTIONAL, + realm[9] Realm, -- Correct realm + sname[10] PrincipalName, -- Correct name + e-text[11] GeneralString OPTIONAL, + e-data[12] OCTET STRING OPTIONAL + } + + Values to be transferred in the error-code field of a KRB-ERROR + message are defined in [RFC-1510], not in this specification. + + + + + + + + +Linn Standards Track [Page 6] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +1.2. Per-Message and Context Deletion Tokens + + Three classes of tokens are defined in this section: "MIC" tokens, + emitted by calls to GSS_GetMIC() (formerly GSS_Sign()) and consumed + by calls to GSS_VerifyMIC() (formerly GSS_Verify()), "Wrap" tokens, + emitted by calls to GSS_Wrap() (formerly GSS_Seal()) and consumed by + calls to GSS_Unwrap() (formerly GSS_Unseal()), and context deletion + tokens, emitted by calls to GSS_Delete_sec_context() and consumed by + calls to GSS_Process_context_token(). Note: References to GSS-API + per-message routines in the remainder of this specification will be + based on those routines' newer recommended names rather than those + names' predecessors. + + Several variants of cryptographic keys are used in generation and + processing of per-message tokens: + + (1) context key: uses Kerberos session key (or subkey, if + present in authenticator emitted by context initiator) directly + + (2) confidentiality key: forms variant of context key by + exclusive-OR with the hexadecimal constant f0f0f0f0f0f0f0f0. + + (3) MD2.5 seed key: forms variant of context key by reversing + the bytes of the context key (i.e. if the original key is the + 8-byte sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the seed key + will be {hh, gg, ff, ee, dd, cc, bb, aa}). + +1.2.1. Per-message Tokens - MIC + +Use of the GSS_GetMIC() call yields a token, separate from the user +data being protected, which can be used to verify the integrity of +that data as received. The token has the following format: + + Byte no Name Description + 0..1 TOK_ID Identification field. + Tokens emitted by GSS_GetMIC() contain + the hex value 01 01 in this field. + 2..3 SGN_ALG Integrity algorithm indicator. + 00 00 - DES MAC MD5 + 01 00 - MD2.5 + 02 00 - DES MAC + 4..7 Filler Contains ff ff ff ff + 8..15 SND_SEQ Sequence number field. + 16..23 SGN_CKSUM Checksum of "to-be-signed data", + calculated according to algorithm + specified in SGN_ALG field. + + + + + +Linn Standards Track [Page 7] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + GSS-API tokens must be encapsulated within the higher-level protocol + by the application; no embedded length field is necessary. + +1.2.1.1. Checksum + + Checksum calculation procedure (common to all algorithms): Checksums + are calculated over the data field, logically prepended by the first + 8 bytes of the plaintext packet header. The resulting value binds + the data to the packet type and signature algorithm identifier + fields. + + DES MAC MD5 algorithm: The checksum is formed by computing an MD5 + [RFC-1321] hash over the plaintext data, and then computing a DES-CBC + MAC on the 16-byte MD5 result. A standard 64-bit DES-CBC MAC is + computed per [FIPS-PUB-113], employing the context key and a zero IV. + The 8-byte result is stored in the SGN_CKSUM field. + + MD2.5 algorithm: The checksum is formed by first DES-CBC encrypting a + 16-byte zero-block, using a zero IV and a key formed by reversing the + bytes of the context key (i.e. if the original key is the 8-byte + sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the checksum key will be + {hh, gg, ff, ee, dd, cc, bb, aa}). The resulting 16-byte value is + logically prepended to the to-be-signed data. A standard MD5 + checksum is calculated over the combined data, and the first 8 bytes + of the result are stored in the SGN_CKSUM field. Note 1: we refer to + this algorithm informally as "MD2.5" to connote the fact that it uses + half of the 128 bits generated by MD5; use of only a subset of the + MD5 bits is intended to protect against the prospect that data could + be postfixed to an existing message with corresponding modifications + being made to the checksum. Note 2: This algorithm is fairly novel + and has received more limited evaluation than that to which other + integrity algorithms have been subjected. An initial, limited + evaluation indicates that it may be significantly weaker than DES MAC + MD5. + + DES-MAC algorithm: A standard 64-bit DES-CBC MAC is computed on the + plaintext data per [FIPS-PUB-113], employing the context key and a + zero IV. Padding procedures to accomodate plaintext data lengths + which may not be integral multiples of 8 bytes are defined in [FIPS- + PUB-113]. The result is an 8-byte value, which is stored in the + SGN_CKSUM field. Support for this algorithm may not be present in + all implementations. + +1.2.1.2. Sequence Number + + Sequence number field: The 8 byte plaintext sequence number field is + formed from the sender's four-byte sequence number as follows. If + the four bytes of the sender's sequence number are named s0, s1, s2 + + + +Linn Standards Track [Page 8] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + and s3 (from least to most significant), the plaintext sequence + number field is the 8 byte sequence: (s0, s1, s2, s3, di, di, di, + di), where 'di' is the direction-indicator (Hex 0 - sender is the + context initiator, Hex FF - sender is the context acceptor). The + field is then DES-CBC encrypted using the context key and an IV + formed from the first 8 bytes of the previously calculated SGN_CKSUM + field. After sending a GSS_GetMIC() or GSS_Wrap() token, the sender's + sequence number is incremented by one. + + The receiver of the token will first verify the SGN_CKSUM field. If + valid, the sequence number field may be decrypted and compared to the + expected sequence number. The repetition of the (effectively 1-bit) + direction indicator within the sequence number field provides + redundancy so that the receiver may verify that the decryption + succeeded. + + Since the checksum computation is used as an IV to the sequence + number decryption, attempts to splice a checksum and sequence number + from different messages will be detected. The direction indicator + will detect packets that have been maliciously reflected. + + The sequence number provides a basis for detection of replayed + tokens. Replay detection can be performed using state information + retained on received sequence numbers, interpreted in conjunction + with the security context on which they arrive. + + Provision of per-message replay and out-of-sequence detection + services is optional for implementations of the Kerberos V5 GSS-API + mechanism. Further, it is recommended that implementations of the + Kerberos V5 GSS-API mechanism which offer these services should honor + a caller's request that the services be disabled on a context. + Specifically, if replay_det_req_flag is input FALSE, replay_det_state + should be returned FALSE and the GSS_DUPLICATE_TOKEN and + GSS_OLD_TOKEN stati should not be indicated as a result of duplicate + detection when tokens are processed; if sequence_req_flag is input + FALSE, sequence_state should be returned FALSE and + GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN stati should + not be indicated as a result of out-of-sequence detection when tokens + are processed. + +1.2.2. Per-message Tokens - Wrap + + Use of the GSS_Wrap() call yields a token which encapsulates the + input user data (optionally encrypted) along with associated + integrity check quantities. The token emitted by GSS_Wrap() consists + of an integrity header whose format is identical to that emitted by + GSS_GetMIC() (except that the TOK_ID field contains the value 02 01), + followed by a body portion that contains either the plaintext data + + + +Linn Standards Track [Page 9] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + (if SEAL_ALG = ff ff) or encrypted data for any other supported value + of SEAL_ALG. Currently, only SEAL_ALG = 00 00 is supported, and + means that DES-CBC encryption is being used to protect the data. + + The GSS_Wrap() token has the following format: + + Byte no Name Description + 0..1 TOK_ID Identification field. + Tokens emitted by GSS_Wrap() contain + the hex value 02 01 in this field. + 2..3 SGN_ALG Checksum algorithm indicator. + 00 00 - DES MAC MD5 + 01 00 - MD2.5 + 02 00 - DES MAC + 4..5 SEAL_ALG ff ff - none + 00 00 - DES + 6..7 Filler Contains ff ff + 8..15 SND_SEQ Encrypted sequence number field. + 16..23 SGN_CKSUM Checksum of plaintext padded data, + calculated according to algorithm + specified in SGN_ALG field. + 24..last Data encrypted or plaintext padded data + + GSS-API tokens must be encapsulated within the higher-level protocol + by the application; no embedded length field is necessary. + +1.2.2.1. Checksum + + Checksum calculation procedure (common to all algorithms): Checksums + are calculated over the plaintext padded data field, logically + prepended by the first 8 bytes of the plaintext packet header. The + resulting signature binds the data to the packet type, protocol + version, and signature algorithm identifier fields. + + DES MAC MD5 algorithm: The checksum is formed by computing an MD5 + hash over the plaintext padded data, and then computing a DES-CBC MAC + on the 16-byte MD5 result. A standard 64-bit DES-CBC MAC is computed + per [FIPS-PUB-113], employing the context key and a zero IV. The 8- + byte result is stored in the SGN_CKSUM field. + + MD2.5 algorithm: The checksum is formed by first DES-CBC encrypting a + 16-byte zero-block, using a zero IV and a key formed by reversing the + bytes of the context key (i.e., if the original key is the 8-byte + sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the checksum key will be + {hh, gg, ff, ee, dd, cc, bb, aa}). The resulting 16-byte value is + logically pre-pended to the "to-be-signed data". A standard MD5 + checksum is calculated over the combined data, and the first 8 bytes + of the result are stored in the SGN_CKSUM field. + + + +Linn Standards Track [Page 10] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + DES-MAC algorithm: A standard 64-bit DES-CBC MAC is computed on the + plaintext padded data per [FIPS-PUB-113], employing the context key + and a zero IV. The plaintext padded data is already assured to be an + integral multiple of 8 bytes; no additional padding is required or + applied in order to accomplish MAC calculation. The result is an 8- + byte value, which is stored in the SGN_CKSUM field. Support for this + lgorithm may not be present in all implementations. + +1.2.2.2. Sequence Number + + Sequence number field: The 8 byte plaintext sequence number field is + formed from the sender's four-byte sequence number as follows. If + the four bytes of the sender's sequence number are named s0, s1, s2 + and s3 (from least to most significant), the plaintext sequence + number field is the 8 byte sequence: (s0, s1, s2, s3, di, di, di, + di), where 'di' is the direction-indicator (Hex 0 - sender is the + context initiator, Hex FF - sender is the context acceptor). + + The field is then DES-CBC encrypted using the context key and an IV + formed from the first 8 bytes of the SEAL_CKSUM field. + + After sending a GSS_GetMIC() or GSS_Wrap() token, the sender's + sequence numbers are incremented by one. + +1.2.2.3. Padding + + Data padding: Before encryption and/or signature calculation, + plaintext data is padded to the next highest multiple of 8 bytes, by + appending between 1 and 8 bytes, the value of each such byte being + the total number of pad bytes. For example, given data of length 20 + bytes, four pad bytes will be appended, and each byte will contain + the hex value 04. An 8-byte random confounder is prepended to the + data, and signatures are calculated over the resulting padded + plaintext. + + After padding, the data is encrypted according to the algorithm + specified in the SEAL_ALG field. For SEAL_ALG=DES (the only non-null + algorithm currently supported), the data is encrypted using DES-CBC, + with an IV of zero. The key used is derived from the established + context key by XOR-ing the context key with the hexadecimal constant + f0f0f0f0f0f0f0f0. + +1.2.3. Context deletion token + + The token emitted by GSS_Delete_sec_context() is based on the packet + format for tokens emitted by GSS_GetMIC(). The context-deletion + token has the following format: + + + + +Linn Standards Track [Page 11] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + Byte no Name Description + 0..1 TOK_ID Identification field. + Tokens emitted by + GSS_Delete_sec_context() contain + the hex value 01 02 in this field. + 2..3 SGN_ALG Integrity algorithm indicator. + 00 00 - DES MAC MD5 + 01 00 - MD2.5 + 02 00 - DES MAC + 4..7 Filler Contains ff ff ff ff + 8..15 SND_SEQ Sequence number field. + 16..23 SGN_CKSUM Checksum of "to-be-signed data", + calculated according to algorithm + specified in SGN_ALG field. + + SGN_ALG and SND_SEQ will be calculated as for tokens emitted by + GSS_GetMIC(). The SGN_CKSUM will be calculated as for tokens emitted + by GSS_GetMIC(), except that the user-data component of the "to-be- + signed" data will be a zero-length string. + +2. Name Types and Object Identifiers + + This section discusses the name types which may be passed as input to + the Kerberos V5 GSS-API mechanism's GSS_Import_name() call, and their + associated identifier values. It defines interface elements in + support of portability, and assumes use of C language bindings per + RFC-1509. In addition to specifying OID values for name type + identifiers, symbolic names are included and recommended to GSS-API + implementors in the interests of convenience to callers. It is + understood that not all implementations of the Kerberos V5 GSS-API + mechanism need support all name types in this list, and that + additional name forms will likely be added to this list over time. + Further, the definitions of some or all name types may later migrate + to other, mechanism-independent, specifications. The occurrence of a + name type in this specification is specifically not intended to + suggest that the type may be supported only by an implementation of + the Kerberos V5 mechanism. In particular, the occurrence of the + string "_KRB5_" in the symbolic name strings constitutes a means to + unambiguously register the name strings, avoiding collision with + other documents; it is not meant to limit the name types' usage or + applicability. + + For purposes of clarification to GSS-API implementors, this section's + discussion of some name forms describes means through which those + forms can be supported with existing Kerberos technology. These + discussions are not intended to preclude alternative implementation + strategies for support of the name forms within Kerberos mechanisms + or mechanisms based on other technologies. To enhance application + + + +Linn Standards Track [Page 12] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + portability, implementors of mechanisms are encouraged to support + name forms as defined in this section, even if their mechanisms are + independent of Kerberos V5. + +2.1. Mandatory Name Forms + + This section discusses name forms which are to be supported by all + conformant implementations of the Kerberos V5 GSS-API mechanism. + +2.1.1. Kerberos Principal Name Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + krb5(2) krb5_name(1)}. The recommended symbolic name for this type + is "GSS_KRB5_NT_PRINCIPAL_NAME". + + This name type corresponds to the single-string representation of a + Kerberos name. (Within the MIT Kerberos V5 implementation, such + names are parseable with the krb5_parse_name() function.) The + elements included within this name representation are as follows, + proceeding from the beginning of the string: + + (1) One or more principal name components; if more than one + principal name component is included, the components are + separated by `/`. Arbitrary octets may be included within + principal name components, with the following constraints and + special considerations: + + (1a) Any occurrence of the characters `@` or `/` within a + name component must be immediately preceded by the `\` + quoting character, to prevent interpretation as a component + or realm separator. + + (1b) The ASCII newline, tab, backspace, and null characters + may occur directly within the component or may be + represented, respectively, by `\n`, `\t`, `\b`, or `\0`. + + (1c) If the `\` quoting character occurs outside the contexts + described in (1a) and (1b) above, the following character is + interpreted literally. As a special case, this allows the + doubled representation `\\` to represent a single occurrence + of the quoting character. + + (1d) An occurrence of the `\` quoting character as the last + character of a component is illegal. + + + + + + +Linn Standards Track [Page 13] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + (2) Optionally, a `@` character, signifying that a realm name + immediately follows. If no realm name element is included, the + local realm name is assumed. The `/` , `:`, and null characters + may not occur within a realm name; the `@`, newline, tab, and + backspace characters may be included using the quoting + conventions described in (1a), (1b), and (1c) above. + +2.1.2. Host-Based Service Name Form + + This name form has been incorporated at the mechanism-independent + GSS-API level as of GSS-API, Version 2. This subsection retains the + Object Identifier and symbolic name assignments previously made at + the Kerberos V5 GSS-API mechanism level, and adopts the definition as + promoted to the mechanism-independent level. + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) service_name(4)}. The previously recommended symbolic + name for this type is "GSS_KRB5_NT_HOSTBASED_SERVICE_NAME". The + currently preferred symbolic name for this type is + "GSS_C_NT_HOSTBASED_SERVICE". + + This name type is used to represent services associated with host + computers. This name form is constructed using two elements, + "service" and "hostname", as follows: + + service@hostname + + When a reference to a name of this type is resolved, the "hostname" + is canonicalized by attempting a DNS lookup and using the fully- + qualified domain name which is returned, or by using the "hostname" + as provided if the DNS lookup fails. The canonicalization operation + also maps the host's name into lower-case characters. + + The "hostname" element may be omitted. If no "@" separator is + included, the entire name is interpreted as the service specifier, + with the "hostname" defaulted to the canonicalized name of the local + host. + + Values for the "service" element will be registered with the IANA. + +2.1.3. Exported Name Object Form for Kerberos V5 Mechanism + + Support for this name form is not required for GSS-V1 + implementations, but will be required for use in conjunction with the + GSS_Export_name() call planned for GSS-API Version 2. Use of this + name form will be signified by a "GSS-API Exported Name Object" OID + value which will be defined at the mechanism-independent level for + + + +Linn Standards Track [Page 14] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + GSS-API Version 2. + + This name type represents a self-describing object, whose framing + structure will be defined at the mechanism-independent level for + GSS-API Version 2. When generated by the Kerberos V5 mechanism, the + Mechanism OID within the exportable name shall be that of the + Kerberos V5 mechanism. The name component within the exportable name + shall be a contiguous string with structure as defined for the + Kerberos Principal Name Form. + + In order to achieve a distinguished encoding for comparison purposes, + the following additional constraints are imposed on the export + operation: + + (1) all occurrences of the characters `@`, `/`, and `\` within + principal components or realm names shall be quoted with an + immediately-preceding `\`. + + (2) all occurrences of the null, backspace, tab, or newline + characters within principal components or realm names will be + represented, respectively, with `\0`, `\b`, `\t`, or `\n`. + + (3) the `\` quoting character shall not be emitted within an + exported name except to accomodate cases (1) and (2). + +2.2. Optional Name Forms + + This section discusses additional name forms which may optionally be + supported by implementations of the Kerberos V5 GSS-API mechanism. + It is recognized that some of the name forms cited here are derived + from UNIX(tm) operating system platforms; some listed forms may be + irrelevant to non-UNIX platforms, and definition of additional forms + corresponding to such platforms may also be appropriate. It is also + recognized that OS-specific functions outside GSS-API are likely to + exist in order to perform translations among these forms, and that + GSS-API implementations supporting these forms may themselves be + layered atop such OS-specific functions. Inclusion of this support + within GSS-API implementations is intended as a convenience to + applications. + +2.2.1. User Name Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) user_name(1)}. The recommended symbolic name for this + type is "GSS_KRB5_NT_USER_NAME". + + This name type is used to indicate a named user on a local system. + + + +Linn Standards Track [Page 15] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + Its interpretation is OS-specific. This name form is constructed as: + + username + + Assuming that users' principal names are the same as their local + operating system names, an implementation of GSS_Import_name() based + on Kerberos V5 technology can process names of this form by + postfixing an "@" sign and the name of the local realm. + +2.2.2. Machine UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) machine_uid_name(2)}. The recommended symbolic name for + this type is "GSS_KRB5_NT_MACHINE_UID_NAME". + + This name type is used to indicate a numeric user identifier + corresponding to a user on a local system. Its interpretation is + OS-specific. The gss_buffer_desc representing a name of this type + should contain a locally-significant uid_t, represented in host byte + order. The GSS_Import_name() operation resolves this uid into a + username, which is then treated as the User Name Form. + +2.2.3. String UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) string_uid_name(3)}. The recommended symbolic name for + this type is "GSS_KRB5_NT_STRING_UID_NAME". + + This name type is used to indicate a string of digits representing + the numeric user identifier of a user on a local system. Its + interpretation is OS-specific. This name type is similar to the + Machine UID Form, except that the buffer contains a string + representing the uid_t. + +3. Credentials Management + + The Kerberos V5 protocol uses different credentials (in the GSSAPI + sense) for initiating and accepting security contexts. Normal + clients receive a ticket-granting ticket (TGT) and an associated + session key at "login" time; the pair of a TGT and its corresponding + session key forms a credential which is suitable for initiating + security contexts. A ticket-granting ticket, its session key, and + any other (ticket, key) pairs obtained through use of the ticket- + granting-ticket, are typically stored in a Kerberos V5 credentials + cache, sometimes known as a ticket file. + + + + +Linn Standards Track [Page 16] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + The encryption key used by the Kerberos server to seal tickets for a + particular application service forms the credentials suitable for + accepting security contexts. These service keys are typically stored + in a Kerberos V5 key table, or srvtab file. In addition to their use + as accepting credentials, these service keys may also be used to + obtain initiating credentials for their service principal. + + The Kerberos V5 mechanism's credential handle may contain references + to either or both types of credentials. It is a local matter how the + Kerberos V5 mechanism implementation finds the appropriate Kerberos + V5 credentials cache or key table. + + However, when the Kerberos V5 mechanism attempts to obtain initiating + credentials for a service principal which are not available in a + credentials cache, and the key for that service principal is + available in a Kerberos V5 key table, the mechanism should use the + service key to obtain initiating credentials for that service. This + should be accomplished by requesting a ticket-granting-ticket from + the Kerberos Key Distribution Center (KDC), and decrypting the KDC's + reply using the service key. + +4. Parameter Definitions + + This section defines parameter values used by the Kerberos V5 GSS-API + mechanism. It defines interface elements in support of portability, + and assumes use of C language bindings per RFC-1509. + +4.1. Minor Status Codes + + This section recommends common symbolic names for minor_status values + to be returned by the Kerberos V5 GSS-API mechanism. Use of these + definitions will enable independent implementors to enhance + application portability across different implementations of the + mechanism defined in this specification. (In all cases, + implementations of GSS_Display_status() will enable callers to + convert minor_status indicators to text representations.) Each + implementation should make available, through include files or other + means, a facility to translate these symbolic names into the concrete + values which a particular GSS-API implementation uses to represent + the minor_status values specified in this section. + + It is recognized that this list may grow over time, and that the need + for additional minor_status codes specific to particular + implementations may arise. It is recommended, however, that + implementations should return a minor_status value as defined on a + mechanism-wide basis within this section when that code is accurately + representative of reportable status rather than using a separate, + implementation-defined code. + + + +Linn Standards Track [Page 17] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +4.1.1. Non-Kerberos-specific codes + + GSS_KRB5_S_G_BAD_SERVICE_NAME + /* "No @ in SERVICE-NAME name string" */ + GSS_KRB5_S_G_BAD_STRING_UID + /* "STRING-UID-NAME contains nondigits" */ + GSS_KRB5_S_G_NOUSER + /* "UID does not resolve to username" */ + GSS_KRB5_S_G_VALIDATE_FAILED + /* "Validation error" */ + GSS_KRB5_S_G_BUFFER_ALLOC + /* "Couldn't allocate gss_buffer_t data" */ + GSS_KRB5_S_G_BAD_MSG_CTX + /* "Message context invalid" */ + GSS_KRB5_S_G_WRONG_SIZE + /* "Buffer is the wrong size" */ + GSS_KRB5_S_G_BAD_USAGE + /* "Credential usage type is unknown" */ + GSS_KRB5_S_G_UNKNOWN_QOP + /* "Unknown quality of protection specified" */ + +4.1.2. Kerberos-specific-codes + + GSS_KRB5_S_KG_CCACHE_NOMATCH + /* "Principal in credential cache does not match desired name" */ + GSS_KRB5_S_KG_KEYTAB_NOMATCH + /* "No principal in keytab matches desired name" */ + GSS_KRB5_S_KG_TGT_MISSING + /* "Credential cache has no TGT" */ + GSS_KRB5_S_KG_NO_SUBKEY + /* "Authenticator has no subkey" */ + GSS_KRB5_S_KG_CONTEXT_ESTABLISHED + /* "Context is already fully established" */ + GSS_KRB5_S_KG_BAD_SIGN_TYPE + /* "Unknown signature type in token" */ + GSS_KRB5_S_KG_BAD_LENGTH + /* "Invalid field length in token" */ + GSS_KRB5_S_KG_CTX_INCOMPLETE + /* "Attempt to use incomplete security context" */ + +4.2. Quality of Protection Values + + This section defines Quality of Protection (QOP) values to be used + with the Kerberos V5 GSS-API mechanism as input to GSS_Wrap() and + GSS_GetMIC() routines in order to select among alternate integrity + and confidentiality algorithms. Additional QOP values may be added in + future versions of this specification. Non-overlapping bit positions + are and will be employed in order that both integrity and + + + +Linn Standards Track [Page 18] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + confidentiality QOP may be selected within a single parameter, via + inclusive-OR of the specified integrity and confidentiality values. + +4.2.1. Integrity Algorithms + + The following Quality of Protection (QOP) values are currently + defined for the Kerberos V5 GSS-API mechanism, and are used to select + among alternate integrity checking algorithms. + + GSS_KRB5_INTEG_C_QOP_MD5 (numeric value: 1) + /* Integrity using partial MD5 ("MD2.5") of plaintext */ + + GSS_KRB5_INTEG_C_QOP_DES_MD5 (numeric value: 2) + /* Integrity using DES MAC of MD5 of plaintext */ + + GSS_KRB5_INTEG_C_QOP_DES_MAC (numeric value: 3) + /* Integrity using DES MAC of plaintext */ + +4.2.2. Confidentiality Algorithms + + Only one confidentiality QOP value is currently defined for the + Kerberos V5 GSS-API mechanism: + + GSS_KRB5_CONF_C_QOP_DES (numeric value: 0) + /* Confidentiality with DES */ + + Note: confidentiality QOP should be indicated only by GSS-API calls + capable of providing confidentiality services. If non-zero + confidentiality QOP values are defined in future to represent + different algorithms, therefore, the bit positions containing those + values should be cleared before being returned by implementations of + GSS_GetMIC() and GSS_VerifyMIC(). + +4.3. Buffer Sizes + + All implementations of this specification shall be capable of + accepting buffers of at least 16 Kbytes as input to GSS_GetMIC(), + GSS_VerifyMIC(), and GSS_Wrap(), and shall be capable of accepting + the output_token generated by GSS_Wrap() for a 16 Kbyte input buffer + as input to GSS_Unwrap(). Support for larger buffer sizes is optional + but recommended. + + + + + + + + + + +Linn Standards Track [Page 19] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +5. Security Considerations + + Security issues are discussed throughout this memo. + +6. References + + + [RFC-1321]: Rivest, R., "The MD5 Message-Digest Algorithm", RFC + 1321, April 1992. + + [RFC-1508]: Linn, J., "Generic Security Service Application Program + Interface", RFC 1508, September 1993. + + [RFC-1509]: Wray, J., "Generic Security Service Application Program + Interface: C-bindings", RFC 1509, September 1993. + + [RFC-1510]: Kohl, J., and C. Neuman, "The Kerberos Network + Authentication Service (V5)", RFC 1510, September 1993. + + [FIPS-PUB-113]: National Bureau of Standards, Federal Information + Processing Standard 113, "Computer Data Authentication", May 1985. + +AUTHOR'S ADDRESS + + John Linn + OpenVision Technologies + One Main St. + Cambridge, MA 02142 USA + + Phone: +1 617.374.2245 + EMail: John.Linn@ov.com + + + + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 20] +