diff options
Diffstat (limited to 'doc/rfc/rfc2479.txt')
| -rw-r--r-- | doc/rfc/rfc2479.txt | 3923 |
1 files changed, 3923 insertions, 0 deletions
diff --git a/doc/rfc/rfc2479.txt b/doc/rfc/rfc2479.txt new file mode 100644 index 0000000..8413bca --- /dev/null +++ b/doc/rfc/rfc2479.txt @@ -0,0 +1,3923 @@ + + + + + + +Network Working Group C. Adams +Request for Comments: 2479 Entrust Technologies +Category: Informational December 1998 + + + Independent Data Unit Protection Generic Security Service + Application Program Interface (IDUP-GSS-API) + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +ABSTRACT + + The IDUP-GSS-API extends the GSS-API [RFC-2078] 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. The protection offered by IDUP includes services such as data + origin authentication with data integrity, data confidentiality with + data integrity, and support for non-repudiation services. 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 Informational [Page 1] + +RFC 2479 IDUP-GSS-API December 1998 + + + As with RFC-2078, 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 + environment, 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 .................................. 5 + 1.1.1. Credentials ............................................ 5 + 1.1.2. Tokens ................................................. 5 + 1.1.3. Security Environment ................................... 6 + 1.1.4. Mechanism Types ........................................ 6 + 1.1.5. Naming ................................................. 6 + 1.1.6. Channel Bindings ....................................... 6 + 1.2. IDUP-GSS-API Features and Issues ......................... 6 + 1.2.1. Status Reporting ....................................... 6 + 1.2.2. Per-IDU Security Service Availability .................. 9 + 1.2.3. Per-IDU Replay Detection and Sequencing ................ 9 + 1.2.4. Quality of Protection .................................. 9 + 1.2.5. The Provision of Time .................................. 12 + 2. Interface Descriptions ..................................... 13 + 2.1. Credential management calls .............................. 14 + 2.1.1. Relationship to GSS-API ................................ 14 + 2.2. Environment-level calls .................................. 15 + 2.2.1. Relationship to GSS-API ................................ 15 + 2.2.2. IDUP_Establish_Env call ................................ 15 + 2.2.3. IDUP_Abolish_Env call .................................. 19 + 2.2.4. IDUP_Inquire_Env call .................................. 19 + 2.3. Per-IDU protection/unprotection calls .................... 20 + 2.3.1. Relationship to GSS-API ................................ 20 + 2.3.2. The "SE" Calls ......................................... 21 + 2.3.3. The "EV" Calls ......................................... 27 + 2.3.4. The "GP" Calls ......................................... 36 + 2.4. Special-Purpose calls .................................... 47 + 2.4.1. Relationship to GSS-API ................................ 47 + 2.4.2. IDUP_Form_Complete_PIDU ................................ 48 + 2.5. Support calls ............................................ 49 + + + +Adams Informational [Page 2] + +RFC 2479 IDUP-GSS-API December 1998 + + + 2.5.1. Relationship to GSS-API ................................ 49 + 2.5.2. IDUP_Acquire_Cred_With_Auth ............................ 49 + 2.5.3. IDUP_Get_Token_Details ................................. 50 + 2.5.4. IDUP_Get_Policy_Info ................................... 53 + 2.5.5. IDUP_Cancel_Multibuffer_Op ............................. 55 + 3. Related Activities ......................................... 55 + 4. Acknowledgments ............................................ 56 + 5. Security Considerations .................................... 56 + 6. References ........................................... 56 + 7. Author's Address ........................................... 56 + Appendix A Mechanism-Independent Token Format ................. 57 + Appendix B Examples of IDUP Use ............................... 58 + Full Copyright Statement ....................................... 70 + +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 that works with IDUs, calling + on IDUP-GSS-API in order to protect its IDUs with services such as + data origin authentication with integrity (DOA), confidentiality with + integrity (CONF), and/or support for non-repudiation (e.g., evidence + generation, where "evidence" is information that either by itself, or + when used in conjunction with other information, is used to establish + proof about an event or action (note: the evidence itself does not + necessarily prove truth or existence of something, but contributes to + establish proof) -- see [ISO/IEC] for fuller discussion regarding + evidence and its role in various types of non-repudiation). An + IDUP-GSS-API caller passes an IDU to, and accepts a token from, its + local IDUP-GSS-API implementation, transferring the resulting + protected IDU (P-IDU) to a peer or to any storage medium. When a P- + IDU is to be "unprotected", it is 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. + + During the protection operation, the input IDU buffers may be + modified (for example, the data may be encrypted or encoded in some + way) or may remain unchanged. In any case, the result is termed a + "M-IDU" (Modified IDU) in order to distinguish it from the original + IDU. Depending on the desire of the calling application and the + capabilities of the underlying IDUP mechanism, the output produced by + the protection processing may or may not encapsulate the M-IDU. Thus, + the P-IDU may be the contents of a single output parameter (if + encapsulation is done) or may be the logical concatenation of an + unencapsulated token parameter and a M-IDU parameter (if + encapsulation is not done). In the latter case, the protecting + application may choose whatever method it wishes to concatenate or + + + +Adams Informational [Page 3] + +RFC 2479 IDUP-GSS-API December 1998 + + + combine the unencapsulated token and the M-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. + + It is expected that any output buffer returned by IDUP (i.e., P-IDU + or portion thereof) is ready for immediate transmission to the + intended receiver(s) by the calling application, if this is desired. + In other words, an application wishing to transmit data buffers as + they appear from IDUP should not be unduly restricted from doing so + by the underlying mechanism. + + 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 DOA, CONF, evidence, and other services, + as requested by the calling application and as supported by the + underlying mechanism. + + The following paragraphs provide an example illustrating the + dataflows involved in the 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. Furthermore, the example does not cover all possible + options available in the protection/unprotection calls. + + The sender first calls IDUP_Establish_Env() to establish a + security environment. Then, for the IDU to be protected the + sender calls the appropriate protection calls (SE, EV, or GP) to + perform the IDU protection. The resulting P-IDU, which may + (depending on whether or not encapsulation was chosen/available) + be either the token itself or the logical concatenation of the + token and the M-IDU, 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 in order to unprotect the P-IDU. Then, for + the received P-IDU the receiver calls the appropriate unprotection + calls (SE, EV, or GP (known a priori, or possibly determined + through the use of the IDUP_Get_token_details call)) to perform + 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 + + + +Adams Informational [Page 4] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 has nothing whatever to do with + 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-2078]. + +1.1.2. Tokens + + Tokens in IDUP-GSS-API are to be understood and used as described in + GSS-API [RFC-2078] with the exception that there are no context-level + tokens generated by IDUP-GSS-API. The IDUP-GSS-API token may + (depending on the underlying mechanism) encapsulate the M-IDU or may + + + +Adams Informational [Page 5] + +RFC 2479 IDUP-GSS-API December 1998 + + + be logically concatenated with the M-IDU prior to transfer to a + target; furthermore, for some evidence services the token may 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-2078]. 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 or + set of credentials. 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 env_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 using a particular + underlying mechanism. 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-2078]. + +1.1.5. Naming + + Naming in IDUP-GSS-API is to be understood and used as described in + GSS-API [RFC-2078]. + +1.1.6. Channel Bindings + + The concept of channel bindings discussed in GSS-API [RFC-2078] 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-2078], with the addition of a number of + IDUP-specific status codes. Descriptions of the major_status codes + + + +Adams Informational [Page 6] + +RFC 2479 IDUP-GSS-API December 1998 + + + used in IDUP are provided in Table 1. Codes that are informatory + (i.e., that do not cause the requested operation to fail) are + indicated with the symbol "(I)". + + As with GSS-API, minor_status codes, which provide more detailed + status information than major_status codes, and which may include + status codes specific to the underlying security mechanism, are not + specified in this document. + + Table 1: IDUP-GSS-API Major Status Codes + + 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. + + GSS_S_BAD_QOP indicates that the provided qop_alg value is not + recognized or supported for the environment. + + GSS_S_BAD_MIC indicates that the received P-IDU contains an + incorrect integrity field (e.g., signature or MAC) for the data. + + GSS_S_COMPLETE indicates that the requested operation was + successful. + + GSS_S_CREDENTIALS_EXPIRED indicates that the credentials + associated with this operation have expired, so that the requested + operation cannot be performed. + + GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + claimant_cred_handle failed, preventing further processing from + being performed using that credential structure. + + GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed + on the received P-IDU failed, preventing further processing from + being performed. + + GSS_S_FAILURE indicates that the requested operation could not be + accomplished for reasons unspecified at the IDUP-GSS-API level, + and that no interface-defined recovery action is available. + + 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. + + IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU data + origin auth. / integ. has either expired or been revoked. + + + + +Adams Informational [Page 7] + +RFC 2479 IDUP-GSS-API December 1998 + + + IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU + cannot be completed because the encrypted IDU was + invalid/defective (e.g., the final block was short or had + incorrect padding). + + IDUP_S_BAD_KE_KEY indicates that the key used to establish a key + for confidentiality purposes between originator and target has + either expired or been revoked. + + IDUP_S_BAD_TARG_INFO indicates that the full set of supplied + information regarding the target(s) is invalid or is insufficient + for the protection of an IDU, so P-IDU cannot be created. + + IDUP_S_DEFECTIVE_VERIF indicates that consistency checks performed + on Service_Verification_Info failed, preventing further processing + from being performed with that parameter. + + IDUP_S_ENCAPSULATION_UNAVAIL (I) indicates that the underlying + mechanism does not support encapsulation of the M-IDU into the + token. + + IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied + do not contain the information necessary for P-IDU unprotection. + + IDUP_S_INCOMPLETE (I) indicates that the unprotection of the P-IDU + is not yet complete (i.e., a determination cannot yet be made on + the validity of the P-IDU). The application should call + IDUP_Form_Complete_PIDU and then should call this function again + with the complete P-IDU. + + IDUP_S_INCONSISTENT_PARAMS indicates that the supplied parameters + are inconsistent (e.g., only one or the other of two parameters + may be supplied, but both have been input). + + IDUP_S_MORE_OUTBUFFER_NEEDED (I) indicates that the output buffer + supplied is too small to hold the generated data. The application + should continue calling this routine (until GSS_S_COMPLETE is + returned) in order to get all remaining output data. + + IDUP_S_MORE_PIDU_NEEDED (I) indicates that not enough of the P-IDU + has been input yet for the completion of StartUnprotect. The + application should call this routine again with another buffer of + P-IDU in partial(initial)_pidu_buffer. + + IDUP_S_NO_ENV indicates that no valid environment was recognized + for the env_handle provided. + + + + + +Adams Informational [Page 8] + +RFC 2479 IDUP-GSS-API December 1998 + + + IDUP_S_NO_MATCH indicates that Service_Verification_Info (or + evidence_check) and the P-IDU to be verified do not match. + + IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service + requested (TTIME or UTIME) is not available in the environment. + + IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism + does not support the service requested. + + IDUP_S_SERV_VERIF_INFO_NEEDED (I) indicates that the + Service_Verification_Info parameter bundle must be input in order + for service verification to proceed. The output parameter + service_verification_info_id contains an identifier which may be + used by the calling application to locate the necessary + information. + + IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value + is not recognized or supported in the underlying mechanism. + +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-2078], with the + exception that combinations of services requested by the calling + application and supported by the underlying mechanism may be applied + simultaneously to any IDU (true for both the SE and the EV calls, but + true in the fullest sense for the GP calls). + + GSS-API callers desiring per-message security services should check + the relevant service OBJECT IDs at environment establishment time to + ensure that what is available in the established environment is + suitable for their security needs. + +1.2.3. Per-IDU Replay Detection and Sequencing + + The concept of per-IDU replay detection and sequencing discussed in + GSS-API [RFC-2078] 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-2078]. However, the actual + description and use of the QOP parameter is given as follows. + + The qop_algs parameter for IDUP is defined to be a 32-bit unsigned + integer with the following bit-field assignments: + + + + + +Adams Informational [Page 9] + +RFC 2479 IDUP-GSS-API December 1998 + + + 31 (MSB) (LSB) 0 + ---------------------------------------------- + | U(19) | TS(5) | IA(4) | MA(4) | + ---------------------------------------------- + + where + + U is a 19-bit Unspecified field (available for future + use/expansion) -- must be set to zero; + + 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); + + 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_algs parameter is as follows. 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. 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. + + + + + + + + + +Adams Informational [Page 10] + +RFC 2479 IDUP-GSS-API December 1998 + + + When qop_algs is used to select a confidentiality algorithm: + + 00000 (0) = default confidentiality algorithm + 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 + + When qop_algs is used to select a DOA/integrity algorithm: + + 00000 (0) = default integrity algorithm + 00001 (1) = IDUP_INT_ALG_DIG_SIGNATURE + (integrity provided through a digital signature) + 00010 (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE + (integrity without a dig. sig. (e.g., with a MAC)) + 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. + ("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 30 qualifiers for each of + confidentiality and integrity (since "0" is reserved for "default" + and "31" is reserved for "none", as shown above). This document + specifies three for confidentiality and two 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_algs parameter 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. + + + + +Adams Informational [Page 11] + +RFC 2479 IDUP-GSS-API December 1998 + + + - 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 intended + P-IDU recipient, however, is free to use these values since they + will be perfectly valid and meaningful for protecting IDUs between + those entities. + + The receiver of a P-IDU must pass back to its calling application (in + IDUP_Start_Unprotect()) a qop_algs 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 (TS=1, IA=0, MA=8). In this way, the + application is free to read whatever part of the qop_algs parameter + it understands (TS or IA/MA). + +1.2.5. The Provision of Time + + IDUP mechanisms should make provision in their protocols for the + carrying of time information from originator to target(s). That is, + a target (a legitimate recipient) should get some indication during + unprotection regarding the time at which the protection operation + took place. This is particularly important if the mechanism offers + non-repudiation services because in some cases evidence verification + may only be achievable if the time at which the evidence was + generated is known. + + Depending upon the platform and resources available to the + implementation, an IDUP environment may have access to a source of + trusted (secure) time, untrusted (local) time, both kinds of time, or + no time. OBJECT IDs indicating such availability are returned by the + IDUP_Establish_Env() call. When starting a protection operation, an + application may specify which time services it wishes to have applied + to the IDU. Similarly, for unprotection, an application may specify + which kind of time (if any) to consult when the validity of the P-IDU + is to be established. Specifying both kinds of time is interpreted + to mean that the calling application does not care which kind of time + is used. + + The IDUP calls which use a time parameter specify the type of that + parameter to be INTEGER. This INTEGER is defined in all cases to be + the number of seconds which have elapsed since midnight, January 1, + 1970, coordinated universal time. + + + + + +Adams Informational [Page 12] + +RFC 2479 IDUP-GSS-API December 1998 + + +2. Interface Descriptions + + This section describes the IDUP-GSS-API's operational 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 unusual or auxiliary evidence generation/verification + requirements. Support calls provide extra functions useful to IDUP- + GSS-API callers. Table 2 groups and summarizes the calls in tabular + fashion. + + Table 2: IDUP-GSS-API Calls + + CREDENTIAL MANAGEMENT + (see the calls given in Section 2.1 of GSS-API [RFC-2078]) + + ENVIRONMENT-LEVEL CALLS + IDUP_Establish_Env + IDUP_Abolish_Env + IDUP_Inquire_Env + + PER-IDU CALLS + SE (SIGN,ENCRYPT) CALLS + IDUP_SE_SingleBuffer_Protect + IDUP_SE_SingleBuffer_Unprotect + IDUP_SE_MultiBuffer_StartProtect + IDUP_SE_MultiBuffer_EndProtect + IDUP_SE_MultiBuffer_StartUnprotect + IDUP_SE_MultiBuffer_EndUnprotect + IDUP_SE_Process_Buffer + EV (EVIDENCE) CALLS + IDUP_EV_SingleBuffer_Generate + IDUP_EV_SingleBuffer_Verify + IDUP_EV_MultiBuffer_StartGenerate + IDUP_EV_MultiBuffer_EndGenerate + IDUP_EV_MultiBuffer_StartVerify + IDUP_EV_MultiBuffer_EndVerify + IDUP_EV_Process_Buffer + GP (GENERAL PROTECTION) CALLS + IDUP_Start_Protect + IDUP_Protect + IDUP_End_Protect + IDUP_Start_Unprotect + IDUP_Unprotect + IDUP_End_Unprotect + + + +Adams Informational [Page 13] + +RFC 2479 IDUP-GSS-API December 1998 + + + SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms) + IDUP_Form_Complete_PIDU + + SUPPORT CALLS + IDUP_Acquire_cred_with_auth + IDUP_Get_Token_Details + IDUP_Get_Policy_Info + IDUP_Cancel_Multibuffer_Op + (see also the calls given in Section 2.4 of GSS-API [RFC-2078]) + + In terms of conformance to this specification, IDUP-GSS-API + implementations must support the credential management calls, the + environment-level calls, some subset of the per-IDU calls, and the + support calls (except where explicitly stated otherwise in Section + 2.5). The subset of per-IDU calls supported will depend upon the + underlying mechanisms supported and will typically be the SE calls, + or the EV calls, or both. As stated in Section 2.3.2.1, + implementations are encouraged to support the more powerful GP calls + to anticipate the future needs of applications developers, but this + is not required for conformance. + +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-2078]. The calls given in Section 2.1 of + GSS-API (including all associated parameters) are unchanged, although + the interpretation of the cred_usage parameter in the GSS-API calls + for IDUP purposes is as follows. + + ENCRYPT_ONLY 8 + DECRYPT_ONLY 16 + SIGN_ONLY 32 + VERIFY_ONLY 64 + + The values above may be logically OR'ed together in any desired + combination to restrict credential usage (where OR'ing all values + results in NO_RESTRICTION). Future possible values for this + parameter are for further study. + + The call IDUP_Acquire_cred_with_auth has been added as a support call + in this specification to permit authenticated credential acquirement; + see Section 2.5.2 for details. + + + + + + + +Adams Informational [Page 14] + +RFC 2479 IDUP-GSS-API December 1998 + + +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 is made to process each IDU, the protection + calls resulting in a P-IDU for each. Finally, IDUP_Abolish_Env() is + called to flush all environment information. + + Semantically, acquiring credentials and establishing an environment + is (in many cases) 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 is used in place of the + calls described in Section 2.2 of GSS-API [RFC-2078], since those + calls are specific to a session-oriented environment. + +2.2.2. IDUP_Establish_Env call + + Inputs: o claimant_cred_handle CREDENTIAL HANDLE, + -- NULL parameter specifies "use default" + + o req_mech_type OBJECT IDENTIFIER, + -- NULL parameter specifies "use default" + o req_environmentPolicies EnvironmentPolicies, + -- NULL parameter specifies "use default" + o req_services SET OF OBJECT IDENTIFIER, + -- GSS_C_NO_OID_SET requests full set of services available + -- for req_mech_type + + 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 actual_environmentPolicies EnvironmentPolicies, + -- actual values always indicated, never NULL + o ret_services SET OF OBJECT IDENTIFIER, + + Return major_status codes: + o GSS_S_COMPLETE + -- environment-level information was successfully initialized, + + + +Adams Informational [Page 15] + +RFC 2479 IDUP-GSS-API December 1998 + + + -- and IDU / P-IDU processing can begin. + o GSS_S_DEFECTIVE_CREDENTIAL + o GSS_S_NO_CRED + o GSS_S_CREDENTIALS_EXPIRED + -- the credentials provided through claimant_cred_handle are + -- no longer valid, so environment cannot be established. + o GSS_S_BAD_MECH + o GSS_S_FAILURE + + The following structures are defined to facilitate environment policy + input and output: + + EnvironmentPolicies ::= SEQUENCE { + confPolicy [0] PolicyAndTime OPTIONAL, + -- NULL parameter (on input) specifies "use default" + integPolicy [1] PolicyAndTime OPTIONAL, + -- NULL parameter (on input) specifies "use default" + evidencePolicy [2] PolicyAndTime OPTIONAL } + -- NULL parameter (on input) specifies "use default" + + PolicyAndTime ::= SEQUENCE { + policy OBJECT IDENTIFIER, + -- this environment-level policy identifier is separate from + -- the policy provisions connected with credentials, if they exist + time INTEGER + -- on input: the policy rules available at the specified time + -- on output: the time at which the policy rules came into effect + -- (defined to be the number of seconds elapsed since midnight, + -- January 1, 1970, coordinated universal time) + endTime INTEGER OPTIONAL } + -- on input: unused + -- on output: the expiration time of the given policy rules + + 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, 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. + + + + +Adams Informational [Page 16] + +RFC 2479 IDUP-GSS-API December 1998 + + + The req_services parameter may be used by the calling application to + request that data origin authentication with integrity, + confidentiality with integrity, evidence generation, and/or evidence + verification services be available in the established environment. + Requests can also be made for "trusted" or "untrusted" time services. + Requesting evidence generation or verification indicates that the + calling application may wish to generate or verify evidence + information for non-repudiation purposes (note: an IDU protector may + request that a flag be inserted into a P-IDU asking a recipient to + provide an evidence of the type "non-repudiation of delivery"; + however, the IDUP-GSS-API cannot by itself guarantee that the + evidence will be sent because there is no way to force a target to + send an evidence_token back to the IDU protector). + + Not all features will be available in all underlying mech_types; the + returned value of ret_services indicates, as a function of mech_type + processing capabilities and the initiator-provided input OBJECT IDs, + the set of features which will be available in the environment. The + value of this parameter is undefined unless the routine's + major_status indicates COMPLETE. Failure to provide the precise set + of services desired by the caller does not cause environment + establishment to fail; it is the caller's choice to abolish the + environment if the service 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 following OBJECT IDs are defined for protection and unprotection + services (the OBJECT ID iso.org.dod.internet.security.services, + 1.3.6.1.5.7, has been assigned by IANA, and some of the security + services under that node are assigned as shown below). It is + recognized that this list may grow over time. + + PER_CONF = { 1.3.6.1.5.7.1.1 } + -- perform data confidentiality (i.e., encrypt data) + PER_CONF_FULL = { 1.3.6.1.5.7.1.3 } + -- perform full confidentiality (i.e., encrypt data and sig) + -- (may be used only when PER_DOA is requested simultaneously) + PER_DOA = { 1.3.6.1.5.7.3.1 } + -- perform data origin authentication with data integrity + PER_DOA_CIPH = { 1.3.6.1.5.7.3.3 } + -- perform DOA with DI over ciphertext (rather than plaintext) + -- (may be used only when PER_CONF is requested simultaneously) + PER_POO = { 1.3.6.1.5.7.4.1 } + -- perform (i.e., create) non-repudiable "proof of origin" + PER_POD = { 1.3.6.1.5.7.4.3 } + -- perform (i.e., create) non-repudiable "proof of delivery" + + + + +Adams Informational [Page 17] + +RFC 2479 IDUP-GSS-API December 1998 + + + REC_CONF = { 1.3.6.1.5.7.1.2 } + -- receive data confidentiality (i.e., decrypt data) + REC_CONF_FULL = { 1.3.6.1.5.7.1.4 } + -- receive full confidentiality (i.e., decrypt data and sig) + -- (may be used only when REC_DOA is received simultaneously) + REC_DOA = { 1.3.6.1.5.7.3.2 } + -- receive / verify DOA with data integrity + REC_DOA_CIPH = { 1.3.6.1.5.7.3.4 } + -- verify DOA with DI over ciphertext (rather than plaintext) + -- (may be used only when PER_CONF is received simultaneously) + REC_POO = { 1.3.6.1.5.7.4.2 } + -- receive / verify "proof of origin" + REC_POD = { 1.3.6.1.5.7.4.4 } + -- receive / verify "proof of delivery" + TTIME = { 1.3.6.1.5.7.7.1 } + -- trusted time availability + UTIME = { 1.3.6.1.5.7.7.2 } + -- untrusted time availability + + The PER_CONF return value (in the ret_services paramater) indicates + whether the environment supports confidentiality services, and so + informs the caller whether or not a request for encryption can be + honored. In similar fashion, the PER_DOA return value indicates + whether DOA services are available in the established environment, + and the PER_POO and PER_POD return values indicate whether evidence + generation services are available. The TTIME and UTIME values + indicate whether trusted time and untrusted time are available for + protection / unprotection services. + + 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 (or is + explicitly deleted in any other way), 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). + + + + + + + + + + + + + + + +Adams Informational [Page 18] + +RFC 2479 IDUP-GSS-API December 1998 + + +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 + -- the relevant environment-specific information was flushed. + o IDUP_S_NO_ENV + o GSS_S_FAILURE + + This call is made to flush environment-specific information. (Once an + environment is established, cached credential and environment-related + info. is expected to be retained until an IDUP_Abolish_Env() call is + made or until the cred. 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 environment + o environmentPolicies EnvironmentPolicies, + -- the environment policies in effect + o ret_services SET OF OBJECT IDENTIFIER, + + Return major_status codes: + o GSS_S_COMPLETE + -- referenced environment is valid and mech_type and other return + -- values describe the characteristics of the environment. + o GSS_S_CREDENTIALS_EXPIRED + o IDUP_S_NO_ENV + o GSS_S_FAILURE + + This routine provides environment-related information to the caller. + + + + + + + +Adams Informational [Page 19] + +RFC 2479 IDUP-GSS-API December 1998 + + +2.3. Per-IDU calls + + This group of calls is used to perform IDU protection and + unprotection 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. Members of this group form + pairs; the output from the protection types of calls is typically + meant to be input to the unprotection types of calls. + + The per-IDU calls can support caller-requested data origin + authentication with data integrity, confidentiality with data + integrity, evidence, and evidence-requested-from-target services. + + The protection operations output a token which encapsulates all the + information required to unprotect the IDU. The token is passed to + the target (possibly separate from the M-IDU) and is processed by the + unprotection calls at that system. Unprotection performs + decipherment, DOA verification, evidence verification, or + notification of evidence requested, as required. + + Each of the two main operations (protection and unprotection) may be + separated into three parts: "Start_Operation"; "Operation" (which + may be called once for each buffer of input data); and + "End_Operation". This separation is available for the case where the + IDU or P-IDU is to be processed one buffer at a time. + "Start_Operation" allows the caller to specify or retrieve the + appropriate "Quality" used during the processing. "Operation" is + concerned with the processing itself, receiving a buffer of input + data and potentially returning a buffer of output data. + "End_Operation" performs any required clean-up and creates the + appropriate token or states whether the input token was verified. + + If the IDU or P-IDU is wholly contained in a single buffer, the + three-part protection/unprotection processing need not be done. + Instead, protection or unprotection can be accomplished using only a + single call, simplifying application code. + +2.3.1. Relationship to GSS-API + + The set of calls described in this section is used in place of the + calls GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() which + are specified in [RFC-2078], since those calls are specific to a + session-oriented environment. + + + + + + + +Adams Informational [Page 20] + +RFC 2479 IDUP-GSS-API December 1998 + + +2.3.2. The "SE" Calls + +2.3.2.1. IDUP_SE Purpose + + The "SE" group of calls provides a very simple, high-level interface + to underlying IDUP mechanisms when application developers need access + only to signature and encryption protection/unprotection services. + It includes both the single-buffer and multiple-buffer IDU cases and + can be used for signing only, encrypting only, signing and encrypting + (in either order, and with or without visibility of the resulting + signature), and "clear signing" (where the data is not modified in + any way and the signature itself is returned as a separate item). + [Note that encapsulation occurs in all cases except for clear + signing, so that these calls provide functionality similar to the + GSS_Wrap call.] + + Note that the term "signing" is used in its most generic sense, not + necessarily implying the use of public-key techniques. This concept + has also been called "sealing" in other contexts (e.g., in other + standardization efforts). + + The SE calls may be viewed by mechanism implementors as an "API" to + the more powerful GP calls defined later and so may be implemented as + simple mapping functions to those calls (when those optional calls + are supported). Application callers, on the other hand, may find + that the SE calls are all they currently need for many environments. + At some time in the future when they have need of non-repudiation or + "directed receipts" types of services, they may consider using the EV + calls (or the GP calls -- when these are supported -- if complex and + sophisticated combinations of services are required). To assist in + this migration path, mechanism implementors are encouraged to support + the full set of IDUP calls (i.e., the SE, EV, and GP calls) even + though some calling applications will only use the SE calls in the + short term. + +2.3.2.2. IDUP_SE Parameter Bundles + + The concept of "parameter bundles" is used in the calls presented in + the following subsections in order to simplify their presentation and + clarify their intended purpose and use. See Section 2.3.4.1 for a + more complete description of parameter bundles. + + The following parameter bundles are used in the "SE" protection and + unprotection sets of calls. + + + + + + + +Adams Informational [Page 21] + +RFC 2479 IDUP-GSS-API December 1998 + + + o Protect_Options PARAMETER BUNDLE + o protect_operation INTEGER { + sign_only (0), + encrypt_only (1), + sign_and_encrypt (2), + -- let mechanism choose order (and readability of signature) + sign_then_encrypt_data (3), + -- sign, then encrypt plaintext (leaving signature in clear) + sign_then_encrypt_full (4), + -- sign, then encrypt everything (including signature) + encrypt_then_sign (5), + -- encrypt, then sign the ciphertext + clear_sign_only (6) + } OPTIONAL, + o protect_oper_oid OBJECT IDENTIFIER OPTIONAL, + -- may be used in place of above parameter if OID is known + o sign_qop_alg UNSIGNED INTEGER, + o sign_qop_algID AlgorithmIdentifier, --overrides sign_qop_alg + o enc_qop_alg UNSIGNED INTEGER, + o enc_qop_algID AlgorithmIdentifier, --overrides enc_qop_alg + o idu_type_string OCTET STRING, + -- type of the IDU ("data", "e-mail doc", MIME type, etc.) + o pidu_type_string OCTET STRING, + o mech_indep_encap_req BOOLEAN -- (see Appendix A) + + o PIDU_Information PARAMETER BUNDLE + o protect_options Protect_Options, + o originator_name INTERNAL NAME, + o originator_role Originator_Role, -- (see Section 2.3.4.1) + o protection_time INTEGER, + o Bad_Target_Name PARAMETER BUNDLE, -- same as in Section 2.3.3.2 + o bad_targ_name INTERNAL NAME, + o bad_targ_status INTEGER, + -- a status flag giving the reason for rejection of the name + -- in bad_targ_name. Specified reasons include: + -- SYNTAX_INVALID (0) the syntax of the name is invalid; + -- NAME_UNRECOGNIZED (1) the name is not recognized; + -- NAME_AMBIGUOUS (2) the name cannot be resolved; + -- ACCESS_DENIED (3) access to this target is denied; + -- CERTIFICATE_NOT_FOUND (4) the encryption certificate of the + target could not be found. + + o Target_Info PARAMETER BUNDLE, -- same as in Section 2.3.3.2 + o targ_names SET OF INTERNAL NAME, + o bad_targ_count INTEGER, + o bad_target_names SET OF Bad_Target_Name, + + + + + +Adams Informational [Page 22] + +RFC 2479 IDUP-GSS-API December 1998 + + +2.3.2.3. IDUP_SE major_status codes + + The following major_status return codes are defined for the "SE" + calls in this section: + + o GSS_S_COMPLETE + o IDUP_S_MORE_OUTBUFFER_NEEDED + -- returned (by any SE call) to indicate that there is more output + -- data than can fit into the supplied buffers. The application + -- should save the returned data and call again to retrieve the + -- remaining output. + o IDUP_S_MORE_PIDU_NEEDED + -- indicates that more PIDU data is needed for the StartUnprotect + -- operation (e.g., so that PIDU_Information or initial_idu_buffer + -- may be returned). + o IDUP_S_INCONSISTENT_PARAMS + o GSS_S_CREDENTIALS_EXPIRED + o IDUP_S_NO_ENV + o GSS_S_BAD_QOP + o GSS_S_FAILURE + + If Target_Info is used as an input parameter (e.g., if an encryption + operation is being performed), the following major_status return code + is also defined: + + o IDUP_S_BAD_TARG_INFO + + Note for this return code that 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 (with associated status + codes in bad_targ_status). As long as at least one of the targets + can be used, however, this does not cause this call to fail (i.e., + the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the + caller's choice to discontinue IDU protection if the target set which + can be used is unsuitable for the caller's purposes. + +2.3.2.4. IDUP_SE_SingleBuffer_Protect call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o Protect_Options PARAMETER BUNDLE, + o Target_Info PARAMETER BUNDLE, + o idu_buffer OCTET STRING + o additional_protection BOOLEAN + -- TRUE if idu_buffer is the output of a previous protection + -- operation (i.e., if this is the second (or higher) in a + -- series of SE/EV protection calls) + + + + +Adams Informational [Page 23] + +RFC 2479 IDUP-GSS-API December 1998 + + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o pidu_buffer OCTET STRING, + o sig_token OCTET STRING + -- used if Protect_Options is clear_sign_only + + Using the security environment referenced by env_handle, encrypt + and/or sign the supplied IDU. If "clear signing" is performed, the + signature will be returned in sig_token and pidu_buffer may be empty + (depends on underlying mechanism). + +2.3.2.5. IDUP_SE_SingleBuffer_Unprotect call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o pidu_buffer OCTET STRING, + -- may contain an IDU if sig_token is non-NULL (i.e., if + -- clear_sign_only protection was applied) + o sig_token OCTET STRING + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o idu_buffer OCTET STRING, + -- may be empty if clear_sign_only protection was applied (depends + -- on underlying mechanism) + o PIDU_Information PARAMETER BUNDLE + o additional_unprotection BOOLEAN + -- TRUE if idu_buffer should be input to another unprotection + -- operation (i.e., if this should not be the last in a series + -- of SE/EV unprotection calls) + + Using the security environment referenced by env_handle, decrypt + and/or verify the supplied PIDU and return the contained IDU along + with all available PIDU_Information. + +2.3.2.6. IDUP_SE_MultiBuffer_StartProtect call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o Protect_Options PARAMETER BUNDLE, + o Target_Info PARAMETER BUNDLE, + o additional_protection BOOLEAN, -- (see Section 2.3.2.4) + o idu_size INTEGER -- (see Section 2.3.4.2) + + + + + + +Adams Informational [Page 24] + +RFC 2479 IDUP-GSS-API December 1998 + + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o initial_pidu_buffer OCTET STRING + -- may be empty (depends on underlying mechanism) + + Using the security environment referenced by env_handle, initialize + the data structures required to begin the process of signing and/or + encrypting the IDU (which will be supplied in multiple buffers to the + Process_Buffer call). + +2.3.2.7. IDUP_SE_MultiBuffer_EndProtect call + + Inputs: + o env_handle ENVIRONMENT HANDLE + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o final_pidu_buffer OCTET STRING, + o sig_token OCTET STRING + -- used if Protect_Options was clear_sign_only + + Using the security environment referenced by env_handle, complete the + protection processing on the data and place the computed output in + final_pidu_buffer and/or sig_token. Successful application of + IDUP_SE_MultiBuffer_EndProtect() does not guarantee that unprotection + can necessarily be performed successfully when the P-IDU arrives at + the target (for example, it may be damaged in transit). + +2.3.2.8. IDUP_SE_MultiBuffer_StartUnprotect call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o initial_pidu_buffer OCTET STRING, + o sign_qop_alg_in UNSIGNED INTEGER, + -- used if Protect_Options was clear_sign_only (and calling + -- application has prior knowledge of signing alg. applied); + -- if NULL, then sig_token must be supplied + o sig_token OCTET STRING + -- used if Protect_Options was clear_sign_only; + -- if NULL, then sign_qop_alg_in must be supplied + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o PIDU_Information PARAMETER BUNDLE, + -- returns all available information + + + +Adams Informational [Page 25] + +RFC 2479 IDUP-GSS-API December 1998 + + + o initial_idu_buffer OCTET STRING + -- may be empty + + Using the security environment referenced by env_handle, initialize + the data structures required to begin the process of decrypting + and/or verifying the PIDU (which will be supplied in multiple buffers + to the Process_Buffer call). + + The parameters sign_qop_alg_in and sig_token should not both be + supplied (i.e., they should not both be non-NULL). If they are both + non-NULL, however, sig_token is taken to be authoritative since this + is the token created at protection time and therefore is guaranteed + to carry the information needed to unprotect. + +2.3.2.9. IDUP_SE_MultiBuffer_EndUnprotect call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o sig_token OCTET STRING OPTIONAL + -- used if Protect_Options was clear_sign_only and sig_token was + -- not available when StartUnprotect was called + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o PIDU_Information PARAMETER BUNDLE, + -- returns all available information + o final_idu_buffer OCTET STRING -- may be empty + o additional_unprotection BOOLEAN -- (see Section 2.3.2.5) + + Using the security environment referenced by env_handle, complete the + decryption and/or verification processing on the data and place any + residual output in final_idu_buffer. + +2.3.2.10. IDUP_SE_Process_Buffer 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 + -- may be zero length (depends on underlying mechanism and + -- corresponding Start() call and Protect_Options value) + + + + + +Adams Informational [Page 26] + +RFC 2479 IDUP-GSS-API December 1998 + + + Using the security environment referenced by env_handle, continue the + processing on the data in input_buffer and, if it is available, put + any resulting output data in output_buffer. The application calls + this routine over and over again with new buffers of data until it + has processed all the data buffers of the IDU/PIDU. It then calls the + appropriate End() call to complete the processing. + +2.3.3. The "EV" Calls + +2.3.3.1. IDUP_EV Purpose + + The "EV" group of calls provides a simple, high-level interface to + underlying IDUP mechanisms when application developers need to deal + only with evidence but not with encryption or integrity services. It + includes both the single-buffer and multiple-buffer IDU cases and can + be used for the generation and verification of evidence tokens + embodying several different types of evidences. + + The following list of evidence types is supported. This list is by no + means exhaustive and it is anticipated that it may be extended in + future versions of this specification. + + "Non-repudiation of Origin" prevents a message creator's false + denial of creating and sending a message. + + "Non-repudiation of Creation" prevents a message creator's false + denial of creating a message. + + "Non-repudiation of Sender" prevents a message creator's false + denial of sending a message (that was not necessarily created by + the sender). + + "Non-repudiation of Delivery" prevents a message recipient's false + denial of having received and looked at the content of a message. + + "Non-repudiation of Receipt" prevents a message recipient's false + denial of having received a message (whose content was not + necessarily looked at by the recipient). + + "Non-repudiation of Approval" prevents a message recipient's false + denial of having approved the content of a received message. + + An evidence is provided in the form of a evidence token. Two forms of + evidence tokens are supported: + + o Tokens including the associated data, + + + + + +Adams Informational [Page 27] + +RFC 2479 IDUP-GSS-API December 1998 + + + o Tokens without included data (but with a unique reference to + the associated data). + + Evidence tokens may be freely distributed. Any possessor of an + evidence token (and of the associated data, if not included in the + token) can verify the evidence if it has the appropriate credentials + which include the definition of security policies (i.e., keys alone + do not permit the verification of evidence tokens). Any holder of an + evidence token may store it (along with the associated data, if not + included in the token) for later verification. + + Calls that are specific to the support of evidence include: + + * Generate_token, which generates a non-repudiation token using the + current environment. The generated token may consist of: + + 1 - an evidence token + 2 - a token containing a request for an evidence, which carries + information describing which evidence type should be generated + by the recipient(s) and sent back to some entities (that may + or may not include the sender). + 3 - a token containing an evidence token which is an answer to an + evidence that has been previously requested. + 4 - a token including both an evidence and a request for another + evidence to be provided. + + * Verify_evidence, which verifies the evidence token using the + current environment. This operation returns a major_status code + which can be used to determine whether the evidence contained in a + token is complete (i.e., can be successfully verified (perhaps + years) later). If a token's evidence is not complete, the token can + be passed to form_complete_pidu to complete it. + + Additional useful calls for evidence services include: + * IDUP_Get_token_details (see Section 2.5.3); + * IDUP_Form_Complete_PIDU (see Section 2.4.2). + +2.3.3.2. IDUP_EV Parameters + + The following parameter bundles are used in the "EV" protection and + unprotection sets of calls. + + o Nr_Options PARAMETER BUNDLE + o evidence_type INTEGER { + no_evidence (0) + -- used when request-only token desired + proof_of_receipt (1), + proof_of_delivery (2), + + + +Adams Informational [Page 28] + +RFC 2479 IDUP-GSS-API December 1998 + + + proof_of_approval (3), + proof_of_creation (4), + proof_of_sender (5), + proof_of_origin (6) + } OPTIONAL, + o evidence_type_oid OBJECT IDENTIFIER OPTIONAL, + -- may be used in place of above parameter if OID is known + o evidence_validity_duration INTEGER, + -- duration_in_minutes + -- DURATION_HOUR = 60; + -- DURATION_DAY = 1440; + -- DURATION_WEEK = 10080; + -- DURATION_MONTH = 43200;// 30 days + -- DURATION_YEAR = 525600;//365 days + o mech_indep_encap_req BOOLEAN -- (see Appendix A) + + o Originator_Information PARAMETER BUNDLE + o token_generator_name INTERNAL NAME, + -- obtained from the credentials of the originator + -- (e.g., from its public key certificate) + o token_generator_role Originator_Role OPTIONAL, + -- (see Section 2.3.4.1) + o protection_time INTEGER OPTIONAL + + o Bad_Target_Name PARAMETER BUNDLE -- (see Section 2.3.2.2) + o bad_targ_name INTERNAL NAME, + o bad_targ_status INTEGER + -- a status flag giving the reason for rejection of the + -- name in bad_targ_name + + o Target_Info PARAMETER BUNDLE -- same as in Section 2.3.2.2 + o targ_names SET OF INTERNAL NAME, + o bad_targ_count INTEGER, + o bad_target_names SET OF Bad_Target_Name + + o Request_Features PARAMETER BUNDLE + o requested_evidence_type INTEGER { + no_evidence (0), - used when no token desired + proof_of_receipt (1), + proof_of_delivery (2), + proof_of_approval (3), }, + o nr_req_policy OBJECT IDENTIFIER, + o evidence_from Target_Info, + o evidence_to Target_Info, + o include_received_token_in_evidence BOOLEAN + + The following data_type is used in the "EV" protection calls. + + + + +Adams Informational [Page 29] + +RFC 2479 IDUP-GSS-API December 1998 + + + o Nr_Operation INTEGER { + evidence_and_or_evidence_request (1), + returned_evidence (2) } + +2.3.3.3. IDUP_EV major_status codes + + The following major_status return codes are defined for the "EV" + calls in this section: + + o GSS_S_COMPLETE + -- indicates that the evidence is complete + o IDUP_S_INCOMPLETE + o IDUP_S_MORE_OUTBUFFER_NEEDED + -- returned (by any EV call) to indicate that there is more output + -- data than can fit into the supplied buffers. The application + -- should save the returned data and call again to retrieve the + -- remaining output. + o IDUP_S_INCONSISTENT_PARAMS + o GSS_S_CREDENTIALS_EXPIRED + o IDUP_S_NO_MATCH + o IDUP_S_NO_ENV + o GSS_S_FAILURE + + If Target_Info is used as an input parameter (i.e., if an evidence is + being requested ), the following major_status return code is also + defined: + + o IDUP_S_BAD_TARG_INFO + + Note for this return code that 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 (with associated status + codes in bad_targ_status). As long as at least one of the targets + can be used, however, this does not cause this call to fail (i.e., + the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the + caller's choice to discontinue IDU protection if the target set which + can be used is unsuitable for the caller's purposes. + +2.3.3.4. IDUP_EV_SingleBuffer_Generate call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o nr_operation Nr_Operation, + o Nr_Options PARAMETER BUNDLE, + o idu_buffer OCTET STRING, + o form_complete_pidu BOOLEAN, + -- if TRUE the implementation will attempt to form a complete PIDU + o include_data_in_token BOOLEAN, + + + +Adams Informational [Page 30] + +RFC 2479 IDUP-GSS-API December 1998 + + + -- if TRUE, data provided in idu_buffer will be included in the + -- generated token; if FALSE, the data will not be included + o Request_Features PARAMETER BUNDLE + -- the type of the evidence that is requested; + -- policy under which the returned evidence should be generated; + -- the recipients that are supposed to send back an evidence; + -- the recipients that should receive the requested evidence; + -- an indicator include_received_token_in_evidence: + -- if TRUE, the evidence token incorporating the request will be + -- included in the data for which recipients will generate + -- evidence; if FALSE, evidence will be generated using only + -- the data (and not the token incorporating the request). + o additional_protection BOOLEAN -- (see Section 2.3.2.4) + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o token OCTET STRING, + o evidence_check OCTET STRING, + -- present only if an evidence is requested. Consists of data to + -- be used to verify the requested token(s) (if any) when they are + -- received. + + Description: + + This operation generates a non-repudiation token associated with the + data passed in an input buffer. Two kinds of operations can be + performed (using the Nr_Operation parameter): + + a) generating a token that includes either an evidence only, or + an evidence request only, or both an evidence and an evidence + request; + + b) generating a response token for some recipients that includes an + evidence generated as a response to a request (in this case the + idu_buffer is used to enter the request token that was received). + + It is possible to request the generation of complete evidence. This + may succeed or fail; if it fails, a subsequent call to + Form_Complete_PIDU can be made. + +2.3.3.5. IDUP_EV_SingleBuffer_Verify call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o token OCTET STRING, + o external_idu_buffer OCTET STRING, + -- if not present within the token + + + +Adams Informational [Page 31] + +RFC 2479 IDUP-GSS-API December 1998 + + + o evidence_check OCTET STRING, + -- present only if the input token is a response to a previous + -- request for evidence (this parameter is used to validate that + -- evidence). + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o Nr_Options PARAMETER BUNDLE, + o Originator_Information PARAMETER BUNDLE, + o Request_Features PARAMETER BUNDLE, + o trusted_time_stamping_time INTEGER OPTIONAL, + -- present for informational purposes only + o complete_evidence_before INTEGER OPTIONAL, + -- if the major status code that is returned is + -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called + -- with the same token before this time. + -- This may be required, for example, in order to insure that + -- the time skew between the evidence generation time and + -- the trusted time service's countersignature on the evidence + -- falls within the interval allowed by the current NR policy. + o complete_evidence_after INTEGER OPTIONAL, + -- if the major status code that is returned is + -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called + -- with the same token after this time. + -- This may be required, for example, to insure that all + -- authorities involved in generating the evidence have passed + -- the last time at which the current NR policy allows them to + -- repudiate their keys. + o encapsulated_idu_buffer OCTET STRING + -- if the IDU was present within the token + o additional_unprotection BOOLEAN -- (see Section 2.3.2.5) + + Description: + + Verifies the validity and discloses the content of a nr_token. + + If the token containing the evidence to be verified was provided to + the calling application by a partner responding to the calling + application's request, then the calling application must pass the + evidence check it received when it generated the request as a + parameter along with the token it received from the partner. + + Output indicators are provided which give guidance about the time or + times at which form_complete_pidu should be called; see the parameter + descriptions for explanations of these indicators and their use. Note + that the time specified by complete_evidence_before may be earlier + than that specified by complete_evidence_after; in this case it will + + + +Adams Informational [Page 32] + +RFC 2479 IDUP-GSS-API December 1998 + + + be necessary to call form_complete_pidu twice. + + Because keys can be revoked or declared compromised, the return from + verify_evidence cannot in all cases be a definitive "valid" or + "invalid"; sometimes "conditionally valid" may be returned, depending + upon the policy in use. IDUP_S_INCOMPLETE will be returned, for + example, if: + + - the interval during which the generator of the evidence may + permissibly declare his key invalid has not yet expired (and + therefore it is possible that the evidence may be declared invalid + in the future), or + + - trusted time is required for verification, and the time obtained + from the token is not trusted. + +2.3.3.6. IDUP_EV_MultiBuffer_StartGenerate call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o nr_operation Nr_Operation, + o Nr_Options PARAMETER BUNDLE, + o form_complete_pidu BOOLEAN, + o include_data_in_token BOOLEAN, + o idu_size INTEGER, -- (see Section 2.3.4.2) + o Request_Features PARAMETER BUNDLE + o additional_protection BOOLEAN -- (see Section 2.3.2.4) + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o initial_pidu_buffer OCTET STRING + -- may be empty (depends on underlying mechanism) + + Description: + + Using the security environment referenced by env_handle, initialize + the data structures required to begin the generation of a token. The + IDU will be supplied in multiple buffers to the + IDUP_EV_Process_Buffer call). Two kinds of operations can be + performed (using the Nr_Operation parameter) : + + a) generating a token that includes either an evidence only, or + an evidence request only, or both an evidence and an evidence + request. + + + + + + +Adams Informational [Page 33] + +RFC 2479 IDUP-GSS-API December 1998 + + + b) generating a return token for some recipients that includes an + evidence generated as a response to a request. In that case the + received token will be passed into the subsequent + IDUP_EV_Process_Buffer calls. The boolean include_data_in_token + is ignored as the output will always be contained in a single + token. The Request_Features are ignored in that case at this + time in order to keep things simple and to avoid the piggy- + backing that is theoretically possible. + + It is possible to request the generation of complete evidence. This + may succeed or fail; if it fails, a subsequent call to + Form_Complete_PIDU can be made. + +2.3.3.7. IDUP_EV_MultiBuffer_EndGenerate call + + Inputs: + o env_handle ENVIRONMENT HANDLE + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o final_pidu OCTET STRING, + o token OCTET STRING, + o evidence_check OCTET STRING + -- present only if an evidence is requested. + + Description: + + Using the security environment referenced by env_handle, provide the + requested token or the final P-IDU. A token will be generated if + encapsulation was not requested; otherwise, the final P-IDU is + provided. + +2.3.3.8. IDUP_EV_MultiBuffer_StartVerify call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o token OCTET STRING, + o evidence_check OCTET STRING, + -- present only if an evidence has been previously requested. + + Outputs: + o major_status INTEGER, + o minor_status INTEGER + + + + + + + +Adams Informational [Page 34] + +RFC 2479 IDUP-GSS-API December 1998 + + + Description: + + Using the security environment referenced by env_handle, initialize + the data structures required to begin the process of verifying the + token. The P-IDU will be supplied in multiple buffers to the + IDUP_EV_Process_Buffer call. + +2.3.3.9. IDUP_EV_MultiBuffer_EndVerify call + + Input: + o env_handle ENVIRONMENT HANDLE + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o Nr_Options PARAMETER BUNDLE, + o Originator_Information PARAMETER BUNDLE, + o Request_Features PARAMETER BUNDLE, + o trusted_time_stamping_time INTEGER OPTIONAL, + o complete_evidence_before INTEGER OPTIONAL, + o complete_evidence_after INTEGER OPTIONAL, + o idu_buffer OCTET STRING + -- if the IDU was present within the token + o additional_unprotection BOOLEAN -- (see Section 2.3.2.5) + + Description: + + Using the security environment referenced by env_handle, complete the + verification processing on the data and provide verified output + parameters to the caller when the major status code is either: + + o GSS_S_COMPLETE or + o IDUP_S_INCOMPLETE + +2.3.3.10. IDUP_EV_Process_Buffer 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 + -- may be zero length (depends on underlying mechanism and + -- corresponding Generate () call and options + -- (e.g., data_included_in_token) + + + + +Adams Informational [Page 35] + +RFC 2479 IDUP-GSS-API December 1998 + + + Description: + + Using the security environment referenced by env_handle, continue the + processing on the data in input_buffer and, if it is available, put + any resulting output data in output_buffer. The application calls + this routine over and over again with new buffers of data until it + has processed all the data buffers of the IDU/PIDU. It then calls the + appropriate End() call to complete the processing. + +2.3.4. The "GP" Calls + + The "GP" group of calls provides a powerful interface to flexible and + sophisticated combinations of protection and unprotection services. + This power and flexibility, however, necessitates a more complex + interface than either the SE or the EV calls. Furthermore, such + combinations of services are not needed in many of the security + mechanisms in common use today (although this is likely to change as + time goes on). The GP calls are therefore specified to be OPTIONAL + and need not be supported by IDUP-conformant implementations. Note, + however, that the structure of IDUP tokens should be such that the + SE/EV and GP calls may be used interchangably by the receiver. + +2.3.4.1. Parameter Bundles + + The concept of "parameter bundles" is used in the calls presented in + the following subsections in order to simplify their presentation and + clarify their intended purpose and use (note that specific language + bindings may or may not use parameter bundles for its actual calling + conventions). A parameter bundle is simply a set of closely-related + parameters of a call which are either all used by / available to the + calling application or all not used by / unavailable to the calling + application. These parameters may be all input parameters, all + output parameters, or any combination of the two. + + An example use envisioned for parameter bundles in a language such as + C would be as a structure, where individual parameters in the bundle + are structure members. The calling application wishing to use a + particular bundle would then allocate the appropriate structure + variable, assign the desired input values to the appropriate members, + and pass the address of the structure as the bundle "parameter". On + output, the values of the appropriate output members may be read. An + application not wishing to use a particular bundle (or one which is + satisfied with default values for all input parameters of the bundle + and which doesn't care about output values), can pass NULL as the + bundle "parameter". From the mechanism implementor's perspective, if + a parameter bundle is not supported (for example, if it represents a + security service which is not supported by the implementation), then + any non-NULL value passed as the bundle parameter will generate an + + + +Adams Informational [Page 36] + +RFC 2479 IDUP-GSS-API December 1998 + + + error status return code. + + [Note that the parameter bundles given below, except where explicitly + referenced by the SE and EV calls, are specific to the (optional) GP + calls. Thus, these bundles need not be supported by IDUP-conformant + implementations if the GP calls are not supported.] + + The following parameter bundles are used in the subsequent protection + and unprotection sets of calls. A parameter preceded by "(I)" is an + input parameter; one preceded by "(O)" is an output parameter; one + preceded by neither is an input if the bundle itself is an input and + is an output if the bundle itself is an output; one preceded by "(X)" + is the opposite: an output if the bundle itself is an input and an + input if the bundle itself is an output. + + o Mech_Specific_Info PARAMETER BUNDLE + -- actual parameters included in this bundle are defined by (and + -- specific to) the underlying mechanism + + o Sensitivity PARAMETER BUNDLE, + -- actual parameters included in this bundle are defined by (and + -- specific to) the underlying mechanism, but may include + -- codified values for "Unclassified", "Secret", "Top Secret", + -- and so on + + o Service_Creation_Info PARAMETER BUNDLE + -- actual parameters included in this bundle are defined by (and + -- specific to) the underlying mechanism, but it is mandatory + -- that they include at least service_id and Quality + + o Service_Verification_Info PARAMETER BUNDLE + -- actual parameters included in this bundle are defined by (and + -- specific to) the underlying mechanism, but it is mandatory + -- that they include at least service_id and Quality + + o Quality PARAMETER BUNDLE + o qop_algs UNSIGNED INTEGER, + o qop_algID AlgorithmIdentifier, --overrides qop_algs + o validity UNSIGNED INTEGER, + -- protection guaranteed to be valid until time specified + o policy_id OBJECT IDENTIFIER, + -- security policy under which protection is/was carried out + o allow_policy_mapping BOOLEAN, + -- determines whether mapping between policy IDs is allowed + o actual_policy_time INTEGER + -- time at which the above policy rules came into effect + + + + + +Adams Informational [Page 37] + +RFC 2479 IDUP-GSS-API December 1998 + + + o Idu_Information PARAMETER BUNDLE, + o idu_type_oid OBJECT IDENTIFIER, + o idu_type_string OCTET STRING, + o idu_title OCTET STRING, + o idu_sensitivity Sensitivity, + o pidu_type_oid OBJECT IDENTIFIER, + o pidu_type_string OCTET STRING, + o pidu_title OCTET STRING, + o pidu_sensitivity Sensitivity, + + o Prot_Information PARAMETER BUNDLE, + o originator_name INTERNAL NAME, + o originator_role Originator_Role, + o idu_information Idu_Information, + o protection_time INTEGER, + + o Originator_Role PARAMETER BUNDLE, -- role in organization + o domain_name INTERNAL NAME OPTIONAL, + o role PRINTABLE STRING, + o role_info_is_authenticated BOOLEAN + -- TRUE if info. is authenticated (e.g., inside a cert.) + + o Special_Conditions PARAMETER BUNDLE, + o prot_oper_id INTEGER, + o form_complete_pidu BOOLEAN, + -- input to protection operations for evidence generation + o pidu_in_solic_service BOOLEAN, + -- in protection operations, used as input for service + -- solicitation to request that receiver include the + -- received PIDU when generating the response. In unprot. + -- operations, used as output to inform receiver that PIDU + -- should be included when generating the response. + o use_trusted_time BOOLEAN, + o use_untrusted_time BOOLEAN, + o mech_indep_encap_req BOOLEAN -- (see Appendix A) + + o Bad_Target_Name PARAMETER BUNDLE, + o (O) bad_targ_name INTERNAL NAME, + o (O) bad_targ_status INTEGER, + -- a status flag giving the reason for rejection of + -- the name in bad_targ_name. Specified reasons include: + -- SYNTAX_INVALID (0) + -- the syntax of the name is invalid; + -- NAME_UNRECOGNIZED (1) + -- the name is not recognized; + -- NAME_AMBIGUOUS (2) + -- the name cannot be resolved; + -- ACCESS_DENIED (3) + + + +Adams Informational [Page 38] + +RFC 2479 IDUP-GSS-API December 1998 + + + -- access to this target is denied; + -- CERTIFICATE_NOT_FOUND (4) + -- the encryption certificate of the target could + -- not be found. + + o Target_Info PARAMETER BUNDLE, + o targ_names SET OF INTERNAL NAME, + o (O) bad_targ_count INTEGER, + o (O) bad_target_names SET OF Bad_Target_Name, + + o General_Service_Data PARAMETER BUNDLE, + o target_info Target_Info, + o (X) unencapsulated_token OCTET STRING, + -- zero length if encapsulation_request is TRUE + o (O) minor_status INTEGER, + + Three types of protection services are defined in IDUP. These are: + + 1. perform unsolicited service (i.e., act on a locally-generated + service request), + 2. perform solicited service (i.e., act on a remotely-generated + service request), and + 3. perform service solicitation (i.e., send a service request to + the remote end). + + As an originator, applying data confidentiality with data integrity, + or data origin authentication with data integrity, or proof of origin + evidence is an example of service type 1. As a target, creating a + proof of delivery (i.e., receipt) evidence token as the result of a + request received from the originator is an example of service type 2. + Finally, as an originator, submitting a request that one or more + targets return a receipt for the data sent is an example of service + type 3. + + The first four parameters in the Prot_Service parameter bundle + pertain to all service types; the fifth parameter is used if and only + if service type 2 is desired; parameters 6-8 are used if and only if + service type 3 is desired. + + o Prot_Service PARAMETER BUNDLE + o (I) prot_service_type INTEGER, + o (I) service_id OBJECT IDENTIFIER, + o (I) quality Quality, -- NULL specifies default Quality + o (I) general_service_data General_Service_Data, + o (I) service_creation_info Service_Creation_Info, + o (I) service_to SET OF INTERNAL NAME, + o (O) service_verification_info Service_Verification_Info, + o (O) service_verification_info_id INTEGER, + + + +Adams Informational [Page 39] + +RFC 2479 IDUP-GSS-API December 1998 + + + Also, three types of unprotection services are defined. These are: + + 1. receive unsolicited service (i.e., process unrequested + remotely-generated service), + 2. receive solicited service (i.e., process remotely-generated + response to locally-generated request), and + 3. receive service solicitation (i.e., process req. from rem. end) + + As a target, unprotecting an encrypted message, or verifying the + originator's proof of origin is an example of service type 1. As an + originator, verifying a proof of delivery which you requested from a + target is an example of service type 2. Finally, as a target, + receiving a request from an originator for a proof of delivery is an + example of service type 3. + + The first four parameters in the Unprot_Service parameter bundle + pertain to all service types; parameters 5-6 are used if and only if + service type 2 is required; parameters 7-8 are used only if service + type 3 is required. + + o Unprot_Service PARAMETER BUNDLE + o (O) unprot_service_type INTEGER, + o (O) service_id OBJECT IDENTIFIER, + o (O) quality Quality, + -- actual Quality specified (never NULL) + o (O) general_service_data General_Service_Data, + o (O) service_verification_info_id INTEGER, + o (I) service_verification_info Service_Verification_Info, + o (O) service_to SET OF INTERNAL NAME, + o (O) service_creation_info Service_Creation_Info, + +2.3.4.2. IDUP_Start_Protect call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o Mech_Specific_Info PARAMETER BUNDLE, + -- NULL selects the mechanism-defined default values + o Idu_Information PARAMETER BUNDLE, + o Special_Conditions PARAMETER BUNDLE, + o encapsulation_request BOOLEAN, + o single_idu_buffer OCTET STRING, + -- non-zero length for this buffer means that Protect/End_Protect + -- won't be called (i.e., entire IDU is contained in this buffer) + o idu_size INTEGER, + -- size (in bytes) of the IDU to be protected; + -- may be "-1" signifying "UNKNOWN" (note that some mechanisms + -- may not support encapsulation in such a case) + o Target_Info PARAMETER BUNDLE, + + + +Adams Informational [Page 40] + +RFC 2479 IDUP-GSS-API December 1998 + + + o Services_to_Perform SET OF Prot_Service, + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o midu_buffer OCTET STRING, + -- zero length if encapsulation_request is TRUE; + -- may be zero length otherwise (depends on underlying mechanism) + o pidu_buffer OCTET STRING, + -- zero length if encapsulation_request is FALSE; + -- may be zero length otherwise (depends on underlying mechanism) + + Return major_status codes: + o GSS_S_COMPLETE + -- the protection process can begin (or has completed, if + -- single_idu_buffer has non-zero length). + o IDUP_S_MORE_OUTBUFFER_NEEDED + o GSS_S_CREDENTIALS_EXPIRED + o IDUP_S_NO_ENV + o IDUP_S_ENCAPSULATION_UNAVAIL + o IDUP_S_SERVICE_UNAVAIL + o IDUP_S_REQ_TIME_SERVICE_UNAVAIL + o IDUP_S_UNKNOWN_OPER_ID + o GSS_S_BAD_QOP + o IDUP_S_BAD_TARG_INFO + o GSS_S_FAILURE + + Using the security environment referenced by env_handle, initialize + the data structures required to begin the process of protecting the + IDU buffers. The caller requests specific protection services by + supplying the appropriate Prot_Service parameter bundles in + Services_to_Perform. Each service is able to return a minor status + code to the calling application, if necessary. + + The calling application, knowing the size of the IDU it wishes to + protect and the buffer size which it has available to it, can choose + to input the entire IDU in a single buffer and omit the subsequent + IDUP_Protect() and IDUP_End_Protect() calls. Furthermore, the + application can request that the resulting M-IDU be encapsulated in + the token -- so that the token contains the entire P-IDU -- rather + than having it be returned separately in midu_buffer. Encapsulation, + however, may not be supported by all underlying mechanisms or + implementations; if this is the case, the + IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and + M-IDU will be returned in midu_buffer. + + + + + + +Adams Informational [Page 41] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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]. 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 + token (from stage 1) in stage 2. + + Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where + "n" is the number of stages as defined by the mechanism (typically 1 + or 2)). The calling application uses this parameter to indicate to + the underlying mechanism whether it wishes to do stage 1 of + protection / unprotection processing, or stage 2, and so on. Portable + applications may pass "0" to let the mechanism choose the stage (note + that mechanism implementers may still iterate when prot_oper_id = 0 + (e.g., use output as next input, et cetera). + + 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 (with associated status codes in bad_targ_status). 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 choice to discontinue IDU + protection if the target set which can be used is unsuitable for the + caller's purposes. Note that each Prot_Service parameter bundle can + also input a list of targ_names; this is used if a separate list is + to be used for that service only (the general list of targets is to + be used for all services unless overridden in this way). + +2.3.4.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 + -- may be zero length if encapsulation_request was set to TRUE in + -- IDUP_Start_Protect() (depends on underlying mechanism) + + Return major_status codes: + o GSS_S_COMPLETE + o IDUP_S_NO_ENV + + + +Adams Informational [Page 42] + +RFC 2479 IDUP-GSS-API December 1998 + + + o GSS_S_FAILURE + + Using the security environment referenced by env_handle, continue the + protection processing on the data in input_buffer and, if the + underlying mechanism defines this, put any resulting P-IDU/M-IDU data + in output_buffer. The application calls this routine over and over + again with new buffers of data until it has protected all the data + buffers of the IDU. It then calls IDUP_End_Protect() to complete the + protection processing. + +2.3.4.4. IDUP_End_Protect call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o Services_to_Perform SET OF Prot_Service, + o final_midu_buffer OCTET STRING, + -- zero length if encapsulation_request was set to TRUE in + -- IDUP_Start_Protect(), in which case pidu is used + o final_pidu_buffer OCTET STRING, + -- zero length if encapsulation_request was set to FALSE in + -- IDUP_Start_Protect(), in which case token and midu are used + + Return major_status codes: + o GSS_S_COMPLETE + -- protection has successfully completed and the resulting P-IDU + -- is ready for transfer. If defined by the underlying mechanism, + -- final_midu_buffer will contain any residual M-IDU data. + o IDUP_S_MORE_OUTBUFFER_NEEDED + o IDUP_S_NO_ENV + o GSS_S_FAILURE + + Using the security environment referenced by env_handle, complete the + protection processing on the data and place the computed output in + final_pidu_buffer (or final_midu_buffer and the unencapsulated_token + parameter for each Prot_Service). If a service was requested from + one or more targets in Start_Protect() - and if this is supported by + the underlying mechanism - Service_Verification_Info will hold + whatever data is necessary for the mechanism to verify a service + returned by a target (unprotector) 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). + + + + +Adams Informational [Page 43] + +RFC 2479 IDUP-GSS-API December 1998 + + +2.3.4.5. IDUP_Start_Unprotect call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o Mech_Specific_Info PARAMETER BUNDLE, + -- NULL selects the mechanism-defined default values + o single_pidu_buffer OCTET STRING, + -- non-zero length for this buffer means that IDUP_Unprotect() and + -- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU + -- (if encapsulation is used) or M-IDU (if encap. is not used) + -- is contained in this buffer) + o partial_pidu_buffer OCTET STRING, + -- may be an arbitrary-sized piece of the full pidu (if the + -- application's buffer isn't large enough to hold entire pidu). + -- Used if pidu_buffer will be input a buffer at a time (except + -- that the final buffer must be passed in final_pidu_buffer + -- rather than partial_pidu_buffer). Only one of + -- single_pidu_buffer and partial(final)_pidu_buffer can have + -- nonzero length. + o final_pidu_buffer OCTET STRING, + o Special_Conditions PARAMETER BUNDLE, + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o Services_to_Receive SET OF Unprot_Service, + o Prot_Information PARAMETER BUNDLE, + o single_idu_buffer OCTET STRING, + -- if this buffer has non-zero length, then service processing has + -- been completed on the data in single_pidu_buffer + o initial_idu_buffer OCTET STRING, + -- holds any data from partial(final)_pidu_buffer which has been + -- unprotected; remaining data will be returned by Unprotect and + -- End_Unprotect as they are called with successive buffers of + -- pidu + o Service_Verification_Info PARAMETER BUNDLE, + -- used only if target is on "service_to" list in Unprot_Service + o service_verification_info_id INTEGER, + -- used only if target is on "service_to" list in Unprot_Service + + + + + + + + + + + + +Adams Informational [Page 44] + +RFC 2479 IDUP-GSS-API December 1998 + + + Return major_status codes: + o GSS_S_COMPLETE + -- unprotection processing can begin (or has completed, if + -- single_idu_buffer has non-zero length). + o IDUP_S_INCOMPLETE + -- used only if single_idu_buffer has non-zero length. + o IDUP_S_MORE_OUTBUFFER_NEEDED + o IDUP_S_MORE_PIDU_NEEDED + o GSS_S_DEFECTIVE_TOKEN + o IDUP_S_INAPPROPRIATE_CRED + o IDUP_S_INCONSISTENT_PARAMS + o IDUP_S_DEFECTIVE_VERIF + o IDUP_S_NO_MATCH + o IDUP_S_SERVICE_UNAVAIL + o IDUP_S_REQ_TIME_SERVICE_UNAVAIL + o IDUP_S_SERV_VERIF_INFO_NEEDED + o GSS_S_CREDENTIALS_EXPIRED + o IDUP_S_NO_ENV + o IDUP_S_UNKNOWN_OPER_ID + o GSS_S_BAD_QOP + -- the qop_algs value specified in P-IDU for at least one of the + -- services is unavailable in the local mechanism, so processing + -- cannot continue. + o GSS_S_BAD_MIC + o IDUP_S_BAD_DOA_KEY + o IDUP_S_BAD_KE_KEY + o IDUP_S_BAD_ENC_IDU + o GSS_S_FAILURE + + Using the security environment referenced by env_handle, initialize + the data structures required to begin the process of unprotecting a + P-IDU. The caller will be alerted as to which services were applied + to the P-IDU in the returned Services_to_Receive set of parameters. + + If encapsulation was not used by the originator, it is the receiving + application's responsibility to separate the received P-IDU into a + M-IDU and one or more unencapsulated_token buffers (the latter being + input in separate Unprot_Service bundles in the Services_to_Receive + parameter). These unencapsulated_token buffers should be input + before the M-IDU (i.e., in IDUP_Start_Unprotect) or after the M-IDU + (i.e., in IDUP_End_Unprotect) as appropriate; this order may be + dictated, for example, by their placement in the in-coming message. + + If unprotection will be applied more than once to a given P-IDU, it + is the responsibility of the calling application to remember if a + service solicitation has been responded to previously (i.e., if the + requested service has already been generated / sent for that P-IDU) + and thus ignore subsequent solicitations on unprotect. + + + +Adams Informational [Page 45] + +RFC 2479 IDUP-GSS-API December 1998 + + + The time flags indicate whether to consult trusted, untrusted, or no + time (if both flags are FALSE) during the unprotection operation. If + the current time is not to be checked, then unprotection may be + successful even if the protector's key has expired since the P-IDU + was generated (that is, if the Validity period -- as specified in the + Quality parameter bundle -- has expired). + + If the underlying mechanism supports it and if this information is + contained in the P-IDU, information regarding the originator (that + is, the entity which used the protection set of calls to generate + this P-IDU) is returned in the Prot_Information parameter bundle. + +2.3.4.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 + o IDUP_S_NO_ENV + o GSS_S_FAILURE + + Using the security environment referenced by env_handle, continue the + unprotection processing on the data in input_buffer, putting any + resulting IDU data in output_buffer (if required). + +2.3.4.7. IDUP_End_Unprotect call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o Prot_Information PARAMETER BUNDLE, + o Services_to_Receive SET OF Unprot_Service, + o final_idu_buffer OCTET STRING, + o Service_Verification_Info PARAMETER BUNDLE, + -- used only if target is on "service_to" list in Unprot_Service + o service_verification_info_id INTEGER, + -- used only if target is on "service_to" list in Unprot_Service + + + + +Adams Informational [Page 46] + +RFC 2479 IDUP-GSS-API December 1998 + + + Return major_status codes: + o GSS_S_COMPLETE + -- residual IDU data will be returned in final_idu_buffer. + o IDUP_S_INCOMPLETE + o IDUP_S_MORE_OUTBUFFER_NEEDED + o GSS_S_BAD_MIC + o IDUP_S_BAD_DOA_KEY + o IDUP_S_BAD_KE_KEY + o IDUP_S_BAD_ENC_IDU + o IDUP_S_NO_ENV + o GSS_S_FAILURE + + Using the security environment referenced by env_handle, complete the + unprotection processing on the data and return the appropriate status + code. If there is any residual IDU data it will be returned in + final_idu_buffer. + + If the IDUP_S_INCOMPLETE major status value is returned, all output + parameters are conditionally valid; the unprotection set of functions + will have to be called again (perhaps with a complete P-IDU, as + produced by IDUP_Form_Complete_PIDU) in order to get valid values for + all parameters. "Conditional validity" may arise, for example, if + all relevant certificates verify correctly, but it is not yet past + the time up to which the current policy allows the authorities + involved to repudiate their keys. + + If the underlying mechanism supports it and if this information is + contained in the token, information regarding the originator (that + is, the entity which used the protection set of calls to generate + this token) is returned in the Prot_Information parameter bundle. + This information may or may not be omitted if it was returned by the + IDUP_Start_Unprotect() call. + + Note that, 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 call described in this section has no analog in + GSS-API [RFC-2078]. This call is used to complete a P-IDU (that is, + to generate a P-IDU which can be unprotected successfully with no + additional data at any time during its validity period). This call + may not be supported by all underlying IDUP mechanisms or + + + +Adams Informational [Page 47] + +RFC 2479 IDUP-GSS-API December 1998 + + + implementations. + +2.4.2. IDUP_Form_Complete_PIDU call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + o single_pidu_buffer OCTET STRING, + o partial_pidu_buffer OCTET STRING, + -- an arbitrary-sized piece of the full pidu token. Used if pidu + -- will be input a buffer at a time (except that the final buffer + -- must be passed in final_pidu_buffer rather than + -- partial_pidu_buffer). Only one of single_pidu_buffer and + -- partial(final)_pidu_buffer can have nonzero length. + o final_pidu_buffer OCTET STRING, + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o pidu_token_out OCTET STRING -- the augmented PIDU; may be complete + o call_again_before INTEGER, + o call_again_after INTEGER, + o trusted_time_stamping_time INTEGER -- for information only + + Return major_status codes: + o GSS_S_COMPLETE + o IDUP_S_MORE_OUTBUFFER_NEEDED + o IDUP_S_INCOMPLETE + -- generation of the P-IDU is not yet complete. The application + -- should call this function again before the time given in + -- call_again_before (if not NULL), or after the time given in + -- call_again_after (if not NULL), or both (if neither are NULL). + o IDUP_S_INCONSISTENT_PARAMS + o IDUP_S_SERVICE_UNAVAIL + o GSS_S_DEFECTIVE_TOKEN + o GSS_S_FAILURE + + Form_Complete_PIDU is used primarily by the evidence services; in + particular, when the evidence token itself does not contain all the + data required for its verification and it is anticipated that some of + the data not stored in the token may become unavailable during the + interval between generation of the evidence token and verification + unless it is stored in the token. The Form_Complete_PIDU operation + gathers the missing information and includes it in the token so that + verification can be guaranteed to be possible at any future time. + + This call generates a PIDU which can be unprotected successfully with + no additional data at any time during its validity period. [For + background information on the notion of "complete" evidence, see + + + +Adams Informational [Page 48] + +RFC 2479 IDUP-GSS-API December 1998 + + + "CORBA Security Service v1.2 Draft D02", 18 June 1997.] + + Using the security environment referenced by env_handle, complete the + generation of a P-IDU token and return the appropriate status value + along with the completed token (if available). Such a call may be + used, for example, for the purpose of batch evidence generation on an + "evidence server". A local machine may be able to use the protection + set of calls to fill out most of an evidence token and then send a + number of these to a batch processor which forms the complete + evidence tokens (perhaps by adding a certification path, or a + timestamp and signature from a timestamping authority). As another + example, on the receiving end an application may make such a call in + order to collect all the information necessary to unprotect a P-IDU + (such as all relevant certificates and Certificate Revocation Lists); + this will ensure that the calls to the unprotection set of operations + will be entirely local (i.e., can be performed off-line) and fast. + + Note that the complete P-IDU generated will be formed using trusted + time if this is available in the environment referenced by env_handle + and will use untrusted time or no time otherwise (depending on what + is available). + +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-2078]. The calls described in Section 2.4 + of GSS-API (including all associated parameters) are unchanged. The + following additional calls are specified for IDUP-GSS-API. + +2.5.2: IDUP_Acquire_cred_with_auth call + + Inputs: + o desired_name INTERNAL NAME, + -- NULL requests locally-determined default + o authenticator OCTET STRING + -- string which authenticates the caller claiming to be + -- desired_name + o lifetime_req INTEGER, + -- in seconds; 0 requests default + o desired_mechs SET OF OBJECT IDENTIFIER, + -- empty set requests system-selected default + o cred_usage BIT STRING + -- actual values which can be used currently correspond to those + -- given in Section 2.1.1 (i.e., + -- ENCRYPT_ONLY 8 + -- DECRYPT_ONLY 16 + + + +Adams Informational [Page 49] + +RFC 2479 IDUP-GSS-API December 1998 + + + -- SIGN_ONLY 32 + -- VERIFY_ONLY 64 + -- with the values logically OR'ed together in any desired + -- combination to restrict credential usage; OR'ing all values + -- results in NO_RESTRICTION). + -- Future possible values for this parameter are for further + -- study (note that the type of this parameter is BIT STRING + -- (rather than INTEGER as in GSS_Acquire_cred) to facilitate + -- such future expansion). + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o output_cred_handle CREDENTIAL HANDLE, + o actual_mechs SET OF OBJECT IDENTIFIER, + o actual_cred_usage BIT STRING, + o lifetime_rec INTEGER + -- in seconds, or reserved value for INDEFINITE + + This call (which need not be supported by all underlying mechanisms + or implementations) is identical to the GSS_Acquire_cred call, with + the exception of the added input parameter "authenticator" and the + added output parameter "actual_cred_usage". The authenticator + (typically a password, pass-phrase, or PIN) is used to authenticate + the caller claiming to be desired_name to the underlying GSS (or + mechanism) code. The actual_cred_usage specifies the actual uses + available for these credentials; it is up to the caller to determine + if this is sufficient for its purposes. + + Implementations that are able to authenticate the caller in some + other way are encouraged to use the GSS_Acquire_cred call; those + having no other means available to them, or wishing to explicitly + authenticate the caller at the time of credential acquisition, should + use the IDUP_Acquire_cred_with_auth call (if supported). + + Note that the return major status codes for this call are identical + to those given for the GSS_Acquire_cred call. If the authentication + fails (e.g., the wrong authenticator is supplied for the given + desired_name), the major status GSS_S_FAILURE is returned (along with + an appropriate minor status code). + +2.5.3. IDUP_Get_token_details call + + Inputs: + o token OCTET STRING, + -- all the data to be returned shall be within the first 4 KB of + -- the token; hence, a single call is needed. It is not necessary + -- to provide the entire token when the token includes the IDU. + + + +Adams Informational [Page 50] + +RFC 2479 IDUP-GSS-API December 1998 + + + o mech_type SET OF OBJECT IDENTIFIER + -- input if known (typically SET will contain a single member) + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o actual_mech_type OBJECT IDENTIFIER, + o data_included_in_token BOOLEAN, + -- true if the data is encapsulated + o idu_size INTEGER, + o has_SE_protection BOOLEAN, + o has_EV_protection BOOLEAN, + o PIDU_Information PARAMETER BUNDLE, + o nr_policy OBJECT IDENTIFIER, + -- this and subsequent parameters pertain only to evidence tokens + o Nr_Options PARAMETER BUNDLE, + o Originator_Information PARAMETER BUNDLE, + o time_stamping_time INTEGER OPTIONAL + o Request_Features PARAMETER BUNDLE, + -- describes the included request, if any. + o requested_evidence_back BOOLEAN, + -- true if this is an evidence generated in response to a + -- previously-sent request + o evidence_check OCTET STRING, + -- meaningful if the boolean above is true + + Return major_status codes: + o GSS_S_COMPLETE + -- input_token could be parsed for all relevant fields. + o GSS_S_CREDENTIALS_EXPIRED + o GSS_S_DEFECTIVE_TOKEN + -- the mechanism type could be parsed, but either the other fields + -- could not be determined from the input_token, or their values + -- did not correspond to valid values for that mechanism. + o GSS_S_FAILURE + -- the mechanism type was missing or corrupted. + + IDUP_Get_token_details() is used to return to an application the + attributes that 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. + + + + + +Adams Informational [Page 51] + +RFC 2479 IDUP-GSS-API December 1998 + + + If all tokens are framed as suggested in Section 3.1 of [RFC-2078] + (mandated in the Kerberos V5 GSS mechanism [RFC 1964] and in the SPKM + GSS Mechanism [RFC 2025]), then any mechanism implementation should + be able to return the mech_type parameter for any uncorrupted input + token. If the mechanism implementation whose IDUP_Get_token_details() + function is being called does recognize the token, it can return any + further relevant information in the other token attributes, as + specified. In particular, this function can set has_SE_protection if + the SE calls may be used to unprotect it, or has_EV_protection if the + EV calls may be used to unprotect it, or both if both kinds of + protection have been applied (so that SE or EV calls may be used in + any order for unprotection) [note that GP calls, when supported, + should be usable for unprotection of any IDUP token]. + + IDUP_Get_token_details (which need not be supported by all underlying + mechanisms or implementations) gives only a hint about the content of + the token, there is no integrity check of any kind performed. + Regardless of the token type, it is possible to check that this + information is correct only by doing a proper unprotection of the + token. It is recommended that IDUP callers supply a token buffer at + least 4 KB in length in order to ensure that the desired data can + easily flow across this interface. + + The OID of the mechanism and whether the token contains the + associated data is returned. In addition the size of the associated + data, whether inside or outside the token, is included if known. + [Note: data size will typically be unknown if the data was protected + using multibuffer calls. A value of "-1" may be used to indicate + "UNKNOWN".] + + When the input token contains only an evidence generated + spontaneously, the following is returned: + - the evidence type; + - the Non-Repudiation policy under which the evidence was generated; + - the name of the generator of the evidence; + - the date and time when the evidence was generated (if available); + - the date and time when it was time stamped (if available). + + When the input token contains only an evidence generated in response + to a request from another entity, the following additional + information is returned: + - an indicator to state that this evidence relates to a request; + - a string significant for the requester that will allow him to + check whether the answer corresponds to the requested evidence. + + When the input token only contains a request, the following is + returned: + - the name of the requestor of the evidence, + + + +Adams Informational [Page 52] + +RFC 2479 IDUP-GSS-API December 1998 + + + - the date and time when the request was made, + - the evidence type to send back, + - the non-repudiation policy under which the evidence to send back + should be generated, + - the names of the recipients which should generate and distribute + the requested evidence, + - the names of the recipients to whom the requested evidence should + be sent after it has been generated. + + When the input token contains both evidence and a request, an + indicator is returned describing whether the new evidence should be + generated using only the data in the input token, or using both the + data and the evidence in the input token. + + When the input token contains only CONF and DOA services, the + PIDU_Information bundle is returned. Other relevant parameters (such + as idu_size and time_stamping_time) may also be returned if this data + is available. + +2.5.4. IDUP_Get_policy_info call + + Inputs: + o policy_id OBJECT IDENTIFIER + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o policy_version INTEGER, + o policy_effective_time INTEGER, + o policy_expiry_time INTEGER, + o supported_services SET OF Service_Descriptor, + -- services supported by this particular policy_id (equal to the + -- intersection of the services supported by the mechanisms + -- listed in supported_mechanisms) + o supported_mechanisms SET OF Mechanism_Descriptor + -- mechanisms supported by this particular policy_id + + Return major_status codes: + o GSS_S_COMPLETE + -- policy_id recognized; all relevant fields have been returned. + o GSS_S_FAILURE + -- the policy_id was not recognized. + + This call (which need not be supported by all underlying mechanisms + or implementations) allows the application to retrieve information + pertaining to a given policy_id. Policies define the following: + - rules for the protection of IDUs, such as trusted third + parties which may be involved in P-IDU generation, the roles in + + + +Adams Informational [Page 53] + +RFC 2479 IDUP-GSS-API December 1998 + + + which they may be involved, and the duration for which the + generated P-IDU is valid; + + - rules for the unprotection of P-IDUs, such as the interval + during which a trusted third party may legitimately declare its + key to have been compromised or revoked; and + + - rules for adjudication, such as which authorities may be used + to adjudicate disputes. + + The policy itself may be used by an adjudicator when resolving a + dispute. For example, the adjudicator might refer to the policy to + determine whether the rules for generation of the P-IDU have been + followed. + + The following parameter bundles are associated with this call. + + o Service_Descriptor PARAMETER BUNDLE, + o service_type OBJECT IDENTIFIER, + o service_validity_duration INTEGER, + o must_use_trusted_time BOOLEAN + + o Mechanism_Descriptor PARAMETER BUNDLE, + o mechanism_type OBJECT IDENTIFIER, + o Authority_List PARAMETER BUNDLE, + o maximum_time_skew INTEGER + -- maximum permissible difference between P-IDU generation + -- time and the time of countersignature from a time + -- service (if required). This parameter is unused if + -- trusted time is not required. + + o Authority_List PARAMETER BUNDLE, + o authority_name INTERNAL NAME, + o authority_role OCTET STRING, + o last_revocation_check_offset INTEGER + -- may be 0, greater than 0, or less than 0. The value of + -- this parameter is added to P-IDU generation time to + -- get latest time at which the mechanism will check to + -- see if this authority's key has been revoked. + + An example of the use of the last parameter in Authority_List is as + follows. If an authority has a defined last_revocation_check_offset + of negative one hour, then all revocations taking effect earlier than + one hour before the generation of a P-IDU will render that P-IDU + invalid; no revocation taking place later than one hour before the + generation of the P-IDU will affect the P-IDU's validity. + + + + + +Adams Informational [Page 54] + +RFC 2479 IDUP-GSS-API December 1998 + + + Note that both the maximum_time_skew and the + last_revocation_check_offset values are given in minutes. + +2.5.5. IDUP_Cancel_multibuffer_op call + + Inputs: + o env_handle ENVIRONMENT HANDLE, + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + + Return major_status codes: + o GSS_S_COMPLETE + -- operation cancelled; state purged. + o GSS_S_FAILURE + -- unable to cancel operation; state retained. + + This call (which need not be supported by all underlying mechanisms + or implementations) allows the application to cancel a multibuffer + operation prior to normal completion (e.g., subsequent to calling + Start_operation and zero or more Process_operation, but prior to + calling End_operation). When successful, this call purges any + internal state information which would have been used to continue + processing for the full set of multibuffer calls. + +3. 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 and parameter bundle) 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. + + + + + + + + +Adams Informational [Page 55] + +RFC 2479 IDUP-GSS-API December 1998 + + +4. Acknowledgments + + Many thanks are due to Tim Moses and Dhanya Thakkar of Entrust + Technologies, Denis Pinkas of Bull, and David Kurn of Tandem + Computers for a number of helpful comments and contributions. + +5. Security Considerations + + Security issues are discussed throughout this memo. + +6. REFERENCES + + [MSP] U.S. National Security Agency, "Message Security + Protocol", Secure Data Network System SDN.701, March + 1994. + + [RFC-1421] Linn, J., "Privacy Enhancement for Internet Electronic + Mail: Part I: Message Encryption and Authentication + Procedures", RFC 1421, February 1993. + + [RFC-2078] Linn, J., "Generic Security Service Application Program + Interface, Version 2", RFC 2078, January 1997.. + + [RFC 1964] Linn, J, "The Kerberos Version 5 GSS-API Mechanism", RFC + 1964, June 1996. + + [RFC 2025] Adams, C., "The Simple Public-Key GSS-API Mechanism + (SPKM)", RFC 2025, October 1996. + + [ISO/IEC] 2nd ISO/IEC CD 13888-1, "Information technology - + Security techniques - Non-repudiation - Part 1: General + Model", ISO/IEC JTC 1/SC 27, May 30, 1995 + +7. Author's Address + + Carlisle Adams + Entrust Technologies + 750 Heron Road, Suite E08, + Ottawa, Ontario, CANADA K1V 1A7 + + Phone: +1 613.247.3180 + EMail: cadams@entrust.com + + + + + + + + + +Adams Informational [Page 56] + +RFC 2479 IDUP-GSS-API December 1998 + + +APPENDIX A: MECHANISM-INDEPENDENT TOKEN FORMAT + + This appendix specifies the use, for IDUP-GSS-API tokens, of the + mechanism-independent level of encapsulating representation for + tokens given in Section 3.1 of GSS-API [RFC-2078]. The + representation given there incorporates an identifier of the + mechanism type to be used when processing the associated tokens. Use + of that octet format 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. It is recognized, + however, that for interoperability purposes with peers not using IDUP + for specific IDU protection/unprotection protocols, the encapsulating + representation may need to be omitted. (In such a case it is + necessary that the underlying mechanism provides some sort of + internal or external identification that allows it to recognize its + own tokens.) When the mechanism-independent level of encapsulating + representation is not desired, callers SHOULD set + mech_indep_encap_req to FALSE (note that some underlying mechanisms + may default this parameter to FALSE). + + For purely descriptive purposes, the following simple ASN.1 structure + is used to illustrate the structural relationships among token and + tag objects. For interoperability purposes, token and tag encoding + shall be performed using the concrete encoding procedures described + in Section 3.1 of GSS-API [RFC-2078]. + + -- top-level token definition to frame different mechanisms + + IDUP-GSS-API DEFINITIONS ::= + BEGIN + MechType ::= OBJECT IDENTIFIER + + Token ::= [APPLICATION 0] IMPLICIT SEQUENCE { + thisMech MechType, + token ANY DEFINED BY thisMech + -- contents mechanism-specific + } + END + + + + + + + + + + + + + +Adams Informational [Page 57] + +RFC 2479 IDUP-GSS-API December 1998 + + +APPENDIX B: EXAMPLES OF IDUP USE + + This appendix provides examples of the use of IDUP to do IDU + protection and unprotection. 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 particular + underlying technology, and does not demonstrate all IDUP-GSS-API + features. + + Most of the examples below only illustrate the use of CONF/DOA + protection services. Note that when both CONF/DOA and Evidence + services are required, calling applications may use a series of SE + and EV calls, or may use the GP calls (when these are supported). + Using the former approach implies multiple calls (e.g., the SE calls + are used to protect some data and the resulting token is then input + to the EV calls to add evidence information), but some callers may + find this to be more attractive than coding to the GP calls because + of the simpler SE/EV interface. Depending upon the underlying + mechanism, the series of SE/EV calls may result in a single token + that can be unprotected using the SE and EV calls in any order (for + example, because it is a single ASN.1 SEQUENCE that incorporates all + the specified protection services at one level), or the series may + result in a token that can only be unprotected in the reverse order + of protection (for example, because each SE/EV output token was + effectively embedded in the token of the subsequent call). The + IDUP_Get_token_details call can assist callers in determining how to + unprotect any received token. + +B.1. Simple Mechanism, Single Buffer + + To illustrate the simplest possible case, consider an underlying IDUP + mechanism which does straightforward encryption/decryption and + signing/verification only using public-key techniques; none of the + other possible services, such as creation of proof-of-origin + evidence, requests for proof-of-delivery evidence, or use of trusted + time, are supported. PEM[RFC-1421] is one example of a mechanism + which fits this description. Furthermore (again for simplicity), + assume that encapsulation is chosen by the calling application during + IDU protection. + + Such a mechanism would likely use the "SE" set of IDUP-GSS-API calls. + The following parameter bundle uses and defaults would therefore be + specified in the relevant IDUP mechanism document. + + + + + + + + +Adams Informational [Page 58] + +RFC 2479 IDUP-GSS-API December 1998 + + + SENDER: + + Set + env_handle = environment handle in use; + idu_buffer = data buffer; + Target_Info.targ_names = receiver names; + Protect_Options = as necessary; + + Call + IDUP_SE_SingleBuffer_Protect() with above input parameters + + Check + major_status. If not GSS_S_COMPLETE, check + minor_status, + Target_Info.Bad_Targ_Name, + (as required) for more detailed information. + + Send + Output parameter pidu_buffer to receiver. + + RECEIVER (any parameters not listed below are given the value NULL): + + Set + env_handle = environment handle in use; + pidu_buffer = received data buffer; + + Call + IDUP_SE_SingleBuffer_Unprotect() with above input parameters + Check + major_status. If not GSS_S_COMPLETE, check + minor_status, + (as required) for more detailed information + + Utilize + PIDU_Information.Protect_Options.Protect_Operation, + (to determine which services were applied by the originator) + PIDU_Information.Protect_Options.sign_qop_alg / enc_qop_alg, + (to determine the corresponding qualities of the services) + Prot_Information.originator_name, + (to determine the name of the originator) + Prot_Information.protection_time, + (to determine when the IDU was protected) + idu_buffer + (to retrieve the unprotected data). + + + + + + + +Adams Informational [Page 59] + +RFC 2479 IDUP-GSS-API December 1998 + + +B.2. Simple Mechanism, Single Buffer (Again) + + To illustrate a slight variation on the simplest possible case, + assume that everything is as in the previous scenario except that the + "GP" calls are used. + + The following parameter bundle uses and defaults would therefore be + specified in the relevant IDUP mechanism document. + + Mech_Specific_Info + - NOT USED (the only acceptable input, therefore, is NULL) + + Idu_Sensitivity + - NOT USED (the only acceptable input, therefore, is NULL) + + Service_Creation_Info + - NOT USED (the only acceptable input, therefore, is NULL) + + Service_Verification_Info + - NOT USED (the only acceptable input, therefore, is NULL) + + Quality + - the qop_algs parameter must be supported, with a suitable + DEFAULT value specified; + - suitable DEFAULT values for validity, policy_id, and + allow_policy_mapping must be specified (it may be an + implementation option as to whether these parameters are + explicitly modifiable by the calling application, or whether + NULLs are the only acceptable input) + + Idu_Information + - the idu_type parameter must have a value representing a suitable + IDU type (for example, in PEM a value representing the string + "RFC822" or some other valid "Content-Domain" would be used), + with a suitable DEFAULT value specified; + - the idu_title parameter is NOT USED (the only acceptable input, + therefore, is NULL) + + Prot_Information + - the originator_name and idu_type (in Idu_Information) parameters + are read from the encapsulating information and output by + IDUP_Start_Unprotect; + - all other parameters are NOT USED (and therefore NULL) + + Special_Conditions + - NOT USED (the only acceptable input, therefore, is NULL) + + + + + +Adams Informational [Page 60] + +RFC 2479 IDUP-GSS-API December 1998 + + + Target_Info + - this bundle is used as described in IDUP; no DEFAULT values are + specified + + General_Service_Data + - the unencapsulated_token parameter is used if + encapsulation_request is FALSE; + - the minor_status parameter is used to return minor status values + as specified by the mechanism document + + Prot_Service + - the prot_service_type parameter may have a value of "1" + ("perform unsolicited service") or NULL (which specifies the + DEFAULT value of "1"); + - the service_id parameter must have a value representing + "PER_CONF" or "PER_DOA"; + - the parameters Service_Creation_Info, service_to, + Service_Verification_Info, and service_verification_info_id are + NOT USED (and therefore NULL) + + Unprot_Service + - the unprot_service_type parameter will always have a value of + "1" ("receive unsolicited service"); + - the service_id parameter will have a value representing + "REC_CONF" or "REC_DOA"; + - the parameters service_verification_info_id, + Service_Verification_Info, service_to, and + Service_Creation_Info, are NOT USED (and therefore NULL) + + Assuming that the calling application has only a single buffer of + data to protect/unprotect, the following sequence of operations must + be performed by the sender and receivers (subsequent to environment + establishment). + + SENDER (any parameters not listed below are given the value NULL): + + Set + env_handle = environment handle in use; + encapsulation_request = TRUE; + single_idu_buffer = data buffer; + Target_Info.targ_names = receiver names; + P_Services.Prot_Service_1.service_id = PER_CONF; + P_Services.Prot_Service_2.service_id = PER_DOA; + + Call + IDUP_Start_Protect() with above input parameters + + + + + +Adams Informational [Page 61] + +RFC 2479 IDUP-GSS-API December 1998 + + + Check + major_status. If not GSS_S_COMPLETE, check + minor_status, + Target_Info.bad_targ_names / Target_Info.bad_targ_status, + P_Services.Prot_Service_1.General_Service_Data.minor_status, + P_Services.Prot_Service_2.General_Service_Data.minor_status + (as required) for more detailed information. + + Send + Output parameter pidu_buffer to receiver. + + + RECEIVER (any parameters not listed below are given the value NULL): + + Set + env_handle = environment handle in use; + single_pidu_buffer = received data buffer; + + Call + IDUP_Start_Unprotect() with above input parameters + Check + major_status. If not GSS_S_COMPLETE, check + minor_status, + R_Services.Unprot_Service_1.General_Service_Data.minor_status, + R_Services.Unprot_Service_2.General_Service_Data.minor_status + (as required) for more detailed information + + Utilize + R_Services.Unprot_Service_1/2.service_id, + (to determine which services were applied by the originator) + R_Services.Unprot_Service_1/2.Quality, + (to determine the corresponding qualities of the services) + Prot_Information.originator_name, + (to determine the name of the originator) + single_idu_buffer + (to retrieve the unprotected data). + +B.3. Simple Mechanism, Multiple Buffers + + To illustrate the next step up in complexity, consider the use of the + simple IDUP mechanism described in B.2 above with multiple data + buffers. In particular, consider the case in which a large data file + is to be signed. For this example, assume that the calling + application does not wish to use encapsulation. + + Note that the parameter bundle uses and defaults are as specified in + B.2. above. + + + + +Adams Informational [Page 62] + +RFC 2479 IDUP-GSS-API December 1998 + + + SENDER (any parameters not listed below are given the value NULL): + + Set + env_handle = environment handle in use; + encapsulation_request = FALSE; + P_Services.Prot_Service.service_id = PER_DOA; + + Call + IDUP_Start_Protect() with above input parameters + Check + major_status. If not GSS_S_COMPLETE, check + minor_status, + P_Services.Prot_Service.General_Service_Data.minor_status + (as required) for more detailed information. + + For each buffer of input data: + Set + input_buffer = buffer + Call + IDUP_Protect() with above input parameter + Check + major_status. If not GSS_S_COMPLETE, check + minor_status + + Call + IDUP_End_Protect() + Check + major_status. If not GSS_S_COMPLETE, check + minor_status, + P_Services.Prot_Service.General_Service_Data.minor_status + (as required) for more detailed information. + + Send + P_Services.Prot_Service.General_Service_Data.unencapsulated_token, + and the file for which the signature was calculated (if required), + to receiver. + + RECEIVER (any parameters not listed below are given the value NULL): + + Set + env_handle = environment handle in use; + R_Services.Unprot_Service_1.General_Service_Data. + unencapsulated_token = received unencapsulated token; + + Call + IDUP_Start_Unprotect() with above input parameters + Check + major_status. If not GSS_S_COMPLETE, check + + + +Adams Informational [Page 63] + +RFC 2479 IDUP-GSS-API December 1998 + + + minor_status, + R_Services.Unprot_Service_1.General_Service_Data.minor_status, + (as required) for more detailed information + + For each buffer of input data: + Set + input_buffer = buffer + Call + IDUP_Unprotect() with above input parameter + Check + major_status. If not GSS_S_COMPLETE, check + minor_status + + Call + IDUP_End_Unprotect() + Check + major_status. If not GSS_S_COMPLETE, check + minor_status, + R_Services.Unprot_Service_1.General_Service_Data.minor_status, + (as required) for more detailed information. + + Utilize + R_Services.Unprot_Service_1.service_id, + (to determine which service was applied by the originator; note + that Unprot_Service_2 will have NULL in unprot_service_type + to indicate that it is not used) + R_Services.Unprot_Service_1.Quality, + (to determine the corresponding quality of the service) + Prot_Information.originator_name, (from IDUP_Start_Unprotect) + (to determine the name of the signer) + major_status (from IDUP_End_Unprotect) + (to determine pass/fail status of signature verification). + +B.4. More Sophisticated Mechanism, Small Application Buffers + + To illustrate a higher level of complexity, consider the use of a + more sophisticated IDUP mechanism and a calling application with + small data buffers. In particular, consider the case in which a very + small e-mail message is to be encrypted for a relatively large + receiver list (R), some subset of whom (r) will be asked to send + proofs of receipt of the message to some other subset (L) (which + includes the originator). So that the example is not unnecessarily + complicated, assume again that the originating application uses + encapsulation. + + The uses and defaults for the various parameter bundles for this + mechanism would be specified in the relevant IDUP mechanism document + as follows. + + + +Adams Informational [Page 64] + +RFC 2479 IDUP-GSS-API December 1998 + + + Mech_Specific_Info + - NOT USED (the only acceptable input, therefore, is NULL) + + Idu_Sensitivity + - NOT USED (the only acceptable input, therefore, is NULL) + + Service_Creation_Info + - used to create "proof of delivery" evidence (but actual + structure is opaque to calling application) + + Service_Verification_Info + - used to verify "proof of delivery" evidence (but actual + structure is opaque to calling application) + + Quality + - the qop_algs parameter must be supported, with a suitable + DEFAULT value specified; + - suitable DEFAULT values for validity, policy_id, and + allow_policy_mapping must be specified (it may be an + implementation option as to whether these parameters are + explicitly modifiable by the calling application, or whether + NULLs are the only acceptable input) + + Idu_Information + - the idu_type parameter must have a value representing a suitable + IDU type, with a suitable DEFAULT value specified; + - the idu_title parameter must have a value representing a + suitable IDU title, with a suitable DEFAULT value specified + + Prot_Information + - the originator_name, protection_time, and idu_type / idu_title + (in Idu_Information) parameters are read from the contained + header information and output by IDUP_Start_Unprotect; + + Special_Conditions + - the parameter prot_oper_id is NOT USED (the only acceptable + input, therefore, is NULL); + - trusted or untrusted time may be selected by the calling + application, with a suitable DEFAULT value specified + + Target_Info + - this bundle is used as described in IDUP; no DEFAULT values are + specified + + General_Service_Data + - the unencapsulated_token parameter is used if + encapsulation_request is FALSE; + - the minor_status parameter is used to return minor status values + + + +Adams Informational [Page 65] + +RFC 2479 IDUP-GSS-API December 1998 + + + as specified by the mechanism document + + Prot_Service + - the prot_service_type parameter may have a value of "1" + ("perform unsolicited service"), "2" ("perform solicited + service"), "3" (perform service solicitation), or NULL (which + specifies the DEFAULT value of "1"); + - the service_id parameter must have a value representing + "PER_CONF", "PER_DOA", "PER_POO", or "PER_POD"; + - the parameters Service_Creation_Info, service_to, + Service_Verification_Info, and service_verification_info_id are + used when required by the IDUP operation + + Unprot_Service + - the unprot_service_type parameter may have a value of "1" + ("receive unsolicited service"), "2" ("receive solicited + service"), or "3" (receive service solicitation); + - the service_id parameter will have a value representing + "REC_CONF", "REC_DOA", "REC_POO", or "REC_POD"; + - the parameters service_verification_info_id, + Service_Verification_Info, service_to, and + Service_Creation_Info, are used when required by the IDUP + operation + + + SENDER (any parameters not listed below are given the value NULL): + + Set + env_handle = environment handle in use; + Idu_Information.idu_type = value for "e-mail document"; + Idu_Information.idu_title = "Contract 1234"; + Special_Conditions.use_trusted_time = TRUE; + encapsulation_request = TRUE; + single_idu_buffer = very small e-mail message; + Target_Info.targ_names = receiver names (R); + Prot_Service_1.prot_service_type = "1"; + Prot_Service_1.service_id = PER_CONF; + Prot_Service_2.prot_service_type = "3"; + Prot_Service_2.service_id = PER_POD; + Prot_Service_2.General_Service_Data.Target_Info.targ_names + = "receipts from" list (r); + Prot_Service_2.service_to = "receipts to" list (L); + P_Services.Prot_Service_1 = Prot_Service_1; + P_Services.Prot_Service_2 = Prot_Service_2; + + Call + IDUP_Start_Protect() with above input parameters + + + + +Adams Informational [Page 66] + +RFC 2479 IDUP-GSS-API December 1998 + + + Check + major_status. If not GSS_S_COMPLETE, + while major_status == IDUP_S_MORE_OUTBUFFER_NEEDED + Save + pidu_buffer, + Call + IDUP_Start_Protect() (to get next portion of pidu_buffer) + Check + major_status, + minor_status, + Target_Info.bad_targ_names / Target_Info.bad_targ_status, + P_Services.Prot_Service_1.General_Service_Data.minor_status, + P_Services.Prot_Service_2.General_Service_Data.minor_status + (as required) for more detailed information. + + Save + Prot_Service_2.Service_Verification_Info, + Prot_Service_2.service_verification_info_id + + Send + All saved buffers of pidu_buffer to receiver list (R). + + + RECEIVER (ON RECEIVER LIST (R)): + (any parameters not listed below are given the value NULL) + + Set + env_handle = environment handle in use; + partial_pidu_buffer = initial buffer of received p-idu; + + Call + IDUP_Start_Unprotect() with above input parameters + While major_status == IDUP_S_MORE_PIDU_NEEDED, + Set + partial_pidu_buffer = next buffer of p-idu + Call + IDUP_Start_Unprotect() + Check + major_status, + minor_status, + R_Services.Unprot_Service_1.General_Service_Data.minor_status, + R_Services.Unprot_Service_2.General_Service_Data.minor_status, + (as required) for more detailed information + + Save + initial_idu_buffer (if non-empty) + + + + + +Adams Informational [Page 67] + +RFC 2479 IDUP-GSS-API December 1998 + + + Set + input_buffer = remaining p-idu buffer + Call + IDUP_Unprotect() with above input parameter + Check + major_status. If not GSS_S_COMPLETE, check + minor_status + Save + output_buffer + + Call + IDUP_End_Unprotect() + Check + major_status. If not GSS_S_COMPLETE, check + minor_status, + R_Services.Unprot_Service_1.General_Service_Data.minor_status, + R_Services.Unprot_Service_2.General_Service_Data.minor_status, + (as required) for more detailed information. + + Utilize + R_Services.Unprot_Service_1/2.service_id, + (to determine which services were applied by the originator) + R_Services.Unprot_Service_1/2.Quality, + (to determine the corresponding qualities of the service) + Prot_Information.originator_name/protection_time and + Prot_Information.Idu_Information.idu_type/idu_title, + (from IDUP_Start_Unprotect) (to determine originator info.) + R_Services.Unprot_Service_2.General_Service_Data.Target_Info. + targ.names, (to determine if rec. is in "receipts from" (r)) + Service_Verification_Info/service_verification_info_id + (to determine if receiver is in "receipts to" list (L)) + + If receiver is in "receipts from" list (r) + Save + R_Services.Unprot_Service_2.service_to, + R_Services.Unprot_Service_2.Service_Creation_Info + + If receiver is in "receipts to" list (L) + Save + Service_Verification_Info, + service_verification_info_id + + RECEIVER (ON "RECEIPTS FROM" LIST (r)): + (procedure to generate receipt) + + Set + env_handle = environment handle in use; + Target_Info.targ_names = service_to + + + +Adams Informational [Page 68] + +RFC 2479 IDUP-GSS-API December 1998 + + + Prot_Service_1.prot_service_type = "2"; + Prot_Service_1.service_id = "PER_POD"; + Prot_Service_1.Service_Creation_Info = Service_Creation_Info; + P_Services.Prot_Service_1 = Prot_Service_1 + + Call + IDUP_Start_Protect() with above input parameters + Check + major_status. If not GSS_S_COMPLETE, check + minor_status, + P_Services.Prot_Service_1.General_Service_Data.minor_status + (as required) for more detailed information. + + Send + pidu_buffer to "receipts to" list (L) + + RECEIVER (ON "RECEIPTS TO" LIST (L)): + (procedure to process received receipt) + + Set + env_handle = environment handle in use; + single_pidu_buffer = received p-idu buffer (if it fits in a single + buffer; otherwise use partial_pidu_buffer and make multiple + calls, as above) + + Call + IDUP_Start_Unprotect() with above input parameters + If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED + Utilize + R_Services.Unprot_Service_1.service_verification_info.id + (to assist in locating necessary Service_Verification_Info) + Set + R_Services.Unprot_Service_1.Service_Verification_Info + = Service_Verification_Info + Call + IDUP_Start_Unprotect() with above input parameters + Check + major_status, + minor_status, + R_Services.Unprot_Service_1.General_Service_Data.minor_status + (as required) for more detailed information. + + Utilize + R_Services.Unprot_Service_1.service_id, + (to determine that this is a "proof of delivery" evidence) + R_Services.Unprot_Service_1.Quality, + Prot_Information.originator_name, (for evidence generator info.) + major_status (to determine pass/fail status of evi. verif.). + + + +Adams Informational [Page 69] + +RFC 2479 IDUP-GSS-API December 1998 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1998). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + + + + + + + + + + + + + + + + + + + + + + + + +Adams Informational [Page 70] + |