Internet Draft C. Adams, Bell-Northern Research draft-ietf-cat-idup-gss-02.txt July 5, 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 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 ("unprotected") 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: 5 Jan. 1996 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 ................................................. 5 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 ..................................... 9 2.1. Credential management calls .............................. 10 2.1.1. Relationship to GSS-API ................................ 10 2.2. Environment-level calls .................................. 10 2.2.1. Relationship to GSS-API ................................ 10 2.2.2. IDUP_Establish_Env call ................................ 11 2.2.3. IDUP_Abolish_Env call .................................. 13 2.2.4. IDUP_Inquire_Env call .................................. 13 2.3. Per-IDU calls ............................................ 14 2.3.1. Relationship to GSS-API ................................ 15 2.3.2. IDUP_Start_Protect ..................................... 15 2.3.3. IDUP_Protect ........................................... 17 2.3.4. IDUP_End_Protect ....................................... 17 2.3.5. IDUP_Start_Unprotect ................................... 18 2.3.6. IDUP_Unprotect ......................................... 20 2.3.7. IDUP_End_Unprotect ..................................... 20 2.4. Special-Purpose calls .................................... 21 2.4.1. Relationship to GSS-API ................................ 21 2.4.2. IDUP_Start_Generate_Receipt ............................ 21 2.4.3. IDUP_Generate_Receipt .................................. 23 2.4.4. IDUP_End_Generate_Receipt .............................. 23 2.4.5. IDUP_Process_Receipt ................................... 24 2.4.6. IDUP_Generate_Evidence ................................. 25 2.4.7. IDUP_Process_Evidence .................................. 26 2.5. Support calls ............................................ 28 2.5.1. Relationship to GSS-API ................................ 28 2.5.2. IDUP_Parse_token call .................................. 28 Adams Document Expiration: 5 Jan. 1996 2 3. Mechanism-Specific Example Scenarios ....................... 29 3.1. PEM-compliant file protection ............................ 30 3.2. Signed-MSP-compliant file protection ..................... 31 4. Related Activities ......................................... 31 5. Acknowledgments ............................................ 32 6. Security Considerations .................................... 32 7. References ........................................... 32 8. Author's Address ........................................... 32 Appendix A, B ................................................. 33 1. IDUP-GSS-API Characteristics and Concepts The paradigm within 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 passes IDUs to, and accepts tokens from, its local IDUP-GSS-API implementation; it logically concatenates the token(s) and the IDU, thereby creating a protected IDU (P-IDU); finally, it 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/or public- key cryptographic technologies. The protecting application may choose whatever method it wishes to concatenate or combine the token(s) and the IDU into a P-IDU, provided the unprotecting application knows 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 or special-purpose 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 possibly modified IDU (i.e., the IDU with 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. Adams Document Expiration: 5 Jan. 1996 3 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. 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]. Adams Document Expiration: 5 Jan. 1996 4 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 three tokens, prot_token, receipt_token, and evidence_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 two can be sent independently of any other data transfer. 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: 5 Jan. 1996 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 o IDUP_S_BAD_AI_KEY key used for IDU origin auth. and/or IDU integrity has expired or been revoked. o IDUP_S_BAD_KE_KEY key used for key establishment between orig. and targ. has exp. or been revoked. 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 IDUP_S_NO_MATCH receipt_check and receipt_token do not match in the first eight bytes Informatory Status Codes IDUP_S_RECEIPTS_UNAVAIL mechanism does not support receipts IDUP_S_EVIDENCE_UNAVAIL mechanism does not support evidence 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 is given as follows. Adams Document Expiration: 5 Jan. 1996 6 The QOP parameter for IDUP is defined to be a 32-bit unsigned integer with the following bit-field assignments: Confidentiality Integrity 31 (MSB) 16 15 (LSB) 0 ------------------------------------|----------------------------------- | TS (5) | U(3) | IA (4) | MA (4) | TS (5) | U(3) | IA (4) | MA(4) | ------------------------------------|----------------------------------- where TS is a 5-bit Type Specifier (a semantic qualifier whose value specifies the type of algorithm which may be used to protect the corresponding IDU -- see below for details); U is a 3-bit Unspecified field (available for future use/expansion); IA is a 4-bit field enumerating Implementation-specific Algorithms; and MA is a 4-bit field enumerating Mechanism-defined Algorithms. The interpretation of the QOP parameter is as follows (note that the same procedure is used for both the confidentiality and the integrity halves of the parameter). The MA field is examined first. If it is non-zero then the algorithm used to protect the IDU is the mechanism-specified algorithm corresponding to that integer value. If MA is zero then IA is examined. If this field value is non-zero then the algorithm used to protect the IDU is the implementation- specified algorithm corresponding to that integer value. Note that use of this field may hinder portability since a particular value may specify one algorithm in one implementation of the mechanism and may not be supported or may specify a completely different algorithm in another implementation of the mechanism. Finally, if both MA and IA are zero then TS is examined. A value of zero for TS specifies the default algorithm for the established mechanism, if a default is defined in the mechanism specification (confidentiality or integrity, depending on which half of QOP is being examined). A non-zero value for TS corresponds to a particular algorithm qualifier and selects any algorithm from the mechanism specification which satisfies that qualifier (which actual algorithm is selected is an implementation choice; the calling application need not be aware of the choice made). The following TS values (i.e., algorithm qualifiers) are specified; other values may be added in the future. For the Confidentiality TS field: 00001 (1) = IDUP_SYM_ALG_STRENGTH_STRONG 00010 (2) = IDUP_SYM_ALG_STRENGTH_MEDIUM 00011 (3) = IDUP_SYM_ALG_STRENGTH_WEAK 11111 (31) = IDUP_NO_CONFIDENTIALITY Adams Document Expiration: 5 Jan. 1996 7 For the Integrity TS field: 00001 (1) = IDUP_INT_ALG_DIG_SIGNATURE 00010 (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE 11111 (31) = IDUP_NO_INTEGRITY Clearly, qualifiers such as strong, medium, and weak are debatable and likely to change with time, but for the purposes of this version of the specification we define these terms as follows. A confidentiality algorithm is "weak" if the effective key length of the cipher is 40 bits or less; it is "medium-strength" if the effective key length is strictly between 40 and 80 bits; and it is "strong" if the effective key length is 80 bits or greater. (Note that "effective key length" describes the computational effort required to break a cipher using the best-known cryptanalytic attack against that cipher.) A five-bit TS field allows up to 31 qualifiers for each of confidentiality and integrity (since "0" is reserved for "default"). This document specifies four for confidentiality and three for integrity, leaving a lot of room for future specification. Suggestions of qualifiers such as "fast", "medium-speed", and "slow" have been made, but such terms are difficult to quantify (and in any case are platform- and processor-dependent), and so have been left out of this initial specification. The intention is that the TS terms be quantitative, environment-independent qualifiers of algorithms, as much as this is possible. Use of the QOP structure as defined above is ultimately meant to be as follows. - TS values are specified at the IDUP-GSS-API level and are therefore portable across mechanisms. Applications which know nothing about algorithms are still able to choose "quality" of protection for their message tokens. - MA values are specified at the mechanism level and are therefore portable across implementations of a mechanism. - IA values are specified at the implementation level (in user documentation, for example) and are therefore typically non- portable. An application which is aware of its own mechanism implementation and the mechanism implementation of its peer, however, is free to use these values since they will be perfectly valid and meaningful for protecting IDUs between those peers. The receiver of a P-IDU must pass back to its calling application (in IDUP_Start_Unprotect()) a QOP parameter with all relevant fields set. For example, if triple-DES has been specified by a mechanism as algorithm 8, then a receiver of a triple-DES-protected P-IDU must pass to its application (QOP Confidentiality TS=1, IA=0, MA=8). In this way, the application is free to read whatever part of the QOP it understands (TS or IA/MA). Adams Document Expiration: 5 Jan. 1996 8 Furthermore, two additional QOP parameters are defined specifically for evidence generation and processing for non-repudiation purposes. Those parameters are described in Section 2.4: Special-Purpose Calls. 2. Interface Descriptions This section describes the IDUP-GSS-API's service interface, dividing the set of calls offered into five 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. Special-purpose calls deal with receipt generation/processing and with evidence generation/processing for non-repudiation purposes. 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 the 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 SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms) IDUP_Start_Generate_Receipt begin to generate receipt_token IDUP_Generate_Receipt continue generating receipt_token IDUP_End_Generate_Receipt complete generation of receipt_token IDUP_Process_Receipt process the receipt_token Adams Document Expiration: 5 Jan. 1996 9 IDUP_Generate_Evidence generate evidence for non-repudiation IDUP_Process_Evidence process evidence for non-repudiation 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 IDUP_Parse_Token examine an 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. Semantically, acquiring credentials and establishing an environment is analogous to logging in to a system -- it authenticates a local user to the system and gives that user access to a set of operations which can be performed. 2.2.1. Relationship to GSS-API The set of calls described in this section are used in place of the calls GSS_Init_sec_context(), GSS_Accept_sec_context(), GSS_Delete_sec_context(), GSS_Process_context_token(), and GSS_Context_time() which are specified in [RFC-1508], since those calls are specific to a session-oriented environment. Adams Document Expiration: 5 Jan. 1996 10 2.2.2. IDUP_Establish_Env call Inputs: o claimant_cred_handle CREDENTIAL HANDLE, -NULL specifies "use default" o req_mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use default" o req_flags INTEGER, Outputs: o major_status INTEGER, o minor_status INTEGER, o env_handle ENVIRONMENT HANDLE, o actual_mech_type OBJECT IDENTIFIER, -actual mechanism always indicated, never NULL 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 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: 5 Jan. 1996 11 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 IDUs. The claimant_cred_handle, if non-NULL, must correspond to a valid credentials structure. This routine returns an env_handle for all future references to this environment; when protection, unprotection, receipt, evidence, 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, receipt processing, and/or evidence processing be available in the established environment. Requesting receipt processing indicates that the calling application may wish to generate or process a proof of receipt of a P-IDU. Requesting evidence processing indicates that the calling application may wish to generate or process evidence information for non-repudiation purposes (note: this is non-repudiation of origin; the IDUP-GSS-API cannot guarantee non-repudiation of delivery -- even if the receipt calls provide this in the underlying mechanism -- because there is no way to force a target to send a receipt_token back to the IDU protector). Not all features will be available in all underlying mech_types; the returned value of ret_flags (receipts_avail, evidence_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 paramater) 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, the receipts_avail return value indicates whether receipt generation and processing services are available, and the evidence_avail return value indicates whether evidence generation and processing services are available. Adams Document Expiration: 5 Jan. 1996 12 Note that, unlike a GSS "context", an IDUP environment does not have an explicit lifetime associated with it. Instead, it relies on the lifetime of the calling entity's credential (set by the caller in the GSS_Acquire_cred() call). When the credential expires, no new operations are allowed in the IDUP environment (although operations which have begun, such as the Protection set of calls, can be taken to completion). 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 credential lifetime expires.) Attempts to perform IDU processing on a deleted 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, Adams Document Expiration: 5 Jan. 1996 13 Return major_status codes: o GSS_S_COMPLETE indicates that the referenced environment is valid and that mech_type and ret_flags return values describe the corresponding characteristics of the environment. 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, 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 meant to be 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 and/or validation (e.g., verification of MAC or digital signature) of P-IDUs, as required. 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. "End_Operation" performs any required clean-up and creates the appropriate token or states whether the input token and IDU were valid. Adams Document Expiration: 5 Jan. 1996 14 2.3.1. Relationship to GSS-API The set of calls described in this section are used in place of 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], since those calls are specific to a session-oriented environment. 2.3.2. IDUP_Start_Protect call Inputs: o env_handle ENVIRONMENT HANDLE, o qop_req INTEGER, -0 specifies default QOP o targ_names SEQUENCE OF INTERNAL NAME, -- the set of recipients 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 receipt_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_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 (through qop_req) is unavailable in the requested mechanism, so processing cannot continue. Adams Document Expiration: 5 Jan. 1996 15 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 (through qop_req) 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 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 qop_req parameter specifies an integrity algorithm, the caller requests that data origin authentication and/or data integrity services be applied to the IDU buffers (the choice of the digest algorithm determines whether non-repudiation services are requested for the IDU). If the qop_req parameter specifies a confidentiality algorithm, the caller requests that confidentiality be applied to the IDU buffers. If the receipt_req flag is TRUE, the caller requests that a proof of receipt of the P-IDU be returned by one or more recipients. Confidentiality, authentication/integrity, and receipt processing might not be supported in all mech_types or by all implementations; the returned conf_state, digest_state, and receipt_state flags indicate whether confidentiality, authentication/integrity, or receipt processing can be provided for the 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. As another example, a mechanism may choose to do a digital signature in two stages: one for the hashing of the message and another for the signature on the hash. The calling application would therefore use the protection set of calls on the IDU in stage 1 and then use the protection set of calls on the prot_token (from stage 1) in stage 2. 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 this call to fail; it is the caller's prerogative to discontinue IDU protection if the target set which can be used is unsuitable for the caller's purposes. Adams Document Expiration: 5 Jan. 1996 16 2.3.3. IDUP_Protect call Inputs: o env_handle ENVIRONMENT HANDLE, o prot_oper_id INTEGER 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 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 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 encrypted result in output_buffer. 2.3.4. IDUP_End_Protect call Inputs: o env_handle ENVIRONMENT HANDLE, o prot_oper_id INTEGER Outputs: o major_status INTEGER, o minor_status INTEGER, o output_buffer OCTET STRING o prot_token OCTET STRING -- resulting "protection token" o receipt_check OCTET STRING -- first 8 bytes contain random value Adams Document Expiration: 5 Jan. 1996 17 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 Start_Protect() output_buffer will contain any residual ciphertext. 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 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. If a receipt was requested in Start_Protect() -- and if receipt generation and processing is supported by the underlying mechanism -- receipt_check will hold whatever data is necessary for the mechanism to validate a receipt returned by the receiver of the P-IDU. The first 8 bytes of receipt_check contain a random (i.e., previously unused) value which can be used by the calling application to match receipt_check with the IDU used to generate it and with the receipt_token returned by the receiver of the P-IDU. 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 (for example, it may be damaged in transit). Note that the IDU itself (whether or not confidentiality was applied) is not encapsulated into an output token (similar in concept to the GetMIC call of GSS [RFC-1508], where the data is not encapsulated into the GetMIC token). This ensures that no constraints whatsoever are placed on the buffer sizes used in the Unprotection set of calls -- all buffer sizes are a purely local matter requiring no agreement, to any degree, between originator and 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 to be performed Outputs: o major_status INTEGER, Adams Document Expiration: 5 Jan. 1996 18 o minor_status INTEGER, o qop_state INTEGER, o receipt_request_state BOOLEAN, --if TRUE then a receipt was requested during the IDU prot. oper. o originator_info OCTET STRING 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_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 confidentiality was applied to the IDU, then the confidentiality portion of qop_state specifies the algorithm which was used. Similarly, if data integrity / data origin authentication services were applied to the IDU, then the integrity portion of qop_state specifies the algorithm which was used. If a receipt was requested by the sender of the P-IDU (and the underlying mechanism supports this), receipt_state will be TRUE (the Generate_Receipt set of calls can be used to generate this receipt in a form suitable for immediate transfer back to the sender). If the underlying mechanism supports it and if this information is contained in prot_token, information regarding the originator (that is, the entity which used the protection set of calls to protect this IDU) is returned in originator_info. Adams Document Expiration: 5 Jan. 1996 19 2.3.6. IDUP_Unprotect call Inputs: o env_handle ENVIRONMENT HANDLE, o prot_oper_id INTEGER 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 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 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, o prot_oper_id INTEGER Outputs: o major_status INTEGER, o minor_status INTEGER, o output_buffer OCTET STRING Adams Document Expiration: 5 Jan. 1996 20 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 integrity field (e.g., signature or MAC) for the data. o IDUP_S_BAD_AI_KEY indicates that the key used to provide IDU origin auth. and/or integ. has either expired or been revoked. o IDUP_S_BAD_KE_KEY indicates that the key used to establish a key for confidentiality purposes between originator and target has either expired or been revoked. o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU cannot be completed because the encrypted IDU was invalid/defec- tive (e.g., the final block was short or had incorrect padding). 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 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 confidentiality was applied to the IDU, put the final decrypted buffer of data in output_buffer. Note: unlike GSS-API, IDUP-GSS-API does not incorporate the concept of error tokens transferred between sender and recipient 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.4. Special-Purpose Calls 2.4.1. Relationship to GSS-API The special-purpose calls described in this section have no analogue in GSS-API [RFC-1508]. These calls are used to generate and process a receipt (proof of delivery of a P-IDU) and to generate and process evidence for non-repudiation purposes in the IDUP environment. These calls may not be supported by all underlying IDUP mechanisms. 2.4.2. IDUP_Start_Generate_Receipt call Inputs: o env_handle ENVIRONMENT HANDLE, Adams Document Expiration: 5 Jan. 1996 21 o prot_token OCTET STRING --IDUP protection token Outputs: o major_status INTEGER, o minor_status INTEGER, o p_idu_needed BOOLEAN -- indicates whether receipt_token is -- generated by this call or by -- IDUP_End_Generate_Receipt() (i.e., -- whether the entire P-IDU is needed -- for receipt generation or just the -- prot_token) o receipt_token OCTET STRING -- first 8 bytes contain random value -- identical to that in receipt_check Return major_status codes: o GSS_S_COMPLETE indicates that receipt generation was successfully started. Depending on the value of idu_needed, receipt_token is either returned by this call or by IDUP_End_Generate_Receipt(). o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed on the input 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_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 generate a receipt for prot_token and return the appropriate status value. If p_idu_needed is FALSE then receipt generation is complete and receipt_token is returned by this call; otherwise, IDUP_Generate_Receipt() should be called for for each buffer of P-IDU data and IDUP_End_Generate_Receipt() should be called to complete receipt_token generation. The first 8 bytes of the returned receipt_token contains a random value which can be used by the application which originally protected the IDU to match receipt_check (which it has saved) with receipt_token and with the IDU used to generate receipt_check. Adams Document Expiration: 5 Jan. 1996 22 2.4.3. IDUP_Generate_Receipt call Inputs: o env_handle ENVIRONMENT HANDLE, o input_buffer OCTET STRING Outputs: o major_status INTEGER, o minor_status INTEGER, Return major_status codes: o GSS_S_COMPLETE indicates that the input_buffer has successfully been included in the receipt generation computation. o IDUP_S_NO_ENV indicates that no valid environment was recognized for the env_handle provided. o IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism does not support the generation or processing of receipts. 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 receipt generation processing on the data in input_buffer. 2.4.4. IDUP_End_Generate_Receipt call Inputs: o env_handle ENVIRONMNENT HANDLE, Outputs: o major_status INTEGER, o minor_status INTEGER, o receipt_token OCTET STRING -- first 8 bytes contain random value -- identical to that in receipt_check Return major_status codes: o GSS_S_COMPLETE indicates that receipt generation was successful. 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. Adams Document Expiration: 5 Jan. 1996 23 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 processing required to generate a receipt for the P-IDU and return the appropriate status value. The first 8 bytes of the returned receipt_token contains a random value which can be used by the application which originally protected the IDU to match receipt_check (which it has saved) with receipt_token and with the IDU used to generate receipt_check. 2.4.5. IDUP_Process_Receipt call Inputs: o env_handle ENVIRONMENT HANDLE, o receipt_check OCTET STRING -- first 8 bytes contain a random value o receipt_token OCTET STRING -- 1st 8 bytes contain same random val. Outputs: o major_status INTEGER, o minor_status INTEGER, o rec_originator_info OCTET STRING Return major_status codes: o GSS_S_COMPLETE indicates that receipt processing was successful. o GSS_S_DEFECTIVE_CHECK indicates that consistency checks performed on the receipt_check failed, preventing further processing from being performed with that token. 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_NO_MATCH indicates that the first 8 bytes of receipt_check and receipt_token do not match. 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_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. Adams Document Expiration: 5 Jan. 1996 24 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, process the received receipt_token and return the appropriate status value. Information regarding the creator of the receipt_token may be returned in rec_originator_info, if the underlying mechanism supports it. 2.4.6. IDUP_Generate_Evidence call Inputs: o env_handle ENVIRONMENT HANDLE, o gen_evidence_qop INTEGER o prot_token OCTET STRING Outputs: o major_status INTEGER, o minor_status INTEGER, o evidence_token OCTET STRING Return major_status codes: o GSS_S_COMPLETE indicates that evidence generation was successful. o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed on the input 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_EVIDENCE_UNAVAIL indicates that the underlying mechanism does not support the generation or processing of non-repudiation evidence. 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. Adams Document Expiration: 5 Jan. 1996 25 Using the security environment referenced by env_handle, generate an evidence_token for non-repudiation purposes and return the appropriate status value. An evidence_token is a signed testimony (typically by a trusted third party such as a Timestamp Authority) that the prot_token was "good" (e.g., was associated with valid, non-revoked keys) on a particular date. The evidence_token will be valid for a specified period of time from that date (this will typically be the validity period of the evidence signer's key). The input parameter gen_evidence_qop is used to choose an appropriate quality of protection for non-repudiation. The gen_evidence_QOP parameter for IDUP is defined to be a 32-bit unsigned integer with the following bit-field assignments: 31 (MSB) (LSB) 0 -------------------------------- | U(28) | V(4) | -------------------------------- where U is a 28-bit Unspecified field (available for future use/expansion); V is a 4-bit field enumerating a range of values for the Validity of the evidence_token. The following V values (i.e., validity periods) are specified; other values may be added in the future. 0001 (1) = IDUP_ONE_HOUR -- evidence_token valid for up to 1 hour after generation 0010 (2) = IDUP_ONE_DAY 0011 (3) = IDUP_ONE_YEAR 0100 (4) = IDUP_FIVE_YEARS 0101 (5) = IDUP_TEN_YEARS 2.4.7. IDUP_Process_Evidence call Inputs: o env_handle ENVIRONMENT HANDLE, o evidence_token OCTET STRING o proc_evidence_qop INTEGER Outputs: o major_status INTEGER, o minor_status INTEGER, o prot_token OCTET STRING -- extracted from evidence_token by IDUP mechanism Adams Document Expiration: 5 Jan. 1996 26 o evidence_info OCTET STRING Return major_status codes: o GSS_S_COMPLETE indicates that evidence processing was successful. 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 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_EVIDENCE_UNAVAIL indicates that the underlying mechanism does not support the generation or processing of non-repudiation evidence. 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 and the input proc_evidence_qop, process the evidence_token and return the appropriate status value, prot_token, and evidence information. The proc_evidence_QOP parameter for IDUP is defined to be a 32-bit unsigned integer with the following bit-field assignments: 31 (MSB) (LSB) 0 -------------------------------- | U(28) | F(4) | -------------------------------- where U is a 28-bit Unspecified field (available for future use/expansion); F is a 4-bit Flag field (a set of flags whose values specify the type of environment used to validate the non-repudiation evidence) The following F values (i.e., environment qualifiers) are specified; other values may be added in the future. xx0x = Certificate Revocation Lists (CRLs) not used xx1x = CRLs used xxx0 = Trusted time not used xxx1 = Trusted time used Adams Document Expiration: 5 Jan. 1996 27 The CRL flag indicates whether or not checking of Certificate Revocation Lists is to be done during the IDUP_Process_Evidence() call. If CRLs are not to be checked, then verification may be successful even if the evidence signer's key has been revoked since the evidence_token was generated. The Trusted Time flag indicates whether or not to check the current local time during the IDUP_Process_Evidence() call. If the current time is not to be checked (e.g., if the local time is not trusted), then verification may be successful even if the evidence signer's key has expired since the evidence_token was generated (that is, if the Validity period -- as specified by the V field of gen_evidence_qop in IDUP_Generate_Evidence() -- has expired). 2.5. Support calls 2.5.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(), and GSS_Release_oid_set() are unchanged. 2.5.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, 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_CREDENTIALS_EXPIRED indicates that the environment is recognized, but that its associated credentials have expired, so that the requested operation cannot be performed. 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. Adams Document Expiration: 5 Jan. 1996 28 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, the IDUP_Process_Evidence() call, or the IDUP_Process_Receipt() call. If all tokens are framed as suggested in RFC-1508, Appendix B (mandated 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(), IDUP_Process_Evidence(), or IDUP_Process_Receipt(). No minor status return codes have been defined for this function at this time. 2.5.2.1. The token_type Output Parameter The following token types are defined: IDUP_PROT_TOKEN = 1 IDUP_RECEIPT_TOKEN = 2 IDUP_RECEIPT_CHECK = 3 IDUP_EVIDENCE_TOKEN = 4 Every mechanism must be able to perform the mapping from a valid input token to one of the above token types (for any token generated by that mechanism). 3. Mechanism-Specific Example Scenarios This section provides an illustrative overview of the use of two candidate mechanism types to support the IDUP-GSS-API. This discussion is intended primarily for readers familiar with the specific security technologies, demonstrating how IDUP-GSS-API functions can be used and implemented by the candidate underlying mechanisms. 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 each particular underlying technology, and does not demonstrate all IDUP-GSS-API features. Adams Document Expiration: 5 Jan. 1996 29 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 request in req_flags. IDUP_Start_Protect() is called next to specify that both encryption and authentication/integrity are desired, using the QOP parameter to specify either particular algorithms (if the application is aware of algorithms supported by the underlying mechanism) or "generic" values. As well, the targ_names (possibly a set of X.500 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 (electronic mail, for example) to the intended recipient(s). Assuming that this is the only IDU to be protected at this time, the application terminates 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 may be redundant information for a PEM-compliant IDUP-GSS-API mechanism, since receipts and evidence are not required 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(). The decrypted output buffers are written to an output file; after IDUP_End_Unprotect() has been called and the returned status code indicates success, it has been verified that this file is the original IDU which the sender protected. The recipient then abolishes the environment by calling IDUP_Abolish_Env(). Adams Document Expiration: 5 Jan. 1996 30 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. 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, the following is necessary: - object identifiers must be assigned to candidate IDUP-GSS-API mechanisms and the name types which they support; and - concrete data element (i.e., token) 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 a binding for the C language are available in the Internet Draft [IDUP-C]. Adams Document Expiration: 5 Jan. 1996 31 5. Acknowledgments Many thanks are due to Warwick Ford and Paul Van Oorschot of Bell-Northern Research, and to Denis Pinkas of Bull, 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. [KRB5]: J. Linn, "The Kerberos Version 5 GSS-API Mechanism", Internet Draft draft-ietf-cat-kerb5gss-02.txt. [SPKM]: C. Adams, "The Simple Public-Key GSS-API Mechanism (SPKM)", Internet Draft draft-ietf-cat-spkmgss-04.txt. [IDUP-C]: D. Grebovich, "Independent Data Unit Protection Generic Security Service Application Program Interface: C-bindings", Internet Draft draft-ietf-cat-idup-cbind-01.txt. 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: 5 Jan. 1996 32 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 ::= [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 } EvidenceToken ::= [APPLICATION 0] IMPLICIT SEQUENCE { thisMech MechType, evidenceToken ANY DEFINED BY thisMech -- contents mechanism-specific } END APPENDIX B MECHANISM DESIGN CONSTRAINTS The following constrain on IDUP-GSS-API mechanism designs is 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, the ReceiptToken (if defined), and the EvidenceToken (if defined) is required. Adams Document Expiration: 5 Jan. 1996 33
Datatracker
Report a datatracker bug
draft-ietf-cat-idup-gss-02
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 |