| blob | 518f4c63d17125bd167316ccfdae57918a94c8d7 |
2 Internet draft J.Wray
3 IETF Common Authentication Technology WG Digital Equipment Corporation
4 <draft-ietf-cat-gssv2-cbind-04.txt> March 1997
8 Generic Security Service API Version 2 : C-bindings
11 1. STATUS OF THIS MEMO
13 This document is an Internet Draft. Internet Drafts are working
14 documents of the Internet Engineering Task Force (IETF), its Areas, and
15 its Working Groups. Note that other groups may also distribute working
16 documents as Internet Drafts. Internet Drafts are draft documents valid
17 for a maximum of six months. Internet Drafts may be updated, replaced,
18 or obsoleted by other documents at any time. It is not appropriate to
19 use Internet Drafts as reference material or to cite them other than as
20 a "working draft" or "work in progress." Please check the I-D abstract
21 listing contained in each Internet Draft directory to learn the current
22 status of this or any other Internet Draft.
24 Comments on this document should be sent to "cat-ietf@MIT.EDU", the IETF
25 Common Authentication Technology WG discussion list.
28 2. ABSTRACT
30 This draft document specifies C language bindings for Version 2 of the
31 Generic Security Service Application Program Interface (GSSAPI), which
32 is described at a language-independent conceptual level in other drafts
33 [GSSAPI]. It revises RFC-1509, making specific incremental changes in
34 response to implementation experience and liaison requests. It is
35 intended, therefore, that this draft or a successor version thereof will
36 become the basis for subsequent progression of the GSS-API specification
37 on the standards track.
39 The Generic Security Service Application Programming Interface provides
40 security services to its callers, and is intended for implementation
41 atop a variety of underlying cryptographic mechanisms. Typically,
42 GSSAPI callers will be application protocols into which security
43 enhancements are integrated through invocation of services provided by
44 the GSSAPI. The GSSAPI allows a caller application to authenticate a
45 principal identity associated with a peer application, to delegate
46 rights to a peer, and to apply security services such as confidentiality
47 and integrity on a per-message basis.
56 Wray Document Expiration: 1 September 1997 [Page 1]
59 \f
64 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
68 3. INTRODUCTION
70 The Generic Security Service Application Programming Interface [GSSAPI]
71 provides security services to calling applications. It allows a
72 communicating application to authenticate the user associated with
73 another application, to delegate rights to another application, and to
74 apply security services such as confidentiality and integrity on a per-
75 message basis.
77 There are four stages to using the GSSAPI:
79 (a) The application acquires a set of credentials with which it may
80 prove its identity to other processes. The application's
81 credentials vouch for its global identity, which may or may not be
82 related to any local username under which it may be running.
84 (b) A pair of communicating applications establish a joint security
85 context using their credentials. The security context is a pair
86 of GSSAPI data structures that contain shared state information,
87 which is required in order that per-message security services may
88 be provided. Examples of state that might be shared between
89 applications as part of a security context are cryptographic keys,
90 and message sequence numbers. As part of the establishment of a
91 security context, the context initiator is authenticated to the
92 responder, and may require that the responder is authenticated in
93 turn. The initiator may optionally give the responder the right
94 to initiate further security contexts, acting as an agent or
95 delegate of the initiator. This transfer of rights is termed
96 delegation, and is achieved by creating a set of credentials,
97 similar to those used by the initiating application, but which may
98 be used by the responder.
100 To establish and maintain the shared information that makes up the
101 security context, certain GSSAPI calls will return a token data
102 structure, which is a cryptographically protected opaque data
103 type. The caller of such a GSSAPI routine is responsible for
104 transferring the token to the peer application, encapsulated if
105 necessary in an application-application protocol. On receipt of
106 such a token, the peer application should pass it to a
107 corresponding GSSAPI routine which will decode the token and
108 extract the information, updating the security context state
109 information accordingly.
111 (c) Per-message services are invoked to apply either:
113 (i) integrity and data origin authentication, or
115 (ii) confidentiality, integrity and data origin authentication
117 to application data, which are treated by GSSAPI as arbitrary
118 octet-strings. An application transmitting a message that it
122 Wray Document Expiration: 1 September 1997 [Page 2]
125 \f
130 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
134 wishes to protect will call the appropriate GSSAPI routine
135 (gss_get_mic or gss_wrap) to apply protection, specifying the
136 appropriate security context, and send the resulting token to the
137 receiving application. The receiver will pass the received token
138 (and, in the case of data protected by gss_get_mic, the
139 accompanying message-data) to the corresponding decoding routine
140 (gss_verify_mic or gss_unwrap) to remove the protection and
141 validate the data.
143 (d) At the completion of a communications session (which may extend
144 across several transport connections), each application calls a
145 GSSAPI routine to delete the security context. Multiple contexts
146 may also be used (either successively or simultaneously) within a
147 single communications association, at the option of the
148 applications.
151 4. GSSAPI ROUTINES
153 This section lists the routines that make up the GSSAPI, and offers a
154 brief description of the purpose of each routine. Detailed descriptions
155 of each routine are listed in alphabetical order in section 7.
157 Table 4-1 GSSAPI Credential-management Routines
159 ROUTINE SECTION FUNCTION
161 gss_acquire_cred 7.2 Assume a global identity;
162 Obtain a GSSAPI credential
163 handle for pre-existing
164 credentials.
166 gss_add_cred 7.3 Construct credentials
167 incrementally
169 gss_inquire_cred 7.21 Obtain information about
170 a credential.
172 gss_inquire_cred_by_mech 7.22 Obtain per-mechanism information
173 about a credential.
175 gss_release_cred 7.27 Discard a credential handle.
188 Wray Document Expiration: 1 September 1997 [Page 3]
191 \f
196 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
200 Table 4-2 GSSAPI Context-level Routines
202 ROUTINE SECTION FUNCTION
204 gss_init_sec_context 7.19 Initiate a security context
205 with a peer application
208 gss_accept_sec_context 7.1 Accept a security context
209 initiated by a peer
210 application
212 gss_delete_sec_context 7.9 Discard a security context
214 gss_process_context_token 7.25 Process a token on a security
215 context from a peer
216 application
218 gss_context_time 7.7 Determine for how long a
219 context will remain valid
221 gss_inquire_context 7.20 Obtain information about a
222 security context
224 gss_wrap_size_limit 7.33 Determine token-size limit for
225 gss_wrap on a context
227 gss_export_sec_context 7.14 Transfer a security context to
228 another process
230 gss_import_sec_context 7.17 Import a transferred context
235 Table 4-3 GSSAPI Per-message Routines
237 ROUTINE SECTION FUNCTION
239 gss_get_mic 7.15 Calculate a cryptographic
240 Message Integrity Code (MIC)
241 for a message; integrity service
243 gss_verify_mic 7.32 Check a MIC against a message;
244 verify integrity of a received
245 message
247 gss_wrap 7.36 Attach a MIC to a message, and
248 optionally encrypt the message
249 content; confidentiality service
254 Wray Document Expiration: 1 September 1997 [Page 4]
257 \f
262 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
266 gss_unwrap 7.31 Verify a message with attached
267 MIC, and decrypt message
268 content if necessary.
273 Table 4-4 GSSAPI Name manipulation Routines
275 ROUTINE SECTION FUNCTION
277 gss_import_name 7.16 Convert a contiguous string name
278 to internal-form
280 gss_display_name 7.10 Convert internal-form name
281 to text
283 gss_compare_name 7.6 Compare two internal-form names
285 gss_release_name 7.28 Discard an internal-form name
287 gss_inquire_names_for_mech 7.24 List the name-types supported
288 by a specified mechanism
290 gss_inquire_mechs_for_name 7.23 List mechanisms that support
291 a given nametype
293 gss_canonicalize_name 7.5 Convert an internal name to
294 an MN.
296 gss_export_name 7.13 Convert an MN to export form
298 gss_duplicate_name 7.12 Create a copy of an internal name
303 Table 4-5 GSSAPI Miscellaneous Routines
305 ROUTINE SECTION FUNCTION
307 gss_display_status 7.11 Convert a GSSAPI status code
308 to text
310 gss_indicate_mechs 7.18 Determine available underlying
311 authentication mechanisms
313 gss_release_buffer 7.26 Discard a buffer
315 gss_release_oid_set 7.29 Discard a set of object
316 identifiers
320 Wray Document Expiration: 1 September 1997 [Page 5]
323 \f
328 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
332 gss_create_empty_oid_set 7.8 Create a set containing no
333 object identifiers
335 gss_add_oid_set_member 7.4 Add an object identifier to
336 a set
338 gss_test_oid_set_member 7.30 Determines whether an object
339 identifier is a member of a set
345 Individual GSSAPI implementations may augment these routines by
346 providing additional mechanism-specific routines if required
347 functionality is not available from the generic forms. Applications are
348 encouraged to use the generic routines wherever possible on portability
349 grounds.
352 5. DATA TYPES AND CALLING CONVENTIONS
354 The following conventions are used by the GSSAPI C-language bindings:
356 5.1. Integer types
358 GSSAPI uses the following integer data type:
360 OM_uint32 32-bit unsigned integer
362 Where guaranteed minimum bit-count is important, this portable data type
363 is used by the GSSAPI routine definitions. Individual GSSAPI
364 implementations will include appropriate typedef definitions to map this
365 type onto a built-in data type. If the platform supports the X/Open
366 xom.h header file, the OM_uint32 definition contained therein should be
367 used; the GSSAPI header file in Appendix A contains logic that will
368 detect the prior inclusion of xom.h, and will not attempt to re-declare
369 OM_uint32. If the X/Open header file is not available on the platform,
370 the GSSAPI implementation should use the smallest natural unsigned
371 integer type that provides at least 32 bits of precision.
373 5.2. String and similar data
375 Many of the GSSAPI routines take arguments and return values that
376 describe contiguous octet-strings. All such data is passed between the
377 GSSAPI and the caller using the gss_buffer_t data type. This data type
378 is a pointer to a buffer descriptor, which consists of a length field
379 that contains the total number of bytes in the datum, and a value field
380 which contains a pointer to the actual datum:
386 Wray Document Expiration: 1 September 1997 [Page 6]
389 \f
394 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
398 typedef struct gss_buffer_desc_struct {
399 size_t length;
400 void *value;
401 } gss_buffer_desc, *gss_buffer_t;
403 Storage for data returned to the application by a GSSAPI routine using
404 the gss_buffer_t conventions is allocated by the GSSAPI routine. The
405 application may free this storage by invoking the gss_release_buffer
406 routine. Allocation of the gss_buffer_desc object is always the
407 responsibility of the application; unused gss_buffer_desc objects may
408 be initialized to the value GSS_C_EMPTY_BUFFER.
410 5.2.1. Opaque data types
412 Certain multiple-word data items are considered opaque data types at the
413 GSSAPI, because their internal structure has no significance either to
414 the GSSAPI or to the caller. Examples of such opaque data types are the
415 input_token parameter to gss_init_sec_context (which is opaque to the
416 caller), and the input_message parameter to gss_wrap (which is opaque to
417 the GSSAPI). Opaque data is passed between the GSSAPI and the
418 application using the gss_buffer_t datatype.
420 5.2.2. Character strings
422 Certain multiple-word data items may be regarded as simple ISO Latin-1
423 character strings. Examples are the printable strings passed to
424 gss_import_name via the input_name_buffer parameter. Some GSSAPI
425 routines also return character strings. All such character strings are
426 passed between the application and the GSSAPI implementation using the
427 gss_buffer_t datatype, which is a pointer to a gss_buffer_desc object.
429 When a gss_buffer_desc object describes a printable string, the length
430 field of the gss_buffer_desc should only count printable characters
431 within the string. In particular, a trailing NUL character should NOT
432 be included in the length count, nor should either the GSSAPI
433 implementation or the application assume the presence of an uncounted
434 trailing NUL.
436 5.3. Object Identifiers
438 Certain GSSAPI procedures take parameters of the type gss_OID, or Object
439 identifier. This is a type containing ISO-defined tree-structured
440 values, and is used by the GSSAPI caller to select an underlying
441 security mechanism and to specify namespaces. A value of type gss_OID
442 has the following structure:
444 typedef struct gss_OID_desc_struct {
445 OM_uint32 length;
446 void *elements;
447 } gss_OID_desc, *gss_OID;
452 Wray Document Expiration: 1 September 1997 [Page 7]
455 \f
460 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
464 The elements field of this structure points to the first byte of an
465 octet string containing the ASN.1 BER encoding of the value portion of
466 the normal BER TLV encoding of the gss_OID. The length field contains
467 the number of bytes in this value. For example, the gss_OID value
468 corresponding to {iso(1) identified-organization(3) icd-ecma(12)
469 member-company(2) dec(1011) cryptoAlgorithms(7) DASS(5)}, meaning the
470 DASS X.509 authentication mechanism, has a length field of 7 and an
471 elements field pointing to seven octets containing the following octal
472 values: 53,14,2,207,163,7,5. GSSAPI implementations should provide
473 constant gss_OID values to allow applications to request any supported
474 mechanism, although applications are encouraged on portability grounds
475 to accept the default mechanism. gss_OID values should also be provided
476 to allow applications to specify particular name types (see section
477 5.10). Applications should treat gss_OID_desc values returned by GSSAPI
478 routines as read-only. In particular, the application should not
479 attempt to deallocate them with free(). The gss_OID_desc datatype is
480 equivalent to the X/Open OM_object_identifier datatype[XOM].
482 5.4. Object Identifier Sets
484 Certain GSSAPI procedures take parameters of the type gss_OID_set. This
485 type represents one or more object identifiers (section 5.3). A
486 gss_OID_set object has the following structure:
488 typedef struct gss_OID_set_desc_struct {
489 size_t count;
490 gss_OID elements;
491 } gss_OID_set_desc, *gss_OID_set;
493 The count field contains the number of OIDs within the set. The
494 elements field is a pointer to an array of gss_OID_desc objects, each of
495 which describes a single OID. gss_OID_set values are used to name the
496 available mechanisms supported by the GSSAPI, to request the use of
497 specific mechanisms, and to indicate which mechanisms a given credential
498 supports.
500 All OID sets returned to the application by GSSAPI are dynamic objects
501 (the gss_OID_set_desc, the "elements" array of the set, and the
502 "elements" array of each member OID are all dynamically allocated), and
503 this storage must be deallocated by the application using the
504 gss_release_oid_set() routine.
507 5.5. Credentials
509 A credential handle is a caller-opaque atomic datum that identifies a
510 GSSAPI credential data structure. It is represented by the caller-
511 opaque type gss_cred_id_t, which should be implemented as a pointer or
512 arithmetic type. If a pointer implementation is chosen, care must be
513 taken to ensure that two gss_cred_id_t values may be compared with the
514 == operator.
518 Wray Document Expiration: 1 September 1997 [Page 8]
521 \f
526 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
530 GSSAPI credentials can contain mechanism-specific principal
531 authentication data for multiple mechanisms. A GSSAPI credential is
532 composed of a set of credential-elements, each of which is applicable to
533 a single mechanism. A credential may contain at most one credential-
534 element for each supported mechanism. A credential-element identifies
535 the data needed by a single mechanism to authenticate a single
536 principal, and conceptually contains two credential-references that
537 describing the actual mechanism-specific authentication data, one to be
538 used by GSSAPI for initiating contexts, and one to be used for
539 accepting contexts. For mechanisms that do not distinguish between
540 acceptor and initiator credentials, both references would point to the
541 same underlying mechanism-specific authentication data.
543 Credentials describe a set of mechanism-specific principals, and give
544 their holder the ability to act as any of those principals. All
545 principal identities asserted by a single GSSAPI credential should
546 belong to the same entity, although enforcement of this property is an
547 implementation-specific matter. The GSSAPI does not make the actual
548 credentials available to applications; instead a credential handle is
549 used to identify a particular credential, held internally by GSSAPI.
550 The combination of GSSAPI credential handle and mechanism identifies the
551 principal whose identity will be asserted by the credential when used
552 with that mechanism.
554 The gss_init_sec_context and gss_accept_sec_context routines allow the
555 value GSS_C_NO_CREDENTIAL to be specified as their credential handle
556 parameter. This special credential-handle indicates a desire by the
557 application to act as a default principal. While individual GSSAPI
558 implementations are free to determine such default behavior as
559 appropriate to the mechanism, the following default behavior by these
560 routines is recommended for portability:
562 (a) gss_init_sec_context
564 (i) If there is only a single principal capable of initiating
565 security contexts for the chosen mechanism that the
566 application is authorized to act on behalf of, then that
567 principal shall be used, otherwise
569 (ii) If the platform maintains a concept of a default network-
570 identity for the chosen mechanism, and if the application is
571 authorized to act on behalf of that identity for the purpose
572 of initiating security contexts, then the principal
573 corresponding to that identity shall be used, otherwise
575 (iii) If the platform maintains a concept of a default local
576 identity, and provides a means to map local identities into
577 network-identities for the chosen mechanism, and if the
578 application is authorized to act on behalf of the network-
579 identity image of the default local identity for the purpose
580 of initiating security contexts using the chosen mechanism,
584 Wray Document Expiration: 1 September 1997 [Page 9]
587 \f
592 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
596 then the principal corresponding to that identity shall be
597 used, otherwise
599 (iv) A user-configurable default identity should be used.
601 (b) gss_accept_sec_context
603 (i) If there is only a single authorized principal identity
604 capable of accepting security contexts for the chosen
605 mechanism, then that principal shall be used, otherwise
607 (ii) If the mechanism can determine the identity of the target
608 principal by examining the context-establishment token, and
609 if the accepting application is authorized to act as that
610 principal for the purpose of accepting security contexts
611 using the chosen mechanism, then that principal identity
612 shall be used, otherwise
614 (iii) If the mechanism supports context acceptance by any
615 principal, and if mutual authentication was not requested,
616 any principal that the application is authorized to accept
617 security contexts under using the chosen mechanism may be
618 used, otherwise
620 (iv) A user-configurable default identity shall be used.
622 The purpose of the above rules is to allow security contexts to be
623 established by both initiator and acceptor using the default behavior
624 wherever possible. Applications requesting default behavior are likely
625 to be more portable across mechanisms and platforms than ones that use
626 gss_acquire_cred to request a specific identity.
628 5.6. Contexts
630 The gss_ctx_id_t data type contains a caller-opaque atomic value that
631 identifies one end of a GSSAPI security context. It should be
632 implemented as a pointer or arithmetic type. If a pointer type is
633 chosen, care should be taken to ensure that two gss_ctx_id_t values may
634 be compared with the == operator.
636 The security context holds state information about each end of a peer
637 communication, including cryptographic state information.
639 5.7. Authentication tokens
641 A token is a caller-opaque type that GSSAPI uses to maintain
642 synchronization between the context data structures at each end of a
643 GSSAPI security context. The token is a cryptographically protected
644 octet-string, generated by the underlying mechanism at one end of a
645 GSSAPI security context for use by the peer mechanism at the other end.
646 Encapsulation (if required) and transfer of the token are the
650 Wray Document Expiration: 1 September 1997 [Page 10]
653 \f
658 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
662 responsibility of the peer applications. A token is passed between the
663 GSSAPI and the application using the gss_buffer_t conventions.
665 5.8. Interprocess tokens
667 Certain GSSAPI routines are intended to transfer data between processes
668 in multi-process programs. These routines use a caller-opaque octet-
669 string, generated by the GSSAPI in one process for use by the GSSAPI in
670 another process. The calling application is responsible for
671 transferring such tokens between processes in an OS-specific manner.
672 Note that, while GSSAPI implementors are encouraged to avoid placing
673 sensitive information within interprocess tokens, or to
674 cryptographically protect them, many implementations will be unable to
675 avoid placing key material or other sensitive data within them. It is
676 the application's responsibility to ensure that interprocess tokens are
677 protected in transit, and transferred only to processes that are
678 trustworthy. An interprocess token is passed between the GSSAPI and the
679 application using the gss_buffer_t conventions.
681 5.9. Status values
683 One or more status codes are returned by each GSSAPI routine. Two
684 distinct sorts of status codes are returned. These are termed GSS
685 status codes and Mechanism status codes.
687 5.9.1. GSS status codes
689 GSSAPI routines return GSS status codes as their OM_uint32 function
690 value. These codes indicate errors that are independent of the
691 underlying mechanism(s) used to provide the security service. The
692 errors that can be indicated via a GSS status code are either generic
693 API routine errors (errors that are defined in the GSS-API
694 specification) or calling errors (errors that are specific to these
695 language bindings).
697 A GSS status code can indicate a single fatal generic API error from the
698 routine and a single calling error. In addition, supplementary status
699 information may be indicated via the setting of bits in the
700 supplementary info field of a GSS status code.
702 These errors are encoded into the 32-bit GSS status code as follows:
704 MSB LSB
705 |------------------------------------------------------------|
706 | Calling Error | Routine Error | Supplementary Info |
707 |------------------------------------------------------------|
708 Bit 31 24 23 16 15 0
711 Hence if a GSS-API routine returns a GSS status code whose upper 16 bits
712 contain a non-zero value, the call failed. If the calling error field
716 Wray Document Expiration: 1 September 1997 [Page 11]
719 \f
724 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
728 is non-zero, the invoking application's call of the routine was
729 erroneous. Calling errors are defined in table 5-1. If the routine
730 error field is non-zero, the routine failed for one of the routine-
731 specific reasons listed below in table 5-2. Whether or not the upper 16
732 bits indicate a failure or a success, the routine may indicate
733 additional information by setting bits in the supplementary info field
734 of the status code. The meaning of individual bits is listed below in
735 table 5-3.
737 Table 5-1 Calling Errors
739 Name Value in Meaning
740 Field
741 GSS_S_CALL_INACCESSIBLE_READ 1 A required input
742 parameter could
743 not be read.
744 GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output
745 parameter could
746 not be written.
747 GSS_S_CALL_BAD_STRUCTURE 3 A parameter was
748 malformed
753 Table 5-2 Routine Errors
755 Name Value in Meaning
756 Field
758 GSS_S_BAD_MECH 1 An unsupported mechanism was
759 requested
760 GSS_S_BAD_NAME 2 An invalid name was supplied
761 GSS_S_BAD_NAMETYPE 3 A supplied name was of an
762 unsupported type
763 GSS_S_BAD_BINDINGS 4 Incorrect channel bindings
764 were supplied
765 GSS_S_BAD_STATUS 5 An invalid status code was
766 supplied
767 GSS_S_BAD_SIG 6 A token had an invalid
768 GSS_S_BAD_MIC MIC
769 GSS_S_NO_CRED 7 No credentials were supplied,
770 or the credentials were
771 unavailable or inaccessible.
772 GSS_S_NO_CONTEXT 8 No context has been
773 established
774 GSS_S_DEFECTIVE_TOKEN 9 A token was invalid
775 GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid
776 GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials
777 have expired
782 Wray Document Expiration: 1 September 1997 [Page 12]
785 \f
790 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
794 GSS_S_CONTEXT_EXPIRED 12 The context has expired
795 GSS_S_FAILURE 13 Miscellaneous failure
796 (see text)
797 GSS_S_BAD_QOP 14 The quality-of-protection
798 requested could not be
799 provide
800 GSS_S_UNAUTHORIZED 15 The operation is forbidden by
801 local security policy
802 GSS_S_UNAVAILABLE 16 The operation or option is not
803 available
804 GSS_S_DUPLICATE_ELEMENT 17 The requested credential element
805 already exists
806 GSS_S_NAME_NOT_MN 18 The provided name was not a
807 mechanism name.
813 Table 5-3 Supplementary Status Bits
815 Name Bit Number Meaning
816 GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called
817 again to complete its function.
818 See routine documentation for
819 detailed description.
820 GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of
821 an earlier token
822 GSS_S_OLD_TOKEN 2 The token's validity period
823 has expired
824 GSS_S_UNSEQ_TOKEN 3 A later token has already been
825 processed
826 GSS_S_GAP_TOKEN 4 An expected per-message token
827 was not received
830 The routine documentation also uses the name GSS_S_COMPLETE, which is a
831 zero value, to indicate an absence of any API errors or supplementary
832 information bits.
834 All GSS_S_xxx symbols equate to complete OM_uint32 status codes, rather
835 than to bitfield values. For example, the actual value of the symbol
836 GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 << 16.
838 The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and
839 GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS status
840 code and removes all but the relevant field. For example, the value
841 obtained by applying GSS_ROUTINE_ERROR to a status code removes the
842 calling errors and supplementary info fields, leaving only the routine
843 errors field. The values delivered by these macros may be directly
844 compared with a GSS_S_xxx symbol of the appropriate type. The macro
848 Wray Document Expiration: 1 September 1997 [Page 13]
851 \f
856 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
860 GSS_ERROR() is also provided, which when applied to a GSS status code
861 returns a non-zero value if the status code indicated a calling or
862 routine error, and a zero value otherwise. All macros defined by GSS-
863 API evaluate their argument(s) exactly once.
865 A GSS-API implementation may choose to signal calling errors in a
866 platform-specific manner instead of, or in addition to the routine
867 value; routine errors and supplementary info should be returned via
868 routine status values only.
870 5.9.2. Mechanism-specific status codes
872 GSS-API routines return a minor_status parameter, which is used to
873 indicate specialized errors from the underlying security mechanism.
874 This parameter may contain a single mechanism-specific error, indicated
875 by a OM_uint32 value.
877 The minor_status parameter will always be set by a GSS-API routine, even
878 if it returns a calling error or one of the generic API errors indicated
879 above as fatal, although most other output parameters may remain unset
880 in such cases. However, output parameters that are expected to return
881 pointers to storage allocated by a routine must always be set by the
882 routine, even in the event of an error, although in such cases the GSS-
883 API routine may elect to set the returned parameter value to NULL to
884 indicate that no storage was actually allocated. Any length field
885 associated with such pointers (as in a gss_buffer_desc structure) should
886 also be set to zero in such cases.
888 The GSS status code GSS_S_FAILURE is used to indicate that the
889 underlying mechanism detected an error for which no specific GSS status
890 code is defined. The mechanism status code will provide more details
891 about the error.
893 5.10. Names
895 A name is used to identify a person or entity. GSS-API authenticates
896 the relationship between a name and the entity claiming the name.
898 Since different authentication mechanisms may employ different
899 namespaces for identifying their principals, GSSAPI's naming support is
900 necessarily complex in multi-mechanism environments (or even in some
901 single-mechanism environments where the underlying mechanism supports
902 multiple namespaces).
904 Two distinct representations are defined for names:
906 (a) An internal form. This is the GSSAPI "native" format for names,
907 represented by the implementation-specific gss_name_t type. It is
908 opaque to GSSAPI callers. A single gss_name_t object may contain
909 multiple names from different namespaces, but all names should
910 refer to the same entity. An example of such an internal name
914 Wray Document Expiration: 1 September 1997 [Page 14]
917 \f
922 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
926 would be the name returned from a call to the gss_inquire_cred
927 routine, when applied to a credential containing credential
928 elements for multiple authentication mechanisms employing
929 different namespaces. This gss_name_t object will contain a
930 distinct name for the entity for each authentication mechanism.
932 For GSSAPI implementations supporting multiple namespaces, objects
933 of type gss_name_t must contain sufficient information to
934 determine the namespace to which each primitive name belongs.
936 (b) Mechanism-specific contiguous octet-string forms. A format
937 capable of containing a single name (from a single namespace).
938 Contiguous string names are always accompanied by an object
939 identifier specifying the namespace to which the name belongs, and
940 their format is dependent on the authentication mechanism that
941 employs the name. Many, but not all, contiguous string names will
942 be printable, and may therefore be used by GSSAPI applications for
943 communication with their users.
945 Routines (gss_import_name and gss_display_name) are provided to convert
946 names between contiguous string representations and the internal
947 gss_name_t type. gss_import_name may support multiple syntaxes for each
948 supported namespace, allowing users the freedom to choose a preferred
949 name representation. gss_display_name should use an implementation-
950 chosen printable syntax for each supported name-type.
952 If an application calls gss_display_name(), passing the internal name
953 resulting from a call to gss_import_name(), there is no guarantee the
954 the resulting contiguous string name will be the same as the original
955 imported string name. Nor do name-space identifiers necessarily survive
956 unchanged after a journey through the internal name-form. An example of
957 this might be a mechanism that authenticates X.500 names, but provides
958 an algorithmic mapping of Internet DNS names into X.500. That
959 mechanism's implementation of gss_import_name() might, when presented
960 with a DNS name, generate an internal name that contained both the
961 original DNS name and the equivalent X.500 name. Alternatively, it might
962 only store the X.500 name. In the latter case, gss_display_name() would
963 most likely generate a printable X.500 name, rather than the original
964 DNS name.
966 The process of authentication delivers to the context acceptor an
967 internal name. Since this name has been authenticated by a single
968 mechanism, it contains only a single name (even if the internal name
969 presented by the context initiator to gss_init_sec_context had multiple
970 components). Such names are termed internal mechanism names, or "MN"s
971 and the names emitted by gss_accept_sec_context() are always of this
972 type. Since some applications may require MNs without wanting to incur
973 the overhead of an authentication operation, a second function,
974 gss_canonicalize_name(), is provided to convert a general internal name
975 into an MN.
980 Wray Document Expiration: 1 September 1997 [Page 15]
983 \f
988 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
992 Comparison of internal-form names may be accomplished via the
993 gss_compare_name() routine, which returns true if the two names being
994 compared refer to the same entity. This removes the need for the
995 application program to understand the syntaxes of the various printable
996 names that a given GSS-API implementation may support. Since GSSAPI
997 assumes that all primitive names contained within a given internal name
998 refer to the same entity, gss_compare_name() can return true if the two
999 names have at least one primitive name in common. If the implementation
1000 embodies knowledge of equivalence relationships between names taken from
1001 different namespaces, this knowledge may also allow successful
1002 comparison of internal names containing no overlapping primitive
1003 elements.
1005 When used in large access control lists, the overhead of invoking
1006 gss_import_name() and gss_compare_name() on each name from the ACL may
1007 be prohibitive. As an alternative way of supporting this case, GSSAPI
1008 defines a special form of the contiguous string name which may be
1009 compared directly (e.g. with memcmp()). Contigous names suitable for
1010 comparison are generated by the gss_export_name() routine, which
1011 requires an MN as input. Exported names may be re-imported by the
1012 gss_import_name() routine, and the resulting internal name will also be
1013 an MN. The gss_OID constant GSS_C_NT_EXPORT_NAME indentifies the
1014 "export name" type, and the value of this constant is given in Appendix
1015 A. Structurally, an exported name object consists of a header
1016 containing an OID identifying the mechanism that authenticated the name,
1017 and a trailer containing the name itself, where the syntax of the
1018 trailer is defined by the individual mechanism specification. The
1019 precise format of an export name is defined in the language-independent
1020 GSSAPI specification [GSSAPI].
1022 Note that the results obtained by using gss_compare_name() will in
1023 general be different from those obtained by invoking
1024 gss_canonicalize_name() and gss_export_name(), and then comparing the
1025 exported names. The first series of operation determines whether two
1026 (unauthenticated) names identify the same principal; the second whether
1027 a particular mechanism would authenticate them as the same principal.
1028 These two operations will in general give the same results only for MNs.
1030 The gss_name_t datatype should be implemented as a pointer type. To
1031 allow the compiler to aid the application programmer by performing
1032 type-checking, the use of (void *) is discouraged. A pointer to an
1033 implementation-defined type is the preferred choice.
1035 Storage is allocated by routines that return gss_name_t values. A
1036 procedure, gss_release_name, is provided to free storage associated with
1037 an internal-form name.
1046 Wray Document Expiration: 1 September 1997 [Page 16]
1049 \f
1054 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1058 5.11. Channel Bindings
1060 GSS-API supports the use of user-specified tags to identify a given
1061 context to the peer application. These tags are intended to be used to
1062 identify the particular communications channel that carries the context.
1063 Channel bindings are communicated to the GSS-API using the following
1064 structure:
1066 typedef struct gss_channel_bindings_struct {
1067 OM_uint32 initiator_addrtype;
1068 gss_buffer_desc initiator_address;
1069 OM_uint32 acceptor_addrtype;
1070 gss_buffer_desc acceptor_address;
1071 gss_buffer_desc application_data;
1072 } *gss_channel_bindings_t;
1074 The initiator_addrtype and acceptor_addrtype fields denote the type of
1075 addresses contained in the initiator_address and acceptor_address
1076 buffers. The address type should be one of the following:
1078 GSS_C_AF_UNSPEC Unspecified address type
1079 GSS_C_AF_LOCAL Host-local address type
1080 GSS_C_AF_INET Internet address type (e.g. IP)
1081 GSS_C_AF_IMPLINK ARPAnet IMP address type
1082 GSS_C_AF_PUP pup protocols (eg BSP) address type
1083 GSS_C_AF_CHAOS MIT CHAOS protocol address type
1084 GSS_C_AF_NS XEROX NS address type
1085 GSS_C_AF_NBS nbs address type
1086 GSS_C_AF_ECMA ECMA address type
1087 GSS_C_AF_DATAKIT datakit protocols address type
1088 GSS_C_AF_CCITT CCITT protocols
1089 GSS_C_AF_SNA IBM SNA address type
1090 GSS_C_AF_DECnet DECnet address type
1091 GSS_C_AF_DLI Direct data link interface address type
1092 GSS_C_AF_LAT LAT address type
1093 GSS_C_AF_HYLINK NSC Hyperchannel address type
1094 GSS_C_AF_APPLETALK AppleTalk address type
1095 GSS_C_AF_BSC BISYNC 2780/3780 address type
1096 GSS_C_AF_DSS Distributed system services address type
1097 GSS_C_AF_OSI OSI TP4 address type
1098 GSS_C_AF_X25 X25
1099 GSS_C_AF_NULLADDR No address specified
1101 Note that these symbols name address families rather than specific
1102 addressing formats. For address families that contain several
1103 alternative address forms, the initiator_address and acceptor_address
1104 fields must contain sufficient information to determine which address
1105 form is used. When not otherwise specified, addresses should be
1106 specified in network byte-order (that is, native byte-ordering for the
1107 address family).
1112 Wray Document Expiration: 1 September 1997 [Page 17]
1115 \f
1120 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1124 Conceptually, the GSS-API concatenates the initiator_addrtype,
1125 initiator_address, acceptor_addrtype, acceptor_address and
1126 application_data to form an octet string. The mechanism calculates a
1127 MIC over this octet string, and binds the MIC to the context
1128 establishment token emitted by gss_init_sec_context. The same bindings
1129 are presented by the context acceptor to gss_accept_sec_context, and a
1130 MIC is calculated in the same way. The calculated MIC is compared with
1131 that found in the token, and if the MICs differ, gss_accept_sec_context
1132 will return a GSS_S_BAD_BINDINGS error, and the context will not be
1133 established. Some mechanisms may include the actual channel binding
1134 data in the token (rather than just a MIC); applications should
1135 therefore not use confidential data as channel-binding components.
1136 Individual mechanisms may impose additional constraints on addresses and
1137 address types that may appear in channel bindings. For example, a
1138 mechanism may verify that the initiator_address field of the channel
1139 bindings presented to gss_init_sec_context contains the correct network
1140 address of the host system. Portable applications should therefore
1141 ensure that they either provide correct information for the address
1142 fields, or omit addressing information, specifying GSS_C_AF_NULLADDR as
1143 the address-types.
1145 5.12. Optional parameters
1147 Various parameters are described as optional. This means that they
1148 follow a convention whereby a default value may be requested. The
1149 following conventions are used for omitted parameters. These
1150 conventions apply only to those parameters that are explicitly
1151 documented as optional.
1153 5.12.1. gss_buffer_t types
1155 Specify GSS_C_NO_BUFFER as a value. For an input parameter this
1156 signifies that default behavior is requested, while for an output
1157 parameter it indicates that the information that would be returned via
1158 the parameter is not required by the application.
1160 5.12.2. Integer types (input)
1162 Individual parameter documentation lists values to be used to indicate
1163 default actions.
1165 5.12.3. Integer types (output)
1167 Specify NULL as the value for the pointer.
1169 5.12.4. Pointer types
1171 Specify NULL as the value.
1178 Wray Document Expiration: 1 September 1997 [Page 18]
1181 \f
1186 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1190 5.12.5. Object IDs
1192 Specify GSS_C_NO_OID as the value.
1194 5.12.6. Object ID Sets
1196 Specify GSS_C_NO_OID_SET as the value.
1198 5.12.7. Channel Bindings
1200 Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings are
1201 not to be used.
1204 6. ADDITIONAL CONTROLS
1206 This section discusses the optional services that a context initiator
1207 may request of the GSS-API at context establishment. Each of these
1208 services is requested by setting a flag in the req_flags input parameter
1209 to gss_init_sec_context.
1211 The optional services currently defined are:
1213 Delegation - The (usually temporary) transfer of rights from initiator
1214 to acceptor, enabling the acceptor to authenticate itself as an
1215 agent of the initiator.
1217 Mutual Authentication - In addition to the initiator authenticating its
1218 identity to the context acceptor, the context acceptor should also
1219 authenticate itself to the initiator.
1221 Replay detection - In addition to providing message integrity services,
1222 gss_get_mic and gss_wrap should include message numbering
1223 information to enable gss_verify_mic and gss_unwrap to detect if a
1224 message has been duplicated.
1226 Out-of-sequence detection - In addition to providing message integrity
1227 services, gss_get_mic and gss_wrap should include message
1228 sequencing information to enable gss_verify_mic and gss_unwrap to
1229 detect if a message has been received out of sequence.
1231 Anonymous authentication - The establishment of the security context
1232 should not reveal the initiator's identity to the context
1233 acceptor.
1235 Any currently undefined bits within such flag arguments should be
1236 ignored by GSS-API implementations when presented by an application, and
1237 should be set to zero when returned to the application by the GSS-API
1238 implementation.
1244 Wray Document Expiration: 1 September 1997 [Page 19]
1247 \f
1252 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1256 Some mechanisms may not support all optional services, and some
1257 mechanisms may only support some services in conjunction with others.
1258 Both gss_init_sec_context and gss_accept_sec_context inform the
1259 applications which services will be available from the context when the
1260 establishment phase is complete, via the ret_flags output parameter. In
1261 general, if the security mechanism is capable of providing a requested
1262 service, it should do so, even if additional services must be enabled in
1263 order to provide the requested service. If the mechanism is incapable
1264 of providing a requested service, it should proceed without the service,
1265 leaving the application to abort the context establishment process if it
1266 considers the requested service to be mandatory.
1268 Some mechanisms may specify that support for some services is optional,
1269 and that implementors of the mechanism need not provide it. This is
1270 most commonly true of the confidentiality service, often because of
1271 legal restrictions on the use of data-encryption, but may apply to any
1272 of the services. Such mechanisms are required to send at least one
1273 token from acceptor to initiator during context establishment when the
1274 initiator indicates a desire to use such a service, so that the
1275 initiating GSSAPI can correctly indicate whether the service is
1276 supported by the acceptor's GSSAPI.
1278 6.1. Delegation
1280 The GSS-API allows delegation to be controlled by the initiating
1281 application via a boolean parameter to gss_init_sec_context(), the
1282 routine that establishes a security context. Some mechanisms do not
1283 support delegation, and for such mechanisms attempts by an application
1284 to enable delegation are ignored.
1286 The acceptor of a security context for which the initiator enabled
1287 delegation will receive (via the delegated_cred_handle parameter of
1288 gss_accept_sec_context) a credential handle that contains the delegated
1289 identity, and this credential handle may be used to initiate subsequent
1290 GSSAPI security contexts as an agent or delegate of the initiator. If
1291 the original initiator's identity is "A" and the delegate's identity is
1292 "B", then, depending on the underlying mechanism, the identity embodied
1293 by the delegated credential may be either "A" or "B acting for A".
1295 For many mechanisms that support delegation, a simple boolean does not
1296 provide enough control. Examples of additional aspects of delegation
1297 control that a mechanism might provide to an application are duration of
1298 delegation, network addresses from which delegation is valid, and
1299 constraints on the tasks that may be performed by a delegate. Such
1300 controls are presently outside the scope of the GSS-API. GSS-API
1301 implementations supporting mechanisms offering additional controls
1302 should provide extension routines that allow these controls to be
1303 exercised (perhaps by modifying the initiator's GSS-API credential prior
1304 to its use in establishing a context). However, the simple delegation
1305 control provided by GSS-API should always be able to over-ride other
1306 mechanism-specific delegation controls - If the application instructs
1310 Wray Document Expiration: 1 September 1997 [Page 20]
1313 \f
1318 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1322 gss_init_sec_context() that delegation is not desired, then the
1323 implementation must not permit delegation to occur. This is an
1324 exception to the general rule that a mechanism may enable services even
1325 if they are not requested - delegation may only be provide at the
1326 explicit request of the application.
1328 6.2. Mutual authentication
1330 Usually, a context acceptor will require that a context initiator
1331 authenticate itself so that the acceptor may make an access-control
1332 decision prior to performing a service for the initiator. In some
1333 cases, the initiator may also request that the acceptor authenticate
1334 itself. GSS-API allows the initiating application to request this
1335 mutual authentication service by setting a flag when calling
1336 gss_init_sec_context.
1338 The initiating application is informed as to whether or not mutual
1339 authentication is being requested of the context acceptor. Note that
1340 some mechanisms may not support mutual authentication, and other
1341 mechanisms may always perform mutual authentication, whether or not the
1342 initiating application requests it. In particular, mutual
1343 authentication my be required by some mechanisms in order to support
1344 replay or out-of-sequence message detection, and for such mechanisms a
1345 request for either of these services will automatically enable mutual
1346 authentication.
1348 6.3. Replay and out-of-sequence detection
1350 The GSS-API may provide detection of mis-ordered message once a security
1351 context has been established. Protection may be applied to messages by
1352 either application, by calling either gss_get_mic or gss_wrap, and
1353 verified by the peer application by calling gss_verify_mic or
1354 gss_unwrap.
1356 gss_get_mic calculates a cryptographic checksum of an application
1357 message, and returns that checksum in a token. The application should
1358 pass both the token and the message to the peer application, which
1359 presents them to gss_verify_mic.
1361 gss_wrap calculates a cryptographic checksum of an application message,
1362 and places both the checksum and the message inside a single token. The
1363 application should pass the token to the peer application, which
1364 presents it to gss_unwrap to extract the message and verify the
1365 checksum.
1367 Either pair of routines may be capable of detecting out-of-sequence
1368 message delivery, or duplication of messages. Details of such mis-
1369 ordered messages are indicated through supplementary status bits in the
1370 major status code returned by gss_verify_mic or gss_unwrap. The
1371 relevant supplementary bits are:
1376 Wray Document Expiration: 1 September 1997 [Page 21]
1379 \f
1384 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1388 GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has already
1389 been received and processed. Contexts that do not claim to
1390 provide replay detection may still set this bit if the duplicate
1391 message is processed immediately after the original, with no
1392 intervening messages.
1394 GSS_S_OLD_TOKEN - The token is too old to determine whether or not it is
1395 a duplicate. Contexts supporting out-of-sequence detection but
1396 not replay detection should always set this bit if
1397 GSS_S_UNSEQ_TOKEN is set; contexts that support replay detection
1398 should only set this bit if the token is so old that it cannot be
1399 checked for duplication.
1401 GSS_S_UNSEQ_TOKEN - A later token has already been processed.
1403 GSS_S_GAP_TOKEN - An earlier token has not yet been received.
1405 A mechanism need not maintain a list of all tokens that have been
1406 processed in order to support these status codes. A typical mechanism
1407 might retain information about only the most recent "N" tokens
1408 processed, allowing it to distinguish duplicates and missing tokens
1409 within the most recent "N" messages; the receipt of a token older than
1410 the most recent "N" would result in a GSS_S_OLD_TOKEN status.
1412 6.4. Anonymous Authentication
1414 In certain situations, an application may wish to initiate the
1415 authentication process to authenticate a peer, without revealing its own
1416 identity. As an example, consider an application providing access to a
1417 database containing medical information, and offering unrestricted
1418 access to the service. A client of such a service might wish to
1419 authenticate the service (in order to establish trust in any information
1420 retrieved from it), but might not wish the service to be able to obtain
1421 the client's identity (perhaps due to privacy concerns about the
1422 specific inquiries, or perhaps simply to avoid being placed on mailing-
1423 lists).
1425 In normal use of the GSS-API, the initiator's identity is made available
1426 to the acceptor as a result of the context establishment process.
1427 However, context initiators may request that their identity not be
1428 revealed to the context acceptor. Many mechanisms do not support
1429 anonymous authentication, and for such mechanisms the request will not
1430 be honored. An authentication token will be still be generated, but the
1431 application is always informed if a requested service is unavailable,
1432 and has the option to abort context establishment if anonymity is valued
1433 above the other security services that would require a context to be
1434 established.
1436 In addition to informing the application that a context is established
1437 anonymously (via the ret_flags outputs from gss_init_sec_context and
1438 gss_accept_sec_context), the optional src_name output from
1442 Wray Document Expiration: 1 September 1997 [Page 22]
1445 \f
1450 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1454 gss_accept_sec_context and gss_inquire_context will, for such contexts,
1455 return a reserved internal-form name, defined by the implementation.
1456 When presented to gss_display_name, this reserved internal-form name
1457 will result in a printable name that is syntactically distinguishable
1458 from any valid principal name supported by the implementation,
1459 associated with a name-type object identifier with the value
1460 GSS_C_NT_ANONYMOUS, whose value us given in Appendix A. The printable
1461 form of an anonymous name should be chosen such that it implies
1462 anonymity, since this name may appear in, for example, audit logs. For
1463 example, the string "<anonymous>" might be a good choice, if no valid
1464 printable names supported by the implementation can begin with "<" and
1465 end with ">".
1467 6.5. Confidentiality
1469 If a context supports the confidentiality service, gss_wrap may be used
1470 to encrypt application messages. Messages are selectively encrypted,
1471 under the control of the conf_req_flag input parameter to gss_wrap.
1473 6.6. Inter-process context transfer
1475 GSSAPI V2 provides routines (gss_export_sec_context and
1476 gss_import_sec_context) which allow a security context to be transferred
1477 between processes on a single machine. The most common use for such a
1478 feature is a client-server design where the server is implemented as a
1479 single process that accepts incoming security contexts, which then
1480 launches child processes to deal with the data on these contexts. In
1481 such a design, the child processes must have access to the security
1482 context data structure created within the parent by its call to
1483 gss_accept_sec_context so that they can use per-message protection
1484 services and delete the security context when the communication session
1485 ends.
1487 Since the security context data structure is expected to contain
1488 sequencing information, it is impractical in general to share a context
1489 between processes. Thus GSSAPI provides a call (gss_export_sec_context)
1490 that the process which currently owns the context can call to declare
1491 that it has no intention to use the context subsequently, and to create
1492 an inter-process token containing information needed by the adopting
1493 process to successfully import the context. After successful completion
1494 of this call, the original security context is made inaccessible to the
1495 calling process by GSSAPI, and any context handles referring to this
1496 context are no longer valid. The originating process transfers the
1497 inter-process token to the adopting process, which passes it to
1498 gss_import_sec_context, and a fresh gss_ctx_id_t is created such that it
1499 is functionally identical to the original context.
1501 The inter-process token may contain sensitive data from the original
1502 security context (including cryptographic keys). Applications using
1503 inter-process tokens to transfer security contexts must take appropriate
1504 steps to protect these tokens in transit.
1508 Wray Document Expiration: 1 September 1997 [Page 23]
1511 \f
1516 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1520 Implementations are not required to support the inter-process transfer
1521 of security contexts. The ability to transfer a security context is
1522 indicated when the context is created, by gss_init_sec_context or
1523 gss_accept_sec_context setting the GSS_C_TRANS_FLAG bit in their
1524 ret_flags parameter.
1527 6.7. The use of incomplete contexts
1529 Some mechanisms may allow the per-message services to be used before the
1530 context establishment process is complete. For example, a mechanism may
1531 include sufficient information in its initial context-level token for
1532 the context acceptor to immediately decode messages protected with
1533 gss_wrap or gss_get_mic. For such a mechanism, the initiating
1534 application need not wait until subsequent context-level tokens have
1535 been sent and received before invoking the per-message protection
1536 services.
1538 The ability of a context to provide per-message services in advance of
1539 complete context establishment is indicated by the setting of the
1540 GSS_C_PROT_READY_FLAG bit in the ret_flags parameter from
1541 gss_init_sec_context and gss_accept_sec_context. Applications wishing
1542 to use per-message protection services on partially-established contexts
1543 should check this flag before attempting to invoke gss_wrap or
1544 gss_get_mic.
1548 7. GSS-API routine descriptions
1550 In addition to the explicit major status codes documented here, the code
1551 GSS_S_FAILURE may be returned by any routine, indicating an
1552 implementation-specific or mechanism-specific error condition, further
1553 details of which are reported via the minor_status parameter.
1574 Wray Document Expiration: 1 September 1997 [Page 24]
1577 \f
1582 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1586 7.1. gss_accept_sec_context
1588 OM_uint32 gss_accept_sec_context (
1589 OM_uint32 * minor_status,
1590 gss_ctx_id_t * context_handle,
1591 const gss_cred_id_t acceptor_cred_handle,
1592 const gss_buffer_t input_token_buffer,
1593 const gss_channel_bindings_t
1594 input_chan_bindings,
1595 const gss_name_t * src_name,
1596 gss_OID * mech_type,
1597 gss_buffer_t output_token,
1598 OM_uint32 * ret_flags,
1599 OM_uint32 * time_rec,
1600 gss_cred_id_t * delegated_cred_handle)
1602 Purpose:
1604 Allows a remotely initiated security context between the application and
1605 a remote peer to be established. The routine may return a output_token
1606 which should be transferred to the peer application, where the peer
1607 application will present it to gss_init_sec_context. If no token need
1608 be sent, gss_accept_sec_context will indicate this by setting the length
1609 field of the output_token argument to zero. To complete the context
1610 establishment, one or more reply tokens may be required from the peer
1611 application; if so, gss_accept_sec_context will return a status flag of
1612 GSS_S_CONTINUE_NEEDED, in which case it should be called again when the
1613 reply token is received from the peer application, passing the token to
1614 gss_accept_sec_context via the input_token parameters.
1616 Portable applications should be constructed to use the token length and
1617 return status to determine whether a token needs to be sent or waited
1618 for. Thus a typical portable caller should always invoke
1619 gss_accept_sec_context within a loop:
1621 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
1622 ...
1624 do {
1625 receive_token_from_peer(input_token);
1626 maj_stat = gss_accept_sec_context(&min_stat,
1627 &context_hdl,
1628 cred_hdl,
1629 input_token,
1630 input_bindings,
1631 &client_name,
1632 &mech_type,
1633 output_token,
1634 &ret_flags,
1635 &time_rec,
1636 &deleg_cred);
1640 Wray Document Expiration: 1 September 1997 [Page 25]
1643 \f
1648 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1652 if (GSS_ERROR(maj_stat)) {
1653 report_error(maj_stat, min_stat);
1654 };
1655 if (output_token->length != 0) {
1656 send_token_to_peer(output_token);
1657 gss_release_buffer(&min_stat,
1658 output_token)
1659 };
1660 if (GSS_ERROR(maj_stat)) {
1661 if (context_hdl != GSS_C_NO_CONTEXT)
1662 gss_delete_sec_context(&min_stat,
1663 &context_hdl,
1664 GSS_C_NO_BUFFER);
1665 break;
1666 };
1667 } while (maj_stat & GSS_S_CONTINUE_NEEDED);
1670 Whenever the routine returns a major status that includes the value
1671 GSS_S_CONTINUE_NEEDED, the context is not fully established and the
1672 following restrictions apply to the output parameters:
1674 (a) The value returned via the time_rec parameter is undefined
1676 (b) Unless the accompanying ret_flags parameter contains the bit
1677 GSS_C_PROT_READY_FLAG, indicating that per-message services may be
1678 applied in advance of a successful completion status, the value
1679 returned via the mech_type parameter may be undefined until the
1680 routine returns a major status value of GSS_S_COMPLETE.
1682 (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG,
1683 GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG,
1684 GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the
1685 ret_flags parameter should contain the values that the
1686 implementation expects would be valid if context establishment
1687 were to succeed.
1689 The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
1690 within ret_flags should indicate the actual state at the time
1691 gss_accept_sec_context returns, whether or not the context is
1692 fully established.
1694 Although this requires that GSSAPI implementations set the
1695 GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller
1696 (i.e. when accompanied by a GSS_S_COMPLETE status code),
1697 applications should not rely on this behavior as the flag was not
1698 defined in Version 1 of the GSSAPI. Instead, applications should
1699 be prepared to use per-message services after a successful context
1700 establishment, according to the GSS_C_INTEG_FLAG and
1701 GSS_C_CONF_FLAG values.
1706 Wray Document Expiration: 1 September 1997 [Page 26]
1709 \f
1714 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1718 All other bits within the ret_flags argument should be set to
1719 zero.
1722 While the routine returns GSS_S_CONTINUE_NEEDED, the values returned via
1723 the ret_flags argument indicate the services that the implementation
1724 expects to be available from the established context.
1726 If the initial call of gss_accept_sec_context() fails, the
1727 implementation should not create a context object, and should leave the
1728 value of the context_handle parameter set to GSS_C_NO_CONTEXT to
1729 indicate this. In the event of a failure on a subsequent call, the
1730 implementation is permitted to delete the "half-built" security context
1731 (in which case it should set the context_handle parameter to
1732 GSS_C_NO_CONTEXT), but the preferred behavior is to leave the security
1733 context (and the context_handle parameter) untouched for the application
1734 to delete (using gss_delete_sec_context).
1736 Parameters:
1738 context_handle gss_ctx_id_t, read/modify
1739 context handle for new context. Supply
1740 GSS_C_NO_CONTEXT for first call; use value
1741 returned in subsequent calls. Once
1742 gss_accept_sec_context() has returned a value
1743 via this parameter, resources have been assigned
1744 to the corresponding context, and must be
1745 freed by the application after use with a call
1746 to gss_delete_sec_context().
1749 acceptor_cred_handle gss_cred_id_t, read
1750 Credential handle claimed by context acceptor.
1751 Specify GSS_C_NO_CREDENTIAL to accept the
1752 context as a default principal. If
1753 GSS_C_NO_CREDENTIAL is specified, but no
1754 default acceptor principal is defined,
1755 GSS_S_NO_CRED will be returned.
1757 input_token_buffer buffer, opaque, read
1758 token obtained from remote application.
1760 input_chan_bindings channel bindings, read, optional
1761 Application-specified bindings. Allows
1762 application to securely bind channel
1763 identification information to the security
1764 context. If channel bindings are not
1765 used, specify GSS_C_NO_CHANNEL_BINDINGS.
1767 src_name gss_name_t, modify, optional
1768 Authenticated name of context initiator.
1772 Wray Document Expiration: 1 September 1997 [Page 27]
1775 \f
1780 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1784 After use, this name should be deallocated by
1785 passing it to gss_release_name(). If not
1786 required, specify NULL.
1788 mech_type Object ID, modify, optional
1789 Security mechanism used. The returned
1790 OID value will be a pointer into static
1791 storage, and should be treated as read-only
1792 by the caller (in particular, it does not
1793 need to be freed). If not required, specify
1794 NULL.
1796 output_token buffer, opaque, modify
1797 Token to be passed to peer application. If the
1798 length field of the returned token buffer is 0,
1799 then no token need be passed to the peer
1800 application. If a non-zero length field is
1801 returned, the associated storage must be freed
1802 after use by the application with a call to
1803 gss_release_buffer().
1805 ret_flags bit-mask, modify, optional
1806 Contains various independent flags, each of
1807 which indicates that the context supports a
1808 specific service option. If not needed,
1809 specify NULL. Symbolic names are
1810 provided for each flag, and the symbolic names
1811 corresponding to the required flags
1812 should be logically-ANDed with the ret_flags
1813 value to test whether a given option is
1814 supported by the context. The flags are:
1815 GSS_C_DELEG_FLAG
1816 True - Delegated credentials are available
1817 via the delegated_cred_handle
1818 parameter
1819 False - No credentials were delegated
1820 GSS_C_MUTUAL_FLAG
1821 True - Remote peer asked for mutual
1822 authentication
1823 False - Remote peer did not ask for mutual
1824 authentication
1825 GSS_C_REPLAY_FLAG
1826 True - replay of protected messages
1827 will be detected
1828 False - replayed messages will not be
1829 detected
1830 GSS_C_SEQUENCE_FLAG
1831 True - out-of-sequence protected
1832 messages will be detected
1833 False - out-of-sequence messages will not
1834 be detected
1838 Wray Document Expiration: 1 September 1997 [Page 28]
1841 \f
1846 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1850 GSS_C_CONF_FLAG
1851 True - Confidentiality service may be invoked
1852 by calling the gss_wrap routine
1853 False - No confidentiality service (via
1854 gss_wrap) available. gss_wrap will
1855 provide message encapsulation,
1856 data-origin authentication and
1857 integrity services only.
1858 GSS_C_INTEG_FLAG
1859 True - Integrity service may be invoked by
1860 calling either gss_get_mic or gss_wrap
1861 routines.
1862 False - Per-message integrity service
1863 unavailable.
1864 GSS_C_ANON_FLAG
1865 True - The initiator does not wish to
1866 be authenticated; the src_name
1867 parameter (if requested) contains
1868 an anonymous internal name.
1869 False - The initiator has been
1870 authenticated normally.
1871 GSS_C_PROT_READY_FLAG
1872 True - Protection services (as specified
1873 by the states of the GSS_C_CONF_FLAG
1874 and GSS_C_INTEG_FLAG) are available
1875 if the accompanying major status return
1876 value is either GSS_S_COMPLETE or
1877 GSS_S_CONTINUE_NEEDED.
1878 False - Protection services (as specified
1879 by the states of the GSS_C_CONF_FLAG
1880 and GSS_C_INTEG_FLAG) are available
1881 only if the accompanying major status
1882 return value is GSS_S_COMPLETE.
1883 GSS_C_TRANS_FLAG
1884 True - The resultant security context may
1885 be transferred to other processes via
1886 a call to gss_export_sec_context().
1887 False - The security context is not
1888 transferrable.
1889 All other bits should be set to zero.
1891 time_rec Integer, modify, optional
1892 number of seconds for which the context
1893 will remain valid. Specify NULL if not required.
1895 delegated_cred_handle
1896 gss_cred_id_t, modify, optional
1897 credential handle for credentials received from
1898 context initiator. Only valid if deleg_flag in
1899 ret_flags is true, in which case an explicit
1903 Wray Document Expiration: 1 September 1997 [Page 29]
1906 \f
1911 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1915 credential handle (i.e. not GSS_C_NO_CREDENTIAL)
1916 will be returned; if deleg_flag is false,
1917 gss_accept_context() will set this parameter to
1918 GSS_C_NO_CREDENTIAL. If a credential handle is
1919 returned, the associated resources must be released
1920 by the application after use with a call to
1921 gss_release_cred(). Specify NULL if not required.
1924 minor_status Integer, modify
1925 Mechanism specific status code.
1928 Function value: GSS status code
1930 GSS_S_COMPLETE Successful completion
1932 GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application
1933 is required to complete the context, and that
1934 gss_accept_sec_context must be called again with that
1935 token.
1937 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the
1938 input_token failed.
1940 GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed
1941 on the credential failed.
1943 GSS_S_NO_CRED The supplied credentials were not valid for context
1944 acceptance, or the credential handle did not reference
1945 any credentials.
1947 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
1949 GSS_S_BAD_BINDINGS The input_token contains different channel bindings
1950 to those specified via the input_chan_bindings
1951 parameter.
1953 GSS_S_NO_CONTEXT Indicates that the supplied context handle did not
1954 refer to a valid context.
1956 GSS_S_BAD_SIG The input_token contains an invalid MIC.
1958 GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error
1959 during context establishment.
1961 GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a
1962 token already processed. This is a fatal error during
1963 context establishment.
1969 Wray Document Expiration: 1 September 1997 [Page 30]
1972 \f
1977 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
1981 GSS_S_BAD_MECH The received token specified a mechanism that is not
1982 supported by the implementation or the provided
1983 credential.
1991 7.2. gss_acquire_cred
1994 OM_uint32 gss_acquire_cred (
1995 OM_uint32 * minor_status,
1996 const gss_name_t desired_name,
1997 OM_uint32 time_req,
1998 const gss_OID_set desired_mechs,
1999 gss_cred_usage_t cred_usage,
2000 gss_cred_id_t * output_cred_handle,
2001 gss_OID_set * actual_mechs,
2002 OM_uint32 * time_rec)
2004 Purpose:
2006 Allows an application to acquire a handle for a pre-existing credential
2007 by name. GSS-API implementations must impose a local access-control
2008 policy on callers of this routine to prevent unauthorized callers from
2009 acquiring credentials to which they are not entitled. This routine is
2010 not intended to provide a ``login to the network'' function, as such a
2011 function would involve the creation of new credentials rather than
2012 merely acquiring a handle to existing credentials. Such functions, if
2013 required, should be defined in implementation-specific extensions to the
2014 API.
2016 If desired_name is GSS_C_NO_NAME, the call is interpreted as a request
2017 for a credential handle that will invoke default behavior when passed to
2018 gss_init_sec_context() (if cred_usage is GSS_C_INITIATE or GSS_C_BOTH)
2019 or gss_accept_sec_context() (if cred_usage is GSS_C_ACCEPT or
2020 GSS_C_BOTH).
2022 This routine is expected to be used primarily by context acceptors,
2023 since implementations are likely to provide mechanism-specific ways of
2024 obtaining GSS-API initiator credentials from the system login process.
2025 Some implementations may therefore not support the acquisition of
2026 GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred for any
2027 name other than an empty name.
2029 If credential acquisition is time-consuming for a mechanism, the
2030 mechanism may chooses to delay the actual acquisition until the
2031 credential is required (e.g. by gss_init_sec_context or
2035 Wray Document Expiration: 1 September 1997 [Page 31]
2038 \f
2043 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2047 gss_accept_sec_context). Such mechanism-specific implementation
2048 decisions should be invisible to the calling application; thus a call of
2049 gss_inquire_cred immediately following the call of gss_acquire_cred must
2050 return valid credential data, and may therefore incur the overhead of a
2051 deferred credential acquisition.
2053 Parameters:
2055 desired_name gss_name_t, read
2056 Name of principal whose credential
2057 should be acquired
2059 time_req Integer, read, optional
2060 number of seconds that credentials
2061 should remain valid. Specify GSS_C_INDEFINITE
2062 to request that the credentials have the maximum
2063 permitted lifetime.
2065 desired_mechs Set of Object IDs, read, optional
2066 set of underlying security mechanisms that
2067 may be used. GSS_C_NO_OID_SET may be used
2068 to obtain an implementation-specific default.
2070 cred_usage gss_cred_usage_t, read
2071 GSS_C_BOTH - Credentials may be used
2072 either to initiate or accept
2073 security contexts.
2074 GSS_C_INITIATE - Credentials will only be
2075 used to initiate security
2076 contexts.
2077 GSS_C_ACCEPT - Credentials will only be used to
2078 accept security contexts.
2080 output_cred_handle gss_cred_id_t, modify
2081 The returned credential handle. Resources
2082 associated with this credential handle must
2083 be released by the application after use
2084 with a call to gss_release_cred().
2086 actual_mechs Set of Object IDs, modify, optional
2087 The set of mechanisms for which the
2088 credential is valid. Storage associated
2089 with the returned OID-set must be released by
2090 the application after use with a call to
2091 gss_release_oid_set(). Specify NULL if not
2092 required.
2094 time_rec Integer, modify, optional
2095 Actual number of seconds for which the
2096 returned credentials will remain valid. If the
2097 implementation does not support expiration of
2101 Wray Document Expiration: 1 September 1997 [Page 32]
2104 \f
2109 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2113 credentials, the value GSS_C_INDEFINITE will
2114 be returned. Specify NULL if not required
2116 minor_status Integer, modify
2117 Mechanism specific status code.
2119 Function value: GSS status code
2121 GSS_S_COMPLETE Successful completion
2123 GSS_S_BAD_MECH Unavailable mechanism requested
2125 GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not
2126 supported
2128 GSS_S_BAD_NAME Value supplied for desired_name parameter is ill-
2129 formed.
2131 GSS_S_CREDENTIALS_EXPIRED The credentials could not be acquired because
2132 they have expired.
2134 GSS_S_NO_CRED No credentials were found for the specified name.
2142 7.3. gss_add_cred
2145 OM_uint32 gss_add_cred (
2146 OM_uint32 * minor_status,
2147 const gss_cred_id_t input_cred_handle,
2148 const gss_name_t desired_name,
2149 const gss_OID desired_mech,
2150 gss_cred_usage_t cred_usage,
2151 OM_uint32 initiator_time_req,
2152 OM_uint32 acceptor_time_req,
2153 gss_cred_id_t * output_cred_handle,
2154 gss_OID_set * actual_mechs,
2155 OM_uint32 * initiator_time_rec,
2156 OM_uint32 * acceptor_time_rec)
2167 Wray Document Expiration: 1 September 1997 [Page 33]
2170 \f
2175 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2179 Purpose:
2181 Adds a credential-element to a credential. The credential-element is
2182 identified by the name of the principal to which it refers. GSSAPI
2183 implementations must impose a local access-control policy on callers of
2184 this routine to prevent unauthorized callers from acquiring credential-
2185 elements to which they are not entitled. This routine is not intended to
2186 provide a ``login to the network'' function, as such a function would
2187 involve the creation of new mechanism-specific authentication data,
2188 rather than merely acquiring a GSSAPI handle to existing data. Such
2189 functions, if required, should be defined in implementation-specific
2190 extensions to the API.
2192 This routine is expected to be used primarily by context acceptors,
2193 since implementations are likely to provide mechanism-specific ways of
2194 obtaining GSS-API initiator credentials from the system login process.
2195 Some implementations may therefore not support the acquisition of
2196 GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred.
2198 If credential acquisition is time-consuming for a mechanism, the
2199 mechanism may chooses to delay the actual acquisition until the
2200 credential is required (e.g. by gss_init_sec_context or
2201 gss_accept_sec_context). Such mechanism-specific implementation
2202 decisions should be invisible to the calling application; thus a call of
2203 gss_inquire_cred immediately following the call of gss_acquire_cred must
2204 return valid credential data, and may therefore incur the overhead of a
2205 deferred credential acquisition.
2207 This routine can be used to either create a new credential containing
2208 all credential-elements of the original in addition to the newly-acquire
2209 credential-element, or to add the new credential-element to an existing
2210 credential. If NULL is specified for the output_cred_handle parameter
2211 argument, the new credential-element will be added to the credential
2212 identified by input_cred_handle; if a valid pointer is specified for the
2213 output_cred_handle parameter, a new credential and handle will be
2214 created.
2216 If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, the
2217 gss_add_cred will create its output_cred_handle based on default
2218 behavior. That is, the call will have the same effect as if the
2219 application had first made a call to gss_acquire_cred(), specifying the
2220 same usage and passing GSS_C_NO_NAME as the desired_name parameter to
2221 obtain an explicit credential handle embodying default behavior, passed
2222 this credential handle to gss_add_cred(), and finally called
2223 gss_release_cred() on the first credential handle.
2225 If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle parameter,
2226 a non-NULL output_cred_handle must be supplied.
2228 Parameters:
2233 Wray Document Expiration: 1 September 1997 [Page 34]
2236 \f
2241 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2245 minor_status Integer, modify
2246 Mechanism specific status code.
2248 input_cred_handle gss_cred_id_t, read, optional
2249 The credential to which a credential-element
2250 will be added. If GSS_C_NO_CREDENTIAL is
2251 specified, the routine will create the new
2252 credential based on default behavior (see
2253 description above). Note that, while the
2254 credential-handle is not modified by
2255 gss_add_cred(), the underlying credential
2256 will be modified if output_credential_handle
2257 is NULL.
2259 desired_name gss_name_t, read.
2260 Name of principal whose credential
2261 should be acquired.
2263 desired_mech Object ID, read
2264 Underlying security mechanism with which the
2265 credential may be used.
2267 cred_usage gss_cred_usage_t, read
2268 GSS_C_BOTH - Credential may be used
2269 either to initiate or accept
2270 security contexts.
2271 GSS_C_INITIATE - Credential will only be
2272 used to initiate security
2273 contexts.
2274 GSS_C_ACCEPT - Credential will only be used to
2275 accept security contexts.
2277 initiator_time_req Integer, read, optional
2278 number of seconds that the credential
2279 should remain valid for initiating security
2280 contexts. This argument is ignored if the
2281 created credentials are of type GSS_C_ACCEPT.
2282 Specify GSS_C_INDEFINITE to request that the
2283 credentials have the maximum permitted initiator
2284 lifetime.
2286 acceptor_time_req Integer, read, optional
2287 number of seconds that the credential
2288 should remain valid for accepting security
2289 contexts. This argument is ignored if the
2290 created credentials are of type GSS_C_INITIATE.
2291 Specify GSS_C_INDEFINITE to request that the
2292 credentials have the maximum permitted initiator
2293 lifetime.
2298 Wray Document Expiration: 1 September 1997 [Page 35]
2301 \f
2306 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2310 output_cred_handle gss_cred_id_t, modify, optional
2311 The returned credential handle, containing
2312 the new credential-element and all the
2313 credential-elements from input_cred_handle.
2314 If a valid pointer to a gss_cred_id_t is
2315 supplied for this parameter, gss_add_cred
2316 creates a new credential handle containing all
2317 credential-elements from the input_cred_handle
2318 and the newly acquired credential-element; if
2319 NULL is specified for this parameter, the newly
2320 acquired credential-element will be added
2321 to the credential identified by input_cred_handle.
2322 The resources associated with any credential
2323 handle returned via this parameter must be
2324 released by the application after use with a
2325 call to gss_release_cred().
2327 actual_mechs Set of Object IDs, modify, optional
2328 The complete set of mechanisms for which
2329 the new credential is valid. Storage for
2330 the returned OID-set must be freed by the
2331 application after use with a call to
2332 gss_release_oid_set(). Specify NULL if
2333 not required.
2335 initiator_time_rec Integer, modify, optional
2336 Actual number of seconds for which the
2337 returned credentials will remain valid for
2338 initiating contexts using the specified
2339 mechanism. If the implementation or mechanism
2340 does not support expiration of credentials, the
2341 value GSS_C_INDEFINITE will be returned. Specify
2342 NULL if not required
2344 acceptor_time_rec Integer, modify, optional
2345 Actual number of seconds for which the
2346 returned credentials will remain valid for
2347 accepting security contexts using the specified
2348 mechanism. If the implementation or mechanism
2349 does not support expiration of credentials, the
2350 value GSS_C_INDEFINITE will be returned. Specify
2351 NULL if not required
2353 Function value: GSS status code
2355 GSS_S_COMPLETE Successful completion
2357 GSS_S_BAD_MECH Unavailable mechanism requested
2359 GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not
2360 supported
2365 Wray Document Expiration: 1 September 1997 [Page 36]
2368 \f
2373 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2377 GSS_S_BAD_NAME Value supplied for desired_name parameter is ill-
2378 formed.
2380 GSS_S_DUPLICATE_ELEMENT The credential already contains an element for
2381 the requested mechanism with overlapping usage and
2382 validity period.
2384 GSS_S_CREDENTIALS_EXPIRED The required credentials could not be added
2385 because they have expired.
2387 GSS_S_NO_CRED No credentials were found for the specified name.
2395 7.4. gss_add_oid_set_member
2397 OM_uint32 gss_add_oid_set_member (
2398 OM_uint32 * minor_status,
2399 const gss_OID member_oid,
2400 gss_OID_set * oid_set)
2402 Purpose:
2404 Add an Object Identifier to an Object Identifier set. This routine is
2405 intended for use in conjunction with gss_create_empty_oid_set when
2406 constructing a set of mechanism OIDs for input to gss_acquire_cred.
2408 The oid_set parameter must refer to an OID-set that was created by
2409 GSSAPI (e.g. a set returned by gss_create_empty_oid_set()). GSSAPI
2410 creates a copy of the member_oid and inserts this copy into the set,
2411 expanding the storage allocated to the OID-set's elements array if
2412 necessary. The routine may add the new member OID anywhere within the
2413 elements array, and implementations should verify that the new
2414 member_oid is not already contained within the elements array.
2416 Parameters:
2418 minor_status Integer, modify
2419 Mechanism specific status code
2421 member_oid Object ID, read
2422 The object identifier to copied into
2423 the set.
2425 oid_set Set of Object ID, modify
2426 The set in which the object identifier
2427 should be inserted.
2431 Wray Document Expiration: 1 September 1997 [Page 37]
2434 \f
2439 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2443 Function value: GSS status code
2445 GSS_S_COMPLETE Successful completion
2453 7.5. gss_canonicalize_name
2455 OM_uint32 gss_canonicalize_name (
2456 OM_uint32 * minor_status,
2457 const gss_name_t input_name,
2458 const gss_OID mech_type,
2459 gss_name_t * output_name)
2461 Purpose:
2463 Generate a canonical mechanism name (MN) from an arbitrary internal
2464 name. The mechanism name is the name that would be returned to a
2465 context acceptor on successful authentication of a context where the
2466 initiator used the input_name in a successful call to gss_acquire_cred,
2467 specifying an OID set containing <mech_type> as its only member,
2468 followed by a call to gss_init_sec_context, specifying <mech_type> as
2469 the authentication mechanism.
2471 Parameters:
2473 minor_status Integer, modify
2474 Mechanism specific status code
2476 input_name gss_name_t, read
2477 The name for which a canonical form is
2478 desired
2480 mech_type Object ID, read
2481 The authentication mechanism for which the
2482 canonical form of the name is desired. The
2483 desired mechanism must be specified explicitly;
2484 no default is provided.
2486 output_name gss_name_t, modify
2487 The resultant canonical name. Storage
2488 associated with this name must be freed by
2489 the application after use with a call to
2490 gss_release_name().
2492 Function value: GSS status code
2497 Wray Document Expiration: 1 September 1997 [Page 38]
2500 \f
2505 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2509 GSS_S_COMPLETE Successful completion.
2511 GSS_S_BAD_MECH The identified mechanism is not supported.
2513 GSS_S_BAD_NAMETYPE The provided internal name contains no elements that
2514 could be processed by the sepcified mechanism.
2516 GSS_S_BAD_NAME The provided internal name was ill-formed.
2524 7.6. gss_compare_name
2526 OM_uint32 gss_compare_name (
2527 OM_uint32 * minor_status,
2528 const gss_name_t name1,
2529 const gss_name_t name2,
2530 int * name_equal)
2532 Purpose:
2534 Allows an application to compare two internal-form names to determine
2535 whether they refer to the same entity.
2537 If either name presented to gss_compare_name denotes an anonymous
2538 principal, the routines should indicate that the two names do not refer
2539 to the same identity.
2541 Parameters:
2543 minor_status Integer, modify
2544 Mechanism specific status code.
2546 name1 gss_name_t, read
2547 internal-form name
2549 name2 gss_name_t, read
2550 internal-form name
2552 name_equal boolean, modify
2553 non-zero - names refer to same entity
2554 zero - names refer to different entities
2555 (strictly, the names are not known
2556 to refer to the same identity).
2558 Function value: GSS status code
2563 Wray Document Expiration: 1 September 1997 [Page 39]
2566 \f
2571 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2575 GSS_S_COMPLETE Successful completion
2577 GSS_S_BAD_NAMETYPE The two names were of incomparable types.
2579 GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed
2587 7.7. gss_context_time
2589 OM_uint32 gss_context_time (
2590 OM_uint32 * minor_status,
2591 const gss_ctx_id_t context_handle,
2592 OM_uint32 * time_rec)
2594 Purpose:
2596 Determines the number of seconds for which the specified context will
2597 remain valid.
2599 Parameters:
2601 minor_status Integer, modify
2602 Implementation specific status code.
2604 context_handle gss_ctx_id_t, read
2605 Identifies the context to be interrogated.
2607 time_rec Integer, modify
2608 Number of seconds that the context will remain
2609 valid. If the context has already expired,
2610 zero will be returned.
2612 Function value: GSS status code
2614 GSS_S_COMPLETE Successful completion
2616 GSS_S_CONTEXT_EXPIRED The context has already expired
2618 GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid
2619 context
2629 Wray Document Expiration: 1 September 1997 [Page 40]
2632 \f
2637 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2641 7.8. gss_create_empty_oid_set
2643 OM_uint32 gss_create_empty_oid_set (
2644 OM_uint32 * minor_status,
2645 gss_OID_set * oid_set)
2647 Purpose:
2649 Create an object-identifier set containing no object identifiers, to
2650 which members may be subsequently added using the
2651 gss_add_oid_set_member() routine. These routines are intended to be
2652 used to construct sets of mechanism object identifiers, for input to
2653 gss_acquire_cred.
2655 Parameters:
2657 minor_status Integer, modify
2658 Mechanism specific status code
2660 oid_set Set of Object IDs, modify
2661 The empty object identifier set.
2662 The routine will allocate the
2663 gss_OID_set_desc object, which the
2664 application must free after use with
2665 a call to gss_release_oid_set().
2667 Function value: GSS status code
2669 GSS_S_COMPLETE Successful completion
2677 7.9. gss_delete_sec_context
2679 OM_uint32 gss_delete_sec_context (
2680 OM_uint32 * minor_status,
2681 gss_ctx_id_t * context_handle,
2682 gss_buffer_t output_token)
2684 Purpose:
2686 Delete a security context. gss_delete_sec_context will delete the local
2687 data structures associated with the specified security context, and may
2688 generate an output_token, which when passed to the peer
2689 gss_process_context_token will instruct it to do likewise. If no token
2690 is required by the mechanism, the GSS-API should set the length field of
2691 the output_token (if provided) to zero. No further security services
2695 Wray Document Expiration: 1 September 1997 [Page 41]
2698 \f
2703 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2707 may be obtained using the context specified by context_handle.
2709 In addition to deleting established security contexts,
2710 gss_delete_sec_context must also be able to delete "half-built" security
2711 contexts resulting from an incomplete sequence of
2712 gss_init_sec_context()/gss_accept_sec_context() calls.
2714 The output_token parameter is retained for compatibility with version 1
2715 of the GSS-API. It is recommended that both peer applications invoke
2716 gss_delete_sec_context passing the value GSS_C_NO_BUFFER for the
2717 output_token parameter, indicating that no token is required, and that
2718 gss_delete_sec_context should simply delete local context data
2719 structures. If the application does pass a valid buffer to
2720 gss_delete_sec_context, mechanisms are encouraged to return a zero-
2721 length token, indicating that no peer action is necessary, and that no
2722 token should be transferred by the application.
2724 Parameters:
2726 minor_status Integer, modify
2727 Mechanism specific status code.
2729 context_handle gss_ctx_id_t, modify
2730 context handle identifying context to delete.
2731 After deleting the context, the GSSAPI will set
2732 this context handle to GSS_C_NO_CONTEXT.
2734 output_token buffer, opaque, modify, optional
2735 token to be sent to remote application to
2736 instruct it to also delete the context. It
2737 is recommended that applications specify
2738 GSS_C_NO_BUFFER for this parameter, requesting
2739 local deletion only. If a buffer parameter is
2740 provided by the application, the mechanism may
2741 return a token in it; mechanisms that implement
2742 only local deletion should set the length field of
2743 this token to zero to indicate to the application
2744 that no token is to be sent to the peer.
2746 Function value: GSS status code
2748 GSS_S_COMPLETE Successful completion
2750 GSS_S_NO_CONTEXT No valid context was supplied
2761 Wray Document Expiration: 1 September 1997 [Page 42]
2764 \f
2769 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2773 7.10. gss_display_name
2775 OM_uint32 gss_display_name (
2776 OM_uint32 * minor_status,
2777 const gss_name_t input_name,
2778 gss_buffer_t output_name_buffer,
2779 gss_OID * output_name_type)
2781 Purpose:
2783 Allows an application to obtain a textual representation of an opaque
2784 internal-form name for display purposes. The syntax of a printable
2785 name is defined by the GSS-API implementation.
2787 If input_name denotes an anonymous principal, the implementation should
2788 return the gss_OID value GSS_C_NT_ANONYMOUS as the output_name_type, and
2789 a textual name that is syntactically distinct from all valid supported
2790 printable names in output_name_buffer.
2792 Parameters:
2794 minor_status Integer, modify
2795 Mechanism specific status code.
2797 input_name gss_name_t, read
2798 name to be displayed
2800 output_name_buffer buffer, character-string, modify
2801 buffer to receive textual name string.
2802 The application must free storage associated
2803 with this name after use with a call to
2804 gss_release_buffer().
2806 output_name_type Object ID, modify, optional
2807 The type of the returned name. The returned
2808 gss_OID will be a pointer into static storage,
2809 and should be treated as read-only by the caller
2810 (in particular, it does not need to be freed).
2811 Specify NULL if not required.
2813 Function value: GSS status code
2815 GSS_S_COMPLETE Successful completion
2817 GSS_S_BAD_NAME input_name was ill-formed
2827 Wray Document Expiration: 1 September 1997 [Page 43]
2830 \f
2835 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2839 7.11. gss_display_status
2841 OM_uint32 gss_display_status (
2842 OM_uint32 * minor_status,
2843 OM_uint32 status_value,
2844 int status_type,
2845 const gss_OID mech_type,
2846 OM_uint32 * message_context,
2847 gss_buffer_t status_string)
2849 Purpose:
2851 Allows an application to obtain a textual representation of a GSS-API
2852 status code, for display to the user or for logging purposes. Since
2853 some status values may indicate multiple conditions, applications may
2854 need to call gss_display_status multiple times, each call generating a
2855 single text string. The message_context parameter is used by
2856 gss_acquire_cred to store state information about which error messages
2857 have already been extracted from a given status_value; message_context
2858 must be initialized to 0 by the application prior to the first call, and
2859 gss_display_status will return a non-zero value in this parameter if
2860 there are further messages to extract. The message_context parameter
2861 contains all state information required by gss_display_status in order
2862 to extract further messages from the status_value; even when a non-zero
2863 value is returned in this parameter, the application is not required to
2864 call gss_display_status again unless subsequent messages are desired.
2865 The following code extracts all messages from a given status code and
2866 prints them to stderr:
2869 OM_uint32 message_context;
2870 OM_uint32 status_code;
2871 OM_uint32 maj_status;
2872 OM_uint32 min_status;
2873 gss_buffer_desc status_string;
2875 ...
2877 message_context = 0;
2879 do {
2881 maj_status = gss_display_status (&min_status,
2882 status_code,
2883 GSS_C_GSS_CODE,
2884 GSS_C_NO_OID,
2885 &message_context,
2886 &status_string)
2888 fprintf(stderr,
2889 "%.*s\n",
2893 Wray Document Expiration: 1 September 1997 [Page 44]
2896 \f
2901 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2905 status_string.length,
2906 status_string.value);
2908 gss_release_buffer(&min_status,
2909 &status_string);
2911 } while (message_context != 0);
2915 Parameters:
2917 minor_status Integer, modify
2918 Mechanism specific status code.
2920 status_value Integer, read
2921 Status value to be converted
2923 status_type Integer, read
2924 GSS_C_GSS_CODE - status_value is a GSS status
2925 code
2926 GSS_C_MECH_CODE - status_value is a mechanism
2927 status code
2929 mech_type Object ID, read, optional
2930 Underlying mechanism (used to interpret a
2931 minor status value) Supply GSS_C_NO_OID to
2932 obtain the system default.
2934 message_context Integer, read/modify
2935 Should be initialized to zero by the
2936 application prior to the first call.
2937 On return from gss_display_status(),
2938 a non-zero status_value parameter indicates
2939 that additional messages may be extracted
2940 from the status code via subsequent calls
2941 to gss_display_status(), passing the same
2942 status_value, status_type, mech_type, and
2943 message_context parameters.
2945 status_string buffer, character string, modify
2946 textual interpretation of the status_value.
2947 Storage associated with this parameter must
2948 be freed by the application after use with
2949 a call to gss_release_buffer().
2951 Function value: GSS status code
2953 GSS_S_COMPLETE Successful completion
2959 Wray Document Expiration: 1 September 1997 [Page 45]
2962 \f
2967 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
2971 GSS_S_BAD_MECH Indicates that translation in accordance with an
2972 unsupported mechanism type was requested
2974 GSS_S_BAD_STATUS The status value was not recognized, or the status
2975 type was neither GSS_C_GSS_CODE nor GSS_C_MECH_CODE.
2983 7.12. gss_duplicate_name
2985 OM_uint32 gss_duplicate_name (
2986 OM_uint32 * minor_status,
2987 const gss_name_t src_name,
2988 gss_name_t * dest_name)
2990 Purpose:
2992 Create an exact duplicate of the existing internal name src_name. The
2993 new dest_name will be independent of src_name (i.e. src_name and
2994 dest_name must both be released, and the release of one shall not affect
2995 the validity of the other).
2997 Parameters:
2999 minor_status Integer, modify
3000 Mechanism specific status code.
3002 src_name gss_name_t, read
3003 internal name to be duplicated.
3005 dest_name gss_name_t, modify
3006 The resultant copy of <src_name>.
3007 Storage associated with this name must
3008 be freed by the application after use
3009 with a call to gss_release_name().
3011 Function value: GSS status code
3013 GSS_S_COMPLETE Successful completion
3015 GSS_S_BAD_NAME The src_name parameter was ill-formed.
3025 Wray Document Expiration: 1 September 1997 [Page 46]
3028 \f
3033 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3037 7.13. gss_export_name
3039 OM_uint32 gss_export_name (
3040 OM_uint32 * minor_status,
3041 const gss_name_t input_name,
3042 gss_buffer_t exported_name)
3044 Purpose:
3046 To produce a canonical contiguous string representation of a mechanism
3047 name (MN), suitable for direct comparison (e.g. with memcmp) for use in
3048 authorization functions (e.g. matching entries in an access-control
3049 list).
3051 The <input_name> parameter must specify a valid MN (i.e. an internal
3052 name generated by gss_accept_sec_context or by gss_canonicalize_name).
3055 Parameters:
3057 minor_status Integer, modify
3058 Mechanism specific status code
3060 input_name gss_name_t, read
3061 The MN to be exported
3063 exported_name gss_buffer_t, octet-string, modify
3064 The canonical contiguous string form of
3065 <input_name>. Storage associated with
3066 this string must freed by the application
3067 after use with gss_release_buffer().
3069 Function value: GSS status code
3071 GSS_S_COMPLETE Successful completion
3073 GSS_S_NAME_NOT_MN The provided internal name was not a mechanism name.
3075 GSS_S_BAD_NAME The provide internal name was ill-formed.
3077 GSS_S_BAD_NAMETYPE The internal name was of a type not supported by the
3078 GSSAPI implementation.
3091 Wray Document Expiration: 1 September 1997 [Page 47]
3094 \f
3099 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3103 7.14. gss_export_sec_context
3105 OM_uint32 gss_export_sec_context (
3106 OM_uint32 * minor_status,
3107 gss_ctx_id_t * context_handle,
3108 gss_buffer_t interprocess_token)
3110 Purpose:
3112 Provided to support the sharing of work between multiple processes.
3113 This routine will typically be used by the context-acceptor, in an
3114 application where a single process receives incoming connection requests
3115 and accepts security contexts over them, then passes the established
3116 context to one or more other processes for message exchange.
3117 gss_export_sec_context() deactivates the security context for the
3118 calling process and creates an interprocess token which, when passed to
3119 gss_import_sec_context in another process, will re-activate the context
3120 in the second process. Only a single instantiation of a given context
3121 may be active at any one time; a subsequent attempt by a context
3122 exporter to access the exported security context will fail.
3124 The implementation may constrain the set of processes by which the
3125 interprocess token may be imported, either as a function of local
3126 security policy, or as a result of implementation decisions. For
3127 example, some implementations may constrain contexts to be passed only
3128 between processes that run under the same account, or which are part of
3129 the same process group.
3131 The interprocess token may contain security-sensitive information (for
3132 example cryptographic keys). While mechanisms are encouraged to either
3133 avoid placing such sensitive information within interprocess tokens, or
3134 to encrypt the token before returning it to the application, in a
3135 typical object-library GSSAPI implementation this may not be possible.
3136 Thus the application must take care to protect the interprocess token,
3137 and ensure that any process to which the token is transferred is
3138 trustworthy.
3140 If creation of the interprocess token is succesful, the implementation
3141 shall deallocate all process-wide resources associated with the security
3142 context, and set the context_handle to GSS_C_NO_CONTEXT. In the event
3143 of an error that makes it impossible to complete the export of the
3144 security context, the implementation must not return an interprocess
3145 token, and should strive to leave the security context referenced by the
3146 context_handle parameter untouched. If this is impossible, it is
3147 permissible for the implementation to delete the security context,
3148 providing it also sets the context_handle parameter to GSS_C_NO_CONTEXT.
3150 Parameters:
3152 minor_status Integer, modify
3153 Mechanism specific status code
3157 Wray Document Expiration: 1 September 1997 [Page 48]
3160 \f
3165 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3169 context_handle gss_ctx_id_t, modify
3170 context handle identifying the context to transfer.
3172 interprocess_token buffer, opaque, modify
3173 token to be transferred to target process.
3174 Storage associated with this token must be
3175 freed by the application after use with a
3176 call to gss_release_buffer().
3178 Function value: GSS status code
3180 GSS_S_COMPLETE Successful completion
3182 GSS_S_CONTEXT_EXPIRED The context has expired
3184 GSS_S_NO_CONTEXT The context was invalid
3186 GSS_S_UNAVAILABLE The operation is not supported.
3194 7.15. gss_get_mic
3196 OM_uint32 gss_get_mic (
3197 OM_uint32 * minor_status,
3198 const gss_ctx_id_t context_handle,
3199 gss_qop_t qop_req,
3200 const gss_buffer_t message_buffer,
3201 gss_buffer_t msg_token)
3203 Purpose:
3205 Generates a cryptographic MIC for the supplied message, and places the
3206 MIC in a token for transfer to the peer application. The qop_req
3207 parameter allows a choice between several cryptographic algorithms, if
3208 supported by the chosen mechanism.
3210 Parameters:
3212 minor_status Integer, modify
3213 Implementation specific status code.
3215 context_handle gss_ctx_id_t, read
3216 identifies the context on which the message
3217 will be sent
3222 Wray Document Expiration: 1 September 1997 [Page 49]
3225 \f
3230 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3233 qop_req gss_qop_t, read, optional
3234 Specifies requested quality of protection.
3235 Callers are encouraged, on portability grounds,
3236 to accept the default quality of protection
3237 offered by the chosen mechanism, which may be
3238 requested by specifying GSS_C_QOP_DEFAULT for
3239 this parameter. If an unsupported protection
3240 strength is requested, gss_get_mic will return a
3241 major_status of GSS_S_BAD_QOP.
3243 message_buffer buffer, opaque, read
3244 message to be protected
3246 msg_token buffer, opaque, modify
3247 buffer to receive token. The application must
3248 free storage associated with this buffer after
3249 use with a call to gss_release_buffer().
3251 Function value: GSS status code
3253 GSS_S_COMPLETE Successful completion
3255 GSS_S_CONTEXT_EXPIRED The context has already expired
3257 GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid
3258 context
3260 GSS_S_BAD_QOP The specified QOP is not supported by the mechanism.
3268 7.16. gss_import_name
3270 OM_uint32 gss_import_name (
3271 OM_uint32 * minor_status,
3272 const gss_buffer_t input_name_buffer,
3273 const gss_OID input_name_type,
3274 gss_name_t * output_name)
3276 Purpose:
3278 Convert a contiguous string name to internal form. In general, the
3279 internal name returned (via the <output_name> parameter) will not be an
3280 MN; the exception to this is if the <input_name_type> indicates that the
3281 contiguous string provided via the <input_name_buffer> parameter is of
3282 type GSS_C_NT_EXPORT_NAME, in which case the returned internal name will
3283 be an MN for the mechanism that exported the name.
3288 Wray Document Expiration: 1 September 1997 [Page 50]
3291 \f
3296 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3300 Parameters:
3302 minor_status Integer, modify
3303 Mechanism specific status code
3305 input_name_buffer buffer, octet-string, read
3306 buffer containing contiguous string name to convert
3308 input_name_type Object ID, read, optional
3309 Object ID specifying type of printable
3310 name. Applications may specify either
3311 GSS_C_NO_OID to use a mechanism-specific
3312 default printable syntax, or an OID registered
3313 by the GSS-API implementation to name a
3314 specific namespace.
3316 output_name gss_name_t, modify
3317 returned name in internal form. Storage
3318 associated with this name must be freed
3319 by the application after use with a call
3320 to gss_release_name().
3322 Function value: GSS status code
3324 GSS_S_COMPLETE Successful completion
3326 GSS_S_BAD_NAMETYPE The input_name_type was unrecognized
3328 GSS_S_BAD_NAME The input_name parameter could not be interpreted as a
3329 name of the specified type
3338 7.17. gss_import_sec_context
3340 OM_uint32 gss_import_sec_context (
3341 OM_uint32 * minor_status,
3342 const gss_buffer_t interprocess_token,
3343 gss_ctx_id_t * context_handle)
3345 Purpose:
3347 Allows a process to import a security context established by another
3348 process. A given interprocess token may be imported only once. See
3349 gss_export_sec_context.
3354 Wray Document Expiration: 1 September 1997 [Page 51]
3357 \f
3362 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3366 Parameters:
3368 minor_status Integer, modify
3369 Mechanism specific status code
3371 interprocess_token buffer, opaque, modify
3372 token received from exporting process
3374 context_handle gss_ctx_id_t, modify
3375 context handle of newly reactivated context.
3376 Resources associated with this context handle
3377 must be released by the application after use
3378 with a call to gss_delete_sec_context().
3381 Function value: GSS status code
3383 GSS_S_COMPLETE Successful completion.
3385 GSS_S_NO_CONTEXT The token did not contain a valid context reference.
3387 GSS_S_DEFECTIVE_TOKEN The token was invalid.
3389 GSS_S_UNAVAILABLE The operation is unavailable.
3391 GSS_S_UNAUTHORIZED Local policy prevents the import of this context by
3392 the current process..
3400 7.18. gss_indicate_mechs
3402 OM_uint32 gss_indicate_mechs (
3403 OM_uint32 * minor_status,
3404 gss_OID_set * mech_set)
3406 Purpose:
3408 Allows an application to determine which underlying security mechanisms
3409 are available.
3411 Parameters:
3413 minor_status Integer, modify
3414 Mechanism specific status code.
3419 Wray Document Expiration: 1 September 1997 [Page 52]
3422 \f
3427 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3430 mech_set set of Object IDs, modify
3431 set of implementation-supported mechanisms.
3432 The returned gss_OID_set value will be a
3433 dynamically-allocated OID set, that should
3434 be released by the caller after use with a
3435 call to gss_release_oid_set().
3437 Function value: GSS status code
3439 GSS_S_COMPLETE Successful completion
3447 7.19. gss_init_sec_context
3449 OM_uint32 gss_init_sec_context (
3450 OM_uint32 * minor_status,
3451 const gss_cred_id_t initiator_cred_handle,
3452 gss_ctx_id_t * context_handle,
3453 const gss_name_t target_name,
3454 const gss_OID mech_type,
3455 OM_uint32 req_flags,
3456 OM_uint32 time_req,
3457 const gss_channel_bindings_t
3458 input_chan_bindings,
3459 const gss_buffer_t input_token
3460 gss_OID * actual_mech_type,
3461 gss_buffer_t output_token,
3462 OM_uint32 * ret_flags,
3463 OM_uint32 * time_rec )
3465 Purpose:
3467 Initiates the establishment of a security context between the
3468 application and a remote peer. Initially, the input_token parameter
3469 should be specified either as GSS_C_NO_BUFFER, or as a pointer to a
3470 gss_buffer_desc object whose length field contains the value zero. The
3471 routine may return a output_token which should be transferred to the
3472 peer application, where the peer application will present it to
3473 gss_accept_sec_context. If no token need be sent, gss_init_sec_context
3474 will indicate this by setting the length field of the output_token
3475 argument to zero. To complete the context establishment, one or more
3476 reply tokens may be required from the peer application; if so,
3477 gss_init_sec_context will return a status containing the supplementary
3478 information bit GSS_S_CONTINUE_NEEDED. In this case,
3479 gss_init_sec_context should be called again when the reply token is
3480 received from the peer application, passing the reply token to
3481 gss_init_sec_context via the input_token parameters.
3485 Wray Document Expiration: 1 September 1997 [Page 53]
3488 \f
3493 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3497 Portable applications should be constructed to use the token length and
3498 return status to determine whether a token needs to be sent or waited
3499 for. Thus a typical portable caller should always invoke
3500 gss_init_sec_context within a loop:
3502 int context_established = 0;
3503 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
3504 ...
3505 input_token->length = 0;
3507 while (!context_established) {
3508 maj_stat = gss_init_sec_context(&min_stat,
3509 cred_hdl,
3510 &context_hdl,
3511 target_name,
3512 desired_mech,
3513 desired_services,
3514 desired_time,
3515 input_bindings,
3516 input_token,
3517 &actual_mech,
3518 output_token,
3519 &actual_services,
3520 &actual_time);
3521 if (GSS_ERROR(maj_stat)) {
3522 report_error(maj_stat, min_stat);
3523 };
3524 if (output_token->length != 0) {
3525 send_token_to_peer(output_token);
3526 gss_release_buffer(&min_stat,
3527 output_token)
3528 };
3529 if (GSS_ERROR(maj_stat)) {
3530 if (context_hdl != GSS_C_NO_CONTEXT)
3531 gss_delete_sec_context(&min_stat,
3532 &context_hdl,
3533 GSS_C_NO_BUFFER);
3534 break;
3535 };
3536 if (maj_stat & GSS_S_CONTINUE_NEEDED) {
3537 receive_token_from_peer(input_token);
3538 } else {
3539 context_established = 1;
3540 };
3541 };
3543 Whenever the routine returns a major status that includes the value
3544 GSS_S_CONTINUE_NEEDED, the context is not fully established and the
3545 following restrictions apply to the output parameters:
3551 Wray Document Expiration: 1 September 1997 [Page 54]
3554 \f
3559 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3563 (a) The value returned via the time_rec parameter is undefined
3565 (b) Unless the accompanying ret_flags parameter contains the bit
3566 GSS_C_PROT_READY_FLAG, indicating that per-message services may be
3567 applied in advance of a successful completion status, the value
3568 returned via the actual_mech_type parameter is undefined until the
3569 routine returns a major status value of GSS_S_COMPLETE.
3571 (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG,
3572 GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG,
3573 GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the
3574 ret_flags parameter should contain the values that the
3575 implementation expects would be valid if context establishment
3576 were to succeed. In particular, if the application has requested
3577 a service such as delegation or anonymous authentication via the
3578 req_flags argument, and such a service is unavailable from the
3579 underlying mechanism, gss_init_sec_context should generate a token
3580 that will not provide the service, and indicate via the ret_flags
3581 argument that the service will not be supported. The application
3582 may choose to abort the context establishment by calling
3583 gss_delete_sec_context (if it cannot continue in the absence of
3584 the service), or it may choose to transmit the token and continue
3585 context establishment (if the service was merely desired but not
3586 mandatory).
3588 The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
3589 within ret_flags should indicate the actual state at the time
3590 gss_init_sec_context returns, whether or not the context is fully
3591 established.
3593 Although this requires that GSSAPI implementations set the
3594 GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller
3595 (i.e. when accompanied by a GSS_S_COMPLETE status code),
3596 applications should not rely on this behavior as the flag was not
3597 defined in Version 1 of the GSSAPI. Instead, applications should
3598 be prepared to use per-message services after a successful context
3599 establishment, according to the GSS_C_INTEG_FLAG and
3600 GSS_C_CONF_FLAG values.
3602 All other bits within the ret_flags argument should be set to
3603 zero.
3605 If the initial call of gss_init_sec_context() fails, the implementation
3606 should not create a context object, and should leave the value of the
3607 context_handle parameter set to GSS_C_NO_CONTEXT to indicate this. In
3608 the event of a failure on a subsequent call, the implementation is
3609 permitted to delete the "half-built" security context (in which case it
3610 should set the context_handle parameter to GSS_C_NO_CONTEXT), but the
3611 preferred behavior is to leave the security context untouched for the
3612 application to delete (using gss_delete_sec_context).
3617 Wray Document Expiration: 1 September 1997 [Page 55]
3620 \f
3625 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3629 Parameters:
3631 minor_status Integer, modify
3632 Mechanism specific status code.
3634 initiator_cred_handle gss_cred_id_t, read, optional
3635 handle for credentials claimed. Supply
3636 GSS_C_NO_CREDENTIAL to act as a default
3637 initiator principal. If no default
3638 initiator is defined, the function will
3639 return GSS_S_NO_CRED.
3641 context_handle gss_ctx_id_t, read/modify
3642 context handle for new context. Supply
3643 GSS_C_NO_CONTEXT for first call; use value
3644 returned by first call in continuation calls.
3645 Resources associated with this context-handle
3646 must be released by the application after use
3647 with a call to gee_delete_sec_context().
3649 target_name gss_name_t, read
3650 Name of target
3652 mech_type OID, read, optional
3653 Object ID of desired mechanism. Supply
3654 GSS_C_NO_OID to obtain an implementation
3655 specific default
3657 req_flags bit-mask, read
3658 Contains various independent flags, each of
3659 which requests that the context support a
3660 specific service option. Symbolic
3661 names are provided for each flag, and the
3662 symbolic names corresponding to the required
3663 flags should be logically-ORed
3664 together to form the bit-mask value. The
3665 flags are:
3667 GSS_C_DELEG_FLAG
3668 True - Delegate credentials to remote peer
3669 False - Don't delegate
3670 GSS_C_MUTUAL_FLAG
3671 True - Request that remote peer
3672 authenticate itself
3673 False - Authenticate self to remote peer
3674 only
3675 GSS_C_REPLAY_FLAG
3676 True - Enable replay detection for
3677 messages protected with gss_wrap
3678 or gss_get_mic
3679 False - Don't attempt to detect
3680 replayed messages
3683 Wray Document Expiration: 1 September 1997 [Page 56]
3686 \f
3691 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3695 GSS_C_SEQUENCE_FLAG
3696 True - Enable detection of out-of-sequence
3697 protected messages
3698 False - Don't attempt to detect
3699 out-of-sequence messages
3700 GSS_C_ANON_FLAG
3701 True - Do not reveal the initiator's
3702 identity to the acceptor.
3703 False - Authenticate normally.
3705 time_req Integer, read, optional
3706 Desired number of seconds for which context
3707 should remain valid. Supply 0 to request a
3708 default validity period.
3710 input_chan_bindings channel bindings, read, optional
3711 Application-specified bindings. Allows
3712 application to securely bind channel
3713 identification information to the security
3714 context. Specify GSS_C_NO_CHANNEL_BINDINGS
3715 if channel bindings are not used.
3717 input_token buffer, opaque, read, optional (see text)
3718 Token received from peer application.
3719 Supply GSS_C_NO_BUFFER, or a pointer to
3720 a buffer containing the value GSS_C_EMPTY_BUFFER
3721 on initial call.
3723 actual_mech_type OID, modify, optional
3724 Actual mechanism used. The OID returned via
3725 this parameter will be a pointer to static
3726 storage that should be treated as read-only;
3727 In particular the application should not attempt
3728 to free it. Specify NULL if not required.
3730 output_token buffer, opaque, modify
3731 token to be sent to peer application. If
3732 the length field of the returned buffer is
3733 zero, no token need be sent to the peer
3734 application. Storage associated with this
3735 buffer must be freed by the application
3736 after use with a call to gss_release_buffer().
3738 ret_flags bit-mask, modify, optional
3739 Contains various independent flags, each of which
3740 indicates that the context supports a specific
3741 service option. Specify NULL if not
3742 required. Symbolic names are provided
3743 for each flag, and the symbolic names
3744 corresponding to the required flags should be
3748 Wray Document Expiration: 1 September 1997 [Page 57]
3751 \f
3756 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3760 logically-ANDed with the ret_flags value to test
3761 whether a given option is supported by the
3762 context. The flags are:
3764 GSS_C_DELEG_FLAG
3765 True - Credentials were delegated to
3766 the remote peer
3767 False - No credentials were delegated
3768 GSS_C_MUTUAL_FLAG
3769 True - Remote peer has been asked to
3770 authenticated itself
3771 False - Remote peer has not been asked to
3772 authenticate itself
3773 GSS_C_REPLAY_FLAG
3774 True - replay of protected messages
3775 will be detected
3776 False - replayed messages will not be
3777 detected
3778 GSS_C_SEQUENCE_FLAG
3779 True - out-of-sequence protected
3780 messages will be detected
3781 False - out-of-sequence messages will
3782 not be detected
3783 GSS_C_CONF_FLAG
3784 True - Confidentiality service may be
3785 invoked by calling gss_wrap routine
3786 False - No confidentiality service (via
3787 gss_wrap) available. gss_wrap will
3788 provide message encapsulation,
3789 data-origin authentication and
3790 integrity services only.
3791 GSS_C_INTEG_FLAG
3792 True - Integrity service may be invoked by
3793 calling either gss_get_mic or gss_wrap
3794 routines.
3795 False - Per-message integrity service
3796 unavailable.
3797 GSS_C_ANON_FLAG
3798 True - The initiator's identity has not been
3799 revealed, and will not be revealed if
3800 any emitted token is passed to the
3801 acceptor.
3802 False - The initiator's identity has been or
3803 will be authenticated normally.
3804 GSS_C_PROT_READY_FLAG
3805 True - Protection services (as specified
3806 by the states of the GSS_C_CONF_FLAG
3807 and GSS_C_INTEG_FLAG) are available for
3808 use if the accompanying major status
3809 return value is either GSS_S_COMPLETE or
3810 GSS_S_CONTINUE_NEEDED.
3814 Wray Document Expiration: 1 September 1997 [Page 58]
3817 \f
3822 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3826 False - Protection services (as specified
3827 by the states of the GSS_C_CONF_FLAG
3828 and GSS_C_INTEG_FLAG) are available
3829 only if the accompanying major status
3830 return value is GSS_S_COMPLETE.
3831 GSS_C_TRANS_FLAG
3832 True - The resultant security context may
3833 be transferred to other processes via
3834 a call to gss_export_sec_context().
3835 False - The security context is not
3836 transferrable.
3837 All other bits should be set to zero.
3839 time_rec Integer, modify, optional
3840 number of seconds for which the context
3841 will remain valid. If the implementation does
3842 not support context expiration, the value
3843 GSS_C_INDEFINITE will be returned. Specify
3844 NULL if not required.
3846 Function value: GSS status code
3848 GSS_S_COMPLETE Successful completion
3850 GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application
3851 is required to complete the context, and that
3852 gss_init_sec_context must be called again with that
3853 token.
3855 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the
3856 input_token failed
3858 GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed
3859 on the credential failed.
3861 GSS_S_NO_CRED The supplied credentials were not valid for context
3862 initiation, or the credential handle did not reference
3863 any credentials.
3865 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired
3867 GSS_S_BAD_BINDINGS The input_token contains different channel bindings
3868 to those specified via the input_chan_bindings
3869 parameter
3871 GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC that
3872 could not be verified
3874 GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error
3875 during context establishment
3880 Wray Document Expiration: 1 September 1997 [Page 59]
3883 \f
3888 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3892 GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a
3893 token already processed. This is a fatal error during
3894 context establishment.
3896 GSS_S_NO_CONTEXT Indicates that the supplied context handle did not
3897 refer to a valid context
3899 GSS_S_BAD_NAMETYPE The provided target_name parameter contained an
3900 invalid or unsupported type of name
3902 GSS_S_BAD_NAME The provided target_name parameter was ill-formed.
3904 GSS_S_BAD_MECH The specified mechanism is not supported by the
3905 provided credential, or is unrecognized by the
3906 implementation.
3914 7.20. gss_inquire_context
3916 OM_uint32 gss_inquire_context (
3917 OM_uint32 * minor_status,
3918 const gss_ctx_id_t context_handle,
3919 gss_name_t * src_name,
3920 gss_name_t * targ_name,
3921 OM_uint32 * lifetime_rec,
3922 gss_OID * mech_type,
3923 OM_uint32 * ctx_flags,
3924 int * locally_initiated,
3925 int * open )
3927 Purpose:
3929 Obtains information about a security context. The caller must already
3930 have obtained a handle that refers to the context, although the context
3931 need not be fully established.
3933 Parameters:
3935 minor_status Integer, modify
3936 Mechanism specific status code
3938 context_handle gss_ctx_id_t, read
3939 A handle that refers to the security context.
3941 src_name gss_name_t, modify, optional
3942 The name of the context initiator.
3946 Wray Document Expiration: 1 September 1997 [Page 60]
3949 \f
3954 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
3958 If the context was established using anonymous
3959 authentication, and if the application invoking
3960 gss_inquire_context is the context acceptor,
3961 an anonymous name will be returned. Storage
3962 associated with this name must be freed by the
3963 application after use with a call to
3964 gss_release_name(). Specify NULL if not
3965 required.
3967 targ_name gss_name_t, modify, optional
3968 The name of the context acceptor.
3969 Storage associated with this name must be
3970 freed by the application after use with a call
3971 to gss_release_name(). Specify NULL if not
3972 Specify NULL if not required.
3974 lifetime_rec Integer, modify, optional
3975 The number of seconds for which the context
3976 will remain valid. If the context has
3977 expired, this parameter will be set to zero.
3978 If the implementation does not support
3979 context expiration, the value
3980 GSS_C_INDEFINITE will be returned. Specify
3981 NULL if not required.
3983 mech_type gss_OID, modify, optional
3984 The security mechanism providing the
3985 context. The returned OID will be a
3986 pointer to static storage that should
3987 be treated as read-only by the application;
3988 in particular the application should not
3989 attempt to free it. Specify NULL if not
3990 required.
3992 ctx_flags bit-mask, modify, optional
3993 Contains various independent flags, each of
3994 which indicates that the context supports
3995 (or is expected to support, if ctx_open is
3996 false) a specific service option. If not
3997 needed, specify NULL. Symbolic names are
3998 provided for each flag, and the symbolic names
3999 corresponding to the required flags
4000 should be logically-ANDed with the ret_flags
4001 value to test whether a given option is
4002 supported by the context. The flags are:
4004 GSS_C_DELEG_FLAG
4005 True - Credentials were delegated from
4006 the initiator to the acceptor.
4007 False - No credentials were delegated
4011 Wray Document Expiration: 1 September 1997 [Page 61]
4014 \f
4019 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4022 GSS_C_MUTUAL_FLAG
4023 True - The acceptor was authenticated
4024 to the initiator
4025 False - The acceptor did not authenticate
4026 itself.
4027 GSS_C_REPLAY_FLAG
4028 True - replay of protected messages
4029 will be detected
4030 False - replayed messages will not be
4031 detected
4032 GSS_C_SEQUENCE_FLAG
4033 True - out-of-sequence protected
4034 messages will be detected
4035 False - out-of-sequence messages will not
4036 be detected
4037 GSS_C_CONF_FLAG
4038 True - Confidentiality service may be invoked
4039 by calling gss_wrap routine
4040 False - No confidentiality service (via
4041 gss_wrap) available. gss_wrap will
4042 provide message encapsulation,
4043 data-origin authentication and
4044 integrity services only.
4045 GSS_C_INTEG_FLAG
4046 True - Integrity service may be invoked by
4047 calling either gss_get_mic or gss_wrap
4048 routines.
4049 False - Per-message integrity service
4050 unavailable.
4051 GSS_C_ANON_FLAG
4052 True - The initiator's identity will not
4053 be revealed to the acceptor.
4054 The src_name parameter (if
4055 requested) contains an anonymous
4056 internal name.
4057 False - The initiator has been
4058 authenticated normally.
4059 GSS_C_PROT_READY_FLAG
4060 True - Protection services (as specified
4061 by the states of the GSS_C_CONF_FLAG
4062 and GSS_C_INTEG_FLAG) are available
4063 for use.
4064 False - Protection services (as specified
4065 by the states of the GSS_C_CONF_FLAG
4066 and GSS_C_INTEG_FLAG) are available
4067 only if the context is fully
4068 established (i.e. if the open parameter
4069 is non-zero).
4070 GSS_C_TRANS_FLAG
4071 True - The resultant security context may
4072 be transferred to other processes via
4073 a call to gss_export_sec_context().
4074 False - The security context is not
4075 transferrable.
4077 Wray Document Expiration: 1 September 1997 [Page 62]
4080 \f
4085 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4091 locally_initiated Boolean, modify
4092 Non-zero if the invoking application is the
4093 context initiator.
4094 Specify NULL if not required.
4096 open Boolean, modify
4097 Non-zero if the context is fully established;
4098 Zero if a context-establishment token
4099 is expected from the peer application.
4100 Specify NULL if not required.
4102 Function value: GSS status code
4104 GSS_S_COMPLETE Successful completion
4106 GSS_S_NO_CONTEXT The referenced context could not be accessed.
4108 GSS_S_CONTEXT_EXPIRED The context has expired. If the lifetime_rec
4109 parameter was requested, it will be set to 0.
4117 7.21. gss_inquire_cred
4119 OM_uint32 gss_inquire_cred (
4120 OM_uint32 * minor_status,
4121 const gss_cred_id_t cred_handle,
4122 gss_name_t * name,
4123 OM_uint32 * lifetime,
4124 gss_cred_usage_t * cred_usage,
4125 gss_OID_set * mechanisms )
4127 Purpose:
4129 Obtains information about a credential. The caller must already have
4130 obtained a handle that refers to the credential.
4132 Parameters:
4134 minor_status Integer, modify
4135 Mechanism specific status code
4137 cred_handle gss_cred_id_t, read
4138 A handle that refers to the target credential.
4139 Specify GSS_C_NO_CREDENTIAL to inquire about
4140 the default initiator principal.
4143 Wray Document Expiration: 1 September 1997 [Page 63]
4146 \f
4151 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4156 name gss_name_t, modify, optional
4157 The name whose identity the credential asserts.
4158 Storage associated with this name should be freed
4159 by the application after use with a call to
4160 gss_release_name(). Specify NULL if not required.
4162 lifetime Integer, modify, optional
4163 The number of seconds for which the credential
4164 will remain valid. If the credential has
4165 expired, this parameter will be set to zero.
4166 If the implementation does not support
4167 credential expiration, the value
4168 GSS_C_INDEFINITE will be returned. Specify
4169 NULL if not required.
4171 cred_usage gss_cred_usage_t, modify, optional
4172 How the credential may be used. One of the
4173 following:
4174 GSS_C_INITIATE
4175 GSS_C_ACCEPT
4176 GSS_C_BOTH
4177 Specify NULL if not required.
4179 mechanisms gss_OID_set, modify, optional
4180 Set of mechanisms supported by the credential.
4181 Storage associated with this OID set must be
4182 freed by the application after use with a call
4183 to gss_release_oid_set(). Specify NULL if not
4184 required.
4186 Function value: GSS status code
4188 GSS_S_COMPLETE Successful completion
4190 GSS_S_NO_CRED The referenced credentials could not be accessed.
4192 GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid.
4194 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. If
4195 the lifetime parameter was not passed as NULL, it will
4196 be set to 0.
4206 Wray Document Expiration: 1 September 1997 [Page 64]
4209 \f
4214 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4218 7.22. gss_inquire_cred_by_mech
4220 OM_uint32 gss_inquire_cred_by_mech (
4221 OM_uint32 * minor_status,
4222 const gss_cred_id_t cred_handle,
4223 const gss_OID mech_type,
4224 gss_name_t * name,
4225 OM_uint32 * initiator_lifetime,
4226 OM_uint32 * acceptor_lifetime,
4227 gss_cred_usage_t * cred_usage )
4229 Purpose:
4231 Obtains per-mechanism information about a credential. The caller must
4232 already have obtained a handle that refers to the credential.
4234 Parameters:
4236 minor_status Integer, modify
4237 Mechanism specific status code
4239 cred_handle gss_cred_id_t, read
4240 A handle that refers to the target credential.
4241 Specify GSS_C_NO_CREDENTIAL to inquire about
4242 the default initiator principal.
4244 mech_type gss_OID, read
4245 The mechanism for which information should be
4246 returned.
4248 name gss_name_t, modify, optional
4249 The name whose identity the credential asserts.
4250 Storage associated with this name must be
4251 freed by the application after use with a call
4252 to gss_release_name(). Specify NULL if not
4253 required.
4255 initiator_lifetime Integer, modify, optional
4256 The number of seconds for which the credential
4257 will remain capable of initiating security contexts
4258 under the specified mechanism. If the credential
4259 can no longer be used to initiate contexts, or if
4260 the credential usage for this mechanism is
4261 GSS_C_ACCEPT,
4262 this parameter will be set to zero. If the
4263 implementation does not support expiration of
4264 initiator credentials, the value GSS_C_INDEFINITE
4265 will be returned. Specify NULL if not required.
4267 acceptor_lifetime Integer, modify, optional
4268 The number of seconds for which the credential
4272 Wray Document Expiration: 1 September 1997 [Page 65]
4275 \f
4280 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4284 will remain capable of accepting security contexts
4285 under the specified mechanism. If the credential
4286 can no longer be used to accept contexts, or if
4287 the credential usage for this mechanism is
4288 GSS_C_INITIATE, this parameter will be set to zero.
4289 If the implementation does not support expiration
4290 of acceptor credentials, the value GSS_C_INDEFINITE
4291 will be returned. Specify NULL if not required.
4293 cred_usage gss_cred_usage_t, modify, optional
4294 How the credential may be used with the specified
4295 mechanism. One of the following:
4296 GSS_C_INITIATE
4297 GSS_C_ACCEPT
4298 GSS_C_BOTH
4299 Specify NULL if not required.
4301 Function value: GSS status code
4303 GSS_S_COMPLETE Successful completion
4305 GSS_S_NO_CRED The referenced credentials could not be accessed.
4307 GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid.
4309 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. If
4310 the lifetime parameter was not passed as NULL, it will
4311 be set to 0.
4319 7.23. gss_inquire_mechs_for_name
4321 OM_uint32 gss_inquire_mechs_for_name (
4322 OM_uint32 * minor_status,
4323 const gss_name_t input_name,
4324 gss_OID_set * mech_types )
4326 Purpose:
4328 Returns the set of mechanisms supported by the GSSAPI implementation
4329 that may be able to process the specified name.
4331 Each mechanism returned will recognize at least one element within the
4332 name. It is permissible for this routine to be implemented within a
4333 mechanism-independent GSSAPI layer, using the type information contained
4334 within the presented name, and based on registration information
4338 Wray Document Expiration: 1 September 1997 [Page 66]
4341 \f
4346 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4350 provided by individual mechanism implementations. This means that the
4351 returned mech_types set may indicate that a particular mechanism will
4352 understand the name when in fact it would refuse to accept the name as
4353 input to gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred
4354 or gss_add_cred (due to some property of the specific name, as opposed
4355 to the name type). Thus this routine should be used only as a pre-
4356 filter for a call to a subsequent mechanism-specific routine.
4360 Parameters:
4362 minor_status Integer, modify
4363 Implementation specific status code.
4365 input_name gss_name_t, read
4366 The name to which the inquiry relates.
4368 mech_types gss_OID_set, modify
4369 Set of mechanisms that may support the
4370 specified name. The returned OID set
4371 must be freed by the caller after use
4372 with a call to gss_release_oid_set().
4374 Function value: GSS status code
4376 GSS_S_COMPLETE Successful completion
4378 GSS_S_BAD_NAME The input_name parameter was ill-formed.
4380 GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or
4381 unsupported type of name
4388 7.24. gss_inquire_names_for_mech
4390 OM_uint32 gss_inquire_names_for_mech (
4391 OM_uint32 * minor_status,
4392 const gss_OID mechanism,
4393 gss_OID_set * name_types)
4395 Purpose:
4397 Returns the set of nametypes supported by the specified mechanism.
4404 Wray Document Expiration: 1 September 1997 [Page 67]
4407 \f
4412 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4416 Parameters:
4418 minor_status Integer, modify
4419 Implementation specific status code.
4421 mechanism gss_OID, read
4422 The mechanism to be interrogated.
4424 name_types gss_OID_set, modify
4425 Set of name-types supported by the specified
4426 mechanism. The returned OID set must be
4427 freed by the application after use with a
4428 call to gss_release_oid_set().
4430 Function value: GSS status code
4432 GSS_S_COMPLETE Successful completion
4440 7.25. gss_process_context_token
4442 OM_uint32 gss_process_context_token (
4443 OM_uint32 * minor_status,
4444 const gss_ctx_id_t context_handle,
4445 const gss_buffer_t token_buffer)
4447 Purpose:
4449 Provides a way to pass a token to the security service. Used with
4450 tokens emitted by gss_delete_sec_context. Note that mechanisms are
4451 encouraged to perform local deletion, and not emit tokens from
4452 gss_delete_sec_context. This routine, therefore, is primarily for
4453 backwards compatibility with V1 applications.
4455 Parameters:
4457 minor_status Integer, modify
4458 Implementation specific status code.
4460 context_handle gss_ctx_id_t, read
4461 context handle of context on which token is to
4462 be processed
4464 token_buffer buffer, opaque, read
4465 token to process
4470 Wray Document Expiration: 1 September 1997 [Page 68]
4473 \f
4478 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4482 Function value: GSS status code
4484 GSS_S_COMPLETE Successful completion
4486 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the
4487 token failed
4489 GSS_S_NO_CONTEXT The context_handle did not refer to a valid context
4497 7.26. gss_release_buffer
4499 OM_uint32 gss_release_buffer (
4500 OM_uint32 * minor_status,
4501 gss_buffer_t buffer)
4503 Purpose:
4505 Free storage associated with a buffer. The storage must have been
4506 allocated by a GSS-API routine. In addition to freeing the associated
4507 storage, the routine will zero the length field in the descriptor to
4508 which the buffer parameter refers.
4510 Parameters:
4512 minor_status Integer, modify
4513 Mechanism specific status code
4515 buffer buffer, modify
4516 The storage associated with the buffer will be
4517 deleted. The gss_buffer_desc object will not
4518 be freed, but its length field will be zeroed.
4520 Function value: GSS status code
4522 GSS_S_COMPLETE Successful completion
4536 Wray Document Expiration: 1 September 1997 [Page 69]
4539 \f
4544 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4548 7.27. gss_release_cred
4550 OM_uint32 gss_release_cred (
4551 OM_uint32 * minor_status,
4552 gss_cred_id_t * cred_handle)
4554 Purpose:
4556 Informs GSS-API that the specified credential handle is no longer
4557 required by the application, and frees associated resources.
4559 Parameters:
4561 cred_handle gss_cred_id_t, modify, optional
4562 Opaque handle identifying credential
4563 to be released. If GSS_C_NO_CREDENTIAL
4564 is supplied, the routine will complete
4565 successfully, but will do nothing.
4567 minor_status Integer, modify
4568 Mechanism specific status code.
4570 Function value: GSS status code
4572 GSS_S_COMPLETE Successful completion
4574 GSS_S_NO_CRED Credentials could not be accessed.
4582 7.28. gss_release_name
4584 OM_uint32 gss_release_name (
4585 OM_uint32 * minor_status,
4586 gss_name_t * name)
4588 Purpose:
4590 Free GSSAPI-allocated storage by associated with an internal-form name.
4592 Parameters:
4594 minor_status Integer, modify
4595 Mechanism specific status code
4597 name gss_name_t, modify
4598 The name to be deleted
4602 Wray Document Expiration: 1 September 1997 [Page 70]
4605 \f
4610 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4614 Function value: GSS status code
4616 GSS_S_COMPLETE Successful completion
4618 GSS_S_BAD_NAME The name parameter did not contain a valid name
4626 7.29. gss_release_oid_set
4628 OM_uint32 gss_release_oid_set (
4629 OM_uint32 * minor_status,
4630 gss_OID_set * set)
4632 Purpose:
4634 Free storage associated with a GSSAPI-generated gss_OID_set object. The
4635 set parameter must refer to an OID-set that was returned from a GSSAPI
4636 routine. gss_release_oid_set() will free the storage associated with
4637 each individual member OID, the OID set's elements array, and the
4638 gss_OID_set_desc.
4641 Parameters:
4643 minor_status Integer, modify
4644 Mechanism specific status code
4646 set Set of Object IDs, modify
4647 The storage associated with the gss_OID_set
4648 will be deleted.
4650 Function value: GSS status code
4652 GSS_S_COMPLETE Successful completion
4668 Wray Document Expiration: 1 September 1997 [Page 71]
4671 \f
4676 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4680 7.30. gss_test_oid_set_member
4682 OM_uint32 gss_test_oid_set_member (
4683 OM_uint32 * minor_status,
4684 const gss_OID member,
4685 const gss_OID_set set,
4686 int * present)
4688 Purpose:
4690 Interrogate an Object Identifier set to determine whether a specified
4691 Object Identifier is a member. This routine is intended to be used with
4692 OID sets returned by gss_indicate_mechs(), gss_acquire_cred(), and
4693 gss_inquire_cred(), but will also work with user-generated sets.
4695 Parameters:
4697 minor_status Integer, modify
4698 Mechanism specific status code
4700 member Object ID, read
4701 The object identifier whose presence
4702 is to be tested.
4704 set Set of Object ID, read
4705 The Object Identifier set.
4707 present Boolean, modify
4708 non-zero if the specified OID is a member
4709 of the set, zero if not.
4711 Function value: GSS status code
4713 GSS_S_COMPLETE Successful completion
4721 7.31. gss_unwrap
4723 OM_uint32 gss_unwrap (
4724 OM_uint32 * minor_status,
4725 const gss_ctx_id_t context_handle,
4726 const gss_buffer_t input_message_buffer,
4727 gss_buffer_t output_message_buffer,
4728 int * conf_state,
4729 gss_qop_t * qop_state)
4734 Wray Document Expiration: 1 September 1997 [Page 72]
4737 \f
4742 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4746 Purpose:
4748 Converts a message previously protected by gss_wrap back to a usable
4749 form, verifying the embedded MIC. The conf_state parameter indicates
4750 whether the message was encrypted; the qop_state parameter indicates the
4751 strength of protection that was used to provide the confidentiality and
4752 integrity services.
4754 Parameters:
4756 minor_status Integer, modify
4757 Mechanism specific status code.
4759 context_handle gss_ctx_id_t, read
4760 Identifies the context on which the message
4761 arrived
4763 input_message_buffer buffer, opaque, read
4764 protected message
4766 output_message_buffer buffer, opaque, modify
4767 Buffer to receive unwrapped message.
4768 Storage associated with this buffer must
4769 be freed by the application after use use
4770 with a call to gss_release_buffer().
4772 conf_state boolean, modify, optional
4773 Non-zero - Confidentiality and integrity protection
4774 were used
4775 Zero - Integrity service only was used
4776 Specify NULL if not required
4778 qop_state gss_qop_t, modify, optional
4779 Quality of protection gained from MIC.
4780 Specify NULL if not required
4782 Function value: GSS status code
4784 GSS_S_COMPLETE Successful completion
4786 GSS_S_DEFECTIVE_TOKEN The token failed consistency checks
4788 GSS_S_BAD_SIG The MIC was incorrect
4790 GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct MIC
4791 for the message, but it had already been processed
4793 GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC for
4794 the message, but it is too old to check for
4795 duplication.
4800 Wray Document Expiration: 1 September 1997 [Page 73]
4803 \f
4808 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4812 GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC for
4813 the message, but has been verified out of sequence; a
4814 later token has already been received.
4816 GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC for
4817 the message, but has been verified out of sequence;
4818 an earlier expected token has not yet been received.
4820 GSS_S_CONTEXT_EXPIRED The context has already expired
4822 GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid
4823 context
4831 7.32. gss_verify_mic
4833 OM_uint32 gss_verify_mic (
4834 OM_uint32 * minor_status,
4835 const gss_ctx_id_t context_handle,
4836 const gss_buffer_t message_buffer,
4837 const gss_buffer_t token_buffer,
4838 gss_qop_t * qop_state)
4840 Purpose:
4842 Verifies that a cryptographic MIC, contained in the token parameter,
4843 fits the supplied message. The qop_state parameter allows a message
4844 recipient to determine the strength of protection that was applied to
4845 the message.
4847 Parameters:
4849 minor_status Integer, modify
4850 Mechanism specific status code.
4852 context_handle gss_ctx_id_t, read
4853 Identifies the context on which the message
4854 arrived
4856 message_buffer buffer, opaque, read
4857 Message to be verified
4859 token_buffer buffer, opaque, read
4860 Token associated with message
4865 Wray Document Expiration: 1 September 1997 [Page 74]
4868 \f
4873 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4876 qop_state gss_qop_t, modify, optional
4877 quality of protection gained from MIC
4878 Specify NULL if not required
4880 Function value: GSS status code
4882 GSS_S_COMPLETE Successful completion
4884 GSS_S_DEFECTIVE_TOKEN The token failed consistency checks
4886 GSS_S_BAD_SIG The MIC was incorrect
4888 GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct MIC
4889 for the message, but it had already been processed
4891 GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC for
4892 the message, but it is too old to check for
4893 duplication.
4895 GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC for
4896 the message, but has been verified out of sequence; a
4897 later token has already been received.
4899 GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC for
4900 the message, but has been verified out of sequence;
4901 an earlier expected token has not yet been received.
4903 GSS_S_CONTEXT_EXPIRED The context has already expired
4905 GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid
4906 context
4914 7.33. gss_wrap
4916 OM_uint32 gss_wrap (
4917 OM_uint32 * minor_status,
4918 const gss_ctx_id_t context_handle,
4919 int conf_req_flag,
4920 gss_qop_t qop_req
4921 const gss_buffer_t input_message_buffer,
4922 int * conf_state,
4923 gss_buffer_t output_message_buffer )
4931 Wray Document Expiration: 1 September 1997 [Page 75]
4934 \f
4939 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
4943 Purpose:
4945 Attaches a cryptographic MIC and optionally encrypts the specified
4946 input_message. The output_message contains both the MIC and the
4947 message. The qop_req parameter allows a choice between several
4948 cryptographic algorithms, if supported by the chosen mechanism.
4950 Since some application-level protocols may wish to use tokens emitted by
4951 gss_wrap() to provide "secure framing", implementations should support
4952 the wrapping of zero-length messages.
4954 Parameters:
4956 minor_status Integer, modify
4957 Mechanism specific status code.
4959 context_handle gss_ctx_id_t, read
4960 Identifies the context on which the message
4961 will be sent
4963 conf_req_flag boolean, read
4964 Non-zero - Both confidentiality and integrity
4965 services are requested
4966 Zero - Only integrity service is requested
4968 qop_req gss_qop_t, read, optional
4969 Specifies required quality of protection. A
4970 mechanism-specific default may be requested by
4971 setting qop_req to GSS_C_QOP_DEFAULT. If an
4972 unsupported protection strength is requested,
4973 gss_wrap will return a major_status of
4974 GSS_S_BAD_QOP.
4976 input_message_buffer buffer, opaque, read
4977 Message to be protected
4979 conf_state boolean, modify, optional
4980 Non-zero - Confidentiality, data origin
4981 authentication and integrity
4982 services have been applied
4983 Zero - Integrity and data origin services only
4984 has been applied.
4985 Specify NULL if not required
4987 output_message_buffer buffer, opaque, modify
4988 Buffer to receive protected message.
4989 Storage associated with this message must
4990 be freed by the application after use with
4991 a call to gss_release_buffer().
4993 Function value: GSS status code
4997 Wray Document Expiration: 1 September 1997 [Page 76]
5000 \f
5005 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5009 GSS_S_COMPLETE Successful completion
5011 GSS_S_CONTEXT_EXPIRED The context has already expired
5013 GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid
5014 context
5016 GSS_S_BAD_QOP The specified QOP is not supported by the mechanism.
5024 7.34. gss_wrap_size_limit
5026 OM_uint32 gss_wrap_size_limit (
5027 OM_uint32 * minor_status,
5028 const gss_ctx_id_t context_handle,
5029 int conf_req_flag,
5030 gss_qop_t qop_req,
5031 OM_uint32 req_output_size,
5032 OM_uint32 * max_input_size)
5034 Purpose:
5036 Allows an application to determine the maximum message size that, if
5037 presented to gss_wrap with the same conf_req_flag and qop_req
5038 parameters, will result in an output token containing no more than
5039 req_output_size bytes.
5041 This call is intended for use by applications that communicate over
5042 protocols that impose a maximum message size. It enables the
5043 application to fragment messages prior to applying protection.
5045 Successful completion of this call does not guarantee that gss_wrap will
5046 be able to protect a message of length max_input_size bytes, since this
5047 ability may depend on the availability of system resources at the time
5048 that gss_wrap is called. However, if the implementation itself imposes
5049 an upper limit on the length of messages that may be processed by
5050 gss_wrap, the implementation should not return a value via
5051 max_input_bytes that is greater than this length.
5053 Parameters:
5055 minor_status Integer, modify
5056 Mechanism specific status code
5058 context_handle gss_ctx_id_t, read
5059 A handle that refers to the security over
5063 Wray Document Expiration: 1 September 1997 [Page 77]
5066 \f
5071 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5075 which the messages will be sent.
5077 conf_req_flag Boolean, read
5078 Indicates whether gss_wrap will be asked
5079 to apply confidentiality protection in
5080 addition to integrity protection. See
5081 the routine description for gss_wrap
5082 for more details.
5084 qop_req gss_qop_t, read
5085 Indicates the level of protection that
5086 gss_wrap will be asked to provide. See
5087 the routine description for gss_wrap for
5088 more details.
5090 req_output_size Integer, read
5091 The desired maximum size for tokens emitted
5092 by gss_wrap.
5094 max_input_size Integer, modify
5095 The maximum input message size that may
5096 be presented to gss_wrap in order to
5097 guarantee that the emitted token shall
5098 be no larger than req_output_size bytes.
5100 Function value: GSS status code
5102 GSS_S_COMPLETE Successful completion
5104 GSS_S_NO_CONTEXT The referenced context could not be accessed.
5106 GSS_S_CONTEXT_EXPIRED The context has expired.
5108 GSS_S_BAD_QOP The specified QOP is not supported by the mechanism.
5129 Wray Document Expiration: 1 September 1997 [Page 78]
5132 \f
5137 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5141 APPENDIX A. GSS-API C header file gssapi.h
5143 C-language GSS-API implementations should include a copy of the
5144 following header-file.
5146 #ifndef GSSAPI_H_
5147 #define GSSAPI_H_
5151 /*
5152 * First, include stddef.h to get size_t defined.
5153 */
5154 #include <stddef.h>
5156 /*
5157 * If the platform supports the xom.h header file, it should be
5158 * included here.
5159 */
5160 #include <xom.h>
5164 /*
5165 * Now define the three implementation-dependent types.
5166 */
5167 typedef <platform-specific> gss_ctx_id_t;
5168 typedef <platform-specific> gss_cred_id_t;
5169 typedef <platform-specific> gss_name_t;
5171 /*
5172 * The following type must be defined as the smallest natural
5173 * unsigned integer supported by the platform that has at least
5174 * 32 bits of precision.
5175 */
5176 typedef <platform-specific> gss_uint32;
5179 #ifdef OM_STRING
5180 /*
5181 * We have included the xom.h header file. Verify that OM_uint32
5182 * is defined correctly.
5183 */
5185 #if sizeof(gss_uint32) != sizeof(OM_uint32)
5186 #error Incompatible definition of OM_uint32 from xom.h
5187 #endif
5189 typedef OM_object_identifier gss_OID_desc, *gss_OID;
5191 #else
5195 Wray Document Expiration: 1 September 1997 [Page 79]
5198 \f
5203 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5207 /*
5208 * We can't use X/Open definitions, so roll our own.
5209 */
5211 typedef gss_uint32 OM_uint32;
5213 typedef struct gss_OID_desc_struct {
5214 OM_uint32 length;
5215 void *elements;
5216 } gss_OID_desc, *gss_OID;
5218 #endif
5220 typedef struct gss_OID_set_desc_struct {
5221 size_t count;
5222 gss_OID elements;
5223 } gss_OID_set_desc, *gss_OID_set;
5225 typedef struct gss_buffer_desc_struct {
5226 size_t length;
5227 void *value;
5228 } gss_buffer_desc, *gss_buffer_t;
5230 typedef struct gss_channel_bindings_struct {
5231 OM_uint32 initiator_addrtype;
5232 gss_buffer_desc initiator_address;
5233 OM_uint32 acceptor_addrtype;
5234 gss_buffer_desc acceptor_address;
5235 gss_buffer_desc application_data;
5236 } *gss_channel_bindings_t;
5239 /*
5240 * For now, define a QOP-type as an OM_uint32
5241 */
5242 typedef OM_uint32 gss_qop_t;
5244 typedef int gss_cred_usage_t;
5246 /*
5247 * Flag bits for context-level services.
5248 */
5249 #define GSS_C_DELEG_FLAG 1
5250 #define GSS_C_MUTUAL_FLAG 2
5251 #define GSS_C_REPLAY_FLAG 4
5252 #define GSS_C_SEQUENCE_FLAG 8
5253 #define GSS_C_CONF_FLAG 16
5254 #define GSS_C_INTEG_FLAG 32
5255 #define GSS_C_ANON_FLAG 64
5256 #define GSS_C_PROT_READY_FLAG 128
5257 #define GSS_C_TRANS_FLAG 256
5261 Wray Document Expiration: 1 September 1997 [Page 80]
5264 \f
5269 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5273 /*
5274 * Credential usage options
5275 */
5276 #define GSS_C_BOTH 0
5277 #define GSS_C_INITIATE 1
5278 #define GSS_C_ACCEPT 2
5280 /*
5281 * Status code types for gss_display_status
5282 */
5283 #define GSS_C_GSS_CODE 1
5284 #define GSS_C_MECH_CODE 2
5286 /*
5287 * The constant definitions for channel-bindings address families
5288 */
5289 #define GSS_C_AF_UNSPEC 0
5290 #define GSS_C_AF_LOCAL 1
5291 #define GSS_C_AF_INET 2
5292 #define GSS_C_AF_IMPLINK 3
5293 #define GSS_C_AF_PUP 4
5294 #define GSS_C_AF_CHAOS 5
5295 #define GSS_C_AF_NS 6
5296 #define GSS_C_AF_NBS 7
5297 #define GSS_C_AF_ECMA 8
5298 #define GSS_C_AF_DATAKIT 9
5299 #define GSS_C_AF_CCITT 10
5300 #define GSS_C_AF_SNA 11
5301 #define GSS_C_AF_DECnet 12
5302 #define GSS_C_AF_DLI 13
5303 #define GSS_C_AF_LAT 14
5304 #define GSS_C_AF_HYLINK 15
5305 #define GSS_C_AF_APPLETALK 16
5306 #define GSS_C_AF_BSC 17
5307 #define GSS_C_AF_DSS 18
5308 #define GSS_C_AF_OSI 19
5309 #define GSS_C_AF_X25 21
5311 #define GSS_C_AF_NULLADDR 255
5313 /*
5314 * Various Null values
5315 */
5316 #define GSS_C_NO_NAME ((gss_name_t) 0)
5317 #define GSS_C_NO_BUFFER ((gss_buffer_t) 0)
5318 #define GSS_C_NO_OID ((gss_OID) 0)
5319 #define GSS_C_NO_OID_SET ((gss_OID_set) 0)
5320 #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0)
5321 #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0)
5322 #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0)
5323 #define GSS_C_EMPTY_BUFFER {0, NULL}
5327 Wray Document Expiration: 1 September 1997 [Page 81]
5330 \f
5335 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5339 /*
5340 * Some alternate names for a couple of the above
5341 * values. These are defined for V1 compatibility.
5342 */
5343 #define GSS_C_NULL_OID GSS_C_NO_OID
5344 #define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET
5346 /*
5347 * Define the default Quality of Protection for per-message
5348 * services. Note that an implementation that offers multiple
5349 * levels of QOP may define GSS_C_QOP_DEFAULT to be either zero
5350 * (as done here) to mean "default protection", or to a specific
5351 * explicit QOP value. However, a value of 0 should always be
5352 * interpreted by a GSSAPI implementation as a request for the
5353 * default protection level.
5354 */
5355 #define GSS_C_QOP_DEFAULT 0
5357 /*
5358 * Expiration time of 2^32-1 seconds means infinite lifetime for a
5359 * credential or security context
5360 */
5361 #define GSS_C_INDEFINITE 0xfffffffful
5363 /*
5364 * The implementation must reserve static storage for a
5365 * gss_OID_desc object containing the value
5366 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12"
5367 * "\x01\x02\x01\x01"},
5368 * corresponding to an object-identifier value of
5369 * {iso(1) member-body(2) United States(840) mit(113554)
5370 * infosys(1) gssapi(2) generic(1) user_name(1)}. The constant
5371 * GSS_C_NT_USER_NAME should be initialized to point
5372 * to that gss_OID_desc.
5373 */
5374 extern gss_OID GSS_C_NT_USER_NAME;
5376 /*
5377 * The implementation must reserve static storage for a
5378 * gss_OID_desc object containing the value
5379 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12"
5380 * "\x01\x02\x01\x02"},
5381 * corresponding to an object-identifier value of
5382 * {iso(1) member-body(2) United States(840) mit(113554)
5383 * infosys(1) gssapi(2) generic(1) machine_uid_name(2)}.
5384 * The constant GSS_C_NT_MACHINE_UID_NAME should be
5385 * initialized to point to that gss_OID_desc.
5386 */
5387 extern gss_OID GSS_C_NT_MACHINE_UID_NAME;
5389 /*
5393 Wray Document Expiration: 1 September 1997 [Page 82]
5396 \f
5401 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5405 * The implementation must reserve static storage for a
5406 * gss_OID_desc object containing the value
5407 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12"
5408 * "\x01\x02\x01\x03"},
5409 * corresponding to an object-identifier value of
5410 * {iso(1) member-body(2) United States(840) mit(113554)
5411 * infosys(1) gssapi(2) generic(1) string_uid_name(3)}.
5412 * The constant GSS_C_NT_STRING_UID_NAME should be
5413 * initialized to point to that gss_OID_desc.
5414 */
5415 extern gss_OID GSS_C_NT_STRING_UID_NAME;
5417 /*
5418 * The implementation must reserve static storage for a
5419 * gss_OID_desc object containing the value
5420 * {6, (void *)"\x2b\x06\x01\x05\x06\x02"},
5421 * corresponding to an object-identifier value of
5422 * {1(iso), 3(org), 6(dod), 1(internet), 5(security),
5423 * 6(nametypes), 2(gss-host-based-services)}. The constant
5424 * GSS_C_NT_HOSTBASED_SERVICE should be initialized to point
5425 * to that gss_OID_desc.
5426 */
5427 extern gss_OID GSS_C_NT_HOSTBASED_SERVICE;
5429 /*
5430 * The implementation must reserve static storage for a
5431 * gss_OID_desc object containing the value
5432 * {6, (void *)"\x2b\x06\01\x05\x06\x03"},
5433 * corresponding to an object identifier value of
5434 * {1(iso), 3(org), 6(dod), 1(internet), 5(security),
5435 * 6(nametypes), 3(gss-anonymous-name)}. The constant
5436 * and GSS_C_NT_ANONYMOUS should be initialized to point
5437 * to that gss_OID_desc.
5438 */
5439 extern gss_OID GSS_C_NT_ANONYMOUS;
5443 /*
5444 * The implementation must reserve static storage for a
5445 * gss_OID_desc object containing the value
5446 * {6, (void *)"\x2b\x06\x01\x05\x06\x04"},
5447 * corresponding to an object-identifier value of
5448 * {1(iso), 3(org), 6(dod), 1(internet), 5(security),
5449 * 6(nametypes), 4(gss-api-exported-name)}. The constant
5450 * GSS_C_NT_EXPORT_NAME should be initialized to point
5451 * to that gss_OID_desc.
5452 */
5453 extern gss_OID GSS_C_NT_EXPORT_NAME;
5459 Wray Document Expiration: 1 September 1997 [Page 83]
5462 \f
5467 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5471 /* Major status codes */
5473 #define GSS_S_COMPLETE 0
5475 /*
5476 * Some "helper" definitions to make the status code macros obvious.
5477 */
5478 #define GSS_C_CALLING_ERROR_OFFSET 24
5479 #define GSS_C_ROUTINE_ERROR_OFFSET 16
5480 #define GSS_C_SUPPLEMENTARY_OFFSET 0
5481 #define GSS_C_CALLING_ERROR_MASK 0377ul
5482 #define GSS_C_ROUTINE_ERROR_MASK 0377ul
5483 #define GSS_C_SUPPLEMENTARY_MASK 0177777ul
5485 /*
5486 * The macros that test status codes for error conditions.
5487 * Note that the GSS_ERROR() macro has changed slightly from
5488 * the V1 GSSAPI so that it now evaluates its argument
5489 * only once.
5490 */
5491 #define GSS_CALLING_ERROR(x) \
5492 (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET))
5493 #define GSS_ROUTINE_ERROR(x) \
5494 (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))
5495 #define GSS_SUPPLEMENTARY_INFO(x) \
5496 (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET))
5497 #define GSS_ERROR(x) \
5498 (x & ((GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET) | \
5499 (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)))
5502 /*
5503 * Now the actual status code definitions
5504 */
5506 /*
5507 * Calling errors:
5508 */
5509 #define GSS_S_CALL_INACCESSIBLE_READ \
5510 (1ul << GSS_C_CALLING_ERROR_OFFSET)
5511 #define GSS_S_CALL_INACCESSIBLE_WRITE \
5512 (2ul << GSS_C_CALLING_ERROR_OFFSET)
5513 #define GSS_S_CALL_BAD_STRUCTURE \
5514 (3ul << GSS_C_CALLING_ERROR_OFFSET)
5516 /*
5517 * Routine errors:
5518 */
5519 #define GSS_S_BAD_MECH (1ul << GSS_C_ROUTINE_ERROR_OFFSET)
5520 #define GSS_S_BAD_NAME (2ul << GSS_C_ROUTINE_ERROR_OFFSET)
5521 #define GSS_S_BAD_NAMETYPE (3ul << GSS_C_ROUTINE_ERROR_OFFSET)
5525 Wray Document Expiration: 1 September 1997 [Page 84]
5528 \f
5533 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5537 #define GSS_S_BAD_BINDINGS (4ul << GSS_C_ROUTINE_ERROR_OFFSET)
5538 #define GSS_S_BAD_STATUS (5ul << GSS_C_ROUTINE_ERROR_OFFSET)
5539 #define GSS_S_BAD_SIG (6ul << GSS_C_ROUTINE_ERROR_OFFSET)
5540 #define GSS_S_BAD_MIC GSS_S_BAD_SIG
5541 #define GSS_S_NO_CRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET)
5542 #define GSS_S_NO_CONTEXT (8ul << GSS_C_ROUTINE_ERROR_OFFSET)
5543 #define GSS_S_DEFECTIVE_TOKEN (9ul << GSS_C_ROUTINE_ERROR_OFFSET)
5544 #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << GSS_C_ROUTINE_ERROR_OFFSET)
5545 #define GSS_S_CREDENTIALS_EXPIRED (11ul << GSS_C_ROUTINE_ERROR_OFFSET)
5546 #define GSS_S_CONTEXT_EXPIRED (12ul << GSS_C_ROUTINE_ERROR_OFFSET)
5547 #define GSS_S_FAILURE (13ul << GSS_C_ROUTINE_ERROR_OFFSET)
5548 #define GSS_S_BAD_QOP (14ul << GSS_C_ROUTINE_ERROR_OFFSET)
5549 #define GSS_S_UNAUTHORIZED (15ul << GSS_C_ROUTINE_ERROR_OFFSET)
5550 #define GSS_S_UNAVAILABLE (16ul << GSS_C_ROUTINE_ERROR_OFFSET)
5551 #define GSS_S_DUPLICATE_ELEMENT (17ul << GSS_C_ROUTINE_ERROR_OFFSET)
5552 #define GSS_S_NAME_NOT_MN (18ul << GSS_C_ROUTINE_ERROR_OFFSET)
5554 /*
5555 * Supplementary info bits:
5556 */
5557 #define GSS_S_CONTINUE_NEEDED (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0))
5558 #define GSS_S_DUPLICATE_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1))
5559 #define GSS_S_OLD_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2))
5560 #define GSS_S_UNSEQ_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3))
5561 #define GSS_S_GAP_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4))
5564 /*
5565 * Finally, function prototypes for the GSS-API routines.
5566 */
5568 OM_uint32 gss_acquire_cred
5569 (OM_uint32 *, /* minor_status */
5570 const gss_name_t, /* desired_name */
5571 OM_uint32, /* time_req */
5572 const gss_OID_set, /* desired_mechs */
5573 gss_cred_usage_t, /* cred_usage */
5574 gss_cred_id_t *, /* output_cred_handle */
5575 gss_OID_set *, /* actual_mechs */
5576 OM_uint32 * /* time_rec */
5577 );
5579 OM_uint32 gss_release_cred
5580 (OM_uint32 *, /* minor_status */
5581 gss_cred_id_t * /* cred_handle */
5582 );
5584 OM_uint32 gss_init_sec_context
5585 (OM_uint32 *, /* minor_status */
5586 const gss_cred_id_t, /* initiator_cred_handle */
5587 gss_ctx_id_t *, /* context_handle */
5591 Wray Document Expiration: 1 September 1997 [Page 85]
5594 \f
5599 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5603 const gss_name_t, /* target_name */
5604 const gss_OID, /* mech_type */
5605 OM_uint32, /* req_flags */
5606 OM_uint32, /* time_req */
5607 const gss_channel_bindings_t,
5608 /* input_chan_bindings */
5609 const gss_buffer_t, /* input_token */
5610 gss_OID *, /* actual_mech_type */
5611 gss_buffer_t, /* output_token */
5612 OM_uint32 *, /* ret_flags */
5613 OM_uint32 * /* time_rec */
5614 );
5616 OM_uint32 gss_accept_sec_context
5617 (OM_uint32 *, /* minor_status */
5618 gss_ctx_id_t *, /* context_handle */
5619 const gss_cred_id_t, /* acceptor_cred_handle */
5620 const gss_buffer_t, /* input_token_buffer */
5621 const gss_channel_bindings_t,
5622 /* input_chan_bindings */
5623 gss_name_t *, /* src_name */
5624 gss_OID *, /* mech_type */
5625 gss_buffer_t, /* output_token */
5626 OM_uint32 *, /* ret_flags */
5627 OM_uint32 *, /* time_rec */
5628 gss_cred_id_t * /* delegated_cred_handle */
5629 );
5631 OM_uint32 gss_process_context_token
5632 (OM_uint32 *, /* minor_status */
5633 const gss_ctx_id_t, /* context_handle */
5634 const gss_buffer_t /* token_buffer */
5635 );
5637 OM_uint32 gss_delete_sec_context
5638 (OM_uint32 *, /* minor_status */
5639 gss_ctx_id_t *, /* context_handle */
5640 gss_buffer_t /* output_token */
5641 );
5643 OM_uint32 gss_context_time
5644 (OM_uint32 *, /* minor_status */
5645 const gss_ctx_id_t, /* context_handle */
5646 OM_uint32 * /* time_rec */
5647 );
5649 OM_uint32 gss_get_mic
5650 (OM_uint32 *, /* minor_status */
5651 const gss_ctx_id_t, /* context_handle */
5652 gss_qop_t, /* qop_req */
5653 const gss_buffer_t, /* message_buffer */
5657 Wray Document Expiration: 1 September 1997 [Page 86]
5660 \f
5665 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5669 gss_buffer_t /* message_token */
5670 );
5673 OM_uint32 gss_verify_mic
5674 (OM_uint32 *, /* minor_status */
5675 const gss_ctx_id_t, /* context_handle */
5676 const gss_buffer_t, /* message_buffer */
5677 const gss_buffer_t, /* token_buffer */
5678 gss_qop_t * /* qop_state */
5679 );
5681 OM_uint32 gss_wrap
5682 (OM_uint32 *, /* minor_status */
5683 const gss_ctx_id_t, /* context_handle */
5684 int, /* conf_req_flag */
5685 gss_qop_t, /* qop_req */
5686 const gss_buffer_t, /* input_message_buffer */
5687 int *, /* conf_state */
5688 gss_buffer_t /* output_message_buffer */
5689 );
5692 OM_uint32 gss_unwrap
5693 (OM_uint32 *, /* minor_status */
5694 const gss_ctx_id_t, /* context_handle */
5695 const gss_buffer_t, /* input_message_buffer */
5696 gss_buffer_t, /* output_message_buffer */
5697 int *, /* conf_state */
5698 gss_qop_t * /* qop_state */
5699 );
5703 OM_uint32 gss_display_status
5704 (OM_uint32 *, /* minor_status */
5705 OM_uint32, /* status_value */
5706 int, /* status_type */
5707 const gss_OID, /* mech_type */
5708 OM_uint32 *, /* message_context */
5709 gss_buffer_t /* status_string */
5710 );
5712 OM_uint32 gss_indicate_mechs
5713 (OM_uint32 *, /* minor_status */
5714 gss_OID_set * /* mech_set */
5715 );
5717 OM_uint32 gss_compare_name
5718 (OM_uint32 *, /* minor_status */
5719 const gss_name_t, /* name1 */
5723 Wray Document Expiration: 1 September 1997 [Page 87]
5726 \f
5731 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5735 const gss_name_t, /* name2 */
5736 int * /* name_equal */
5737 );
5739 OM_uint32 gss_display_name
5740 (OM_uint32 *, /* minor_status */
5741 const gss_name_t, /* input_name */
5742 gss_buffer_t, /* output_name_buffer */
5743 gss_OID * /* output_name_type */
5744 );
5746 OM_uint32 gss_import_name
5747 (OM_uint32 *, /* minor_status */
5748 const gss_buffer_t, /* input_name_buffer */
5749 const gss_OID, /* input_name_type */
5750 gss_name_t * /* output_name */
5751 );
5753 OM_uint32 gss_export_name
5754 (OM_uint32 *, /* minor_status */
5755 const gss_name_t, /* input_name */
5756 gss_buffer_t /* exported_name */
5757 );
5759 OM_uint32 gss_release_name
5760 (OM_uint32 *, /* minor_status */
5761 gss_name_t * /* input_name */
5762 );
5764 OM_uint32 gss_release_buffer
5765 (OM_uint32 *, /* minor_status */
5766 gss_buffer_t /* buffer */
5767 );
5769 OM_uint32 gss_release_oid_set
5770 (OM_uint32 *, /* minor_status */
5771 gss_OID_set * /* set */
5772 );
5774 OM_uint32 gss_inquire_cred
5775 (OM_uint32 *, /* minor_status */
5776 const gss_cred_id_t, /* cred_handle */
5777 gss_name_t *, /* name */
5778 OM_uint32 *, /* lifetime */
5779 gss_cred_usage_t *, /* cred_usage */
5780 gss_OID_set * /* mechanisms */
5781 );
5783 OM_uint32 gss_inquire_context (
5784 OM_uint32 *, /* minor_status */
5785 const gss_ctx_id_t, /* context_handle */
5789 Wray Document Expiration: 1 September 1997 [Page 88]
5792 \f
5797 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5801 gss_name_t *, /* src_name */
5802 gss_name_t *, /* targ_name */
5803 OM_uint32 *, /* lifetime_rec */
5804 gss_OID *, /* mech_type */
5805 OM_uint32 *, /* ctx_flags */
5806 int *, /* locally_initiated */
5807 int * /* open */
5808 );
5810 OM_uint32 gss_wrap_size_limit (
5811 OM_uint32 *, /* minor_status */
5812 const gss_ctx_id_t, /* context_handle */
5813 int, /* conf_req_flag */
5814 gss_qop_t, /* qop_req */
5815 OM_uint32, /* req_output_size */
5816 OM_uint32 * /* max_input_size */
5817 );
5820 OM_uint32 gss_add_cred (
5821 OM_uint32 *, /* minor_status */
5822 const gss_cred_id_t, /* input_cred_handle */
5823 const gss_name_t, /* desired_name */
5824 const gss_OID, /* desired_mech */
5825 gss_cred_usage_t, /* cred_usage */
5826 OM_uint32, /* initiator_time_req */
5827 OM_uint32, /* acceptor_time_req */
5828 gss_cred_id_t *, /* output_cred_handle */
5829 gss_OID_set *, /* actual_mechs */
5830 OM_uint32 *, /* initiator_time_rec */
5831 OM_uint32 * /* acceptor_time_rec */
5832 );
5835 OM_uint32 gss_inquire_cred_by_mech (
5836 OM_uint32 *, /* minor_status */
5837 const gss_cred_id_t, /* cred_handle */
5838 const gss_OID, /* mech_type */
5839 gss_name_t *, /* name */
5840 OM_uint32 *, /* initiator_lifetime */
5841 OM_uint32 *, /* acceptor_lifetime */
5842 gss_cred_usage_t * /* cred_usage */
5843 );
5845 OM_uint32 gss_export_sec_context (
5846 OM_uint32 *, /* minor_status */
5847 gss_ctx_id_t *, /* context_handle */
5848 gss_buffer_t /* interprocess_token */
5849 );
5851 OM_uint32 gss_import_sec_context (
5855 Wray Document Expiration: 1 September 1997 [Page 89]
5858 \f
5863 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5867 OM_uint32 *, /* minor_status */
5868 const gss_buffer_t, /* interprocess_token */
5869 gss_ctx_id_t * /* context_handle */
5870 );
5872 OM_uint32 gss_create_empty_oid_set (
5873 OM_uint32 *, /* minor_status */
5874 gss_OID_set * /* oid_set */
5875 );
5877 OM_uint32 gss_add_oid_set_member (
5878 OM_uint32 *, /* minor_status */
5879 const gss_OID, /* member_oid */
5880 gss_OID_set * /* oid_set */
5881 );
5883 OM_uint32 gss_test_oid_set_member (
5884 OM_uint32 *, /* minor_status */
5885 const gss_OID, /* member */
5886 const gss_OID_set, /* set */
5887 int * /* present */
5888 );
5890 OM_uint32 gss_inquire_names_for_mech (
5891 OM_uint32 *, /* minor_status */
5892 const gss_OID, /* mechanism */
5893 gss_OID_set * /* name_types */
5894 );
5896 OM_uint32 gss_inquire_mechs_for_name (
5897 OM_uint32 *, /* minor_status */
5898 const gss_name_t, /* input_name */
5899 gss_OID_set * /* mech_types */
5900 );
5902 OM_uint32 gss_canonicalize_name (
5903 OM_uint32 *, /* minor_status */
5904 const gss_name_t, /* input_name */
5905 const gss_OID, /* mech_type */
5906 gss_name_t * /* output_name */
5907 );
5909 OM_uint32 gss_duplicate_name (
5910 OM_uint32 *, /* minor_status */
5911 const gss_name_t, /* src_name */
5912 gss_name_t * /* dest_name */
5913 );
5915 /*
5916 * The following routines are obsolete variants of gss_get_mic,
5917 * gss_verify_mic, gss_wrap and gss_unwrap. They should be
5921 Wray Document Expiration: 1 September 1997 [Page 90]
5924 \f
5929 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5933 * provided by GSSAPI V2 implementations for backwards
5934 * compatibility with V1 applications. Distinct entrypoints
5935 * (as opposed to #defines) should be provided, both to allow
5936 * GSSAPI V1 applications to link against GSSAPI V2 implementations,
5937 * and to retain the slight parameter type differences between the
5938 * obsolete versions of these routines and their current forms.
5939 */
5941 OM_uint32 gss_sign
5942 (OM_uint32 *, /* minor_status */
5943 gss_ctx_id_t, /* context_handle */
5944 int, /* qop_req */
5945 gss_buffer_t, /* message_buffer */
5946 gss_buffer_t /* message_token */
5947 );
5950 OM_uint32 gss_verify
5951 (OM_uint32 *, /* minor_status */
5952 gss_ctx_id_t, /* context_handle */
5953 gss_buffer_t, /* message_buffer */
5954 gss_buffer_t, /* token_buffer */
5955 int * /* qop_state */
5956 );
5958 OM_uint32 gss_seal
5959 (OM_uint32 *, /* minor_status */
5960 gss_ctx_id_t, /* context_handle */
5961 int, /* conf_req_flag */
5962 int, /* qop_req */
5963 gss_buffer_t, /* input_message_buffer */
5964 int *, /* conf_state */
5965 gss_buffer_t /* output_message_buffer */
5966 );
5969 OM_uint32 gss_unseal
5970 (OM_uint32 *, /* minor_status */
5971 gss_ctx_id_t, /* context_handle */
5972 gss_buffer_t, /* input_message_buffer */
5973 gss_buffer_t, /* output_message_buffer */
5974 int *, /* conf_state */
5975 int * /* qop_state */
5976 );
5981 #endif /* GSSAPI_H_ */
5987 Wray Document Expiration: 1 September 1997 [Page 91]
5990 \f
5995 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
5999 APPENDIX B. Additional constraints for application binary portability
6001 The purpose of this C-bindings document is to encourage source-level
6002 portability of applications across GSS-API implementations on different
6003 platforms and atop different mechanisms. Additional goals that have not
6004 been explicitly addressed by this document are link-time and run-time
6005 portability.
6007 Link-time portability provides the ability to compile an application
6008 against one implementation of GSS-API, and then link it against a
6009 different implementation on the same platform. It is a stricter
6010 requirement than source-level portability.
6012 Run-time portability differs from link-time portability only on those
6013 platforms that implement dynamically loadable GSS-API implementations,
6014 but do not offer load-time symbol resolution. On such platforms, run-
6015 time portability is a stricter requirement than link-time portability,
6016 and will typically include the precise placement of the various GSS-API
6017 routines within library entrypoint vectors.
6019 Individual platforms will impose their own rules that must be followed
6020 to achieve link-time (and run-time, if different) portability. In order
6021 to ensure either form of binary portability, an ABI specification must
6022 be written for GSS-API implementations on that platform. However, it is
6023 recognized that there are some issues that are likely to be common to
6024 all such ABI specifications. This appendix is intended to be a
6025 repository for such common issues, and contains some suggestions that
6026 individual ABI specifications may choose to reference. Since machine
6027 architectures vary greatly, it may not be possible or desirable to
6028 follow these suggestions on all platforms.
6030 B.1. Pointers
6032 While ANSI-C provides a single pointer type for each declared type, plus
6033 a single (void *) type, some platforms (notably those using segmented
6034 memory architectures) augment this with various modified pointer types
6035 (e.g. far pointers, near pointers). These language bindings assume
6036 ANSI-C, and thus do not address such non-standard implementations.
6037 GSS-API implementations for such platforms must choose an appropriate
6038 memory model, and should use it consistently throughout. For example,
6039 if a memory model is chosen that requires the use of far pointers when
6040 passing routine parameters, then far pointers should also be used within
6041 the structures defined by GSS-API.
6043 B.2. Internal structure alignment
6045 GSS-API defines several data-structures containing differently-sized
6046 fields. An ABI specification should include a detailed description of
6047 how the fields of such structures are aligned, and if there is any
6048 internal padding in these data structures. The use of compiler defaults
6049 for the platform is recommended.
6053 Wray Document Expiration: 1 September 1997 [Page 92]
6056 \f
6061 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
6065 B.3. Handle types
6067 The C bindings specify that the gss_cred_id_t and gss_ctx_id_t types
6068 should be implemented as either pointer or arithmetic types, and that if
6069 pointer types are used, care should be taken to ensure that two handles
6070 may be compared with the == operator. Note that ANSI-C does not
6071 guarantee that two pointer values may be compared with the == operator
6072 unless either the two pointers point to members of a single array, or at
6073 least one of the pointers contains a NULL value.
6075 For binary portability, additional constraints are required. The
6076 following is an attempt at defining platform-independent constraints.
6078 (a) The size of the handle type must be the same as sizeof(void *),
6079 using the appropriate memory model.
6081 (b) The == operator for the chosen type must be a simple bit-wise
6082 comparison. That is, for two in-memory handle objects h1 and h2,
6083 the boolean value of the expression
6085 (h1 == h2)
6087 should always be the same as the boolean value of the expression
6089 (memcmp(&h1, &h2, sizeof(h1)) == 0)
6091 (c) The actual use of the type (void *) for handle types is
6092 discouraged, not for binary portability reasons, but since it
6093 effectively disables much of the compile-time type-checking that
6094 the compiler can otherwise perform, and is therefore not
6095 "programmer-friendly". If a pointer implementation is desired,
6096 and if the platform's implementation of pointers permits, the
6097 handles should be implemented as pointers to distinct
6098 implementation-defined types.
6100 B.4. The gss_name_t type
6102 The gss_name_t type, representing the internal name object, should be
6103 implemented as a pointer type. The use of the (void *) type is
6104 discouraged as it does not allow the compiler to perform strong type-
6105 checking. However, the pointer type chosen should be of the same size
6106 as the (void *) type. Provided this rule is obeyed, ABI specifications
6107 need not further constrain the implementation of gss_name_t objects.
6109 B.5. The int and size_t types
6111 Some platforms may support differently sized implementations of the
6112 "int" and "size_t" types, perhaps chosen through compiler switches, and
6113 perhaps dependent on memory model. An ABI specification for such a
6114 platform should include required implementations for these types. It is
6115 recommended that the default implementation (for the chosen memory
6119 Wray Document Expiration: 1 September 1997 [Page 93]
6122 \f
6127 INTERNET-DRAFT GSS-API V2 - C bindings March 1997
6131 model, if appropriate) is chosen.
6133 B.6. Procedure-calling conventions
6135 Some platforms support a variety of different binary conventions for
6136 calling procedures. Such conventions cover things like the format of
6137 the stack frame, the order in which the routine parameters are pushed
6138 onto the stack, whether or not a parameter count is pushed onto the
6139 stack, whether some argument(s) or return values are to be passed in
6140 registers, and whether the called routine or the caller is responsible
6141 for removing the stack frame on return. For such platforms, an ABI
6142 specification should specify which calling convention is to be used for
6143 GSSAPI implementations.
6146 REFERENCES
6148 [GSSAPI] J. Linn, "Generic Security Service Application Program
6149 Interface, Version 2", Internet-Draft draft-ietf-cat-gssv2-
6150 08, 26 August 1996. (This Internet-Draft, like all other
6151 Internet-Drafts, is not an archival document and is subject
6152 to change or deletion. It is available at the time of this
6153 writing by anonymous ftp from ds.internic.net, directory
6154 internet-drafts. Would-be readers should check for successor
6155 Internet-Draft versions or Internet RFCs before relying on
6156 this document.)
6158 [XOM] OSI Object Management API Specification, Version 2.0 t",
6159 X.400 API Association & X/Open Company Limited, August 24,
6160 1990. Specification of datatypes and routines for
6161 manipulating information objects.
6164 AUTHOR'S ADDRESS
6166 John Wray Internet email: Wray@tuxedo.enet.dec.com
6167 Digital Equipment Corporation Telephone: +1-508-486-5210
6168 550 King Street, LKG2-2/Z7
6169 Littleton, MA 01460
6170 USA
6185 Wray Document Expiration: 1 September 1997 [Page 94]