Internet-Draft MS Windows GSS-API Expires: 25SEP95 24MAR95 P V McMahon, ICL GSS-API V1 MS Windows Dynamic Link Library Interface Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft document valid for a maximum of six months and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress". To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). Contents List 1. Purpose 2. Relationship with the Standards Track GSS-API V1 C Bindings 3. Background and Motivation 4. Scope 5. DLL Interface 5.1 Calling convention 5.2 Pointers 5.3 Structure Alignment 5.4 Implementation-defined Types 5.5 Integer types 5.6 Entry-point Ordinals 5.7 Dynamic Link Library Name 6. Extensions 7. Module Definition File 8. Example Prototypes 9. Example Type Declarations 10. References 11. Security Considerations 12. Author's Address 1. Purpose This note specifies the C interface to GSS-API V1 when implemented in a MS Windows Dynamic Link Library (DLL). McMahon [Page 1] Internet-Draft MS Windows GSS-API 2. Relationship with the Standards Track GSS-API V1 C Bindings To minimise the need for further updates of this note, any differences between the MS Windows GSS-API V1 interface described here, and the Standards Track GSS-API V1 C Bindings are specified as deltas rather than by reproducing the standards track C definitions (RFC 1509 at time of writing). For illustrative purposes only, examples are provided to show the interface definition as applied to RFC 1509. 3. Background and Motivation It is not possible to use the Standards Track GSS-API V1 C Bindings unchanged in a MS Windows 3.1 environment. This is primarily because the underlying segmented addressing mechanism is exposed to the application programmer on 16-bit targets, and valid assumptions about pointers (in an ANSI C environment) break down. Specifically, pointers to DLL inputs must be declared "FAR" so that they point to stack data, otherwise they are incorrectly assumed to point to data on the data segment of the DLL. Hence changes are needed to ensure that GSS-API V1 interface pointers explicitly refer to the data intended by the caller. These are specified in the following sections. In addition, other interface inconsistencies relating to assumed size of "int" which become evident in a MS Windows 3.1 interface are also identified and resolved. 4. Scope The interface is defined to be suitable for MS Windows 3.1 and beyond (i.e. a Win32 environment as available in MS Windows for Workgroups 3.11, and the anticipated Windows 95 isn't assumed - though isn't precluded). This interface specification is, in conjunction with the C Bindings, sufficiently detailed such that binary user applications can link, unchanged, with different providers' GSS-API V1 Dynamic Link Libraries. [Note: This level of portability is in addition to the source-level compatibility defined by the Standards Track GSS-API V1 C Bindings for ANSI C environments.] McMahon [Page 2] Internet-Draft MS Windows GSS-API 5. DLL Interface 5.1 Calling convention The Pascal calling convention is used for all the entry points of the GSS-API V1 DLL. This requires the keyword PASCAL to prefix each entry point to override the default (cdecl). 5.2 Pointers As the GSS-API V1 library is provided in a DLL, all references passed to it from calling applications must be declared FAR. This applies to all parts of the interfaces - both entry points and data structures. 5.3 Structure Alignment A structure alignment value of 4 is used to enable the API to be used for both 16-bit and 32-bit targets. [Note: This can be implemented by a pragma (#pragma pack(4)), or a compiler option /Zp4.] 5.4 Implementation-defined Types For a GSS-API V1 DLL interface to be complete, the types representing 32-bit integers, credentials, contexts, and names need to be specified. The implementation-dependent types are therefore fixed for the MS Windows environment as follows. typedef DWORD OM_uint32; typedef struct {VOID FAR *gss_ctx_id_t}, typedef struct {VOID FAR *gss_cred_id_t}, typedef struct {VOID FAR *gss_name_t} Implementation-defined types may be defined for other development environments in separate documents. McMahon [Page 3] Internet-Draft MS Windows GSS-API 5.5 Integer types There are some minor inconsistencies in RFC 1509 which sometimes use int, where OM_uint32 should be used, for some interfaces. [This is being corrected in the GSS-API V2 update]. Implementations of some GSS-API V1 entry points may therefore use "int" parameters which are adequate in a 32-bit environment, but may be insufficient, and lead to inconsistencies in a 16-bit environment. In particular: - gss_init_sec_context time_req input is a int Given that the "time_rec" output from both gss_init_sec_context and gss_context_time is a OM_uint, the interface definition in the RFC 1509 C Bindings is internally inconsistent with respect to this data type as the type is correctly specified in the header file section, but is incorrect in the interface definition section. - gss_display_status status_value is an int Given that the "minor status" output from GSS-API V1 entry points is always a OM_uint32, the interface in the RFC 1509 C Bindings is internally inconsistent with respect to this data type as the type is correctly specified in the header file section, but is incorrect in the interface definition section. Hence, in the MS Windows 3.1 bindings, both of these parameters need to be of type OM_uint32. 5.6 Entry-point Ordinals Consumers of GSS-API V1 can import DLL entry points by name or by ordinal number, but the latter is recommended by Microsoft for efficiency. Ordinals for the GSS-API V1 are therefore defined starting from 1, and are assigned to entry points as specified in Annex 1. Ordinals between 1 and 1000 are reserved for Standards Track GSS-API V1 interfaces. McMahon [Page 4] Internet-Draft MS Windows GSS-API 5.7 Dynamic Link Library Name The GSS-API V1 is provided in a dynamic library which is called GSSAPI.DLL and its location is determined by local configuration. This library may invoke one or more provider's GSS-API V1 services. The associated link-time import library is called GSSAPI.LIB. 6. Extensions Extensions to GSS-API V1 may be defined in future revisions of the Standards Track GSS-API V1 C Bindings. GSS-API V1 extensions from other sources may be provided in separate DLLs, or as entry points in GSSAPI.DLL with ordinal values greater than 1000. 7. Module Definition File For RFC 1509, the following defines the ordinal numbers to be used by portable implementations (presented as a template module definition file for the GSS-API V1 DLL). GSSAPI.DLL Module-Definition File LIBRARY GSSAPI DESCRIPTION 'Base Generic Security Service API' EXETYPE WINDOWS CODE /* implementation specific */ DATA /* implementation specific */ HEAPSIZE /* implementation specific */ EXPORTS gss_acquire_cred @1 gss_release_cred @2 gss_init_sec_context @3 gss_accept_sec_context @4 gss_process_context_token @5 gss_delete_sec_context @6 gss_context_time @7 gss_sign @8 gss_verify @9 gss_seal @10 gss_unseal @11 gss_display_status @12 gss_indicate_mechs @13 McMahon [Page 5] Internet-Draft MS Windows GSS-API gss_compare_name @14 gss_display_name @15 gss_import_name @16 gss_release_name @17 gss_release_buffer @18 gss_release_oid_set @19 gss_inquire_cred @20 8. Example Prototypes For RFC 1509, the following are the entry points for the GSS-API V1 DLL, as would be declared in . OM_uint32 FAR PASCAL gss_acquire_cred (OM_uint32 FAR *, /* minor_status */ gss_name_t, /* desired_name */ OM_uint32, /* time_req */ gss_OID_set, /* desired_mechs */ int, /* cred_usage */ gss_cred_id_t FAR *, /* output_cred_handle */ gss_OID_set FAR *, /* actual_mechs */ OM_uint32 FAR * /* time_rec */ ); OM_uint32 FAR PASCAL gss_release_cred (OM_uint32 FAR *, /* minor_status */ gss_cred_id_t FAR * /* cred_handle */ ); OM_uint32 FAR PASCAL gss_init_sec_context (OM_uint32 FAR *, /* minor_status */ gss_cred_id_t, /* claimant_cred_handle */ gss_ctx_id_t FAR *, /* context_handle */ gss_name_t, /* target_name */ gss_OID, /* mech_type */ int, /* req_flags */ OM_uint32, /* time_req */ gss_channel_bindings_t,/* input_chan_bindings */ gss_buffer_t, /* input_token */ gss_OID FAR *, /* actual_mech_type */ gss_buffer_t, /* output_token */ int FAR *, /* ret_flags */ OM_uint32 FAR * /* time_rec */ ); OM_uint32 FAR PASCAL gss_process_context_token (OM_uint32 FAR *, /* minor_status */ gss_ctx_id_t, /* context_handle */ gss_buffer_t /* token_buffer */ ); McMahon [Page 6] Internet-Draft MS Windows GSS-API OM_uint32 FAR PASCAL gss_delete_sec_context (OM_uint32 FAR *, /* minor_status */ gss_ctx_id_t *, /* context_handle */ gss_buffer_t /* output_token */ ); OM_uint32 FAR PASCAL gss_sign (OM_uint32 FAR *, /* minor_status */ gss_ctx_id_t, /* context handle */ int, /* qop_req */ gss_buffer_t, /* message_buffer */ gss_buffer_t /* message_token */ ); OM_uint32 FAR PASCAL gss_verify (OM_uint32 FAR *, /* minor_status */ gss_ctx_id_t, /* context_handle */ gss_buffer_t, /* message_buffer */ gss_buffer_t, /* token_buffer */ int FAR * /* qop_state */ ); OM_uint32 FAR PASCAL gss_seal (OM_uint32 FAR *, /* minor_status */ gss_ctx_id_t, /* context_handle */ int, /* conf_req_flag */ int, /* qop_req */ gss_buffer_t, /* input_message_buffer */ int FAR *, /* conf_state */ gss_buffer_t /* output_message_buffer */ ); OM_uint32 FAR PASCAL gss_unseal (OM_uint32 FAR *, /* minor_status */ gss_ctx_id_t, /* context_handle */ gss_buffer_t, /* input_message_buffer */ gss_buffer_t, /* output_message_buffer */ int FAR *, /* conf_state */ int FAR * /* qop_state */ ); OM_uint32 FAR PASCAL gss_indicate_mechs (OM_uint32 FAR *, /* minor_status */ gss_OID_set FAR * /* mech_set */ ); OM_uint32 FAR PASCAL gss_compare_name (OM_uint32 FAR *, /* minor_status */ gss_name_t, /* name 1 */ gss_name_t, /* name 2 */ McMahon [Page 7] Internet-Draft MS Windows GSS-API int FAR * /* name equal */ ); OM_uint32 FAR PASCAL gss_display_name (OM_uint32 FAR *, /* minor_status */ gss_name_t, /* input_name */ gss_buffer_t, /* output_name_buffer */ gss_OID FAR * /* output_name_type */ ); OM_uint32 FAR PASCAL gss_import_name (OM_uint32 FAR *, /* minor_status */ gss_buffer_t, /* input_name_buffer */ gss_OID, /* input_name_type */ gss_name_t FAR * /* output_name */ ); OM_uint32 FAR PASCAL gss_release_name (OM_uint32 FAR *, /* minor_status */ gss_name_t FAR * /* name */ ); OM_uint32 FAR PASCAL gss_display_status (OM_uint32 FAR *, /* minor_status */ OM_uint32, /* status_value */ int, /* status_type */ gss_OID, /* mech_type */ int FAR *, /* message_context */ gss_buffer_t /* status_string */ ); OM_uint32 FAR PASCAL gss_context_time (OM_uint32 FAR *, /* minor_status */ gss_ctx_id_t, /* context_handle */ OM_uint32 FAR * /* time_rec */ ); OM_uint32 FAR PASCAL gss_release_buffer (OM_uint32 FAR *, /* minor_status */ gss_buffer_t /* buffer */ ); OM_uint32 FAR PASCAL gss_release_oid_set (OM_uint32 FAR *, /* minor_status */ gss_OID_set FAR * /* set */ ); OM_uint32 FAR PASCAL gss_inquire_cred (OM_uint32 FAR *, /* minor_status */ gss_cred_id_t, /* cred_handle */ gss_name_t FAR *, /* name */ McMahon [Page 8] Internet-Draft MS Windows GSS-API OM_uint32 FAR *, /* lifetime */ int FAR *, /* cred_usage */ gss_OID_set FAR * /* mechanisms */ ); 9. Example Type Declarations For RFC 1509, the following are the types for the GSS-API V1 DLL as would be declared in . typedef struct gss_OID_desc_struct { OM_uint32 length; VOID FAR *elements; } gss_OID_desc, FAR *gss_OID; typedef struct gss_OID_set_desc_struct { int count; gss_OID elements; } gss_OID_set_desc, FAR *gss_OID_set; typedef struct gss_buffer_desc_struct { size_t length; VOID FAR *value; } gss_buffer_desc, FAR *gss_buffer_t; typedef struct gss_channel_bindings_struct { OM_uint32 initiator_addrtype; gss_buffer_desc initiator_address; OM_uint32 acceptor_addrtype; gss_buffer_desc acceptor_address; gss_buffer_desc application_data; } gss_channel_bindings_desc, FAR *gss_channel_bindings_t; 10. References [RFC1509] Generic Security Service API : C-bindings, J Wray, September 1993 11. Security Considerations This document defines a MS Windows bindings for a generic security interface. The implementation of that interface should be as secure as is practicable for a MS Windows 3.1 environment. McMahon [Page 9] Internet-Draft MS Windows GSS-API 12. Author's Address P V McMahon post: ICL Enterprises, Kings House, 33 Kings Road, Reading, RG1 3PX, UK email: p.v.mcmahon@rea0803.wins.icl.co.uk phone: +44 734 634882 fax: +44 734 855106 McMahon [Page 10]