idnits 2.17.1 draft-ietf-cat-idup-gss-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-27) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 3722 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([RFC-2078]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 758: '... confPolicy [0] PolicyAndTime OPTIONAL,...' RFC 2119 keyword, line 760: '... integPolicy [1] PolicyAndTime OPTIONAL,...' RFC 2119 keyword, line 762: '... evidencePolicy [2] PolicyAndTime OPTIONAL...' RFC 2119 keyword, line 1103: '...get_Info_S PARAMETER BUNDLE OPTIONAL,...' RFC 2119 keyword, line 1147: '...get_Info_S PARAMETER BUNDLE OPTIONAL,...' (9 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 2529 has weird spacing: '... to a reque...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 758 -- Looks like a reference, but probably isn't: '1' on line 760 -- Looks like a reference, but probably isn't: '2' on line 762 == Missing Reference: 'APPLICATION 0' is mentioned on line 2736, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'MSP' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Obsolete normative reference: RFC 2078 (Obsoleted by RFC 2743) -- No information found for draft-ietf-cat-idup-cbind-0x - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'IDUP-C' Summary: 12 errors (**), 0 flaws (~~), 4 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Draft C. Adams, Entrust Technologies 2 draft-ietf-cat-idup-gss-07.txt Mar. 25, 1997 4 Independent Data Unit Protection Generic Security Service 5 Application Program Interface (IDUP-GSS-API) 7 STATUS OF THIS MEMO 9 This document is an Internet-Draft. Internet-Drafts are working 10 documents of the Internet Engineering Task Force (IETF), its areas, 11 and its working groups. Note that other groups may also distribute 12 working documents as Internet-Drafts. 14 Internet-Drafts are draft documents valid for a maximum of six 15 months and may be updated, replaced, or obsoleted by 16 other documents at any time. It is inappropriate to use Internet- 17 Drafts as reference material or to cite them other than as 18 "work in progress." 20 To learn the current status of any Internet Draft, please check the 21 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 22 Directories on ds.internic.net (US East Coast), nic.nordu.net 23 (Europe), ftp.isi.edu (US West Coast) or munnari.oz.au (Pacific Rim). 25 Comments on this document should be sent to "cat-ietf@mit.edu", the 26 IETF Common Authentication Technology WG discussion list. 28 ABSTRACT 30 The IDUP-GSS-API extends the GSS-API [RFC-2078] for applications 31 requiring protection of a generic data unit (such as a file or 32 message) in a way which is independent of the protection of any other 33 data unit and independent of any concurrent contact with designated 34 "receivers" of the data unit. Thus, it is suitable for applications 35 such as secure electronic mail where data needs to be protected 36 without any on-line connection with the intended recipient(s) of that 37 data. The protection offered by IDUP includes services such as data 38 origin authentication with data integrity, data confidentiality with 39 data integrity, and support for non-repudiation services. Subsequent 40 to being protected, the data unit can be transferred to the 41 recipient(s) - or to an archive - perhaps to be processed 42 ("unprotected") only days or years later. 44 Throughout the remainder of this document, the "unit" of data 45 described in the above paragraph will be referred to as an IDU 46 (Independent Data Unit). The IDU can be of any size (the application 47 may, if it wishes, split the IDU into pieces and have the protection 48 computed a piece at a time, but the resulting protection token 49 applies to the entire IDU). However, the primary characteristic of 50 an IDU is that it represents a stand-alone unit of data whose 51 protection is entirely independent of any other unit of data. If an 52 application protects several IDUs and sends them all to a single 53 receiver, the IDUs may be unprotected by that receiver in any order 54 over any time span; no logical connection of any kind is implied by 55 the protection process itself. 57 Adams Document Expiration: 25 Sept. 1997 1 59 As with RFC-2078, this IDUP-GSS-API definition provides security 60 services to callers in a generic fashion, supportable with a range of 61 underlying mechanisms and technologies and hence allowing source- 62 level portability of applications to different environments. This 63 specification defines IDUP-GSS-API services and primitives at a level 64 independent of underlying mechanism and programming language environ- 65 ment, and is to be complemented by other, related specifications: 67 - documents defining specific parameter bindings for particular 68 language environments; 69 - documents defining token formats, protocols, and procedures to 70 be implemented in order to realize IDUP-GSS-API services atop 71 particular security mechanisms. 73 TABLE OF CONTENTS 74 1. IDUP-GSS-API Characteristics and Concepts .................. 3 75 1.1. IDUP-GSS-API Constructs .................................. 5 76 1.1.1. Credentials ............................................ 5 77 1.1.2. Tokens ................................................. 5 78 1.1.3. Security Environment ................................... 5 79 1.1.4. Mechanism Types ........................................ 5 80 1.1.5. Naming ................................................. 5 81 1.1.6. Channel Bindings ....................................... 5 82 1.2. IDUP-GSS-API Features and Issues ......................... 5 83 1.2.1. Status Reporting ....................................... 6 84 1.2.2. Per-IDU Security Service Availability .................. 8 85 1.2.3. Per-IDU Replay Detection and Sequencing ................ 8 86 1.2.4. Quality of Protection .................................. 8 87 1.2.5. The Provision of Time .................................. 10 88 2. Interface Descriptions ..................................... 10 89 2.1. Credential management calls .............................. 12 90 2.1.1. Relationship to GSS-API ................................ 12 91 2.2. Environment-level calls .................................. 12 92 2.2.1. Relationship to GSS-API ................................ 12 93 2.2.2. IDUP_Establish_Env call ................................ 12 94 2.2.3. IDUP_Abolish_Env call .................................. 15 95 2.2.4. IDUP_Inquire_Env call .................................. 15 96 2.3. Per-IDU calls ............................................ 16 97 2.3.1. Relationship to GSS-API ................................ 16 98 2.3.2. The "SE" Calls ......................................... 17 99 2.3.3. The "EV" Calls ......................................... 21 100 2.3.4. Parameter Bundles ...................................... 29 101 2.3.5. IDUP_Start_Protect ..................................... 32 102 2.3.6. IDUP_Protect ........................................... 34 103 2.3.7. IDUP_End_Protect ....................................... 35 104 2.3.8. IDUP_Start_Unprotect ................................... 36 105 2.3.9. IDUP_Unprotect ......................................... 38 106 2.3.10. IDUP_End_Unprotect ..................................... 38 107 2.4. Special-Purpose calls .................................... 39 108 2.4.1. Relationship to GSS-API ................................ 39 109 2.4.2. IDUP_Form_Complete_PIDU ................................ 39 110 2.5. Support calls ............................................ 40 111 2.5.1. Relationship to GSS-API ................................ 40 112 2.5.2. IDUP_Acquire_Cred_With_Auth ............................ 41 113 2.5.3. IDUP_Parse_Token ....................................... 42 114 2.5.4. IDUP_Get_Token_Details ................................. 43 115 2.5.5. IDUP_Get_Policy_Info ................................... 44 117 Adams Document Expiration: 25 Sept. 1997 2 119 3. Related Activities ......................................... 45 120 4. Acknowledgments ............................................ 46 121 5. Security Considerations .................................... 46 122 6. References ........................................... 46 123 7. Author's Address ........................................... 46 124 Appendix A .................................................... 47 125 Appendix B .................................................... 48 127 1. IDUP-GSS-API Characteristics and Concepts 129 The paradigm within which IDUP-GSS-API operates is as follows. An 130 IDUP-GSS-API caller is any application which works with IDUs, calling 131 on IDUP-GSS-API in order to protect its IDUs with services such as 132 data origin authentication with integrity (DOA), confidentiality with 133 integrity (CONF), and/or support for non-repudiation (e.g., evidence 134 generation, where "evidence" is information that either by itself or 135 when used in conjunction with other information is used to establish 136 proof about an event or action (note: the evidence itself does not 137 necessarily prove truth or existence of something, but contributes to 138 establish proof) -- see [ISO/IEC] for fuller discussion regarding 139 evidence and its role in various types of non-repudiation). An 140 IDUP-GSS-API caller passes an IDU to, and accepts a token from, its 141 local IDUP-GSS-API implementation, transferring the resulting 142 protected IDU (P-IDU) to a peer or to any storage medium. When a 143 P-IDU is to be "unprotected", it must be passed to an IDUP-GSS-API 144 implementation for processing. The security services available 145 through IDUP-GSS-API in this fashion are implementable over a range 146 of underlying mechanisms based on secret-key and/or public-key 147 cryptographic technologies. 149 During the protection operation, the input IDU buffers may be 150 modified (for example, the data may be encrypted or encoded in some 151 way) or may remain unchanged. In any case, the result is termed a 152 "M-IDU" (Modified IDU) in order to distinguish it from the original 153 IDU. Depending on the desire of the calling application and the 154 capabilities of the underlying IDUP mechanism, the output produced by 155 the protection processing may or may not encapsulate the M-IDU. 156 Thus, the P-IDU may be the data in a single output parameter (if 157 encapsulation is done) or may be the logical concatenation of an 158 unencapsulated token parameter and a M-IDU parameter (if 159 encapsulation is not done). In the latter case, the protecting 160 application may choose whatever method it wishes to concatenate or 161 combine the unencapsulated token and the M-IDU into a P-IDU, provided 162 the unprotecting application knows how to de-couple the P-IDU back 163 into its component parts prior to calling the IDUP unprotection set 164 of functions. 166 It is expected that any output buffer which is returned by IDUP 167 (i.e., P-IDU or portion thereof) is ready for immediate transmission 168 to the intended receiver(s) by the calling application, if this is 169 desired. In other words, an application wishing to transmit data 170 buffers as they appear from IDUP should not be unduly restricted 171 from doing so by the underlying mechanism. 173 The IDUP-GSS-API separates the operation of initializing a security 174 environment (the IDUP_Establish_Env() call) from the operations of 175 providing per-IDU protection, for IDUs subsequently protected in 176 conjunction with that environment. Per-IDU protection and 177 unprotection calls provide DOA, CONF, evidence, and other services, 178 as requested by the calling application and as supported by the 179 underlying mechanism. 181 Adams Document Expiration: 25 Sept. 1997 3 183 The following paragraphs provide an example illustrating the 184 dataflows involved in the use of the IDUP-GSS-API by the sender and 185 receiver of a P-IDU in a mechanism-independent fashion. The example 186 assumes that credential acquisition has already been completed by 187 both sides. Furthermore, the example does not cover all possible 188 options available in the protection/unprotection calls. 190 The sender first calls IDUP_Establish_Env() to establish a 191 security environment. Then, for the IDU to be protected the 192 sender calls IDUP_Start_Protect(), IDUP_Protect() for each buffer 193 of data, and IDUP_End_Protect() to complete the IDU protection. 194 The resulting P-IDU, which may (depending on whether or not 195 encapsulation was chosen/available) be either the token itself 196 or the logical concatenation of the token and the M-IDU, is now 197 ready to be sent to the target. The sender then calls 198 IDUP_Abolish_Env() to flush all environment-specific information. 200 The receiver first calls IDUP_Establish_Env() to establish a 201 security environment in order to unprotect the P-IDU. Then, for 202 the received P-IDU the receiver calls IDUP_Start_Unprotect(), 203 IDUP_Unprotect() for each buffer of data, and IDUP_End_Unprotect() 204 to complete the P-IDU unprotection. The receiver then calls 205 IDUP_Abolish_Env() to flush all environment-specific information. 207 It is important to note that absolutely no synchronization is implied 208 or expected between the data buffer size used by the sender as input 209 to the protection calls, the data buffer size used by the receiver as 210 input to the unprotection calls, and the block sizes required by the 211 underlying protection algorithms (integrity and confidentiality). 212 All these sizes are meant to be independent; furthermore, the data 213 buffer sizes used for the protection and unprotection calls are 214 purely a function of the local environment where the calls are made. 216 The IDUP-GSS-API design assumes and addresses several basic goals, 217 including the following. 219 Mechanism independence: The IDUP-GSS-API defines an interface to 220 cryptographically implemented security services at a generic level 221 which is independent of particular underlying mechanisms. For 222 example, IDUP-GSS-API-provided services can be implemented by 223 secret-key technologies or public-key approaches. 225 Protocol environment independence: The IDUP-GSS-API is independent 226 of the communications protocol suites which may be used to 227 transfer P-IDUs, permitting use in a broad range of protocol 228 environments. 230 Protocol association independence: The IDUP-GSS-API's security 231 environment construct has nothing whatever to do with 232 communications protocol association constructs, so that 233 IDUP-GSS-API services can be invoked by applications, wholly 234 independent of protocol associations. 236 Suitability for a range of implementation placements: IDUP-GSS-API 237 clients are not constrained to reside within any Trusted Computing 238 Base (TCB) perimeter defined on a system where the IDUP-GSS-API is 239 implemented; security services are specified in a manner suitable 240 for both intra-TCB and extra-TCB callers. 242 Adams Document Expiration: 25 Sept. 1997 4 244 1.1. IDUP-GSS-API Constructs 246 This section describes the basic elements comprising the 247 IDUP-GSS-API. 249 1.1.1. Credentials 251 Credentials in IDUP-GSS-API are to be understood and used as 252 described in GSS-API [RFC-2078]. 254 1.1.2. Tokens 256 Tokens in IDUP-GSS-API are to be understood and used as described in 257 GSS-API [RFC-2078] with the exception that there are no context-level 258 tokens generated by IDUP-GSS-API. The IDUP-GSS-API token 259 may (depending on the underlying mechanism) encapsulate the M-IDU or 260 may be logically concatenated with M-IDU prior to transfer to a 261 target; furthermore, for some evidence services the token may be sent 262 independently of any other data transfer. 264 1.1.3. Security Environment 266 The "security environment" in IDUP-GSS-API is entirely different from 267 the concept of security contexts used in GSS-API [RFC-2078]. Here, a 268 security environment exists within a calling application (that is, it 269 is purely local to the caller) for the purpose of protecting or 270 unprotecting one or more IDUs using a particular caller credential or 271 set of credentials. In GSS-API, on the other hand, a security 272 context exists between peers (the initiator and the target) for the 273 purpose of protecting, in real time, the data that is exchanged 274 between them. Although they are different concepts, the env_handle 275 in IDUP-GSS-API is similar to the context_handle in GSS-API in that 276 it is a convenient way of tying together the entire process of 277 protecting or unprotecting one or more IDUs using a particular 278 underlying mechanism. As with the GSS-API security contexts, a 279 caller can initiate and maintain multiple environments using the same 280 or different credentials. 282 1.1.4. Mechanism Types 284 Mechanism types in IDUP-GSS-API are to be understood and used as 285 described in GSS-API [RFC-2078]. 287 1.1.5. Naming 289 Naming in IDUP-GSS-API is to be understood and used as described in 290 GSS-API [RFC-2078]. 292 1.1.6. Channel Bindings 294 The concept of channel bindings discussed in GSS-API [RFC-2078] is 295 not relevant to the IDUP-GSS-API. 297 1.2. IDUP-GSS-API Features and Issues 299 This section describes aspects of IDUP-GSS-API operations and of the 300 security services which the IDUP-GSS-API provides. It also provides 301 commentary on design issues. 303 Adams Document Expiration: 25 Sept. 1997 5 305 1.2.1. Status Reporting 307 Status reporting in IDUP-GSS-API is to be understood and used as 308 described in GSS-API [RFC-2078], with the addition of a number of 309 IDUP-specific status codes. Descriptions of the major_status codes 310 used in IDUP are provided in Table 1. Codes that are informatory 311 (i.e., that do not cause the requested operation to fail) are 312 indicated with the symbol "(I)". 314 As with GSS-API, minor_status codes, which provide more detailed 315 status information than major_status codes, and which may include 316 status codes specific to the underlying security mechanism, are not 317 specified in this document. 319 Table 1: IDUP-GSS-API Major Status Codes 321 GSS_S_BAD_MECH indicates that a mech_type unsupported by the 322 IDUP_GSS-API implementation was requested, causing the 323 environment establishment operation to fail. 325 GSS_S_BAD_QOP indicates that the provided qop_alg value is not 326 recognized or supported for the environment. 328 GSS_S_BAD_SIG indicates that the received P-IDU contains an 329 incorrect integrity field (e.g., signature or MAC) for the data. 331 GSS_S_COMPLETE indicates that environment-level information was 332 successfully initialized, and that IDU / P-IDU processing can 333 begin on the newly-established environment. 335 GSS_S_CONTINUE_NEEDED indicates that the output buffer 336 supplied is too small to hold the generated data. The application 337 should continue calling this routine (until GSS_S_COMPLETE is 338 returned) in order to get all remaining data. 340 GSS_S_CREDENTIALS_EXPIRED indicates that the credentials associated 341 with this operation have expired, so that the requested operation 342 cannot be performed. 344 GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 345 performed on the credential structure referenced by 346 claimant_cred_handle failed, preventing further processing from 347 being performed using that credential structure. 349 GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 350 on the received P-IDU failed, preventing further processing 351 from being performed. 353 GSS_S_DEFECTIVE_VERIF indicates that consistency checks performed 354 on Service_Verification_Info failed, preventing further processing 355 from being performed with that parameter. 357 GSS_S_FAILURE indicates that environment setup could not be 358 accomplished for reasons unspecified at the IDUP-GSS-API level, 359 and that no interface-defined recovery action is available. 361 GSS_S_NO_CRED indicates that no environment was established, 362 either because the input cred_handle was invalid or because the 363 caller lacks authorization to access the referenced credentials. 365 Adams Document Expiration: 25 Sept. 1997 6 367 IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU 368 data origin auth. / integ. has either expired or been revoked. 370 IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU 371 cannot be completed because the encrypted IDU was invalid/defec- 372 tive (e.g., the final block was short or had incorrect padding). 374 IDUP_S_BAD_KE_KEY indicates that the key used to establish a key 375 for confidentiality purposes between originator and target has 376 either expired or been revoked. 378 IDUP_S_BAD_TARG_INFO indicates that all the information regarding 379 the target(s) is invalid or is insufficient for the protection of 380 an IDU, so P-IDU cannot be created. 382 IDUP_S_ENCAPSULATION_UNAVAIL (I) indicates that the underlying 383 mechanism does not support encapsulation of the M-IDU into the 384 token. 386 IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied 387 do not contain the information necessary for P-IDU unprotection. 389 IDUP_S_INCOMPLETE (I) indicates that the unprotection of the P-IDU 390 is not yet complete (i.e., a determination cannot yet be made on 391 the validity of the P-IDU). The application should call 392 IDUP_Form_Complete_PIDU and then should call this function again 393 with the complete P-IDU. 395 IDUP_S_MORE_DATA_NEEDED (I) indicates that more input data is 396 needed for the requested operation (e.g., so that appropriate data 397 may be generated and returned). 399 IDUP_S_MORE_PIDU_NEEDED (I) indicates that not enough of the P-IDU 400 has been input yet for the completion of Start_Protect. The 401 application should call this routine again with another buffer 402 of P-IDU in partial_pidu_buffer. 404 IDUP_S_NO_ENV indicates that no valid environment was recognized 405 for the env_handle provided. 407 IDUP_S_NO_MATCH indicates that Service_Verification_Info and 408 the P-IDU to be verified do not match. 410 IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 411 requested (TTIME or UTIME) is not available in the environment. 413 IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 414 does not support the service requested. 416 IDUP_S_SERV_VERIF_INFO_NEEDED (I) indicates that the 417 Service_Verification_Info parameter bundle must be input in order 418 for service verification to proceed. The output parameter 419 service_verification_info_id contains an identifier which may be 420 used by the calling application to locate the necessary 421 information. 423 IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 424 is not recognized or supported in the underlying mechanism. 426 Adams Document Expiration: 25 Sept. 1997 7 428 1.2.2. Per-IDU Security Service Availability 430 Per-IDU security service availability in IDUP-GSS-API is to be 431 understood and used as described in GSS-API [RFC-2078], with the 432 exception that any combination of services requested by the calling 433 application and supported by the underlying mechanism can be applied 434 simultaneously to any IDU. 436 GSS-API callers desiring per-message security services should check 437 the relevant service OBJECT IDs at environment establishment time to 438 ensure that what is available in the established environment is 439 suitable for their security needs. 441 1.2.3. Per-IDU Replay Detection and Sequencing 443 The concept of per-IDU replay detection and sequencing discussed 444 in GSS-API [RFC-2078] is not relevant to the IDUP-GSS-API. 446 1.2.4. Quality of Protection 448 The concept of QOP control in IDUP-GSS-API is to be understood 449 essentially as described in GSS-API [RFC-2078]. However, the actual 450 description and use of the QOP parameter is given as follows. 452 The qop_algs parameter for IDUP is defined to be a 32-bit unsigned 453 integer with the following bit-field assignments: 455 31 (MSB) (LSB) 0 456 ---------------------------------------------- 457 | U(19) | TS(5) | IA(4) | MA(4) | 458 ---------------------------------------------- 460 where 462 U is a 19-bit Unspecified field (available for future 463 use/expansion) -- must be set to zero; 465 TS is a 5-bit Type Specifier (a semantic qualifier whose value 466 specifies the type of algorithm which may be used to protect the 467 corresponding IDU -- see below for details); 469 IA is a 4-bit field enumerating Implementation-specific 470 Algorithms; and 472 MA is a 4-bit field enumerating Mechanism-defined Algorithms. 474 The interpretation of the qop_algs parameter is as follows. The MA 475 field is examined first. If it is non-zero then the algorithm used 476 to protect the IDU is the mechanism-specified algorithm corresponding 477 to that integer value. 479 If MA is zero then IA is examined. If this field value is non-zero 480 then the algorithm used to protect the IDU is the implementation- 481 specified algorithm corresponding to that integer value. Note that 482 use of this field may hinder portability since a particular value may 483 specify one algorithm in one implementation of the mechanism and may 484 not be supported or may specify a completely different algorithm in 485 another implementation of the mechanism. 487 Adams Document Expiration: 25 Sept. 1997 8 489 Finally, if both MA and IA are zero then TS is examined. A value of 490 zero for TS specifies the default algorithm for the established 491 mechanism. A non-zero value for TS corresponds to a particular 492 algorithm qualifier and selects any algorithm from the mechanism 493 specification which satisfies that qualifier (which actual algorithm 494 is selected is an implementation choice; the calling application need 495 not be aware of the choice made). 497 The following TS values (i.e., algorithm qualifiers) are specified; 498 other values may be added in the future. 500 When qop_algs is used to select a confidentiality algorithm: 502 00000 (0) = default confidentiality algorithm 503 00001 (1) = IDUP_SYM_ALG_STRENGTH_STRONG 504 00010 (2) = IDUP_SYM_ALG_STRENGTH_MEDIUM 505 00011 (3) = IDUP_SYM_ALG_STRENGTH_WEAK 506 11111 (31) = IDUP_NO_CONFIDENTIALITY 508 When qop_algs is used to select a DOA/integrity algorithm: 510 00000 (0) = default integrity algorithm 511 00001 (1) = IDUP_INT_ALG_DIG_SIGNATURE 512 (integrity provided through a digital signature) 513 00010 (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE 514 (integrity without a dig. sig. (e.g., with a MAC)) 515 11111 (31) = IDUP_NO_INTEGRITY 517 Clearly, qualifiers such as strong, medium, and weak are debatable 518 and likely to change with time, but for the purposes of this version 519 of the specification we define these terms as follows. A confiden- 520 tiality algorithm is "weak" if the effective key length of the cipher 521 is 40 bits or less; it is "medium-strength" if the effective key 522 length is strictly between 40 and 80 bits; and it is "strong" if the 523 effective key length is 80 bits or greater. ("Effective key length" 524 describes the computational effort required to break a cipher using 525 the best-known cryptanalytic attack against that cipher.) 527 A five-bit TS field allows up to 30 qualifiers for each of confiden- 528 tiality and integrity (since "0" is reserved for "default" and "31" 529 is reserved for "none", as shown above). This document specifies 530 three for confidentiality and two for integrity, leaving a lot of 531 room for future specification. Suggestions of qualifiers such as 532 "fast", "medium-speed", and "slow" have been made, but such terms are 533 difficult to quantify (and in any case are platform- and processor- 534 dependent), and so have been left out of this initial specification. 535 The intention is that the TS terms be quantitative, environment- 536 independent qualifiers of algorithms, as much as this is possible. 538 Use of the qop_algs parameter as defined above is ultimately meant to 539 be as follows. 541 - TS values are specified at the IDUP-GSS-API level and are 542 therefore portable across mechanisms. Applications which know 543 nothing about algorithms are still able to choose "quality" of 544 protection for their message tokens. 546 - MA values are specified at the mechanism level and are therefore 547 portable across implementations of a mechanism. 549 Adams Document Expiration: 25 Sept. 1997 9 551 - IA values are specified at the implementation level (in user 552 documentation, for example) and are therefore typically non- 553 portable. An application which is aware of its own mechanism 554 implementation and the mechanism implementation of its intended 555 P-IDU recipient, however, is free to use these values since they 556 will be perfectly valid and meaningful for protecting IDUs 557 between those entities. 559 The receiver of a P-IDU must pass back to its calling application 560 (in IDUP_Start_Unprotect()) a qop_algs parameter with all relevant 561 fields set. For example, if triple-DES has been specified by a 562 mechanism as algorithm 8, then a receiver of a triple-DES-protected 563 P-IDU must pass to its application (TS=1, IA=0, MA=8). In this way, 564 the application is free to read whatever part of the qop_algs 565 parameter it understands (TS or IA/MA). 567 1.2.5. The Provision of Time 569 IDUP mechanisms should make provision in their protocols for the 570 carrying of time information from originator to target(s). That is, 571 a target (a legitimate recipient) should get some indication during 572 unprotection regarding the time at which the protection operation 573 took place. This is particularly important if the mechanism offers 574 non-repudiation services because in some cases evidence verification 575 may only be achievable if the time at which the evidence was 576 generated is known. 578 Depending upon the platform and resources available to the 579 implementation, an IDUP environment may have access to a source of 580 trusted (secure) time, untrusted (local) time, both kinds of time, or 581 no time. OBJECT IDs indicating such availability are returned by the 582 IDUP_Establish_Env() call. When starting a protection operation, an 583 application may specify which time services it wishes to have applied 584 to the IDU. Similarly, for unprotection, an application may specify 585 which kind of time (if any) to consult when the validity of the P-IDU 586 is to be established. Specifying both kinds of time is interpreted 587 to mean that the calling application does not care which kind of time 588 is used. 590 The IDUP calls which use a time parameter specify the type of that 591 parameter to be INTEGER. This INTEGER is defined in all cases to be 592 the number of seconds which have elapsed since midnight, January 1, 593 1970, coordinated universal time. 595 2. Interface Descriptions 597 This section describes the IDUP-GSS-API's operational interface, 598 dividing the set of calls offered into five groups. Credential 599 management calls are related to the acquisition and release of 600 credentials by API callers. Environment-level calls are related to 601 the management of the security environment by an API caller. Per-IDU 602 calls are related to the protection or unprotection of individual 603 IDUs in established security environments. Special-purpose calls 604 deal with unusual or auxiliary evidence generation/verification 605 requirements. Support calls provide extra functions useful to 606 IDUP-GSS-API callers. Table 2 groups and summarizes the calls in 607 tabular fashion. 609 Adams Document Expiration: 25 Sept. 1997 10 611 Table 2: IDUP-GSS-API Calls 613 CREDENTIAL MANAGEMENT 614 (see the calls given in Section 2.1 of GSS-API [RFC-2078]) 616 ENVIRONMENT-LEVEL CALLS 617 IDUP_Establish_Env 618 establish IDUP environment (to protect and unprotect IDUs) 619 IDUP_Abolish_Env 620 abolish env. when no longer needed 621 IDUP_Inquire_Env 622 indicate characteristics of env. 624 PER-IDU CALLS 625 IDUP_SE_SingleBuffer_Protect 626 protect a single buffer (signing and/or encryption only) 627 IDUP_SE_SingleBuffer_Unprotect 628 unprotect a single buffer (verifying and/or decryption only) 629 IDUP_SE_MultiBuffer_StartProtect 630 begin the protection process (sign. and/or enc. only) 631 IDUP_SE_MultiBuffer_EndProtect 632 complete the protection process (sign. and/or enc. only) 633 IDUP_SE_MultiBuffer_StartUnprotect 634 begin the unprotection process (verif. and/or dec. only) 635 IDUP_SE_MultiBuffer_EndUnprotect 636 complete the unprotection process (verif. and/or dec. only) 637 IDUP_SE_Process_Buffer 638 protect or unprotect one buffer (SE or VD only) 639 IDUP_Start_Protect 640 begin the protection process 641 IDUP_Protect 642 protect the IDU (perhaps 1 buffer at a time) 643 IDUP_End_Protect 644 end the protection process; create a token which contains 645 info. necessary for the legitimate receiver(s) of the P-IDU 646 to unprotect it 647 IDUP_Start_Unprotect 648 begin the unprotect process 649 IDUP_Unprotect 650 use the token to unprotect the P-IDU 651 (possibly one buffer at a time) 652 IDUP_End_Unprotect 653 end the unprotect process 655 SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms) 656 IDUP_Form_Complete_PIDU 657 insert in P-IDU any data not provided by the protection call(s) 659 SUPPORT CALLS 660 IDUP_Acquire_cred_with_auth 661 acquire cred. using an authenticator 662 IDUP_Parse_Token 663 examine an input token to determine mech_type 664 IDUP_Get_Policy_Info 665 return policy info. for a given policy_id 666 (see also the calls given in Section 2.4 of GSS-API [RFC-2078]) 668 Adams Document Expiration: 25 Sept. 1997 11 670 2.1. Credential management calls 672 2.1.1. Relationship to GSS-API 674 Credential management in IDUP-GSS-API is to be understood and used as 675 described in GSS-API [RFC-2078]. The calls given in Section 2.1 of 676 GSS-API (including all associated parameters) are unchanged, although 677 the interpretation of the cred_usage parameter in the GSS-API calls 678 for IDUP purposes is as follows. 680 NO_RESTRICTION 0 681 ENCRYPT_ONLY 1 682 DECRYPT_ONLY 2 683 SIGN_ONLY 4 684 VERIFY_ONLY 8 686 The non-zero values above may be logically OR'ed together in any 687 desired combination to restrict credential usage. Future possible 688 values for this parameter are for further study. 690 The call IDUP_Acquire_cred_with_auth has been added as a support call 691 in this specification to permit authenticated credential acquirement; 692 see Section 2.5.2 for details. 694 2.2. Environment-level calls 696 This group of calls is devoted to the establishment and management of 697 an environment for the purpose of IDU protection and unprotection. 698 Before protecting or unprotecting any IDU, an application must call 699 IDUP_Establish_Env() to initialize environment information and select 700 the underlying IDUP-GSS mechanism to be used. A series of protection 701 or unprotection calls is made to process each IDU, the protection 702 calls resulting in a P-IDU for each. Finally, IDUP_Abolish_Env() 703 is called to flush all environment information. 705 Semantically, acquiring credentials and establishing an environment 706 is (in many cases) analogous to logging in to a system -- it 707 authenticates a local user to the system and gives that user access 708 to a set of operations which can be performed. 710 2.2.1. Relationship to GSS-API 712 The set of calls described in this section is used in place of the 713 calls described in Section 2.2 of GSS-API [RFC-2078], since those 714 calls are specific to a session-oriented environment. 716 2.2.2. IDUP_Establish_Env call 718 Inputs: 720 o claimant_cred_handle CREDENTIAL HANDLE, 721 -- NULL parameter specifies "use default" 722 o req_mech_type OBJECT IDENTIFIER, 723 -- NULL parameter specifies "use default" 724 o req_environmentPolicies EnvironmentPolicies, 725 -- NULL parameter specifies "use default" 726 o req_services SET OF OBJECT IDENTIFIER, 728 Adams Document Expiration: 25 Sept. 1997 12 730 Outputs: 732 o major_status INTEGER, 733 o minor_status INTEGER, 734 o env_handle ENVIRONMENT HANDLE, 735 o actual_mech_type OBJECT IDENTIFIER, 736 -- actual mechanism always indicated, never NULL 737 o actual_environmentPolicies EnvironmentPolicies, 738 -- actual values always indicated, never NULL 739 o ret_services SET OF OBJECT IDENTIFIER, 741 Return major_status codes: 743 o GSS_S_COMPLETE 744 -- environment-level information was successfully initialized, 745 -- and IDU / P-IDU processing can begin. 746 o GSS_S_DEFECTIVE_CREDENTIAL 747 o GSS_S_NO_CRED 748 o GSS_S_CREDENTIALS_EXPIRED 749 -- the credentials provided through claimant_cred_handle are 750 -- no longer valid, so environment cannot be established. 751 o GSS_S_BAD_MECH 752 o GSS_S_FAILURE 754 The following structures are defined to facilitate environment policy 755 input and output: 757 EnvironmentPolicies ::= SEQUENCE { 758 confPolicy [0] PolicyAndTime OPTIONAL, 759 -- NULL parameter (on input) specifies "use default" 760 integPolicy [1] PolicyAndTime OPTIONAL, 761 -- NULL parameter (on input) specifies "use default" 762 evidencePolicy [2] PolicyAndTime OPTIONAL 763 -- NULL parameter (on input) specifies "use default" 764 } 766 PolicyAndTime ::= SEQUENCE { 767 policy OBJECT IDENTIFIER, 768 -- this environment-level policy identifier is separate from 769 -- the policy provisions connected with credentials, if they exist 770 time INTEGER 771 -- on input: the policy rules available at the specified time 772 -- on output: the time at which the policy rules came into effect 773 -- (defined to be the number of seconds elapsed since midnight, 774 -- January 1, 1970, coordinated universal time); 775 } 777 This routine is used by an application which protects or unprotects 778 IDUs. Using information in the credentials structure referenced by 779 claimant_cred_handle, IDUP_Establish_Env() initializes the data 780 structures required to protect or unprotect IDUs. The 781 claimant_cred_handle, if non-NULL, must correspond to a valid 782 credentials structure. 784 This routine returns an env_handle for all future references to 785 this environment; when protection, unprotection, or 786 IDUP_Abolish_Env() calls are made, this handle value will be used 787 as the input env_handle argument. 789 Adams Document Expiration: 25 Sept. 1997 13 791 It is the caller's responsibility to establish a communications path 792 to the intended recipients of the P-IDU, and to transmit the P-IDU to 793 those recipients over that path. This may occur subsequent to the 794 IDUP_Abolish_Env() call. 796 The req_services parameter may be used by the calling application to 797 request that data origin authentication with integrity, 798 confidentiality with integrity, evidence generation, and/or evidence 799 verification services be available in the established environment. 800 Requests can also be made for "trusted" or "untrusted" time services. 801 Requesting evidence generation or verification indicates that the 802 calling application may wish to generate or verify evidence 803 information for non-repudiation purposes (note: an IDU protector may 804 request that a flag be inserted into a P-IDU asking a recipient to 805 provide an evidence of the type "non-repudiation of delivery"; 806 however, the IDUP-GSS-API cannot by itself guarantee that the 807 evidence will be sent because there is no way to force a target to 808 send an evidence_token back to the IDU protector). 810 Not all features will be available in all underlying mech_types; the 811 returned value of ret_services indicates, as a function 812 of mech_type processing capabilities and the initiator-provided input 813 OBJECT IDs, the set of features which will be available in the 814 environment. The value of this parameter is undefined unless the 815 routine's major_status indicates COMPLETE. Failure to provide the 816 precise set of services desired by the caller does not cause 817 environment establishment to fail; it is the caller's choice to 818 abolish the environment if the service set provided is unsuitable for 819 the caller's use. The returned mech_type value indicates the 820 specific mechanism employed in the environment, and will never 821 indicate the value for "default". 823 The following OBJECT IDs are defined for protection and unprotection 824 services (the OBJECT ID iso.org.dod.internet.security.services, 825 1.3.6.1.5.7, has been assigned by IANA, and some of the security 826 services under that node are assigned as shown below). It is 827 recognized that this list may grow over time; for example, if a 828 particular order of services is required (such as sign-data-then- 829 encrypt-everything-including-the-signature), then an OID can be 830 assigned (e.g., PER_DOA_THEN_FULL_CONF) which registers this 831 new service. 833 PER_CONF = { 1.3.6.1.5.7.1.1 } 834 -- perform data confidentiality (i.e., encrypt data) 835 PER_DOA = { 1.3.6.1.5.7.3.1 } 836 -- perform data origin authentication with data integrity 837 PER_POO = { 1.3.6.1.5.7.4.1 } 838 -- perform (i.e., create) non-repudiable "proof of origin" 839 PER_POD = { 1.3.6.1.5.7.4.3 } 840 -- perform (i.e., create) non-repudiable "proof of delivery" 841 REC_CONF = { 1.3.6.1.5.7.1.2 } 842 -- receive data confidentiality (i.e., decrypt data) 843 REC_DOA = { 1.3.6.1.5.7.3.2 } 844 -- receive / verify DOA with data integrity 845 REC_POO = { 1.3.6.1.5.7.4.2 } 846 -- receive / verify "proof of origin" 847 REC_POD = { 1.3.6.1.5.7.4.4 } 848 -- receive / verify "proof of delivery" 849 TTIME = { 1.3.6.1.5.7.7.1 } 850 -- trusted time availability 851 UTIME = { 1.3.6.1.5.7.7.2 } 852 -- untrusted time availability 854 Adams Document Expiration: 25 Sept. 1997 14 856 The PER_CONF return value (in the ret_services paramater) indicates 857 whether the environment supports confidentiality services, and so 858 informs the caller whether or not a request for encryption through 859 a confidentiality service input to IDUP_Start_Protect() can be 860 honored. In similar fashion, the PER_DOA return value indicates 861 whether DOA services are available in the established environment, 862 and the PER_POO and PER_POD return values indicate whether evidence 863 generation services are available. The TTIME and UTIME values 864 indicate whether trusted time and untrusted time are available for 865 protection / unprotection services. 867 Note that, unlike a GSS "context", an IDUP environment does not have 868 an explicit lifetime associated with it. Instead, it relies on the 869 lifetime of the calling entity's credential (set by the caller in the 870 GSS_Acquire_cred() call). When the credential expires (or is 871 explicitly deleted using the gss_release_cred() call), no new 872 operations are allowed in the IDUP environment (although operations 873 which have begun, such as the Protection set of calls, can be taken 874 to completion). 876 2.2.3. IDUP_Abolish_Env call 878 Input: 880 o env_handle ENVIRONMENT HANDLE 882 Outputs: 884 o major_status INTEGER, 885 o minor_status INTEGER, 887 Return major_status codes: 889 o GSS_S_COMPLETE 890 -- the relevant environment-specific information was flushed. 891 o IDUP_S_NO_ENV 892 o GSS_S_FAILURE 894 This call is made to flush environment-specific information. (Once an 895 environment is established, cached credential and environment-related 896 info. is expected to be retained until an IDUP_Abolish_Env() call is 897 made or until the cred. lifetime expires.) Attempts to perform IDU 898 processing on a deleted environment will result in error returns. 900 2.2.4. IDUP_Inquire_Env call 902 Input: 904 o env_handle ENVIRONMENT HANDLE, 906 Outputs: 908 o major_status INTEGER, 909 o minor_status INTEGER, 910 o mech_type OBJECT IDENTIFIER, 911 -- the mechanism supporting this env. 912 o policy OBJECT IDENTIFIER, 913 -- the policy used in this env. 914 o policy_time INTEGER, 915 -- time at which the policy rules came into effect 916 o ret_services SET OF OBJECT IDENTIFIER, 918 Adams Document Expiration: 25 Sept. 1997 15 920 Return major_status codes: 922 o GSS_S_COMPLETE 923 -- referenced environment is valid and mech_type and other return 924 -- values describe the characteristics of the environment. 925 o GSS_S_CREDENTIALS_EXPIRED 926 o IDUP_S_NO_ENV 927 o GSS_S_FAILURE 929 This routine provides environment-related information to the caller. 931 2.3. Per-IDU calls 933 This group of calls is used to perform IDU protection and 934 unprotection processing on an established IDUP environment. Some of 935 these calls may block pending network interactions (depending on the 936 underlying mechanism in use). These calls may be invoked by an IDU's 937 protector or by the P-IDU's recipient. The two sets of members of 938 this group form a pair; the output from the protection set is 939 typically meant to be input to the unprotection set. 941 The per-IDU calls can support caller-requested data origin 942 authentication with data integrity, confidentiality with data 943 integrity, evidence, and evidence-requested-from-target services. 944 The protection operations output a token which encapsulates all the 945 information required to unprotect the IDU. The token is passed to 946 the target (possibly separate from the M-IDU) and is processed by the 947 unprotection calls at that system. Unprotection performs 948 decipherment, DOA verification, evidence verification, or 949 notification of evidence requested, as required. 951 Each of the two main operations (protection and unprotection) may be 952 separated into three parts: "Start_Operation"; "Operation" (which 953 may be called once for each buffer of input data); and 954 "End_Operation". This separation is available for the case where the 955 IDU or P-IDU is to be processed one buffer at a time. 956 "Start_Operation" allows the caller to specify or retrieve the 957 appropriate "Quality" used during the processing. "Operation" is 958 concerned with the processing itself, receiving a buffer of input 959 data and potentially returning a buffer of output data. 960 "End_Operation" performs any required clean-up and creates the 961 appropriate token or states whether the input token was verified. 963 If the IDU or P-IDU is wholly contained in a single buffer, the 964 three-part protection/unprotection processing need not be done. 965 Instead, protection and unprotection can be accomplished using only 966 the "Start_Operation" call, simplifying application code. 968 2.3.1. Relationship to GSS-API 970 The set of calls described in this section is used in place of the 971 calls GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() 972 which are specified in [RFC-2078], since those calls are specific to 973 a session-oriented environment. 975 Adams Document Expiration: 25 Sept. 1997 16 977 2.3.2. The "SE" Calls 979 2.3.2.1. IDUP_SE Purpose 981 The "SE" group of calls provides a very simple, high-level 982 interface to underlying IDUP mechanisms when application developers 983 need access only to signature and encryption protection/unprotection 984 services. It includes both the single-buffer and multiple-buffer IDU 985 cases and can be used for signing only, encrypting only, signing and 986 encrypting (in either order, and with or without visibility of the 987 resulting signature), and "clear signing" (where the data is not 988 modified in any way and the signature itself is returned 989 (unencapsulated) as a separate item). 991 Note that the term "signing" is used in its most generic sense, not 992 necessarily implying the use of public-key techniques. This concept 993 has also been called "sealing" in other contexts (e.g., in other 994 standardization efforts). 996 The SE calls may be viewed by mechanism implementors as an "API" to 997 the more powerful Protection and Unprotection sets of calls defined 998 later and so may be implemented as simple mapping functions to those 999 calls. Application callers, on the other hand, may find that the SE 1000 calls are all they currently need for many environments and may 1001 migrate to the more general calls only at some time in the future 1002 when they have need of data labeling, non-repudiation, or "directed 1003 receipts" types of services. To assist in this migration path, it 1004 is recommended that mechanism implementors support the full set of 1005 IDUP calls (i.e., both the SE calls and the more powerful calls) even 1006 though some calling applications will only use the SE calls in the 1007 short term. 1009 2.3.2.2. IDUP_SE Parameter Bundles 1011 The concept of "parameter bundles" is used in the calls presented in 1012 the following subsections in order to simplify their presentation and 1013 clarify their intended purpose and use. See Section 2.3.3 for a more 1014 complete description of parameter bundles. 1016 The following parameter bundles are used in the "SE" protection and 1017 unprotection sets of calls. 1019 o Protect_Options PARAMETER BUNDLE 1020 o protect_operation INTEGER { 1021 sign_only (0), 1022 encrypt_only (1), 1023 sign_and_encrypt (2), 1024 -- let mechanism choose order (and readability of signature) 1025 sign_then_encrypt_data (3), 1026 -- sign, then encrypt plaintext (leaving signature in clear) 1027 sign_then_encrypt_full (4), 1028 -- sign, then encrypt everything (including signature) 1029 encrypt_then_sign (5), 1030 -- encrypt, then sign the ciphertext 1031 clear_sign_only (6) 1032 } 1033 o sign_qop_alg UNSIGNED INTEGER, 1034 o enc_qop_alg UNSIGNED INTEGER, 1035 o idu_type_string OCTET STRING, 1036 -- type of the IDU ("data", "e-mail doc", MIME type, etc.) 1038 Adams Document Expiration: 25 Sept. 1997 17 1040 o PIDU_Information PARAMETER BUNDLE 1041 o protect_options Protect_Options, 1042 o originator_name INTERNAL NAME, 1043 o protection_time INTEGER, 1045 o Bad_Target_Name PARAMETER BUNDLE, -- same as in Section 2.3.3 1046 o bad_targ_name INTERNAL NAME, 1047 o bad_targ_status INTEGER, 1048 -- a (mechanism-defined) status flag giving the reason 1049 -- for rejection of the name in bad_targ_name. 1050 -- Example reasons may include: 1051 -- SYNTAX_INVALID the syntax of the name is invalid; 1052 -- NAME_UNRECOGNIZED the name is not recognized; 1053 -- NAME_AMBIGUOUS the name cannot be resolved; 1054 -- ACCESS_DENIED access to this target is denied; 1055 -- CERTIFICATE_NOT_FOUND the encryption certificate of the 1056 target could not be found. 1058 o Target_Info PARAMETER BUNDLE, -- same as in Section 2.3.3 1059 o targ_names SET OF INTERNAL NAME, 1060 o bad_targ_count INTEGER, 1061 o bad_target_name Bad_Target_Name, 1063 2.3.2.3. IDUP_SE major_status codes 1065 The following major_status return codes are defined for the "SE" 1066 calls in this section: 1068 o GSS_S_COMPLETE 1069 o GSS_S_CONTINUE_NEEDED 1070 o IDUP_S_MORE_DATA_NEEDED 1071 -- indicates that more input data is needed for the StartUnprotect 1072 -- operation (e.g., so that PIDU_Information or initial_idu_buffer 1073 -- may be returned). 1074 o GSS_S_CREDENTIALS_EXPIRED 1075 o IDUP_S_NO_ENV 1076 o GSS_S_BAD_QOP 1077 o GSS_S_FAILURE 1079 If Target_Info is used as an input parameter (i.e., if an encryption 1080 operation is being performed), the following major_status return code 1081 is also defined: 1083 o IDUP_S_BAD_TARG_INFO 1085 Note for this return code that if one or more of the targets in 1086 targ_names cannot be used as a valid recipient of the P-IDU, these 1087 names will be returned in bad_targ_names (with associated status 1088 codes in bad_targ_status). As long as at least one of the targets 1089 can be used, however, this does not cause this call to fail (i.e., 1090 the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the 1091 caller's choice to discontinue IDU protection if the target set 1092 which can be used is unsuitable for the caller's purposes. 1094 Adams Document Expiration: 25 Sept. 1997 18 1096 2.3.2.4. IDUP_SE_SingleBuffer_Protect call 1098 Inputs: 1099 o env_handle ENVIRONMENT HANDLE, 1100 o Protect_Options PARAMETER BUNDLE, 1101 o Target_Info_E PARAMETER BUNDLE, 1102 -- used if Protect_Options is encrypt_only or sign_and_encrypt 1103 o Target_Info_S PARAMETER BUNDLE OPTIONAL, 1104 -- used only if a separate recipient list is needed for signing 1105 o idu_buffer OCTET STRING 1107 Outputs: 1108 o major_status INTEGER, 1109 o minor_status INTEGER, 1110 o pidu_buffer OCTET STRING, 1111 o sig_token OCTET STRING 1112 -- used if Protect_Options is clear_sign_only 1114 Using the security environment referenced by env_handle, encrypt 1115 and/or sign the supplied IDU. If "clear signing" is performed, the 1116 signature will be returned in sig_token and pidu_buffer may be empty 1117 (depends on underlying mechanism). 1119 2.3.2.5. IDUP_SE_SingleBuffer_Unprotect call 1121 Inputs: 1122 o env_handle ENVIRONMENT HANDLE, 1123 o pidu_buffer OCTET STRING, 1124 -- may contain an IDU if sig_token is non-NULL (i.e., if 1125 -- clear_sign_only protection was applied) 1126 o sig_token OCTET STRING 1128 Outputs: 1129 o major_status INTEGER, 1130 o minor_status INTEGER, 1131 o idu_buffer OCTET STRING, 1132 -- may be empty if clear_sign_only protection was applied (depends 1133 -- on underlying mechanism) 1134 o PIDU_Information PARAMETER BUNDLE 1136 Using the security environment referenced by env_handle, decrypt 1137 and/or verify the supplied PIDU and return the contained IDU along 1138 with all available PIDU_Information. 1140 2.3.2.6. IDUP_SE_MultiBuffer_StartProtect call 1142 Inputs: 1143 o env_handle ENVIRONMENT HANDLE, 1144 o Protect_Options PARAMETER BUNDLE, 1145 o Target_Info_E PARAMETER BUNDLE, 1146 -- used if Protect_Options is encrypt_only or sign_and_encrypt 1147 o Target_Info_S PARAMETER BUNDLE OPTIONAL, 1148 -- used only if a separate recipient list is needed for signing 1150 Outputs: 1151 o major_status INTEGER, 1152 o minor_status INTEGER, 1153 o initial_pidu_buffer OCTET STRING 1154 -- may be empty (depends on underlying mechanism) 1155 Adams Document Expiration: 25 Sept. 1997 19 1157 Using the security environment referenced by env_handle, initialize 1158 the data structures required to begin the process of signing 1159 and/or encrypting the IDU (which will be supplied in multiple buffers 1160 to the Process_Buffer call). 1162 2.3.2.7. IDUP_SE_MultiBuffer_EndProtect call 1164 Inputs: 1165 o env_handle ENVIRONMENT HANDLE 1167 Outputs: 1168 o major_status INTEGER, 1169 o minor_status INTEGER, 1170 o final_pidu_buffer OCTET STRING, 1171 o sig_token OCTET STRING 1172 -- used if Protect_Options was clear_sign_only 1174 Using the security environment referenced by env_handle, complete the 1175 protection processing on the data and place the computed output in 1176 final_pidu_buffer and/or sig_token. Successful application of 1177 IDUP_SE_MultiBuffer_EndProtect() does not guarantee that unprotection 1178 can necessarily be performed successfully when the P-IDU arrives at 1179 the target (for example, it may be damaged in transit). 1181 2.3.2.8. IDUP_SE_MultiBuffer_StartUnprotect call 1183 Inputs: 1184 o env_handle ENVIRONMENT HANDLE, 1185 o initial_pidu_buffer OCTET STRING, 1186 o sign_qop_alg_in UNSIGNED INTEGER, 1187 -- used if Protect_Options was clear_sign_only (and calling 1188 -- application has prior knowledge of signing alg. applied); 1189 -- if NULL, then sig_token must be supplied 1190 o sig_token OCTET STRING 1191 -- used if Protect_Options was clear_sign_only; 1192 -- if NULL, then sign_qop_alg_in must be supplied 1194 Outputs: 1195 o major_status INTEGER, 1196 o minor_status INTEGER, 1197 o PIDU_Information PARAMETER BUNDLE, 1198 -- returns all available information 1199 o initial_idu_buffer OCTET STRING 1200 -- may be empty 1202 Using the security environment referenced by env_handle, initialize 1203 the data structures required to begin the process of decrypting 1204 and/or verifying the PIDU (which will be supplied in multiple buffers 1205 to the Process_Buffer call). 1207 2.3.2.9. IDUP_SE_MultiBuffer_EndUnprotect call 1209 Inputs: 1210 o env_handle ENVIRONMENT HANDLE, 1211 o sig_token OCTET STRING OPTIONAL 1212 -- used if Protect_Options was clear_sign_only and sig_token was 1213 -- not available when StartUnprotect was called 1215 Adams Document Expiration: 25 Sept. 1997 20 1217 Outputs: 1218 o major_status INTEGER, 1219 o minor_status INTEGER, 1220 o PIDU_Information PARAMETER BUNDLE, 1221 -- returns all available information 1222 o final_idu_buffer OCTET STRING 1223 -- may be empty 1225 Using the security environment referenced by env_handle, complete the 1226 decryption and/or verification processing on the data and place any 1227 residual output in final_idu_buffer. 1229 2.3.2.10. IDUP_SE_Process_Buffer call 1231 Inputs: 1232 o env_handle ENVIRONMENT HANDLE, 1233 o input_buffer OCTET STRING, 1235 Outputs: 1236 o major_status INTEGER, 1237 o minor_status INTEGER, 1238 o output_buffer OCTET STRING 1239 -- may be zero length (depends on underlying mechanism and 1240 -- corresponding Start() call and Protect_Options value) 1242 Using the security environment referenced by env_handle, continue the 1243 processing on the data in input_buffer and, if it is available, put 1244 any resulting output data in output_buffer. The application calls 1245 this routine over and over again with new buffers of data until it 1246 has processed all the data buffers of the IDU/PIDU. It then calls 1247 the appropriate End() call to complete the processing. 1249 2.3.3. The "EV" Calls 1251 2.3.3.1. IDUP_EV Purpose 1253 The "EV" group of calls provides a simple, high-level interface 1254 to underlying IDUP mechanisms when application developers 1255 need to deal only with evidence but not with encryption or integrity 1256 services. It includes both the single-buffer and multiple-buffer 1257 IDU cases and can be used for the generation and verification of 1258 evidence tokens embodying several different types of evidences. 1260 The following list of evidence's types are supported. This list 1261 is by no means exhaustive and it is anticipated that it will be 1262 extended. 1264 Non-repudiation of Origin prevents a message creator's false 1265 denial of creating and sending a message. 1267 Non-repudiation of Creation prevents a message creator's false 1268 denial of creating a message. 1270 Non-repudiation of Sender prevents a message creator's false 1271 denial of sending a message (that was not necessarily created 1272 by the sender). 1274 Non-repudiation of Delivery prevents a message recipient's 1275 false denial of having received and looked at the content of a 1276 message. 1278 Adams Document Expiration: 25 Sept. 1997 21 1280 Non-repudiation of Receipt prevents a message recipient's 1281 false denial of having received a message (whose content was 1282 not necessarily looked at by the recipient). 1284 Non-repudiation of Retrieval prevents a message recipient's 1285 false denial of having retrieved a message a message from a 1286 message store (whose content was not necessarilly looked at by 1287 the recipient). 1289 Non-repudiation of Approval prevents a message recipient's 1290 false denial of having approved the content of a received 1291 message. 1293 An evidence is provided in the form of a evidence token. Two forms 1294 of evidence tokens are supported: 1296 o Tokens including the associated data, 1298 o Tokens without included data (but with a unique reference to 1299 the associated data). 1301 Evidence tokens may be freely distributed. Any possessor of an 1302 evidence token (and of the associated data, if not included in the 1303 token) can verify the evidence if it has the appropriate 1304 credentials which include the definition of security policies (i.e., 1305 keys alone do not permit the verification of evidence tokens). Any 1306 holder of an evidence token may store it (along with the associated 1307 data, if not included in the token) for later verification. 1309 Calls that are specific to the support of evidence include: 1311 * Generate_token generates a non-repudiation token using the current 1312 environment. The generated token may consist of: 1314 1 - an evidence token 1316 2 - a token containing a request for an evidence, which carries 1317 information describing which evidence type should be generated 1318 by the recipient(s) and sent back to some entities (that may or 1319 may not include the sender). 1321 3 - a token containing an evidence token which is an answer to 1322 an evidence that has been previously requested. 1324 4 - a token including both an evidence and a request for another 1325 evidence to be provided. 1327 * Verify_evidence verifies the evidence token using the current 1328 environment. The verify_evidence operation returns a major status 1329 code which can be used to determine whether the evidence 1330 contained in a token is complete (i.e., can be successfully 1331 verified (perhaps years) later). If a token's evidence is not 1332 complete, the token can be passed to form_complete_evidence to 1333 complete it. 1335 Additional useful calls for evidence services include: 1337 * IDUP_Get_token_details (see Section 2.5.4); 1338 * IDUP_Form_Complete_PIDU (see Section 2.4.2). 1340 Adams Document Expiration: 25 Sept. 1997 22 1342 2.3.3.2. IDUP_EV Parameters 1344 The following parameter bundles are used in the "EV" protection and 1345 unprotection sets of calls. 1347 o Nr_Options PARAMETER BUNDLE 1348 o evidence_type INTEGER { 1349 no_evidence (0) 1350 -- used when request-only token desired 1351 proof_of_receipt (1), 1352 proof_of_delivery (2), 1353 proof_of_approval (3), 1354 proof_of_retrieval (4), 1355 proof_of_creation (5), 1356 proof_of_sender (6), 1357 proof_of_origin (7) 1358 }, 1359 o evidence_validity_duration INTEGER, 1360 -- duration_in_minutes 1361 -- DURATION_HOUR = 60; 1362 -- DURATION_DAY = 1440; 1363 -- DURATION_WEEK = 10080; 1364 -- DURATION_MONTH = 43200;// 30 days 1365 -- DURATION_YEAR = 525600;//365 days 1367 o Originator_Information PARAMETER BUNDLE 1368 o token_generator_name INTERNAL NAME, 1369 -- obtained from the credentials of the originator 1370 -- (e.g. from its public key certificate) 1371 o protection_time UTCTime OPTIONAL. 1373 o Bad_Target_Name PARAMETER BUNDLE -- same as in Section 2.3.3 1374 o bad_targ_name INTERNAL NAME, 1375 o bad_targ_status INTEGER 1376 -- a (mechanism-defined) status flag giving the reason 1377 -- for rejection of the name in bad_targ_name 1379 o Target_Info PARAMETER BUNDLE -- same as in Section 2.3.3 1380 o targ_names SET OF INTERNAL NAME, 1381 o bad_targ_count INTEGER, 1382 o Bad_Target_Name PARAMETER BUNDLE 1384 o Request_Features PARAMETER BUNDLE 1385 o requested_evidence_type INTEGER { 1386 no_evidence (0), - used when no token desired 1387 proof_of_receipt (1), 1388 proof_of_delivery (2), 1389 proof_of_approval (3), 1390 proof_of_retrieval (4) 1391 }, 1392 o nr_req_policy OBJECT IDENTIFIER, 1393 o evidence_from Target_Info, 1394 o evidence_to Target_Info, 1395 o include_received_token_in evidence BOOLEAN 1397 The following data_type is used in the "EV" protection sets 1398 of calls. 1400 Adams Document Expiration: 25 Sept. 1997 23 1402 o Nr_Operation INTEGER { 1403 evidence_and_or_evidence_request (1), 1404 returned_evidence (2) 1405 } 1407 2.3.3.3. IDUP_EV major_status codes 1409 The following major_status return codes are defined for the "EV" 1410 calls in this section: 1412 o GSS_S_COMPLETE 1413 -- indicates that the evidence is complete 1414 o IDUP_S_INCOMPLETE 1415 o GSS_S_CONTINUE_NEEDED 1416 o IDUP_S_MORE_DATA_NEEDED 1417 o GSS_S_CREDENTIALS_EXPIRED 1418 o IDUP_S_NO_ENV 1419 o GSS_S_FAILURE 1421 If Target_Info is used as an input parameter (i.e., if an 1422 evidence is being requested ), the following major_status return 1423 code is also defined: 1425 o IDUP_S_BAD_TARG_INFO 1427 Note for this return code that if one or more of the targets in 1428 targ_names cannot be used as a valid recipient of the P-IDU, these 1429 names will be returned in bad_targ_names (with associated status 1430 codes in bad_targ_status). As long as at least one of the targets 1431 can be used, however, this does not cause this call to fail (i.e., 1432 the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the 1433 caller's choice to discontinue IDU protection if the target set 1434 which can be used is unsuitable for the caller's purposes. 1436 2.3.3.4. IDUP_EV_SingleBuffer_Generate call 1438 Inputs: 1440 o env_handle ENVIRONMENT HANDLE, 1441 o nr_operation Nr_Operation, 1442 o Nr_Options PARAMETER BUNDLE, 1443 o idu_buffer OCTET STRING, 1444 o form_complete_evidence BOOLEAN, 1445 -- if TRUE the implementation will attempt to form a complete evi. 1446 o include_data_in_token BOOLEAN, 1447 -- if TRUE, data provided in idu_buffer will be included in the 1448 -- generated token; if FALSE, the data will not be included 1449 o Request_Features PARAMETER BUNDLE 1450 -- the type of the evidence that is requested. 1451 -- policy under which the returned evidence should be generated. 1452 -- the recipients that are supposed to send back an evidence. 1453 -- the recipients that should receive the requested evidence. 1454 -- an indicator include_received_token_in_evidence: 1455 -- if TRUE, the evidence token incorporating the request will be 1456 -- included in the data for which recipients will generate 1457 -- evidence; if FALSE, evidence will be generated using only 1458 -- the data (and not the token incorporating the request). 1460 Adams Document Expiration: 25 Sept. 1997 24 1462 Outputs: 1464 o major_status INTEGER, 1465 o minor_status INTEGER, 1466 o token OCTET STRING, 1467 o evidence_check OCTET STRING, 1468 -- present only if an evidence is requested. Consists of data to 1469 -- be used to verify the requested token(s) (if any) when they are 1470 -- received. 1472 Description: 1474 This operation generates a non-repudiation token associated with the 1475 data passed in an input buffer. Two kinds of operations can be 1476 performed (using the Nr_Operation parameter) : 1478 a) generating a token that includes either an evidence only, or 1479 an evidence request only, or both an evidence and an evidence 1480 request. 1482 b) generating a response token for some recipients that includes an 1483 evidence generated as a response to a request. In that case 1484 the idu_buffer is used to enter the request token that was 1485 received . 1487 It is possible to request the generation of complete evidence. This 1488 may succeed or fail; if it fails, a subsequent call to 1489 Form_Complete_Evidence can be made. 1491 2.3.3.5. IDUP_EV_SingleBuffer_Verify call 1493 Inputs: 1495 o env_handle ENVIRONMENT HANDLE, 1496 o token OCTET STRING, 1497 o idu_buffer OCTET STRING, 1498 -- if not present within the token 1499 o evidence_check OCTET STRING, 1500 -- present only if the input token is a response to a previous 1501 -- request for evidence (this parameter is used to validate that 1502 -- evidence). 1504 Outputs: 1506 o major_status INTEGER, 1507 o minor_status INTEGER, 1508 o Nr_Options PARAMETER BUNDLE, 1509 o Originator_Information PARAMETER BUNDLE, 1510 o Request_Features PARAMETER BUNDLE, 1511 o trusted_time_stamping_time INTEGER OPTIONAL, 1512 -- present for informational purposes only 1514 Adams Document Expiration: 25 Sept. 1997 25 1516 o complete_evidence_before INTEGER OPTIONAL, 1517 -- if the major status code that is returned is 1518 -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called 1519 -- with the same token before this time. 1520 -- This may be required, for example, in order to insure that 1521 -- the time skew between the evidence generation time and 1522 -- the trusted time service's countersignature on the evidence 1523 -- falls within the interval allowed by the current NR policy. 1524 o complete_evidence_after INTEGER OPTIONAL, 1525 -- if the major status code that is returned is 1526 -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called 1527 -- with the same token after this time. 1528 -- This may be required, for example, to insure that all 1529 -- authorities involved in generating the evidence have passed 1530 -- the last time at which the current NR policy allows them to 1531 -- repudiate their keys. 1532 o idu_buffer OCTET STRING 1533 -- if the IDU was present within the token 1535 Description: 1537 Verifies the validity and discloses the content of a nr_token. 1539 If the token containing the evidence to be verified was provided to 1540 the calling application by a partner responding to the calling 1541 application's request, then the calling application must pass the 1542 evidence check it received when it generated the request as a 1543 parameter along with the token it received from the partner. 1545 Output indicators are provided which give guidance about the time or 1546 times at which form_complete_evidence should be called; see the 1547 parameter descriptions for explanations of these indicators and their 1548 use. Note that the time specified by complete_evidence_before may be 1549 earlier than that specified by complete_evidence_after; in this case 1550 it will be necessary to call form_complete_evidence twice. 1552 Because keys can be revoked or declared compromised, the return from 1553 verify_evidence cannot in all cases be a definitive valid or invalid; 1554 sometimes conditionally valid may be returned, depending upon the 1555 policy in use. IDUP_S_INCOMPLETE will be returned if: 1557 - the interval during which the generator of the evidence may 1558 permissibly declare his key invalid has not yet expired (and 1559 therefore it is possible that the evidence may be declared 1560 invalid in the future), or 1562 - trusted time is required for verification, and the time obtained 1563 from the token is not trusted. 1565 Adams Document Expiration: 25 Sept. 1997 26 1567 2.3.3.6. IDUP_EV_MultiBuffer_StartGenerate call 1569 Inputs: 1571 o env_handle ENVIRONMENT HANDLE, 1572 o nr_operation Nr_Operation, 1573 o Nr_Options PARAMETER BUNDLE, 1574 o form_complete_evidence BOOLEAN, 1575 o include_data_in_token BOOLEAN, 1576 o Request_Features PARAMETER BUNDLE 1578 Outputs: 1580 o major_status INTEGER, 1581 o minor_status INTEGER, 1582 o initial_pidu_buffer OCTET STRING 1583 -- may be empty (depends on underlying mechanism) 1585 Description: 1587 Using the security environment referenced by env_handle, initialize 1588 the data structures required to begin the generation of a token. 1589 The IDU will be supplied in multiple buffers to the 1590 IDUP_EV_Process_Buffer call). Two kinds of operations can be 1591 performed (using the Nr_Operation parameter) : 1593 a) generating a token that includes either an evidence only, or 1594 an evidence request only, or both an evidence and an evidence 1595 request. 1597 b) generating a token back for some recipients that includes an 1598 evidence generated as a response to a request. In that case 1599 the idu_buffer is used to enter the received token. The 1600 boolean include_data_in_token is ignored as the output will 1601 always be contained in a single token. The Request_Features 1602 are ignored in that case at this time in order to keep things 1603 simple and avoid piggy-backing (that is possible in theory). 1605 It is possible to request the generation of complete evidence. This 1606 may succeed or fail; if it fails, a subsequent call to 1607 Form_Complete_Evidence can be made. 1609 2.3.3.7. IDUP_EV_MultiBuffer_EndGenerate call 1611 Inputs: 1613 o env_handle ENVIRONMENT HANDLE 1615 Outputs: 1617 o major_status INTEGER, 1618 o minor_status INTEGER, 1619 o final_pidu OCTET STRING, 1620 o token OCTET STRING, 1621 o evidence_check OCTET STRING 1622 -- present only if an evidence is requested. 1624 Adams Document Expiration: 25 Sept. 1997 27 1626 Description: 1628 Using the security environment referenced by env_handle, provide 1629 the requested token or the final P-IDU. A token will be generated 1630 if encapsulation was not requested; otherwise, the final P-IDU is 1631 provided. 1633 2.3.3.8. IDUP_EV_MultiBuffer_StartVerify call 1635 Inputs: 1637 o env_handle ENVIRONMENT HANDLE, 1638 o token OCTET STRING, 1639 o evidence_check OCTET STRING, 1640 -- present only if an evidence has been previously requested. 1642 Outputs: 1644 o major_status INTEGER, 1645 o minor_status INTEGER 1647 Description: 1649 Using the security environment referenced by env_handle, initialize 1650 the data structures required to begin the process of verifying the 1651 token. The P-IDU will be supplied in multiple buffers to the 1652 IDUP_EV_Process_Buffer call. 1654 2.3.3.9. IDUP_EV_MultiBuffer_EndVerify call 1656 Input: 1658 o env_handle ENVIRONMENT HANDLE 1660 Outputs: 1662 o major_status INTEGER, 1663 o minor_status INTEGER, 1664 o Nr_Options PARAMETER BUNDLE, 1665 o Originator_Information PARAMETER BUNDLE, 1666 o Request_Features PARAMETER BUNDLE, 1667 o trusted_time_stamping_time UTCTime OPTIONAL, 1668 o complete_evidence_before UTCTime OPTIONAL, 1669 o complete_evidence_after UTCTime OPTIONAL, 1670 o idu_buffer OCTET STRING 1671 -- if the IDU was present within the token 1673 Description: 1675 Using the security environment referenced by env_handle, complete 1676 the verification processing on the data and provide verified output 1677 parameters to the caller when the major status code is either: 1679 o GSS_S_COMPLETE or 1680 o IDUP_S_INCOMPLETE 1682 Adams Document Expiration: 25 Sept. 1997 28 1684 2.3.3.10. IDUP_EV_Process_Buffer call 1686 Inputs: 1688 o env_handle ENVIRONMENT HANDLE, 1689 o input_buffer OCTET STRING 1691 Outputs: 1693 o major_status INTEGER, 1694 o minor_status INTEGER, 1695 o output_buffer OCTET STRING 1696 -- may be zero length (depends on underlying mechanism and 1697 -- corresponding Generate () call and options 1698 (data_included_in_token) 1700 Description: 1702 Using the security environment referenced by env_handle, continue 1703 the processing on the data in input_buffer and, if it is available, 1704 put any resulting output data in output_buffer. The application 1705 calls this routine over and over again with new buffers of data 1706 until it has processed all the data buffers of the IDU/PIDU. It 1707 then calls the appropriate End() call to complete the processing. 1709 2.3.4. Parameter Bundles 1711 The concept of "parameter bundles" is used in the calls presented in 1712 the following subsections in order to simplify their presentation and 1713 (hopefully) clarify their intended purpose and use. A parameter 1714 bundle is simply a set of closely-related parameters of a call which 1715 are either all used by / available to the calling application or all 1716 not used by / unavailable to the calling application. These 1717 parameters may be all input parameters, all output parameters, or 1718 any combination of the two. 1720 A typical use envisioned for parameter bundles in a language such as 1721 C would be as a structure, where individual parameters in the bundle 1722 are structure members. The calling application wishing to use a 1723 particular bundle would then allocate the appropriate structure 1724 variable, assign the desired input values to the appropriate members, 1725 and pass the address of the structure as the bundle "parameter". On 1726 output, the values of the appropriate output members may be read. An 1727 application not wishing to use a particular bundle (or one which is 1728 satisfied with default values for all input parameters of the bundle 1729 and which doesn't care about output values), can pass NULL as the 1730 bundle "parameter". From the mechanism implementor's perspective, if 1731 a parameter bundle is not supported (for example, if it represents a 1732 security service which is not supported by the implementation), then 1733 any non-NULL value passed as the bundle parameter will generate an 1734 error status return code. 1736 The following parameter bundles are used in the subsequent protection 1737 and unprotection sets of calls. A parameter preceded by "(I)" is an 1738 input parameter; one preceded by "(O)" is an output parameter; one 1739 preceded by neither is an input if the bundle itself is an input and 1740 is an output if the bundle itself is an output; one preceded by "(X)" 1741 is the opposite: an output if the bundle itself is an input and an 1742 input if the bundle itself is an output. 1744 Adams Document Expiration: 25 Sept. 1997 29 1746 o Mech_Specific_Info PARAMETER BUNDLE 1747 -- actual parameters included in this bundle are defined by (and 1748 -- specific to) the underlying mechanism 1750 o Sensitivity PARAMETER BUNDLE, 1751 -- actual parameters included in this bundle are defined by (and 1752 -- specific to) the underlying mechanism, but may include 1753 -- codified values for "Unclassified", "Secret", "Top Secret", 1754 -- and so on 1756 o Service_Creation_Info PARAMETER BUNDLE 1757 -- actual parameters included in this bundle are defined by (and 1758 -- specific to) the underlying mechanism, but it is mandatory 1759 -- that they include at least service_id and Quality 1761 o Service_Verification_Info PARAMETER BUNDLE 1762 -- actual parameters included in this bundle are defined by (and 1763 -- specific to) the underlying mechanism, but it is mandatory 1764 -- that they include at least service_id and Quality 1766 o Quality PARAMETER BUNDLE 1767 o qop_algs UNSIGNED INTEGER, 1768 o validity UNSIGNED INTEGER, 1769 -- protection guaranteed to be valid until time specified 1770 o policy_id OBJECT IDENTIFIER, 1771 -- security policy under which protection is/was carried out 1772 o allow_policy_mapping BOOLEAN, 1773 -- determines whether mapping between policy IDs is allowed 1774 o actual_policy_time INTEGER 1775 -- time at which the above policy rules came into effect 1777 o Idu_Information PARAMETER BUNDLE, 1778 o idu_type_oid OBJECT IDENTIFIER, 1779 o idu_type_string OCTET STRING, 1780 o idu_title OCTET STRING, 1781 o idu_sensitivity Sensitivity, 1782 o pidu_type_oid OBJECT IDENTIFIER, 1783 o pidu_type_string OCTET STRING, 1784 o pidu_title OCTET STRING, 1785 o pidu_sensitivity Sensitivity, 1787 o Prot_Information PARAMETER BUNDLE, 1788 o originator_name INTERNAL NAME, 1789 o idu_information Idu_Information, 1790 o protection_time INTEGER, 1792 Adams Document Expiration: 25 Sept. 1997 30 1794 o Special_Conditions PARAMETER BUNDLE, 1795 o prot_oper_id INTEGER, 1796 o form_complete_evidence BOOLEAN, 1797 -- input to protection operations for evidence generation 1798 o pidu_in_solic_service BOOLEAN, 1799 -- in protection operations, used as input for service 1800 -- solicitation to request that receiver include the 1801 -- received PIDU when generating the response. In unprot. 1802 -- operations, used as output to inform receiver that PIDU 1803 -- should be included when generating the response. 1804 o use_trusted_time BOOLEAN, 1805 o use_untrusted_time BOOLEAN, 1807 o Bad_Target_Name PARAMETER BUNDLE, 1808 o (O) bad_targ_name INTERNAL NAME, 1809 o (O) bad_targ_status INTEGER, 1810 -- a (mechanism-defined) status flag giving the reason 1811 -- for rejection of the name in bad_targ_name 1812 -- Example reasons may include: 1813 -- SYNTAX_INVALID 1814 -- the syntax of the name is invalid; 1815 -- NAME_UNRECOGNIZED 1816 -- the name is not recognized; 1817 -- NAME_AMBIGUOUS 1818 -- the name cannot be resolved; 1819 -- ACCESS_DENIED 1820 -- access to this target is denied; 1821 -- CERTIFICATE_NOT_FOUND 1822 -- the encryption certificate of the target could 1823 -- not be found. 1825 o Target_Info PARAMETER BUNDLE, 1826 o targ_names SET OF INTERNAL NAME, 1827 o (O) bad_targ_count INTEGER, 1828 o (O) bad_target_name Bad_Target_Name, 1830 o General_Service_Data PARAMETER BUNDLE, 1831 o target_info Target_Info, 1832 o (X) unencapsulated_token OCTET STRING, 1833 -- zero length if encapsulation_request is TRUE 1834 o (O) minor_status INTEGER, 1836 Three types of protection services are defined in IDUP. These are 1838 1. perform unsolicited service (i.e., act on a locally-generated 1839 service request), 1840 2. perform solicited service (i.e., act on a remotely-generated 1841 service request), and 1842 3. perform service solicitation (i.e., send a service request to 1843 the remote end). 1845 As an originator, applying data confidentiality with data integrity, 1846 or data origin authentication with data integrity, or proof of origin 1847 evidence is an example of service type 1. As a target, creating a 1848 proof of delivery (i.e., receipt) evidence token as the result of a 1849 request received from the originator is an example of service type 2. 1850 Finally, as an originator, submitting a request that one or more 1851 targets return a receipt for the data sent is an example of service 1852 type 3. 1854 Adams Document Expiration: 25 Sept. 1997 31 1856 The first four parameters in the Prot_Service parameter bundle 1857 pertain to all service types; the fifth parameter is used if and only 1858 if service type 2 is desired; parameters 6-8 are used if and only if 1859 service type 3 is desired. 1861 o Prot_Service PARAMETER BUNDLE 1862 o (I) prot_service_type INTEGER, 1863 o (I) service_id OBJECT IDENTIFIER, 1864 o (I) quality Quality, 1865 -- NULL specifies default Quality 1866 o (I) general_service_data General_Service_Data, 1867 o (I) service_creation_info Service_Creation_Info, 1868 o (I) service_to SET OF INTERNAL NAME, 1869 o (O) service_verification_info Service_Verification_Info, 1870 o (O) service_verification_info_id INTEGER, 1872 Also, three types of unprotection services are defined. These are 1874 1. receive unsolicited service (i.e., process unrequested 1875 remotely-generated service), 1876 2. receive solicited service (i.e., process remotely-generated 1877 response to locally-generated request), and 1878 3. receive service solicitation (i.e., process req. from rem. end) 1880 As a target, unprotecting an encrypted message, or verifying the 1881 originator's proof of origin is an example of service type 1. As an 1882 originator, verifying a proof of delivery which you requested from a 1883 target is an example of service type 2. Finally, as a target, 1884 receiving a request from an originator for a proof of delivery is an 1885 example of service type 3. 1887 The first four parameters in the Unprot_Service parameter bundle 1888 pertain to all service types; parameters 5-6 are used if and only if 1889 service type 2 is required; parameters 7-8 are used only if service 1890 type 3 is required. 1892 o Unprot_Service PARAMETER BUNDLE 1893 o (O) unprot_service_type INTEGER, 1894 o (O) service_id OBJECT IDENTIFIER, 1895 o (O) quality Quality, 1896 -- actual Quality specified (never NULL) 1897 o (O) general_service_data General_Service_Data, 1898 o (O) service_verification_info_id INTEGER, 1899 o (I) service_verification_info Service_Verification_Info, 1900 o (O) service_to SET OF INTERNAL NAME, 1901 o (O) service_creation_info Service_Creation_Info, 1903 2.3.5. IDUP_Start_Protect call 1905 Inputs: 1907 o env_handle ENVIRONMENT HANDLE, 1908 o Mech_Specific_Info PARAMETER BUNDLE, 1909 -- NULL selects the mechanism-defined default values 1910 o Idu_Information PARAMETER BUNDLE, 1911 o Special_Conditions PARAMETER BUNDLE, 1912 o encapsulation_request BOOLEAN, 1913 o single_idu_buffer OCTET STRING, 1914 -- non-zero length for this buffer means that Protect/End_Protect 1915 -- won't be called (i.e., entire IDU is contained in this buffer) 1916 o Target_Info PARAMETER BUNDLE, 1917 o Services_to_Perform SET OF Prot_Service, 1919 Adams Document Expiration: 25 Sept. 1997 32 1921 Outputs: 1923 o major_status INTEGER, 1924 o minor_status INTEGER, 1925 o midu_buffer OCTET STRING, 1926 -- zero length if encapsulation_request is TRUE; 1927 -- may be zero length otherwise (depends on underlying mechanism) 1928 o pidu_buffer OCTET STRING, 1929 -- zero length if encapsulation_request is FALSE; 1930 -- may be zero length otherwise (depends on underlying mechanism) 1932 Return major_status codes: 1934 o GSS_S_COMPLETE 1935 -- the protection process can begin (or has completed, if 1936 -- single_idu_buffer has non-zero length). 1937 o GSS_S_CONTINUE_NEEDED 1938 o GSS_S_CREDENTIALS_EXPIRED 1939 o IDUP_S_NO_ENV 1940 o IDUP_S_ENCAPSULATION_UNAVAIL 1941 o IDUP_S_MORE_DATA_NEEDED 1942 -- indicates whether protection is completed by this call or by 1943 -- IDUP_End_Protect() (e.g., whether more data buffers are 1944 -- required for evidence generation). 1945 o IDUP_S_SERVICE_UNAVAIL 1946 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL 1947 o IDUP_S_UNKNOWN_OPER_ID 1948 o GSS_S_BAD_QOP 1949 o IDUP_S_BAD_TARG_INFO 1950 o GSS_S_FAILURE 1952 Using the security environment referenced by env_handle, initialize 1953 the data structures required to begin the process of protecting the 1954 IDU buffers. The caller requests specific protection services by 1955 supplying the appropriate Prot_Service parameter bundles in 1956 Services_to_Perform. Each service is able to return a minor status 1957 code to the calling application, if necessary. 1959 The calling application, knowing the size of the IDU it wishes to 1960 protect and the buffer size which it has available to it, can choose 1961 to input the entire IDU in a single buffer and omit the subsequent 1962 IDUP_Protect() and IDUP_End_Protect() calls. Furthermore, the 1963 application can request that the resulting M-IDU be encapsulated in 1964 the token -- so that the token contains the entire P-IDU -- rather 1965 than having it be returned separately in midu_buffer. Encapsulation, 1966 however, may not be supported by all underlying mechanisms or 1967 implementations; if this is the case, the 1968 IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and 1969 M-IDU will be returned in midu_buffer. 1971 For those mechanisms which allow or require multiple stages of 1972 processing, each producing a different aspect of protection for the 1973 IDU, the operation identifier prot_oper_id is used to specify 1974 which stage is currently being requested by the application. An 1975 example where this would be useful is a mechanism which implements 1976 the signed Message Security Protocol [MSP]. As another example, a 1977 mechanism may choose to do a digital signature in two stages: one 1978 for the hashing of the message and another for the signature on the 1979 hash. The calling application would therefore use the protection set 1980 of calls on the IDU in stage 1 and then use the protection set of 1981 calls on the token (from stage 1) in stage 2. 1983 Adams Document Expiration: 25 Sept. 1997 33 1985 Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where 1986 "n" is the number of stages as defined by the mechanism (typically 1 1987 or 2)). The calling application uses this parameter to indicate to 1988 the underlying mechanism whether it wishes to do stage 1 of 1989 protection / unprotection processing, or stage 2, and so on. 1991 If one or more of the targets in targ_names cannot be used as a valid 1992 recipient of the P-IDU, these names will be returned in 1993 bad_targ_names (with associated status codes in bad_targ_status). As 1994 long as at least one of the targets can be used, this does not cause 1995 this call to fail; it is the caller's choice to discontinue IDU 1996 protection if the target set which can be used is unsuitable for the 1997 caller's purposes. Note that each Prot_Service parameter bundle can 1998 also input a list of targ_names; this is used if a separate list is 1999 to be used for that service only (the general list of targets is to 2000 be used for all services unless overridden in this way). 2002 2.3.6. IDUP_Protect call 2004 Inputs: 2006 o env_handle ENVIRONMENT HANDLE, 2007 o input_buffer OCTET STRING, 2009 Outputs: 2011 o major_status INTEGER, 2012 o minor_status INTEGER, 2013 o output_buffer OCTET STRING 2014 -- may be zero length if encapsulation_request was set to TRUE in 2015 -- IDUP_Start_Protect() (depends on underlying mechanism) 2017 Return major_status codes: 2019 o GSS_S_COMPLETE 2020 o IDUP_S_NO_ENV 2021 o GSS_S_FAILURE 2023 Using the security environment referenced by env_handle, continue the 2024 protection processing on the data in input_buffer and, if the 2025 underlying mechanism defines this, put any resulting P-IDU/M-IDU data 2026 in output_buffer. The application calls this routine over and over 2027 again with new buffers of data until it has protected all the data 2028 buffers of the IDU. It then calls IDUP_End_Protect() to complete the 2029 protection processing. 2031 Adams Document Expiration: 25 Sept. 1997 34 2033 2.3.7. IDUP_End_Protect call 2035 Inputs: 2037 o env_handle ENVIRONMENT HANDLE, 2039 Outputs: 2041 o major_status INTEGER, 2042 o minor_status INTEGER, 2043 o Services_to_Perform SET OF Prot_Service, 2044 o final_midu_buffer OCTET STRING, 2045 -- zero length if encapsulation_request was set to TRUE in 2046 -- IDUP_Start_Protect(), in which case pidu is used 2047 o final_pidu_buffer OCTET STRING, 2048 -- zero length if encapsulation_request was set to FALSE in 2049 -- IDUP_Start_Protect(), in which case token and midu are used 2051 Return major_status codes: 2053 o GSS_S_COMPLETE 2054 -- protection has successfully completed and the resulting P-IDU 2055 -- is ready for transfer. If defined by the underlying mechanism, 2056 -- final_midu_buffer will contain any residual M-IDU data. 2057 o GSS_S_CONTINUE_NEEDED 2058 o IDUP_S_NO_ENV 2059 o GSS_S_FAILURE 2061 Using the security environment referenced by env_handle, complete the 2062 protection processing on the data and place the computed output in 2063 final_pidu_buffer (or final_midu_buffer and the unencapsulated_token 2064 parameter for each Prot_Service). If a service was requested from 2065 one or more targets in Start_Protect() - and if this is supported by 2066 the underlying mechanism - Service_Verification_Info will hold 2067 whatever data is necessary for the mechanism to verify a service 2068 returned by a target (unprotector) of the P-IDU. Successful 2069 application of IDUP_End_Protect() does not guarantee that the 2070 corresponding unprotection set of calls can necessarily be performed 2071 successfully when the P-IDU arrives at the target (for example, it 2072 may be damaged in transit). 2074 Adams Document Expiration: 25 Sept. 1997 35 2076 2.3.8. IDUP_Start_Unprotect call 2078 Inputs: 2080 o env_handle ENVIRONMENT HANDLE, 2081 o Mech_Specific_Info PARAMETER BUNDLE, 2082 -- NULL selects the mechanism-defined default values 2083 o single_data_buffer OCTET STRING, 2084 -- non-zero length for this buffer means that IDUP_Unprotect() and 2085 -- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU 2086 -- (if encapsulation is used) or M-IDU (if encap. is not used) 2087 -- is contained in this buffer) 2088 o partial_pidu_buffer OCTET STRING, 2089 -- may be an arbitrary-sized piece of the full pidu (if the 2090 -- application's buffer isn't large enough to hold entire pidu). 2091 -- Used if pidu_buffer will be input a buffer at a time (except 2092 -- that the final buffer must be passed in final_pidu_buffer 2093 -- rather than partial_pidu_buffer). Only one of 2094 -- single_pidu_buffer and partial(final)_pidu_buffer can have 2095 -- nonzero length. 2096 o final_pidu_buffer OCTET STRING, 2097 o Special_Conditions PARAMETER BUNDLE, 2099 Outputs: 2101 o major_status INTEGER, 2102 o minor_status INTEGER, 2103 o Services_to_Receive SET OF Unprot_Service, 2104 o Prot_Information PARAMETER BUNDLE, 2105 o single_idu_buffer OCTET STRING, 2106 -- if this buffer has non-zero length, then service processing has 2107 -- been completed on the data in single_pidu_buffer 2108 o initial_idu_buffer OCTET STRING, 2109 -- holds any data from partial(final)_pidu_buffer which has been 2110 -- unprotected; remaining data will be returned by Unprotect and 2111 -- End_Unprotect as they are called with successive buffers of 2112 -- pidu 2113 o Service_Verification_Info PARAMETER BUNDLE, 2114 -- used only if target is on "service_to" list in Unprot_Service 2115 o service_verification_info_id INTEGER, 2116 -- used only if target is on "service_to" list in Unprot_Service 2118 Return major_status codes: 2120 o GSS_S_COMPLETE 2121 -- unprotection processing can begin (or has completed, if 2122 -- single_idu_buffer has non-zero length). 2123 o IDUP_S_INCOMPLETE 2124 -- used only if single_idu_buffer has non-zero length. 2125 o GSS_S_CONTINUE_NEEDED 2126 o IDUP_S_MORE_PIDU_NEEDED 2127 o GSS_S_DEFECTIVE_TOKEN 2128 o IDUP_S_INAPPROPRIATE_CRED 2130 Adams Document Expiration: 25 Sept. 1997 36 2132 o IDUP_S_MORE_DATA_NEEDED 2133 o GSS_S_DEFECTIVE_VERIF 2134 o IDUP_S_NO_MATCH 2135 o IDUP_S_SERVICE_UNAVAIL 2136 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL 2137 o IDUP_S_SERV_VERIF_INFO_NEEDED 2138 o GSS_S_CREDENTIALS_EXPIRED 2139 o IDUP_S_NO_ENV 2140 o IDUP_S_UNKNOWN_OPER_ID 2141 o GSS_S_BAD_QOP 2142 -- the qop_algs value specified in P-IDU for at least one of the 2143 -- services is unavailable in the local mechanism, so processing 2144 -- cannot continue. 2145 o GSS_S_BAD_SIG 2146 o IDUP_S_BAD_DOA_KEY 2147 o IDUP_S_BAD_KE_KEY 2148 o IDUP_S_BAD_ENC_IDU 2149 o GSS_S_FAILURE 2151 Using the security environment referenced by env_handle, initialize 2152 the data structures required to begin the process of unprotecting a 2153 P-IDU. The caller will be alerted as to which services were applied 2154 to the P-IDU in the returned Services_to_Receive set of parameters. 2156 If encapsulation was not used by the originator, it is the receiving 2157 application's responsibility to separate the received P-IDU into a 2158 M-IDU and one or more unencapsulated_token buffers (the latter being 2159 input in separate Unprot_Service bundles in the Services_to_Receive 2160 parameter). These unencapsulated_token buffers should be input 2161 before the M-IDU (i.e., in IDUP_Start_Unprotect) or after the M-IDU 2162 (i.e., in IDUP_End_Unprotect) as appropriate; this order may be 2163 dictated, for example, by their placement in the in-coming message. 2165 If unprotection will be applied more than once to a given P-IDU, it 2166 is the responsibility of the calling application to remember if a 2167 service solicitation has been responded to previously (i.e., if the 2168 requested service has already been generated / sent for that P-IDU) 2169 and thus ignore subsequent solicitations on unprotect. 2171 The time flags indicate whether to consult trusted, untrusted, or no 2172 time (if both flags are FALSE) during the unprotection operation. If 2173 the current time is not to be checked, then unprotection may be 2174 successful even if the protector's key has expired since the P-IDU 2175 was generated (that is, if the Validity period -- as specified in 2176 the Quality parameter bundle -- has expired). 2178 If the underlying mechanism supports it and if this information is 2179 contained in the P-IDU, information regarding the originator (that 2180 is, the entity which used the protection set of calls to generate 2181 this P-IDU) is returned in the Prot_Information parameter bundle. 2183 Adams Document Expiration: 25 Sept. 1997 37 2185 2.3.9. IDUP_Unprotect call 2187 Inputs: 2189 o env_handle ENVIRONMENT HANDLE, 2190 o input_buffer OCTET STRING 2192 Outputs: 2194 o major_status INTEGER, 2195 o minor_status INTEGER, 2196 o output_buffer OCTET STRING 2198 Return major_status codes: 2200 o GSS_S_COMPLETE 2201 o IDUP_S_NO_ENV 2202 o GSS_S_FAILURE 2204 Using the security environment referenced by env_handle, continue the 2205 unprotection processing on the data in input_buffer, putting any 2206 resulting IDU data in output_buffer (if required). 2208 2.3.10. IDUP_End_Unprotect call 2210 Inputs: 2212 o env_handle ENVIRONMENT HANDLE, 2214 Outputs: 2216 o major_status INTEGER, 2217 o minor_status INTEGER, 2218 o Prot_Information PARAMETER BUNDLE, 2219 o Services_to_Receive SET OF Unprot_Service, 2220 o final_idu_buffer OCTET STRING, 2221 o Service_Verification_Info PARAMETER BUNDLE, 2222 -- used only if target is on "service_to" list in Unprot_Service 2223 o service_verification_info_id INTEGER, 2224 -- used only if target is on "service_to" list in Unprot_Service 2226 Return major_status codes: 2228 o GSS_S_COMPLETE 2229 -- residual IDU data will be returned in final_idu_buffer. 2230 o IDUP_S_INCOMPLETE 2231 o GSS_S_CONTINUE_NEEDED 2232 o GSS_S_BAD_SIG 2233 o IDUP_S_BAD_DOA_KEY 2234 o IDUP_S_BAD_KE_KEY 2235 o IDUP_S_BAD_ENC_IDU 2236 o IDUP_S_NO_ENV 2237 o GSS_S_FAILURE 2239 Using the security environment referenced by env_handle, complete the 2240 unprotection processing on the data and return the appropriate status 2241 code. If there is any residual IDU data it will be returned in 2242 final_idu_buffer. 2244 Adams Document Expiration: 25 Sept. 1997 38 2246 If the IDUP_S_INCOMPLETE major status value is returned, all output 2247 parameters are conditionally valid; the unprotection set of functions 2248 will have to be called again (perhaps with a complete P-IDU, as 2249 produced by IDUP_Form_Complete_PIDU) in order to get valid values for 2250 all parameters. "Conditional validity" may arise, for example, if 2251 all relevant certificates verify correctly, but it is not yet past 2252 the time up to which the current policy allows the authorities 2253 involved to repudiate their keys. 2255 If the underlying mechanism supports it and if this information is 2256 contained in the token, information regarding the originator (that 2257 is, the entity which used the protection set of calls to generate 2258 this token) is returned in the Prot_Information parameter bundle. 2259 This information may or may not be omitted if it was returned by the 2260 IDUP_Start_Unprotect() call. 2262 Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the 2263 concept of error tokens transferred between sender and recipient 2264 since the protection and unprotection of an IDU may be separated by 2265 an indefinite amount of time and may or may not be performed by the 2266 same entity. 2268 2.4. Special-Purpose Calls 2270 2.4.1. Relationship to GSS-API 2272 The special-purpose call described in this section has no analog 2273 in GSS-API [RFC-2078]. This call is used to complete a P-IDU (that 2274 is, to generate a P-IDU which can be unprotected successfully with 2275 no additional data at any time during its validity period). This 2276 call may not be supported by all underlying IDUP mechanisms or 2277 implementations. 2279 2.4.2. IDUP_Form_Complete_PIDU call 2281 Inputs: 2283 o env_handle ENVIRONMENT HANDLE, 2284 o single_pidu_buffer OCTET STRING, 2285 o partial_pidu_buffer OCTET STRING, 2286 -- an arbitrary-sized piece of the full pidu token. Used if pidu 2287 -- will be input a buffer at a time (except that the final buffer 2288 -- must be passed in final_pidu_buffer rather than 2289 -- partial_pidu_buffer). Only one of single_pidu_buffer and 2290 -- partial(final)_pidu_buffer can have nonzero length. 2291 o final_pidu_buffer OCTET STRING, 2293 Outputs: 2295 o major_status INTEGER, 2296 o minor_status INTEGER, 2297 o pidu_token_out OCTET STRING 2298 -- the augmented PIDU; may be complete 2299 o call_again_before INTEGER, 2300 o call_again_after INTEGER, 2301 o trusted_time_stamping_time INTEGER 2302 -- for information only 2304 Adams Document Expiration: 25 Sept. 1997 39 2306 Return major_status codes: 2308 o GSS_S_COMPLETE 2309 o GSS_S_CONTINUE_NEEDED 2310 o IDUP_S_INCOMPLETE 2311 -- generation of the P-IDU is not yet complete. The application 2312 -- should call this function again before the time given in 2313 -- call_again_before (if not NULL), or after the time given in 2314 -- call_again_after (if not NULL), or both (if neither are NULL). 2315 o IDUP_S_SERVICE_UNAVAIL 2316 o GSS_S_DEFECTIVE_TOKEN 2317 o GSS_S_FAILURE 2319 Form_Complete_PIDU is used primarily by the evidence services; in 2320 particular, when the evidence token itself does not contain all the 2321 data required for its verification, and it is anticipated that some 2322 of the data not stored in the token may become unavailable during 2323 the interval between generation of the evidence token and 2324 verification unless it is stored in the token. The 2325 Form_Complete_PIDU operation gathers the missing information and 2326 includes it in the token so that verification can be guaranteed to 2327 be possible at any future time. 2329 This call generates a PIDU which can be unprotected successfully with 2330 no additional data at any time during its validity period. 2332 Using the security environment referenced by env_handle, complete the 2333 generation of a P-IDU token and return the appropriate status value 2334 along with the completed token (if available). Such a call may be 2335 used, for example, for the purpose of batch evidence generation on an 2336 "evidence server". A local machine may be able to use the protection 2337 set of calls to fill out most of an evidence token and then send a 2338 number of these to a batch processor which forms the complete 2339 evidence tokens (perhaps by adding a certification path, or a 2340 timestamp and signature from a timestamping authority). As another 2341 example, on the receiving end an application may make such a call in 2342 order to collect all the information necessary to unprotect a P-IDU 2343 (such as all relevant certificates and Certificate Revocation Lists); 2344 this will ensure that the calls to the unprotection set of operations 2345 will be entirely local (i.e., can be performed off-line) and fast. 2347 Note that the complete P-IDU generated will be formed using trusted 2348 time if this is available in the environment referenced by env_handle 2349 and will use untrusted time or no time otherwise (depending on what 2350 is available). 2352 2.5. Support calls 2354 2.5.1. Relationship to GSS-API 2356 Support calls in IDUP-GSS-API are to be understood and used as 2357 described in GSS-API [RFC-2078]. The calls described in Section 2.4 2358 of GSS-API (including all associated parameters) are unchanged. The 2359 following additional calls are specified for IDUP-GSS-API. 2361 Adams Document Expiration: 25 Sept. 1997 40 2363 2.5.2: IDUP_Acquire_cred_with_auth call 2365 Inputs: 2367 o desired_name INTERNAL NAME, 2368 -- NULL requests locally-determined default 2369 o authenticator OCTET STRING 2370 -- string which authenticates the caller claiming to be 2371 -- desired_name 2372 o lifetime_req INTEGER, 2373 -- in seconds; 0 requests default 2374 o desired_mechs SET OF OBJECT IDENTIFIER, 2375 -- empty set requests system-selected default 2376 o cred_usage BIT STRING 2377 -- actual values which can be used currently correspond to those 2378 -- given in Section 2.1.1 (i.e., 2379 -- NO_RESTRICTION 0 2380 -- ENCRYPT_ONLY 1 2381 -- DECRYPT_ONLY 2 2382 -- SIGN_ONLY 4 2383 -- VERIFY_ONLY 8 2384 -- with the non-zero values logically OR'ed together in any 2385 -- desired combination to restrict credential usage). 2386 -- Future possible values for this parameter are for further 2387 -- study (note that the type of this parameter is BIT STRING 2388 -- (rather than INTEGER as in GSS_Acquire_cred) to facilitate 2389 -- such future expansion). 2391 Outputs: 2393 o major_status INTEGER, 2394 o minor_status INTEGER, 2395 o output_cred_handle CREDENTIAL HANDLE, 2396 o actual_mechs SET OF OBJECT IDENTIFIER, 2397 o lifetime_rec INTEGER 2398 -- in seconds, or reserved value for INDEFINITE 2400 This call is identical to the GSS_Acquire_cred call, with the 2401 exception of the added parameter "authenticator". This parameter 2402 (typically a password, pass-phrase, or PIN) is used to 2403 authenticate the caller claiming to be desired_name to the 2404 underlying GSS (or mechanism) code. 2406 Implementations that are able to authenticate the caller in some 2407 other way are encouraged to use the GSS_Acquire_cred call; 2408 implementations having no other means available to them, or wishing 2409 to explicitly authenticate the caller at the time of credential 2410 acquirement, should use the IDUP_Acquire_cred_with_auth call. 2412 Note that the return major status codes for this call are identical 2413 to those given for the GSS_Acquire_cred call. If the authentication 2414 fails (e.g., the wrong authenticator is supplied for the given 2415 desired_name), the major status GSS_S_FAILURE is returned (along with 2416 an appropriate minor status code). 2418 Adams Document Expiration: 25 Sept. 1997 41 2420 2.5.3. IDUP_Parse_token call 2422 Inputs: 2424 o input_token OCTET STRING 2426 Outputs: 2428 o major_status INTEGER, 2429 o minor_status INTEGER, 2430 o mech_type OBJECT IDENTIFIER, 2432 Return major_status codes: 2434 o GSS_S_COMPLETE 2435 -- input_token could be parsed for all relevant fields. 2436 o GSS_S_CREDENTIALS_EXPIRED 2437 o GSS_S_DEFECTIVE_TOKEN 2438 -- the mechanism type could be parsed, but either the other fields 2439 -- could not be determined from the input_token, or their values 2440 -- did not correspond to valid values for that mechanism. 2441 o GSS_S_FAILURE 2442 -- the mechanism type could not be parsed (for example, the 2443 -- token may be corrupted). 2445 IDUP_Parse_Token() is used to return to an application the attributes 2446 which correspond to a given input token. Since IDUP-GSS-API tokens 2447 are meant to be opaque to the calling application, this function 2448 allows the application to determine information about the token 2449 without having to violate the opaqueness intention of IDUP. Of 2450 primary importance is the mechanism type, which the application can 2451 then use as input to the IDUP_Establish_Env() call in order to 2452 establish the correct environment in which to have the token 2453 processed. Other token attributes may be added as outputs of this 2454 call in future versions of this specification, if required (see 2455 IDUP_Get_token_details below). 2457 If all tokens are framed as suggested in Section 3.1 of [RFC-2078] 2458 (mandated in the Kerberos V5 GSS mechanism [RFC 1964] and in the SPKM 2459 GSS Mechanism [RFC 2025]), then any mechanism implementation should 2460 be able to return the mech_type parameter for any uncorrupted input 2461 token. If the mechanism implementation whose IDUP_Parse_token() 2462 function is being called does recognize the token, it can return 2463 other token attributes, if specified. 2465 The call IDUP_Get_token_details is an extension to IDUP_Parse_token 2466 in that a number of token attributes are returned when the mech_type 2467 is recognized. The attributes described are specific to the 2468 processing of evidence tokens; in future versions of this 2469 specification it may be desirable to add parameters for integrity and 2470 confidentiality services so that IDUP_Get_token_details is a more 2471 general-purpose call. At such a time it may make sense to phase out 2472 the IDUP_Parse_token call, since its functionality would be subsumed 2473 by IDUP_Get_token_details. 2475 Adams Document Expiration: 25 Sept. 1997 42 2477 2.5.4. IDUP_Get_token_details call 2479 Inputs: 2481 o token OCTET STRING 2482 -- all the data to be returned shall be at the beginning of the 2483 -- token; hence, a single call is needed. It is not necessary to 2484 -- provide the entire token when the token includes the IDU. 2486 Ouputs: 2488 o major_status INTEGER, 2489 o minor_status INTEGER, 2490 o mech_type OBJECT IDENTIFIER, 2491 o data_included_in_token BOOLEAN, 2492 -- true if the data is encapsulated 2493 o idu_size INTEGER, 2494 o requested_evidence_back BOOLEAN, 2495 -- true if this is an evidence generated in response to a 2496 -- previously-sent request 2497 o evidence_check OCTET STRING, 2498 -- meaningful if the boolean above is true 2499 o nr_policy OBJECT IDENTIFIER, 2500 o Nr_Options PARAMETER BUNDLE, 2501 o Originator_Information PARAMETER BUNDLE, 2502 o Request_Features PARAMETER BUNDLE, 2503 -- describes the included request, if any. 2504 o time_stamping_time INTEGER OPTIONAL 2506 Description: 2508 IDUP_Get_token_details gives only an hint about the content of the 2509 token, there is no integrity check of any kind performed. When the 2510 token contains an evidence it is possible to check that this 2511 information is correct only by doing a proper verification of the 2512 evidence. 2514 The OID of the mechanism and whether the token contains the 2515 associated data is returned. In addition the size of the associated 2516 data, whether inside or outside the token, is included. 2518 When the input token contains only an evidence generated 2519 spontaneously, the following is returned: 2521 - the evidence type, 2522 - the Non-Repudiation policy under which the evidence has been 2523 generated, 2524 - the name of the generator of the evidence, 2525 - the date and time when the evidence was generated (if available), 2526 - the date and time when it was time stamped (if available) 2528 When the input token contains only an evidence generated in response 2529 to a request from another entity, the following additional 2530 information is returned: 2532 - an indicator to state that this evidence relates to a request, 2533 - a string significant for the requester that will allow him to 2534 check whether the answer corresponds to the requested evidence. 2536 Adams Document Expiration: 25 Sept. 1997 43 2538 When the input token only contains a request, the following is 2539 returned: 2541 - the name of the requestor of the evidence, 2542 - the date and time when the request was made, 2543 - the evidence type to send back, 2544 - the non-repudiation policy under which the evidence to send back 2545 should be generated, 2546 - the names of the recipients which should generate and distribute 2547 the requested evidence, 2548 - the names of the recipients to whom the requested evidence should 2549 be sent after it has been generated. 2551 When the input token contains both evidence and a request, an 2552 indicator is returned describing whether the new evidence should be 2553 generated using only the data in the input token, or using both the 2554 data and the evidence in the input token. 2556 2.5.5. IDUP_Get_policy_info call 2558 Inputs: 2560 o policy_id OBJECT IDENTIFIER 2562 Outputs: 2564 o major_status INTEGER, 2565 o minor_status INTEGER, 2566 o policy_version INTEGER, 2567 o policy_effective_time INTEGER, 2568 o policy_expiry_time INTEGER, 2569 o supported_services SET OF Service_Descriptor, 2570 o supported_mechanisms SET OF Mechanism_Descriptor 2572 Return major_status codes: 2574 o GSS_S_COMPLETE 2575 -- policy_id recognized; all relevant fields have been returned. 2576 o GSS_S_FAILURE 2577 -- the policy_id was not recognized. 2579 This call (which need not be supported by all underlying mechanisms 2580 or implementations) allows the application to retrieve information 2581 pertaining to a given policy_id. Policies define the following: 2583 - rules for the protection of IDUs, such as trusted third 2584 parties which may be involved in P-IDU generation, the roles 2585 in which they may be involved, and the duration for which the 2586 generated P-IDU is valid; 2588 - rules for the unprotection of P-IDUs, such as the interval 2589 during which a trusted third party may legitimately declare its 2590 key to have been compromised or revoked; and 2592 - rules for adjudication, such as which authorities may be used 2593 to adjudicate disputes. 2595 Adams Document Expiration: 25 Sept. 1997 44 2597 The policy itself may be used by an adjudicator when resolving a 2598 dispute. For example, the adjudicator might refer to the policy to 2599 determine whether the rules for generation of the P-IDU have been 2600 followed. 2602 The following parameter bundles are associated with this call. 2604 o Service_Descriptor PARAMETER BUNDLE, 2605 o service_type OBJECT IDENTIFIER, 2606 o service_validity_duration INTEGER, 2607 o must_use_trusted_time BOOLEAN 2609 o Mechanism_Descriptor PARAMETER BUNDLE, 2610 o mechanism_type OBJECT IDENTIFIER, 2611 o Authority_List PARAMETER BUNDLE, 2612 o maximum_time_skew INTEGER 2613 -- maximum permissible difference between P-IDU generation 2614 -- time and the time of countersignature from a time 2615 -- service (if required). This parameter is unused if 2616 -- trusted time is not required. 2618 o Authority_List PARAMETER BUNDLE, 2619 o authority_name INTERNAL NAME, 2620 o authority_role OCTET STRING, 2621 o last_revocation_check_offset INTEGER 2622 -- may be greater than 0 or less than 0. The value of 2623 -- this parameter is added to P-IDU generation time to 2624 -- get latest time at which the mechanism will check to 2625 -- see if this authority's key has been revoked. 2627 An example of the use of the last parameter in Authority_List is as 2628 follows. If an authority has a defined last_revocation_check_offset 2629 of negative one hour, then all revocations taking effect earlier than 2630 one hour before the generation of a P-IDU will render that P-IDU 2631 invalid; no revocation taking place later than one hour before the 2632 generation of the P-IDU will affect the P-IDU's validity. 2634 Note that both the maximum_time_skew and the 2635 last_revocation_check_offset values are given in minutes. 2637 3. Related Activities 2639 In order to implement the IDUP-GSS-API atop existing, emerging, and 2640 future security mechanisms, the following is necessary: 2642 - object identifiers must be assigned to candidate IDUP-GSS-API 2643 mechanisms and the name types which they support; and 2645 - concrete data element (i.e., token and parameter bundle) formats 2646 must be defined for candidate mechanisms. 2648 Calling applications must implement formatting conventions which will 2649 enable them to distinguish IDUP-GSS-API P-IDUs from other 2650 IDUs in their environment. 2652 Concrete language bindings are required for the programming 2653 environments in which the IDUP-GSS-API is to be employed; such a 2654 binding for the C language is available in the Internet Draft 2655 [IDUP-C]. 2657 Adams Document Expiration: 25 Sept. 1997 45 2659 4. Acknowledgments 2661 Many thanks are due to Tim Moses and Dhanya Thakkar of Entrust 2662 Technologies, Denis Pinkas of Bull, and David Kurn of Tandem 2663 Computers for a number of helpful comments and contributions. 2665 5. Security Considerations 2667 Security issues are discussed throughout this memo. 2669 6. REFERENCES 2671 [MSP]: U.S. National Security Agency, "Message Security 2672 Protocol", Secure Data Network System SDN.701, March 1994. 2674 [RFC-1421]: J. Linn, "Privacy Enhancement for Internet Electronic 2675 Mail: Part I: Message Encryption and Authentication Procedures", 2676 RFC 1421. 2678 [RFC-2078]: J. Linn, "Generic Security Service Application Program 2679 Interface, Version 2", RFC 2078. 2681 [RFC 1964]: J. Linn, "The Kerberos Version 5 GSS-API Mechanism", 2682 RFC 1964. 2684 [RFC 2025]: C. Adams, "The Simple Public-Key GSS-API Mechanism 2685 (SPKM)", RFC 2025. 2687 [IDUP-C]: D. Thakkar, D. Grebovich, "Independent Data Unit 2688 Protection Generic Security Service Application Program Interface: C- 2689 bindings", Internet Draft draft-ietf-cat-idup-cbind-0x.txt (work in 2690 progress). 2692 [ISO/IEC]: 2nd ISO/IEC CD 13888-1, "Information technology - 2693 Security techniques - Non-repudiation - Part 1: General Model", 2694 ISO/IEC JTC 1/SC 27, May 30, 1995 2696 7. Author's Address 2698 Carlisle Adams 2699 Entrust Technologies 2700 P.O.Box 3511, Station C 2701 Ottawa, Ontario, CANADA K1Y 4H7 2703 Phone: +1 613.763.9008 2704 E-mail: cadams@entrust.com 2706 Adams Document Expiration: 25 Sept. 1997 46 2708 APPENDIX A 2710 MECHANISM-INDEPENDENT TOKEN FORMAT 2712 This appendix specifies the use, for IDUP-GSS-API tokens, of the 2713 mechanism-independent level of encapsulating representation for 2714 tokens given in Section 3.1 of GSS-API [RFC-2078]. The 2715 representation given there incorporates an identifier of the 2716 mechanism type to be used when processing the associated tokens. 2717 Use of that octet format is recommended to the designers of 2718 IDUP-GSS-API implementations based on various mechanisms so that 2719 tokens can be interpreted unambiguously at IDUP-GSS-API peers. It is 2720 recognized, however, that for interoperability purposes with peers 2721 not using IDUP for specific IDU protection/unprotection protocols, 2722 the encapsulating representation may need to be omitted. 2724 For purely descriptive purposes, the following simple ASN.1 structure 2725 is used to illustrate the structural relationships among token and 2726 tag objects. For interoperability purposes, token and tag encoding 2727 shall be performed using the concrete encoding procedures described 2728 in Section 3.1 of GSS-API [RFC-2078]. 2730 -- top-level token definition to frame different mechanisms 2732 IDUP-GSS-API DEFINITIONS ::= 2733 BEGIN 2734 MechType ::= OBJECT IDENTIFIER 2736 Token ::= [APPLICATION 0] IMPLICIT SEQUENCE { 2737 thisMech MechType, 2738 token ANY DEFINED BY thisMech 2739 -- contents mechanism-specific 2740 } 2741 END 2743 Adams Document Expiration: 25 Sept. 1997 47 2745 APPENDIX B 2747 EXAMPLES OF IDUP USE 2749 This appendix provides examples of the use of IDUP to do IDU protec- 2750 tion and unprotection. It should not be regarded as constrictive to 2751 implementations or as defining the only means through which 2752 IDUP-GSS-API functions can be realized with particular underlying 2753 technology, and does not demonstrate all IDUP-GSS-API features. 2755 B.1. Simple Mechanism, Single Buffer 2757 To illustrate the simplest possible case, consider an underlying IDUP 2758 mechanism which does straightforward encryption/decryption and 2759 signing/verification only; none of the other possible services, such 2760 as creation of proof-of-origin evidence, requests for proof-of- 2761 delivery evidence, or use of trusted time, are supported. PEM 2762 [RFC-1421] is one example of a mechanism which fits this description. 2763 Furthermore (again for simplicity), assume that encapsulation is 2764 chosen by the calling application during IDU protection. 2766 Such a mechanism would likely use the "SE" set of IDUP-GSS-API calls. 2767 The following parameter bundle uses and defaults would therefore be 2768 specified in the relevant IDUP mechanism document. 2770 SENDER: 2772 Set 2773 env_handle = environment handle in use; 2774 idu_buffer = data buffer; 2775 Target_Info.targ_names = receiver names; 2776 Protect_Options = as necessary; 2778 Call 2779 IDUP_SE_SingleBuffer_Protect() with above input parameters 2780 Check 2781 major_status. If not GSS_S_COMPLETE, check 2782 minor_status, 2783 Target_Info.Bad_Targ_Name, 2784 (as required) for more detailed information. 2786 Send 2787 Output parameter pidu_buffer to receiver. 2789 RECEIVER (any parameters not listed below are given the value NULL): 2791 Set 2792 env_handle = environment handle in use; 2793 pidu_buffer = received data buffer; 2795 Call 2796 IDUP_SE_SingleBuffer_Unprotect() with above input parameters 2797 Check 2798 major_status. If not GSS_S_COMPLETE, check 2799 minor_status, 2800 (as required) for more detailed information 2802 Adams Document Expiration: 25 Sept. 1997 48 2804 Utilize 2805 PIDU_Information.Protect_Options.Protect_Operation, 2806 (to determine which services were applied by the originator) 2807 PIDU_Information.Protect_Options.sign_qop_alg / enc_qop_alg, 2808 (to determine the corresponding qualities of the services) 2809 Prot_Information.originator_name, 2810 (to determine the name of the originator) 2811 Prot_Information.protection_time, 2812 (to determine when the IDU was protected) 2813 idu_buffer 2814 (to retrieve the unprotected data). 2816 B.2. Simple Mechanism, Single Buffer (Again) 2818 To illustrate a slight variation on the simplest possible case, 2819 assume that everything is as in the previous scenario except that 2820 the "SE" calls are not used. 2822 The following parameter bundle uses and defaults would therefore be 2823 specified in the relevant IDUP mechanism document. 2825 Mech_Specific_Info 2826 - NOT USED (the only acceptable input, therefore, is NULL) 2828 Idu_Sensitivity 2829 - NOT USED (the only acceptable input, therefore, is NULL) 2831 Service_Creation_Info 2832 - NOT USED (the only acceptable input, therefore, is NULL) 2834 Service_Verification_Info 2835 - NOT USED (the only acceptable input, therefore, is NULL) 2837 Quality 2838 - the qop_algs parameter must be supported, with a suitable 2839 DEFAULT value specified; 2840 - suitable DEFAULT values for validity, policy_id, and 2841 allow_policy_mapping must be specified (it may be an 2842 implementation option as to whether these parameters are 2843 explicitly modifiable by the calling application, or whether 2844 NULLs are the only acceptable input) 2846 Idu_Information 2847 - the idu_type parameter must have a value representing a suitable 2848 IDU type (for example, in PEM a value representing the string 2849 "RFC822" or some other valid "Content-Domain" would be used), 2850 with a suitable DEFAULT value specified; 2851 - the idu_title parameter is NOT USED (the only acceptable input, 2852 therefore, is NULL) 2854 Adams Document Expiration: 25 Sept. 1997 49 2856 Prot_Information 2857 - the originator_name and idu_type (in Idu_Information) parameters 2858 are read from the encapsulating information and output by 2859 IDUP_Start_Unprotect; 2860 - all other parameters are NOT USED (and therefore NULL) 2862 Special_Conditions 2863 - NOT USED (the only acceptable input, therefore, is NULL) 2865 Target_Info 2866 - this bundle is used as described in IDUP; no DEFAULT values are 2867 specified 2869 General_Service_Data 2870 - the unencapsulated_token parameter is used if 2871 encapsulation_request is FALSE; 2872 - the minor_status parameter is used to return minor status values 2873 as specified by the mechanism document 2875 Prot_Service 2876 - the prot_service_type parameter may have a value of "1" 2877 ("perform unsolicited service") or NULL (which specifies the 2878 DEFAULT value of "1"); 2879 - the service_id parameter must have a value representing 2880 "PER_CONF" or "PER_DOA"; 2881 - the parameters Service_Creation_Info, service_to, 2882 Service_Verification_Info, and service_verification_info_id are 2883 NOT USED (and therefore NULL) 2885 Unprot_Service 2886 - the unprot_service_type parameter will always have a value of 2887 "1" ("receive unsolicited service"); 2888 - the service_id parameter will have a value representing 2889 "REC_CONF" or "REC_DOA"; 2890 - the parameters service_verification_info_id, 2891 Service_Verification_Info, service_to, and 2892 Service_Creation_Info, are NOT USED (and therefore NULL) 2894 Assuming that the calling application has only a single buffer of 2895 data to protect/unprotect, the following sequence of operations must 2896 be performed by the sender and receivers (subsequent to environment 2897 establishment). 2899 SENDER (any parameters not listed below are given the value NULL): 2901 Set 2902 env_handle = environment handle in use; 2903 encapsulation_request = TRUE; 2904 single_idu_buffer = data buffer; 2905 Target_Info.targ_names = receiver names; 2906 P_Services.Prot_Service_1.service_id = PER_CONF; 2907 P_Services.Prot_Service_2.service_id = PER_DOA; 2909 Adams Document Expiration: 25 Sept. 1997 50 2911 Call 2912 IDUP_Start_Protect() with above input parameters 2913 Check 2914 major_status. If not GSS_S_COMPLETE, check 2915 minor_status, 2916 Target_Info.bad_targ_names / Target_Info.bad_targ_status, 2917 P_Services.Prot_Service_1.General_Service_Data.minor_status, 2918 P_Services.Prot_Service_2.General_Service_Data.minor_status 2919 (as required) for more detailed information. 2921 Send 2922 Output parameter pidu_buffer to receiver. 2924 RECEIVER (any parameters not listed below are given the value NULL): 2926 Set 2927 env_handle = environment handle in use; 2928 single_pidu_buffer = received data buffer; 2930 Call 2931 IDUP_Start_Unprotect() with above input parameters 2932 Check 2933 major_status. If not GSS_S_COMPLETE, check 2934 minor_status, 2935 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2936 R_Services.Unprot_Service_2.General_Service_Data.minor_status 2937 (as required) for more detailed information 2939 Utilize 2940 R_Services.Unprot_Service_1/2.service_id, 2941 (to determine which services were applied by the originator) 2942 R_Services.Unprot_Service_1/2.Quality, 2943 (to determine the corresponding qualities of the services) 2944 Prot_Information.originator_name, 2945 (to determine the name of the originator) 2946 single_idu_buffer 2947 (to retrieve the unprotected data). 2949 Adams Document Expiration: 25 Sept. 1997 51 2951 B.3. Simple Mechanism, Multiple Buffers 2953 To illustrate the next step up in complexity, consider the use of the 2954 simple IDUP mechanism described in B.2 above with multiple data 2955 buffers. In particular, consider the case in which a large data file 2956 is to be signed. For this example, assume that the calling 2957 application does not wish to use encapsulation. 2959 Note that the parameter bundle uses and defaults are as specified in 2960 B.2. above. 2962 SENDER (any parameters not listed below are given the value NULL): 2964 Set 2965 env_handle = environment handle in use; 2966 encapsulation_request = FALSE; 2967 P_Services.Prot_Service.service_id = PER_DOA; 2969 Call 2970 IDUP_Start_Protect() with above input parameters 2971 Check 2972 major_status. If not GSS_S_COMPLETE, check 2973 minor_status, 2974 P_Services.Prot_Service.General_Service_Data.minor_status 2975 (as required) for more detailed information. 2977 For each buffer of input data: 2978 Set 2979 input_buffer = buffer 2980 Call 2981 IDUP_Protect() with above input parameter 2982 Check 2983 major_status. If not GSS_S_COMPLETE, check 2984 minor_status 2986 Call 2987 IDUP_End_Protect() 2988 Check 2989 major_status. If not GSS_S_COMPLETE, check 2990 minor_status, 2991 P_Services.Prot_Service.General_Service_Data.minor_status 2992 (as required) for more detailed information. 2994 Send 2995 P_Services.Prot_Service.General_Service_Data.unencapsulated_token, 2996 and the file for which the signature was calculated (if required), 2997 to receiver. 2999 Adams Document Expiration: 25 Sept. 1997 52 3001 RECEIVER (any parameters not listed below are given the value NULL): 3003 Set 3004 env_handle = environment handle in use; 3005 R_Services.Unprot_Service_1.General_Service_Data. 3006 unencapsulated_token = received unencapsulated token; 3008 Call 3009 IDUP_Start_Unprotect() with above input parameters 3010 Check 3011 major_status. If not GSS_S_COMPLETE, check 3012 minor_status, 3013 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 3014 (as required) for more detailed information 3016 For each buffer of input data: 3017 Set 3018 input_buffer = buffer 3019 Call 3020 IDUP_Unprotect() with above input parameter 3021 Check 3022 major_status. If not GSS_S_COMPLETE, check 3023 minor_status 3025 Call 3026 IDUP_End_Unprotect() 3027 Check 3028 major_status. If not GSS_S_COMPLETE, check 3029 minor_status, 3030 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 3031 (as required) for more detailed information. 3033 Utilize 3034 R_Services.Unprot_Service_1.service_id, 3035 (to determine which service was applied by the originator; note 3036 that Unprot_Service_2 will have NULL in unprot_service_type 3037 to indicate that it is not used) 3038 R_Services.Unprot_Service_1.Quality, 3039 (to determine the corresponding quality of the service) 3040 Prot_Information.originator_name, (from IDUP_Start_Unprotect) 3041 (to determine the name of the signer) 3042 major_status (from IDUP_End_Unprotect) 3043 (to determine pass/fail status of signature verification). 3045 Adams Document Expiration: 25 Sept. 1997 53 3047 B.4. More Sophisticated Mechanism, Small Application Buffers 3049 To illustrate a higher level of complexity, consider the use of a 3050 more sophisticated IDUP mechanism and a calling application with 3051 small data buffers. In particular, consider the case in which a very 3052 small e-mail message is to be encrypted for a relatively large 3053 receiver list (R), some subset of whom (r) will be asked to send 3054 proofs of receipt of the message to some other subset (L) (which 3055 includes the originator). So that the example is not unnecessarily 3056 complicated, assume again that the originating application uses 3057 encapsulation. 3059 The uses and defaults for the various parameter bundles for this 3060 mechanism would be specified in the relevant IDUP mechanism document 3061 as follows. 3063 Mech_Specific_Info 3064 - NOT USED (the only acceptable input, therefore, is NULL) 3066 Idu_Sensitivity 3067 - NOT USED (the only acceptable input, therefore, is NULL) 3069 Service_Creation_Info 3070 - used to create "proof of delivery" evidence (but actual 3071 structure is opaque to calling application) 3073 Service_Verification_Info 3074 - used to verify "proof of delivery" evidence (but actual 3075 structure is opaque to calling application) 3077 Quality 3078 - the qop_algs parameter must be supported, with a suitable 3079 DEFAULT value specified; 3080 - suitable DEFAULT values for validity, policy_id, and 3081 allow_policy_mapping must be specified (it may be an 3082 implementation option as to whether these parameters are 3083 explicitly modifiable by the calling application, or whether 3084 NULLs are the only acceptable input) 3086 Idu_Information 3087 - the idu_type parameter must have a value representing a suitable 3088 IDU type, with a suitable DEFAULT value specified; 3089 - the idu_title parameter must have a value representing a 3090 suitable IDU title, with a suitable DEFAULT value specified 3092 Prot_Information 3093 - the originator_name, protection_time, and idu_type / idu_title 3094 (in Idu_Information) parameters are read from the contained 3095 header information and output by IDUP_Start_Unprotect; 3097 Special_Conditions 3098 - the parameter prot_oper_id is NOT USED (the only acceptable 3099 input, therefore, is NULL); 3100 - trusted or untrusted time may be selected by the calling 3101 application, with a suitable DEFAULT value specified 3103 Adams Document Expiration: 25 Sept. 1997 54 3105 Target_Info 3106 - this bundle is used as described in IDUP; no DEFAULT values are 3107 specified 3109 General_Service_Data 3110 - the unencapsulated_token parameter is used if 3111 encapsulation_request is FALSE; 3112 - the minor_status parameter is used to return minor status values 3113 as specified by the mechanism document 3115 Prot_Service 3116 - the prot_service_type parameter may have a value of "1" 3117 ("perform unsolicited service"), "2" ("perform solicited 3118 service"), "3" (perform service solicitation), or NULL (which 3119 specifies the DEFAULT value of "1"); 3120 - the service_id parameter must have a value representing 3121 "PER_CONF", "PER_DOA", "PER_POO", or "PER_POD"; 3122 - the parameters Service_Creation_Info, service_to, 3123 Service_Verification_Info, and service_verification_info_id are 3124 used when required by the IDUP operation 3126 Unprot_Service 3127 - the unprot_service_type parameter may have a value of "1" 3128 ("receive unsolicited service"), "2" ("receive solicited 3129 service"), or "3" (receive service solicitation); 3130 - the service_id parameter will have a value representing 3131 "REC_CONF", "REC_DOA", "REC_POO", or "REC_POD"; 3132 - the parameters service_verification_info_id, 3133 Service_Verification_Info, service_to, and 3134 Service_Creation_Info, are used when required by the IDUP 3135 operation 3137 SENDER (any parameters not listed below are given the value NULL): 3139 Set 3140 env_handle = environment handle in use; 3141 Idu_Information.idu_type = value for "e-mail document"; 3142 Idu_Information.idu_title = "Contract 1234"; 3143 Special_Conditions.use_trusted_time = TRUE; 3144 encapsulation_request = TRUE; 3145 single_idu_buffer = very small e-mail message; 3146 Target_Info.targ_names = receiver names (R); 3147 Prot_Service_1.prot_service_type = "1"; 3148 Prot_Service_1.service_id = PER_CONF; 3149 Prot_Service_2.prot_service_type = "3"; 3150 Prot_Service_2.service_id = PER_POD; 3151 Prot_Service_2.General_Service_Data.Target_Info.targ_names 3152 = "receipts from" list (r); 3153 Prot_Service_2.service_to = "receipts to" list (L); 3154 P_Services.Prot_Service_1 = Prot_Service_1; 3155 P_Services.Prot_Service_2 = Prot_Service_2; 3157 Adams Document Expiration: 25 Sept. 1997 55 3159 Call 3160 IDUP_Start_Protect() with above input parameters 3161 Check 3162 major_status. If not GSS_S_COMPLETE, 3163 while major_status == GSS_S_CONTINUE_NEEDED 3164 Save 3165 pidu_buffer, 3166 Call 3167 IDUP_Start_Protect() (to get next portion of pidu_buffer) 3168 Check 3169 major_status, 3170 minor_status, 3171 Target_Info.bad_targ_names / Target_Info.bad_targ_status, 3172 P_Services.Prot_Service_1.General_Service_Data.minor_status, 3173 P_Services.Prot_Service_2.General_Service_Data.minor_status 3174 (as required) for more detailed information. 3176 Save 3177 Prot_Service_2.Service_Verification_Info, 3178 Prot_Service_2.service_verification_info_id 3180 Send 3181 All saved buffers of pidu_buffer to receiver list (R). 3183 RECEIVER (ON RECEIVER LIST (R)): 3184 (any parameters not listed below are given the value NULL) 3186 Set 3187 env_handle = environment handle in use; 3188 partial_pidu_buffer = initial buffer of received p-idu; 3190 Call 3191 IDUP_Start_Unprotect() with above input parameters 3192 While major_status == IDUP_S_MORE_PIDU_NEEDED, 3193 Set 3194 partial_pidu_buffer = next buffer of p-idu 3195 Call 3196 IDUP_Start_Unprotect() 3197 Check 3198 major_status, 3199 minor_status, 3200 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 3201 R_Services.Unprot_Service_2.General_Service_Data.minor_status, 3202 (as required) for more detailed information 3204 Save 3205 initial_idu_buffer (if non-empty) 3207 Adams Document Expiration: 25 Sept. 1997 56 3209 Set 3210 input_buffer = remaining p-idu buffer 3211 Call 3212 IDUP_Unprotect() with above input parameter 3213 Check 3214 major_status. If not GSS_S_COMPLETE, check 3215 minor_status 3216 Save 3217 output_buffer 3219 Call 3220 IDUP_End_Unprotect() 3221 Check 3222 major_status. If not GSS_S_COMPLETE, check 3223 minor_status, 3224 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 3225 R_Services.Unprot_Service_2.General_Service_Data.minor_status, 3226 (as required) for more detailed information. 3228 Utilize 3229 R_Services.Unprot_Service_1/2.service_id, 3230 (to determine which services were applied by the originator) 3231 R_Services.Unprot_Service_1/2.Quality, 3232 (to determine the corresponding qualities of the service) 3233 Prot_Information.originator_name/protection_time and 3234 Prot_Information.Idu_Information.idu_type/idu_title, 3235 (from IDUP_Start_Unprotect) (to determine originator info.) 3236 R_Services.Unprot_Service_2.General_Service_Data.Target_Info. 3237 targ.names, (to determine if rec. is in "receipts from" (r)) 3238 Service_Verification_Info/service_verification_info_id 3239 (to determine if receiver is in "receipts to" list (L)) 3241 If receiver is in "receipts from" list (r) 3242 Save 3243 R_Services.Unprot_Service_2.service_to, 3244 R_Services.Unprot_Service_2.Service_Creation_Info 3246 If receiver is in "receipts to" list (L) 3247 Save 3248 Service_Verification_Info, 3249 service_verification_info_id 3251 Adams Document Expiration: 25 Sept. 1997 57 3253 RECEIVER (ON "RECEIPTS FROM" LIST (r)): 3254 (procedure to generate receipt) 3256 Set 3257 env_handle = environment handle in use; 3258 Target_Info.targ_names = service_to 3259 Prot_Service_1.prot_service_type = "2"; 3260 Prot_Service_1.service_id = "PER_POD"; 3261 Prot_Service_1.Service_Creation_Info = Service_Creation_Info; 3262 P_Services.Prot_Service_1 = Prot_Service_1 3264 Call 3265 IDUP_Start_Protect() with above input parameters 3266 Check 3267 major_status. If not GSS_S_COMPLETE, check 3268 minor_status, 3269 P_Services.Prot_Service_1.General_Service_Data.minor_status 3270 (as required) for more detailed information. 3272 Send 3273 pidu_buffer to "receipts to" list (L) 3275 RECEIVER (ON "RECEIPTS TO" LIST (L)): 3276 (procedure to process received receipt) 3278 Set 3279 env_handle = environment handle in use; 3280 single_pidu_buffer = received p-idu buffer (if it fits in a single 3281 buffer; otherwise use partial_pidu_buffer and make multiple 3282 calls, as above) 3284 Call 3285 IDUP_Start_Unprotect() with above input parameters 3286 If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED 3287 Utilize 3288 R_Services.Unprot_Service_1.service_verification_info.id 3289 (to assist in locating necessary Service_Verification_Info) 3290 Set 3291 R_Services.Unprot_Service_1.Service_Verification_Info 3292 = Service_Verification_Info 3293 Call 3294 IDUP_Start_Unprotect() with above input parameters 3295 Check 3296 major_status, 3297 minor_status, 3298 R_Services.Unprot_Service_1.General_Service_Data.minor_status 3299 (as required) for more detailed information. 3301 Utilize 3302 R_Services.Unprot_Service_1.service_id, 3303 (to determine that this is a "proof of delivery" evidence) 3304 R_Services.Unprot_Service_1.Quality, 3305 Prot_Information.originator_name, (for evidence generator info.) 3306 major_status (to determine pass/fail status of evi. verif.). 3308 Adams Document Expiration: 25 Sept. 1997 58