idnits 2.17.1 draft-ietf-cat-idup-gss-06.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-18) 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 3139 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-1508]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 541 has weird spacing: '...ish_Env esta...' == Line 550 has weird spacing: '...Protect begi...' == Line 556 has weird spacing: '...Protect pro...' == Line 561 has weird spacing: '...protect end ...' == Line 562 has weird spacing: '...protect unpro...' == (4 more instances...) -- 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) == Missing Reference: 'APPLICATION 0' is mentioned on line 2215, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'MSP' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Obsolete normative reference: RFC 1508 (Obsoleted by RFC 2078) -- No information found for draft-ietf-cat-gssv2-0x - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'GSSv2' -- 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: 11 errors (**), 0 flaws (~~), 9 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Draft C. Adams, Nortel 2 draft-ietf-cat-idup-gss-06.txt Nov. 26, 1996 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-1508] 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. 56 Adams Document Expiration: 26 May 1997 1 58 As with RFC-1508, this IDUP-GSS-API definition provides security 59 services to callers in a generic fashion, supportable with a range of 60 underlying mechanisms and technologies and hence allowing source- 61 level portability of applications to different environments. This 62 specification defines IDUP-GSS-API services and primitives at a level 63 independent of underlying mechanism and programming language environ- 64 ment, and is to be complemented by other, related specifications: 66 - documents defining specific parameter bindings for particular 67 language environments; 68 - documents defining token formats, protocols, and procedures to 69 be implemented in order to realize IDUP-GSS-API services atop 70 particular security mechanisms. 72 TABLE OF CONTENTS 73 1. IDUP-GSS-API Characteristics and Concepts .................. 3 74 1.1. IDUP-GSS-API Constructs .................................. 5 75 1.1.1. Credentials ............................................ 5 76 1.1.2. Tokens ................................................. 5 77 1.1.3. Security Environment ................................... 5 78 1.1.4. Mechanism Types ........................................ 5 79 1.1.5. Naming ................................................. 5 80 1.1.6. Channel Bindings ....................................... 6 81 1.2. IDUP-GSS-API Features and Issues ......................... 6 82 1.2.1. Status Reporting ....................................... 6 83 1.2.2. Per-IDU Security Service Availability .................. 7 84 1.2.3. Per-IDU Replay Detection and Sequencing ................ 7 85 1.2.4. Quality of Protection .................................. 7 86 1.2.5. The Provision of Time .................................. 10 87 2. Interface Descriptions ..................................... 10 88 2.1. Credential management calls .............................. 11 89 2.1.1. Relationship to GSS-API ................................ 11 90 2.2. Environment-level calls .................................. 12 91 2.2.1. Relationship to GSS-API ................................ 12 92 2.2.2. IDUP_Establish_Env call ................................ 13 93 2.2.3. IDUP_Abolish_Env call .................................. 15 94 2.2.4. IDUP_Inquire_Env call .................................. 16 95 2.3. Per-IDU calls ............................................ 17 96 2.3.1. Relationship to GSS-API ................................ 17 97 2.3.2. Parameter Bundles ...................................... 17 98 2.3.3. IDUP_Start_Protect ..................................... 21 99 2.3.4. IDUP_Protect ........................................... 24 100 2.3.5. IDUP_End_Protect ....................................... 25 101 2.3.7. IDUP_Start_Unprotect ................................... 27 102 2.3.8. IDUP_Unprotect ......................................... 30 103 2.3.9. IDUP_End_Unprotect ..................................... 31 104 2.4. Special-Purpose calls .................................... 35 105 2.4.1. Relationship to GSS-API ................................ 35 106 2.4.5. IDUP_Form_Complete_PIDU ................................ 35 107 2.5. Support calls ............................................ 37 108 2.5.1. Relationship to GSS-API ................................ 37 109 2.5.2. IDUP_Parse_token call .................................. 37 110 2.5.3. IDUP_Get_Policy_Info ................................... 38 112 Adams Document Expiration: 26 May 1997 2 114 3. Related Activities ......................................... 40 115 4. Acknowledgments ............................................ 40 116 5. Security Considerations .................................... 40 117 6. References ........................................... 41 118 7. Author's Address ........................................... 41 119 Appendix A, ................................................... 42 120 Appendix B .................................................... 43 122 1. IDUP-GSS-API Characteristics and Concepts 124 The paradigm within which IDUP-GSS-API operates is as follows. An 125 IDUP-GSS-API caller is any application which works with IDUs, calling 126 on IDUP-GSS-API in order to protect its IDUs with services such as 127 data origin authentication with integrity (DOA), confidentiality with 128 integrity (CONF), and/or support for non-repudiation (e.g., evidence 129 generation, where "evidence" is information that either by itself or 130 when used in conjunction with other information is used to establish 131 proof about an event or action (note: the evidence itself does not 132 necessarily prove truth or existence of something, but contributes to 133 establish proof) -- see [ISO/IEC] for fuller discussion regarding 134 evidence and its role in various types of non-repudiation). An 135 IDUP-GSS-API caller passes an IDU to, and accepts a token from, its 136 local IDUP-GSS-API implementation, transferring the resulting 137 protected IDU (P-IDU) to a peer or to any storage medium. When a 138 P-IDU is to be "unprotected", it must be passed to an IDUP-GSS-API 139 implementation for processing. The security services available 140 through IDUP-GSS-API in this fashion are implementable over a range 141 of underlying mechanisms based on secret-key and/or public-key 142 cryptographic technologies. 144 During the protection operation, the input IDU buffers may be 145 modified (for example, the data may be encrypted or encoded in some 146 way) or may remain unchanged. In any case, the result is termed a 147 "M-IDU" (Modified IDU) in order to distinguish it from the original 148 IDU. Depending on the desire of the calling application and the 149 capabilities of the underlying IDUP mechanism, the token produced by 150 the protection processing may or may not encapsulate the M-IDU. 151 Thus, the P-IDU may be the token alone (if encapsulation is done) or 152 may be the logical concatenation of the token and the M-IDU (if 153 encapsulation is not done). In the latter case, the protecting 154 application may choose whatever method it wishes to concatenate or 155 combine the token and the M-IDU into a P-IDU, provided the 156 unprotecting application knows how to de-couple the P-IDU back into 157 its component parts prior to calling the IDUP unprotection set of 158 functions. 160 The IDUP-GSS-API separates the operation of initializing a security 161 environment (the IDUP_Establish_Env() call) from the operations of 162 providing per-IDU protection, for IDUs subsequently protected in 163 conjunction with that environment. Per-IDU protection and 164 unprotection calls provide DOA, CONF, evidence, and other services, 165 as requested by the calling application and as supported by the 166 underlying mechanism. 168 Adams Document Expiration: 26 May 1997 3 170 The following paragraphs provide an example illustrating the 171 dataflows involved in the use of the IDUP-GSS-API by the sender and 172 receiver of a P-IDU in a mechanism-independent fashion. The example 173 assumes that credential acquisition has already been completed by 174 both sides. Furthermore, the example does not cover all possible 175 options available in the protection/unprotection calls. 177 The sender first calls IDUP_Establish_Env() to establish a 178 security environment. Then, for the IDU to be protected the 179 sender calls IDUP_Start_Protect(), IDUP_Protect() for each buffer 180 of data, and IDUP_End_Protect() to complete the IDU protection. 181 The resulting P-IDU, which may (depending on whether or not 182 encapsulation was chosen/available) be either the token itself 183 or the logical concatenation of the token and the M-IDU, is now 184 ready to be sent to the target. The sender then calls 185 IDUP_Abolish_Env() to flush all environment-specific information. 187 The receiver first calls IDUP_Establish_Env() to establish a 188 security environment in order to unprotect the P-IDU. Then, for 189 the received P-IDU the receiver calls IDUP_Start_Unprotect(), 190 IDUP_Unprotect() for each buffer of data, and IDUP_End_Unprotect() 191 to complete the P-IDU unprotection. The receiver then calls 192 IDUP_Abolish_Env() to flush all environment-specific information. 194 It is important to note that absolutely no synchronization is implied 195 or expected between the data buffer size used by the sender as input 196 to the protection calls, the data buffer size used by the receiver as 197 input to the unprotection calls, and the block sizes required by the 198 underlying protection algorithms (integrity and confidentiality). 199 All these sizes are meant to be independent; furthermore, the data 200 buffer sizes used for the protection and unprotection calls are 201 purely a function of the local environment where the calls are made. 203 The IDUP-GSS-API design assumes and addresses several basic goals, 204 including the following. 206 Mechanism independence: The IDUP-GSS-API defines an interface to 207 cryptographically implemented security services at a generic level 208 which is independent of particular underlying mechanisms. For 209 example, IDUP-GSS-API-provided services can be implemented by 210 secret-key technologies or public-key approaches. 212 Protocol environment independence: The IDUP-GSS-API is independent 213 of the communications protocol suites which may be used to 214 transfer P-IDUs, permitting use in a broad range of protocol 215 environments. 217 Protocol association independence: The IDUP-GSS-API's security 218 environment construct has nothing whatever to do with 219 communications protocol association constructs, so that 220 IDUP-GSS-API services can be invoked by applications, wholly 221 independent of protocol associations. 223 Adams Document Expiration: 26 May 1997 4 225 Suitability for a range of implementation placements: IDUP-GSS-API 226 clients are not constrained to reside within any Trusted Computing 227 Base (TCB) perimeter defined on a system where the IDUP-GSS-API is 228 implemented; security services are specified in a manner suitable 229 for both intra-TCB and extra-TCB callers. 231 1.1. IDUP-GSS-API Constructs 233 This section describes the basic elements comprising the 234 IDUP-GSS-API. 236 1.1.1. Credentials 238 Credentials in IDUP-GSS-API are to be understood and used as 239 described in GSS-API [RFC-1508]. 241 1.1.2. Tokens 243 Tokens in IDUP-GSS-API are to be understood and used as described in 244 GSS-API [RFC-1508] with the exception that there are no context-level 245 tokens generated by IDUP-GSS-API. The IDUP-GSS-API token 246 may (depending on the underlying mechanism) encapsulate the M-IDU or 247 may be logically concatenated with M-IDU prior to transfer to a 248 target; furthermore, for some evidence services the token may be sent 249 independently of any other data transfer. 251 1.1.3. Security Environment 253 The "security environment" in IDUP-GSS-API is entirely different from 254 the concept of security contexts used in GSS-API [RFC-1508]. Here, a 255 security environment exists within a calling application (that is, it 256 is purely local to the caller) for the purpose of protecting or 257 unprotecting one or more IDUs using a particular caller credential or 258 set of credentials. In GSS-API, on the other hand, a security 259 context exists between peers (the initiator and the target) for the 260 purpose of protecting, in real time, the data that is exchanged 261 between them. Although they are different concepts, the env_handle 262 in IDUP-GSS-API is similar to the context_handle in GSS-API in that 263 it is a convenient way of tying together the entire process of 264 protecting or unprotecting one or more IDUs using a particular 265 underlying mechanism. As with the GSS-API security contexts, a 266 caller can initiate and maintain multiple environments using the same 267 or different credentials. 269 1.1.4. Mechanism Types 271 Mechanism types in IDUP-GSS-API are to be understood and used as 272 described in GSS-API [RFC-1508]. 274 1.1.5. Naming 276 Naming in IDUP-GSS-API is to be understood and used as described in 277 GSS-API [RFC-1508]. 279 Adams Document Expiration: 26 May 1997 5 281 1.1.6. Channel Bindings 283 The concept of channel bindings discussed in GSS-API [RFC-1508] is 284 not relevant to the IDUP-GSS-API. 286 1.2. IDUP-GSS-API Features and Issues 288 This section describes aspects of IDUP-GSS-API operations and of the 289 security services which the IDUP-GSS-API provides. It also provides 290 commentary on design issues. 292 1.2.1. Status Reporting 294 Status reporting in IDUP-GSS-API is to be understood and used as 295 described in GSS-API [RFC-1508], with the addition of the following 296 IDUP-GSS-API major status codes. 298 As with GSS-API, minor_status codes, which provide more detailed 299 status information than major_status codes, and which may include 300 status codes specific to the underlying security mechanism, are not 301 specified in this document. 303 Table 1: IDUP-GSS-API Major Status Codes 305 Fatal Error Codes 307 IDUP_S_BAD_TARG_INFO all target information is invalid or 308 unsuitable for IDU protection 310 IDUP_S_BAD_DOA_KEY DOA key has expired or been revoked 312 IDUP_S_BAD_KE_KEY key used for key establishment between 313 orig. and targ. has exp. or been revoked 315 IDUP_S_BAD_ENC_IDU encrypted IDU is defective/invalid 317 IDUP_S_INCOMPLETE 318 there is not enough info. in token for P-IDU verification 320 IDUP_S_SERV_VERIF_INFO_NEEDED 321 the Service_Verification_Info parameter bundle is required 323 IDUP_S_SERVICE_UNAVAIL mech. does not support requested service 325 IDUP_S_REQ_TIME_SERVICE_UNAVAIL 326 the time service requested is not avail. in this environment 328 IDUP_S_INAPPROPRIATE_CRED 329 the credentials supplied cannot be used to unprotect P-IDU 331 Adams Document Expiration: 26 May 1997 6 333 IDUP_S_NO_ENV no environment recognized for env_handle 335 IDUP_S_NO_MATCH Service_Verification_Info and input token 336 do not match 338 IDUP_S_UNKNOWN_OPER_ID requested operation id. is unsupported 340 Informatory Status Codes 342 IDUP_S_ENCAPSULATION_UNAVAIL 343 encapsulation of M-IDU into pidu_buffer is not supported 345 IDUP_S_MORE_PIDU_NEEDED 346 more p-idu data is needed for IDUP_Start_Unprotect() 348 IDUP_S_MORE_DATA_NEEDED 349 more data is needed for protection or unprotection 351 1.2.2. Per-IDU Security Service Availability 353 Per-IDU security service availability in IDUP-GSS-API is to be 354 understood and used as described in GSS-API [RFC-1508], with the 355 exception that any combination of services requested by the calling 356 application and supported by the underlying mechanism can be applied 357 simultaneously to any IDU. 359 GSS-API callers desiring per-message security services should check 360 the relevant service OBJECT IDs at environment establishment time to 361 ensure that what is available in the established environment is 362 suitable for their security needs. 364 1.2.3. Per-IDU Replay Detection and Sequencing 366 The concept of per-IDU replay detection and sequencing discussed 367 in GSS-API [RFC-1508] is not relevant to the IDUP-GSS-API. 369 1.2.4. Quality of Protection 371 The concept of QOP control in IDUP-GSS-API is to be understood 372 essentially as described in GSS-API [RFC-1508]. However, the actual 373 description and use of the QOP parameter is given as follows. 375 Adams Document Expiration: 26 May 1997 7 377 The qop_algs parameter for IDUP is defined to be a 32-bit unsigned 378 integer with the following bit-field assignments: 380 31 (MSB) (LSB) 0 381 ---------------------------------------------- 382 | U(19) | TS(5) | IA(4) | MA(4) | 383 ---------------------------------------------- 385 where 387 U is a 19-bit Unspecified field (available for future 388 use/expansion) -- must be set to zero; 390 TS is a 5-bit Type Specifier (a semantic qualifier whose value 391 specifies the type of algorithm which may be used to protect the 392 corresponding IDU -- see below for details); 394 IA is a 4-bit field enumerating Implementation-specific 395 Algorithms; and 397 MA is a 4-bit field enumerating Mechanism-defined Algorithms. 399 The interpretation of the qop_algs parameter is as follows. The MA 400 field is examined first. If it is non-zero then the algorithm used 401 to protect the IDU is the mechanism-specified algorithm corresponding 402 to that integer value. 404 If MA is zero then IA is examined. If this field value is non-zero 405 then the algorithm used to protect the IDU is the implementation- 406 specified algorithm corresponding to that integer value. Note that 407 use of this field may hinder portability since a particular value may 408 specify one algorithm in one implementation of the mechanism and may 409 not be supported or may specify a completely different algorithm in 410 another implementation of the mechanism. 412 Finally, if both MA and IA are zero then TS is examined. A value of 413 zero for TS specifies the default algorithm for the established 414 mechanism. A non-zero value for TS corresponds to a particular 415 algorithm qualifier and selects any algorithm from the mechanism 416 specification which satisfies that qualifier (which actual algorithm 417 is selected is an implementation choice; the calling application need 418 not be aware of the choice made). 420 The following TS values (i.e., algorithm qualifiers) are specified; 421 other values may be added in the future. 423 When qop_algs is used to select a confidentiality algorithm: 425 00000 (0) = default confidentiality algorithm 426 00001 (1) = IDUP_SYM_ALG_STRENGTH_STRONG 427 00010 (2) = IDUP_SYM_ALG_STRENGTH_MEDIUM 428 00011 (3) = IDUP_SYM_ALG_STRENGTH_WEAK 429 11111 (31) = IDUP_NO_CONFIDENTIALITY 431 Adams Document Expiration: 26 May 1997 8 433 When qop_algs is used to select a DOA/integrity algorithm: 435 00000 (0) = default integrity algorithm 436 00001 (1) = IDUP_INT_ALG_DIG_SIGNATURE 437 (integrity provided through a digital signature) 438 00010 (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE 439 (integrity without a dig. sig. (e.g., with a MAC)) 440 11111 (31) = IDUP_NO_INTEGRITY 442 Clearly, qualifiers such as strong, medium, and weak are debatable 443 and likely to change with time, but for the purposes of this version 444 of the specification we define these terms as follows. A confiden- 445 tiality algorithm is "weak" if the effective key length of the cipher 446 is 40 bits or less; it is "medium-strength" if the effective key 447 length is strictly between 40 and 80 bits; and it is "strong" if the 448 effective key length is 80 bits or greater. ("Effective key length" 449 describes the computational effort required to break a cipher using 450 the best-known cryptanalytic attack against that cipher.) 452 A five-bit TS field allows up to 30 qualifiers for each of confiden- 453 tiality and integrity (since "0" is reserved for "default" and "31" 454 is reserved for "none", as shown above). This document specifies 455 three for confidentiality and two for integrity, leaving a lot of 456 room for future specification. Suggestions of qualifiers such as 457 "fast", "medium-speed", and "slow" have been made, but such terms are 458 difficult to quantify (and in any case are platform- and processor- 459 dependent), and so have been left out of this initial specification. 460 The intention is that the TS terms be quantitative, environment- 461 independent qualifiers of algorithms, as much as this is possible. 463 Use of the qop_algs parameter as defined above is ultimately meant to 464 be as follows. 466 - TS values are specified at the IDUP-GSS-API level and are 467 therefore portable across mechanisms. Applications which know 468 nothing about algorithms are still able to choose "quality" of 469 protection for their message tokens. 471 - MA values are specified at the mechanism level and are therefore 472 portable across implementations of a mechanism. 474 - IA values are specified at the implementation level (in user 475 documentation, for example) and are therefore typically non- 476 portable. An application which is aware of its own mechanism 477 implementation and the mechanism implementation of its intended 478 P-IDU recipient, however, is free to use these values since they 479 will be perfectly valid and meaningful for protecting IDUs 480 between those entities. 482 The receiver of a P-IDU must pass back to its calling application 483 (in IDUP_Start_Unprotect()) a qop_algs parameter with all relevant 484 fields set. For example, if triple-DES has been specified by a 485 mechanism as algorithm 8, then a receiver of a triple-DES-protected 486 P-IDU must pass to its application (TS=1, IA=0, MA=8). In this way, 487 the application is free to read whatever part of the qop_algs 488 parameter it understands (TS or IA/MA). 490 Adams Document Expiration: 26 May 1997 9 492 1.2.5. The Provision of Time 494 IDUP mechanisms should make provision in their protocols for the 495 carrying of time information from originator to target(s). That is, 496 a target (a legitimate recipient) should get some indication during 497 unprotection regarding the time at which the protection operation 498 took place. This is particularly important if the mechanism offers 499 non-repudiation services because in some cases evidence verification 500 may only be achievable if the time at which the evidence was 501 generated is known. 503 Depending upon the platform and resources available to the 504 implementation, an IDUP environment may have access to a source of 505 trusted (secure) time, untrusted (local) time, both kinds of time, or 506 no time. OBJECT IDs indicating such availability are returned by the 507 IDUP_Establish_Env() call. When starting a protection operation, an 508 application may specify which time services it wishes to have applied 509 to the IDU. Similarly, for unprotection, an application may specify 510 which kind of time (if any) to consult when the validity of the P-IDU 511 is to be established. Specifying both kinds of time is interpreted 512 to mean that the calling application does not care which kind of time 513 is used. 515 2. Interface Descriptions 517 This section describes the IDUP-GSS-API's operational interface, 518 dividing the set of calls offered into five groups. Credential 519 management calls are related to the acquisition and release of 520 credentials by API callers. Environment-level calls are related to 521 the management of the security environment by an API caller. Per-IDU 522 calls are related to the protection or unprotection of individual 523 IDUs in established security environments. Special-purpose calls 524 deal with unusual or auxiliary evidence generation/verification 525 requirements. Support calls provide extra functions useful to 526 IDUP-GSS-API callers. Table 2 groups and summarizes the calls in 527 tabular fashion (an asterisk marks the calls which are identical to 528 the GSS-API specification). 530 Table 2: IDUP-GSS-API Calls 532 CREDENTIAL MANAGEMENT 534 * GSS_Acquire_cred acquire credentials for use 535 * GSS_Release_cred release credentials after use 536 * GSS_Inquire_cred display information about credentials 537 * GSS_Add_cred add credential info. (see [GSSv2]) 539 ENVIRONMENT-LEVEL CALLS 541 IDUP_Establish_Env establish IDUP environment (to protect and 542 unprotect IDUs) 543 IDUP_Abolish_Env abolish env. when no longer needed 544 IDUP_Inquire_Env indicate characteristics of env. 546 Adams Document Expiration: 26 May 1997 10 548 PER-IDU CALLS 550 IDUP_Start_Protect begin the protection process 551 IDUP_Protect protect the IDU (perhaps 1 buffer at a time) 552 IDUP_End_Protect end the protection process; create a token 553 which contains info. necessary for the 554 legitimate receiver(s) of the P-IDU to 555 unprotect it 556 IDUP_File_Protect protect an IDU (input as a file) 558 IDUP_Start_Unprotect begin the unprotect process 559 IDUP_Unprotect use the token to unprotect the P-IDU 560 (possibly one buffer at a time) 561 IDUP_End_Unprotect end the unprotect process 562 IDUP_File_Unprotect unprotect a P-IDU (input as a file) 564 SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms) 566 IDUP_Form_Complete_PIDU insert in P-IDU any data not provided 567 by the protection call(s) 569 SUPPORT CALLS 571 * GSS_Display_status translate status codes to printable form 572 * GSS_Indicate_mechs indicate mech_types supported on local 573 system 574 * GSS_Compare_name compare two names for equality 575 * GSS_Display_name translate name to printable form 576 * GSS_Import_name convert printable name to normalize form 577 * GSS_Release_name free storage of normalized-form name 578 * GSS_Release_buffer free storage of printable name 579 * GSS_Release_oid_set free storage of OID set 580 IDUP_Parse_Token examine an input token to determine mech_type 581 IDUP_Get_Policy_Info return policy info. for a given policy_id 583 2.1. Credential management calls 585 2.1.1. Relationship to GSS-API 587 Credential management in IDUP-GSS-API is to be understood and used as 588 described in GSS-API [RFC-1508]. The calls GSS_Acquire_cred(), 589 GSS_Release_cred(), and GSS_Inquire_cred() are unchanged (the call 590 GSS_Add_cred() from GSS-API v2 [GSSv2] is also included). However, 591 the interpretation (and possible modification) of the cred_usage 592 parameter for IDUP purposes is for further study. 594 Adams Document Expiration: 26 May 1997 11 596 2.2. Environment-level calls 598 This group of calls is devoted to the establishment and management of 599 an environment for the purpose of IDU protection and unprotection. 600 Before protecting or unprotecting any IDU, an application must call 601 IDUP_Establish_Env() to initialize environment information and select 602 the underlying IDUP-GSS mechanism to be used. A series of protection 603 or unprotection calls is made to process each IDU, the protection 604 calls resulting in a P-IDU for each. Finally, IDUP_Abolish_Env() 605 is called to flush all environment information. 607 Semantically, acquiring credentials and establishing an environment 608 is (in many cases) analogous to logging in to a system -- it 609 authenticates a local user to the system and gives that user access 610 to a set of operations which can be performed. 612 2.2.1. Relationship to GSS-API 614 The set of calls described in this section are used in place of the 615 calls GSS_Init_sec_context(), GSS_Accept_sec_context(), 616 GSS_Delete_sec_context(), GSS_Process_context_token(), and 617 GSS_Context_time() which are described in [RFC-1508], since those 618 calls are specific to a session-oriented environment. 620 Adams Document Expiration: 26 May 1997 12 622 2.2.2. IDUP_Establish_Env call 624 Inputs: 626 o claimant_cred_handle CREDENTIAL HANDLE, 627 -- NULL parameter specifies "use default" 629 o req_mech_type OBJECT IDENTIFIER, 630 -- NULL parameter specifies "use default" 632 o req_policy OBJECT IDENTIFIER, 633 -- NULL parameter specifies "use default". 634 -- This environment-level policy identifier is separate from 635 -- the policy provisions connected with credentials, if they exist 637 o policy_time INTEGER, 638 -- the security policy rules available at the specified time 639 -- NULL parameter specifies "use default" 641 o req_services SET OF OBJECT IDENTIFIER, 643 Outputs: 645 o major_status INTEGER, 647 o minor_status INTEGER, 649 o env_handle ENVIRONMENT HANDLE, 651 o actual_mech_type OBJECT IDENTIFIER, 652 -- actual mechanism always indicated, never NULL 654 o actual_policy OBJECT IDENTIFIER, 655 -- actual policy always indicated, never NULL 657 o actual_policy_time, 658 -- actual time at which the above policy rules came into effect 660 o ret_services SET OF OBJECT IDENTIFIER, 662 Return major_status codes: 664 o GSS_S_COMPLETE indicates that environment-level information was 665 successfully initialized, and that IDU / P-IDU processing can 666 begin on the newly-established environment. 668 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 669 performed on the credential structure referenced by 670 claimant_cred_handle failed, preventing further processing from 671 being performed using that credential structure. 673 o GSS_S_NO_CRED indicates that no environment was established, 674 either because the input cred_handle was invalid or because the 675 caller lacks authorization to access the referenced credentials. 677 Adams Document Expiration: 26 May 1997 13 679 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided 680 through the input claimant_cred_handle argument are no longer 681 valid, so environment establishment cannot be completed. 683 o GSS_S_BAD_MECH indicates that a mech_type unsupported by the 684 IDUP_GSS-API implementation was requested, causing the 685 environment establishment operation to fail. 687 o GSS_S_FAILURE indicates that environment setup could not be 688 accomplished for reasons unspecified at the IDUP-GSS-API level, 689 and that no interface-defined recovery action is available. 691 This routine is used by an application which protects or unprotects 692 IDUs. Using information in the credentials structure referenced by 693 claimant_cred_handle, IDUP_Establish_Env() initializes the data 694 structures required to protect or unprotect IDUs. The 695 claimant_cred_handle, if non-NULL, must correspond to a valid 696 credentials structure. 698 This routine returns an env_handle for all future references to 699 this environment; when protection, unprotection, or 700 IDUP_Abolish_Env() calls are made, this handle value will be used 701 as the input env_handle argument. 703 It is the caller's responsibility to establish a communications path 704 to the intended recipients of the P-IDU, and to transmit the P-IDU to 705 those recipients over that path. This may occur subsequent to the 706 IDUP_Abolish_Env() call. 708 The req_services parameter may be used by the calling application to 709 request that data origin authentication with integrity, 710 confidentiality with integrity, evidence generation, and/or evidence 711 verification services be available in the established environment. 712 Requests can also be made for "trusted" or "untrusted" time services. 713 Requesting evidence generation or verification indicates that the 714 calling application may wish to generate or verify evidence 715 information for non-repudiation purposes (note: an IDU protector may 716 request that a flag be inserted into a P-IDU asking a recipient to 717 provide an evidence of the type "non-repudiation of delivery"; 718 however, the IDUP-GSS-API cannot by itself guarantee that the 719 evidence will be sent because there is no way to force a target to 720 send an evidence_token back to the IDU protector). 722 Not all features will be available in all underlying mech_types; the 723 returned value of ret_services indicates, as a function 724 of mech_type processing capabilities and the initiator-provided input 725 OBJECT IDs, the set of features which will be available in the 726 environment. The value of this parameter is undefined unless the 727 routine's major_status indicates COMPLETE. Failure to provide the 728 precise set of services desired by the caller does not cause 729 environment establishment to fail; it is the caller's prerogative to 730 abolish the environment if the service set provided is unsuitable for 731 the caller's use. The returned mech_type value indicates the 732 specific mechanism employed in the environment, and will never 733 indicate the value for "default". 735 Adams Document Expiration: 26 May 1997 14 737 The following OBJECT IDs are defined for protection and unprotection 738 services. It is recognized that this list may grow over time. 740 PER_CONF = { xx } 741 -- perform data confidentiality (i.e., encrypt data) 742 PER_DOA = { xx } 743 -- perform data origin authentication with data integrity 744 PER_POO = { xx } 745 -- perform (i.e., create) non-repudiable "proof of origin" 746 PER_POD = { xx } 747 -- perform (i.e., create) non-repudiable "proof of delivery" 748 REC_CONF = { xx } 749 -- receive data confidentiality (i.e., decrypt data) 750 REC_DOA = { xx } 751 -- receive / verify DOA with data integrity 752 REC_POO = { xx } 753 -- receive / verify "proof of origin" 754 REC_POD = { xx } 755 -- receive / verify "proof of delivery" 756 TTIME = { xx } 757 -- trusted time availability 758 UTIME = { xx } 759 -- untrusted time availability 761 The PER_CONF return value (in the ret_services paramater) indicates 762 whether the environment supports confidentiality services, and so 763 informs the caller whether or not a request for encryption through 764 a confidentiality service input to IDUP_Start_Protect() can be 765 honored. In similar fashion, the PER_DOA return value indicates 766 whether DOA services are available in the established environment, 767 and the PER_POO and PER_POD return values indicate whether evidence 768 generation services are available. The TTIME and UTIME values 769 indicate whether trusted time and untrusted time are available for 770 protection / unprotection services. 772 Note that, unlike a GSS "context", an IDUP environment does not have 773 an explicit lifetime associated with it. Instead, it relies on the 774 lifetime of the calling entity's credential (set by the caller in the 775 GSS_Acquire_cred() call). When the credential expires (or is 776 explicitly deleted using the gss_release_cred() call), no new 777 operations are allowed in the IDUP environment (although operations 778 which have begun, such as the Protection set of calls, can be taken 779 to completion). 781 2.2.3. IDUP_Abolish_Env call 783 Input: 785 o env_handle ENVIRONMENT HANDLE 787 Outputs: 789 o major_status INTEGER, 791 o minor_status INTEGER, 793 Adams Document Expiration: 26 May 1997 15 795 Return major_status codes: 797 o GSS_S_COMPLETE indicates that the environment was recognized and 798 that relevant environment-specific information was flushed. 800 o IDUP_S_NO_ENV indicates that no valid environment was recognized 801 for the env_handle provided, so no deletion was performed. 803 o GSS_S_FAILURE indicates that the environment is recognized, but 804 that the requested operation could not be performed for reasons 805 unspecified at the IDUP-GSS-API level. 807 This call is made to flush environment-specific information. (Once an 808 environment is established, cached credential and environment-related 809 info. is expected to be retained until an IDUP_Abolish_Env() call is 810 made or until the cred. lifetime expires.) Attempts to perform IDU 811 processing on a deleted environment will result in error returns. 813 2.2.4: IDUP_Inquire_Env call 815 Input: 817 o env_handle ENVIRONMENT HANDLE, 819 Outputs: 821 o major_status INTEGER, 823 o minor_status INTEGER, 825 o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this env. 827 o policy OBJECT IDENTIFIER, -- the policy used in this env. 829 o policy_time, -- time at which the policy rules came into effect 831 o ret_services SET OF OBJECT IDENTIFIER, 833 Return major_status codes: 835 o GSS_S_COMPLETE indicates that the referenced environment is valid 836 and that mech_type and other return values describe the 837 corresponding characteristics of the environment. 839 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 840 recognized, but that its associated credentials have expired, so 841 that the requested operation cannot be performed. 843 o IDUP_S_NO_ENV indicates that no valid environment was recognized 844 for the env_handle provided, so no return values can be provided. 846 o GSS_S_FAILURE indicates that the environment is recognized, but 847 that the requested operation could not be performed for reasons 848 unspecified at the IDUP-GSS-API level. 850 This routine provides environment-related information to the caller. 852 Adams Document Expiration: 26 May 1997 16 854 2.3. Per-IDU calls 856 This group of calls is used to perform IDU protection and 857 unprotection processing on an established IDUP environment. Some of 858 these calls may block pending network interactions (depending on the 859 underlying mechanism in use). These calls may be invoked by an IDU's 860 protector or by the P-IDU's recipient. The two sets of members of 861 this group form a pair; the output from the protection set is 862 typically meant to be input to the unprotection set. 864 The per-IDU calls can support caller-requested data origin 865 authentication with data integrity, confidentiality with data 866 integrity, evidence, and evidence-requested-from-target services. 867 The protection operations output a token which encapsulates all the 868 information required to unprotect the IDU. The token is passed to 869 the target (possibly separate from the M-IDU) and is processed by the 870 unprotection calls at that system. Unprotection performs 871 decipherment, DOA verification, evidence verification, or 872 notification of evidence requested, as required. 874 Each of the two main operations (protection and unprotection) may be 875 separated into three parts: "Start_Operation"; "Operation" (which 876 may be called once for each buffer of input data); and 877 "End_Operation". This separation is available for the case where the 878 IDU or P-IDU is to be processed one buffer at a time. 879 "Start_Operation" allows the caller to specify or retrieve the 880 appropriate "Quality" used during the processing. "Operation" is 881 concerned with the processing itself, receiving a buffer of input 882 data and potentially returning a buffer of output data. 883 "End_Operation" performs any required clean-up and creates the 884 appropriate token or states whether the input token was verified. 886 If the IDU or P-IDU is wholly contained in a single buffer, the 887 three-part protection/unprotection processing need not be done. 888 Instead, protection and unprotection can be accomplished using only 889 the "Start_Operation" call, simplifying application code. 891 2.3.1. Relationship to GSS-API 893 The set of calls described in this section are used in place of the 894 calls GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() -- now 895 named GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() -- 896 which are specified in [RFC-1508], since those calls are specific to 897 a session-oriented environment. 899 Adams Document Expiration: 26 May 1997 17 901 2.3.2. The "SE" Calls 903 2.3.2.1. IDUP_SE Parameter Bundles 905 The concept of "parameter bundles" is used in the calls presented in 906 the following subsections in order to simplify their presentation and 907 clarify their intended purpose and use. See Section 2.3.2 for a more 908 complete description of parameter bundles. 910 The following parameter bundles are used in the "SE" protection and 911 unprotection sets of calls. 913 o Protect_Options PARAMETER BUNDLE 914 o Protect_Operation INTEGER { 915 sign_only (0), 916 encrypt_only (1), 917 sign_and_encrypt (2), 918 clear_sign_only (3) 919 } 920 o sign_qop_alg UNSIGNED INTEGER, 921 o enc_qop_alg UNSIGNED INTEGER, 922 o idu_type_string OCTET STRING 924 o PIDU_Information PARAMETER BUNDLE 925 o Protect_Options PARAMETER BUNDLE, 926 o originator_name INTERNAL NAME, 927 o protection_time INTEGER 929 o Bad_Target_Name PARAMETER BUNDLE, 930 o bad_targ_name INTERNAL NAME, 931 o bad_targ_status INTEGER, 932 -- a (mechanism-defined) status flag giving the reason 933 -- for rejection of the name in bad_targ_name 935 o Target_Info PARAMETER BUNDLE, 936 o targ_names SET OF INTERNAL NAME, 937 o bad_targ_count INTEGER, 938 o Bad_Target_Name PARAMETER BUNDLE, 940 2.3.2.2. IDUP_SE major_status codes 942 The following major_status return codes are defined for the "SE" 943 calls in this section: 945 o GSS_S_COMPLETE indicates that the requested operation has 946 completed successfully. 948 o GSS_S_CONTINUE_NEEDED indicates that the output buffer 949 supplied is too small to hold the generated data. The application 950 should continue calling this routine (until GSS_S_COMPLETE is 951 returned) in order to get all remaining data. 953 o IDUP_S_MORE_DATA_NEEDED indicates that more input data is needed 954 for the StartUnprotect operation (e.g., so that PIDU_Information 955 or initial_idu_buffer may be returned). 957 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 958 recognized, but that its associated credentials have expired, so 959 that the requested operation cannot be performed. 961 Adams Document Expiration: 26 May 1997 18 963 o IDUP_S_NO_ENV indicates that no valid environment was recognized 964 for the env_handle provided. 966 o GSS_S_BAD_QOP indicates that the provided qop_alg value is not 967 recognized or supported for the environment. 969 o GSS_S_FAILURE indicates that the environment is recognized, but 970 that the requested operation could not be performed for reasons 971 unspecified at the IDUP-GSS-API level. 973 If Target_Info is used as an input parameter (i.e., if an encryption 974 operation is being performed), the following major_status return code 975 is also defined: 977 o IDUP_S_BAD_TARG_INFO indicates that all the information regarding 978 the target(s) is invalid or is insufficient for the protection of 979 an IDU, so P-IDU cannot be created. 981 Note for this return code that if one or more of the targets in 982 targ_names cannot be used as a valid recipient of the P-IDU, these 983 names will be returned in bad_targ_names (with associated status 984 codes in bad_targ_status). As long as at least one of the targets 985 can be used, however, this does not cause this call to fail (i.e., 986 the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the 987 caller's prerogative to discontinue IDU protection if the target set 988 which can be used is unsuitable for the caller's purposes. 990 2.3.2.3. IDUP_SE Purpose 992 The "SE" group of calls provides a very simple, high-level 993 interface to underlying IDUP mechanisms when application developers 994 need access only to signature and encryption protection/unprotection 995 services. It includes both the single-buffer and multiple-buffer IDU 996 cases and can be used for signing only, encrypting only, signing and 997 encrypting (where the signature is computed on the cleartext data and 998 the signature itself is not encrypted), and "clear signing" (where 999 the data is not modified in any way and the signature itself is 1000 returned (unencapsulated) as a separate item). 1002 The SE calls may be viewed by mechanism implementors as an "API" to 1003 the more powerful Protection and Unprotection sets of calls defined 1004 later and so may be implemented as simple mapping functions to those 1005 calls. Application callers, on the other hand, may find that the SE 1006 calls are all they currently need for many environments and may 1007 migrate to the more general calls only at some time in the future 1008 when they have need of data labeling, non-repudiation, or "directed 1009 receipts" types of services. To assist in this migration path, it 1010 is recommended that mechanism implementors support the full set of 1011 IDUP calls (i.e., both the SE calls and the more powerful calls) even 1012 though some calling applications will only use the SE calls in the 1013 short term. 1015 Adams Document Expiration: 26 May 1997 19 1017 2.3.2.4. IDUP_SE_SingleBuffer_Protect call 1019 Inputs: 1020 o env_handle ENVIRONMENT HANDLE, 1021 o Protect_Options PARAMETER BUNDLE, 1022 o Target_Info PARAMETER BUNDLE, 1023 -- used if Protect_Options is encrypt_only or sign_and_encrypt 1024 o idu_buffer OCTET STRING 1026 Outputs: 1027 o major_status INTEGER, 1028 o minor_status INTEGER, 1029 o pidu_buffer OCTET STRING, 1030 o sig_token OCTET STRING 1031 -- used if Protect_Options is clear_sign_only 1033 Using the security environment referenced by env_handle, encrypt 1034 and/or sign the supplied IDU. If "clear signing" is performed, the 1035 signature will be returned in sig_token and pidu_buffer may be empty 1036 (depends on underlying mechanism). 1038 2.3.2.5. IDUP_SE_SingleBuffer_Unprotect call 1040 Inputs: 1041 o env_handle ENVIRONMENT HANDLE, 1042 o pidu_buffer OCTET STRING, 1043 -- may contain an IDU if sig_token is non-NULL (i.e., if 1044 -- clear_sign_only protection was applied) 1045 o sig_token OCTET STRING 1047 Outputs: 1048 o major_status INTEGER, 1049 o minor_status INTEGER, 1050 o idu_buffer OCTET STRING, 1051 -- may be empty if clear_sign_only protection was applied (depends 1052 -- on underlying mechanism) 1053 o PIDU_Information PARAMETER BUNDLE 1055 Using the security environment referenced by env_handle, decrypt 1056 and/or verify the supplied PIDU and return the contained IDU along 1057 with all available PIDU_Information. 1059 2.3.2.6. IDUP_SE_MultiBuffer_StartProtect call 1061 Inputs: 1062 o env_handle ENVIRONMENT HANDLE, 1063 o Protect_Options PARAMETER BUNDLE, 1064 o Target_Info PARAMETER BUNDLE 1065 -- used if Protect_Options is encrypt_only or sign_and_encrypt 1067 Outputs: 1068 o major_status INTEGER, 1069 o minor_status INTEGER, 1070 o initial_pidu_buffer OCTET STRING 1071 -- may be empty (depends on underlying mechanism) 1073 Using the security environment referenced by env_handle, initialize 1074 the data structures required to begin the process of signing 1075 and/or encrypting the IDU (which will be supplied in multiple buffers 1076 to the Process_Buffer call). 1078 Adams Document Expiration: 26 May 1997 20 1080 2.3.2.7. IDUP_SE_MultiBuffer_EndProtect call 1082 Inputs: 1083 o env_handle ENVIRONMENT HANDLE 1085 Outputs: 1086 o major_status INTEGER, 1087 o minor_status INTEGER, 1088 o final_pidu_buffer OCTET STRING, 1089 o sig_token OCTET STRING 1090 -- used if Protect_Options was clear_sign_only 1092 Using the security environment referenced by env_handle, complete the 1093 protection processing on the data and place the computed output in 1094 final_pidu_buffer and/or sig_token. Successful application of 1095 IDUP_SE_MultiBuffer_EndProtect() does not guarantee that unprotection 1096 can necessarily be performed successfully when the P-IDU arrives at 1097 the target (for example, it may be damaged in transit). 1099 2.3.2.8. IDUP_SE_MultiBuffer_StartUnprotect call 1101 Inputs: 1102 o env_handle ENVIRONMENT HANDLE, 1103 o initial_pidu_buffer OCTET STRING, 1104 o sign_qop_alg_in UNSIGNED INTEGER, 1105 -- used if Protect_Options was clear_sign_only; 1106 -- if NULL, then sig_token must be supplied 1107 o sig_token OCTET STRING 1108 -- used if Protect_Options was clear_sign_only; 1109 -- if NULL, then sign_qop_alg_in must be supplied 1111 Outputs: 1112 o major_status INTEGER, 1113 o minor_status INTEGER, 1114 o PIDU_Information PARAMETER BUNDLE, 1115 -- returns all available information 1116 o initial_idu_buffer OCTET STRING 1117 -- may be empty 1119 Using the security environment referenced by env_handle, initialize 1120 the data structures required to begin the process of decrypting 1121 and/or verifying the PIDU (which will be supplied in multiple buffers 1122 to the Process_Buffer call). 1124 2.3.2.9. IDUP_SE_MultiBuffer_EndUnprotect call 1126 Inputs: 1127 o env_handle ENVIRONMENT HANDLE, 1128 o sig_token OCTET STRING 1129 -- used if Protect_Options was clear_sign_only 1131 Outputs: 1132 o major_status INTEGER, 1133 o minor_status INTEGER, 1134 o PIDU_Information PARAMETER BUNDLE, 1135 -- returns all available information 1136 o final_idu_buffer OCTET STRING 1137 -- may be empty 1139 Using the security environment referenced by env_handle, complete the 1140 decryption and/or verification processing on the data and place any 1141 residual output in final_idu_buffer. 1143 Adams Document Expiration: 26 May 1997 21 1145 2.3.2.10. IDUP_SE_Process_Buffer call 1147 Inputs: 1148 o env_handle ENVIRONMENT HANDLE, 1149 o input_buffer OCTET STRING, 1151 Outputs: 1152 o major_status INTEGER, 1153 o minor_status INTEGER, 1154 o output_buffer OCTET STRING 1155 -- may be zero length (depends on underlying mechanism and 1156 -- corresponding Start() call and Protect_Options value) 1158 Using the security environment referenced by env_handle, continue the 1159 processing on the data in input_buffer and, if it is available, put 1160 any resulting output data in output_buffer. The application calls 1161 this routine over and over again with new buffers of data until it 1162 has processed all the data buffers of the IDU/PIDU. It then calls 1163 the appropriate End() call to complete the processing. 1165 2.3.2. Parameter Bundles 1167 The concept of "parameter bundles" is used in the calls presented in 1168 the following subsections in order to simplify their presentation and 1169 (hopefully) clarify their intended purpose and use. A parameter 1170 bundle is simply a set of closely-related parameters of a call which 1171 are either all used by / available to the calling application or all 1172 not used by / unavailable to the calling application. These 1173 parameters may be all input parameters, all output parameters, or 1174 any combination of the two. 1176 Adams Document Expiration: 26 May 1997 22 1178 A typical use envisioned for parameter bundles in a language such as 1179 C would be as a structure, where individual parameters in the bundle 1180 are structure members. The calling application wishing to use a 1181 particular bundle would then allocate the appropriate structure 1182 variable, assign the desired input values to the appropriate members, 1183 and pass the address of the structure as the bundle "parameter". On 1184 output, the values of the appropriate output members may be read. An 1185 application not wishing to use a particular bundle (or one which is 1186 satisfied with default values for all input parameters of the bundle 1187 and which doesn't care about output values), can pass NULL as the 1188 bundle "parameter". From the mechanism implementor's perspective, if 1189 a parameter bundle is not supported (for example, if it represents a 1190 security service which is not supported by the implementation), then 1191 any non-NULL value passed as the bundle parameter will generate an 1192 error status return code. 1194 The following parameter bundles are used in the subsequent protection 1195 and unprotection sets of calls. A parameter preceded by "(I)" is an 1196 input parameter; one preceded by "(O)" is an output parameter; one 1197 preceded by neither is an input if the bundle itself is an input and 1198 is an output if the bundle itself is an output; one preceded by "(X)" 1199 is the opposite: an output if the bundle itself is an input and an 1200 input if the bundle itself is an output. 1202 o Mech_Specific_Info PARAMETER BUNDLE 1203 -- actual parameters included in this bundle are defined by (and 1204 -- specific to) the underlying mechanism 1206 o Sensitivity PARAMETER BUNDLE, 1207 -- actual parameters included in this bundle are defined by (and 1208 -- specific to) the underlying mechanism, but may include 1209 -- codified values for "Unclassified", "Secret", "Top Secret", 1210 -- and so on 1212 o Service_Creation_Info PARAMETER BUNDLE 1213 -- actual parameters included in this bundle are defined by (and 1214 -- specific to) the underlying mechanism, but it is mandatory 1215 -- that they include at least service_id and Quality 1217 o Service_Verification_Info PARAMETER BUNDLE 1218 -- actual parameters included in this bundle are defined by (and 1219 -- specific to) the underlying mechanism, but it is mandatory 1220 -- that they include at least service_id and Quality 1222 o Quality PARAMETER BUNDLE 1223 o qop_algs UNSIGNED INTEGER, 1224 o validity UNSIGNED INTEGER, 1225 -- protection guaranteed to be valid until time specified 1226 o policy_id OBJECT IDENTIFIER, 1227 -- security policy under which protection is/was carried out 1228 o allow_policy_mapping BOOLEAN, 1229 -- determines whether mapping between policy IDs is allowed 1231 Adams Document Expiration: 26 May 1997 23 1233 o Idu_Information PARAMETER BUNDLE, 1234 o idu_type_oid OBJECT IDENTIFIER, 1235 o idu_type_string OCTET STRING, 1236 o idu_title OCTET STRING, 1237 o idu_sensitivity Sensitivity, 1238 o pidu_type_oid OBJECT IDENTIFIER, 1239 o pidu_type_string OCTET STRING, 1240 o pidu_title OCTET STRING, 1241 o pidu_sensitivity Sensitivity, 1243 o Prot_Information PARAMETER BUNDLE, 1244 o originator_name INTERNAL NAME, 1245 o idu_information Idu_Information, 1246 o protection_time INTEGER, 1248 o Special_Conditions PARAMETER BUNDLE, 1249 o prot_oper_id INTEGER, 1250 o use_trusted_time BOOLEAN, 1251 o use_untrusted_time BOOLEAN, 1253 o Bad_Target_Name PARAMETER BUNDLE, 1254 o (O) bad_targ_name INTERNAL NAME, 1255 o (O) bad_targ_status INTEGER, 1256 -- a (mechanism-defined) status flag giving the reason 1257 -- for rejection of the name in bad_targ_name 1259 o Target_Info PARAMETER BUNDLE, 1260 o targ_names SET OF INTERNAL NAME, 1261 o (O) bad_targ_count INTEGER, 1262 o (O) bad_target_name Bad_Target_Name, 1264 o General_Service_Data PARAMETER BUNDLE, 1265 o target_info Target_Info, 1266 o (X) unencapsulated_token OCTET STRING, 1267 -- zero length if encapsulation_request is TRUE 1268 o (O) minor_status INTEGER, 1270 Adams Document Expiration: 26 May 1997 24 1272 Three types of protection services are defined in IDUP. These are 1274 1. perform unsolicited service (i.e., act on a locally-generated 1275 service request), 1276 2. perform solicited service (i.e., act on a remotely-generated 1277 service request), and 1278 3. perform service solicitation (i.e., send a service request to 1279 the remote end). 1281 As an originator, applying data confidentiality with data integrity, 1282 or data origin authentication with data integrity, or proof of origin 1283 evidence is an example of service type 1. As a target, creating a 1284 proof of delivery (i.e., receipt) evidence token as the result of a 1285 request received from the originator is an example of service type 2. 1286 Finally, as an originator, submitting a request that one or more 1287 targets return a receipt for the data sent is an example of service 1288 type 3. 1290 The first four parameters in the Prot_Service parameter bundle 1291 pertain to all service types; the fifth parameter is used if and only 1292 if service type 2 is desired; parameters 6-8 are used if and only if 1293 service type 3 is desired. 1295 o Prot_Service PARAMETER BUNDLE 1296 o (I) prot_service_type INTEGER, 1297 o (I) service_id OBJECT IDENTIFIER, 1298 o (I) quality Quality, 1299 -- NULL specifies default Quality 1300 o (I) general_service_data General_Service_Data, 1301 o (I) service_creation_info Service_Creation_Info, 1302 o (I) service_to SET OF INTERNAL NAME, 1303 o (O) service_verification_info Service_Verification_Info, 1304 o (O) service_verification_info_id INTEGER, 1306 Also, three types of unprotection services are defined. These are 1308 1. receive unsolicited service (i.e., process unrequested 1309 remotely-generated service), 1310 2. receive solicited service (i.e., process remotely-generated 1311 response to locally-generated request), and 1312 3. receive service solicitation (i.e., process req. from rem. end) 1314 As a target, unprotecting an encrypted message, or verifying the 1315 originator's proof of origin is an example of service type 1. As an 1316 originator, verifying a proof of delivery which you requested from a 1317 target is an example of service type 2. Finally, as a target, 1318 receiving a request from an originator for a proof of delivery is an 1319 example of service type 3. 1321 Adams Document Expiration: 26 May 1997 25 1323 The first four parameters in the Unprot_Service parameter bundle 1324 pertain to all service types; parameters 5-6 are used if and only if 1325 service type 2 is required; parameters 7-8 are used only if service 1326 type 3 is required. 1328 o Unprot_Service PARAMETER BUNDLE 1329 o (O) unprot_service_type INTEGER, 1330 o (O) service_id OBJECT IDENTIFIER, 1331 o (O) quality Quality, 1332 -- actual Quality specified (never NULL) 1333 o (O) general_service_data General_Service_Data, 1334 o (O) service_verification_info_id INTEGER, 1335 o (I) service_verification_info Service_Verification_Info, 1336 o (O) service_to SET OF INTERNAL NAME, 1337 o (O) service_creation_info Service_Creation_Info, 1339 2.3.3. IDUP_Start_Protect call 1341 Inputs: 1343 o env_handle ENVIRONMENT HANDLE, 1345 o Mech_Specific_Info PARAMETER BUNDLE, 1346 -- NULL selects the mechanism-defined default values 1348 o Idu_Information PARAMETER BUNDLE, 1350 o Special_Conditions PARAMETER BUNDLE, 1352 o encapsulation_request BOOLEAN, 1354 o single_idu_buffer OCTET STRING, 1355 -- non-zero length for this buffer means that Protect/End_Protect 1356 -- won't be called (i.e., entire IDU is contained in this buffer) 1358 o Target_Info PARAMETER BUNDLE, 1360 o Services_to_Perform SET OF Prot_Service, 1362 Outputs: 1364 o major_status INTEGER, 1366 o minor_status INTEGER, 1368 o midu_buffer OCTET STRING, 1369 -- zero length if encapsulation_request is TRUE; 1370 -- may be zero length otherwise (depends on underlying mechanism) 1372 Adams Document Expiration: 26 May 1997 26 1374 o pidu_buffer OCTET STRING, 1375 -- zero length if encapsulation_request is FALSE; 1376 -- may be zero length otherwise (depends on underlying mechanism) 1378 Return major_status codes: 1380 o GSS_S_COMPLETE indicates that the protection process can begin 1381 (or has completed, if single_idu_buffer has non-zero length). 1383 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1384 supplied is too small to hold the generated data. The application 1385 should continue calling this routine (until GSS_S_COMPLETE is 1386 returned) in order to get all remaining data. 1388 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 1389 recognized, but that its associated credentials have expired, so 1390 that the requested operation cannot be performed. 1392 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1393 for the env_handle provided. 1395 o IDUP_S_ENCAPSULATION_UNAVAIL indicates that the underlying 1396 mechanism does not support encapsulation of the M-IDU into the 1397 token. 1399 o IDUP_S_MORE_DATA_NEEDED indicates whether protection is completed 1400 by this call or by IDUP_End_Protect() (e.g., whether more data 1401 buffers are required for evidence generation) 1403 o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 1404 does not support the service requested. 1406 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 1407 requested (TTIME or UTIME) is not available in the environment. 1409 o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 1410 is not recognized or supported in the underlying mechanism. 1412 o GSS_S_BAD_QOP indicates that the provided qop_algs value is not 1413 recognized or supported for the environment. 1415 o IDUP_S_BAD_TARG_INFO indicates that all the information regarding 1416 the target(s) is invalid or is insufficient for the protection of 1417 an IDU, so P-IDU cannot be created. 1419 o GSS_S_FAILURE indicates that the environment is recognized, but 1420 that the requested operation could not be performed for reasons 1421 unspecified at the IDUP-GSS-API level. 1423 Adams Document Expiration: 26 May 1997 27 1425 Using the security environment referenced by env_handle, initialize 1426 the data structures required to begin the process of protecting the 1427 IDU buffers. The caller requests specific protection services by 1428 supplying the appropriate Prot_Service parameter bundles in 1429 Services_to_Perform. Each service is able to return a minor status 1430 code to the calling application, if necessary. 1432 The calling application, knowing the size of the IDU it wishes to 1433 protect and the buffer size which it has available to it, can choose 1434 to input the entire IDU in a single buffer and omit the subsequent 1435 IDUP_Protect() and IDUP_End_Protect() calls. Furthermore, the 1436 application can request that the resulting M-IDU be encapsulated in 1437 the token -- so that the token contains the entire P-IDU -- rather 1438 than having it be returned separately in midu_buffer. Encapsulation, 1439 however, may not be supported by all underlying mechanisms or 1440 implementations; if this is the case, the 1441 IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and 1442 M-IDU will be returned in midu_buffer. 1444 For those mechanisms which allow or require multiple stages of 1445 processing, each producing a different aspect of protection for the 1446 IDU, the operation identifier prot_oper_id is used to specify 1447 which stage is currently being requested by the application. An 1448 example where this would be useful is a mechanism which implements 1449 the signed Message Security Protocol [MSP]. As another example, a 1450 mechanism may choose to do a digital signature in two stages: one 1451 for the hashing of the message and another for the signature on the 1452 hash. The calling application would therefore use the protection set 1453 of calls on the IDU in stage 1 and then use the protection set of 1454 calls on the token (from stage 1) in stage 2. 1456 Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where 1457 "n" is the number of stages as defined by the mechanism (typically 1 1458 or 2)). The calling application uses this parameter to indicate to 1459 the underlying mechanism whether it wishes to do stage 1 of 1460 protection / unprotection processing, or stage 2, and so on. 1462 If one or more of the targets in targ_names cannot be used as a valid 1463 recipient of the P-IDU, these names will be returned in 1464 bad_targ_names (with associated status codes in bad_targ_status). As 1465 long as at least one of the targets can be used, this does not cause 1466 this call to fail; it is the caller's prerogative to discontinue IDU 1467 protection if the target set which can be used is unsuitable for the 1468 caller's purposes. Note that each Prot_Service parameter bundle can 1469 also input a list of targ_names; this is used if a separate list is 1470 to be used for that service only (the general list of targets is to 1471 be used for all services unless overridden in this way). 1473 Adams Document Expiration: 26 May 1997 28 1475 2.3.4. IDUP_Protect call 1477 Inputs: 1479 o env_handle ENVIRONMENT HANDLE, 1481 o input_buffer OCTET STRING, 1483 Outputs: 1485 o major_status INTEGER, 1487 o minor_status INTEGER, 1489 o output_buffer OCTET STRING 1490 -- may be zero length if encapsulation_request was set to TRUE in 1491 -- IDUP_Start_Protect() (depends on underlying mechanism) 1493 Return major_status codes: 1495 o GSS_S_COMPLETE indicates that the input_buffer has successfully 1496 been included in the protection computation. 1498 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1499 for the env_handle provided. 1501 o GSS_S_FAILURE indicates that the environment is recognized, but 1502 that the required operation could not be performed for reasons 1503 unspecified at the IDUP-GSS-API level. 1505 Using the security environment referenced by env_handle, continue the 1506 protection processing on the data in input_buffer and, if the 1507 underlying mechanism defines this, put any resulting P-IDU/M-IDU data 1508 in output_buffer. The application calls this routine over and over 1509 again with new buffers of data until it has protected all the data 1510 buffers of the IDU. It then calls IDUP_End_Protect() to complete the 1511 protection processing. 1513 Adams Document Expiration: 26 May 1997 29 1515 2.3.5. IDUP_End_Protect call 1517 Inputs: 1519 o env_handle ENVIRONMENT HANDLE, 1521 Outputs: 1523 o major_status INTEGER, 1525 o minor_status INTEGER, 1527 o Services_to_Perform SET OF Prot_Service, 1529 o final_midu_buffer OCTET STRING, 1530 -- zero length if encapsulation_request was set to TRUE in 1531 -- IDUP_Start_Protect(), in which case pidu is used 1533 o final_pidu_buffer OCTET STRING, 1534 -- zero length if encapsulation_request was set to FALSE in 1535 -- IDUP_Start_Protect(), in which case token and midu are used 1537 Return major_status codes: 1539 o GSS_S_COMPLETE indicates that the protection computation has been 1540 successfully completed and the resulting P-IDU is ready for 1541 transfer. If defined by the underlying mechanism, 1542 final_midu_buffer will contain any residual M-IDU data. 1544 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1545 supplied is too small to hold the generated data. The application 1546 should continue calling this routine (until GSS_S_COMPLETE is 1547 returned) in order to get all remaining data. 1549 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1550 for the env_handle provided. 1552 o GSS_S_FAILURE indicates that the environment is recognized, but 1553 that the requested operation could not be performed for reasons 1554 unspecified at the IDUP-GSS-API level. 1556 Using the security environment referenced by env_handle, complete the 1557 protection processing on the data and place the computed output in 1558 final_pidu_buffer (or final_midu_buffer and the unencapsulated_token 1559 parameter for each Prot_Service). If a service was requested from 1560 one or more targets in Start_Protect() - and if this is supported by 1561 the underlying mechanism - Service_Verification_Info will hold 1562 whatever data is necessary for the mechanism to verify a service 1563 returned by a target (unprotector) of the P-IDU. Successful 1564 application of IDUP_End_Protect() does not guarantee that the 1565 corresponding unprotection set of calls can necessarily be performed 1566 successfully when the P-IDU arrives at the target (for example, it 1567 may be damaged in transit). 1569 Adams Document Expiration: 26 May 1997 30 1571 2.3.6. IDUP_Start_Unprotect call 1573 Inputs: 1575 o env_handle ENVIRONMENT HANDLE, 1577 o Mech_Specific_Info PARAMETER BUNDLE, 1578 -- NULL selects the mechanism-defined default values 1580 o single_data_buffer OCTET STRING, 1581 -- non-zero length for this buffer means that IDUP_Unprotect() and 1582 -- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU 1583 -- (if encapsulation is used) or M-IDU (if encap. is not used) 1584 -- is contained in this buffer) 1586 o partial_pidu_buffer OCTET STRING, 1587 -- may be an arbitrary-sized piece of the full pidu (if the 1588 -- application's buffer isn't large enough to hold entire pidu). 1589 -- Used if pidu_buffer will be input a buffer at a time (except 1590 -- that the final buffer must be passed in final_pidu_buffer 1591 -- rather than partial_pidu_buffer). Only one of 1592 -- single_pidu_buffer and partial(final)_pidu_buffer can have 1593 -- nonzero length. 1595 o final_pidu_buffer OCTET STRING, 1597 o Special_Conditions PARAMETER BUNDLE, 1599 Adams Document Expiration: 26 May 1997 31 1601 Outputs: 1603 o major_status INTEGER, 1605 o minor_status INTEGER, 1607 o Services_to_Receive SET OF Unprot_Service, 1609 o Prot_Information PARAMETER BUNDLE, 1611 o single_idu_buffer OCTET STRING, 1612 -- if this buffer has non-zero length, then service processing has 1613 -- been completed on the data in single_pidu_buffer 1615 o initial_idu_buffer OCTET STRING, 1616 -- holds any data from partial(final)_pidu_buffer which has been 1617 -- unprotected; remaining data will be returned by Unprotect and 1618 -- End_Unprotect as they are called with successive buffers of 1619 -- pidu 1621 o Service_Verification_Info PARAMETER BUNDLE, 1622 -- used only if target is on "service_to" list in Unprot_Service 1624 o service_verification_info_id INTEGER, 1625 -- used only if target is on "service_to" list in Unprot_Service 1627 Return major_status codes: 1629 o GSS_S_COMPLETE indicates that unprotection processing can begin 1630 (or has completed, if single_idu_buffer has non-zero length). 1632 o IDUP_S_INCOMPLETE indicates that the unprotection of the P-IDU 1633 is not yet complete (i.e., a determination cannot yet be made on 1634 the validity of the P-IDU). The application should call 1635 IDUP_Form_Complete_PIDU and then should call this function again 1636 with the complete P-IDU. (This status code is used in 1637 IDUP_Start_Unprotect only if single_idu_buffer has non-zero 1638 length) 1640 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1641 supplied is too small to hold the generated data. The application 1642 should continue calling this routine (until GSS_S_COMPLETE is 1643 returned) in order to get all remaining data. 1645 o IDUP_S_MORE_PIDU_NEEDED indicates that not enough of the P-IDU 1646 has been input yet for the completion of Start_Protect. The 1647 application should call this routine again with another buffer 1648 of P-IDU in partial_pidu_buffer. 1650 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 1651 on the received P-IDU failed, preventing further processing 1652 from being performed. 1654 o IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied 1655 do not contain the information necessary for P-IDU unprotection. 1657 Adams Document Expiration: 26 May 1997 32 1659 o IDUP_S_MORE_DATA_NEEDED indicates whether unprotection is 1660 completed by this call or by IDUP_End_Unprotect() (e.g., whether 1661 more data buffers are required for unprotection) 1663 o GSS_S_DEFECTIVE_VERIF indicates that consistency checks performed 1664 on Service_Verification_Info failed, preventing further processing 1665 from being performed with that parameter. 1667 o IDUP_S_NO_MATCH indicates that Service_Verification_Info and 1668 the P-IDU to be verified do not match. 1670 o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 1671 does not support the service requested. 1673 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 1674 requested (TTIME or UTIME) is not available in the environment. 1676 o IDUP_S_SERV_VERIF_INFO_NEEDED indicates that the 1677 Service_Verification_Info parameter bundle must be input in order 1678 for service verification to proceed. The output parameter 1679 service_verification_info_id contains an identifier which may be 1680 used by the calling application to locate the necessary 1681 information. 1683 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 1684 recognized, but that its associated credentials have expired, so 1685 that the requested operation cannot be performed. 1687 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1688 for the env_handle provided. 1690 o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 1691 is not recognized or supported in the underlying mechanism. 1693 o GSS_S_BAD_QOP indicates that the qop_algs value specified in P-IDU 1694 for at least one of the services is unavailable in the local 1695 mechanism, so processing cannot continue. 1697 o GSS_S_BAD_SIG indicates that the received P-IDU contains an 1698 incorrect integrity field (e.g., signature or MAC) for the data. 1700 o IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU 1701 data origin auth. / integ. has either expired or been revoked. 1703 o IDUP_S_BAD_KE_KEY indicates that the key used to establish a key 1704 for confidentiality purposes between originator and target has 1705 either expired or been revoked. 1707 o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU 1708 cannot be completed because the encrypted IDU was invalid/defec- 1709 tive (e.g., the final block was short or had incorrect padding). 1711 o GSS_S_FAILURE indicates that the environment is recognized, but 1712 that the requested operation could not be performed for reasons 1713 unspecified at the IDUP-GSS-API level. 1715 Adams Document Expiration: 26 May 1997 33 1717 Using the security environment referenced by env_handle, initialize 1718 the data structures required to begin the process of unprotecting a 1719 P-IDU. The caller will be alerted as to which services were applied 1720 to the P-IDU in the returned Services_to_Receive set of parameters. 1722 If unprotection will be applied more than once to a given P-IDU, it 1723 is the responsibility of the calling application to remember if a 1724 service solicitation has been responded to previously (i.e., if the 1725 requested service has already been generated / sent for that P-IDU) 1726 and thus ignore subsequent solicitations on unprotect. 1728 The time flags indicate whether to consult trusted, untrusted, or no 1729 time (if both flags are FALSE) during the unprotection operation. If 1730 the current time is not to be checked, then unprotection may be 1731 successful even if the protector's key has expired since the P-IDU 1732 was generated (that is, if the Validity period -- as specified in 1733 the Quality parameter bundle -- has expired). 1735 If the underlying mechanism supports it and if this information is 1736 contained in the token, information regarding the originator (that 1737 is, the entity which used the protection set of calls to generate 1738 this token) is returned in the Prot_Information parameter bundle. 1740 2.3.7. IDUP_Unprotect call 1742 Inputs: 1744 o env_handle ENVIRONMENT HANDLE, 1746 o input_buffer OCTET STRING 1748 Outputs: 1750 o major_status INTEGER, 1752 o minor_status INTEGER, 1754 o output_buffer OCTET STRING 1756 Return major_status codes: 1758 o GSS_S_COMPLETE indicates that the input_buffer has successfully 1759 been included in the unprotection computation. 1761 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1762 for the env_handle provided. 1764 o GSS_S_FAILURE indicates that the environment is recognized, but 1765 that the requested operation could not be performed for reasons 1766 unspecified at the IDUP-GSS-API level. 1768 Using the security environment referenced by env_handle, continue the 1769 unprotection processing on the data in input_buffer, putting any 1770 resulting IDU data in output_buffer (if required). 1772 Adams Document Expiration: 26 May 1997 34 1774 2.3.8. IDUP_End_Unprotect call 1776 Inputs: 1778 o env_handle ENVIRONMENT HANDLE, 1780 Outputs: 1782 o major_status INTEGER, 1784 o minor_status INTEGER, 1786 o Prot_Information PARAMETER BUNDLE, 1788 o Services_to_Receive SET OF Unprot_Service, 1790 o final_idu_buffer OCTET STRING, 1792 o Service_Verification_Info PARAMETER BUNDLE, 1793 -- used only if target is on "service_to" list in Unprot_Service 1795 o service_verification_info_id INTEGER, 1796 -- used only if target is on "service_to" list in Unprot_Service 1798 Return major_status codes: 1800 o GSS_S_COMPLETE indicates that the unprotect computation was 1801 successful. Any residual IDU data will be returned in 1802 final_idu_buffer. 1804 o IDUP_S_INCOMPLETE indicates that the unprotection of the P-IDU 1805 is not yet complete (i.e., a determination cannot yet be made on 1806 the validity of the P-IDU). The application should call 1807 IDUP_Form_Complete_PIDU and then should call this function again 1808 with the complete P-IDU. 1810 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1811 supplied is too small to hold the generated data. The application 1812 should continue calling this routine (until GSS_S_COMPLETE is 1813 returned) in order to get all remaining data. 1815 o GSS_S_BAD_SIG indicates that the received P-IDU contains an 1816 incorrect integrity field (e.g., signature or MAC) for the data. 1818 o IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU 1819 data origin auth. / integ. has either expired or been revoked. 1821 o IDUP_S_BAD_KE_KEY indicates that the key used to establish a key 1822 for confidentiality purposes between originator and target has 1823 either expired or been revoked. 1825 o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU 1826 cannot be completed because the encrypted IDU was invalid/defec- 1827 tive (e.g., the final block was short or had incorrect padding). 1829 Adams Document Expiration: 26 May 1997 35 1831 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1832 for the env_handle provided. 1834 o GSS_S_FAILURE indicates that the environment is recognized, but 1835 that the requested operation could not be performed for reasons 1836 unspecified at the IDUP-GSS-API level. 1838 Using the security environment referenced by env_handle, complete the 1839 unprotection processing on the data and return the appropriate status 1840 code. If there is any residual IDU data it will be returned in 1841 final_idu_buffer. 1843 If the IDUP_S_INCOMPLETE major status value is returned, all output 1844 parameters are conditionally valid; the unprotection set of functions 1845 will have to be called again (perhaps with a complete P-IDU, as 1846 produced by IDUP_Form_Complete_PIDU) in order to get valid values for 1847 all parameters. "Conditional validity" may arise, for example, if 1848 all relevant certificates verify correctly, but it is not yet past 1849 the time up to which the current policy allows the authorities 1850 involved to repudiate their keys. 1852 If the underlying mechanism supports it and if this information is 1853 contained in the token, information regarding the originator (that 1854 is, the entity which used the protection set of calls to generate 1855 this token) is returned in the Prot_Information parameter bundle. 1856 This information may or may not be omitted if it was returned by the 1857 IDUP_Start_Unprotect() call. 1859 Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the 1860 concept of error tokens transferred between sender and recipient 1861 since the protection and unprotection of an IDU may be separated by 1862 an indefinite amount of time and may or may not be performed by the 1863 same entity. 1865 Adams Document Expiration: 26 May 1997 36 1867 2.4. Special-Purpose Calls 1869 2.4.1. Relationship to GSS-API 1871 The special-purpose call described in this section has no analog 1872 in GSS-API [RFC-1508]. This call is used to complete a P-IDU (that 1873 is, to generate a P-IDU which can be unprotected successfully with 1874 no additional data at any time during its validity period). This 1875 call may not be supported by all underlying IDUP mechanisms or 1876 implementations. 1878 2.4.2. IDUP_Form_Complete_PIDU call 1880 Inputs: 1882 o env_handle ENVIRONMENT HANDLE, 1884 o single_pidu_buffer OCTET STRING, 1886 o partial_pidu_buffer OCTET STRING, 1887 -- an arbitrary-sized piece of the full pidu token. Used if pidu 1888 -- will be input a buffer at a time (except that the final buffer 1889 -- must be passed in final_pidu_buffer rather than 1890 -- partial_pidu_buffer). Only one of single_pidu_buffer and 1891 -- partial(final)_pidu_buffer can have nonzero length. 1893 o final_pidu_buffer OCTET STRING, 1895 Outputs: 1897 o major_status INTEGER, 1899 o minor_status INTEGER, 1901 o pidu_token_out OCTET STRING 1903 o call_again_before INTEGER, 1905 o call_again_after INTEGER, 1907 Adams Document Expiration: 26 May 1997 37 1909 Return major_status codes: 1911 o GSS_S_COMPLETE indicates that the completion of P-IDU generation 1912 was successful. 1914 o GSS_S_CONTINUE_NEEDED indicates that the buffer supplied for 1915 pidu_token_out is too small to hold the generated data. The 1916 application should continue calling this routine (until 1917 GSS_S_COMPLETE is returned) in order to get all remaining data. 1919 o IDUP_S_INCOMPLETE indicates that the generation of the P-IDU 1920 is not yet complete. The application should call this function 1921 again before the time given in call_again_before (if not NULL), 1922 or after the time given in call_again_after (if not NULL), or 1923 both (if neither are NULL). 1925 o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 1926 does not support the service requested. 1928 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 1929 on the input P-IDU token failed, preventing further processing 1930 from being performed with that token. 1932 o GSS_S_FAILURE indicates that the environment is recognized, but 1933 that the requested operation could not be performed for reasons 1934 unspecified at the IDUP-GSS-API level. 1936 Using the security environment referenced by env_handle, complete the 1937 generation of a P-IDU token and return the appropriate status value 1938 along with the completed token (if available). Such a call may be 1939 used, for example, for the purpose of batch evidence generation on an 1940 "evidence server". A local machine may be able to use the protection 1941 set of calls to fill out most of an evidence token and then send a 1942 number of these to a batch processor which forms the complete 1943 evidence tokens (perhaps by adding a certification path, or a 1944 timestamp and signature from a timestamping authority). As another 1945 example, on the receiving end an application may make such a call in 1946 order to collect all the information necessary to unprotect a P-IDU 1947 (such as all relevant certificates and Certificate Revocation Lists); 1948 this will ensure that the calls to the unprotection set of operations 1949 will be entirely local (i.e., can be performed off-line) and fast. 1951 Note that the complete P-IDU generated will be formed using trusted 1952 time if this is available in the environment referenced by env_handle 1953 and will use untrusted time or no time otherwise (depending on what 1954 is available). 1956 Adams Document Expiration: 26 May 1997 38 1958 2.5. Support calls 1960 2.5.1. Relationship to GSS-API 1962 Support calls in IDUP-GSS-API are to be understood and used as 1963 described in GSS-API [RFC-1508]. The calls GSS_Display_status(), 1964 GSS_Indicate_mechs(), GSS_Compare_name(), GSS_Display_name(), 1965 GSS_Import_name(), GSS_Release_name(), GSS_Release_buffer(), and 1966 GSS_Release_oid_set() are unchanged. 1968 2.5.2. IDUP_Parse_token call 1970 Inputs: 1972 o input_token OCTET STRING 1974 Outputs: 1976 o major_status INTEGER, 1978 o minor_status INTEGER, 1980 o mech_type OBJECT IDENTIFIER, 1982 Return major_status codes: 1984 o GSS_S_COMPLETE indicates that the input_token could be parsed for 1985 all relevant fields. 1987 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 1988 recognized, but that its associated credentials have expired, so 1989 that the requested operation cannot be performed. 1991 o GSS_S_DEFECTIVE_TOKEN indicates that the mechanism type could be 1992 parsed, but that either the other fields could not be determined 1993 from the input_token, or their values did not correspond to valid 1994 values for that mechanism. 1996 o GSS_S_FAILURE indicates that the mechanism type could not be 1997 parsed (for example, the token may be corrupted). 1999 IDUP_Parse_Token() is used to return to an application the attributes 2000 which correspond to a given input token. Since IDUP-GSS-API tokens 2001 are meant to be opaque to the calling application, this function 2002 allows the application to determine information about the token 2003 without having to violate the opaqueness intention of IDUP. Of 2004 primary importance is the mechanism type, which the application can 2005 then use as input to the IDUP_Establish_Env() call in order to 2006 establish the correct environment in which to have the token 2007 processed. Other token attributes may be added as outputs of this 2008 call in future versions of this specification, if required. 2010 Adams Document Expiration: 26 May 1997 39 2012 If all tokens are framed as suggested in RFC-1508, Appendix B 2013 (mandated in the Kerberos V5 GSS mechanism [RFC 1964] and in the SPKM 2014 GSS Mechanism [RFC 2025], then any mechanism implementation should be 2015 able to return the mech_type parameter for any uncorrupted input 2016 token. If the mechanism implementation whose IDUP_Parse_token() 2017 function is being called does recognize the token, it can return 2018 other token attributes, if specified. 2020 2.5.3. IDUP_Get_policy_info call 2022 Inputs: 2024 o policy_id OBJECT IDENTIFIER 2026 Outputs: 2028 o major_status INTEGER, 2030 o minor_status INTEGER, 2032 o policy_version INTEGER, 2034 o policy_effective_time INTEGER, 2036 o policy_expiry_time INTEGER, 2038 o supported_services SET OF Service_Descriptor, 2040 o supported_mechanisms SET OF Mechanism_Descriptor 2042 Return major_status codes: 2044 o GSS_S_COMPLETE indicates that the policy_id was recognized and 2045 all relevant fields have been returned. 2047 o GSS_S_FAILURE indicates that the policy_id was not recognized. 2049 This call (which need not be supported by all underlying mechanisms 2050 or implementations) allows the application to retrieve information 2051 pertaining to a given policy_id. Policies define the following: 2053 - rules for the protection of IDUs, such as trusted third 2054 parties which may be involved in P-IDU generation, the roles 2055 in which they may be involved, and the duration for which the 2056 generated P-IDU is valid; 2058 Adams Document Expiration: 26 May 1997 40 2060 - rules for the unprotection of P-IDUs, such as the interval 2061 during which a trusted third party may legitimately declare its 2062 key to have been compromised or revoked; and 2064 - rules for adjudication, such as which authorities may be used 2065 to adjudicate disputes. 2067 The policy itself may be used by an adjudicator when resolving a 2068 dispute. For example, the adjudicator might refer to the policy to 2069 determine whether the rules for generation of the P-IDU have been 2070 followed. 2072 The following parameter bundles are associated with this call. 2074 o Service_Descriptor PARAMETER BUNDLE, 2076 o service_type OBJECT IDENTIFIER, 2078 o service_validity_duration INTEGER, 2080 o must_use_trusted_time BOOLEAN 2082 o Mechanism_Descriptor PARAMETER BUNDLE, 2084 o mechanism_type OBJECT IDENTIFIER, 2086 o Authority_List PARAMETER BUNDLE, 2088 o maximum_time_skew INTEGER 2089 -- maximum permissible difference between P-IDU generation 2090 -- time and the time of countersignature from a time 2091 -- service (if required). This parameter is unused if 2092 -- trusted time is not required. 2094 o Authority_List PARAMETER BUNDLE, 2096 o authority_name INTERNAL NAME, 2098 o authority_role OCTET STRING, 2100 o last_revocation_check_offset INTEGER 2101 -- may be greater than 0 or less than 0. The value of 2102 -- this parameter is added to P-IDU generation time to 2103 -- get latest time at which the mechanism will check to 2104 -- see if this authority's key has been revoked. 2106 An example of the use of the last parameter in Authority_List is as 2107 follows. If an authority has a defined last_revocation_check_offset 2108 of negative one hour, then all revocations taking effect earlier than 2109 one hour before the generation of a P-IDU will render that P-IDU 2110 invalid; no revocation taking place later than one hour before the 2111 generation of the P-IDU will affect the P-IDU's validity. 2113 Note that both the maximum_time_skew and the 2114 last_revocation_check_offset values are given in minutes. 2116 Adams Document Expiration: 26 May 1997 41 2118 3. Related Activities 2120 In order to implement the IDUP-GSS-API atop existing, emerging, and 2121 future security mechanisms, the following is necessary: 2123 - object identifiers must be assigned to candidate IDUP-GSS-API 2124 mechanisms and the name types which they support; and 2126 - concrete data element (i.e., token and parameter bundle) formats 2127 must be defined for candidate mechanisms. 2129 Calling applications must implement formatting conventions which will 2130 enable them to distinguish IDUP-GSS-API P-IDUs from other 2131 IDUs in their environment. 2133 Concrete language bindings are required for the programming 2134 environments in which the IDUP-GSS-API is to be employed; such a 2135 binding for the C language are available in the Internet Draft 2136 [IDUP-C]. 2138 4. Acknowledgments 2140 Many thanks are due to Tim Moses and Dhanya Thakkar of Nortel, 2141 Denis Pinkas of Bull, and David Kurn of Tandem Computers for a number 2142 of helpful comments. 2144 5. Security Considerations 2146 Security issues are discussed throughout this memo. 2148 Adams Document Expiration: 26 May 1997 42 2150 6. REFERENCES 2152 [MSP]: U.S. National Security Agency, "Message Security 2153 Protocol", Secure Data Network System SDN.701, March 1994. 2155 [RFC-1421]: J. Linn, "Privacy Enhancement for Internet Electronic 2156 Mail: Part I: Message Encryption and Authentication Procedures", 2157 RFC 1421. 2159 [RFC-1508]: J. Linn, "Generic Security Service Application Program 2160 Interface", RFC 1508. 2162 [GSSv2]: J. Linn, "Generic Security Service Application Program 2163 Interface, Version 2", Internet Draft draft-ietf-cat-gssv2-0x.txt 2164 (work in progress). 2166 [RFC 1964]: J. Linn, "The Kerberos Version 5 GSS-API Mechanism", 2167 RFC 1964. 2169 [RFC 2025]: C. Adams, "The Simple Public-Key GSS-API Mechanism 2170 (SPKM)", RFC 2025. 2172 [IDUP-C]: D. Thakkar, D. Grebovich, "Independent Data Unit 2173 Protection Generic Security Service Application Program Interface: C- 2174 bindings", Internet Draft draft-ietf-cat-idup-cbind-0x.txt (work in 2175 progress). 2177 [ISO/IEC]: 2nd ISO/IEC CD 13888-1, "Information technology - 2178 Security techniques - Non-repudiation - Part 1: General Model", 2179 ISO/IEC JTC 1/SC 27, May 30, 1995 2181 7. Author's Address 2183 Carlisle Adams 2184 Nortel Secure Networks 2185 P.O.Box 3511, Station C 2186 Ottawa, Ontario, CANADA K1Y 4H7 2188 Phone: +1 613.763.9008 2189 E-mail: cadams@entrust.com 2191 Adams Document Expiration: 26 May 1997 43 2193 APPENDIX A 2195 MECHANISM-INDEPENDENT TOKEN FORMAT 2197 This appendix specifies a mechanism-independent level of 2198 encapsulating representation for IDUP-GSS-API tokens, incorporating 2199 an identifier of the mechanism type to be used when processing those 2200 tokens. Use of this format (with ASN.1-encoded data elements 2201 represented in BER, constrained in the interests of parsing 2202 simplicity to the Distinguished Encoding Rule (DER) BER subset 2203 defined in X.509, clause 8.7) is recommended to the designers of 2204 IDUP-GSS-API implementations based on various mechanisms, so that 2205 tokens can be interpreted unambiguously at IDUP-GSS-API peers. There 2206 is no requirement that the mechanism-specific token data element be 2207 encoded in ASN.1 BER. 2209 -- top-level token definition to frame different mechanisms 2211 IDUP-GSS-API DEFINITIONS ::= 2212 BEGIN 2213 MechType ::= OBJECT IDENTIFIER 2215 Token ::= [APPLICATION 0] IMPLICIT SEQUENCE { 2216 thisMech MechType, 2217 token ANY DEFINED BY thisMech 2218 -- contents mechanism-specific 2219 } 2220 END 2222 Adams Document Expiration: 26 May 1997 44 2224 APPENDIX B 2226 EXAMPLES OF IDUP USE 2228 This appendix provides examples of the use of IDUP to do IDU protec- 2229 tion and unprotection. It should not be regarded as constrictive to 2230 implementations or as defining the only means through which 2231 IDUP-GSS-API functions can be realized with particular underlying 2232 technology, and does not demonstrate all IDUP-GSS-API features. 2234 B.1. Simple Mechanism, Single Buffer 2236 To illustrate the simplest possible case, consider an underlying IDUP 2237 mechanism which does straightforward encryption/decryption and 2238 signing/verification only; none of the other possible services, such 2239 as creation of proof-of-origin evidence, requests for proof-of- 2240 delivery evidence, or use of trusted time, are supported. PEM 2241 [RFC-1421] is one example of a mechanism which fits this description. 2242 Furthermore (again for simplicity), assume that encapsulation is 2243 chosen by the calling application during IDU protection. 2245 The following parameter bundle uses and defaults would therefore be 2246 specified in the relevant IDUP mechanism document. 2248 Mech_Specific_Info 2249 - NOT USED (the only acceptable input, therefore, is NULL) 2251 Idu_Sensitivity 2252 - NOT USED (the only acceptable input, therefore, is NULL) 2254 Service_Creation_Info 2255 - NOT USED (the only acceptable input, therefore, is NULL) 2257 Service_Verification_Info 2258 - NOT USED (the only acceptable input, therefore, is NULL) 2260 Quality 2261 - the qop_algs parameter must be supported, with a suitable 2262 DEFAULT value specified; 2263 - suitable DEFAULT values for validity, policy_id, and 2264 allow_policy_mapping must be specified (it may be an 2265 implementation option as to whether these parameters are 2266 explicitly modifiable by the calling application, or whether 2267 NULLs are the only acceptable input) 2269 Idu_Information 2270 - the idu_type parameter must have a value representing a suitable 2271 IDU type (for example, in PEM a value representing the string 2272 "RFC822" or some other valid "Content-Domain" would be used), 2273 with a suitable DEFAULT value specified; 2274 - the idu_title parameter is NOT USED (the only acceptable input, 2275 therefore, is NULL) 2277 Adams Document Expiration: 26 May 1997 45 2279 Prot_Information 2280 - the originator_name and idu_type (in Idu_Information) parameters 2281 are read from the encapsulating information and output by 2282 IDUP_Start_Unprotect; 2283 - all other parameters are NOT USED (and therefore NULL) 2285 Special_Conditions 2286 - NOT USED (the only acceptable input, therefore, is NULL) 2288 Target_Info 2289 - this bundle is used as described in IDUP; no DEFAULT values are 2290 specified 2292 General_Service_Data 2293 - the unencapsulated_token parameter is used if 2294 encapsulation_request is FALSE; 2295 - the minor_status parameter is used to return minor status values 2296 as specified by the mechanism document 2298 Prot_Service 2299 - the prot_service_type parameter may have a value of "1" 2300 ("perform unsolicited service") or NULL (which specifies the 2301 DEFAULT value of "1"); 2302 - the service_id parameter must have a value representing 2303 "PER_CONF" or "PER_DOA"; 2304 - the parameters Service_Creation_Info, service_to, 2305 Service_Verification_Info, and service_verification_info_id are 2306 NOT USED (and therefore NULL) 2308 Unprot_Service 2309 - the unprot_service_type parameter will always have a value of 2310 "1" ("receive unsolicited service"); 2311 - the service_id parameter will have a value representing 2312 "REC_CONF" or "REC_DOA"; 2313 - the parameters service_verification_info_id, 2314 Service_Verification_Info, service_to, and 2315 Service_Creation_Info, are NOT USED (and therefore NULL) 2317 Assuming that the calling application has only a single buffer of 2318 data to protect/unprotect, the following sequence of operations must 2319 be performed by the sender and receivers (subsequent to environment 2320 establishment). 2322 SENDER (any parameters not listed below are given the value NULL): 2324 Set 2325 env_handle = environment handle in use; 2326 encapsulation_request = TRUE; 2327 single_idu_buffer = data buffer; 2328 Target_Info.targ_names = receiver names; 2329 P_Services.Prot_Service_1.service_id = PER_CONF; 2330 P_Services.Prot_Service_2.service_id = PER_DOA; 2332 Adams Document Expiration: 26 May 1997 46 2334 Call 2335 IDUP_Start_Protect() with above input parameters 2336 Check 2337 major_status. If not GSS_S_COMPLETE, check 2338 minor_status, 2339 Target_Info.bad_targ_names / Target_Info.bad_targ_status, 2340 P_Services.Prot_Service_1.General_Service_Data.minor_status, 2341 P_Services.Prot_Service_2.General_Service_Data.minor_status 2342 (as required) for more detailed information. 2344 Send 2345 Output parameter pidu_buffer to receiver. 2347 RECEIVER (any parameters not listed below are given the value NULL): 2349 Set 2350 env_handle = environment handle in use; 2351 single_pidu_buffer = received data buffer; 2353 Call 2354 IDUP_Start_Unprotect() with above input parameters 2355 Check 2356 major_status. If not GSS_S_COMPLETE, check 2357 minor_status, 2358 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2359 R_Services.Unprot_Service_2.General_Service_Data.minor_status 2360 (as required) for more detailed information 2362 Utilize 2363 R_Services.Unprot_Service_1/2.service_id, 2364 (to determine which services were applied by the originator) 2365 R_Services.Unprot_Service_1/2.Quality, 2366 (to determine the corresponding qualities of the services) 2367 Prot_Information.originator_name, 2368 (to determine the name of the originator) 2369 single_idu_buffer 2370 (to retrieve the unprotected data). 2372 Adams Document Expiration: 26 May 1997 47 2374 B.2. Simple Mechanism, Multiple Buffers 2376 To illustrate the next step up in complexity, consider the use of the 2377 simple IDUP mechanism described above with multiple data buffers. In 2378 particular, consider the case in which a large data file is to be 2379 signed. For this example, assume that the calling application does 2380 not wish to use encapsulation. 2382 Note that the parameter bundle uses and defaults are as specified in 2383 C.1. above. 2385 SENDER (any parameters not listed below are given the value NULL): 2387 Set 2388 env_handle = environment handle in use; 2389 encapsulation_request = FALSE; 2390 P_Services.Prot_Service.service_id = PER_DOA; 2392 Call 2393 IDUP_Start_Protect() with above input parameters 2394 Check 2395 major_status. If not GSS_S_COMPLETE, check 2396 minor_status, 2397 P_Services.Prot_Service.General_Service_Data.minor_status 2398 (as required) for more detailed information. 2400 For each buffer of input data: 2401 Set 2402 input_buffer = buffer 2403 Call 2404 IDUP_Protect() with above input parameter 2405 Check 2406 major_status. If not GSS_S_COMPLETE, check 2407 minor_status 2409 Call 2410 IDUP_End_Protect() 2411 Check 2412 major_status. If not GSS_S_COMPLETE, check 2413 minor_status, 2414 P_Services.Prot_Service.General_Service_Data.minor_status 2415 (as required) for more detailed information. 2417 Send 2418 P_Services.Prot_Service.General_Service_Data.unencapsulated_token, 2419 the file for which the signature was calculated (if required) 2420 to receiver. 2422 Adams Document Expiration: 26 May 1997 48 2424 RECEIVER (any parameters not listed below are given the value NULL): 2426 Set 2427 env_handle = environment handle in use; 2428 partial_pidu_buffer = received unencapsulated token; 2430 Call 2431 IDUP_Start_Unprotect() with above input parameters 2432 Check 2433 major_status. If not GSS_S_COMPLETE, check 2434 minor_status, 2435 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2436 (as required) for more detailed information 2438 For each buffer of input data: 2439 Set 2440 input_buffer = buffer 2441 Call 2442 IDUP_Unprotect() with above input parameter 2443 Check 2444 major_status. If not GSS_S_COMPLETE, check 2445 minor_status 2447 Call 2448 IDUP_End_Unprotect() 2449 Check 2450 major_status. If not GSS_S_COMPLETE, check 2451 minor_status, 2452 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2453 (as required) for more detailed information. 2455 Utilize 2456 R_Services.Unprot_Service_1.service_id, 2457 (to determine which service was applied by the originator; note 2458 that Unprot_Service_2 will have NULL in unprot_service_type 2459 to indicate that it is not used) 2460 R_Services.Unprot_Service_1.Quality, 2461 (to determine the corresponding quality of the service) 2462 Prot_Information.originator_name, (from IDUP_Start_Unprotect) 2463 (to determine the name of the signer) 2464 major_status (from IDUP_End_Unprotect) 2465 (to determine pass/fail status of signature verification). 2467 Adams Document Expiration: 26 May 1997 49 2469 B.3. More Sophisticated Mechanism, Small Application Buffers 2471 To illustrate a higher level of complexity, consider the use of a 2472 more sophisticated IDUP mechanism and a calling application with 2473 small data buffers. In particular, consider the case in which a very 2474 small e-mail message is to be encrypted for a relatively large 2475 receiver list (R), some subset of whom (r) will be asked to send 2476 proofs of receipt of the message to some other subset (L) (which 2477 includes the originator). So that the example is not unnecessarily 2478 complicated, assume again that the originating application uses 2479 encapsulation. 2481 The uses and defaults for the various parameter bundles for this 2482 mechanism would be specified in the relevant IDUP mechanism document 2483 as follows. 2485 Mech_Specific_Info 2486 - NOT USED (the only acceptable input, therefore, is NULL) 2488 Idu_Sensitivity 2489 - NOT USED (the only acceptable input, therefore, is NULL) 2491 Service_Creation_Info 2492 - used to create "proof of delivery" evidence (but actual 2493 structure is opaque to calling application) 2495 Service_Verification_Info 2496 - used to verify "proof of delivery" evidence (but actual 2497 structure is opaque to calling application) 2499 Quality 2500 - the qop_algs parameter must be supported, with a suitable 2501 DEFAULT value specified; 2502 - suitable DEFAULT values for validity, policy_id, and 2503 allow_policy_mapping must be specified (it may be an 2504 implementation option as to whether these parameters are 2505 explicitly modifiable by the calling application, or whether 2506 NULLs are the only acceptable input) 2508 Idu_Information 2509 - the idu_type parameter must have a value representing a suitable 2510 IDU type, with a suitable DEFAULT value specified; 2511 - the idu_title parameter must have a value representing a 2512 suitable IDU title, with a suitable DEFAULT value specified 2514 Prot_Information 2515 - the originator_name, protection_time, and idu_type / idu_title 2516 (in Idu_Information) parameters are read from the contained 2517 header information and output by IDUP_Start_Unprotect; 2519 Special_Conditions 2520 - the parameter prot_oper_id is NOT USED (the only acceptable 2521 input, therefore, is NULL); 2522 - trusted or untrusted time may be selected by the calling 2523 application, with a suitable DEFAULT value specified 2525 Adams Document Expiration: 26 May 1997 50 2527 Target_Info 2528 - this bundle is used as described in IDUP; no DEFAULT values are 2529 specified 2531 General_Service_Data 2532 - the unencapsulated_token parameter is used if 2533 encapsulation_request is FALSE; 2534 - the minor_status parameter is used to return minor status values 2535 as specified by the mechanism document 2537 Prot_Service 2538 - the prot_service_type parameter may have a value of "1" 2539 ("perform unsolicited service"), "2" ("perform solicited 2540 service"), "3" (perform service solicitation), or NULL (which 2541 specifies the DEFAULT value of "1"); 2542 - the service_id parameter must have a value representing 2543 "PER_CONF", "PER_DOA", "PER_POO", or "PER_POD"; 2544 - the parameters Service_Creation_Info, service_to, 2545 Service_Verification_Info, and service_verification_info_id are 2546 used when required by the IDUP operation 2548 Unprot_Service 2549 - the unprot_service_type parameter may have a value of "1" 2550 ("receive unsolicited service"), "2" ("receive solicited 2551 service"), or "3" (receive service solicitation); 2552 - the service_id parameter will have a value representing 2553 "REC_CONF", "REC_DOA", "REC_POO", or "REC_POD"; 2554 - the parameters service_verification_info_id, 2555 Service_Verification_Info, service_to, and 2556 Service_Creation_Info, are used when required by the IDUP 2557 operation 2559 SENDER (any parameters not listed below are given the value NULL): 2561 Set 2562 env_handle = environment handle in use; 2563 Idu_Information.idu_type = value for "e-mail document"; 2564 Idu_Information.idu_title = "Contract 1234"; 2565 Special_Conditions.use_trusted_time = TRUE; 2566 encapsulation_request = TRUE; 2567 single_idu_buffer = very small e-mail message; 2568 Target_Info.targ_names = receiver names (R); 2569 Prot_Service_1.prot_service_type = "1"; 2570 Prot_Service_1.service_id = PER_CONF; 2571 Prot_Service_2.prot_service_type = "3"; 2572 Prot_Service_2.service_id = PER_POD; 2573 Prot_Service_2.General_Service_Data.Target_Info.targ_names 2574 = "receipts from" list (r); 2575 Prot_Service_2.service_to = "receipts to" list (L); 2576 P_Services.Prot_Service_1 = Prot_Service_1; 2577 P_Services.Prot_Service_2 = Prot_Service_2; 2579 Adams Document Expiration: 26 May 1997 51 2581 Call 2582 IDUP_Start_Protect() with above input parameters 2583 Check 2584 major_status. If not GSS_S_COMPLETE, 2585 while major_status == GSS_S_CONTINUE_NEEDED 2586 Save 2587 pidu_buffer, 2588 Call 2589 IDUP_Start_Protect() (to get next portion of pidu_buffer) 2590 Check 2591 major_status, 2592 minor_status, 2593 Target_Info.bad_targ_names / Target_Info.bad_targ_status, 2594 P_Services.Prot_Service_1.General_Service_Data.minor_status, 2595 P_Services.Prot_Service_2.General_Service_Data.minor_status 2596 (as required) for more detailed information. 2598 Save 2599 Prot_Service_2.Service_Verification_Info, 2600 Prot_Service_2.service_verification_info_id 2602 Send 2603 All saved buffers of pidu_buffer to receiver list (R). 2605 RECEIVER (ON RECEIVER LIST (R)): 2606 (any parameters not listed below are given the value NULL) 2608 Set 2609 env_handle = environment handle in use; 2610 partial_pidu_buffer = initial buffer of received p-idu; 2612 Call 2613 IDUP_Start_Unprotect() with above input parameters 2614 While major_status == IDUP_S_MORE_PIDU_NEEDED, 2615 Set 2616 partial_pidu_buffer = next buffer of p-idu 2617 Call 2618 IDUP_Start_Unprotect() 2619 Check 2620 major_status, 2621 minor_status, 2622 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2623 R_Services.Unprot_Service_2.General_Service_Data.minor_status, 2624 (as required) for more detailed information 2626 Save 2627 initial_idu_buffer (if non-empty) 2629 Adams Document Expiration: 26 May 1997 52 2631 Set 2632 input_buffer = remaining p-idu buffer 2633 Call 2634 IDUP_Unprotect() with above input parameter 2635 Check 2636 major_status. If not GSS_S_COMPLETE, check 2637 minor_status 2638 Save 2639 output_buffer 2641 Call 2642 IDUP_End_Unprotect() 2643 Check 2644 major_status. If not GSS_S_COMPLETE, check 2645 minor_status, 2646 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2647 R_Services.Unprot_Service_2.General_Service_Data.minor_status, 2648 (as required) for more detailed information. 2650 Utilize 2651 R_Services.Unprot_Service_1/2.service_id, 2652 (to determine which services were applied by the originator) 2653 R_Services.Unprot_Service_1/2.Quality, 2654 (to determine the corresponding qualities of the service) 2655 Prot_Information.originator_name/protection_time and 2656 Prot_Information.Idu_Information.idu_type/idu_title, 2657 (from IDUP_Start_Unprotect) (to determine originator info.) 2658 R_Services.Unprot_Service_2.General_Service_Data.Target_Info. 2659 targ.names, (to determine if rec. is in "receipts from" (r)) 2660 Service_Verification_Info/service_verification_info_id 2661 (to determine if receiver is in "receipts to" list (L)) 2663 If receiver is in "receipts from" list (r) 2664 Save 2665 R_Services.Unprot_Service_2.service_to, 2666 R_Services.Unprot_Service_2.Service_Creation_Info 2668 If receiver is in "receipts to" list (L) 2669 Save 2670 Service_Verification_Info, 2671 service_verification_info_id 2673 Adams Document Expiration: 26 May 1997 53 2675 RECEIVER (ON "RECEIPTS FROM" LIST (r)): 2676 (procedure to generate receipt) 2678 Set 2679 env_handle = environment handle in use; 2680 Target_Info.targ_names = service_to 2681 Prot_Service_1.prot_service_type = "2"; 2682 Prot_Service_1.service_id = "PER_POD"; 2683 Prot_Service_1.Service_Creation_Info = Service_Creation_Info; 2684 P_Services.Prot_Service_1 = Prot_Service_1 2686 Call 2687 IDUP_Start_Protect() with above input parameters 2688 Check 2689 major_status. If not GSS_S_COMPLETE, check 2690 minor_status, 2691 P_Services.Prot_Service_1.General_Service_Data.minor_status 2692 (as required) for more detailed information. 2694 Send 2695 pidu_buffer to "receipts to" list (L) 2697 RECEIVER (ON "RECEIPTS TO" LIST (L)): 2698 (procedure to process received receipt) 2700 Set 2701 env_handle = environment handle in use; 2702 single_pidu_buffer = received p-idu buffer (if it fits in a single 2703 buffer; otherwise use partial_pidu_buffer and make multiple 2704 calls, as above) 2706 Call 2707 IDUP_Start_Unprotect() with above input parameters 2708 If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED 2709 Utilize 2710 R_Services.Unprot_Service_1.service_verification_info.id 2711 (to assist in locating necessary Service_Verification_Info) 2712 Set 2713 R_Services.Unprot_Service_1.Service_Verification_Info 2714 = Service_Verification_Info 2715 Call 2716 IDUP_Start_Unprotect() with above input parameters 2717 Check 2718 major_status, 2719 minor_status, 2720 R_Services.Unprot_Service_1.General_Service_Data.minor_status 2721 (as required) for more detailed information. 2723 Utilize 2724 R_Services.Unprot_Service_1.service_id, 2725 (to determine that this is a "proof of delivery" evidence) 2726 R_Services.Unprot_Service_1.Quality, 2727 Prot_Information.originator_name, (for evidence generator info.) 2728 major_status (to determine pass/fail status of evi. verif.). 2730 Adams Document Expiration: 26 May 1997 54