Internet Draft S. Klump, Entrust Technologies Ltd. draft-ietf-cat-idup-cbind-03.txt D. Thakkar, Entrust Technologies Ltd. Expires: November 1, 1997 May 1, 1997 Independent Data Unit Protection Generic Security Service Application Program Interface: C-bindings STATUS OF THIS MEMO This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." To learn the current status of any Internet Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). Comments on this document should be sent to "cat-ietf@mit.edu", the IETF Common Authentication Technology WG discussion list. ABSTRACT The Independent Data Unit Protection Generic Security Service Application Program Interface (IDUP-GSS-API) extends the GSS-API [RFC-1508] for applications requiring protection of a generic data unit (such as a file or message) in a way that is independent of the protection of any other data unit and independent of any concurrent contact with designated "receivers" of the data unit. Thus, it is suitable for applications such as secure electronic mail where data needs to be protected without any on-line connection with the intended recipient(s) of that data. The protection offered by the IDUP includes data origin authentication with data integrity, data confidentiality with data integrity, and support for non-repudiation services. Subsequent to being protected, the independent data unit can be transferred to the recipient(s) - or to an archive - perhaps to be processed ("unprotected") only days or years later. The Independent Data Unit Protection Generic Security Service Application Program Interface for Signing and Encrypting (IDUP-SE) provides a simplified API for the services of signing and encrypting. The Independent Data Unit Protection Generic Security Service Application Program Interface for Evidence (IDUP-EV) provides a simplified API for the service of evidence validation. This document is a companion document to the IDUP-GSS-API and specifies its C language bindings. It extends the generic GSS-API: C-Bindings document [RFC-1509]. Klump, Thakkar 1 Expires: November 1, 1997 TABLE OF CONTENTS 1. INTRODUCTION ................................................ 4 2. IDUP-GSS-API ROUTINES ....................................... 6 2.1. Data Types and Calling Conventions ........................ 7 2.1.1. Structured data types ................................... 7 2.1.2. Integer types ........................................... 7 2.1.3. String and similar data ................................. 8 2.1.3.1. Opaque data types ..................................... 8 2.1.3.2. Character strings ..................................... 8 2.1.4. Object Identifiers ...................................... 8 2.1.5. Object Identifier Sets .................................. 9 2.1.6. Parameter Bundles ....................................... 9 2.1.6.1. Regular IDUP-GSS-API Parameter Bundles ................ 10 2.1.6.2. Parameter Bundles Specific to IDUP-SE ................. 15 2.1.6.3. Parameter Bundles Specific to IDUP-EV ................. 16 2.1.7. Credentials ............................................. 19 2.1.8. Environments ............................................ 19 2.1.9. Tokens .................................................. 19 2.1.10. Status values .......................................... 19 2.1.10.1. IDUP-GSS status codes ................................ 20 2.1.10.2. Mechanism-specific status codes ...................... 22 2.1.11. Names .................................................. 23 2.1.12. Optional parameters .................................... 23 2.1.12.1. gss_buffer_t types ................................... 24 2.1.12.2. Integer types (input) ................................ 24 2.1.12.3. Integer types (output) ............................... 24 2.1.12.4. Pointer types ........................................ 24 2.1.12.5. Object IDs ........................................... 24 2.1.12.6. Object ID Sets ....................................... 24 2.1.12.7. Parameter Bundles .................................... 24 2.1.12.8. Credentials .......................................... 24 2.1.12.9. Environments ......................................... 24 3. IDUP-GSS-API routine descriptions .......................... 25 3.1. Credential management calls .............................. 25 3.2. Environment-level calls .................................. 25 3.2.1. idup_establish_env ...................................... 26 3.2.2. idup_abolish_env ........................................ 29 3.2.3. idup_inquire_env ........................................ 30 3.3. Per-IDU Calls ............................................ 32 3.3.1. The IDUP-SE Calls ....................................... 32 3.3.1.1. idup_se_singlebuffer_protect .......................... 33 3.3.1.2. idup_se_singlebuffer_unprotect ........................ 35 3.3.1.3. idup_se_multibuffer_start_protect ..................... 37 3.3.1.4. idup_se_multibuffer_end_protect ....................... 39 3.3.1.5. idup_se_multibuffer_start_unprotect ................... 41 3.3.1.6. idup_se_multibuffer_end_unprotect ..................... 43 3.3.1.7. idup_se_multibuffer_process_buffer .................... 45 3.3.2. The IDUP-EV Calls ....................................... 46 3.3.2.1. idup_ev_singlebuffer_generate ......................... 46 3.3.2.2. idup_ev_singlebuffer_verify ........................... 48 3.3.2.3. idup_ev_multibuffer_startgenerate ..................... 51 3.3.2.4. idup_ev_multibuffer_endgenerate ....................... 53 3.3.2.5. idup_ev_multibuffer_startverify ....................... 55 3.3.2.6. idup_ev_multibuffer_endverify ......................... 57 3.3.2.7. idup_ev_process_buffer ................................ 59 3.3.3. The General IDUP-GSS-API Calls .......................... 60 3.3.3.1. idup_start_protect .................................... 60 3.3.3.2. idup_protect .......................................... 63 3.3.3.3. idup_end_protect ...................................... 64 3.3.3.4. idup_start_unprotect .................................. 66 3.3.3.5. idup_unprotect ........................................ 70 3.3.3.6. idup_end_unprotect .................................... 71 Klump, Thakkar 2 Expires: November 1, 1997 3.4. Special-Purpose Calls .................................... 73 3.4.1. idup_form_complete_pidu ................................. 73 3.5. Support calls ............................................ 75 3.5.1. idup_acquire_cred_with_auth ............................. 75 3.5.2. IDUP_Parse_token ........................................ 77 3.5.3. idup_get_token_details .................................. 78 3.5.4. idup_get_policy_info .................................... 81 3.6. Memory Management Calls .................................. 83 3.6.1. Memory Management Calls Specific to IDUP-SE ............. 83 3.6.1.1. idup_se_alloc_protect_options ......................... 84 3.6.1.2. idup_se_release_protect_options ....................... 85 3.6.1.3. idup_se_alloc_pidu_information ........................ 86 3.6.1.4. idup_se_release_pidu_information ...................... 87 3.6.2. Memory Management Calls Specific to IDUP-EV ............. 88 3.6.2.1. idup_ev_alloc_Nr_Options .............................. 88 3.6.2.2. idup_ev_release_Nr_Options ............................ 89 3.6.2.3. idup_ev_alloc_Originator_Options ...................... 90 3.6.2.4. idup_ev_release_Originator_Options .................... 91 3.6.2.5. idup_ev_alloc_Request_Features ........................ 92 3.6.2.6. idup_ev_release_Request_Features ...................... 93 3.6.3. Memory Management Calls for the General IDUP-GSS-API .... 94 3.6.3.1. idup_release_buffer ................................... 94 3.6.3.2. idup_release_buffer_content ........................... 95 3.6.3.3. idup_release_name ..................................... 96 3.6.3.4. idup_release_name_content ............................. 97 3.6.3.5. idup_create_empty_name_set ............................ 98 3.6.3.6. idup_add_name_set_member .............................. 100 3.6.3.7. idup_remove_name_set_member ........................... 101 3.6.3.8. idup_release_name_set ................................. 102 3.6.3.9. idup_alloc_general_service_data ....................... 103 3.6.3.10. idup_release_general_service_data .................... 104 3.6.3.11. idup_alloc_idu_information ........................... 105 3.6.3.12. idup_release_idu_information ......................... 106 3.6.3.13. idup_alloc_idu_sensitivity ........................... 107 3.6.3.14. idup_release_idu_sensitivity ......................... 108 3.6.3.15. idup_alloc_prot_service .............................. 109 3.6.3.16. idup_release_prot_service ............................ 110 3.6.3.17. idup_alloc_quality ................................... 111 3.6.3.18. idup_release_quality ................................. 112 3.6.3.19. idup_alloc_prot_information .......................... 113 3.6.3.20. idup_release_prot_information ........................ 114 3.6.3.21. idup_alloc_service_creation_info ..................... 115 3.6.3.22. idup_release_service_creation_info ................... 116 3.6.3.23. idup_alloc_service_verification_info ................. 117 3.6.3.24. idup_release_service_verification_info ............... 118 3.6.3.25. idup_create_empty_services_to_receive ................ 119 3.6.3.26. idup_release_services_to_receive ..................... 120 3.6.3.27. idup_create_empty_services_to_perform ................ 121 3.6.3.28. idup_add_services_to_perform_member .................. 122 3.6.3.29. idup_release_services_to_perform ..................... 123 3.6.3.30. idup_alloc_special_conditions ........................ 124 3.6.3.31. idup_release_special_conditions ...................... 125 3.6.3.32. idup_alloc_target_info ............................... 126 3.6.3.33. idup_release_target_info ............................. 127 3.6.3.34. idup_alloc_unprot_service ............................ 128 3.6.3.35. idup_release_unprot_service .......................... 129 4. ACKNOWLEDGMENTS ............................................ 130 5. SECURITY CONSIDERATIONS .................................... 131 6. REFERENCES ................................................. 132 7. AUTHORS' ADDRESSES ......................................... 133 APPENDIX - IDUP-GSS-API Example ................................ 134 Klump, Thakkar 3 Expires: November 1, 1997 1. INTRODUCTION The Independent Data Unit Protection Generic Security Service Application Program Interface (IDUP-GSS-API) [IDUP] provides security services to calling applications in a local environment. It allows an application to protect an independent data unit for future use, to unprotect a protected independent data unit and to apply security services such as data origin authentication with integrity (DOA), confidentiality (CONF) with integrity (INT), and / or support for non-repudiation on a per-data-unit basis. There are four stages to using the IDUP-GSS-API: (a) The application acquires a set of credentials with which it may bind its identity to a data unit. The application's credentials vouch for its global identity, which may or may not be related to the local user name under which it is running. (b) The application establishes a security environment using its credentials. The security environment is an IDUP-GSS-API data structure that contains information necessary to gain access to per-data-unit security services. (c) The application invokes per-data-unit services on an established IDUP environment to perform IDU protection and unprotection. Per-IDU calls for IDU protection can support (i) data origin authentication with data integrity, (ii) confidentiality with data integrity, (iii) evidence generation (perform non-repudiable "proof of origin", "proof of delivery", etc...). The simplified IDUP-SE API per-IDU calls for IDU protection can support only (i) and (ii) above. The simplified IDUP-EV API per-IDU calls for evidence generation can support only (iii) above. The application wishing to protect an IDU will call the protect IDUP-GSS-API routines, specifying the appropriate security environment. IDUP-GSS-API calls for protection operations will return a token data structure. This token encapsulates all the information to unprotect the IDU. Per-IDU calls for P-IDU unprotection can support (i) data origin authentication verification, (ii) decipherment, (iii) evidence verification The simplified IDUP-SE API calls for P-IDU unprotection can support only (i) and (ii) above. The simplified IDUP-EV API calls for evidence verification can support only (iii) above. The recipient will pass the protected IDU to the unprotecting routines to remove the protection and validate the data. Klump, Thakkar 4 Expires: November 1, 1997 (d) At the completion of a security environment (which may extend across several protection and unprotection operations), the application calls an IDUP-GSS-API routine to abolish the security environment. Klump, Thakkar 5 Expires: November 1, 1997 2. IDUP-GSS-API ROUTINES This section lists the functions performed by each of the IDUP-GSS-API calls and discusses their major parameters, describing how they are to be passed to the routines. Figure 1 lists the calls (an asterisk marks the calls which are identical to the GSS-API specification). Figure 1 - IDUP-GSS-API Calls CREDENTIAL MANAGEMENT * gss_acquire_cred Acquires credentials for use. * gss_release_cred Releases credentials after use. * gss_inquire_cred Displays information about credentials. * gss_add_cred Adds credential info (see [GSSv2]). ENVIRONMENT-LEVEL CALLS idup_establish_env Establishes IDUP environment (to protect or unprotect IDUs). idup_abolish_env Abolishes env. when no longer needed. idup_inquire_env Obtains environment parameters. PER-IDU CALLS idup_se_singlebuffer_protect Protects a single buffer (signing and/or encryption only) idup_se_singlebuffer_unprotect Unprotects a single buffer (verifying and/or decryption only). idup_se_multibuffer_startprotect Begins the protection process (signing and/or encryption only). idup_se_multibuffer_endprotect Ends the protection process (signing and/or encryption only). idup_se_multibuffer_startunprotect Begins the unprotection process (verifying and/or decryption only). idup_se_multibuffer_endunprotect Ends the unprotection process (verifying and/or decryption only). idup_se_process_buffer Protects or unprotects one buffer (signing/encryption and/or verifying/ decryption only). idup_start_protect Begins the protection process. idup_protect Protects IDU (perhaps 1 buffer at a time). Klump, Thakkar 6 Expires: November 1, 1997 idup_end_protect Ends the protection process; create a token that contains info. necessary for the legitimate receiver(s) of the P-IDU to unprotect it. idup_start_unprotect Begins the unprotection process. idup_unprotect Uses the token to unprotect the P-IDU (possibly 1 buffer at a time). idup_end_unprotect Ends the unprotection process. SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms) idup_form_complete_pidu Inserts in evidence_token any data not provided by the evi. generation calls SUPPORT CALLS * gss_display_status Translates status codes to printable form. * gss_indicate_mechs Indicates mech_types supported on local system * gss_compare_name Compares two names for equality. * gss_display_name Translates name to printable form. * gss_import_name Converts printable name to normalized form. * gss_release_name Frees storage of normalized-form name. * gss_release_buffer Frees storage of printable name. * gss_release_oid_set Frees storage of OID set. idup_parse_token Examines an input token to determine mech_type and token_type and other info. Individual IDUP-GSS-API implementations may augment these routines by providing additional mechanism-specific routines if required functionality is not available from the generic forms. Applications should use the generic routines wherever possible on portability grounds. 2.1. Data Types and Calling Conventions The following conventions are used by the IDUP-GSS-API: 2.1.1. Structured data types Wherever these IDUP-GSS-API C-bindings describe structured data, they document only those fields that all IDUP-GSS-API implementations must provide. Individual implementations may provide additional fields, either for internal use within IDUP-GSS-API routines, or for use by non-portable applications. 2.1.2. Integer types IDUP-GSS-API defines the following integer data type: OM_uint32 32-bit unsigned integer Klump, Thakkar 7 Expires: November 1, 1997 Where guaranteed minimum bit-count is important, this portable data type is used by the IDUP-GSS-API routine definitions. Individual IDUP-GSS-API implementations will include appropriate typedef definitions to map this type onto a built-in data type. 2.1.3. String and similar data Many of the IDUP-GSS-API routines take arguments and return values that describe contiguous multiple-byte data. The gss_buffer_t type passes all such data between the IDUP-GSS-API and the caller. This data type is a pointer to a buffer descriptor, which consists of a length field that contains the total number of bytes in the datum, and a value field which contains a pointer to the actual datum: typedef struct gss_buffer_desc_struct { size_t length; void* value; } gss_buffer_desc, *gss_buffer_t; An IDUP-GSS-API routine passing, via the gss_buffer_t convention, from itself to an application, allocates the storage itself. The application may free this storage by invoking the gss_release_buffer routine. The application is always responsible for the allocation of the gss_buffer_desc data unit; unused gss_buffer_desc units may initialize to the value GSS_C_EMPTY_BUFFER. 2.1.3.1. Opaque data types Certain multiple-word data items are considered opaque data types at the IDUP-GSS-API, because their internal structure has no significance either to the IDUP-GSS-API or to the caller. An example of such opaque data types is the input_buffer parameter to idup_protect (which is opaque to the IDUP-GSS-API). Opaque data is passed between the IDUP-GSS-API and the application using the gss_buffer_t datatype. 2.1.3.2. Character strings Certain multiple-word data items may be regarded as simple ISO Latin-1 character strings. An example of this is the input_name_buffer parameter to gss_import_name. Some IDUP-GSS-API routines also return character strings. IDUP-GSS-API routines always use the gss_buffer_t data type, defined earlier, to pass strings between the application and the IDUP-GSS-API. 2.1.4. Object Identifiers Certain IDUP-GSS-API procedures take parameters of the type gss_OID, or Object identifier. This is a type containing ISO-defined tree-structured values; the IDUP-GSS-API caller uses it to select an underlying security mechanism. A value of type gss_OID has the following structure: typedef struct gss_OID_desc_struct { OM_uint32 length; void* elements; } gss_OID_desc, *gss_OID; Klump, Thakkar 8 Expires: November 1, 1997 The elements field of this structure points to the first byte of an octet string containing the ASN.1 BER encoding of the value of the gss_OID. The length field contains the number of bytes in this value. For example, the gss_OID value corresponding to {iso(1) identified-organization(3) icd-ecma(12) member-company(2) dec(1011) cryptoAlgorithms(7) SPX(5)} meaning SPX (Digital's X.509 authentication mechanism) has a length field of 7 and an elements field pointing to seven octets containing the following octal values: 53,14,2,207,163,7,5. IDUP-GSS-API implementations should provide constant gss_OID values to allow callers to request any supported mechanism, although applications are encouraged on portability grounds to accept the default mechanism. gss_OID values should also be provided to allow applications to specify particular name types (see section 2.1.10). Applications should treat gss_OID_desc values returned by IDUP-GSS-API routines as read-only. In particular, the application should not attempt to deallocate them. The gss_OID_desc datatype is equivalent to the X/Open OM_object_identifier datatype [OSI]. 2.1.5. Object Identifier Sets Certain IDUP-GSS-API procedures take parameters of the type gss_OID_set. This type represents one or more object identifiers (section 2.1.4). A gss_OID_set object has the following structure: typedef struct gss_OID_set_desc_struct { int count; gss_OID elements; } gss_OID_set_desc, *gss_OID_set; The count field contains the number of OIDs within the set. The elements field is a pointer to an array of gss_OID_desc objects, each of which describes a single OID. Values of gss_OID_set are used to name the available mechanisms supported by the API-GSS-API, to request the use of specific mechanisms, and to indicate which mechanisms a given credential supports. The gss_release_oid_set routine deallocates storage associated with a gss_OID_set values. 2.1.6. Parameter Bundles Parameter bundles are sets of closely-related parameters of a call. Several IDUP-GSS-API procedures use them. A parameter bundle in turn may contain one or more parameter bundles. Parameters in a parameter bundle are either used by / available to the calling application or not used by / unavailable to the calling application. These parameters can be all input parameters, all output parameters, or any combination of the two. A parameter with comment "/* Input */" is an input parameter; one with "/* Output */" is an output parameter; one with no comment is an input if the bundle itself is an input and is an output if the bundle itself is an output. Wherever these IDUP-GSS-API C-bindings describe parameter bundles, they document only those fields that all IDUP-GSS-API implementations must provide. Individual implementations may provide additional fields, either for internal use within IDUP-GSS-API routines, or for use by non-portable applications. For some parameter bundles, the underlying mechanism include or define some actual parameters; the IDUP-GSS-API C-bindings do not present such parameters. The list of described parameter bundles follows. Klump, Thakkar 9 Expires: November 1, 1997 Regular IDUP-GSS-API Parameter Bundles: o Mech_Specific_Info o Idu_Sensitivity o Service_Creation_Info o Service_Verification_Info o Quality o Idu_Information o Prot_Information o Special_Conditions o General_Service_Data o Bad_Target_Name o Target_Info o Prot_Service o Unprot_Service o Services_to_Perform o Services_to_Receive o Service_Descriptor o Authority_List o Mechanism_Descriptor Parameter Bundles Specific to IDUP-SE: o Protect_Operation o Protect_Options o PIDU_Information Parameter Bundles Specific to IDUP-EV: o evidence_type o Nr_Options o Originator_Information o requested_evidence_type o Request_Features o nr_operation 2.1.6.1. Regular IDUP-GSS-API Parameter Bundles The following parameter bundles occur in the regular IDUP-GSS-API. o Mech_Specific_Info : Actual parameters included in this structure are defined by (and specific to) the underlying mechanism. o Idu_Sensitivity : Actual parameters included in this structure are defined by (and specific to) the underlying mechanism, but may include codified values for "Unclassifed", "Secret", "Top Secret", and so on. o Service_Creation_Info : o Service_Verification_Info : Actual parameters included in this structure are defined by (and specific to) the underlying mechanism, but it is mandatory that they include at least service_id and Quality. A Service_Creation_Info and Service_Verification_Info parameter bundle has the following structure: typedef struct { gss_OID service_id; IDUP_Quality Quality; } IDUP_Service_Creation_Info_desc, *IDUP_Service_Creation_Info, IDUP_Service_Verification_Info_desc, *IDUP_Service_Verification_Info; Klump, Thakkar 10 Expires: November 1, 1997 o Quality : This parameter bundle includes information which defines the level of quality associated with a security service. A Quality parameter bundle has the following structure: typedef struct { OM_uint32 qop_algs; OM_uint32 validity; gss_OID policy_id; BOOL allow_policy_mapping; } IDUP_Quality_desc, *IDUP_Quality; o Idu_Information : This parameter bundle contains encapsulated content type, content description and sensitivity IDU information. A Idu_Information parameter bundle has the following structure: typedef struct { gss_buffer_t idu_type; gss_buffer_t idu_title; IDUP_Idu_Sensitivity Idu_Sensitivity; } IDUP_Idu_Information_desc, *IDUP_Idu_Information; o Prot_Information : This parameter bundle contains subject field from the certificate (originator name), IDU information, time when protection was performed. A Prot_Information parameter bundle has the following structure: typedef struct { gss_buffer_t originator_name; IDUP_Idu_Information Idu_Information; time_t protection_time; } IDUP_Prot_Information_desc, *IDUP_Prot_Information; o Special_Conditions : This parameter bundle contains parameters which control the (un)protection procedures. A Special_Conditions parameter bundle has the following structure: typedef struct { int prot_oper_id; int use_trusted_time; int use_untrusted_time; } IDUP_Special_Conditions_desc, *IDUP_Special_Conditions; o General_Service_Data : Only protection procedures use this parameter bundle. It contains an IDUP_Target_Info parameter bundle as input and returns an unencapsulated token (if enacapsulation_request is TRUE) and a minor status code as output. Klump, Thakkar 11 Expires: November 1, 1997 A General_Service_Data parameter bundle has the following structure: typedef struct { IDUP_Target_Info Target_Info; gss_buffer_t unencapsulated_token; /* Output */ OM_uint32 minor_status; /* Output */ } IDUP_General_Service_Data_desc, *IDUP_General_Service_Data; o Bad_Target_Name This parameter bundle contains parameters that specify a rejected target name and a reason for rejection. A Bad_Target_Name parameter bundle has the following structure: typedef struct { gss_buffer_t bad_targ_name; /* Output */ int bad_targ_status; /* Output */ } IDUP_Bad_Target_Name_desc, *IDUP_Bad_Target_Name; o Target_Info : This parameter bundle contains parameters that allow the application to specify target names (to whom to deliver the service), to receive rejected names and to receive a reason for each rejection. A Target_Info parameter bundle has the following structure: typedef struct { idup_name_set targ_names; /* Input */ IDUP_Bad_Target_Name Bad_Target_Names; /* Output */ int bad_count; /* Output */ } IDUP_Target_Info_desc, *IDUP_Target_Info; The targ_names field is pointer to array of gss_name_desc objects, each of which describes a single name to whom to deliver the service. The IDUP-GSS-API returns the rejected names in IDUP_Bad_Target_Name, which is a pointer to an array of Bad_Target_Name_desc objects - each of which describes rejected name with a reason for rejection. The IDUP-GSS-API returns the number of rejected names in bad_count. o Prot_Service : IDUP defines three types of protection services: 1. Perform Unsolicited Service As an originator, applying data confidentiality with data integrity, data origin authentication with data integrity, or proof of origin evidence is an example of this service type. 2. Perform Solicited Service As a target, creating a proof of delivery (i.e., receipt) evidence token as the result of a request received from the originator is an example of this service type. 3. Perform Service Solicitation As an originator, submitting a request that one or more targets return a receipt for the data sent is an example of this service type. Klump, Thakkar 12 Expires: November 1, 1997 The first four parameters in the Prot_Service parameter bundle pertain to all service types; the fifth parameter is used if and only if service type 2 is desired; parameters 6-8 are used if and only if service type 3 is desired. A Prot_Service parameter bundle has the following structure: typedef struct { int prot_service_type; /* Input */ gss_OID service_id; /* Input */ IDUP_Quality Quality; /* Input */ IDUP_General_Service_Data General_Service_Data;/* Input */ IDUP_Service_Creation_Info Service_Creation_Info; /* Input */ idup_name_set services_to; /* Input */ IDUP_Service_Verification_Info Service_Verification_Info; /* Output */ gss_buffer_t service_verification_info_id; /* Output */ } IDUP_Prot_Service_desc, *IDUP_Prot_Service; o Services_To_Perform : This parameter bundle is a set of Prot_Service parameter bundles. A Services_To_Perform parameter bundle has the following structure: typedef struct { OM_uint32 no_of_services; IDUP_Prot_Service Prot_Service; } IDUP_Services_To_Perform_desc, *IDUP_Services_To_Perform; o Unprot_Service : IDUP-GSS-API defines three types of unprotection services: 1. Receive Unsolicited Service As a target, unprotecting an encrypted message or verifying the originator's proof of origin is an example of this service type. 2. Receive Solicited Service As an originator, verifying a proof of delivery that you requested from a target is an example of this service type. 3. Receive Service Solicitation As a target, receiving a request from an originator for a proof of delivery is an example of this service type. The first four parameters in the Unprot_Service parameter bundle pertain to all service types; parameters 5-6 are used if and only if service type 2 is required; parameters 7-8 are used if and only if service type 3 is required. Klump, Thakkar 13 Expires: November 1, 1997 A Unprot_Service parameter bundle has the following structure: typedef struct { int unprot_service_type; /* Output */ gss_OID service_id; /* Output */ IDUP_Quality Quality; /* Output */ IDUP_General_Service_Data General_Service_Data;/* Output */ int service_verification_info_id; /* Output */ IDUP_Service_Verification_Info Service_Verification_Info; /* Input */ idup_name_set services_to; /* Output */ IDUP_Service_Creation_Info Service_Creation_Info; /* Output */ } IDUP_Unprot_Service_desc, *IDUP_Unprot_Service; o Services_To_Receive : This parameter bundle is a set of Unprot_Service parameter bundles. A Services_To_Perform parameter bundle has the following structure: typedef struct { OM_uint32 no_of_services; IDUP_Unprot_Service Unprot_Service; } IDUP_Services_To_Receive_desc, *IDUP_Services_To_Receive; o Service_Descriptor A Service_Descriptor specifies a service type, a service validity duration and whether the service must use trusted time. A Service_Descriptor has the following structure: typedef struct { gss_OID service_type; int service_validity_duration; int must_use_trusted_time; } IDUP_Service_Descriptor_desc, *IDUP_Service_Descriptor; A Service_Descriptor_Set is a set of Service_Descriptor structures; it has a count and a pointer to the number of Service_Descriptor structures specified in the count. A Service_Descriptor_Set has the following structure: typedef struct { int count; IDUP_Service_Descriptor elements; } IDUP_Service_Descriptor_Set_desc, *IDUP_Service_Descriptor_Set; o Authority_List An Authority_List parameter bundle has the name and role of the authority, and a "last revocation check offset" time, in minutes. Any revocation taking effect earlier than the number of minutes in the last_revocation_check_offset parameter after the generation of a P-IDU renders that P-IDU invalid. Any revocation taking place after this time has no effect. For example, if the last_revocation_check_offset is -30 minutes, then any P-IDU generated with a certificate up to a half-hour before its revocation is considered valid. Klump, Thakkar 14 Expires: November 1, 1997 An Authority_List has the following structure: typedef struct { gss_name_t authority_name; gss_buffer_t authority_role; int last_revocation_check_offset; } IDUP_Authority_List_desc, *IDUP_Authority_List; o Mechanism_Descriptor A Mechanism_Descriptor specifies the mechanism type, a listing of the authority in charge and the maximum time skew in minutes. The maximum time skew is the permissible difference between P-IDU generation time and the time of countersignature from the time service (if required). This parameter is used only if trusted time is required. A Mechanism_Descriptor has the following structure: typedef struct { gss_OID mechanism_type; IDUP_Authority_List Authority_List; int maximum_time_skew; } IDUP_Mechanism_Descriptor_desc, *IDUP_Mechanism_Descriptor; A Mechanism_Descriptor_Set is a set of Mechanism_Descriptor strucures; it has a count and a pointer to the number of Mechanism_Descriptor structures specified in the count. A Mechanism_Descriptor_Set has the following structure: typedef struct { int count; IDUP_Mechanism_Descriptor elements; } IDUP_Mechanism_Descriptor_Set_desc, *IDUP_Mechanism_Descriptor_Set; 2.1.6.2. Parameter Bundles Specific to IDUP-SE The following parameter bundles occur only in the calls of the IDUP-SE API. o Protect_Operation : This parameter specifies the protection operation in IDUP-SE. A Protect_Operation has the following structure: typedef enum { sign_only, encrypt_only, sign_and_encrypt, sign_then_encrypt_data, sign_then_encrypt_full, encrypt_then_sign, clear_sign_only } IDUP_Protect_Operation; Figure 2 explains the meaning of each possible IDUP_Protect_Operation. Klump, Thakkar 15 Expires: November 1, 1997 Figure 2 - IDUP_Protect_Operation Meanings Value Meaning =================================================================== sign_only sign only; let mechanism choose encapsulation mode encrypt_only encrypt only sign_and_encrypt sign and encrypt; let mechanism choose order and readability of signature sign_then_encrypt_data sign, then encrypt the data and leave the signature in clear sign_then_encrypt_full sign, then encrypt the data and the signature encrypt_then_sign encrypt, then sign the ciphertext clear_sign_only sign the data; do not encapsulate o Protect_Options When protecting an IDU via IDUP-SE, this parameter bundle lays out the relevant options to be used in doing so: the protection operation, the signature algorithm, the encryption algorithm and a string specifying the IDU type. When unprotecting a P-IDU via IDUP-SE, this parameter bundle keeps track of the options used at protection time. A Protect_Options has the following structure: typedef struct { IDUP_Protect_Operation Protect_Operation; OM_uint32 sign_qop_alg; OM_uint32 enc_qop_alg; gss_buffer_t idu_type_string; } IDUP_Protect_Options_desc, *IDUP_Protect_Options; o PIDU_Information When unprotecting a P-IDU via IDUP-SE, a PIDU_Information reveals information about the protected IDU: the options used at protection time, who protected it and when. A PIDU_Information parameter bundle has the following structure: typedef struct { IDUP_Protect_Options Protect_Options; gss_buffer_t originator_name; time_t protection_time; } IDUP_PIDU_Information_desc, *IDUP_PIDU_Information; 2.1.6.3. Parameter Bundles Specific to IDUP-EV The following parameter bundles occur only in the calls of the IDUP-EV API. o evidence_type This parameter specifies the type of evidence in IDUP-EV. Klump, Thakkar 16 Expires: November 1, 1997 An evidence_type has the following structure: typedef enum { no_evidence, proof_of_receipt, proof_of_delivery, proof_of_approval, proof_of_retrieval, proof_of_creation, proof_of_sender, proof_of_origin } IDUP_evidence_type; Figure 3 - IDUP_evidence_type Meanings Value Meaning =================================================================== no_evidence used only to form request-only tokens proof_of_receipt non-repudiation of having received message proof_of_delivery non-repudiation of having received and looked at message proof_of_approval non-repudiation of having received and approved message proof_of_retrieval non-repudiation of having retrieved a message from a message store proof_of_creation non-repudiation of having created a message proof_of_sender non-repudiation of having sent a message proof_of_origin non-repudiation of having created and sent a message o Nr_Options A Nr_Options parameter bundle specifies the non-repudiation options desired in IDUP-EV: the type and the validity duration (in minutes). A Nr_Options parameter bundle has the following structure: typedef struct { IDUP_evidence_type evidence_type; int evidence_validity_duration; } IDUP_Nr_Options_desc, *IDUP_Nr_Options; o Originator_Information An Originator_Information parameter bundle keeps information about the originator and the time of origin of the token. An Originator_Information parameter bundle has the following structure: typedef struct { gss_name_t token_generator_name time_t protection_time } IDUP_Originator_Information_desc, *IDUP_Originator_Information; o requested_evidence_type A requested_evidence_type parameter specifies the type of evidence requested at generation time. Klump, Thakkar 17 Expires: November 1, 1997 A requested_evidence_type parameter has the following structure: typedef enum { no_evidence, proof_of_receipt, proof_of_delivery, proof_of_approval, proof_of_retrieval, } IDUP_requested_evidence_type; o Request_Features An Features parameter bundle specifies the features of the request for evidence generation: the requested evidence type, the security policy in effect, the recipients who are to send back an evidence token, the recipients who are to receive an evidence token and whether to include the request token in the generated evidence token. An Request_Features parameter bundle has the following structure: typedef struct { IDUP_requested_evidence_type requested_evidence_type; gss_OID nr_req_policy; IDUP_Target_Info evidence_from; IDUP_Target_Info evidence_to; int include_received_token_in_evidence; } IDUP_Request_Features_desc, *IDUP_Request_Features; o nr_operation An nr_operation parameter specifies whether an evidence token includes either evidence only, an evidence request only or both; or, a response to an evidence token that itself was generated as a response to a request. An nr_operation parameter has the following structure: typedef enum { evidence_and_or_evidence_request = 1, returned_evidence } IDUP_nr_operation; Klump, Thakkar 18 Expires: November 1, 1997 2.1.7. Credentials A credential handle is a caller-opaque atomic datum that identifies an IDUP-GSS-API credential data structure. The gss_cred_id_t type represents a credential handle. The data type may be either a pointer or an arithmetic type. Credentials describe a principal, and they give their holder the ability to act as that principal. The IDUP-GSS-API does not make the actual credentials available to applications; instead the credential handle identifies a particular credential, held internally by IDUP-GSS-API or an underlying mechanism. Thus, the credential handle contains no security-relevant information, and requires no special protection by the application. Depending on the implementation, a given credential handle may refer to different credentials when presented to the IDUP-GSS-API by different callers. Individual IDUP-GSS-API implementations should define both the scope of a credential handle and the scope of a credential itself (which must be at least as wide as that of a handle). Possibilities for credential handle scope include the process that acquired the handle, the acquisition process and its children, or all processes sharing some local identification information (e.g., UID). If no handles exist by which a given credential may be reached, the IDUP-GSS-API may abolish the credential. Certain routines allow omission of credential handle parameters to indicate the use of a default credential. The individual IDUP-GSS-API application should define the mechanism by which to establish a default credential. 2.1.8. Environments The idup_env_id_t data type contains a caller-opaque atomic value that identifies an IDUP-GSS-API security environment. The data type may be either an arithmetic or a pointer type. Depending on the implementation, a given idup_env_id_t value may refer to different IDUP-GSS-API security environments when presented to the IDUP-GSS-API by different callers. The security environment holds state information about the security operations, including cryptographic state information. Individual IDUP-GSS-API implementations should define the scope of an environment. Since no way is provided by which a new idup_env_id_t value may be obtained for an existing environment, the scope of an environment should be the same as the scope of the idup_env_id_t data type. 2.1.9. Tokens A token is a caller-opaque type that the IDUP-GSS-API uses to store information regarding an IDU. The token is a bit-string, generated by the underlying mechanism during protection, receipt generation, or evidence generation calls for use by the same or another security mechanism during unprotection, receipt processing, or evidence processing calls. The IDUP-GSS-API and the application pass tokens between themselves using the gss_buffer_t convention. 2.1.10. Status values Each IDUP-GSS-API routine returns one or more status codes. There are two kinds: IDUP-GSS status codes and Mechanism status codes. Klump, Thakkar 19 Expires: November 1, 1997 2.1.10.1. IDUP-GSS status codes IDUP-GSS-API routines return IDUP-GSS status codes as their OM_uint32 function value. These codes indicate errors that are independent of the underlying mechanism used to provide the security service. IDUP-GSS status codes indicate either generic API routine errors (errors that are defined in the IDUP-GSS-API specification) or calling errors (errors that are specific to these bindings). An IDUP-GSS status code can indicate a single fatal generic API error from the routine and a single calling error. In addition, setting bits in the supplementary info field of an IDUP-GSS status code can indicate supplementary information. These errors are encoded into the 32-bit GSS status code as follows: MSB LSB |------------------------------------------------------------| | Calling Error | Routine Error | Supplementary Info | |------------------------------------------------------------| Bit 31 24 23 16 15 0 Hence if an IDUP-GSS-API routine returns an IDUP-GSS status code whose upper 16 bits contain a non-zero value, the call failed. If the calling error field is non-zero, the invoking application's call of the routine was erroneous. Calling errors are defined in Table 1. If the routine error field is non-zero, the routine failed for one of the routine-specific reasons listed below in Table 2. Whether the upper 16 bits indicate a failure or a success, the routine may indicate additional information by setting bits in the supplementary info field of the status code. Table 3 lists the meaning of individual bits. Table 1 - Calling Errors Name Value in Meaning Field GSS_S_CALL_INACCESSIBLE_READ 1 a required input parameter could not be read GSS_S_CALL_INACCESSIBLE_WRITE 2 a required output parameter could not be written. GSS_S_CALL_BAD_STRUCTURE 3 a parameter was malformed. Klump, Thakkar 20 Expires: November 1, 1997 Table 2 - Routine Errors Name Value in Meaning Field GSS_S_BAD_MECH 1 unsupported mechanism requested GSS_S_BAD_NAME 2 invalid name provided GSS_S_BAD_NAMETYPE 3 name of unsupported type provided GSS_S_BAD_BINDINGS 4 NOT APPLICABLE TO IDUP GSS_S_BAD_STATUS 5 invalid input status selector GSS_S_BAD_SIG 6 token had invalid signature GSS_S_NO_CRED 7 no valid credentials provided GSS_S_NO_CONTEXT 8 NOT APPLICABLE TO IDUP GSS_S_DEFECTIVE_TOKEN 9 defective token detected GSS_S_DEFECTIVE_CREDENTIAL 10 defective credential detected GSS_S_CREDENTIALS_EXPIRED 11 expired credentials detected GSS_S_CONTEXT_EXPIRED 12 specified security context expired GSS_S_FAILURE 13 failure, unspecified at GSS-API level GSS_S_BAD_QOP 14 unsupported QOP value GSS_S_UNAUTHORIZED 15 the operation is forbidden by local security policy GSS_S_UNAVAILABLE 16 the operation or option is not available IDUP_S_BAD_TARG_INFO 17 all target information is invalid or unsuitable for IDU protection. IDUP_S_BAD_DOA_KEY 18 DOA key has expired or been revoked IDUP_S_BAD_KE_KEY 19 key used for key establishment between originator and target has expired or been revoked. IDUP_S_BAD_ENC_IDU 20 encrypted IDU is defective/invalid IDUP_S_EVIDENCE_TOKEN_INCOMPLETE 21 there is not enough info. in evidence_token for verification IDUP_S_SERV_VERIF_INFO_NEEDED 22 the Service_Verification_Info parameter bundle is required IDUP_S_SERVICE_UNAVAIL 23 mechanism does not support requested service IDUP_S_REQ_TIME_SERVICE_UNAVAIL 24 the time service requested in not available in this environment IDUP_S_NO_ENV 25 no environment recognized for env_handle IDUP_S_NO_MATCH 26 evidence check and token do not match IDUP_S_UNKNOWN_OPER_ID 27 requested operation id. is unsupported Klump, Thakkar 21 Expires: November 1, 1997 Table 3 - Supplementary Status Bits Name Bit Number Meaning (LSB) GSS_S_CONTINUE_NEEDED 0 continuation call to routine required GSS_S_DUPLICATE_TOKEN 1 NOT APPLICABLE TO IDUP GSS_S_OLD_TOKEN 2 NOT APPLICABLE TO IDUP GSS_S_UNSEQ_TOKEN 3 NOT APPLICABLE TO IDUP GSS_S_GAP_TOKEN 4 NOT APPLICABLE TO IDUP IDUP_S_ENCAPSULATION_UNAVAIL 5 encapsulation of M-IDU into prot_token is not supported IDUP_S_MORE_PIDU_NEEDED 6 more prot_token data is needed for IDUP_Start_Unprotect() IDUP_S_MORE_DATA_NEEDED 7 more data is needed for protection or unprotection (MSB) The routine documentation also uses the name GSS_S_COMPLETE, which is a zero value, to indicate an absence of any API errors or supplementary information bits. All GSS_S_xxx and IDUP_S_xxx symbols equate to complete OM_uint32 status codes, rather than to bitfield values. For example, the actual value of the symbol GSS_S_BAD_NAMETYPE (value 4 in the routine error field) is 4 << 16. The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and GSS_SUPPLEMENTARY_INFO() are provided, each of which takes an IDUP-GSS status code and removes all but the relevant field. For example, the value obtained by applying GSS_ROUTINE_ERROR to a status code removes the calling errors and supplementary info fields, leaving only the routine errors field. The values delivered by these macros may be directly compared with a GSS_S_xxx symbol of the appropriate type. The macro GSS_ERROR() is also provided, which when applied to a IDUP-GSS status code returns a non-zero value if the status code indicated a calling or routine error, and a zero value otherwise. An IDUP-GSS-API implementation may choose to signal calling errors in a platform-specific manner instead of, or in addition to the routine value; routines should return routine errors and supplementary info via routine status values only. 2.1.10.2. Mechanism-specific status codes IDUP-GSS-API routines return a minor_status parameter, which is used to indicate specialized errors from the underlying security mechanism. This parameter may contain a single mechanism-specific error, indicated by a OM_uint32 value. The minor_status parameter will always be set by a IDUP-GSS-API routine, even if it returns a calling error or one of the generic API errors indicated above as fatal, although other output parameters remain unset in such cases. However, output parameters that are expected to return pointers to storage allocated by a routine must always set by the routine, even in the event of an error, although in such cases the IDUP-GSS-API routine may elect to set the returned parameter value to NULL to indicate that no storage was actually allocated. Any length field associated with such pointers (as in a gss_buffer_desc structure) should also be set to zero in such cases. Klump, Thakkar 22 Expires: November 1, 1997 The GSS status code GSS_S_FAILURE is used to indicate that the underlying mechanism detected an error for which no specific IDUP-GSS status code is defined. The mechanism status code will provide more details about the error. 2.1.11. Names A name is used to identify a person or entity. IDUP-GSS-API authenticates the relationship between a name and the entity claiming the name. Two distinct representations are defined for names: (a) A printable form, for presentation to a user (b) An internal form, for presentation at the API The syntax of a printable name is defined by the IDUP-GSS-API implementation, and may be dependent on local system configuration, or on individual user preference. The internal form provides a canonical representation of the name that is independent of configuration. A given IDUP-GSS-API implementation may support names drawn from multiple namespaces. In such an implementation, the internal form of the name must include fields that identify the namespace from which the name is drawn. The namespace from which a printable name is drawn is specified by an accompanying object identifier. Routines (gss_import_name and gss_display_name) are provided to convert names between their printable representations and the gss_name_t type. The gss_import_name routine may support multiple syntaxes for each supported namespace, allowing users the freedom to choose a preferred name representation. The gss_display_name routine should use an implementation-chosen preferred syntax for each supported name-type. The gss_compare_names routine compares internal-form names. This routine removes the need for the application program to understand the syntaxes of the various printable names that a given IDUP-GSS-API implementation may support. Routines that return gss_name_t values allocate storage for them. The provided gss_release_name procedure frees the storage associated with a name. Certain IDUP-GSS-API procedures take parameters of the type idup_name_set. This type represents one or more names. A idup_name_set object has the following structure: typedef struct idup_name_set_desc_struct { int count; gss_name_t elements; } idup_name_set_desc, *idup_name_set; 2.1.12. Optional parameters Various parameters are described as optional. This means that they follow a convention whereby the calling application may request a default value. The following conventions are used for omitted parameters; they apply only to those parameters explicity documented as optional. Klump, Thakkar 23 Expires: November 1, 1997 2.1.12.1. gss_buffer_t types Specify GSS_C_NO_BUFFER as a value. For an input parameter this requests default behavior, while for an output parameter it Indicates that the application does not require the information that would be returned in it. 2.1.12.2. Integer types (input) Individual parameter documentation lists values to be used to indicate default actions. 2.1.12.3. Integer types (output) Specify NULL as the value for the pointer. 2.1.12.4. Pointer types Specify NULL as the value. 2.1.12.5. Object IDs Specify GSS_C_NULL_OID as the value. 2.1.12.6. Object ID Sets Specify GSS_C_NULL_OID_SET as the value. 2.1.12.7. Parameter Bundles Specify NULL as the value. 2.1.12.8. Credentials Specify GSS_C_NO_CREDENTIAL to use the default credential handle. 2.1.12.9. Environments Specify IDUP_C_NO_ENV to use the default environment handle. Klump, Thakkar 24 Expires: November 1, 1997 3. IDUP-GSS-API routine descriptions 3.1 Credential Management Calls Credential management in IDUP-GSS-API is to be understood and used as described in GSS-API [RFC-1508 and RFC-1509]. The calls gss_acquire_cred(), gss_release_cred() and gss_inquire_cred() are unchanged. 3.2 Environment-level Calls The set of calls described in this section are used in place of the calls gss_init_sec_context(), gss_accept_sec_context(), gss_delete_sec_context(), gss_process_context_token() and gss_context_time(), which are specified in [RFC-1508 and RFC-1509]. Klump, Thakkar 25 Expires: November 1, 1997 3.2.1. IDUP_Establish_env OM_uint32 idup_establish_env ( gss_cred_id_t claimant_cred_handle; gss_OID req_mech_type; gss_OID req_policy; time_t policy_time; gss_OID_set req_services; OM_uint32* minor_status; idup_env_id_t* env_handle; gss_OID* actual_mech_type; gss_OID* actual_policy; time_t* actual_policy_time; gss_OID_set ret_services) Purpose: Called by the application to establish a security environment. Parameters: claimant_cred_handle gss_cred_id_t, read, optional Handle for credentials claimed. GSS_C_NO_CREDENTIAL parameter specifies "use default". req_mech_type OID, read, optional Object ID of desired mechanism. GSS_C_NULL_OID parameter specifies "use default". req_policy OID, read, optional Object ID of desired policy. policy_time time_t, read The security policy rules available at the specified time. NULL parameter specifies "use default". req_services set of OID, read Set of Object ID which request that the environment support specific services. The OIDs available are: PER_CONF perform data confidentiality PER_DOA perform data origin authentication with data integrity PER_POO perform non-repudiable "proof of origin" PER_POD perform non-repudiable "proof of delivery" REC_CONF receive data confidentiality REC_DOA receive/verify DOA with data integrity REC_POO receive/verify "proof of origin" REC_POD receive/verify "proof of delivery" TTIME trusted time available UTIME untrusted time available. Klump, Thakkar 26 Expires: November 1, 1997 minor_status integer, modify Mechanism specific status code. env_handle idup_env_id_t, modify Environment handle for new environment. actual_mech_type OID, modify Actual mechanism used. Always indicated, never NULL. actual_policy OID, modify Always indicated, never NULL. actual_policy_time time_t, modify Actual time at which the above policy rules came into effect. ret_services set of OID, modify Not all services requested in req_services may be available in all underlying mech_types. The set of OID returned indicates services supported in the environment. The value of this parameter is undefined unless the routine returns GSS_S_COMPLETE. Function value: GSS status code: GSS_S_COMPLETE Indicates that environment-level information was successfully initialized, and that IDU / P-IDU processing can begin on the newly-established environment (along with evidence generation and verification, if supported). GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed on the credential structure referenced by claimant_cred_handle failed, preventing further processing from being performed using that credential structure. GSS_S_NO_CRED Indicates that no environment was established, either because the input cred_handle is invalid or because the caller lacks authorization to access the referenced credentials. GSS_S_CREDENTIALS_EXPIRED Indicates that the credentials provided through the input claimant_cred_handle argument are no longer valid, so environment establishment cannot be completed. GSS_S_BAD_MECH Indicates that a mech_type unsupported by the IDUP_GSS-API implementation type was requested, causing the environment establishment operation to fail. Klump, Thakkar 27 Expires: November 1, 1997 GSS_S_FAILURE Indicates that environment setup could not be accomplished for reasons unspecified at the IDUP-GSS-API level, and that no interface-defined recovery action is available. Failure, See minor_status for more information. Klump, Thakkar 28 Expires: November 1, 1997 3.2.2 idup_abolish_env OM_uint32 idup_abolish_env ( idup_env_id_t* env_handle, OM_uint32 * minor_status) Purpose: This call is made to flush environment-specific information. (Once an environment is established, cached credential and environment-related information is expected to be retained until an idup_abolish_env() call is made or until the credential lifetime expires.) Attempts to perform IDU processing on a deleted environment will result in error returns. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment to abolish. minor_status integer, modify Mechanism specific status code. Function value: GSS status code: GSS_S_COMPLETE Indicates that the environment was recognized and that relevant environment- specific information was flushed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided, so no deletion was performed. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS-API level. Failure, see minor_status for more information. Klump, Thakkar 29 Expires: November 1, 1997 3.2.3 idup_inquire_env OM_uint32 idup_inquire_env ( idup_env_id_t env_handle, OM_uint32* minor_status, gss_OID* mech_type, gss_OID* policy, time_t* policy_time, gss_OID_set* ret_services) Purpose: This call is used to extract information describing characteristics of the security environment. Parameters: env_handle idup_env_id_t, read, optional Environment handle identifying environment used. minor_status integer, modify Mechanism specific status code. mech_type OID, modify, optional The mechanism supporting this security environment. policy OID, modify The policy used in this environment. policy_time time_t, modify Time at which the above policy rules came into effect. ret_services set of OID, modify The set of OID returned indicates services supported in the environment. OIDs available are: PER_CONF perform data confidentiality PER_DOA perform data origin authentication with data integrity PER_POO perform non-repudiable "proof of origin" PER_POD perform non-repudiable "proof of delivery" REC_CONF receive data confidentiality REC_DOA receive/verify DOA with data integrity REC_POO receive/verify "proof of origin" REC_POD receive/verify "proof of delivery" TTIME trusted time available UTIME untrusted time available. Klump, Thakkar 30 Expires: November 1, 1997 Function value: GSS status code: GSS_S_COMPLETE Indicates that the referenced environment is valid and that src_name, lifetime_rec, mech_type, and ret_flags return values describe the corresponding characteristics of the environment. GSS_S_CREDENTIALS_EXPIRED Indicates that the credentials provided through the input claimant_cred_handle argument are no longer valid, so environment establishment cannot be completed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the input env_handle provided. Return values other than major_status and minor_status are undefined. GSS_S_FAILURE Indicates that the requested operation failed for reasons unspecified at the IDUP-GSS-API level. Return values other than major_status and minor_status are undefined. Klump, Thakkar 31 Expires: November 1, 1997 3.3 Per-IDU Calls This group of calls is performs IDU protection processing on an established IDUP environment. Some of these calls may block pending network interactions (depending on the underlying mechanism in use). Either the data unit's protector or recipient may invoke these calls. The two sets of members of this group form a pair; the output from the protection set is properly the input to the unprotection set. The IDUP-SE group of calls forms a simplified API with access only to the services of signing and encryption. The IDUP-EV group of calls forms a simplified API with access only to the services to do with data integrity and non-repudiation. 3.3.1. The IDUP-SE Calls This section lays out the simplified IDUP-SE interface for signing and encryption services. Klump, Thakkar 32 Expires: November 1, 1997 3.3.1.1. idup_se_singlebuffer_protect OM_uint32 idup_se_singlebuffer_protect ( idup_env_id_t env_handle, IDUP_Protect_Options Protect_Options, IDUP_Target_Info Target_Info, gss_buffer_t idu_buffer, OM_uint32* minor_status, gss_buffer_t pidu_buffer, gss_buffer_t sig_token) Purpose: Using the security environment referenced by env_handle, encrypt and/or sign the supplied IDU. If "clear signing" is performed, the signature will be returned in sig_token and pidu_buffer will be empty. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. Protect_Options IDUP_Protect_Options, read The options desired in protecting the IDU. Target_Info IDUP_Target_Info, read/modify The P-IDU recipients are specified using the idup_name_set parameter; invalid recipients get returned in the Bad_Target_Name parameter bundle. idu_buffer buffer, read Buffer holding the entire IDU. minor_status integer, modify Implementation specific status code. pidu_buffer buffer, opaque, modify Buffer containing the P-IDU unless clear-signing, in which case it will be empty. sig_token buffer, opaque, modify If clear-signing, the buffer containing the signature token. Otherwise, it will be empty. Klump, Thakkar 33 Expires: November 1, 1997 Function value: GSS status codes: GSS_S_COMPLETE Indicates that the protection Computation has been successfully completed and the result has been placed in pidu_buffer (or sig_token if clear-signing). GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_BAD_QOP Indicates that the provided QOP value is not recognized or supported for the environment. IDUP_S_BAD_TARG_INFO Indicates that all the information regarding the target(s) is invalid or is insufficient for the protection of an IDU, so the P-IDU cannot be created. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 34 Expires: November 1, 1997 3.3.1.2. idup_se_singlebuffer_unprotect IDUPEXPT32 OM_uint32 IDUPEXPT16 idup_se_singlebuffer_unprotect ( idup_env_id_t env_handle, gss_buffer_t pidu_buffer, gss_buffer_t sig_token, OM_uint32* minor_status, gss_buffer_t idu_buffer, IDUP_PIDU_Information PIDU_Information) Purpose: Using the security environment referenced by env_handle, decrypt and/or verify the supplied P-IDU and return the contained IDU along with all available PIDU_Information. If unprotecting a clear-signed message, the caller may specify the signature token in sig_token and a copy of the clear text in pidu_buffer, or he may append the clear text to the signature token and then pass the whole thing in pidu_buffer, leaving the sig_token empty. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. pidu_buffer buffer, read Buffer holding the P-IDU (or, if unprotecting a clear-signed message, the clear text possibly prepended with the signature token). sig_token buffer, read If clear-signing, may hold the signature token. minor_status integer, modify Mechanism specific status code. idu_buffer buffer, read File to hold the IDU PIDU_Information IDUP_PIDU_Information, modify Information about who originally protected the IDU and how. Function value: GSS status codes: GSS_S_COMPLETE Indicates that the unprotect computation was successful. Any IDU data will be returned in idu_buffer. Klump, Thakkar 35 Expires: November 1, 1997 GSS_S_CONTINUE_NEEDED Indicates that at least one of the buffers supplied is too small to hold the generated data. The application should continue calling this routine (until GSS_S_COMPLETE is returned) in order to get all remaining data. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 36 Expires: November 1, 1997 3.3.1.3. idup_se_multibuffer_startprotect OM_uint32 idup_se_multibuffer_startprotect ( idup_env_id_t env_handle, IDUP_Protect_Options Protect_Options, IDUP_Target_Info Target_Info, OM_uint32 FAR * minor_status, gss_buffer_t initial_pidu_buffer) Purpose: Using the security environment referenced by env_handle, initialize the data structures required to begin the process of signing and/or encrypting the IDU (which will be supplied in multiple buffers to the idup_process_buffer call). Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used Protect_Options IDUP_Protect_Options, read The options desired in protecting the IDU. Target_Info IDUP_Target_Info, read/modify The P-IDU recipients are specified using the idup_name_set parameter; invalid recipients get returned in the Bad_Target_Name parameter bundle. minor_status integer, modify Implementation specific status code. initial_pidu_buffer buffer, opaque, modify If it contains data at all, this buffer may contain the first part of the P-IDU unless clear-signing, in which case it may contain the first part of the signature token. Klump, Thakkar 37 Expires: November 1, 1997 Function value: GSS status codes: GSS_S_COMPLETE Indicates that the protection computation has been successfully completed. Any residual protected data will be returned in initial_pidu_buffer. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_BAD_QOP Indicates that the provided QOP value is not recognized or supported for the environment. IDUP_S_BAD_TARG_INFO Indicates that all the information regarding the target(s) is invalid or is insufficient for the protection of an IDU, so the P-IDU cannot be created. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 38 Expires: November 1, 1997 3.3.1.4. idup_se_multibuffer_endprotect OM_uint32 idup_se_multibuffer_endprotect ( idup_env_id_t env_handle, OM_uint32* minor_status, gss_buffer_t final_pidu_buffer, gss_buffer_t sig_token) Purpose: Using the security environment referenced by env_handle, complete the protection processing on the data and place the computed output in final_pidu_buffer and/or sig_token. Successful application of idup_se_multibuffer_endprotect() does not guarantee that unprotection can necessarily be performed successfully when the P-IDU arrives at the target (for example, it may be damaged in transit). Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. minor_status integer, modify Implementation specific status code. final_pidu_buffer buffer, opaque, modify Protected data unit buffer. Zero length if clear-signing, in which case sig_token is used. sig_token buffer, opaque, modify If clear-signing, the buffer containing the signature token. Otherwise, it will be empty. Klump, Thakkar 39 Expires: November 1, 1997 Function value: GSS status codes: GSS_S_COMPLETE Indicates that the protection computation has been successfully completed and the result has been placed in final_pidu_buffer (or sig_token if clear-signing). GSS_CONTINUE_NEEDED Indicates that at least one of the buffers supplied is too small to hold the generated data. The application should continue calling this routine (until GSS_S_COMPLETE is returned) in order to get all remaining data. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 40 Expires: November 1, 1997 3.3.1.5. idup_se_multibuffer_startunprotect OM_uint32 idup_se_multibuffer_startunprotect ( idup_env_id_t env_handle, gss_buffer_t initial_pidu_buffer, int sign_qop_alg_in, gss_buffer_t sig_token, OM_uint32* minor_status, IDUP_PIDU_Information PIDU_Information, gss_buffer_t initial_idu_buffer) Purpose: Using the security environment referenced by env_handle, initialize the data structures required to begin the process of decrypting and/or verifying the P-IDU (which will be supplied in multiple buffers to the Process_Buffer call). Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. initial_pidu_buffer buffer, read If the protected data was clear- signed, buffer containing either the signature token and the first part of the clear text, or just the first part of the clear text. Otherwise, buffer containing the first part of P-IDU. sign_qop_alg_in integer, read The signature algorithm used if the P-IDU was clear-signed and the application has prior knowledge of the algorithm. Cannot be left blank if the P-IDU was clear-signed and the sig_token is left unspecified. sig_token buffer, opaque, read If clear-signing and the signature token does not begin the initial_pidu_buffer, this parameter contains the signature token. Otherwise, it must be empty. minor_status integer, modify Implementation specific status code. PIDU_Information IDUP_PIDU_Information, modify Any available information about the P-IDU initial_idu_buffer buffer, modify Initial (possibly empty) part of IDU that came from the initial_pidu_buffer. Klump, Thakkar 41 Expires: November 1, 1997 Function value: GSS status codes: GSS_S_COMPLETE Indicates that the unprotect computation was successful. Any residual IDU data will be returned in initial_idu_buffer. IDUP_S_MORE_DATA_NEEDED Indicates that not enough data was present in the initial_pidu_buffer to complete the call successfully. The application should continue calling this routine (until GSS_S_COMPLETE is returned) with further blocks of the P-IDU in the initial_pidu_buffer. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_BAD_QOP Indicates that the provided QOP value is not recognized or supported for the environment. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 42 Expires: November 1, 1997 3.3.1.6. idup_se_multibuffer_endunprotect OM_uint32 idup_se_multibuffer_endunprotect ( idup_env_id_t env_handle, gss_buffer_t sig_token, OM_uint32* minor_status, IDUP_PIDU_Information PIDU_Information, gss_buffer_t final_idu_buffer) Purpose: Using the security environment referenced by env_handle, complete the decryption and/or verification processing on the data and place any residual output in final_idu_buffer. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. sig_token buffer, opaque, read If clear-signing and the signature token does was not available at the start of the protection sequence, buffer contains the signature token. minor_status integer, modify Implementation specific status code. PIDU_Information IDUP_PIDU_Information, modify Any available information about the P-IDU. final_idu_buffer buffer, modify Unprotected data unit buffer. Klump, Thakkar 43 Expires: November 1, 1997 Function value: GSS status codes: GSS_S_COMPLETE Indicates that the unprotect computation was successful. Any IDU data will be returned in final_idu_buffer. GSS_S_CONTINUE_NEEDED Indicates that at least one of the buffers supplied is too small to hold the generated data. The application should continue calling this routine (until GSS_S_COMPLETE is returned) in order to get all remaining data. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 44 Expires: November 1, 1997 3.3.1.7. idup_se_process_buffer OM_uint32 idup_se_process_buffer ( idup_env_id_t env_handle, gss_buffer_t input_buffer, OM_uint32* minor_status, gss_buffer_t output_buffer) Purpose: Using the security environment referenced by env_handle, continue the processing on the data in input_buffer and, if it is available, put any resulting output data in output_buffer. The application calls this routine over and over again with new buffers of data until it has processed all the data buffers of the IDU/P-IDU. It then calls the appropriate idup_end() call to complete the processing. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. input_buffer buffer, read Contains current part of input IDU/P-IDU. minor_status integer, modify Implementation specific status code. output_buffer buffer, modify Holds new part of IDU/P-IDU that results from the input_buffer. Function value: GSS status codes: GSS_S_COMPLETE Indicates that the unprotect computation was successful. Any residual IDU data will be returned in final_idu_buffer. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 45 Expires: November 1, 1997 3.3.2. The IDUP-EV Calls This section lays out the simplified IDUP-EV interface for evidence generation and verification services. 3.3.2.1. idup_ev_singlebuffer_generate OM_uint32 idup_ev_singlebuffer_generate ( idup_env_id_t env_handle, IDUP_nr_operation nr_operation, IDUP_Nr_Options Nr_Options, gss_buffer_t idu_buffer, int form_complete_evidence, int include_data_in_token, IDUP_Request_Features Request_Features, OM_uint32* minor_status, gss_buffer_t token, gss_buffer_t evidence_check) Purpose: This operation generates a non-repudiation token associated with the data passed in an input buffer. The nr_operation parameter can specify two kinds of operation: (a) generate a token including either: (i) an evidence only, (ii) an evidence request only, or (iii) an evidence and a request for evidence or, (b) generate for some recipients a response token that includes an evidence generated as a response to a request. In this case, the idu_buffer parameter contains the received request token. The call will ignore the include_data_in_token boolean (since the output will always be a single token) and the Request_Features parameter (to avoid piggybacking). If form_complete_evidence is TRUE, the call will attempt to generate complete evidence. If it fails to do so, the application can call idup_form_complete_pidu. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. nr_operation IDUP_nr_operation, read Whether this evidence is to be generated in response to a request or not. Nr_Options IDUP_Nr_Options, read The options desired in generating this evidence. idu_buffer buffer, read The data against which to create the evidence, if doing so. Klump, Thakkar 46 Expires: November 1, 1997 form_complete_evidence integer, read Whether the application should attempt to form a complete evidence. include_data_in_token integer, read Whether the application should include the data in the idu_buffer. Request_Features IDUP_Request_Features, read The features the application wants in the request for evidence minor_status integer, modify Implementation specific status code. token buffer, modify The output token with evidence if requested, or the request if not evidence_check buffer, modify If evidence is requested, data to be used to verify the requested token(s) when received Function value: GSS status codes: GSS_S_COMPLETE Indicates that the generation computation has been successfully completed and the result has been placed in token. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. IDUP_S_BAD_TARG_INFO Indicates that all the information regarding the target(s) is invalid or is insufficient for the protection of an IDU, so the P-IDU cannot be created. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 47 Expires: November 1, 1997 3.3.2.2. idup_ev_singlebuffer_verify OM_uint32 idup_ev_singlebuffer_verify ( idup_env_id_t env_handle, gss_buffer_t token, gss_buffer_t idu_buffer, gss_buffer_t evidence_check, OM_uint32* minor_status, IDUP_Nr_Options Nr_Options, IDUP_Originator_Information Originator_Information, IDUP_Request_Features Request_Features, time_t* trusted_time_stamping_time, time_t* complete_evidence_before, time_t* complete_evidence_after, gss_buffer_t idu_buffer) Purpose: This call verifies the validity and discloses the content of a non-repudiation token. If the application has received the non-repudiation token as a response to a request it made previously, the application must supply the evidence check it received as a parameter when it generated the original request. Output parameters give guidance about the time or times at which to call idup_form_complete_pidu. If the time in complete_evidence_before is earlier than that in complete_evidence_after, the application will have to call idup_form_complete_pidu twice. Because keys can be revoked or declared compromised, the return from idup_verify_evidence cannot always be a definitive valid or invalid. Sometimes idup_verify_evidence may return conditionally valid, depending on the active security policy. The call will return IDUP_S_INCOMPLETE if: - the interval during which the generator of the evidence may permissibly declare his key invalid has not yet expired (and therefore it is possible that the evidence may be declared invalid in the future), or - trusted time is required to verify the token, and the time obtained from the token is untrusted. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. token buffer, read The input token to verify. idu_buffer buffer, read The data for which the evidence token was generated, if not present in the token. Klump, Thakkar 48 Expires: November 1, 1997 evidence_check buffer, read If token is a response to a request for evidence, data to be used to verify the received token. minor_status integer, modify Implementation specific status code. Nr_Options IDUP_Nr_Options, modify The options used in generating this evidence. Originator_Information IDUP_Originator_Information Who created the token and when. Request_Features IDUP_Request_Features, read The features the application used in the original request for evidence. trusted_time_stamping_time time_t, modify For information only. complete_evidence_before time_t, modify If the call returns IDUP_S_INCOMPLETE, the application should call idup_form_complete_pidu with the same token before this time. complete_evidence_after time_t, modify If the call returns IDUP_S_INCOMPLETE, the application should call idup_form_complete_pidu with the same token after this time. idu_buffer buffer, modify The IDU against which the evidence was generated, if present within the token. Function value: GSS status codes: GSS_S_COMPLETE Indicates that the verification computation has been successfully completed. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. Klump, Thakkar 49 Expires: November 1, 1997 IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. IDUP_S_INCOMPLETE Indicates that the token is conditionally valid, depending on the active security policy. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 50 Expires: November 1, 1997 3.3.2.3. idup_ev_multibuffer_startgenerate OM_uint32 idup_ev_multibuffer_startgenerate ( idup_env_id_t env_handle, IDUP_nr_operation nr_operation, IDUP_Nr_Options Nr_Options, int form_complete_evidence, int include_data_in_token, IDUP_Request_Features Request_Features, OM_uint32* minor_status, gss_buffer_t initial_pidu_buffer) Purpose: Using the security environment referenced by env_handle, initialize the data structures required to begin generating a token. The IDU will follow in multiple buffers to the idup_ev_process_buffer call. The Nr_Operation parameter can specify one of two kinds of operations: a) generating a token that includes either an evidence, an evidence request, or both; or, b) generating for some recipients a token that includes an evidence generated as a response to a request. In this case, the input buffer in subsequent calls to idup_ev_process_buffer will hold the received token. Furthermore, the call ignores the include_data_in_token boolean (since the output will always be contained in a single token) and the Request_Features (to keep things simple and avoid piggy-backing). If form_complete_evidence is TRUE, the call will attempt to generate complete evidence; this may succeed or fail. If it fails, the it can call idup_form_complete_pidu. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. nr_operation IDUP_nr_operation, read Whether this evidence is to be generated in response to a request or not. Nr_Options IDUP_Nr_Options, read The options desired in generating this evidence. form_complete_evidence integer, read Whether the application should attempt to form a complete evidence. include_data_in_token integer, read Whether the application should include the data in the idu_buffer. Klump, Thakkar 51 Expires: November 1, 1997 Request_Features IDUP_Request_Features, read The features the application wants in the request for evidence. minor_status integer, modify Implementation specific status code. initial_pidu_buffer buffer, modify May contain the start of the token under construction, depending on the underlying mechanism. Function value: GSS status codes: GSS_S_COMPLETE Indicates that the generation computation has been successfully completed and the result has been placed in token. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. IDUP_S_BAD_TARG_INFO Indicates that all the information regarding the target(s) is invalid or is insufficient for the protection of an IDU, so the P-IDU cannot be created. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 52 Expires: November 1, 1997 3.3.2.4. idup_ev_multibuffer_endgenerate OM_uint32 idup_ev_multibuffer_endgenerate ( idup_env_id_t env_handle, OM_uint32* minor_status, gss_buffer_t final_pidu, gss_buffer_t token, gss_buffer_t evidence_check) Purpose: Using the security environment referenced by env_handle, provide the requested token (if encapsulation is off) or the final P-IDU (if encapsulation is on). Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. minor_status integer, modify Implementation specific status code. final_pidu buffer, modify If encapsulation is on, the final P-IDU; otherwise, this parameter will be empty. token buffer, modify The output token with evidence if requested, or the request if not. evidence_check buffer, modify If evidence is requested, data to be used to verify the requested token(s) when received. Klump, Thakkar 53 Expires: November 1, 1997 Function value: GSS status codes: GSS_S_COMPLETE Indicates that the generation computation has been successfully completed and the result has been placed in token. GSS_S_CONTINUE_NEEDED Indicates that at least one of the buffers supplied is too small to hold the generated data. The application should continue calling this routine (until GSS_S_COMPLETE is returned) in order to get all remaining data. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_MORE_DATA_NEEDED Indicates that not enough data was present in the final_pidu_buffer to complete the call successfully. The application should continue calling this routine (until GSS_S_COMPLETE is returned) with further blocks of the P-IDU in the final_pidu_buffer. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 54 Expires: November 1, 1997 3.3.2.5. idup_ev_multibuffer_startverify OM_uint32 idup_ev_multibuffer_startverify ( idup_env_id_t env_handle, gss_buffer_t token, gss_buffer_t evidence_check, OM_uint32* minor_status) Purpose: Using the security environment referenced by env_handle, initialize the data structures required to begin the process of verifying the token. The application will supplie the P-IDU in multiple buffers to the idup_ev_process_buffer call. If the application has received the non-repudiation token as a response to a request it made previously, the application must supply the evidence check it received as a parameter when it generated the original request. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. token buffer, read The input token to verify. evidence_check buffer, read If token is a response to a request for evidence, data to be used to verify the received token. minor_status integer, modify Implementation specific status code. Klump, Thakkar 55 Expires: November 1, 1997 Function value: GSS status codes: GSS_S_COMPLETE Indicates that the verification computation has been successfully completed. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_MORE_DATA_NEEDED Indicates that not enough data was present in the token parameter to complete the call successfully. The application should continue calling this routine (until GSS_S_COMPLETE is returned) with further blocks of the token. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 56 Expires: November 1, 1997 3.3.2.6. idup_ev_multibuffer_endverify OM_uint32 idup_ev_multibuffer_endverify ( idup_env_id_t env_handle, OM_uint32* minor_status, IDUP_Nr_Options Nr_Options, IDUP_Originator_Information Originator_Information, IDUP_Request_Features Request_Features, time_t* trusted_time_stamping_time, time_t* complete_evidence_before, time_t* complete_evidence_after, gss_buffer_t idu_buffer) Purpose: Using the security environment referenced by env_handle, complete the verification processing on the data and provide verified output parameters to the caller when the major status code is GSS_S_COMPLETE or IDUP_S_INCOMPLETE. Output parameters give guidance about the time or times at which to call idup_form_complete_pidu. If the time in complete_evidence_before is earlier than that in complete_evidence_after, the application will have to call idup_form_complete_pidu twice. Because keys can be revoked or declared compromised, the return from idup_verify_evidence cannot always be a definitive valid or invalid. Sometimes idup_verify_evidence may return conditionally valid, depending on the active security policy. The call will return IDUP_S_INCOMPLETE if: - the interval during which the generator of the evidence may permissibly declare his key invalid has not yet expired (and therefore it is possible that the evidence may be declared invalid in the future), or - trusted time is required to verify the token, and the time obtained from the token is untrusted. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. minor_status integer, modify Implementation specific status code. Nr_Options IDUP_Nr_Options, modify The options used in generating this evidence. Originator_Information IDUP_Originator_Information Who created the token and when. Klump, Thakkar 57 Expires: November 1, 1997 Request_Features IDUP_Request_Features, read The features the application used in the original request for evidence. trusted_time_stamping_time time_t, modify For information only. complete_evidence_before time_t, modify If the call returns IDUP_S_INCOMPLETE, the application should call idup_form_complete_pidu with the same token before this time. complete_evidence_after time_t, modify If the call returns IDUP_S_INCOMPLETE, the application should call idup_form_complete_pidu with the same token after this time. idu_buffer buffer, modify The IDU against which the evidence was generated, if present within the token. Function value: GSS status codes: GSS_S_COMPLETE Indicates that the verification computation has been successfully completed. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. IDUP_S_INCOMPLETE Indicates that the token is conditionally valid, depending on the active security policy. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 58 Expires: November 1, 1997 3.3.2.7. idup_ev_process_buffer OM_uint32 idup_ev_process_buffer ( idup_env_id_t env_handle, gss_buffer_t input_buffer, OM_uint32* minor_status, gss_buffer_t output_buffer) Purpose: Using the security environment referenced by env_handle, continue the processing on the data in input_buffer and, if it is available, put any resulting output data in the output_buffer. The application calls this routine over and over again with new buffers of data until it has processed all the data buffers of the IDU/P-IDU. It then calls the appropriate idup_end() call to complete the processing. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. input_buffer buffer, read Contains current part of input IDU/P-IDU. minor_status integer, modify Implementation specific status code. output_buffer buffer, modify Holds new part of IDU/P-IDU that results from the input_buffer. Function value: GSS status codes: GSS_S_COMPLETE Indicates that the verification computation has been successfully completed. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 59 Expires: November 1, 1997 3.3.3. The General IDUP-GSS-API Calls This section lays out the general IDUP-GSS-API calls. Protocols and applications that require confidentiality, integrity and non-repudiation services need this general interface; for many others, the IDUP-SE or IDUP-EV interface should suffice. 3.3.3.1. idup_start_protect OM_uint32 idup_start_protect ( idup_env_id_t env_handle, IDUP_Idu_Information Idu_Information, int encapsulation_request, IDUP_Special_Conditions Special_Conditions, gss_buffer_t single_idu_buffer, IDUP_Target_Info Target_Info, IDUP_Services_To_Perform Services_to_Perform, OM_uint32* minor_status, IDUP_Mech_Specific_Info Mech_Specific_Info, gss_buffer_t midu_buffer, gss_buffer_t pidu_buffer) Purpose: Using the security environment referenced by env_handle, initialize the data structures required to begin the process of protecting the IDU buffers. Parameters: env_handle idup_env_id_t, read Identifies the environment in which the data unit will be protected. Idu_Information IDUP_Idu_Information, read A collection of information (such as encapsulated content type, content description and sensitivity) of the IDU to be protected. encapsulation_request integer, read TRUE - request to encapsulate IDU FALSE - do not encapsulate IDU. Special_Conditions IDUP_Special_Conditions, read These conditions control the (un)protection procedure. For those mechanisms which allow for or require multiple stages of processing, each producing a different aspect of protection for the data data unit, the parameter bundle contains a prot_oper_id, parameter which specifies what stage the application currently is requesting. The parameter bundle also includes flags to request use of trusted time and use of untrusted time. Klump, Thakkar 60 Expires: November 1, 1997 single_idu_buffer gss_buffer_t, read Non-zero length for this buffer means that idup_protect() and idup_end_protect() will not be called (i.e., the entire IDU is contained in this buffer). Target_Info IDUP_Target_Info, read/modify The P-IDU recipients are specified in the idup_name_set parameter; invalid recipients get returned in the Bad_Target_Name parameter bundle. Services_to_Perform IDUP_Services_To_Perform, read/modify Protection Services requested. Each service is able to return minor status code to the calling application, if necessary. minor_status integer, modify Mechanism specific status code. Mech_Specific_Info IDUP_Mech_Specific_Info, read/modify A collection of information defined by (and specific to) the underlying mechanism. NULL selects the mechanism- defined default value for each parameter. midu_buffer gss_buffer_t, modify Zero length if encapsulation_request is TRUE or if single_idu_buffer has zero length. pidu_buffer gss_buffer_t, modify Zero length if encapsulation_request is FALSE or if single_idu_buffer has zero length. Function value: GSS status code: GSS_S_COMPLETE Indicates that the protection process can begin (or has completed, if single_idu_buffer has non-zero length). GSS_S_CONTINUE NEEDED Indicates that at least one of the buffers supplied is too small to hold the generated data. The application should continue calling this routine (until GSS_S_COMPLETE is returned) in order to get all remaining data. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. Klump, Thakkar 61 Expires: November 1, 1997 IDUP_S_ENCAPSULATION_UNAVAIL Indicates that the underlying mechanism does not support encapsulation of the M-IDU into the token. IDUP_S_MORE_DATA_NEEDED Indicates whether protection is completed by this call or by IDUP_End_Protect() (e.g., whether more data buffers are required for evidence generation). IDUP_S_SERVICE_UNAVAIL Indicates that the underlying mechanism does not support the service requested. IDUP_S_REQ_TIME_SERVICE_UNAVAIL Indicates that the time service requested (TTIME or UTIME) is not available in the environment. IDUP_S_UNKNOWN_OPER_ID Indicates that the input prot_oper_id value is not recognized or supported in the underlying mechanism. GSS_S_BAD_QOP Indicates that the provided QOP value is not recognized or supported for the environment. IDUP_S_BAD_TARG_INFO Indicates that all the information regarding the target(s) is invalid or is insufficient for the protection of an IDU, so the P-IDU cannot be created. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 62 Expires: November 1, 1997 3.3.3.2. idup_protect OM_uint32 idup_protect ( idup_env_id_t env_handle, gss_buffer_t input_buffer, OM_uint32* minor_status, gss_buffer_t output_buffer) Purpose: Using the security environment referenced by env_handle, continue the protection processing on the data in input_buffer and, if the underlying mechanism defines this, put any resulting M-IDU data in output_buffer. The application calls this routine over and over again with new buffers of data until it has protected all the data buffers of the IDU. It then calls idup_end_protect() to complete the protecting process. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. input_buffer buffer, read IDU buffer. minor_status integer, modify Implementation specific status code. output_buffer buffer, opaque, modify Protected data unit buffer. Zero length if encapsulation_request was set to TRUE in idup_start_protect(). Function value: GSS status codes: GSS_S_COMPLETE Indicates that the input_buffer has successfully been included in the protection computation. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. GSS_S_FAILURE Indicates that the environment is recognized, but that the required operation could not be performed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 63 Expires: November 1, 1997 3.3.3.3. idup_end_protect OM_uint32 idup_end_protect ( idup_env_id_t env_handle, OM_uint32 * minor_status, IDUP_Services_To_Perform Services_to_Perform, gss_buffer_t final_midu_buffer, gss_buffer_t final_pidu_buffer) Purpose: Using the security environment referenced by env_handle, complete the protection processing on the data and place the computed output in final_pidu_buffer (or final_midu_buffer and the uncapsulated_token parameter for each Prot_Service). If a service was requested from one or more targets in idup_start_protect() - and if this is supported by underlying mechanism - Service_Verification_Info will hold whatever data is necessary for the mechanism to verify a service retuned by a target (unprotector) of the P-IDU. Successful application of idup_end_protect() does not guarantee that the corresponding unprotection set of functions can necessarily be performed successfully when the protected data unit arrives at the target (for example, it may be damaged in transit). Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. minor_status integer, modify Implementation specific status code. Services_to_Perform IDUP_Services_To_Perform Protection Services requested. Each service is able to return minor status code to the calling application, if necessary. final_midu_buffer buffer, opaque, modify Protected data unit buffer. Zero length if encapsulation_request was set to TRUE in IDUP_Start_Protect(), in which case final_pidu_buffer is used. final_pidu_buffer buffer, opaque, modify Protected data unit buffer. Zero length if encapsulation_request was set to FALSE in IDUP_Start_Protect(), in which case token and midu are used. Klump, Thakkar 64 Expires: November 1, 1997 Function value: GSS status codes: GSS_S_COMPLETE Indicates that the protection computation has been successfully completed and the result has been placed in prot_token. If defined by the underlying mechanism, final_midu_buffer will contain any residual M-IDU data. GSS_CONTINUE NEEDED Indicates that at least one of the buffers supplied is too small to hold the generated data. The application should continue calling this routine (until GSS_S_COMPLETE is returned) in order to get all remaining data. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 65 Expires: November 1, 1997 3.3.3.4. idup_start_unprotect OM_uint32 idup_start_unprotect( idup_env_id_t env_handle, gss_buffer_t single_pidu_buffer, gss_buffer_t partial_pidu_buffer, gss_buffer_t final_pidu_buffer, IDUP_Special_Conditions Special_Conditions, OM_uint32* minor_status, IDUP_Mech_Specific_Info Mech_Specific_Info, IDUP_Services_To_Receive Services_to_Receive, IDUP_Prot_Information Prot_Information, gss_buffer_t single_idu_buffer, gss_buffer_t initial_idu_buffer, IDUP_Service_Verification_Info Service_Verification_Info, gss_buffer_t service_verification_info_id) Purpose: Using the security environment referenced by env_handle, initialize the data structures required to begin the process of unprotecting the P-IDU. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. single_pidu_buffer buffer, read Non-zero length for this buffer means that IDUP_Unprotect() and IDUP_End_Unprotect() will not be called. (i.e., the entire P-IDU is contained in this buffer). partial_pidu_buffer buffer, read May be arbitarily-sized piece of the full P-IDU (if the application's buffer isn't large enough to hold the entire P-IDU), or may be service token (if encapsulation was not used). final_pidu_buffer buffer, read Final buffer must be passed in final_pidu_buffer rather than partial P-IDU buffer. Only one of single_pidu_buffer and partial(final)_pidu_buffer can have non zero length. Klump, Thakkar 66 Expires: November 1, 1997 Special_Conditions Special_Conditions, read These conditions control the unprotection procedure. For those mechanisms which allow or require multiple stages of processing, each producing a different aspect of unprotection for the P-IDU, the parameter bundle contains a prot_oper_id parameter that is used to specify which stage is currently being requested by the application. The parameter bundle also includes flags to request use of trusted time and use of untrusted time. minor_status integer, modify Implementation specific status code. Mech_Specific_Info IDUP_Mech_Specific_Info, read/modify A collection of information defined by (and specific to) the underlying mechanism. NULL selects the mechanism-defined default value for each parameter. Services_to_Receive IDUP_Services_To_Receive, read/modify This parameter bundle returns which services were applied to the P-IDU. Service_Verification_Info parameter bundle inside this parameter bundle must be input in order for service verification to proceed. Prot_Information IDUP_Prot_Information, modify Holds originator name, IDU information, time when protection was performed. single_idu_buffer buffer, modify If this buffer has non-zero length, then service receipt has been completed on the data in single_pidu_buffer. initial_idu_buffer buffer, modify Holds any data from partial(final)_pidu_buffer which has been decrypted/verified; remaining data will be returned by idup_unprotect and idup_end_unprotect as they are called with successive buffers of P-IDU. Service_Verification_Info IDUP_Service_Verification_Info, modify Used only if target is on "service_to" list in Unprot_Service. service_verification_info_id buffer, modify Used only if target is on "service_to" list in Unprot_Service. Klump, Thakkar 67 Expires: November 1, 1997 Function value: GSS status codes: GSS_S_COMPLETE Indicates that unprotection processing can begin (or has been completed, if single_idu_buffer has non-zero length). GSS_S_CONTINUE_NEEDED Indicates that at least one of the buffers supplied is too small to hold the generated data. The should continue calling this routine (until GSS_S_COMPLETE is returned) in order to get all remaining data. IDUP_S_MORE_PIDU_NEEDED Indicates that not enough of P-IDU has been input yet for the completion of idup_start_unprotect. The application should call this routine again with another buffer of P-IDU in partial_pidu_buffer. GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the received prot_token failed, preventing further processing from being performed with that token. IDUP_S_MORE_DATA_NEEDED Indicates whether unprotection is completed by this call or by idup_end_unprotect() (e.g., whether more data buffers are required for unprotection). GSS_DEFECTIVE_VERIF Indicates that consistency checks performed on the Service_Verification_Info failed, preventing further processing from being performed with that parameter. IDUP_S_NO_MATCH Indicates that Service_Verification_Info and the P-IDU to be verified do not match. IDUP_S_SERVICE_UNAVAIL Indicates that the underlying mechanism does not support the service requested. IDUP_S_REQ_TIME_SERVICE_UNAVAIL Indicates that the time service requested (TTIME or UTIME) is not available in the environment. IDUP_S_EVIDENCE_TOKEN_INCOMPLETE Indicates that mere information is needed in the P-IDU in order to verify it (this may, if specified by the underlying mechanism, be an indication that the token is incomplete and idup_form_complete_pidu needs to be called to complete it). Klump, Thakkar 68 Expires: November 1, 1997 IDUP_S_SERV_VERIF_INFO_NEEDED Indicates that the Service_Verification_Info parameter bundle must be input in order for service verification to proceed. The output parameter service_verification_info_id contains an identifier whch may be used by the calling application to locate the necessary information. GSS_S_CREDENTIALS_EXPIRED Indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. IDUP_S_UNKNOWN_OPER_ID Indicates that the input prot_oper_id value is not recognized or supported in the underlying mechanism. GSS_S_BAD_QOP Indicates that the qop_algs value specified in P-IDU for atleast one of the services is unavailable in the local mechanism, so processing cannot continue. GSS_S_BAD_SIG Indicates that the received P-IDU contains an incorrect integrity field (e.g., signature or MAC) for the data. IDUP_S_BAD_DOA_KEY Indicates that the key used to provide IDU data origin auth. / integ. has either expired or been revoked. IDUP_S_BAD_KE_KEY Indicates that the key used to establish a key for confidentiality purposes between originator and target has either expired or been revoked. IDUP_S_BAD_ENC_IDU Indicates that decryption of the received IDU cannot be completed because the encrypted IDU was invalid/defective (e.g., the final block was short or had incorrect padding). GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 69 Expires: November 1, 1997 3.3.3.5. idup_unprotect OM_uint32 idup_unprotect ( idup_env_id_t env_handle, gss_buffer_t input_buffer, OM_uint32* minor_status, gss_buffer_t output_buffer) Purpose: Using the security environment referenced by env_handle, complete the unprotect processing on the data and return the appropriate status code. If there is any residual IDU data, it will be returned in final_idu_buffer. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. input_buffer buffer, modify Protected data unit buffer. minor_status integer, modify Implementation specific status code. output_buffer buffer, modify Unprotected data unit buffer. Function values: GSS status codes: GSS_S_COMPLETE Indicates that the unprotect computation was successful. Any residual IDU data will be returned in final_idu_buffer. IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 70 Expires: November 1, 1997 3.3.3.6. idup_end_unprotect OM_uint32 idup_end_unprotect ( idup_env_id_t env_handle, OM_uint32* minor_status, IDUP_Prot_Information Prot_Information, IDUP_Services_To_Receive Services_to_Receive, gss_buffer_t final_idu_buffer, IDUP_Service_Verification_Info Service_Verification_Info, gss_buffer_t service_verification_info_id) Purpose: Using the security environment referenced by env_handle, complete the unprotection processing on the data and return the appropriate status code. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. minor_status integer, modify Implementation specific status code. Prot_Information IDUP_Prot_Information, modify Information about the way the IDU was originally protected. Services_to_Receive IDUP_Services_To_Receive, modify This parameter bundle returns which services were applied to the P-IDU. final_idu_buffer buffer, modify Unprotected data unit buffer. Service_Verification_Info IDUP_Service_Verification_Info, modify Used only if target is on "service_to" list in Unprot_Service. service_verification_info_id buffer, modify Used only if target is on "service_to" list in Unprot_Service. Klump, Thakkar 71 Expires: November 1, 1997 Function value: GSS status codes: GSS_S_COMPLETE Indicates that the unprotect computation was successful. Any residual IDU data will be returned in final_idu_buffer. GSS_S_CONTINUE_NEEDED Indicates that at least one of the buffers supplied is too small to hold the generated data. The application should continue calling this routine (until GSS_S_COMPLETE is returned) in order to get all remaining data. GSS_S_BAD_SIG Indicates that the received P-IDU contains an incorrect integrity field (e.g., signature or MAC) for the data. IDUP_S_BAD_DOA_KEY Indicates that the key used to provide IDU data origin auth. / integ. has either expired or been revoked. IDUP_S_BAD_KE_KEY Indicates that the key used to establish a key for confidentiality purposes between originator and target has either expired or been revoked. IDUP_S_BAD_ENC_IDU Indicates that decryption of the received IDU cannot be completed because the encrypted IDU was invalid/defective (e.g., the final block was short or had incorrect padding). IDUP_S_NO_ENV Indicates that no valid environment was recognized for the env_handle provided. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not performed for reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 72 Expires: November 1, 1997 3.4 Special Purpose Calls The special purpose calls described in this section have no analogue in GSS-API [RFC-1508, RFC-1509]. These calls are used to generate and verify evdence for non-repudiation purposes in the IDUP environment. These calls may not be supported by all underlying IDUP mechanisms or implementations. 3.4.1. idup_form_complete_pidu OM_uint32 idup_form_complete_pidu ( idup_env_id_t env_handle, gss_buffer_t single_pidu_buffer, gss_buffer_t partial_pidu_buffer, gss_buffer_t final_pidu_buffer, OM_uint32* minor_status, gss_buffer_t pidu_token_out, time_t* call_again_before, time_t* call_again_after, time_t* trusted_time_stamping_time) Purpose: Using the security environment referenced by env_handle, complete the generation of an evidence token for non-repudiation purposes and return the appropriate status value along with the completed token. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used. single_pidu_buffer buffer, opaque, read The full evidence token. partial_pidu_buffer buffer, opaque, read May be arbitary-sized piece of the full evidence token. final_pidu_buffer buffer, opaque, read Final buffer must be passed in final_evidence_buffer rather than partial evidence buffer. Only one of single_evidence_buffer and partial(final)_evidence_buffer can have non zero length. minor_status integer, modify Implementation specific status code. pidu_token_out buffer, modify the complete output evidence token. Klump, Thakkar 73 Expires: November 1, 1997 call_again_before time_t, modify If non-NULL and the call returns IDUP_S_INCOMPLETE, specifies the time before which the application should call this function to complete the token. call_again_after time_t, modify If non-NULL and the call returns IDUP_S_INCOMPLETE, specifies the time after which the application should call this function to complete the token. trusted_time_stamping_time time_t, modify For information only. Function value: GSS status codes: GSS_S_COMPLETE Indicates that evidence generation completed successfully. GSS_S_CONTINUE_NEEDED Indicates that the buffer supplied for evidence_token_out is too small to hold the generated data. The application should continue calling this routine (until GSS_S_COMPLETE is returned) in order to get all remaining data. IDUP_S_INCOMPLETE Indicates that the generation of the P-IDU is not yet complete. The application should call this function again before the time in call_again_before (if non-NULL) and/or after the time in call_again_after (if non-NULL). IDUP_S_SERVICE_UNAVAIL Indicates that the underlying mechanism does not support service requested. GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the evidence_token_in failed, preventing further processing from being performed with that token. GSS_S_FAILURE Indicates that the environment is recognized, but that the requested operation could not be performed reasons unspecified at the IDUP-GSS- API level. Klump, Thakkar 74 Expires: November 1, 1997 3.5 Support calls Support calls in IDUP-GSS-API are to be understood and used as described in GSS-API [RFC-1508 and RFC-1509]. The calls gss_display_status(), gss_indicate_mechs(), gss_compare_name(), gss_display_name(), gss_import_name(), gss_release_name(), gss_release_buffer(), gss_release_oid_set() are unchanged. 3.5.1 idup_acquire_cred_with_auth OM_uint32 idup_acquire_cred_with_auth ( gss_name_t desired_name, gss_buffer_t authenticator, OM_uint32 lifetime_req, gss_OID_set desired_mechs, gss_buffer_t cred_usage, OM_uint32* minor_status, gss_cred_id_t* output_cred_handle, gss_OID_set actual_mechs, OM_uint32* lifetime_rec) Purpose: This call is identical to the gss_acquire_cred call, with the exception of an authenticator parameter (typically a password, pass-phrase or PIN), which authenticates the caller claiming to be desired_name to the underlying GSS (or mechanism) code. Implementations that are able to authenticate the caller in some other way are encouraged to use the gss_acquire_cred call; implementations having no ther means available to them, or wishing explicitly to authenticate the caller when acquiring credentials, should use idup_acquire_cred_with_auth. Note that the return major status codes for this call are identical to those given for the gss_acquire_cred call. If the authentication fails, the call returns GSS_S_FAILURE with an appropriate minor_status code. Parameters: desired_name name, read The name of the user logging in. authenticator buffer, read An authentication for the user claiming to be desired_name. lifetime_req integer, read The desired lifetime of the requested credentials in in seconds; 0 for default. desired_mechs gss_OID_set, read The underlying security mechanisms desired. Klump, Thakkar 75 Expires: November 1, 1997 cred_usage buffer, read Desired usage of this set of credentials. minor_status integer, modify Implementation specific minor status code. output_cred_handle credential handle, modify Handle to the returned credentials. actual_mechs gss_OID_set, modify The actual set of security mechanisms underlying the credentials. lifetime_rec integer, modify Received credential lifetime, in seconds; possibly a reserved value for INDEFINITE. Function value: GSS status codes: As gss_acquire_cred. Klump, Thakkar 76 Expires: November 1, 1997 3.5.2 idup_parse_token OM_uint32 idup_parse_token ( gss_buffer_t input_token, OM_uint32* minor_status, gss_OID* mech_type) Purpose: IDUP_Parse_token is used to return to an application the attributes which correspond to a given input token. Parameters: input_token gss_buffer_t, read Input token from the protect call. minor_status integer, modify Implementation specific status code. mech_type OID, modify The mechanism that was used to create input_token. Function value: GSS status code: GSS_S_COMPLETE Indicates that the input_token could be parsed for all relevant fields. GSS_S_DEFECTIVE_TOKEN Indicates that the mechanism type could be parsed, but that either the other fields could not be determined from the input_token, or their values did not correspond to valid values for that mechanism. GSS_S_FAILURE Indicates that the mechanism type could not be parsed (e.g., the token may be corrupted). Klump, Thakkar 77 Expires: November 1, 1997 3.5.3. idup_get_token_details OM_uint32 idup_get_token_details ( gss_buffer_t token, OM_uint32* minor_status, gss_OID mech_type, int* data_included_in_token, OM_uint32* idu_size, int* requested_evidence_back, gss_buffer_t evidence_check, gss_OID nr_policy, IDUP_Nr_Options Nr_Options, IDUP_Originator_Information Originator_Information, IDUP_Request_Features Request_Features, time_t* time_stamping_time) Purpose: This call gives only a hint about the content of the token, without performing any integrity check. When the token contains an evidence, only by doing a proper verification of the evidence is it possible to check that such information is correct. The call returns the OID of the mechanism and whether the token contains the associated data. In addition, it tells the size of the associated data, whether inside or outside the token. When the input token contains only an evidence generated spontaneously, the call returns: - the evidence type, - the non-repudiation policy under which the evidence was generated, - who generated the evidence, - the date and time when it was generated (if available), - the date and time when it was time-stamped (if available). When the input token contains only an evidence generated in response to a request from another party, the call returns the following additional information: - an indicator to state that this evidence relates to a request, - a string significant for the requestor that will allow him to check whether the answer corresponds to the requested evidence. When the input token only contains a request, the call returns the following: - who requested the evidence, - the date and time he requested it, - the evidence type to send back, - the non-repudiation policy under which to generate the evidence to send back, - the names of the recipients which should generate and distribute the requested evidence, - the names of the recipients to whom the requested evidence should go after it is generated. When the input token contains both evidence and a request, an indicator is returned describing whether the new evidence should be generated using only the data in the input token, or using both the data and the evidence in the input token. Klump, Thakkar 78 Expires: November 1, 1997 Parameters: token buffer, read The input token to verify. minor_status integer, modify Implementation specific status code. mech_type OID, modify The mechanism that was used to create input_token. data_included_in_token integer, modify Whether the token includes its associated data. idu_size integer, modify The size of the data associated with the token. requested_evidence_back integer, modify Whether this is an evidence generated in response to a previous request. evidence_check buffer, modify If requested_evidence_back is TRUE, data to be used to verify the token. nr_policy OID, modify The non-repudiation policy under which the evidence was generated. Nr_Options IDUP_Nr_Options, read The options used in generating this evidence. Originator_Information IDUP_Originator_Information Who created the token and when. Request_Features IDUP_Request_Features, read The features the application wants in the request for evidence. time_stamping_time time_t, modify For information only. Function value: GSS status code: GSS_S_COMPLETE Indicates that the input token could be parsed for all relevant fields. GSS_S_DEFECTIVE_TOKEN Indicates that the mechanism type could be parsed, but that either the other fields could not be determined from the input token, or their values did not correspond to valid values for that mechanism. Klump, Thakkar 79 Expires: November 1, 1997 GSS_S_FAILURE Indicates that the mechanism type could not be parsed (e.g., the token may be corrupted). Klump, Thakkar 80 Expires: November 1, 1997 3.5.4. idup_get_policy_info OM_uint32 idup_get_policy_info ( gss_OID policy_id, OM_uint32* minor_status, int* policy_version, time_t* policy_effective_time, time_t* policy_expiry_time, IDUP_Service_Descriptor_Set Service_Descriptor_Set, IDUP_Mechanism_Descriptor_Set Mechanism_Descriptor_Set) Purpose: This call allows the application to retrieve information pertaining to a given policy_id. Policies define the following: - rules for protecting IDU's, such as: - trusted third parties that may be involved in P-IDU generation - the roles in which they may be involved - the duration for which the generated P-IDU is valid; - rules for unprotecting P-IDU's, such as the interval during which a trusted third party may legitimately declare its key to have been compromised or revoked; and - rules for adjudication, such as which authorities may be used to adjudicate disputes. An adjudicator may use the policy itself when resolving a dispute. For example, the adjudicator might refer to the policy to determine whether the rules for generation of the P-IDU have been followed. Parameters: policy_id OID, read The security policy. minor_status integer, modify Implementation specific status code. policy_version integer, modify The version number of the policy. policy_effective_time time_t, modify The time at which the policy came into effect. policy_expiry_time time_t, modify The time at which the policy came will expires. supported_services IDUP_Service_Descriptor_Set, modify Particulars about the set of services that the policy in question supports. supported_mechanisms IDUP_Mechanism_Descriptor_Set, modify Particulars about the set of mechanisms that the policy in question supports. Klump, Thakkar 81 Expires: November 1, 1997 Function value: GSS status code: GSS_S_COMPLETE Indicates that the input token could be parsed for all relevant fields. GSS_S_FAILURE Indicates that the call failed. Klump, Thakkar 82 Expires: November 1, 1997 3.6. Memory Management Calls This section deals with calls to allocate and release memory. 3.6.1. Memory Management Calls Specific to IDUP-SE This group of calls deals with the allocation and release of parameter bundles specific to the simplified IDUP-EV interface. Klump, Thakkar 83 Expires: November 1, 1997 3.6.1.1. idup_se_alloc_protect_options IDUP_Protect_Options idup_se_alloc_protect_options ( OM_uint32* minor_status); Purpose: This routine allocates a Protect_Options parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 84 Expires: November 1, 1997 3.6.1.2. idup_se_release_protect_options OM_uint32 idup_se_release_protect_options ( OM_uint32* minor_status, IDUP_Protect_Options* Protect_Options); Purpose: This routine releases the memory associated with the input Protect_Options parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Protect_Options IDUP_Protect_Options, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 85 Expires: November 1, 1997 3.6.1.3. idup_se_alloc_pidu_information IDUP_PIDU_Information idup_se_alloc_pidu_information ( OM_uint32* minor_status); Purpose: This routine allocates a PIDU_Information parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 86 Expires: November 1, 1997 3.6.1.4. idup_se_release_pidu_information OM_uint32 idup_se_release_pidu_information ( OM_uint32* minor_status, IDUP_PIDU_Information* PIDU_Information); Purpose: This routine releases the memory associated with the input PIDU_Information parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. PIDU_Information IDUP_PIDU_Information, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 87 Expires: November 1, 1997 3.6.2. Memory Management Calls Specific to IDUP-EV This group of calls deals with the allocation and release of parameter bundles specific to the simplified IDUP-EV interface. 3.6.2.1. idup_ev_alloc_Nr_Options IDUP_Nr_Options idup_ev_alloc_Nr_Options ( OM_uint32* minor_status); Purpose: This routine allocates a Nr_Options parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 88 Expires: November 1, 1997 3.6.2.2. idup_ev_release_Nr_Options OM_uint32 idup_ev_release_Nr_options ( OM_uint32* minor_status, IDUP_Nr_Options* Nr_Options); Purpose: This routine releases the memory associated with the input Nr_Options parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Nr_Options IDUP_Nr_Options, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 89 Expires: November 1, 1997 3.6.2.3. idup_ev_alloc_Originator_Options IDUP_Originator_Options idup_ev_alloc_Originator_Options ( OM_uint32* minor_status); Purpose: This routine allocates an Originator_Options parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 90 Expires: November 1, 1997 3.6.2.4. idup_ev_release_Originator_Options OM_uint32 idup_ev_release_Originator_Options ( OM_uint32* minor_status, IDUP_Originator_Options* Originator_Options); Purpose: This routine releases the memory associated with the input Originator_Options parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Originator_Options IDUP_Originator_Options, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 91 Expires: November 1, 1997 3.6.2.5. idup_ev_alloc_Request_Features IDUP_Request_Features idup_ev_alloc_Request_Features ( OM_uint32* minor_status); Purpose: This routine allocates a Request_Features parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 92 Expires: November 1, 1997 3.6.2.6. idup_ev_release_Request_Features OM_uint32 idup_ev_release_Request_Features ( OM_uint32* minor_status, IDUP_Request_Features* Request_Features); Purpose: This routine releases the memory associated with the input Request_Features parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Request_Features IDUP_Request_Features, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 93 Expires: November 1, 1997 3.6.3. Memory Management Calls for the General IDUP-GSS-API This group of calls deals with the allocation and release of parameter bundles specific to the general IDUP-GSS-API. 3.6.3.1. idup_release_buffer OM_uint32 idup_release_buffer ( OM_uint32* minor_status, gss_buffer_t* buffer); Purpose: This routine releases the memory associated with the input buffer. Parameters: minor_status integer, modify Implementation specific status code. buffer buffer, modify The structure to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 94 Expires: November 1, 1997 3.6.3.2. idup_release_buffer_content OM_uint32 idup_release_buffer_content ( OM_uint32* minor_status, gss_buffer_t buffer); Purpose: This routine clears the contents of the input buffer, but leaves the structure itself intact. Parameters: minor_status integer, modify Implementation specific status code. buffer buffer, modify The structure whose contents to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 95 Expires: November 1, 1997 3.6.3.3. idup_release_name OM_uint32 idup_release_name ( OM_uint32* minor_status, gss_name_t* name); Purpose: This routine releases the memory associated with the input name. Parameters: minor_status integer, modify Implementation specific status code. name name, modify The structure to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 96 Expires: November 1, 1997 3.6.3.4. idup_release_name_content OM_uint32 idup_release_name_content ( OM_uint32* minor_status, gss_name_t name); Purpose: This routine clears the contents of the input name, but leaves the structure itself intact. Parameters: minor_status integer, modify Implementation specific status code. name name, modify The structure whose contents to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 97 Expires: November 1, 1997 3.6.3.5. idup_create_empty_name_set idup_name_set idup_create_empty_name_set ( OM_uint32* minor_status); Purpose: This routine creates an empty name set which it returns, or or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 98 Expires: November 1, 1997 3.6.3.6. idup_add_name_set_member OM_uint32 idup_add_name_set_member ( idup_name_set nameset, gss_name_t name, OM_uint32* minor_status, int* index); Purpose: This routine adds a name to an existing name set. It passes back the index of the new entry in the name set, or the index at which the name exists in the list if already present. Parameters: nameset name set, modify The name set to which to add the name. name name, read The name to add to the name set. minor_status integer, modify Implementation specific status code. index integer, modify The index at which the routine added the name to the set, or if the name was already present, its index in the set. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 99 Expires: November 1, 1997 3.6.3.7. idup_remove_name_set_member OM_uint32 idup_remove_name_set_member ( idup_name_set nameset, gss_name_t name, OM_uint32* minor_status); Purpose: This routine deletes a name, if present, from a name set. Parameters: nameset name set, modify The name set from which to delete the name. name name, read The name to delete from the name set. minor_status integer, modify Implementation specific status code. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 100 Expires: November 1, 1997 3.6.3.8. idup_release_name_set OM_uint32 idup_release_name_set ( OM_uint32* minor_status, idup_name_set* names); Purpose: This routine releases the memory associated with the input name_set parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. names name set, modify The name set to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 101 Expires: November 1, 1997 3.6.3.9. idup_alloc_general_service_data IDUP_General_Service_Data idup_alloc_general_service_data ( OM_uint32* minor_status); Purpose: This routine allocates a General_Service_Data parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 102 Expires: November 1, 1997 3.6.3.10. idup_release_general_service_data OM_uint32 idup_release_general_service_data ( OM_uint32* minor_status, IDUP_General_Service_Data* General_Service_Data); Purpose: This routine releases the memory associated with the input general_service_data parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. General_Service_Data IDUP_General_Service_Data, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 103 Expires: November 1, 1997 3.6.3.11. idup_alloc_idu_information IDUP_Idu_Information idup_alloc_idu_information ( OM_uint32* minor_status); Purpose: This routine allocates an Idu_Information parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 104 Expires: November 1, 1997 3.6.3.12. idup_release_idu_information OM_uint32 idup_release_idu_information ( OM_uint32* minor_status, IDUP_Idu_Information* Idu_Information); Purpose: This routine releases the memory associated with the input Idu_Information parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Idu_Information IDUP_Idu_Information, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 105 Expires: November 1, 1997 3.6.3.13. idup_alloc_idu_sensitivity IDUP_Idu_Sensitivity idup_alloc_idu_sensitivity ( OM_uint32* minor_status); Purpose: This routine allocates an Idu_Sensitivity parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 106 Expires: November 1, 1997 3.6.3.14. idup_release_idu_sensitivity OM_uint32 idup_release_idu_sensitivity ( OM_uint32* minor_status, IDUP_Idu_Sensitivity* Idu_Sensitivity); Purpose: This routine releases the memory associated with the input Idu_Sensitivity parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Idu_Sensitivity IDUP_Idu_Sensitivity, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 107 Expires: November 1, 1997 3.6.3.15. idup_alloc_prot_service IDUP_Prot_Service idup_alloc_prot_service ( OM_uint32* minor_status); Purpose: This routine allocates a Prot_Service parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 108 Expires: November 1, 1997 3.6.3.16. idup_release_prot_service OM_uint32 idup_release_prot_service ( OM_uint32* minor_status, IDUP_Prot_Service* Prot_Service); Purpose: This routine releases the memory associated with the input Prot_Service parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Prot_Service IDUP_Prot_Service, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 109 Expires: November 1, 1997 3.6.3.17. idup_alloc_quality IDUP_Quality idup_alloc_quality ( OM_uint32* minor_status); Purpose: This routine allocates a Quality parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 110 Expires: November 1, 1997 3.6.3.18. idup_release_quality OM_uint32 idup_release_quality ( OM_uint32* minor_status, IDUP_Quality* Quality); Purpose: This routine releases the memory associated with the input Quality parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Quality IDUP_Quality, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 111 Expires: November 1, 1997 3.6.3.19. idup_alloc_prot_information IDUP_Prot_Information idup_alloc_prot_information ( OM_uint32* minor_status); Purpose: This routine allocates a Prot_Information parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 112 Expires: November 1, 1997 3.6.3.20. idup_release_prot_information OM_uint32 idup_release_prot_information ( OM_uint32* minor_status, IDUP_Prot_Information* Prot_Information); Purpose: This routine releases the memory associated with the input Prot_Information parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Prot_Information IDUP_Prot_Information, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 113 Expires: November 1, 1997 3.6.3.21. idup_alloc_service_creation_info IDUP_Service_Creation_Info idup_alloc_service_creation_info ( OM_uint32* minor_status); Purpose: This routine allocates a Service_Creation_Info parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 115 Expires: November 1, 1997 3.6.3.22. idup_release_service_creation_info OM_uint32 idup_release_service_creation_info( OM_uint32* minor_status, IDUP_Service_Creation_Info* Service_Creation_Info); Purpose: This routine releases the memory associated with the input Service_Creation_Info parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Service_Creation_Info IDUP_Service_Creation_Info, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 116 Expires: November 1, 1997 3.6.3.23. idup_alloc_service_verification_info IDUP_Service_Verification_Info idup_alloc_service_verification_info ( OM_uint32* minor_status); Purpose: This routine allocates a Service_Verification_Info parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 117 Expires: November 1, 1997 3.6.3.24. idup_release_service_verification_info OM_uint32 idup_release_service_verification_info ( OM_uint32* minor_status, IDUP_Service_Verification_Info* Service_Verification_Info); Purpose: This routine releases the memory associated with the input Service_Verification_Info parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Service_Verification_Info IDUP_Service_Verification_Info, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 118 Expires: November 1, 1997 3.6.3.25. idup_create_empty_services_to_receive IDUP_Services_To_Receive idup_create_empty_services_to_receive ( OM_uint32* minor_status); Purpose: This routine creates an empty Services_To_Receive parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 119 Expires: November 1, 1997 3.6.3.26. idup_release_services_to_receive OM_uint32 idup_release_services_to_receive( OM_uint32* minor_status, IDUP_Services_To_Receive* Services_To_Receive); Purpose: This routine releases the memory associated with the input Services_To_Receive parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Services_To_Receive IDUP_Services_To_Receive, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 120 Expires: November 1, 1997 3.6.3.27. idup_create_empty_services_to_perform IDUP_Services_To_Perform idup_create_empty_services_to_perform ( OM_uint32* minor_status); Purpose: This routine allocates a Services_To_Perform parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 121 Expires: November 1, 1997 3.6.3.28. idup_add_services_to_perform_member OM_uint32 idup_add_services_to_perform_member ( IDUP_Services_To_Perform Services_To_Perform, IDUP_Prot_Service Prot_Service, OM_uint32* minor_status, int* index); Purpose: This routine adds a Prot_Service to an existing Services_To_Perform parameter bundle. It passes back the index at which it adds the entry to the set. Parameters: Services_To_Perform IDUP_Services_To_Perform, modify The set to which to add the service. Prot_Service IDUP_Prot_Service, read The service to add to the set. minor_status integer, modify Implementation specific status code. index integer, modify The index at which the routine added the service to the set. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 122 Expires: November 1, 1997 3.6.3.29. idup_release_services_to_perform OM_uint32 idup_release_services_to_perform ( OM_uint32* minor_status, IDUP_Services_To_Perform* Services_To_Perform); Purpose: This routine releases the memory associated with the input Services_To_Perform parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Services_To_Perform IDUP_Services_To_Perform, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 123 Expires: November 1, 1997 3.6.3.30. idup_alloc_special_conditions IDUP_Special_Conditions idup_alloc_special_conditions ( OM_uint32* minor_status); Purpose: This routine allocates a Special_Conditions parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 124 Expires: November 1, 1997 3.6.3.31. idup_release_special_conditions OM_uint32 idup_release_special_conditions( OM_uint32* minor_status, IDUP_Special_Conditions* Special_Conditions); Purpose: This routine releases the memory associated with the input Special_Conditions parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Special_Conditions IDUP_Special_Conditions, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 125 Expires: November 1, 1997 3.6.3.32. idup_alloc_target_info IDUP_Target_Info idup_alloc_target_info ( OM_uint32* minor_status); Purpose: This routine allocates a Target_Info parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 126 Expires: November 1, 1997 3.6.3.33. idup_release_target_info OM_uint32 idup_release_target_info( OM_uint32* minor_status, IDUP_Target_Info* Target_Info); Purpose: This routine releases the memory associated with the input Target_Info parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Target_Info IDUP_Target_Info, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 127 Expires: November 1, 1997 3.6.3.34. idup_alloc_unprot_service IDUP_Unprot_Service idup_alloc_unprot_service ( OM_uint32* minor_status); Purpose: This routine allocates an Unprot_Service parameter bundle which it returns, or a NULL pointer if it cannot make the allocation. Parameters: minor_status integer, modify Implementation specific status code. Function value: This function returns a NULL pointer if it cannot make the allocation; otherwise, it returns a pointer to an empty parameter bundle. Klump, Thakkar 128 Expires: November 1, 1997 3.6.3.35. idup_release_unprot_service OM_uint32 idup_release_unprot_service ( OM_uint32* minor_status, IDUP_Unprot_Service* Unprot_Service); Purpose: This routine releases the memory associated with the input Unprot_Service parameter bundle. Parameters: minor_status integer, modify Implementation specific status code. Unprot_Service IDUP_Unprot_Service, modify The parameter bundle to release. Function value: GSS status code: GSS_S_COMPLETE Indicates that the operation succeeded. GSS_S_FAILURE Indicates that the call failed for reasons unspecified at the IDUP-GSS-API level. Klump, Thakkar 129 Expires: November 1, 1997 4. ACKNOWLEDGMENTS Many thanks to Carlisle Adams of Bell-Northern Research for many helpful comments. Section 1 and many parts of section 2 of this document are either strongly influenced by or identical to John Wray's GSS-API: C-Bindings [RFC-1509]. Klump, Thakkar 130 Expires: November 1, 1997 5. SECURITY CONSIDERATIONS Security issues are discussed throughout this memo. Klump, Thakkar 131 Expires: November 1, 1997 6. REFERENCES [GSSv2] J. Linn, "Generic Security Service Application Program Interface, Version 2", Internet Draft draft-ietf-cat-gssv2-02.txt (work in progress) [IDUP] Independent Data Unit Protection Generic Security Service Application Program Interface, Internet Draft, C. Adams, Internet Draft draft-ietf-cat-idup-gss-04.txt (work in progress), December 1995. [MSP]: U.S. National Security Agency, "Message Security Protocol", Secure Data Network System SDN.701, March 1994. [OSI] "OSI Object Management API Specification, Version 2.0 t", X.400 API Association & X/Open Company Limited, August 1990. Specification of datatypes and routines for manipulating information objects. [RFC-1421]: J. Linn, "Privacy Enhancement for Internet Electronic Mail: Part I: Message Encryption and Authentication Procedures", RFC 1421. [RFC-1508]: J. Linn, "Generic Security Service Application Program Interface", RFC 1508. [RFC-1509]: J. Wray, "Generic Security Service API: C-bindings", RFC1509. Klump, Thakkar 132 Expires: November 1, 1997 7. AUTHORS' ADDRESSES Stephen Klump Entrust Technologies Ltd. 2 Constellation Crescent P.O.Box 3511, Station C Nepean, Ontario, CANADA K1Y 4H7 Phone: +1 (613) 763-4515 E-mail: sklump@entrust.com Dhanya Thakkar Entrust Technologies Ltd. 2 Constellation Crescent P.O.Box 3511, Station C Nepean, Ontario, CANADA K1Y 4H7 Phone: +1 (613) 763-9039 E-mail: dickie48@bnr.ca Klump, Thakkar 133 Expires: November 1, 1997 APPENDIX - IDUP-GSS-API Example #ifndef IDUP_GSS_API_H_ #define IDUP_GSS_API_H_ /* * First, define the platform-dependent types. */ typedef OM_uint32; typedef idup_env_id_t; typedef gss_cred_id_t; typedef gss_name_t; typedef idup_name_t; /* * Note that a platform supporting the xom.h X/Open header file * may make use of that header for the definitions of OM_uint32 * and the structure to which gss_OID_desc equates. */ typedef void* IDUP_Mech_Specific_Info; typedef struct gss_OID_desc_struct { OM_uint32 length; void* elements; } gss_OID_desc, *gss_OID; typedef struct gss_OID_set_desc_struct { int count; gss_OID elements; } gss_OID_set_desc, *gss_OID_set; typedef struct gss_buffer_desc_struct { size_t length; void* value; } gss_buffer_desc, *gss_buffer_t; typedef struct idup_name_set_desc_struct { int count; gss_name_t elements; } idup_name_set_desc, *idup_name_set; typedef struct { gss_OID service_id; IDUP_Quality Quality; } IDUP_Service_Creation_Info_desc, *IDUP_Service_Creation_Info, IDUP_Service_Verification_Info_desc, *IDUP_Service_Verification_Info; typedef struct { OM_uint32 qop_algs; OM_uint32 validity; gss_OID policy_id; BOOL allow_policy_mapping; } IDUP_Quality_desc, *IDUP_Quality; Klump, Thakkar 134 Expires: November 1, 1997 typedef struct { gss_buffer_t idu_type; gss_buffer_t idu_title; IDUP_Idu_Sensitivity Idu_Sensitivity; } IDUP_Idu_Information_desc, *IDUP_Idu_Information; typedef struct { gss_buffer_t originator_name; IDUP_Idu_Information Idu_Information; int protection_time; } IDUP_Prot_Information_desc, *IDUP_Prot_Information; typedef struct { int prot_oper_id; int use_trusted_time; int use_untrusted_time; } IDUP_Special_Conditions_desc, *IDUP_Special_Conditions; typedef struct { IDUP_Target_Info Target_Info; gss_buffer_t unencapsulated_token; /* Output */ OM_uint32 minor_status; /* Output */ } IDUP_General_Service_Data_desc, *IDUP_General_Service_Data; typedef struct { gss_buffer_t bad_targ_name; /* Output */ int bad_targ_status; /* Output */ } IDUP_Bad_Target_Name_desc, *IDUP_Bad_Target_Name; typedef struct { idup_name_set targ_names; /* Input */ IDUP_Bad_Target_Name Bad_Target_Names; /* Output */ int bad_count; /* Output */ } IDUP_Target_Info_desc, *IDUP_Target_Info; typedef struct { int prot_service_type; /* Input */ gss_OID service_id; /* Input */ IDUP_Quality Quality; /* Input */ IDUP_General_Service_Data General_Service_Data; /* Input */ IDUP_Service_Creation_Info Service_Creation_Info; /* Input */ idup_name_set services_to; /* Input */ IDUP_Service_Verification_Info Service_Verification_Info; /* Output */ intservice_verification_info_id; /* Output */ } IDUP_Prot_Service_desc, *IDUP_Prot_Service; typedef struct { OM_uint32 no_of_services; IDUP_Prot_Service Prot_Service; } IDUP_Services_To_Perform_desc, *IDUP_Services_To_Perform; Klump, Thakkar 135 Expires: November 1, 1997 typedef struct { int unprot_service_type; /* Output */ gss_OID service_id; /* Output */ IDUP_Quality Quality; /* Output */ IDUP_General_Service_Data General_Service_Data; /* Output */ int service_verification_info_id; /* Output */ IDUP_Service_Verification_Info Service_Verification_Info; /* Input */ idup_name_set services_to; /* Output */ IDUP_Service_Creation_Info Service_Creation_Info; /* Output */ } IDUP_Unprot_Service_desc, *IDUP_Unprot_Service; typedef struct { OM_uint32 no_of_services; IDUP_Unprot_Service Unprot_Service; } IDUP_Services_To_Receive_desc, *IDUP_Services_To_Receive; typedef enum { sign_only, encrypt_only, sign_and_encrypt, clear_sign_only } IDUP_Protect_Operation; typedef struct { IDUP_Protect_Operation Protect_Operation; OM_uint32 sign_qop_alg; OM_uint32 enc_qop_alg; gss_buffer_t idu_type_string; } IDUP_Protect_Options_desc, *IDUP_Protect_Options; typedef struct { IDUP_Protect_Options Protect_Options; gss_buffer_t originator_name; int protection_time; } IDUP_PIDU_Information_desc, *IDUP_PIDU_Information; typedef enum { no_evidence, proof_of_receipt, proof_of_delivery, proof_of_approval, proof_of_retrieval, proof_of_creation, proof_of_sender, proof_of_origin } IDUP_evidence_type; typedef struct { IDUP_evidence_type evidence_type; int evidence_validity_duration; } IDUP_Nr_Options_desc, *IDUP_Nr_Options; Klump, Thakkar 136 Expires: November 1, 1997 typedef struct { gss_name_t token_generator_name int protection_time } IDUP_Originator_Information_desc, *IDUP_Originator_Information; typedef enum { no_evidence, proof_of_receipt, proof_of_delivery, proof_of_approval, proof_of_retrieval, } IDUP_requested_evidence_type; typedef struct { IDUP_requested_evidence_type requested_evidence_type; gss_OID nr_req_policy; IDUP_Target_Info evidence_from; IDUP_Target_Info evidence_to; int include_received_token_in_evidence; } IDUP_Request_Features_desc, *IDUP_Request_Features; typedef enum { evidence_and_or_evidence_request = 1, returned_evidence } IDUP_nr_operation; /* * Credential usage options */ #define GSS_C_BOTH 0 #define IDUP_C_PROTECT 1 #define IDUP_C_UNPROTECT 2 /* * Status code types for GSS_Display_status */ #define GSS_C_GSS_CODE 1 #define GSS_C_MECH_CODE 2 #define IDUP_C_CODE 3 #define GSS_C_AF_NULLADDR 255; #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) #define GSS_C_NULL_OID ((gss_OID) 0) #define GSS_C_NULL_OID_SET ((gss_OID_set) 0) #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) #define GSS_C_EMPTY_BUFFER {0, NULL} #define IDUP_C_NO_ENV ((idup_env_id_t) 0) /* * Define the default Quality of Protection for per-data-unit * services. Note that an implementation that offers multiple * levels of QOP may either reserve a value (for example zero, * as assumed here) to mean "default protection", or alternatively * may simply equate GSS_C_QOP_DEFAULT to a specific explicit QOP * value. */ Klump, Thakkar 137 Expires: November 1, 1997 #define GSS_C_QOP_DEFAULT 0 /* * Define the default policy time for per-data-unit services. * An implementation may equate IDUP_C_POLICY_TIME_DEFAULT to a * specific explicit IDUP_C_POLICY_TIME_DEFAULT value. */ #define IDUP_C_POLICY_TIME_DEFAULT 0 /* * Expiration time of 2^32-1 seconds means infinite lifetime for a * credential or security environment */ #define GSS_C_INDEFINITE 0xfffffffful /* Major status codes */ #define GSS_S_COMPLETE 0 /* * Some "helper" definitions to make the status code macros obvious. */ #define GSS_C_CALLING_ERROR_OFFSET 24 #define GSS_C_ROUTINE_ERROR_OFFSET 16 #define GSS_C_SUPPLEMENTARY_OFFSET 0 #define GSS_C_CALLING_ERROR_MASK 0377ul #define GSS_C_ROUTINE_ERROR_MASK 0377ul #define GSS_C_SUPPLEMENTARY_MASK 0177777ul /* * The macros that test status codes for error conditions */ #define GSS_CALLING_ERROR(x) \ (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) #define GSS_ROUTINE_ERROR(x) \ (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) #define GSS_SUPPLEMENTARY_INFO(x) \ (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) #define GSS_ERROR(x) \ ((GSS_CALLING_ERROR(x) != 0) || (GSS_ROUTINE_ERROR(x) != 0)) /* * Calling errors: */ #define GSS_S_CALL_INACCESSIBLE_READ \ (1ul << GSS_C_CALLING_ERROR_OFFSET) #define GSS_S_CALL_INACCESSIBLE_WRITE \ (2ul << GSS_C_CALLING_ERROR_OFFSET) #define GSS_S_CALL_BAD_STRUCTURE \ (3ul << GSS_C_CALLING_ERROR_OFFSET) Klump, Thakkar 138 Expires: November 1, 1997 /* * Routine errors: */ #define GSS_S_BAD_MECH \ (1ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_BAD_NAME \ (2ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_BAD_NAMETYPE \ (3ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_BAD_BINDINGS \ (4ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_BAD_STATUS \ (5ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_BAD_SIG \ (6ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_NO_CRED \ (7ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_NO_CONTEXT \ (8ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_DEFECTIVE_TOKEN \ (9ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_DEFECTIVE_CREDENTIAL \ (10ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_CREDENTIALS_EXPIRED \ (11ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_CONTEXT_EXPIRED \ (12ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_FAILURE \ (13ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_BAD_QOP \ (14ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_UNAUTHORIZED \ (15ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define GSS_S_UNAVAILABLE \ (16ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_BAD_TARG_INFO \ (17ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_BAD_DOA_KEY \ (18ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_BAD_KE_KEY \ (19ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_BAD_ENC_IDU \ (20ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_EVIDENCE_TOKEN_INCOMPLETE \ (21ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_SERV_VERIF_INFO_NEEDED \ (22ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_SERVICE_UNAVAIL \ (23ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_REQ_TIME_SERVICE_UNAVAIL \ (24ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_NO_ENV \ (25ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_NO_MATCH \ (26ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_UNKNOWN_OPER_ID \ (27ul << IDUP_C_ROUTINE_ERROR_OFFSET) Klump, Thakkar 139 Expires: November 1, 1997 /* * Supplementary info bits: */ #define GSS_S_CONTINUE_NEEDED \ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) #define GSS_S_DUPLICATE_TOKEN \ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) #define GSS_S_OLD_TOKEN \ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) #define GSS_S_UNSEQ_TOKEN \ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) #define GSS_S_GAP_TOKEN \ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4)) #define IDUP_S_ENCAPSULATION_UNAVAIL \ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 5)) #define IDUP_S_MORE_PIDU_NEEDED \ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 6)) #define IDUP_S_MORE_DATA_NEEDED \ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 7)) /* * Finally, function prototypes for the IDUP-GSS-API routines. */ OM_uint32 idup_establish_env ( gss_cred_id_t, /* claimant_cred_handle */ gss_OID, /* req_mech_type */ gss_OID, /* req_policy */ time_t, /* policy_time */ gss_OID_set, /* req_services */ OM_uint32*, /* minor_status */ idup_env_id_t*, /* env_handle */ gss_OID*, /* actual_mech_type */ gss_OID*, /* actual_policy */ time_t*, /* actual_policy_time */ gss_OID_set /* ret_services */ ); OM_uint32 idup_abolish_env ( idup_env_id_t*, /* env_handle */ OM_uint32* /* minor_status */ ); OM_uint32 idup_inquire_env ( idup_env_id_t, /* env_handle */ OM_uint32*, /* minor_status */ gss_OID*, /* mech_type */ gss_OID*, /* policy */ time_t*, /* policy_time */ gss_OID_set* /* ret_services */ ); Klump, Thakkar 140 Expires: November 1, 1997 OM_uint32 idup_se_singlebuffer_protect ( idup_env_id_t env_handle, IDUP_Protect_Options Protect_Options, IDUP_Target_Info Target_Info, const gss_buffer_t idu_buffer, OM_uint32* minor_status, gss_buffer_t pidu_buffer, gss_buffer_t sig_token ); OM_uint32 idup_se_singlebuffer_unprotect ( idup_env_id_t env_handle, gss_buffer_t pidu_buffer, gss_buffer_t sig_token, OM_uint32* minor_status, gss_buffer_t idu_buffer, IDUP_PIDU_Information PIDU_Information ); OM_uint32 idup_se_multibuffer_startprotect ( idup_env_id_t env_handle, IDUP_Protect_Options Protect_Options, IDUP_Target_Info Target_Info, OM_uint32* minor_status, gss_buffer_t initial_pidu_buffer ); OM_uint32 idup_se_multibuffer_endprotect ( idup_env_id_t env_handle, OM_uint32* minor_status, gss_buffer_t final_pidu_buffer, gss_buffer_t sig_token ); OM_uint32 idup_se_multibuffer_startunprotect ( idup_env_id_t env_handle, gss_buffer_t initial_pidu_buffer, int sign_qop_alg_in, gss_buffer_t sig_token, OM_uint32* minor_status, IDUP_PIDU_Information PIDU_Information, gss_buffer_t initial_idu_buffer ); OM_uint32 idup_se_multibuffer_endunprotect ( idup_env_id_t env_handle, gss_buffer_t sig_token, OM_uint32* minor_status, IDUP_PIDU_Information PIDU_Information, gss_buffer_t final_idu_buffer ); Klump, Thakkar 141 Expires: November 1, 1997 OM_uint32 idup_se_process_buffer ( idup_env_id_t env_handle, gss_buffer_t input_buffer, OM_uint32* minor_status, gss_buffer_t output_buffer ); OM_uint32 idup_ev_singlebuffer_generate ( idup_env_id_t env_handle, IDUP_nr_operation nr_operation, IDUP_Nr_Options Nr_Options, gss_buffer_t idu_buffer, int form_complete_evidence, int include_data_in_token, IDUP_Request_Features Request_Features, OM_uint32* minor_status, gss_buffer_t token, gss_buffer_t evidence_check); OM_uint32 idup_ev_singlebuffer_verify ( idup_env_id_t env_handle, gss_buffer_t token, gss_buffer_t idu_buffer, gss_buffer_t evidence_check, OM_uint32* minor_status, IDUP_Nr_Options Nr_Options, IDUP_Originator_Information Originator_Information, IDUP_Request_Features Request_Features, int* trusted_time_stamping_time, int* complete_evidence_before, int* complete_evidence_after, gss_buffer_t idu_buffer); OM_uint32 idup_ev_multibuffer_startgenerate ( idup_env_id_t env_handle, IDUP_nr_operation nr_operation, IDUP_Nr_Options Nr_Options, int form_complete_evidence, int include_data_in_token, IDUP_Request_Features Request_Features, OM_uint32* minor_status, gss_buffer_t initial_pidu_buffer); OM_uint32 idup_ev_multibuffer_endgenerate ( idup_env_id_t env_handle, OM_uint32* minor_status, gss_buffer_t final_pidu, gss_buffer_t token, gss_buffer_t evidence_check); OM_uint32 idup_ev_multibuffer_startverify ( idup_env_id_t env_handle, gss_buffer_t token, gss_buffer_t evidence_check, OM_uint32* minor_status); Klump, Thakkar 142 Expires: November 1, 1997 OM_uint32 idup_ev_multibuffer_endverify ( idup_env_id_t env_handle, OM_uint32* minor_status, IDUP_Nr_Options Nr_Options, IDUP_Originator_Information Originator_Information, IDUP_Request_Features Request_Features, int* trusted_time_stamping_time, int* complete_evidence_before, int* complete_evidence_after, gss_buffer_t idu_buffer); OM_uint32 idup_ev_process_buffer ( idup_env_id_t env_handle, gss_buffer_t input_buffer, OM_uint32* minor_status, gss_buffer_t output_buffer); OM_uint32 idup_start_protect ( idup_env_id_t, /* env_handle */ IDUP_Idu_Information, /* Idu_Information */ int, /* encapsulation_request */ IDUP_Special_Conditions, /* Special_Conditions */ gss_buffer_t, /* single_idu_buffer */ IDUP_Target_Info, /* Target_Info */ IDUP_Services_To_Perform, /* Services_to_Perform */ OM_uint32*, /* minor_status */ IDUP_Mech_Specific_Info, /* Mech_Specific_Info */ gss_buffer_t, /* midu_buffer */ gss_buffer_t /* pidu_buffer */ ); OM_uint32 idup_protect ( idup_env_id_t, /* env_handle */ gss_buffer_t, /* input_buffer */ OM_uint32*, /* minor_status */ gss_buffer_t /* output_buffer */ ); OM_uint32 idup_end_protect ( idup_env_id_t, /* env_handle */ OM_uint32*, /* minor_status */ IDUP_Services_To_Perform, /* Services_to_Perform */ gss_buffer_t, /* final_midu_buffer */ gss_buffer_t /* final_pidu_buffer */ ); Klump, Thakkar 143 Expires: November 1, 1997 OM_uint32 idup_start_unprotect ( idup_env_id_t, /* env_handle */ IDUP_Mech_Specific_Info, /* Mech_Specific_Info */ gss_buffer_t, /* single_pidu_buffer */ gss_buffer_t, /* partial_pidu_buffer */ gss_buffer_t, /* final_pidu_buffer */ IDUP_Special_Conditions, /* Special_Conditions */ OM_uint32*, /* minor_status */ IDUP_Services_To_Receive, /* Services_to_Receive */ IDUP_Prot_Information, /* Prot_Information */ gss_buffer_t /* single_idu_buffer */ gss_buffer_t, /* initial_idu_buffer */ IDUP_Service_Verification_Info, /* Service_Verification_Info */ gss_buffer_t /* service_verification_info_id */ ); OM_uint32 idup_unprotect ( idup_env_id_t, /* env_handle */ gss_buffer_t, /* input_buffer */ OM_uint32*, /* minor_status */ gss_buffer_t /* output_buffer */ ); OM_uint32 idup_end_unprotect ( idup_env_id_t, /* env_handle */ OM_uint32*, /* minor_status */ IDUP_Prot_Information, /* Prot_Information */ IDUP_Services_To_Receive, /* Services_to_Receive */ gss_buffer_t, /* final_idu_buffer */ IDUP_Service_Verification_Info, /* Service_Verification_Info */ gss_buffer_t /* service_verification_info_id */ ); OM_uint32 idup_form_complete_pidu ( idup_env_id_t, /* env_handle */ gss_buffer_t, /* single_evidence_buffer */ gss_buffer_t, /* partial_evidence_buffer */ gss_buffer_t, /* final_evidence_buffer */ OM_uint32*, /* minor_status */ gss_buffer_t /* evidence_token_out */ ); OM_uint32 idup_acquire_cred_with_auth ( gss_name_t desired_name, gss_buffer_t authenticator, OM_uint32 lifetime_req, gss_OID_set desired_mechs, gss_buffer_t cred_usage, OM_uint32* minor_status, gss_cred_id_t output_cred_handle, gss_OID_set actual_mechs, OM_uint32* lifetime_rec); OM_uint32 idup_parse_token ( gss_buffer_t, /* input_token */ OM_uint32*, /* minor_status */ gss_OID* /* mech_type */ ); Klump, Thakkar 144 Expires: November 1, 1997 OM_uint32 idup_get_token_details ( gss_buffer_t token, OM_uint32* minor_status, gss_OID mech_type, int* data_included_in_token, OM_uint32* idu_size, int* requested_evidence_back, gss_buffer_t evidence_check, gss_OID nr_policy, IDUP_Nr_Options Nr_Options, IDUP_Originator_Information Originator_Information, IDUP_Request_Features Request_Features, int* time_stamping_time); OM_uint32 idup_get_policy_info ( gss_OID policy_id, OM_uint32* minor_status, int* policy_version, int* policy_effective_time, int* policy_expiry_time, gss_OID_set Service_Descriptor, gss_OID_set Mechanism_Descriptor); OM_uint32 gss_display_status ( OM_uint32*, /* minor_status */ OM_uint32, /* status_value */ int, /* status_type */ gss_OID, /* mech_type */ int*, /* message_environment */ gss_buffer_t /* status_string */ ); OM_uint32 gss_indicate_mechs ( OM_uint32*, /* minor_status */ gss_OID_set* /* mech_set */ ); OM_uint32 gss_compare_name ( OM_uint32*, /* minor_status */ gss_name_t, /* name1 */ gss_name_t, /* name2 */ int* /* name_equal */ ); OM_uint32 gss_display_name ( OM_uint32*, /* minor_status */ gss_name_t, /* input_name */ gss_buffer_t, /* output_name_buffer */ gss_OID* /* output_name_type */ ); OM_uint32 gss_import_name ( OM_uint32*, /* minor_status */ gss_buffer_t, /* input_name_buffer */ gss_OID, /* input_name_type */ gss_name_t* /* output_name */ ); Klump, Thakkar 145 Expires: November 1, 1997 OM_uint32 gss_release_name ( OM_uint32*, /* minor_status */ gss_name_t* /* input_name */ ); OM_uint32 gss_release_buffer ( OM_uint32*, /* minor_status */ gss_buffer_t /* buffer */ ); OM_uint32 gss_release_oid_set ( OM_uint32*, /* minor_status */ gss_OID_set* /* set */ ); OM_uint32 idup_release_name_set ( OM_uint32*, /* minor_status */ idup_name_set* /* set */ ); IDUP_Protect_Options idup_se_alloc_protect_options ( OM_uint32* minor_status ); OM_uint32 idup_se_release_protect_options ( OM_uint32* minor_status, IDUP_Protect_Options* Protect_Options ); IDUP_PIDU_Information idup_se_alloc_pidu_information ( OM_uint32* minor_status ); OM_uint32 idup_se_release_pidu_information ( OM_uint32* minor_status, IDUP_PIDU_Information* PIDU_Information ); IDUP_Nr_Options idup_ev_alloc_Nr_Options ( OM_uint32* minor_status ); OM_uint32 idup_ev_release_Nr_options ( OM_uint32* minor_status, IDUP_Nr_Options* Nr_Options ); IDUP_Originator_Options idup_ev_alloc_Originator_Options ( OM_uint32* minor_status ); OM_uint32 idup_ev_release_Originator_Options ( OM_uint32* minor_status, IDUP_Originator_Options* Originator_Options ); IDUP_Request_Features idup_ev_alloc_Request_Features ( OM_uint32* minor_status ); Klump, Thakkar 146 Expires: November 1, 1997 OM_uint32 idup_ev_release_Request_Features ( OM_uint32* minor_status, IDUP_Request_Features* Request_Features ); OM_uint32 idup_release_buffer ( OM_uint32* minor_status, gss_buffer_t* buffer ); OM_uint32 idup_release_buffer_content ( OM_uint32* minor_status, gss_buffer_t buffer ); OM_uint32 idup_release_name ( OM_uint32* minor_status, gss_name_t* name ); OM_uint32 idup_release_name_content ( OM_uint32* minor_status, gss_name_t name ); idup_name_set idup_create_empty_name_set ( OM_uint32* minor_status ); OM_uint32 idup_add_name_set_member ( idup_name_set nameset, gss_name_t name, OM_uint32* minor_status, int* index ); OM_uint32 idup_remove_name_set_member ( idup_name_set nameset, gss_name_t name, OM_uint32* minor_status ); OM_uint32 idup_release_name_set ( OM_uint32* minor_status, idup_name_set* names ); IDUP_General_Service_Data idup_alloc_general_service_data ( OM_uint32* minor_status ); OM_uint32 idup_release_general_service_data ( OM_uint32* minor_status, IDUP_General_Service_Data* General_Service_Data ); IDUP_Idu_Information idup_alloc_idu_information ( OM_uint32* minor_status ); Klump, Thakkar 147 Expires: November 1, 1997 OM_uint32 idup_release_idu_information ( OM_uint32* minor_status, IDUP_Idu_Information* Idu_Information ); IDUP_Idu_Sensitivity idup_alloc_idu_sensitivity ( OM_uint32* minor_status ); OM_uint32 idup_release_idu_sensitivity ( OM_uint32* minor_status, IDUP_Idu_Sensitivity* Idu_Sensitivity ); IDUP_Prot_Service idup_alloc_prot_service ( OM_uint32* minor_status ); OM_uint32 idup_release_prot_service ( OM_uint32* minor_status, IDUP_Prot_Service* Prot_Service ); IDUP_Quality idup_alloc_quality ( OM_uint32* minor_status ); OM_uint32 idup_release_quality ( OM_uint32* minor_status, IDUP_Quality* Quality ); IDUP_Prot_Information idup_alloc_prot_information ( OM_uint32* minor_status ); OM_uint32 idup_release_prot_information ( OM_uint32* minor_status, IDUP_Prot_Information* Prot_Information ); IDUP_Service_Creation_Info idup_alloc_service_creation_info ( OM_uint32* minor_status ); OM_uint32 idup_release_service_creation_info( OM_uint32* minor_status, IDUP_Service_Creation_Info* Service_Creation_Info ); IDUP_Service_Verification_Info idup_alloc_service_verification_info ( OM_uint32* minor_status ); OM_uint32 idup_release_service_verification_info ( OM_uint32* minor_status, IDUP_Service_Verification_Info* Service_Verification_Info ); IDUP_Services_To_Receive idup_create_empty_services_to_receive ( OM_uint32* minor_status ); Klump, Thakkar 148 Expires: November 1, 1997 OM_uint32 idup_release_services_to_receive( OM_uint32* minor_status, IDUP_Services_To_Receive* Services_To_Receive ); IDUP_Services_To_Perform idup_create_empty_services_to_perform ( OM_uint32* minor_status ); OM_uint32 idup_add_services_to_perform_member ( IDUP_Services_To_Perform Services_To_Perform, IDUP_Prot_Service Prot_Service, OM_uint32* minor_status, int* index ); OM_uint32 idup_release_services_to_perform ( OM_uint32* minor_status, IDUP_Services_To_Perform* Services_To_Perform ); IDUP_Special_Conditions idup_alloc_special_conditions ( OM_uint32* minor_status ); OM_uint32 idup_release_special_conditions( OM_uint32* minor_status, IDUP_Special_Conditions* Special_Conditions ); IDUP_Target_Info idup_alloc_target_info ( OM_uint32* minor_status ); OM_uint32 idup_release_target_info( OM_uint32* minor_status, IDUP_Target_Info* Target_Info ); IDUP_Unprot_Service idup_alloc_unprot_service ( OM_uint32* minor_status ); OM_uint32 idup_release_unprot_service ( OM_uint32* minor_status, IDUP_Unprot_Service* Unprot_Service ); #endif /* IDUP_GSS_API_H_ */ Klump, Thakkar 149 Expires: November 1, 1997