Internet Draft D. Grebovich draft-ietf-cat-idup-cbind-00.txt Bell-Northern Research Expires: September 30, 1995 March 24, 1995 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 which 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. Subsequent to being protected, the independent data unit can be transferred to the recipient(s) - or to an archive - perhaps to be processed only days or years later. 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 [RFC-1509]. TABLE OF CONTENTS 1. INTRODUCTION ................................................ 3 2. IDUP-GSS-API ROUTINES ....................................... 4 2.1. Data Types and Calling Conventions ........................ 5 2.1.1. Structured data types ................................... 5 2.1.2. Integer types ........................................... 5 2.1.3. String and similar data ................................. 6 2.1.3.1. Opaque data types ..................................... 6 2.1.3.2. Character strings ..................................... 6 2.1.4. Data Unit Identifiers ................................... 6 2.1.5. Data Unit Identifier Sets ............................... 7 2.1.6. Credentials ............................................. 7 2.1.7. Environments ............................................ 8 2.1.8. Authentication tokens ................................... 8 2.1.9. Status values ........................................... 8 2.1.9.1. IDUP-GSS status codes ................................. 8 2.1.9.2. Mechanism-specific status codes ....................... 11 2.1.10. Names .................................................. 11 2.1.11. Optional parameters .................................... 12 2.1.11.1. gss_buffer_t types ................................... 12 2.1.11.2. Integer types (input) ................................ 12 2.1.11.3. Integer types (output) ............................... 12 2.1.11.4. Pointer types ........................................ 12 2.1.11.5. Data Unit IDs ........................................ 12 2.1.11.6. Data Unit ID Sets .................................... 12 2.1.11.7. Credentials .......................................... 12 3. IDUP-GSS-API ROUTINE DESCRIPTIONS .......................... 13 3.1. Credential management calls .............................. 13 3.2. Environment-level calls .................................. 13 3.2.1. IDUP_Establish_env ..................................... 13 3.2.2. IDUP_Abolish_env ....................................... 16 3.2.3 IDUP_Inquire_env ....................................... 17 3.3. Per-IDU calls ............................................ 18 3.3.1. IDUP_Start_Protect ...................................... 19 3.3.2. IDUP_Protect ............................................ 22 3.3.3. IDUP_End_Protect ........................................ 23 3.3.4. IDUP_Start_Unprotect .................................... 24 3.3.5. IDUP_Unprotect .......................................... 26 3.3.6. IDUP_End_Unprotect ...................................... 27 3.3.7 IDUP_Process_Receipt .................................... 28 3.4. Support calls ............................................ 30 3.4.1 IDUP_Parse_token ........................................ 30 4. ACKNOWLEDGMENTS ............................................ 31 5. SECURITY CONSIDERATIONS .................................... 31 6. REFERENCES ........................................... 31 7. AUTHOR'S ADDRESS ........................................... 31 APPENDIX - IDUP-GSS-API Example ................................ 32 Grebovich 2 Expires: September 30, 1995 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 confidentiality, integrity and 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 username 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, which is required in order that per-data-unit security services may be provided. To establish the information that is used to protect an IDU, certain IDUP-GSS-API calls will return a token data structure. The caller of the data protection IDUP-GSS-API routine is responsible for attaching the token to the data unit. This token is used, by a corresponding IDUP-GSS-API routine which will process the protected IDU, to verify the integrity, data origin authenticity and/or extract the data unit information. (c) Per-data-unit services are invoked to apply any combination of the following: (i) integrity, (ii) data origin authentication, (iii) confidentiality, The application wishing to protect an IDU will call the protect IDUP-GSS-API routines, specifying the appropriate security environment. The recipient will pass the protected IDU to the unprotecting routines to remove the protection and validate the data. (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. Grebovich 3 Expires: September 30, 1995 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. The calls are listed in Figure 1 (an asterisk marks the calls which are identical to the GSS- API specification). Figure 1 - IDUP-GSS-API Calls CREDENTIAL MANAGEMENT * GSS_Acquire_cred acquire credentials for use * GSS_Release_cred release credentials after use * GSS_Inquire_cred display information about credentials ENVIRONMENT-LEVEL CALLS IDUP_Establish_env establish IDUP environment (to protect or unprotect IDUs) IDUP_Abolish_env abolish env. when no longer needed IDUP_Inquire_env obtain environment parameters PER-IDU CALLS IDUP_Start_Protect begin the protection process IDUP_Protect protect IDU (perhaps 1 buffer at a time) IDUP_End_Protect end the protection process; create a "protect token" which contains info. necessary for the legitimate receiver(s) of the P-IDU to unprotect it IDUP_Start_Unprotect begin the unprotect process IDUP_Unprotect use the "protect token" to unprotect the P-IDU (possibly 1 buffer at a time) IDUP_End_Unprotect end the unprotect process; create a receipt token if this was requested and if underlying mechanism supports it IDUP_Process_Receipt process the receipt_token Grebovich 4 Expires: September 30, 1995 SUPPORT CALLS * GSS_Display_status translate status codes to printable form * GSS_Indicate_mechs indicate mech_types supported on local system * GSS_Compare_name compare two names for equality * GSS_Display_name translate name to printable form * GSS_Import_name convert printable name to normalized form * GSS_Release_name free storage of normalized-form name * GSS_Release_buffer free storage of printable name * GSS_Release_oid_set free storage of OID set object * GSS_Import_name_object import name from object * GSS_Export_name_object export name to object IDUP_Parse_Token examine the input token to determine mech_type and token_type 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 are encouraged to use the generic routines wherever possible on portability grounds. 2.1. Data Types and Calling Conventions The following conventions are used by the IDUP-GSS-API: 2.1.1. Structured data types Wherever these IDUP-GSS-API C-bindings describe structured data, only fields that must be provided by all IDUP-GSS-API implementation are documented. 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 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. Grebovich 5 Expires: September 30, 1995 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. All such data is passed between the IDUP-GSS-API and the caller using the gss_buffer_t data type. This data type is a pointer to a buffer descriptor, which consists of a length field that contains the total number of bytes in the datum, and a value field which contains a pointer to the actual datum: typedef struct gss_buffer_desc_struct { size_t length; void *value; } _gss_buffer_desc, *gss_buffer_t; Storage for data passed to the application by a IDUP-GSS-API routine using the gss_buffer_t conventions is allocated by the IDUP-GSS-API routine. The application may free this storage by invoking the GSS_Release_buffer routine. Allocation of the gss_buffer_desc data unit is always the responsibility of the application; unused gss_buffer_desc data units may be initialized to the value GSS_C_EMPTY_BUFFER. 2.1.3.1. Opaque data types Certain multiple-word data items are considered opaque data types at the IDUP-GSS-API, because their internal structure has no significance either to the IDUP-GSS-API or to the caller. 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. Character strings are passed between the application and the IDUP-GSS-API using the gss_buffer_t datatype, defined earlier. 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, and is used by the IDUP-GSS-API caller to select an underlying security mechanism. A value of type gss_OID has the following structure: typedef struct gss_OID_desc_struct { OM_uint32 length; void *elements; } gss_OID_desc, *gss_OID; Grebovich 6 Expires: September 30, 1995 The elements field of this structure points to the first byte of an octet string containing the ASN.1 BER encoding of the value of the gss_OID. The length field contains the number of bytes in this value. For example, the gss_OID value corresponding to {iso(1) identified- oganization(3) icd-ecma(12) member-company(2) dec(1011) cryptoAlgorithms(7) SPX(5)} meaning SPX (Digital's X.509 authentication mechanism) has a length field of 7 and an elements field pointing to seven octets containing the following octal values: 53,14,2,207,163,7,5. 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. gss_OID_set values 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. Storage associated with gss_OID_set values returned to the application by the IDUP-GSS-API may be deallocated by the GSS_Release_oid_set routine. 2.1.6. Credentials A credential handle is a caller-opaque atomic datum that identifies a IDUP-GSS-API credential data structure. It is represented by the caller-opaque type gss_cred_id_t, which may be implemented as either an arithmetic or a pointer type. Credentials describe a principal, and they give their holder the ability to act as that principal. The IDUP-GSS-API does not make the actual credentials available to applications; instead the credential handle is used to identify a particular credential, held internally by IDUP-GSS-API or underlying mechanism. Thus the credential handle contains no security-relavent information, and requires no special protection by the application. Depending on the implementation, a given credential handle may refer to different credentials when presented to the 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 Grebovich 7 Expires: September 30, 1995 handle). Possibilities for credential handle scope include the process that acquired the handle, the acquiring process and its children, or all processes sharing some local identification information (e.g., UID). If no handles exist by which a given credential may be reached, the IDUP-GSS-API may abolish the credential. Certain routines allow credential handle parameters to be omitted to indicate the use of a default credential. The mechanism by which a default credential is established and its scope should be defined by the individual IDUP-GSS-API implementation. 2.1.7. Environments The idup_env_id_t data type contains a caller-opaque atomic value that identifies one end of a IDUP-GSS-API security environment. It may be implemented as 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 association, including cryptographic state information. Individual IDUP-GSS-API implementations should define the scope of a 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 a environment should be the same as the scope of a idup_env_id_t. 2.1.8. Authentication tokens A token is a caller-opaque type that IDUP-GSS-API uses to store protection information regarding an IDU. The token is a bit-string, generated by the underlying mechanism at protection of a IDUP-GSS-API security environment for use by the security mechanism at unprotection. A token is passed between the IDUP-GSS-API and the application using the gss_buffer_t conventions. 2.1.9. Status values One or more status codes are returned by each IDUP-GSS-API routine. Two distinct sorts of status codes are returned. These are termed GSS status codes and Mechanism status codes. 2.1.9.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. The errors that can be indicated via a IDUP-GSS status code are 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). Grebovich 8 Expires: September 30, 1995 An IDUP-GSS status code can indicate a single fatal generic API error from the routine and a single calling error. In addition, supplementary status information may be indicated via the setting of bits in the supplementary info field of a IDUP-GSS status code. These errors are encoded into the 32-bit GSS status code as follows: MSB LSB |------------------------------------------------------------| | Calling Error | Routine Error | Supplementary Info | |------------------------------------------------------------| Bit 31 24 23 16 15 0 Hence if a IDUP-GSS-API routine returns a 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 or not the upper 16 bits indicate a failure or a success, the routine may indicate additional information by setting bits in the supplementary info field of the status code. The meaning of individual bits is listed below in Table 3. 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. Table 2 - Routine Errors Name Value in Meaning Field GSS_S_BAD_BINDINGS 1 NOT APPLICABLE TO IDUP GSS_S_BAD_MECH 2 unsupported mechanism requested GSS_S_BAD_NAME 3 invalid name provided GSS_S_BAD_NAMETYPE 4 name of unsupported type provided GSS_S_BAD_STATUS 5 invalid input status selector GSS_S_BAD_SIG 6 token had invalid signature GSS_S_CONTEXT_EXPIRED 7 specified security context expired GSS_S_CREDENTIALS_EXPIRED 8 expired credentials detected GSS_S_DEFECTIVE_CREDENTIAL 9 defective credential detected GSS_S_DEFECTIVE_TOKEN 10 defective token detected GSS_S_FAILURE 11 failure, unspecified at GSS-API level GSS_S_NO_CONTEXT 12 NOT APPLICABLE TO IDUP GSS_S_NO_CRED 13 no valid credentials provided Grebovich 9 Expires: September 30, 1995 GSS_S_BAD_QOP 14 unsupported QOP value IDUP_S_BAD_TARG_INFO 15 Target information is invalid or unsuitable for IDU protection. IDUP_S_BAD_DIGEST_ALG 16 Requested digest algorithm unsupported. IDUP_S_BAD_CONF_ALG 17 Requested conf. algorithm unsupported. IDUP_S_BAD_ENC_IDU 18 Encrypted IDU is defective/invalid algorithm unsupported. IDUP_S_NO_ENV 19 No environment recognized for env_handle IDUP_S_UNKNOWN_OPER_ID 20 Requested operation id. unsupported Table 3 - Supplementary Status Bits Name Bit Number Meaning GSS_S_COMPLETE 0 (LSB) Normal completion GSS_S_CONTINUE_NEEDED 1 Continuation call to routine required GSS_S_DUPLICATE_TOKEN 2 NOT APPLICABLE TO IDU-P GSS_S_OLD_TOKEN 3 NOT APPLICABLE TO IDU-P GSS_S_UNSEQ_TOKEN 4 NOT APPLICABLE TO IDU-P GSS_S_GAP_TOKEN 5 NOT APPLICABLE TO IDU-P IDUP_S_RECEIPTS_UNAVAIL 6 Mechanism does not support receipts 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 3 in the routine error field) is 3 << 16. The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a 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; routine errors and supplementary info should be returned via routine status values only. Grebovich 10 Expires: September 30, 1995 2.1.9.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 may remain unset in such cases. However, output parameters that are expected to return pointers to storage allocated by a routine must always set set by the routine, even in the event of an error, although in such cases the 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. 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.10. 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. GSS_Import_name may support multiple syntaxes for each supported namespace, allowing users the freedom to choose a preferred name representation. GSS_Display_name should use an implementation-chosen preferred syntax for each supported name-type. Grebovich 11 Expires: September 30, 1995 Comparison of internal-form names is accomplished via the GSS_Compare_names routine. This removes the need for the application program to understand the syntaxes of the various printable names that a given IDUP-GSS-API implementation may support. Storage is allocated by routines that return gss_name_t values. A procedure, GSS_Release_name, is provided to free storage associated with a name. 2.1.11. Optional parameters Various parameters are described as optional. This means that they follow a convention whereby a default value may be requested. The following conventions are used for omitted parameters. These conventions apply only to those parameters that are explicitly documented as optional. 2.1.11.1. gss_buffer_t types Specify GSS_C_NO_BUFFER as a value. For an input parameter this signifies that default behavior is requested, while for an output parameter it indicates that the information that would be returned via the parameter is not required by the application. 2.1.11.2. Integer types (input) Individual parameter documentation lists values to be used to indicate default actions. 2.1.11.3. Integer types (output) Specify NULL as the value for the pointer. 2.1.11.4. Pointer types Specify NULL as the value. 2.1.11.5. Object IDs Specify GSS_C_NULL_OID as the value. 2.1.11.6. Object ID Sets Specify GSS_C_NULL_OID_SET as the value. 2.1.11.7. Credentials Specify GSS_C_NO_CREDENTIAL to use the default credential handle. Grebovich 12 Expires: September 30, 1995 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 replaces the calls gss_init_sec_environment(), gss_accept_sec_environment(), gss_delete_sec_environment(), gss_process_Environment_token() and gss_environment_time() which are specified in [RFC-1508 and RFC- 1509]. 3.2.1. IDUP_Establish_env OM_uint32 IDUP_Establish_env ( gss_cred_id_t claimant_cred_handle, gss_OID req_mech_type, int time_req, int req_flag, OM_uint32 * minor_status, idup_env_id_t * env_handle, gss_OID * actual_mech_type, int * time_rec, int * ret_flags) Purpose: Initiates the establishment of a security environment by the application. The values returned via the ret_flags parameters are not defined unless the routine returns GSS_S_COMPLETE. Parameters: claimant_cred_handle gss_cred_id_t, read, optional handle for credentials claimed. Supply GSS_C_NO_CRED to use default credentials. req_mech_type OID, read, optional Object ID of desired mechanism. Supply GSS_C_NULL_OID to obtain an implementation specific default time_req integer, read, optional Indicates lifetime requested for environment. Grebovich 13 Expires: September 30, 1995 req_flags integer, read Contains three flags which request that the environment support specific service options: GSS_C_CONF_FLAG True - Confidentiality service requested by calling protect routine False - No confidentiality service (via protect) requested. Protect will provide data-origin authentication and/or integrity services only. GSS_C_INTEG_FLAG True - Integrity service requested by calling protect routine. False - IDU integrity service not requested. IDUP_C_RECEIPT_REQ_FLAG True - Receipts requested, i.e. initiator wishes to obtain a proof of receipt (of an IDU which it protected in the established environment) from one or more of the intended recipients of that P-IDU False - Receipts not requested 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. time_rec integer, modify, optional Indicates actual lifetime for environment. ret_flags bit-mask, modify Contains three independent flags, each of which indicates that the environment supports a specific service option. Symbolic names are provided for each flag, and the symbolic names corresponding to the required flags should be logically-ANDed with the ret_flags value to test whether a given option is supported by the environment. The flags are: Grebovich 14 Expires: September 30, 1995 GSS_C_CONF_FLAG True - Confidentiality service may be invoked by calling protect routine False - No confidentiality service (via protect) available. Protect will provide data-origin authentication and/or integrity services only. GSS_C_INTEG_FLAG True - Integrity service may be invoked by calling protect routine. False - IDU integrity service unavailable. IDUP_C_RECEIPT_AVAIL_FLAG True - Receipts available, i.e. initiator may be able to obtain a proof of receipt (of an IDU which it protected in the established environment) from one or more of the intended recipients of that P- IDU False - Receipts not available Function value: GSS status code: GSS_S_COMPLETE indicates that environment-level information was successfully initialized, and that data unit processing can begin on the newly-established environment. 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 was 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_NAMETYPE indicates that the provided targ_names are of a type uninterpretable or unsupported by the supporting IDUP-GSS-API implementation, 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. Grebovich 15 Expires: September 30, 1995 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 3.2.2 IDUP_Abolish_env OM_uint32 IDUP_Abolish_env ( idup_env_id_t * env_handle, OM_uint32 * minor_status) Purpose: Abolish a security environment. IDUP_Abolish_env will abolish the local data structures associated with the specified security environment. No further security services may be obtained using the environment specified by environment_handle. 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 environment_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 Grebovich 16 Expires: September 30, 1995 3.2.3 IDUP_Inquire_env OM_uint32 IDUP_Inquire_env ( idup_env_id_t env_handle, OM_uint32 * minor_status, int * lifetime_rec, gss_OID * mech_type, int * ret_flags) Purpose: This call is used to extract information describing characteristics of a security context. Parameters: env_handle idup_env_id_t, read, optional environment handle identifying environment used. minor_status integer, modify mechanism specific status code. lifetime_rec integer, modify in seconds, or reserved value for INDEFINITE mech_type OID, modify, optional the mechanism supporting this security environment ret_flags bit-mask, modify Contains three independent flags, each of which indicates that the environment supports a specific service option. Symbolic names are provided for each flag, and the symbolic names corresponding to the required flags should be logically- ANDed with the ret_flags value to test whether a given option is supported by the environment. The flags are: GSS_C_CONF_FLAG True - Confidentiality service may be invoked by calling protect routine False - No confidentiality service (via protect) available. Protect will provide data-origin authentication and/or integrity services only. GSS_C_INTEG_FLAG True - Integrity service may be invoked by calling protect routine. False - IDU integrity service unavailable. Grebovich 17 Expires: September 30, 1995 IDUP_C_RECEIPT_AVAIL_FLAG True - Receipts available, i.e. initiator may be able to obtain a proof of receipt (of an IDU which it protected in the established environment) from one or more of the intended recipients of that P-IDU False - Receipts not available 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_ENV_EXPIRED indicates that the provided input env_handle is recognized, but that the referenced environment has expired. Return values other than major_status and minor_status are undefined. GSS_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 GSS- API level. Return values other than major_status and minor_status are undefined. 3.3 Per-IDU Calls This group of calls is used to perform IDU protection processing on an established IDUP environment. Some of these calls may block pending network interactions (depending on the underlying mechanism in use). These calls may be invoked by a data unit's protector or by the P-IDU's recipient. The two sets of members of this group form a pair; the output from the protection set is properly input to the unprotection set. Grebovich 18 Expires: September 30, 1995 3.3.1. IDUP_Start_Protect OM_uint32 IDUP_Start_Protect ( idup_env_id_t env_handle, int digest_req_flag, int conf_req_flag, int qop_req, idup_name_t_set targ_names, int receipt_req_flag, idup_name_t_set receipts_from, idup_name_t_set receipts_to, int prot_oper_id, OM_uint32 * minor_status, int * digest_state, int * conf_state, idup_name_t_set bad_targ_names) Purpose: Using the security environment referenced by env_handle, establish 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 digest_req_flag boolean, read True - the caller requests the data origin authentication and/or data integrity services be applied to the data unit buffers False - data origin authentication and integrity services not requested conf_req_flag boolean, read True - the caller requests the data confidentiality service be applied to the data unit buffers False - data confidentiality service is not requested qop_req integer, read Specifies requested quality of protection. Callers are encouraged, on portability grounds, to accept the default quality of protection offered by the chosen mechanism, which may be requested by specifying GSS_C_QOP_DEFAULT for this parameter. If an unsupported protection strength is requested, IDUP_Start_Protect will return a major_status of GSS_S_FAILURE. Grebovich 19 Expires: September 30, 1995 Zero specifies default QOP (which is defined to specify the integrity service only).. NOTE: Choice of the QOP value determines whether non-repudiation services should be supported for a data unit. targ_names idup_name_t_set, read Indicates a list of names which will be recipients to the P-IDU. receipt_req_flag boolean, modify Indicates a request to receive receipts. receipts_from idup_name_t_set, read Indicates a list of names that receipts are expected from. receipts_to idup_name_t_set, read Indicates a list of names that receipts are to be delivered to prot_oper_id integer, read For those mechanisms which allow or require multiple stages of processing, each producing a different aspect of protection for the data data unit, this parameter is used to specify which stage is currently being requested by the application, e.g., as in a mechanism which implements the signed Message Security Protocol [MSP]. minor_status integer, modify Implementation specific status code digest_state boolean, modify True - data origin authentication and/or data integrity services are applied to the data unit buffers False - data origin authentication and/or data integrity services are not applied to the data unit buffers conf_state boolean, modify True - confidentiality is applied to the data unit buffers False - confidentiality is not applied to the data unit buffers bad_targ_names idup_name_t_set, modify Indicates a list of names that cannot be used as recipients. Grebovich 20 Expires: September 30, 1995 i Function value: GSS status code: GSS_S_COMPLETE indicates that the protection process can begin. 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_ENV_EXPIRED indicated that the provided input env_handle is recognized, but that the referenced environment has expired. Return values other than major_status and minor_status are undefined. IDUP_S_NO_ENV indicates that no valid environment was recognized for the env_handle provided. IDUP_S_BAD_DIGEST_ALG indicates that the digest algorithm specified is unavailable in the requested mechanism, so processing cannot continue. 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_CONF_ALG indicates that the confidentiality algorithm specified is unavailable in the requested mechanism, so processing cannot continue. IDUP_S_BAD_TARG_INFO indicates that the information regarding the target(s) is invalid or is insufficient for the protection of an IDU, so prot_token cannot be created. IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism does not support the generation of receipts by the unprotection set of calls. 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. Grebovich 21 Expires: September 30, 1995 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 environment_handle, continue the protection processing on the data in input_buffer and, if confidentially was requested in IDUP_Start_Protect(), put the result in output_buffer. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used input_buffer octet string, read IDU buffer minor_status integer, modify Implementation specific status code output_buffer buffer, opaque, modify Protected data unit buffer Function value: GSS status codes: GSS_S_COMPLETE indicates that the input_buffer has successfully been included in the protection computation. 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 required operation could not be performed for reasons unspecified at the IDUP-GSS-API level. Grebovich 22 Expires: September 30, 1995 3.3.3. IDUP_End_Protect OM_uint32 IDUP_End_Protect ( idup_env_id_t env_handle, OM_uint32 * minor status, gss_buffer_t output_buffer, gss_buffer_t prot_token) Purpose: Using the security environment referenced by environment_handle, complete the protection processing on the data and place the result in prot_token. 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. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used minor_status integer, modify Implementation specific status code output_buffer buffer, opaque, modify Protected data unit buffer prot_token buffer, opaque, modify Protect token 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 confidentiality was requested in IDUP_Start_Protect(), output_buffer will contain any residual ciphertext. 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. Grebovich 23 Expires: September 30, 1995 IDUP_S_BAD_TARG_INFO indicates that the information regarding the target(s) is invalid or is insufficient for the protection of a data unit, so prot_token cannot be created. IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism does support the generation of receipts by the unprotection set of calls. 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. 3.3.4. IDUP_Start_Unprotect OM_uint32 IDUP_Start_Unprotect ( idup_env_id_t env_handle, gss_buffer_t prot_token, int prot_oper_id, OM_uint32 * minor_status, int conf_state, int digest_state, int qop_state, gss_buffer_t originator_info) Purpose: Using the security environment referenced by environment_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. prot_token buffer, opaque, read Protect token. prot_oper_id integer, read For those mechanisms which allow or require multiple stages of processing, each producing a different aspect of protection for the data unit, this parameter is used to specify which stage is currently being requested by the application, e.g., as in a mechanism which implements the signed Message Security Protocol [MSP]. Grebovich 24 Expires: September 30, 1995 minor_status integer, modify Implementation specific status code conf_state boolean, modify True - confidentiality is applied to the data unit buffers False - confidentiality is not applied to the data unit buffers digest_state boolean, modify True - data origin authentication and/or data integrity services are applied to the data unit buffers False - data origin authentication and/or data integrity services are not applied to the data unit buffers NOTE: Confidentiality and authentication/integrity may not be supported in all mech_types or by all implementations; the returned conf_state and digest_state flags indicate whether confidentiality or authentication/integrity, or both, has been applied to the data unit. qop_state integer, modify Specifies quality of protection which was applied to the P- IDU. If an unsupported protection strength was applied, IDUP_Start_Unprotect will return a major_status of GSS_S_FAILURE. originator_info buffer, modify if underlying mechanism supports it, contains return information regarding the originator Function value: GSS status codes: GSS_S_COMPLETE indicates that unprotection processing can begin. GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed on the received prot_token failed, preventing further processing from being performed with that token. Grebovich 25 Expires: September 30, 1995 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_ENV_EXPIRED indicates that the provided input env_handle is recognized, but that the referenced environment has expired. Return values other than major_status and minor_status are undefined. GSS_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. IDUP_S_BAD_DIGEST_ALG indicates that the digest algorithm specified in prot_token is unavailable in the local mechanism, so processing cannot continue. IDUP_S_BAD_CONF_ALG indicates that the confidentiality algorithm specified in prot_token is unavailable in the local mechanism, so processing cannot continue. 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. 3.3.5. IDUP_Unprotect OM_uint32 IDUP_Unprotect ( idup_env_id_t environment_handle, gss_buffer_t input buffer, OM_uint32 * minor status, gss_buffer_t output_buffer) Purpose: Using the security environment referenced by environment_handle, continue the unprotect processing on the data in input_buffer. If confidentiality was applied to the data unit, put the decrypted data in output_buffer. Grebovich 26 Expires: September 30, 1995 Parameters: environment_handle idup_env_id_t, rea Environment handle identifying environment used. input_buffer octet string, opaque, read 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 input_buffer has successfully been included in the unprotection computation. 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_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. 3.3.6. IDUP_End_Unprotect OM_uint32 IDUP_End_Unprotect ( idup_env_id_t env_handle, OM_uint32 * minor status, gss_buffer_t output_buffer, gss_buffer_t receipt_token) Purpose: Using the security environment referenced by environment_handle, complete the unprotect processing on the data and return the appropriate status code. Grebovich 27 Expires: September 30, 1995 Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used minor_status integer, modify Implementation specific status code output_buffer buffer, modify Unprotected data unit buffer. receipt_token buffer, opaque, modify Receipt token in a form suitable for immediate transfer back to the sender of the protected data unit. Function value: GSS status codes: GSS_S_COMPLETE indicates that the unprotect computation was successful. If confidentiality was applied to the data unit, output_buffer will contain any residual plaintext. GSS_S_BAD_SIG indicates that the received prot_token contains an incorrect digest for the data. 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_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_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. 3.3.7 IDUP_Process_Receipt OM_uint32 IDUP_Process_Receipt ( idup_env_id_t env_handle, gss_buffer_t receipt_token, OM_uint32 * minor status, gss_buffer_t originator_info) Grebovich 28 Expires: September 30, 1995 Purpose: Using the security environment referenced by environment_handle, initialize the data structures required to process the received receipt_token and return the appropriate status value. Parameters: env_handle idup_env_id_t, read Environment handle identifying environment used receipt_token gss_buffer_t, read Received receipt_token. minor_status integer, modify Implementation specific status code originator_info gss_buffer_t, modify Information regarding the creator of the receipt_token may be returned in originator_info, if the underlying mechanism supports it. Function value: GSS status codes: GSS_S_COMPLETE indicates that receipt processing was successful. GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed on the received receipt_token failed, preventing further processing from being performed with that token. IDUP_S_ENV_EXPIRED indicates that the provided env_handle is recognized, but that the referenced environment has expired. Return values other than major_status and minor_status are undefined. IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism does not support the generation of receipts by the unprotection set of calls. 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. Grebovich 29 Expires: September 30, 1995 3.4 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.4.1 IDUP_Parse_token OMuint IDUP_Parse_token ( gss_buffer_t input_token, OM_uint32 * minor status, gss_OID * mech_type, int token_type) Purpose: IDUP_Parse_token is used to return to an application the mechanism type and token type which correspond to a given input token. Parameters: input_token gss_buffer_t, read Input token from the protect call. minor_status OM_uint32, modify Implementation specific status code. mech_type gss_OID, modify The mechanism that was used to create the input_token. token_type int, modify Type of the input_token. Function value: GSS status code: GSS_S_COMPLETE indicates that the input_token could be parsed for both fields. The resulting values are stored in mech_type and token_type. GSS_S_DEFECTIVE_TOKEN indicates that the mechanism type could be parsed, but that either the token type could not be determined from the input token, or the value determined did not correspond to any valid token_type. GSS_S_FAILURE indicates that the mechanism type could not be parsed (e.g., the token may be corrupted). Grebovich 30 Expires: September 30, 1995 4. ACKNOWLEDGMENTS I would like to thank 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. 5. SECURITY CONSIDERATIONS Security issues are discussed throughout this memo. 6. REFERENCES [IDUP] Independent Data Unit Protection Generic Security Service Application Program Interface, Internet Draft, C. Adams, March 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. 7. AUTHOR'S ADDRESS Dragan Grebovich Bell-Northern Research, Ltd. P.O.Box 3511, Station C Ottawa, Ontario, CANADA K1Y 4H7 Phone: +1 (613) 765-3524 E-mail: dragan@bnr.ca Grebovich 31 Expires: September 30, 1995 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 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_t_set_desc_struct { int count; gss_name_t elements; } idup_name_t_set_desc, *idup_name_t_set; /* * Seven independent flags each of which indicates that a environment * supports a specific service option. */ #define GSS_C_DELEG_FLAG 1 #define GSS_C_MUTUAL_FLAG 2 #define GSS_C_REPLAY_FLAG 4 #define GSS_C_SEQUENCE_FLAG 8 #define GSS_C_CONF_FLAG 16 #define GSS_C_INTEG_FLAG 32 #define IDUP_C_RECEIPT_REQ_FLAG 64 Grebovich 32 Expires: September 30, 1995 /* * 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_CONTEXT ((idup_env_id_t) 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. */ #define GSS_C_QOP_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 Grebovich 33 Expires: September 30, 1995 /* * The macros that test status codes for error conditions */ #define GSS_CALLING_ERROR(x) \ (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) #define GSS_ROUTINE_ERROR(x) \ (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) #define GSS_SUPPLEMENTARY_INFO(x) \ (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) #define GSS_ERROR(x) \ ((GSS_CALLING_ERROR(x) != 0) || (GSS_ROUTINE_ERROR(x) != 0)) /* * Now the actual status code definitions */ /* * Calling errors: */ #define GSS_S_CALL_INACCESSIBLE_READ \ (1ul << GSS_C_CALLING_ERROR_OFFSET) #define GSS_S_CALL_INACCESSIBLE_WRITE \ (2ul << GSS_C_CALLING_ERROR_OFFSET) #define GSS_S_CALL_BAD_STRUCTURE \ (3ul << GSS_C_CALLING_ERROR_OFFSET) /* * Routine errors: */ #define GSS_S_BAD_BINDINGS (1ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_BAD_MECH (2ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_BAD_NAME (3ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_BAD_NAMETYPE (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_CONTEXT_EXPIRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_CREDENTIALS_EXPIRED (8ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_DEFECTIVE_CREDENTIAL (9ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_DEFECTIVE_TOKEN (10ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_FAILURE (11ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_NO_CONTEXT (12ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_NO_CRED (13ul << GSS_C_ROUTINE_ERROR_OFFSET) #define GSS_S_BAD_QOP (14ul << GSS_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_BAD_TARG_INFO (15ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_BAD_DIGEST_ALG (16ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_BAD_CONF_ALG (17ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_BAD_ENC_IDU (18ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_NO_ENV (19ul << IDUP_C_ROUTINE_ERROR_OFFSET) #define IDUP_S_UNKNOWN_OPER_ID (20ul << IDUP_C_ROUTINE_ERROR_OFFSET) Grebovich 34 Expires: September 30, 1995 /* * 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_RECEIPTS_UNAVAIL \ (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 5)) /* * Finally, function prototypes for the IDUP-GSS-API routines. */ OM_uint32 IDUP_Establish_env (gss_cred_id_t /* claimant_cred_handle */ gss_OID /* mech_type */ int /* time_req */ int /* req_flag */ OM_uint32 * /* minor_status */ idup_env_id_t * /* env_handle */ gss_OID * /* mech_type */ int * /* time_rec */ int * /* ret_flags */ ) 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 */ int * /* lifetime_rec */ gss_OID * /* mech_type */ int * /* ret_flags */ ) OM_uint32 IDUP_Start_Protect ( (idup_env_id_t /* env_handle */ int /* digest_req_flag */ int /* conf_req_flag */ int /* qop_req */ idup_name_t_set /* targ_names */ int /* receipt_req_flag */ idup_name_t_set /* receipts_from */ idup_name_t_set /* receipts_to */ int /* prot_oper_id */ OM_uint32 * /* minor_status */ int * /* digest_state */ int * /* conf_state */ idup_name_t_set /* bad_targ_names */ ) Grebovich 35 Expires: September 30, 1995 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 */ gss_buffer_t /* output_buffer */ gss_buffer_t /* prot_token */ ) OM_uint32 IDUP_Start_Unprotect (idup_env_id_t /* env_handle */ gss_buffer_t /* prot_token */ int /* prot_oper_id */ OM_uint32 * /* minor_status */ int /* conf_state */ int /* digest_state */ int /* qop_state */ gss_buffer_t /* originator_info */ ) OM_uint32 IDUP_Unprotect (idup_env_id_t /* environment_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 */ gss_buffer_t /* output_buffer */ gss_buffer_t /* receipt_token */ ); OM_uint32 IDUP_Process_Receipt (idup_env_id_t /* env_handle */ gss_buffer_t /* receipt_token */ OM_uint32 * /* minor status */ gss_buffer_t /* originator_info */ ); 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 */ ); Grebovich 36 Expires: September 30, 1995 OM_uint32 GSS_Indicate_mechs (OM_uint32*, /* minor_status */ gss_OID_set* /* mech_set */ ); OM_uint32 GSS_Compare_name (OM_uint32*, /* minor_status */ gss_name_t, /* name1 */ gss_name_t, /* name2 */ int* /* name_equal */ ); OM_uint32 GSS_Display_name, (OM_uint32*, /* minor_status */ gss_name_t, /* input_name */ gss_buffer_t, /* output_name_buffer */ gss_OID* /* output_name_type */ ); OM_uint32 GSS_Import_name (OM_uint32*, /* minor_status */ gss_buffer_t, /* input_name_buffer */ gss_OID, /* input_name_type */ gss_name_t* /* output_name */ ); OM_uint32 GSS_Release_name (OM_uint32*, /* minor_status */ gss_name_t* /* input_name */ ); OM_uint32 GSS_Release_buffer (OM_uint32*, /* minor_status */ gss_buffer_t /* buffer */ ); OM_uint32 GSS_Release_oid_set (OM_uint32*, /* minor_status */ gss_OID_set* /* set */ ); OMuint IDUP_Parse_token (gss_buffer_t /* input_token */ OM_uint32 * /* minor status */ gss_OID * /* mech_type */ int /* token_type */ ) /* * IDUP Token Types */ #define IDUP_PROT_TOKEN 1 #define IDUP_RECEIPT_TOKEN 2 #endif /* IDUP-GSS-API_H_ * Grebovich 37 Expires: September 30, 1995