Internet Draft C. Adams, Bell-Northern Research draft-ietf-cat-idup-gss-01.txt March 31, 1995 Independent Data Unit Protection Generic Security Service Application Program Interface (IDUP-GSS-API) 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 IDUP-GSS-API (previously known as IOP-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 data unit can be transferred to the recipient(s) - or to an archive - perhaps to be processed only days or years later. Throughout the remainder of this document, the "unit" of data described in the above paragraph will be referred to as an IDU (Independent Data Unit). The IDU can be of any size (the application may, if it wishes, split the IDU into pieces and have the protection computed a piece at a time, but the resulting protection token applies to the entire IDU). However, the primary characteristic of an IDU is that it represents a stand-alone unit of data whose protection is entirely independent of any other unit of data. If an application protects several IDUs and sends them all to a single receiver, the IDUs may be unprotected by that receiver in any order over any time span; no logical connection of any kind is implied by the protection process itself. Adams Document Expiration: 30 Sept. 1995 1 As with RFC-1508, this IDUP-GSS-API definition provides security services to callers in a generic fashion, supportable with a range of underlying mechanisms and technologies and hence allowing source- level portability of applications to different environments. This specification defines IDUP-GSS-API services and primitives at a level independent of underlying mechanism and programming language environ- ment, and is to be complemented by other, related specifications: - documents defining specific parameter bindings for particular language environments; - documents defining token formats, protocols, and procedures to be implemented in order to realize IDUP-GSS-API services atop particular security mechanisms. TABLE OF CONTENTS 1. IDUP-GSS-API Characteristics and Concepts ................... 3 1.1. IDUP-GSS-API Constructs ................................... 4 1.1.1. Credentials ............................................ 4 1.1.2. Tokens ................................................. 4 1.1.3. Security Environment ................................... 5 1.1.4. Mechanism Types ........................................ 5 1.1.5. Naming ................................................. 5 1.1.6. Channel Bindings ....................................... 5 1.2. IDUP-GSS-API Features and Issues ......................... 5 1.2.1. Status Reporting ....................................... 5 1.2.2. Per-IDU Security Service Availability .................. 6 1.2.3. Per-IDU Replay Detection and Sequencing ................ 6 1.2.4. Quality of Protection .................................. 6 2. Interface Descriptions ...................................... 7 2.1. Credential management calls .............................. 8 2.1.1. Relationship to GSS-API ................................ 8 2.2. Environment-level calls .................................. 8 2.2.1. Relationship to GSS-API ................................ 8 2.2.2. IDUP_Establish_Env call ................................ 9 2.2.3. IDUP_Abolish_Env call .................................. 11 2.2.4. IDUP_Inquire_Env call .................................. 11 2.3. Per-IDU calls ............................................ 12 2.3.1. Relationship to GSS-API ................................ 12 2.3.2. IDUP_Start_Protect ..................................... 13 2.3.3. IDUP_Protect ........................................... 15 2.3.4. IDUP_End_Protect ....................................... 15 2.3.5. IDUP_Start_Unprotect ................................... 16 2.3.6. IDUP_Unprotect ......................................... 18 2.3.7. IDUP_End_Unprotect ..................................... 18 2.3.8. IDUP_Process_Receipt ................................... 19 2.4. Support calls ............................................ 20 2.4.1. Relationship to GSS-API ................................ 20 2.4.2. IDUP_Parse_token call .................................. 20 3. Mechanism-Specific Example Scenarios ........................ 22 3.1. PEM-compliant file protection ............................ 22 3.2. Signed-MSP-compliant file protection ..................... 23 4. Related Activities .......................................... 23 5. Acknowledgments ............................................. 24 6. Security Considerations ..................................... 24 7. References ............................................ 24 8. Author's Address ............................................ 24 Appendix A, B .................................................. 25 Adams Document Expiration: 30 Sept. 1995 2 1. IDUP-GSS-API Characteristics and Concepts The operational paradigm in which IDUP-GSS-API operates is as follows. An IDUP-GSS-API caller is any application which works with IDUs, calling on IDUP-GSS-API in order to protect its IDUs with origin authentication, integrity, confidentiality, and/or (support for) non-repudiation security services. An IDUP-GSS-API caller accepts tokens provided to it by its local IDUP-GSS-API implementation, logically concatenates the token(s) and the IDU to create a protected IDU (P-IDU), and transfers the P-IDU to a peer or to any storage medium. When the P-IDU is to be "unprotected", the token(s) and the IDU must be passed to an IDUP-GSS-API implementation for processing. The security services available through IDUP-GSS-API in this fashion are implementable over a range of underlying mechanisms based on secret-key and public-key cryptographic technologies. Note that the protecting application may choose whatever method it wishes to concatenate or combine the token(s) and the IDU into a P-IDU, but the unprotecting application must know how to de-couple the P-IDU back into its component parts prior to calling the IDUP unprotection set of functions. The IDUP-GSS-API separates the operation of initializing a security environment (the IDUP_Establish_Env() call) from the operations of providing per-IDU protection, for IDUs subsequently protected in conjunction with that environment. Per-IDU protection and unprotection calls provide the data origin authentication / data integrity services, or confidentiality services, or both, as a caller option. Additional calls provide supportive functions to the IDUP-GSS-API's users. The following paragraphs provide an example illustrating the dataflows involved in use of the IDUP-GSS-API by the sender and receiver of a P-IDU in a mechanism-independent fashion. The example assumes that credential acquisition has already been completed by both sides. The sender first calls IDUP_Establish_Env() to establish a security environment. Then, for the IDU to be protected the sender calls IDUP_Start_Protect(), IDUP_Protect() for each buffer of data, and IDUP_End_Protect() to complete the IDU protection. The prot_token output by IDUP_End_Protect() and the IDU (which had confidentiality applied if this was requested in IDUP_Start_Protect()) are logically concatenated to form the P-IDU, which is now ready to be sent to the target. The sender then calls IDUP_Abolish_Env() to flush all environment-specific information. The receiver first calls IDUP_Establish_Env() to establish a security environment for unprotecting P-IDUs. Then, for the received P-IDU the receiver calls IDUP_Start_Unprotect(), IDUP_Unprotect() for each buffer of data, and IDUP_End_Unprotect() to complete the P-IDU unprotection. The receiver then calls IDUP_Abolish_Env() to flush all environment-specific information. Adams Document Expiration: 30 Sept. 1995 3 It is important to note that absolutely no synchronization is implied or expected between the data buffer size used by the sender as input to the protection calls, the data buffer size used by the receiver as input to the unprotection calls, and the block sizes required by the underlying protection algorithms (integrity and confidentiality). All these sizes are meant to be independent; furthermore, the data buffer sizes used for the protection and unprotection calls are purely a function of the local environment where the calls are made. The IDUP-GSS-API design assumes and addresses several basic goals, including the following. Mechanism independence: The IDUP-GSS-API defines an interface to cryptographically implemented security services at a generic level which is independent of particular underlying mechanisms. For example, IDUP-GSS-API-provided services can be implemented by secret-key technologies or public-key approaches. Protocol environment independence: The IDUP-GSS-API is independent of the communications protocol suites which may be used to transfer P-IDUs, permitting use in a broad range of protocol environments. Protocol association independence: The IDUP-GSS-API's security environment construct is independent of communications protocol association constructs, so that IDUP-GSS-API services can be invoked by applications, wholly independent of protocol associations. Suitability for a range of implementation placements: IDUP-GSS-API clients are not constrained to reside within any Trusted Computing Base (TCB) perimeter defined on a system where the IDUP-GSS-API is implemented; security services are specified in a manner suitable for both intra-TCB and extra-TCB callers. 1.1. IDUP-GSS-API Constructs This section describes the basic elements comprising the IDUP-GSS-API. 1.1.1. Credentials Credentials in IDUP-GSS-API are to be understood and used as described in GSS-API [RFC-1508]. 1.1.2. Tokens Tokens in IDUP-GSS-API are to be understood and used as described in GSS-API [RFC-1508] with the exception that there are no context-level tokens generated by IDUP-GSS-API. Only two tokens, prot_token and receipt_token, are defined by IDUP-GSS-API. The first is meant to be logically concatenated with an IDU prior to transfer to a target; the latter can be sent independently of any other data transfer. Adams Document Expiration: 30 Sept. 1995 4 1.1.3. Security Environment The "security environment" in IDUP-GSS-API is entirely different from the concept of security contexts used in GSS-API [RFC-1508]. Here, a security environment exists within a calling application (that is, it is purely local to the caller) for the purpose of protecting or unprotecting one or more IDUs using a particular caller credential. In GSS-API, on the other hand, a security context exists between peers (the initiator and the target) for the purpose of protecting, in real time, the data that is exchanged between them. Although they are different concepts, the IDUP_handle in IDUP-GSS-API is similar to the context_handle in GSS-API in that it is a convenient way of tying together the entire process of protecting or unprotecting one or more IDUs. As with the GSS-API security contexts, a caller can initiate and maintain multiple environments using the same or different credentials. 1.1.4. Mechanism Types Mechanism types in IDUP-GSS-API are to be understood and used as described in GSS-API [RFC-1508]. 1.1.5. Naming Naming in IDUP-GSS-API is to be understood and used as described in GSS-API [RFC-1508]. 1.1.6. Channel Bindings The concept of channel bindings discussed in GSS-API [RFC-1508] is not relevant to the IDUP-GSS-API. 1.2. IDUP-GSS-API Features and Issues This section describes aspects of IDUP-GSS-API operations and of the security services which the IDUP-GSS-API provides. It also provides commentary on design issues. 1.2.1. Status Reporting Status reporting in IDUP-GSS-API is to be understood and used as described in GSS-API [RFC-1508], with the addition of the following IDUP-GSS-API major status codes: Adams Document Expiration: 30 Sept. 1995 5 Table 1: IDUP-GSS-API Major Status Codes FATAL ERROR CODES IDUP_S_BAD_TARG_INFO target information is invalid or unsuitable for IDU protection. IDUP_S_BAD_DIGEST_ALG requested digest algorithm unsupported IDUP_S_BAD_CONF_ALG requested conf. algorithm unsupported IDUP_S_BAD_ENC_IDU encrypted IDU is defective/invalid IDUP_S_NO_ENV no environment recognized for env_handle IDUP_S_UNKNOWN_OPER_ID requested operation id. is unsupported INFORMATORY STATUS CODES IDUP_S_RECEIPTS_UNAVAIL mechanism does not support receipts 1.2.2. Per-IDU Security Service Availability Per-IDU security service availability in IDUP-GSS-API is to be understood and used as described in GSS-API [RFC-1508], with the exception that integrity or confidentiality or both can be applied to any IDU. 1.2.3. Per-IDU Replay Detection and Sequencing The concept of per-IDU replay detection and sequencing discussed in GSS-API [RFC-1508] is not relevant to the IDUP-GSS-API. 1.2.4. Quality of Protection The concept of QOP control in IDUP-GSS-API is to be understood essentially as described in GSS-API [RFC-1508]. However, the actual description and use of the QOP parameter follows that given in the Internet Draft "draft-ietf-cat-spkmgss-02.txt". This QOP description allows either mechanism-independent labels or particular algorithm labels to be specified by calling applications for both confidentiality and integrity. Adams Document Expiration: 30 Sept. 1995 6 2. Interface Descriptions This section describes the IDUP-GSS-API's service interface, dividing the set of calls offered into four groups. Credential management calls are related to the acquisition and release of credentials by API callers. Environment-level calls are related to the management of the security environment by an API caller. Per-IDU calls are related to the protection or unprotection of individual IDUs in established security environments. Support calls provide ancillary functions useful to IDUP-GSS-API callers. Table 2 groups and summarizes the calls in tabular fashion (an asterisk marks the calls which are identical to the GSS-API specification). Table 2: 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 estbablish IDUP environment (to protect and unprotect IDUs) IDUP_Abolish_Env abolish env. when no longer needed IDUP_Inquire_Env indicate characteristics of env. 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 one 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 Adams Document Expiration: 30 Sept. 1995 7 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 normalize 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 2.1. Credential management calls 2.1.1. Relationship to GSS-API Credential management in IDUP-GSS-API is to be understood and used as described in GSS-API [RFC-1508]. The calls GSS_Acquire_cred(), GSS_Release_cred(), and GSS_Inquire_cred() are unchanged. 2.2. Environment-level calls This group of calls is devoted to the establishment and management of an environment for the purpose of IDU protection and unprotection. Before protecting or unprotecting any IDU, an application must call IDUP_Establish_Env() to initialize environment information and select the underlying IDUP-GSS mechanism to be used. A series of protection or unprotection calls are made to process each IDU, resulting in a "prot_token" or a "receipt_token" (if supported) for each. Finally, IDUP_Abolish_Env() is called to flush all environment information. 2.2.1. Relationship to GSS-API The set of calls described in this section replaces 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]. Adams Document Expiration: 30 Sept. 1995 8 2.2.2. IDUP_Establish_Env call Inputs: o claimant_cred_handle CREDENTIAL HANDLE, -NULL specifies "use default" o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use default" o time_req INTEGER, o req_flags INTEGER, Outputs: o major_status INTEGER, o minor_status INTEGER, o env_handle ENVIRONMENT HANDLE, o mech_type OBJECT IDENTIFIER, -actual mechanism always indicated, never NULL o time_rec INTEGER, o ret_flags INTEGER, Return major_status codes: o GSS_S_COMPLETE indicates that environment-level information was successfully initialized, and that IDU processing can begin on the newly-established environment. o 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. o 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. o 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. o 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. o 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. Adams Document Expiration: 30 Sept. 1995 9 This routine is used by an application which protects or unprotects IDUs. Using information in the credentials structure referenced by claimant_cred_handle, IDUP_Establish_Env() initializes the data structures required to protect or unprotect an IDU. The claimant_cred_handle must correspond to a valid credentials structure. This routine returns an env_handle for all future references to this environment; when protection, unprotection, or IDUP_Abolish_Env() calls are made, this handle value will be used as the input env_handle argument. It is the caller's responsibility to establish a communications path to the intended recipients of the P-IDU, and to transmit the P-IDU to those recipients over that path. This may occur subsequent to the IDUP_Abolish_Env() call. The req_flags parameter may be used by the calling application to request that integrity, confidentiality, and/or receipt processing be available in the established environment. Requesting receipt processing indicates that the calling application may wish to obtain a proof of receipt (of an IDU which it will protect in the established environment) from one or more of the intended recipients of that P-IDU. Not all features will be available in all underlying mech_types; the returned value of ret_flags (receipts_avail, conf_avail, integ_avail) indicates, as a function of mech_type processing capabilities and the initiator-provided input flags, the set of features which will be available in the environment. These state indicators' values are undefined unless the routine's major_status indicates COMPLETE. Failure to provide the precise set of features desired by the caller does not cause environment establishment to fail; it is the caller's prerogative to abolish the environment if the feature set provided is unsuitable for the caller's use. The returned mech_type value indicates the specific mechanism employed in the environment, and will never indicate the value for "default". The conf_avail return value (in the ret_flags paramter) indicates whether the environment supports confidentiality services, and so informs the caller whether or not a request for encryption through the conf_req_flag input to IDUP_Protect() can be honored. In similar fashion, the integ_avail return value indicates whether integrity services are available in the established environment, and the receipts_avail return value indicates whether receipt generation and processing services are available. Adams Document Expiration: 30 Sept. 1995 10 2.2.3. IDUP_Abolish_Env call Input: o env_handle ENVIRONMENT HANDLE Outputs: o major_status INTEGER, o minor_status INTEGER, Return major_status codes: o GSS_S_COMPLETE indicates that the environment was recognized and that relevant environment-specific information was flushed. o IDUP_S_NO_ENV indicates that no valid environment was recognized for the env_handle provided, so no deletion was performed. o 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. 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 environment lifetime expires.) Attempts to perform IDU processing on a deleted or expired environment will result in error returns. 2.2.4: IDUP_Inquire_Env call Input: o env_handle ENVIRONMENT HANDLE, Outputs: o major_status INTEGER, o minor_status INTEGER, o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this env. o ret_flags INTEGER, o time_rec INTEGER -- in seconds Return major_status codes: o GSS_S_COMPLETE indicates that the referenced environment is valid and that mech_type, ret_flags, and time_rec return values describe the corresponding characteristics of the environment. Adams Document Expiration: 30 Sept. 1995 11 o 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. o IDUP_S_NO_ENV indicates that no valid environment was recognized for the env_handle provided, so no return values can be provided. o 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. This call is used to extract information describing characteristics of the security environment. 2.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 an IDU'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. The per-IDU calls support caller-requested confidentiality in addition to data origin authentication / data integrity / non- repudiation services. IDUP_End_Protect() outputs a token which encapsulates all the information required to unprotect the IDU. The token from IDUP_End_Protect() is passed to the target along with the IDU and is processed by the unprotection calls at that system. Unprotection performs decipherment or validation of P-IDUs (or both), as required. Note that each of the two main operations (protection and unprotection) is separated into three parts: "Start_Operation"; "Operation", called once for each buffer of input data; and "End_Operation". This separation is done for convenience since the parts require different parameters. "Start_Operation" allows the caller to specify or retrieve the algorithms (through the QOP value) used during the processing. "Operation" is concerned with the processing itself, receiving a buffer of input data and, if confidentiality is involved, returning a buffer of output data. Finally, "End_Operation" performs any required clean-up and creates the appropriate token or states whether the input token and IDU were valid. 2.3.1. Relationship to GSS-API The set of calls described in this section replaces the calls GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() -- now named GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() -- which are specified in [RFC-1508]. Adams Document Expiration: 30 Sept. 1995 12 2.3.2. IDUP_Start_Protect call Inputs: o env_handle ENVIRONMENT HANDLE, o digest_req_flag BOOLEAN, o conf_req_flag BOOLEAN, o qop_req INTEGER, -0 specifies default QOP o targ_names SEQUENCE OF INTERNAL NAME, o receipt_req_flag BOOLEAN, o receipts_from SEQUENCE OF INTERNAL NAME, -must be a subset of targ_names o receipts_to SEQUENCE OF INTERNAL NAME, o prot_oper_id INTEGER -stage of protection operation to be performed Outputs: o major_status INTEGER, o minor_status INTEGER, o digest_state BOOLEAN, o conf_state BOOLEAN, o bad_targ_names SEQUENCE OF INTERNAL NAME, Return major_status codes: o GSS_S_COMPLETE indicates that the protection process can begin. o 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. o 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. o IDUP_S_NO_ENV indicates that no valid environment was recognized for the env_handle provided. o IDUP_S_BAD_DIGEST_ALG indicates that the digest algorithm specified is unavailable in the requested mechanism, so processing cannot continue. Adams Document Expiration: 30 Sept. 1995 13 o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value is not recognized or supported in the underlying mechanism. o GSS_S_BAD_QOP indicates that the provided QOP value is not recognized or supported for the environment. o IDUP_S_BAD_CONF_ALG indicates that the confidentiality algorithm specified is unavailable in the requested mechanism, so processing cannot continue. o 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. o IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism does not support the generation of receipts by the unprotection set of calls. o 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. Using the security environment referenced by env_handle, initialize the data structures required to begin the process of protecting the IDU buffers. If the digest_req_flag is TRUE, the caller requests that data origin authentication and/or data integrity services be applied to the IDU buffers. If the conf_req_flag is TRUE, the caller requests that confidentiality be applied to the IDU buffers. 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, can be provided for the IDU. The qop_req parameter allows quality-of-protection control. Choice of the digest algorithm determines whether non-repudiation services can be supported for an IDU. For those mechanisms which allow or require multiple stages of processing, each producing a different aspect of protection for the IDU, the operation identifier prot_oper_id is used to specify which stage is currently being requested by the application. An example where this would be useful is a mechanism which implements the signed Message Security Protocol [MSP] -- see Section 3.2 for details. If one or more of the targets in targ_names cannot be used as a valid recipient of the P-IDU, these names will be returned in bad_targ_names. As long as at least one of the targets can be used, this does not cause environment establishment to fail; it is the caller's prerogative to abolish the environment if the target set which can be used is unsuitable for the caller's purposes. Adams Document Expiration: 30 Sept. 1995 14 2.3.3. IDUP_Protect call Inputs: o env_handle ENVIRONMENT HANDLE, o input_buffer OCTET STRING Outputs: o major_status INTEGER, o minor_status INTEGER, o output_buffer OCTET STRING Return major_status codes: o GSS_S_COMPLETE indicates that the input_buffer has successfully been included in the protection computation. o 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. o IDUP_S_NO_ENV indicates that no valid environment was recognized for the env_handle provided. o 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. Using the security environment referenced by env_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. 2.3.4. IDUP_End_Protect call Inputs: o env_handle ENVIRONMENT HANDLE, Outputs: o major_status INTEGER, o minor_status INTEGER, o output_buffer OCTET STRING o prot_token OCTET STRING Adams Document Expiration: 30 Sept. 1995 15 Return major_status codes: o 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. o 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. o IDUP_S_NO_ENV indicates that no valid environment was recognized for the env_handle provided. o 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. Using the security environment referenced by env_handle, complete the protection processing on the data and place the computed protection token in prot_token. Successful application of IDUP_End_Protect() does not guarantee that the corresponding unprotection set of calls can necessarily be performed successfully when the P-IDU arrives at the target. 2.3.5. IDUP_Start_Unprotect call Inputs: o env_handle ENVIRONMENT HANDLE, o prot_token OCTET STRING o prot_oper_id INTEGER -stage of unprotection operation to be performed Outputs: o major_status INTEGER, o minor_status INTEGER, o conf_state BOOLEAN -TRUE implies that conf. was applied o digest_state BOOLEAN -TRUE implies that integrity was applied o qop_state INTEGER, o originator_info OCTET STRING Adams Document Expiration: 30 Sept. 1995 16 Return major_status codes: o GSS_S_COMPLETE indicates that unprotection processing can begin. o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed on the received prot_token failed, preventing further processing from being performed with that token. o 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. o 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. o IDUP_S_NO_ENV indicates that no valid environment was recognized for the env_handle provided. o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value is not recognized or supported in the underlying mechanism. o IDUP_S_BAD_DIGEST_ALG indicates that the digest algorithm specified in prot_token is unavailable in the local mechanism, so processing cannot continue. o IDUP_S_BAD_CONF_ALG indicates that the confidentiality algorithm specified in prot_token is unavailable in the local mechanism, so processing cannot continue. o 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. Using the security environment referenced by env_handle, initialize the data structures required to begin the process of unprotecting a P-IDU. If the returned conf_state value is TRUE, then confidentiality was applied to the IDU and the confidentiality portion of qop_state specifies the algorithm which was used. Similarly, if the returned digest_state value is TRUE, then data integrity / data origin authentication services were applied to the IDU and the integrity portion of qop_state specifies the algorithm which was used. If underlying mechanism supports it and if this information is contained in prot_token, return information regarding the originator (that is, the entity which used the protection set of calls to protect this IDU) in originator_info. Adams Document Expiration: 30 Sept. 1995 17 2.3.6. IDUP_Unprotect call Inputs: o env_handle ENVIRONMENT HANDLE, o input_buffer OCTET STRING Outputs: o major_status INTEGER, o minor_status INTEGER, o output_buffer OCTET STRING Return major_status codes: o GSS_S_COMPLETE indicates that the input_buffer has successfully been included in the unprotection computation. o 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. o IDUP_S_NO_ENV indicates that no valid environment was recognized for the env_handle provided. o 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. Using the security environment referenced by env_handle, continue the unprotect processing on the data in input_buffer. If confidentiality was applied to the IDU, put the decrypted data in output_buffer. 2.3.7. IDUP_End_Unprotect call Inputs: o env_handle ENVIRONMNENT HANDLE, Outputs: o major_status INTEGER, o minor_status INTEGER, o output_buffer OCTET STRING o receipt_token OCTET STRING Adams Document Expiration: 30 Sept. 1995 18 Return major_status codes: o GSS_S_COMPLETE indicates that the unprotect computation was successful. If confidentiality was applied to the IDU, output_buffer will contain any residual plaintext. o GSS_S_BAD_SIG indicates that the received prot_token contains an incorrect digest for the data. o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU cannot be completed because the encrypted IDU was invalid/defective (for example the final block was short or had incorrect padding). o 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. o IDUP_S_NO_ENV indicates that no valid environment was recognized for the env_handle provided. o 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. Using the security environment referenced by env_handle, complete the unprotect processing on the data and return the appropriate status code. If a receipt was requested by the sender of the P-IDU (and the underlying mechanism supports this), receipt_token will contain this receipt in a form suitable for transfer back to the sender. Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the concept of error tokens since the protection and unprotection of an IDU may be separated by an indefinite amount of time and may or may not be performed by the same entity. 2.3.8. IDUP_Process_Receipt call Inputs: o env_handle ENVIRONMENT HANDLE, o receipt_token OCTET STRING Outputs: o major_status INTEGER, o minor_status INTEGER, o originator_info OCTET STRING Return major_status codes: o GSS_S_COMPLETE indicates that receipt processing was successful. Adams Document Expiration: 30 Sept. 1995 19 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed on the received receipt_token failed, preventing further processing from being performed with that token. o 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. o IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism does not support the generation or processing of receipts. o IDUP_S_NO_ENV indicates that no valid environment was recognized for the env_handle provided. o 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. Using the security environment referenced by env_handle, initialize the data structures required to process the received receipt_token and return the appropriate status value. Information regarding the creator of the receipt_token may be returned in originator_info, if the underlying mechanism supports it. 2.4. Support calls 2.4.1. Relationship to GSS-API Support calls in IDUP-GSS-API are to be understood and used as described in GSS-API [RFC-1508]. 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(), GSS_Import_name_object(), and GSS_Export_name_object() are unchanged. 2.4.2. IDUP_Parse_token call Inputs: o input_token OCTET STRING Outputs: o major_status INTEGER, o minor_status INTEGER, o mech_type OBJECT IDENTIFIER, o token_type INTEGER, Adams Document Expiration: 30 Sept. 1995 20 Return major_status codes: o 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. o 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. o GSS_S_FAILURE indicates that the mechanism type could not be parsed (for example, the token may be corrupted). IDUP_Parse_Token() is used to return to an application the mechanism type and token type which correspond to a given input token. Since IDUP-GSS-API tokens are meant to be opaque to the calling application, this function allows the application to determine information about the token without having to violate the opaqueness intention of IDUP. Of primary importance is the mechanism type, which the application can then use as input to the IDUP_Establish_Env() call in order to establish the correct environment in which to have the token processed. The token_type may be used to allow the application to determine whether to pass the token to the IDUP_Start_Unprotect() call or the IDUP_Process_Receipt() call. If all tokens are framed as suggested in RFC-1508, Appendix B (specified in the Kerberos V5 GSS mechanism [KRB5], in the SPKM GSS Mechanism [SPKM], and in this document), then any mechanism implementation should be able to return at least the mech_type parameter (the token_type parameter being NULL) for any uncorrupted input token. If the mechanism implementation whose IDUP_Parse_token() function is being called does recognize the token, it can return token_type so that the application can subsequently call IDUP_Start_Unprotect() or IDUP_Process_Receipt(). Note that no minor status return codes have been defined for this function at this time. 2.4.2.1. The token_type Output Parameter The following token types are defined: IDUP_PROT_TOKEN = 1 IDUP_RECEIPT_TOKEN = 2 Every mechanism must be able to perform the mapping from an input token to one of the above token types (for any token generated by that mechanism). Adams Document Expiration: 30 Sept. 1995 21 3. Mechanism-Specific Example Scenarios This section provides an illustrative overview of the use of a candidate mechanism type to support the IDUP-GSS-API. This discussion is intended primarily for readers familiar with the specific security technology, demonstrating how IDUP-GSS-API functions can be used and implemented by a candidate underlying mechanism. It should not be regarded as constrictive to implementations or as defining the only means through which IDUP-GSS-API functions can be realized with a particular underlying technology, and does not demonstrate all IDUP-GSS-API features. 3.1. PEM-compliant file protection A PEM-compliant IDUP-GSS-API mechanism would have as its prot_token a PEM-compliant header for a protected (encrypted and/or signed) file [RFC-1421]. A calling application wishing to encrypt and sign a data file would initiate an environment using IDUP_Establish_Env(), passing in the appropriate mech_type and a FALSE receipt_req. IDUP_Start_Protect() is called next to specify that both encryption and authentication/integrity are desired, and a QOP value is input specifying either particular algorithms to be used (if the application is aware of algorithms supported by the underlying mechanism) or "generic" values. As well, the targ_names (possibly a set of Distinguished Names) are specified at this time to be used in the construction of prot_token. Any targets which cannot be used as valid recipients (for example, because they do not have public-key certificates which can be accessed by the mechanism) are returned in bad_targ_names. The file is then encrypted and signed one buffer at a time using IDUP_Protect(). As each IDUP_Protect() call returns, the application writes output_buffer (which contains ciphertext) to the end of an output file. After the last input_buffer has been protected, the application calls IDUP_End_Protect(). Any residual ciphertext is returned in output_buffer, which is then written to the end of the output file. As well, the returned prot_token is prepended to the beginning of the output file. The output file is the "P-IDU" which can be transferred by any means to the intended recipient(s). Assuming that this is the only IDU to be protected at this time, the application abolishes the environment by calling IDUP_Abolish_Env(). The recipient of the P-IDU begins by calling IDUP_Parse_Token() to determine the mech_type of the received token (the token_type is redundant information for a PEM-compliant IDUP-GSS-API mechanism, since receipts are not defined for such a mechanism). IDUP_Establish_Env() is then called to initialize the environment. The recipient then calls IDUP_Start_Unprotect(), passing it the prot_token, IDUP_Unprotect() (once for each buffer of data), and IDUP_End_Unprotect(). Output buffers are written to an output file; after IDUP_End_Unprotect() has been called this file is the original IDU which the sender protected. The recipient then abolishes the env. by calling IDUP_Abolish_Env(). Adams Document Expiration: 30 Sept. 1995 22 3.2. Signed-MSP-compliant file protection An MSP-compliant IDUP-GSS-API mechanism would be virtually identical to the PEM-compliant mechanism described above (for details regarding MSP see [MSP]). A Signed-MSP-compliant mechanism, however, requires a signature on the MSP IDU itself -- that is, on the MSP header and the encapsulated (possibly encrypted) content. This can be achieved using the prot_oper_id parameter of the IDUP_Start_Protect() call. For example, if prot_oper_id = 1 then the protection set of calls would produce a prot_token which is the MSP header and which is then concatenated with the (possibly encrypted) IDU to create an MSP IDU. If the protection set were then called again on MSP IDU with prot_oper_id = 2, prot_token would be the signature on MSP IDU, which would be appended to MSP IDU to create the Signed-MSP IDU (i.e., the final P-IDU). MSP recognizes at least two kinds of recipients, intermediate Message Transfer Agents (MTAs) and end User Agents (UAs). An MTA may be able to validate that a Signed-MSP IDU is valid, but only end UAs should be able to retrieve MSP-protected data. Thus, the MTA would call the unprotection set of calls with prot_oper_id = 2 to verify the signature on the MSP IDU, but would be unable to successfully call the unprotection set with prot_oper_id = 1 since it would lack the proper credentials. A valid end UA (one of the specified targets of the P-IDU), on the other hand, would be able to unprotect the Signed- MSP IDU with either value of prot_oper_id. Note that a receipt generated by an MSP-compliant mechanism will be sent to the IDU protector as a receipt_token and will be processed using the IDUP_Process_Receipt() call. 4. Related Activities In order to implement the IDUP-GSS-API atop existing, emerging, and future security mechanisms, object identifiers must be assigned to candidate IDUP-GSS-API mechanisms and the name types which they support, and concrete data element formats must be defined for candidate mechanisms. Calling applications must implement formatting conventions which will enable them to distinguish IDUP-GSS-API P-IDUs from other IDUs in their environment. Concrete language bindings are required for the programming environments in which the IDUP-GSS-API is to be employed; such bindings for the C language are available in an associated draft. Adams Document Expiration: 30 Sept. 1995 23 5. Acknowledgments Many thanks are due to Warwick Ford and Paul Van Oorschot of Bell-Northern Research for a number of helpful comments. 6. Security Considerations Security issues are discussed throughout this memo. 7. REFERENCES [MSP]: U.S. National Security Agency, "Message Security Protocol", Secure Data Network System SDN.701, March 1994. [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. 8. Author's Address Carlisle Adams Bell-Northern Research P.O.Box 3511, Station C Ottawa, Ontario, CANADA K1Y 4H7 Phone: +1 613.763.9008 E-mail: cadams@bnr.ca Adams Document Expiration: 30 Sept. 1995 24 APPENDIX A MECHANISM-INDEPENDENT TOKEN FORMAT This appendix specifies a mechanism-independent level of encapsulating representation for IDUP-GSS-API tokens, incorporating an identifier of the mechanism type to be used when processing those tokens. Use of this format (with ASN.1-encoded data elements represented in BER, constrained in the interests of parsing simplicity to the Distinguished Encoding Rule (DER) BER subset defined in X.509, clause 8.7) is recommended to the designers of IDUP-GSS-API implementations based on various mechanisms, so that tokens can be interpreted unambiguously at IDUP-GSS-API peers. There is no requirement that the mechanism-specific protToken data element be encoded in ASN.1 BER. -- top-level token definition to frame different mechanisms IDUP-GSS-API DEFINITIONS ::= BEGIN MechType ::= OBJECT IDENTIFIER ProtToken ::= -- option indication done within mechanism-specific token [APPLICATION 0] IMPLICIT SEQUENCE { thisMech MechType, protToken ANY DEFINED BY thisMech -- contents mechanism-specific } ReceiptToken ::= [APPLICATION 0] IMPLICIT SEQUENCE { thisMech MechType, receiptToken ANY DEFINED BY thisMech -- contents mechanism-specific } END APPENDIX B MECHANISM DESIGN CONSTRAINTS The following constraints on IDUP-GSS-API mechanism designs are adopted in response to observed caller protocol requirements, and adherence thereto is anticipated in subsequent descriptions of IDUP-GSS-API mechanisms to be documented in standards-track Internet specifications. Use of the approach defined in Appendix A of this specification, applying a mechanism type tag to the ProtToken and the ReceiptToken (if defined), is required. Adams Document Expiration: 30 Sept. 1995 25
Datatracker
Report a datatracker bug
draft-ietf-cat-idup-gss-01
Internet-Draft
| Document | Document type |
This is an older version of an Internet-Draft that was ultimately published as RFC 2479.
Expired & archived
|
|
|---|---|---|---|
| Select version | |||
| Compare versions | |||
| Author | |||
| RFC stream |
|
||
| Other formats | |||
| Additional resources | Mailing list discussion |