idnits 2.17.1 draft-ietf-cat-idup-gss-05.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-23) 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 5 longer pages, the longest (page 9) being 59 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 532 has weird spacing: '...ish_Env esta...' == Line 540 has weird spacing: '...Protect begi...' == Line 546 has weird spacing: '...Protect pro...' == Line 551 has weird spacing: '...protect end ...' == Line 552 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.) -- The document date (June 11, 1996) is 10178 days in the past. Is this intentional? 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 2138, 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-kerb5gss-0x - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'KRB5' -- No information found for draft-ietf-cat-spkmgss-0x - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SPKM' -- 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 (==), 11 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-05.txt June 11, 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: 11 Dec. 1996 1 57 As with RFC-1508, this IDUP-GSS-API definition provides security 58 services to callers in a generic fashion, supportable with a range of 59 underlying mechanisms and technologies and hence allowing source- 60 level portability of applications to different environments. This 61 specification defines IDUP-GSS-API services and primitives at a level 62 independent of underlying mechanism and programming language environ- 63 ment, and is to be complemented by other, related specifications: 65 - documents defining specific parameter bindings for particular 66 language environments; 67 - documents defining token formats, protocols, and procedures to 68 be implemented in order to realize IDUP-GSS-API services atop 69 particular security mechanisms. 71 TABLE OF CONTENTS 72 1. IDUP-GSS-API Characteristics and Concepts .................. 3 73 1.1. IDUP-GSS-API Constructs .................................. 5 74 1.1.1. Credentials ............................................ 5 75 1.1.2. Tokens ................................................. 5 76 1.1.3. Security Environment ................................... 5 77 1.1.4. Mechanism Types ........................................ 5 78 1.1.5. Naming ................................................. 5 79 1.1.6. Channel Bindings ....................................... 6 80 1.2. IDUP-GSS-API Features and Issues ......................... 6 81 1.2.1. Status Reporting ....................................... 6 82 1.2.2. Per-IDU Security Service Availability .................. 7 83 1.2.3. Per-IDU Replay Detection and Sequencing ................ 7 84 1.2.4. Quality of Protection .................................. 7 85 1.2.5. The Provision of Time .................................. 10 86 2. Interface Descriptions ..................................... 10 87 2.1. Credential management calls .............................. 11 88 2.1.1. Relationship to GSS-API ................................ 11 89 2.2. Environment-level calls .................................. 12 90 2.2.1. Relationship to GSS-API ................................ 12 91 2.2.2. IDUP_Establish_Env call ................................ 13 92 2.2.3. IDUP_Abolish_Env call .................................. 15 93 2.2.4. IDUP_Inquire_Env call .................................. 16 94 2.3. Per-IDU calls ............................................ 17 95 2.3.1. Relationship to GSS-API ................................ 17 96 2.3.2. Parameter Bundles ...................................... 17 97 2.3.3. IDUP_Start_Protect ..................................... 21 98 2.3.4. IDUP_Protect ........................................... 24 99 2.3.5. IDUP_End_Protect ....................................... 25 100 2.3.6. IDUP_File_Protect ...................................... 26 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.3.10. IDUP_File_Unprotect .................................... 32 105 2.4. Special-Purpose calls .................................... 35 106 2.4.1. Relationship to GSS-API ................................ 35 107 2.4.5. IDUP_Form_Complete_PIDU ................................ 35 108 2.5. Support calls ............................................ 37 109 2.5.1. Relationship to GSS-API ................................ 37 110 2.5.2. IDUP_Parse_token call .................................. 37 111 2.5.3. IDUP_Get_Policy_Info ................................... 38 113 Adams Document Expiration: 11 Dec. 1996 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, B ................................................. 42 120 Appendix C .................................................... 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: 11 Dec. 1996 3 169 The following paragraphs provide an example illustrating the 170 dataflows involved in the use of the IDUP-GSS-API by the sender and 171 receiver of a P-IDU in a mechanism-independent fashion. The example 172 assumes that credential acquisition has already been completed by 173 both sides. Furthermore, the example does not cover all possible 174 options available in the protection/unprotection calls. 176 The sender first calls IDUP_Establish_Env() to establish a 177 security environment. Then, for the IDU to be protected the 178 sender calls IDUP_Start_Protect(), IDUP_Protect() for each buffer 179 of data, and IDUP_End_Protect() to complete the IDU protection. 180 The resulting P-IDU, which may (depending on whether or not 181 encapsulation was chosen/available) be either the token itself 182 or the logical concatenation of the token and the M-IDU, is now 183 ready to be sent to the target. The sender then calls 184 IDUP_Abolish_Env() to flush all environment-specific information. 186 The receiver first calls IDUP_Establish_Env() to establish a 187 security environment in order to unprotect the P-IDU. Then, for 188 the received P-IDU the receiver calls IDUP_Start_Unprotect(), 189 IDUP_Unprotect() for each buffer of data, and IDUP_End_Unprotect() 190 to complete the P-IDU unprotection. The receiver then calls 191 IDUP_Abolish_Env() to flush all environment-specific information. 193 It is important to note that absolutely no synchronization is implied 194 or expected between the data buffer size used by the sender as input 195 to the protection calls, the data buffer size used by the receiver as 196 input to the unprotection calls, and the block sizes required by the 197 underlying protection algorithms (integrity and confidentiality). 198 All these sizes are meant to be independent; furthermore, the data 199 buffer sizes used for the protection and unprotection calls are 200 purely a function of the local environment where the calls are made. 202 The IDUP-GSS-API design assumes and addresses several basic goals, 203 including the following. 205 Mechanism independence: The IDUP-GSS-API defines an interface to 206 cryptographically implemented security services at a generic level 207 which is independent of particular underlying mechanisms. For 208 example, IDUP-GSS-API-provided services can be implemented by 209 secret-key technologies or public-key approaches. 211 Protocol environment independence: The IDUP-GSS-API is independent 212 of the communications protocol suites which may be used to 213 transfer P-IDUs, permitting use in a broad range of protocol 214 environments. 216 Protocol association independence: The IDUP-GSS-API's security 217 environment construct has nothing whatever to do with 218 communications protocol association constructs, so that 219 IDUP-GSS-API services can be invoked by applications, wholly 220 independent of protocol associations. 222 Adams Document Expiration: 11 Dec. 1996 4 223 Suitability for a range of implementation placements: IDUP-GSS-API 224 clients are not constrained to reside within any Trusted Computing 225 Base (TCB) perimeter defined on a system where the IDUP-GSS-API is 226 implemented; security services are specified in a manner suitable 227 for both intra-TCB and extra-TCB callers. 229 1.1. IDUP-GSS-API Constructs 231 This section describes the basic elements comprising the 232 IDUP-GSS-API. 234 1.1.1. Credentials 236 Credentials in IDUP-GSS-API are to be understood and used as 237 described in GSS-API [RFC-1508]. 239 1.1.2. Tokens 241 Tokens in IDUP-GSS-API are to be understood and used as described in 242 GSS-API [RFC-1508] with the exception that there are no context-level 243 tokens generated by IDUP-GSS-API. The IDUP-GSS-API token 244 may (depending on the underlying mechanism) encapsulate the M-IDU or 245 may be logically concatenated with M-IDU prior to transfer to a 246 target; furthermore, for some evidence services the token may be sent 247 independently of any other data transfer. 249 1.1.3. Security Environment 251 The "security environment" in IDUP-GSS-API is entirely different from 252 the concept of security contexts used in GSS-API [RFC-1508]. Here, a 253 security environment exists within a calling application (that is, it 254 is purely local to the caller) for the purpose of protecting or 255 unprotecting one or more IDUs using a particular caller credential or 256 set of credentials. In GSS-API, on the other hand, a security 257 context exists between peers (the initiator and the target) for the 258 purpose of protecting, in real time, the data that is exchanged 259 between them. Although they are different concepts, the env_handle 260 in IDUP-GSS-API is similar to the context_handle in GSS-API in that 261 it is a convenient way of tying together the entire process of 262 protecting or unprotecting one or more IDUs using a particular 263 underlying mechanism. As with the GSS-API security contexts, a 264 caller can initiate and maintain multiple environments using the same 265 or different credentials. 267 1.1.4. Mechanism Types 269 Mechanism types in IDUP-GSS-API are to be understood and used as 270 described in GSS-API [RFC-1508]. 272 1.1.5. Naming 274 Naming in IDUP-GSS-API is to be understood and used as described in 275 GSS-API [RFC-1508]. 277 Adams Document Expiration: 11 Dec. 1996 5 278 1.1.6. Channel Bindings 280 The concept of channel bindings discussed in GSS-API [RFC-1508] is 281 not relevant to the IDUP-GSS-API. 283 1.2. IDUP-GSS-API Features and Issues 285 This section describes aspects of IDUP-GSS-API operations and of the 286 security services which the IDUP-GSS-API provides. It also provides 287 commentary on design issues. 289 1.2.1. Status Reporting 291 Status reporting in IDUP-GSS-API is to be understood and used as 292 described in GSS-API [RFC-1508], with the addition of the following 293 IDUP-GSS-API major status codes. 295 As with GSS-API, minor_status codes, which provide more detailed 296 status information than major_status codes, and which may include 297 status codes specific to the underlying security mechanism, are not 298 specified in this document. 300 Table 1: IDUP-GSS-API Major Status Codes 302 Fatal Error Codes 304 IDUP_S_BAD_TARG_INFO all target information is invalid or 305 unsuitable for IDU protection 307 IDUP_S_BAD_DOA_KEY DOA key has expired or been revoked 309 IDUP_S_BAD_KE_KEY key used for key establishment between 310 orig. and targ. has exp. or been revoked 312 IDUP_S_BAD_ENC_IDU encrypted IDU is defective/invalid 314 IDUP_S_INCOMPLETE 315 there is not enough info. in token for P-IDU verification 317 IDUP_S_SERV_VERIF_INFO_NEEDED 318 the Service_Verification_Info parameter bundle is required 320 IDUP_S_SERVICE_UNAVAIL mech. does not support requested service 322 IDUP_S_REQ_TIME_SERVICE_UNAVAIL 323 the time service requested is not avail. in this environment 325 IDUP_S_INAPPROPRIATE_CRED 326 the credentials supplied cannot be used to unprotect P-IDU 328 Adams Document Expiration: 11 Dec. 1996 6 329 IDUP_S_NO_ENV no environment recognized for env_handle 331 IDUP_S_NO_MATCH Service_Verification_Info and input token 332 do not match 334 IDUP_S_UNKNOWN_OPER_ID requested operation id. is unsupported 336 Informatory Status Codes 338 IDUP_S_ENCAPSULATION_UNAVAIL 339 encapsulation of M-IDU into pidu_buffer is not supported 341 IDUP_S_MORE_PIDU_NEEDED 342 more p-idu data is needed for IDUP_Start_Unprotect() 344 IDUP_S_MORE_DATA_NEEDED 345 more data is needed for protection or unprotection 347 1.2.2. Per-IDU Security Service Availability 349 Per-IDU security service availability in IDUP-GSS-API is to be 350 understood and used as described in GSS-API [RFC-1508], with the 351 exception that any combination of services requested by the calling 352 application and supported by the underlying mechanism can be applied 353 simultaneously to any IDU. 355 GSS-API callers desiring per-message security services should check 356 the relevant service OBJECT IDs at environment establishment time to 357 ensure that what is available in the established environment is 358 suitable for their security needs. 360 1.2.3. Per-IDU Replay Detection and Sequencing 362 The concept of per-IDU replay detection and sequencing discussed 363 in GSS-API [RFC-1508] is not relevant to the IDUP-GSS-API. 365 1.2.4. Quality of Protection 367 The concept of QOP control in IDUP-GSS-API is to be understood 368 essentially as described in GSS-API [RFC-1508]. However, the actual 369 description and use of the QOP parameter is given as follows. 371 Adams Document Expiration: 11 Dec. 1996 7 372 The qop_algs parameter for IDUP is defined to be a 32-bit unsigned 373 integer with the following bit-field assignments: 375 31 (MSB) (LSB) 0 376 ---------------------------------------------- 377 | U(19) | TS(5) | IA(4) | MA(4) | 378 ---------------------------------------------- 380 where 382 U is a 19-bit Unspecified field (available for future 383 use/expansion) -- must be set to zero; 385 TS is a 5-bit Type Specifier (a semantic qualifier whose value 386 specifies the type of algorithm which may be used to protect the 387 corresponding IDU -- see below for details); 389 IA is a 4-bit field enumerating Implementation-specific 390 Algorithms; and 392 MA is a 4-bit field enumerating Mechanism-defined Algorithms. 394 The interpretation of the qop_algs parameter is as follows. The MA 395 field is examined first. If it is non-zero then the algorithm used 396 to protect the IDU is the mechanism-specified algorithm corresponding 397 to that integer value. 399 If MA is zero then IA is examined. If this field value is non-zero 400 then the algorithm used to protect the IDU is the implementation- 401 specified algorithm corresponding to that integer value. Note that 402 use of this field may hinder portability since a particular value may 403 specify one algorithm in one implementation of the mechanism and may 404 not be supported or may specify a completely different algorithm in 405 another implementation of the mechanism. 407 Finally, if both MA and IA are zero then TS is examined. A value of 408 zero for TS specifies the default algorithm for the established 409 mechanism. A non-zero value for TS corresponds to a particular 410 algorithm qualifier and selects any algorithm from the mechanism 411 specification which satisfies that qualifier (which actual algorithm 412 is selected is an implementation choice; the calling application need 413 not be aware of the choice made). 415 The following TS values (i.e., algorithm qualifiers) are specified; 416 other values may be added in the future. 418 When qop_algs is used to select a confidentiality algorithm: 420 00000 (0) = default confidentiality algorithm 421 00001 (1) = IDUP_SYM_ALG_STRENGTH_STRONG 422 00010 (2) = IDUP_SYM_ALG_STRENGTH_MEDIUM 423 00011 (3) = IDUP_SYM_ALG_STRENGTH_WEAK 424 11111 (31) = IDUP_NO_CONFIDENTIALITY 426 Adams Document Expiration: 11 Dec. 1996 8 427 00000 (0) = default integrity algorithm 428 00001 (1) = IDUP_INT_ALG_DIG_SIGNATURE 429 (integrity provided through a digital signature) 430 00010 (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE 431 (integrity without a dig. sig. (e.g., with a MAC)) 432 11111 (31) = IDUP_NO_INTEGRITY 434 Clearly, qualifiers such as strong, medium, and weak are debatable 435 and likely to change with time, but for the purposes of this version 436 of the specification we define these terms as follows. A confiden- 437 tiality algorithm is "weak" if the effective key length of the cipher 438 is 40 bits or less; it is "medium-strength" if the effective key 439 length is strictly between 40 and 80 bits; and it is "strong" if the 440 effective key length is 80 bits or greater. ("Effective key length" 441 describes the computational effort required to break a cipher using 442 the best-known cryptanalytic attack against that cipher.) 444 A five-bit TS field allows up to 30 qualifiers for each of confiden- 445 tiality and integrity (since "0" is reserved for "default" and "31" 446 is reserved for "none", as shown above). This document specifies 447 three for confidentiality and two for integrity, leaving a lot of 448 room for future specification. Suggestions of qualifiers such as 449 "fast", "medium-speed", and "slow" have been made, but such terms are 450 difficult to quantify (and in any case are platform- and processor- 451 dependent), and so have been left out of this initial specification. 452 The intention is that the TS terms be quantitative, environment- 453 independent qualifiers of algorithms, as much as this is possible. 455 Use of the qop_algs parameter as defined above is ultimately meant to 456 be as follows. 458 - TS values are specified at the IDUP-GSS-API level and are 459 therefore portable across mechanisms. Applications which know 460 nothing about algorithms are still able to choose "quality" of 461 protection for their message tokens. 463 - MA values are specified at the mechanism level and are therefore 464 portable across implementations of a mechanism. 466 - IA values are specified at the implementation level (in user 467 documentation, for example) and are therefore typically non- 468 portable. An application which is aware of its own mechanism 469 implementation and the mechanism implementation of its intended 470 P-IDU recipient, however, is free to use these values since they 471 will be perfectly valid and meaningful for protecting IDUs 472 between those entities. 474 The receiver of a P-IDU must pass back to its calling application 475 (in IDUP_Start_Unprotect()) a qop_algs parameter with all relevant 476 fields set. For example, if triple-DES has been specified by a 477 mechanism as algorithm 8, then a receiver of a triple-DES-protected 478 P-IDU must pass to its application (TS=1, IA=0, MA=8). In this way, 479 the application is free to read whatever part of the qop_algs 480 parameter it understands (TS or IA/MA). 482 Adams Document Expiration: 11 Dec. 1996 9 483 1.2.5. The Provision of Time 485 IDUP mechanisms should make provision in their protocols for the 486 carrying of time information from originator to target(s). That is, 487 a target (a legitimate recipient) should get some indication during 488 unprotection regarding the time at which the protection operation 489 took place. This is particularly important if the mechanism offers 490 non-repudiation services because in some cases evidence verification 491 may only be achievable if the time at which the evidence was 492 generated is known. 494 Depending upon the platform and resources available to the 495 implementation, an IDUP environment may have access to a source of 496 trusted (secure) time, untrusted (local) time, both kinds of time, or 497 no time. OBJECT IDs indicating such availability are returned by the 498 IDUP_Establish_Env() call. When starting a protection operation, an 499 application may specify which time services it wishes to have applied 500 to the IDU. Similarly, for unprotection, an application may specify 501 which kind of time (if any) to consult when the validity of the P-IDU 502 is to be established. Specifying both kinds of time is interpreted 503 to mean that the calling application does not care which kind of time 504 is used. 506 2. Interface Descriptions 508 This section describes the IDUP-GSS-API's operational interface, 509 dividing the set of calls offered into five groups. Credential 510 management calls are related to the acquisition and release of 511 credentials by API callers. Environment-level calls are related to 512 the management of the security environment by an API caller. Per-IDU 513 calls are related to the protection or unprotection of individual 514 IDUs in established security environments. Special-purpose calls 515 deal with unusual or auxiliary evidence generation/verification 516 requirements. Support calls provide extra functions useful to 517 IDUP-GSS-API callers. Table 2 groups and summarizes the calls in 518 tabular fashion (an asterisk marks the calls which are identical to 519 the GSS-API specification). 521 Table 2: IDUP-GSS-API Calls 523 CREDENTIAL MANAGEMENT 525 * GSS_Acquire_cred acquire credentials for use 526 * GSS_Release_cred release credentials after use 527 * GSS_Inquire_cred display information about credentials 528 * GSS_Add_cred add credential info. (see [GSSv2]) 530 ENVIRONMENT-LEVEL CALLS 532 IDUP_Establish_Env establish IDUP environment (to protect and 533 unprotect IDUs) 534 IDUP_Abolish_Env abolish env. when no longer needed 535 IDUP_Inquire_Env indicate characteristics of env. 537 Adams Document Expiration: 11 Dec. 1996 10 538 PER-IDU CALLS 540 IDUP_Start_Protect begin the protection process 541 IDUP_Protect protect the IDU (perhaps 1 buffer at a time) 542 IDUP_End_Protect end the protection process; create a token 543 which contains info. necessary for the 544 legitimate receiver(s) of the P-IDU to 545 unprotect it 546 IDUP_File_Protect protect an IDU (input as a file) 548 IDUP_Start_Unprotect begin the unprotect process 549 IDUP_Unprotect use the token to unprotect the P-IDU 550 (possibly one buffer at a time) 551 IDUP_End_Unprotect end the unprotect process 552 IDUP_File_Unprotect unprotect a P-IDU (input as a file) 554 SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms) 556 IDUP_Form_Complete_PIDU insert in P-IDU any data not provided 557 by the protection call(s) 559 SUPPORT CALLS 561 * GSS_Display_status translate status codes to printable form 562 * GSS_Indicate_mechs indicate mech_types supported on local 563 system 564 * GSS_Compare_name compare two names for equality 565 * GSS_Display_name translate name to printable form 566 * GSS_Import_name convert printable name to normalize form 567 * GSS_Release_name free storage of normalized-form name 568 * GSS_Release_buffer free storage of printable name 569 * GSS_Release_oid_set free storage of OID set 570 IDUP_Parse_Token examine an input token to determine mech_type 571 IDUP_Get_Policy_Info return policy info. for a given policy_id 573 2.1. Credential management calls 575 2.1.1. Relationship to GSS-API 577 Credential management in IDUP-GSS-API is to be understood and used as 578 described in GSS-API [RFC-1508]. The calls GSS_Acquire_cred(), 579 GSS_Release_cred(), and GSS_Inquire_cred() are unchanged (the call 580 GSS_Add_cred() from GSS-API v2 [GSSv2] is also included). However, 581 the interpretation (and possible modification) of the cred_usage 582 parameter for IDUP purposes is for further study. 584 Adams Document Expiration: 11 Dec. 1996 11 585 2.2. Environment-level calls 587 This group of calls is devoted to the establishment and management of 588 an environment for the purpose of IDU protection and unprotection. 589 Before protecting or unprotecting any IDU, an application must call 590 IDUP_Establish_Env() to initialize environment information and select 591 the underlying IDUP-GSS mechanism to be used. A series of protection 592 or unprotection calls is made to process each IDU, the protection 593 calls resulting in a P-IDU for each. Finally, IDUP_Abolish_Env() 594 is called to flush all environment information. 596 Semantically, acquiring credentials and establishing an environment 597 is (in many cases) analogous to logging in to a system -- it 598 authenticates a local user to the system and gives that user access 599 to a set of operations which can be performed. 601 2.2.1. Relationship to GSS-API 603 The set of calls described in this section are used in place of the 604 calls GSS_Init_sec_context(), GSS_Accept_sec_context(), 605 GSS_Delete_sec_context(), GSS_Process_context_token(), and 606 GSS_Context_time() which are described in [RFC-1508], since those 607 calls are specific to a session-oriented environment. 609 Adams Document Expiration: 11 Dec. 1996 12 610 2.2.2. IDUP_Establish_Env call 612 Inputs: 614 o claimant_cred_handle CREDENTIAL HANDLE, 615 -- NULL parameter specifies "use default" 617 o req_mech_type OBJECT IDENTIFIER, 618 -- NULL parameter specifies "use default" 620 o req_policy OBJECT IDENTIFIER, 621 -- NULL parameter specifies "use default". 622 -- This environment-level policy identifier is separate from 623 -- the policy provisions connected with credentials, if they exist 625 o policy_time INTEGER, 626 -- the security policy rules available at the specified time 627 -- NULL parameter specifies "use default" 629 o req_services SET OF OBJECT IDENTIFIER, 631 Outputs: 633 o major_status INTEGER, 635 o minor_status INTEGER, 637 o env_handle ENVIRONMENT HANDLE, 639 o actual_mech_type OBJECT IDENTIFIER, 640 -- actual mechanism always indicated, never NULL 642 o actual_policy OBJECT IDENTIFIER, 643 -- actual policy always indicated, never NULL 645 o actual_policy_time, 646 -- actual time at which the above policy rules came into effect 648 o ret_services SET OF OBJECT IDENTIFIER, 650 Return major_status codes: 652 o GSS_S_COMPLETE indicates that environment-level information was 653 successfully initialized, and that IDU / P-IDU processing can 654 begin on the newly-established environment. 656 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 657 performed on the credential structure referenced by 658 claimant_cred_handle failed, preventing further processing from 659 being performed using that credential structure. 661 o GSS_S_NO_CRED indicates that no environment was established, 662 either because the input cred_handle was invalid or because the 663 caller lacks authorization to access the referenced credentials. 665 Adams Document Expiration: 11 Dec. 1996 13 666 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided 667 through the input claimant_cred_handle argument are no longer 668 valid, so environment establishment cannot be completed. 670 o GSS_S_BAD_MECH indicates that a mech_type unsupported by the 671 IDUP_GSS-API implementation was requested, causing the 672 environment establishment operation to fail. 674 o GSS_S_FAILURE indicates that environment setup could not be 675 accomplished for reasons unspecified at the IDUP-GSS-API level, 676 and that no interface-defined recovery action is available. 678 This routine is used by an application which protects or unprotects 679 IDUs. Using information in the credentials structure referenced by 680 claimant_cred_handle, IDUP_Establish_Env() initializes the data 681 structures required to protect or unprotect IDUs. The 682 claimant_cred_handle, if non-NULL, must correspond to a valid 683 credentials structure. 685 This routine returns an env_handle for all future references to 686 this environment; when protection, unprotection, or 687 IDUP_Abolish_Env() calls are made, this handle value will be used 688 as the input env_handle argument. 690 It is the caller's responsibility to establish a communications path 691 to the intended recipients of the P-IDU, and to transmit the P-IDU to 692 those recipients over that path. This may occur subsequent to the 693 IDUP_Abolish_Env() call. 695 The req_services parameter may be used by the calling application to 696 request that data origin authentication with integrity, 697 confidentiality with integrity, evidence generation, and/or evidence 698 verification services be available in the established environment. 699 Requests can also be made for "trusted" or "untrusted" time services. 700 Requesting evidence generation or verification indicates that the 701 calling application may wish to generate or verify evidence 702 information for non-repudiation purposes (note: an IDU protector may 703 request that a flag be inserted into a P-IDU asking a recipient to 704 provide an evidence of the type "non-repudiation of delivery"; 705 however, the IDUP-GSS-API cannot by itself guarantee that the 706 evidence will be sent because there is no way to force a target to 707 send an evidence_token back to the IDU protector). 709 Not all features will be available in all underlying mech_types; the 710 returned value of ret_services indicates, as a function 711 of mech_type processing capabilities and the initiator-provided input 712 OBJECT IDs, the set of features which will be available in the 713 environment. The value of this parameter is undefined unless the 714 routine's major_status indicates COMPLETE. Failure to provide the 715 precise set of services desired by the caller does not cause 716 environment establishment to fail; it is the caller's prerogative to 717 abolish the environment if the service set provided is unsuitable for 718 the caller's use. The returned mech_type value indicates the 719 specific mechanism employed in the environment, and will never 720 indicate the value for "default". 722 Adams Document Expiration: 11 Dec. 1996 14 723 The following OBJECT IDs are defined for protection and unprotection 724 services. It is recognized that this list may grow over time. 726 PER_CONF = { xx } 727 -- perform data confidentiality (i.e., encrypt data) 728 PER_DOA = { xx } 729 -- perform data origin authentication with data integrity 730 PER_POO = { xx } 731 -- perform (i.e., create) non-repudiable "proof of origin" 732 PER_POD = { xx } 733 -- perform (i.e., create) non-repudiable "proof of delivery" 734 REC_CONF = { xx } 735 -- receive data confidentiality (i.e., decrypt data) 736 REC_DOA = { xx } 737 -- receive / verify DOA with data integrity 738 REC_POO = { xx } 739 -- receive / verify "proof of origin" 740 REC_POD = { xx } 741 -- receive / verify "proof of delivery" 742 TTIME = { xx } 743 -- trusted time availability 744 UTIME = { xx } 745 -- untrusted time availability 747 The PER_CONF return value (in the ret_services paramater) indicates 748 whether the environment supports confidentiality services, and so 749 informs the caller whether or not a request for encryption through 750 a confidentiality service input to IDUP_Start_Protect() can be 751 honored. In similar fashion, the PER_DOA return value indicates 752 whether DOA services are available in the established environment, 753 and the PER_POO and PER_POD return values indicate whether evidence 754 generation services are available. The TTIME and UTIME values 755 indicate whether trusted time and untrusted time are available for 756 protection / unprotection services. 758 Note that, unlike a GSS "context", an IDUP environment does not have 759 an explicit lifetime associated with it. Instead, it relies on the 760 lifetime of the calling entity's credential (set by the caller in the 761 GSS_Acquire_cred() call). When the credential expires (or is 762 explicitly deleted using the gss_release_cred() call), no new 763 operations are allowed in the IDUP environment (although operations 764 which have begun, such as the Protection set of calls, can be taken 765 to completion). 767 2.2.3. IDUP_Abolish_Env call 769 Input: 771 o env_handle ENVIRONMENT HANDLE 773 Outputs: 775 o major_status INTEGER, 777 o minor_status INTEGER, 779 Adams Document Expiration: 11 Dec. 1996 15 780 o GSS_S_COMPLETE indicates that the environment was recognized and 781 that relevant environment-specific information was flushed. 783 o IDUP_S_NO_ENV indicates that no valid environment was recognized 784 for the env_handle provided, so no deletion was performed. 786 o GSS_S_FAILURE indicates that the environment is recognized, but 787 that the requested operation could not be performed for reasons 788 unspecified at the IDUP-GSS-API level. 790 This call is made to flush environment-specific information. (Once an 791 environment is established, cached credential and environment-related 792 info. is expected to be retained until an IDUP_Abolish_Env() call is 793 made or until the cred. lifetime expires.) Attempts to perform IDU 794 processing on a deleted environment will result in error returns. 796 2.2.4: IDUP_Inquire_Env call 798 Input: 800 o env_handle ENVIRONMENT HANDLE, 802 Outputs: 804 o major_status INTEGER, 806 o minor_status INTEGER, 808 o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this env. 810 o policy OBJECT IDENTIFIER, -- the policy used in this env. 812 o policy_time, -- time at which the policy rules came into effect 814 o ret_services SET OF OBJECT IDENTIFIER, 816 Return major_status codes: 818 o GSS_S_COMPLETE indicates that the referenced environment is valid 819 and that mech_type and other return values describe the 820 corresponding characteristics of the environment. 822 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 823 recognized, but that its associated credentials have expired, so 824 that the requested operation cannot be performed. 826 o IDUP_S_NO_ENV indicates that no valid environment was recognized 827 for the env_handle provided, so no return values can be provided. 829 o GSS_S_FAILURE indicates that the environment is recognized, but 830 that the requested operation could not be performed for reasons 831 unspecified at the IDUP-GSS-API level. 833 This routine provides environment-related information to the caller. 835 Adams Document Expiration: 11 Dec. 1996 16 836 2.3. Per-IDU calls 838 This group of calls is used to perform IDU protection and 839 unprotection processing on an established IDUP environment. Some of 840 these calls may block pending network interactions (depending on the 841 underlying mechanism in use). These calls may be invoked by an IDU's 842 protector or by the P-IDU's recipient. The two sets of members of 843 this group form a pair; the output from the protection set is 844 typically meant to be input to the unprotection set. 846 The per-IDU calls can support caller-requested data origin 847 authentication with data integrity, confidentiality with data 848 integrity, evidence, and evidence-requested-from-target services. 849 The protection operations output a token which encapsulates all the 850 information required to unprotect the IDU. The token is passed to 851 the target (possibly separate from the M-IDU) and is processed by the 852 unprotection calls at that system. Unprotection performs 853 decipherment, DOA verification, evidence verification, or 854 notification of evidence requested, as required. 856 Each of the two main operations (protection and unprotection) may be 857 separated into three parts: "Start_Operation"; "Operation" (which 858 may be called once for each buffer of input data); and 859 "End_Operation". This separation is available for the case where the 860 IDU or P-IDU is to be processed one buffer at a time. 861 "Start_Operation" allows the caller to specify or retrieve the 862 appropriate "Quality" used during the processing. "Operation" is 863 concerned with the processing itself, receiving a buffer of input 864 data and potentially returning a buffer of output data. 865 "End_Operation" performs any required clean-up and creates the 866 appropriate token or states whether the input token was verified. 868 If the IDU or P-IDU is wholly contained in a single buffer, the 869 three-part protection/unprotection processing need not be done. 870 Instead, protection and unprotection can be accomplished using only 871 the "Start_Operation" call, simplifying application code. 873 2.3.1. Relationship to GSS-API 875 The set of calls described in this section are used in place of the 876 calls GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() -- now 877 named GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() -- 878 which are specified in [RFC-1508], since those calls are specific to 879 a session-oriented environment. 881 2.3.2. Parameter Bundles 883 The concept of "parameter bundles" is used in the calls presented in 884 the following subsections in order to simplify their presentation and 885 (hopefully) clarify their intended purpose and use. A parameter 886 bundle is simply a set of closely-related parameters of a call which 887 are either all used by / available to the calling application or all 888 not used by / unavailable to the calling application. These 889 parameters may be all input parameters, all output parameters, or 890 any combination of the two. 892 Adams Document Expiration: 11 Dec. 1996 17 893 A typical use envisioned for parameter bundles in a language such as 894 C would be as a structure, where individual parameters in the bundle 895 are structure members. The calling application wishing to use a 896 particular bundle would then allocate the appropriate structure 897 variable, assign the desired input values to the appropriate members, 898 and pass the address of the structure as the bundle "parameter". On 899 output, the values of the appropriate output members may be read. An 900 application not wishing to use a particular bundle (or one which is 901 satisfied with default values for all input parameters of the bundle 902 and which doesn't care about output values), can pass NULL as the 903 bundle "parameter". From the mechanism implementor's perspective, if 904 a parameter bundle is not supported (for example, if it represents a 905 security service which is not supported by the implementation), then 906 any non-NULL value passed as the bundle parameter will generate an 907 error status return code. 909 The following parameter bundles are used in the subsequent protection 910 and unprotection sets of calls. A parameter preceded by "(I)" is an 911 input parameter; one preceded by "(O)" is an output parameter; one 912 preceded by neither is an input if the bundle itself is an input and 913 is an output if the bundle itself is an output. 915 o Mech_Specific_Info PARAMETER BUNDLE 916 -- actual parameters included in this bundle are defined by (and 917 -- specific to) the underlying mechanism 919 o Idu_Sensitivity PARAMETER BUNDLE, 920 -- actual parameters included in this bundle are defined by (and 921 -- specific to) the underlying mechanism, but may include 922 -- codified values for "Unclassified", "Secret", "Top Secret", 923 -- and so on 925 o Service_Creation_Info PARAMETER BUNDLE 926 -- actual parameters included in this bundle are defined by (and 927 -- specific to) the underlying mechanism, but it is mandatory 928 -- that they include at least service_id and Quality. 930 o Service_Verification_Info PARAMETER BUNDLE 931 -- actual parameters included in this bundle are defined by (and 932 -- specific to) the underlying mechanism, but it is mandatory 933 -- that they include at least service_id and Quality. 935 o Quality PARAMETER BUNDLE 937 o qop_algs UNSIGNED INTEGER, 939 o validity UNSIGNED INTEGER, 940 -- protection guaranteed to be valid until time specified 942 o policy_id OBJECT IDENTIFIER, 943 -- security policy under which protection is/was carried out 945 o allow_policy_mapping BOOLEAN, 946 -- determines whether or not mapping between policy 947 -- identifiers is allowed 949 Adams Document Expiration: 11 Dec. 1996 18 950 o idu_type_oid OBJECT IDENTIFIER, 952 o idu_type_string OCTET STRING, 954 o idu_title OCTET STRING, 956 o Idu_Sensitivity PARAMETER BUNDLE, 958 o Prot_Information PARAMETER BUNDLE, 960 o originator_name INTERNAL NAME, 962 o Idu_Information PARAMETER BUNDLE, 964 o protection_time INTEGER, 966 o Special_Conditions PARAMETER BUNDLE, 968 o prot_oper_id INTEGER, 970 o use_trusted_time BOOLEAN, 972 o use_untrusted_time BOOLEAN, 974 o Bad_Target_Name PARAMETER BUNDLE, 976 o (O) bad_targ_name INTERNAL NAME, 978 o (O) bad_targ_status INTEGER, 979 -- a (mechanism-defined) status flag giving the reason 980 -- for rejection of the name in bad_targ_name 982 o Target_Info PARAMETER BUNDLE, 984 o targ_names SET OF INTERNAL NAME, 986 o (O) bad_targ_count INTEGER, 988 o (O) Bad_Target_Name PARAMETER BUNDLE, 990 o General_Service_Data PARAMETER BUNDLE, 992 o Target_Info PARAMETER BUNDLE, 994 o (O) unencapsulated_token OCTET STRING, 995 -- zero length if encapsulation_request is TRUE; 996 -- unused in the unprotection set of calls 998 o (O) minor_status INTEGER, 1000 Adams Document Expiration: 11 Dec. 1996 19 1001 1. perform unsolicited service (i.e., act on a locally-generated 1002 service request), 1003 2. perform solicited service (i.e., act on a remotely-generated 1004 service request), and 1005 3. perform service solicitation (i.e., send a service request to 1006 the remote end). 1008 As an originator, applying data confidentiality with data integrity, 1009 or data origin authentication with data integrity, or proof of origin 1010 evidence is an example of service type 1. As a target, creating a 1011 proof of delivery (i.e., receipt) evidence token as the result of a 1012 request received from the originator is an example of service type 2. 1013 Finally, as an originator, submitting a request that one or more 1014 targets return a receipt for the data sent is an example of service 1015 type 3. 1017 The first four parameters in the Prot_Service parameter bundle 1018 pertain to all service types; the fifth parameter is used if and only 1019 if service type 2 is desired; parameters 6-8 are used if and only if 1020 service type 3 is desired. 1022 o Prot_Service PARAMETER BUNDLE 1024 o (I) prot_service_type INTEGER, 1026 o (I) service_id OBJECT IDENTIFIER, 1028 o (I) Quality PARAMETER BUNDLE, 1029 -- NULL specifies default Quality 1031 o (I) General_Service_Data PARAMETER BUNDLE, 1033 o (I) Service_Creation_Info PARAMETER BUNDLE, 1035 o (I) service_to SET OF INTERNAL NAME, 1037 o (O) Service_Verification_Info PARAMETER BUNDLE, 1039 o (O) service_verification_info_id INTEGER, 1041 Also, three types of unprotection services are defined. These are 1043 1. receive unsolicited service (i.e., process unrequested 1044 remotely-generated service), 1045 2. receive solicited service (i.e., process remotely-generated 1046 response to locally-generated request), and 1047 3. receive service solicitation (i.e., process req. from rem. end) 1049 As a target, unprotecting an encrypted message, or verifying the 1050 originator's proof of origin is an example of service type 1. As an 1051 originator, verifying a proof of delivery which you requested from a 1052 target is an example of service type 2. Finally, as a target, 1053 receiving a request from an originator for a proof of delivery is an 1054 example of service type 3. 1056 Adams Document Expiration: 11 Dec. 1996 20 1057 pertain to all service types; parameters 5-6 are used if and only if 1058 service type 2 is required; parameters 7-8 are used only if service 1059 type 3 is required. 1061 o Unprot_Service PARAMETER BUNDLE 1063 o (O) unprot_service_type INTEGER, 1065 o (O) service_id OBJECT IDENTIFIER, 1067 o (O) Quality PARAMETER BUNDLE, 1068 -- actual Quality specified (never NULL) 1070 o (O) General_Service_Data PARAMETER BUNDLE, 1072 o (O) service_verification_info_id INTEGER, 1074 o (I) Service_Verification_Info PARAMETER BUNDLE, 1076 o (O) service_to SET OF INTERNAL NAME, 1078 o (O) Service_Creation_Info PARAMETER BUNDLE, 1080 2.3.3. IDUP_Start_Protect call 1082 Inputs: 1084 o env_handle ENVIRONMENT HANDLE, 1086 o Mech_Specific_Info PARAMETER BUNDLE, 1087 -- NULL selects the mechanism-defined default values 1089 o Idu_Information PARAMETER BUNDLE, 1091 o Special_Conditions PARAMETER BUNDLE, 1093 o encapsulation_request BOOLEAN, 1095 o single_idu_buffer OCTET STRING, 1096 -- non-zero length for this buffer means that Protect/End_Protect 1097 -- won't be called (i.e., entire IDU is contained in this buffer) 1099 o Target_Info PARAMETER BUNDLE, 1101 o Services_to_Perform SET OF Prot_Service, 1103 Outputs: 1105 o major_status INTEGER, 1107 o minor_status INTEGER, 1109 o midu_buffer OCTET STRING, 1110 -- zero length if encapsulation_request is TRUE or if 1111 -- single_idu_buffer has zero length 1113 Adams Document Expiration: 11 Dec. 1996 21 1114 o pidu_buffer OCTET STRING, 1115 -- zero length if encapsulation_request is FALSE or if 1116 -- single_idu_buffer has zero length 1118 Return major_status codes: 1120 o GSS_S_COMPLETE indicates that the protection process can begin 1121 (or has completed, if single_idu_buffer has non-zero length). 1123 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1124 supplied is too small to hold the generated data. The application 1125 should continue calling this routine (until GSS_S_COMPLETE is 1126 returned) in order to get all remaining data. 1128 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 1129 recognized, but that its associated credentials have expired, so 1130 that the requested operation cannot be performed. 1132 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1133 for the env_handle provided. 1135 o IDUP_S_ENCAPSULATION_UNAVAIL indicates that the underlying 1136 mechanism does not support encapsulation of the M-IDU into the 1137 token. 1139 o IDUP_S_MORE_DATA_NEEDED indicates whether protection is completed 1140 by this call or by IDUP_End_Protect() (e.g., whether more data 1141 buffers are required for evidence generation) 1143 o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 1144 does not support the service requested. 1146 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 1147 requested (TTIME or UTIME) is not available in the environment. 1149 o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 1150 is not recognized or supported in the underlying mechanism. 1152 o GSS_S_BAD_QOP indicates that the provided qop_algs value is not 1153 recognized or supported for the environment. 1155 o IDUP_S_BAD_TARG_INFO indicates that all the information regarding 1156 the target(s) is invalid or is insufficient for the protection of 1157 an IDU, so P-IDU cannot be created. 1159 o GSS_S_FAILURE indicates that the environment is recognized, but 1160 that the requested operation could not be performed for reasons 1161 unspecified at the IDUP-GSS-API level. 1163 Adams Document Expiration: 11 Dec. 1996 22 1164 Using the security environment referenced by env_handle, initialize 1165 the data structures required to begin the process of protecting the 1166 IDU buffers. The caller requests specific protection services by 1167 supplying the appropriate Prot_Service parameter bundles in 1168 Services_to_Perform. Each service is able to return a minor status 1169 code to the calling application, if necessary. 1171 The calling application, knowing the size of the IDU it wishes to 1172 protect and the buffer size which it has available to it, can choose 1173 to input the entire IDU in a single buffer and omit the subsequent 1174 IDUP_Protect() and IDUP_End_Protect() calls. Furthermore, the 1175 application can request that the resulting M-IDU be encapsulated in 1176 the token -- so that the token contains the entire P-IDU -- rather 1177 than having it be returned separately in midu_buffer. Encapsulation, 1178 however, may not be supported by all underlying mechanisms or 1179 implementations; if this is the case, the 1180 IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and 1181 M-IDU will be returned in midu_buffer. 1183 For those mechanisms which allow or require multiple stages of 1184 processing, each producing a different aspect of protection for the 1185 IDU, the operation identifier prot_oper_id is used to specify 1186 which stage is currently being requested by the application. An 1187 example where this would be useful is a mechanism which implements 1188 the signed Message Security Protocol [MSP]. As another example, a 1189 mechanism may choose to do a digital signature in two stages: one 1190 for the hashing of the message and another for the signature on the 1191 hash. The calling application would therefore use the protection set 1192 of calls on the IDU in stage 1 and then use the protection set of 1193 calls on the token (from stage 1) in stage 2. 1195 Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where 1196 "n" is the number of stages as defined by the mechanism (typically 1 1197 or 2)). The calling application uses this parameter to indicate to 1198 the underlying mechanism whether it wishes to do stage 1 of 1199 protection / unprotection processing, or stage 2, and so on. 1201 If one or more of the targets in targ_names cannot be used as a valid 1202 recipient of the P-IDU, these names will be returned in 1203 bad_targ_names (with associated status codes in bad_targ_status). As 1204 long as at least one of the targets can be used, this does not cause 1205 this call to fail; it is the caller's prerogative to discontinue IDU 1206 protection if the target set which can be used is unsuitable for the 1207 caller's purposes. Note that each Prot_Service parameter bundle can 1208 also input a list of targ_names; this is used if a separate list is 1209 to be used for that service only (the general list of targets is to 1210 be used for all services unless overridden in this way). 1212 Adams Document Expiration: 11 Dec. 1996 23 1213 2.3.4. IDUP_Protect call 1215 Inputs: 1217 o env_handle ENVIRONMENT HANDLE, 1219 o input_buffer OCTET STRING, 1221 Outputs: 1223 o major_status INTEGER, 1225 o minor_status INTEGER, 1227 o output_buffer OCTET STRING 1228 -- may be zero length if encapsulation_request was set to TRUE in 1229 -- IDUP_Start_Protect() (depends on underlying mechanism) 1231 Return major_status codes: 1233 o GSS_S_COMPLETE indicates that the input_buffer has successfully 1234 been included in the protection computation. 1236 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1237 for the env_handle provided. 1239 o GSS_S_FAILURE indicates that the environment is recognized, but 1240 that the required operation could not be performed for reasons 1241 unspecified at the IDUP-GSS-API level. 1243 Using the security environment referenced by env_handle, continue the 1244 protection processing on the data in input_buffer and, if the 1245 underlying mechanism defines this, put any resulting P-IDU/M-IDU data 1246 in output_buffer. The application calls this routine over and over 1247 again with new buffers of data until it has protected all the data 1248 buffers of the IDU. It then calls IDUP_End_Protect() to complete the 1249 protection processing. 1251 Adams Document Expiration: 11 Dec. 1996 24 1252 2.3.5. IDUP_End_Protect call 1254 Inputs: 1256 o env_handle ENVIRONMENT HANDLE, 1258 Outputs: 1260 o major_status INTEGER, 1262 o minor_status INTEGER, 1264 o Services_to_Perform SET OF Prot_Service, 1266 o final_midu_buffer OCTET STRING, 1267 -- zero length if encapsulation_request was set to TRUE in 1268 -- IDUP_Start_Protect(), in which case pidu is used 1270 o final_pidu_buffer OCTET STRING, 1271 -- zero length if encapsulation_request was set to FALSE in 1272 -- IDUP_Start_Protect(), in which case token and midu are used 1274 Return major_status codes: 1276 o GSS_S_COMPLETE indicates that the protection computation has been 1277 successfully completed and the resulting P-IDU is ready for 1278 transfer. If defined by the underlying mechanism, 1279 final_midu_buffer will contain any residual M-IDU data. 1281 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1282 supplied is too small to hold the generated data. The application 1283 should continue calling this routine (until GSS_S_COMPLETE is 1284 returned) in order to get all remaining data. 1286 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1287 for the env_handle provided. 1289 o GSS_S_FAILURE indicates that the environment is recognized, but 1290 that the requested operation could not be performed for reasons 1291 unspecified at the IDUP-GSS-API level. 1293 Using the security environment referenced by env_handle, complete the 1294 protection processing on the data and place the computed output in 1295 final_pidu_buffer (or final_midu_buffer and the unencapsulated_token 1296 parameter for each Prot_Service). If a service was requested from 1297 one or more targets in Start_Protect() - and if this is supported by 1298 the underlying mechanism - Service_Verification_Info will hold 1299 whatever data is necessary for the mechanism to verify a service 1300 returned by a target (unprotector) of the P-IDU. Successful 1301 application of IDUP_End_Protect() does not guarantee that the 1302 corresponding unprotection set of calls can necessarily be performed 1303 successfully when the P-IDU arrives at the target (for example, it 1304 may be damaged in transit). 1306 Adams Document Expiration: 11 Dec. 1996 25 1307 2.3.6. IDUP_File_Protect call 1309 Inputs: 1311 o env_handle ENVIRONMENT HANDLE, 1313 o Mech_Specific_Info PARAMETER BUNDLE, 1314 -- NULL selects the mechanism-defined default values 1316 o Idu_Information PARAMETER BUNDLE, 1318 o Special_Conditions PARAMETER BUNDLE, 1320 o input_filename INTERNAL FILE NAME, 1322 o Target_Info PARAMETER BUNDLE, 1324 o Services_to_Perform SET OF Prot_Service, 1326 Outputs: 1328 o major_status INTEGER, 1330 o minor_status INTEGER, 1332 o output_filename INTERNAL FILE NAME, 1334 Return major_status codes: 1336 o GSS_S_COMPLETE indicates that file protection is complete. 1338 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 1339 recognized, but that its associated credentials have expired, so 1340 that the requested operation cannot be performed. 1342 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1343 for the env_handle provided. 1345 o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 1346 does not support the service requested. 1348 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 1349 requested (TTIME or UTIME) is not available in the environment. 1351 o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 1352 is not recognized or supported in the underlying mechanism. 1354 o GSS_S_BAD_QOP indicates that the provided qop_algs value is not 1355 recognized or supported for the environment. 1357 o IDUP_S_BAD_TARG_INFO indicates that all the information regarding 1358 the target(s) is invalid or is insufficient for the protection of 1359 an IDU, so P-IDU cannot be created. 1361 Adams Document Expiration: 11 Dec. 1996 26 1362 o GSS_S_FAILURE indicates that the environment is recognized, but 1363 that the requested operation could not be performed for reasons 1364 unspecified at the IDUP-GSS-API level. 1366 This call is almost identical to the IDUP_Start_Protect call except 1367 that instead of single_idu_buffer the input is a filename and instead 1368 of midu_buffer or pidu_buffer the output is again a filename. This 1369 can greatly simplify and improve the performance of applications 1370 which work primarily with files instead of buffers of data. It is 1371 important, however, to note two caveats. Firstly, for reasons of 1372 simplicity, unencapsulation is not available to callers of this 1373 function (as it is to callers of IDUP_Start_Protect); encapsulation 1374 is the only option available. Secondly, and more importantly, 1375 because of the INTERNAL FILE NAME parameters (input_filename and 1376 output_filename), callers of this function are very likely to be 1377 non-portable across different computing platforms (since handles to 1378 files may differ from platform to platform). 1380 Because of the above caveats, this call is specified to be optional, 1381 and may not be supported by all underlying mechanisms or 1382 implementations. 1384 2.3.7. IDUP_Start_Unprotect call 1386 Inputs: 1388 o env_handle ENVIRONMENT HANDLE, 1390 o Mech_Specific_Info PARAMETER BUNDLE, 1391 -- NULL selects the mechanism-defined default values 1393 o single_pidu_buffer OCTET STRING, 1394 -- non-zero length for this buffer means that IDUP_Unprotect() and 1395 -- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU 1396 -- is contained in this buffer) 1398 o partial_pidu_buffer OCTET STRING, 1399 -- may be an arbitrary-sized piece of the full pidu (if the 1400 -- applications buffer isnt large enough to hold entire pidu), 1401 -- or may be a service token (if encapsulation was not used). 1402 -- Used if pidu_buffer will be input a buffer at a time (except 1403 -- that the final buffer must be passed in final_pidu_buffer 1404 -- rather than partial_pidu_buffer). Only one of 1405 -- single_pidu_buffer and partial(final)_pidu_buffer can have 1406 -- nonzero length. 1408 o final_pidu_buffer OCTET STRING, 1410 o Special_Conditions PARAMETER BUNDLE, 1412 Adams Document Expiration: 11 Dec. 1996 27 1413 Outputs: 1415 o major_status INTEGER, 1417 o minor_status INTEGER, 1419 o Services_to_Receive SET OF Unprot_Service, 1421 o Prot_Information PARAMETER BUNDLE, 1423 o single_idu_buffer OCTET STRING, 1424 -- if this buffer has non-zero length, then service processing has 1425 -- been completed on the data in single_pidu_buffer 1427 o initial_idu_buffer OCTET STRING, 1428 -- holds any data from partial(final)_pidu_buffer which has been 1429 -- unprotected; remaining data will be returned by Unprotect and 1430 -- End_Unprotect as they are called with successive buffers of 1431 -- pidu 1433 o Service_Verification_Info PARAMETER BUNDLE, 1434 -- used only if target is on "service_to" list in Unprot_Service 1436 o service_verification_info_id INTEGER, 1437 -- used only if target is on "service_to" list in Unprot_Service 1439 Return major_status codes: 1441 o GSS_S_COMPLETE indicates that unprotection processing can begin 1442 (or has completed, if single_idu_buffer has non-zero length). 1444 o IDUP_S_INCOMPLETE indicates that the unprotection of the P-IDU 1445 is not yet complete (i.e., a determination cannot yet be made on 1446 the validity of the P-IDU). The application should call 1447 IDUP_Form_Complete_PIDU and then should call this function again 1448 with the complete P-IDU. (This status code is used in 1449 IDUP_Start_Unprotect only if single_idu_buffer has non-zero 1450 length) 1452 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1453 supplied is too small to hold the generated data. The application 1454 should continue calling this routine (until GSS_S_COMPLETE is 1455 returned) in order to get all remaining data. 1457 o IDUP_S_MORE_PIDU_NEEDED indicates that not enough of the P-IDU 1458 has been input yet for the completion of Start_Protect. The 1459 application should call this routine again with another buffer 1460 of P-IDU in partial_pidu_buffer. 1462 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 1463 on the received P-IDU failed, preventing further processing 1464 from being performed. 1466 o IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied 1467 do not contain the information necessary for P-IDU unprotection. 1469 Adams Document Expiration: 11 Dec. 1996 28 1470 o IDUP_S_MORE_DATA_NEEDED indicates whether unprotection is 1471 completed by this call or by IDUP_End_Unprotect() (e.g., whether 1472 more data buffers are required for unprotection) 1474 o GSS_S_DEFECTIVE_VERIF indicates that consistency checks performed 1475 on Service_Verification_Info failed, preventing further processing 1476 from being performed with that parameter. 1478 o IDUP_S_NO_MATCH indicates that Service_Verification_Info and 1479 the P-IDU to be verified do not match. 1481 o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 1482 does not support the service requested. 1484 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 1485 requested (TTIME or UTIME) is not available in the environment. 1487 o IDUP_S_SERV_VERIF_INFO_NEEDED indicates that the 1488 Service_Verification_Info parameter bundle must be input in order 1489 for service verification to proceed. The output parameter 1490 service_verification_info_id contains an identifier which may be 1491 used by the calling application to locate the necessary 1492 information. 1494 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 1495 recognized, but that its associated credentials have expired, so 1496 that the requested operation cannot be performed. 1498 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1499 for the env_handle provided. 1501 o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 1502 is not recognized or supported in the underlying mechanism. 1504 o GSS_S_BAD_QOP indicates that the qop_algs value specified in P-IDU 1505 for at least one of the services is unavailable in the local 1506 mechanism, so processing cannot continue. 1508 o GSS_S_BAD_SIG indicates that the received P-IDU contains an 1509 incorrect integrity field (e.g., signature or MAC) for the data. 1511 o IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU 1512 data origin auth. / integ. has either expired or been revoked. 1514 o IDUP_S_BAD_KE_KEY indicates that the key used to establish a key 1515 for confidentiality purposes between originator and target has 1516 either expired or been revoked. 1518 o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU 1519 cannot be completed because the encrypted IDU was invalid/defec- 1520 tive (e.g., the final block was short or had incorrect padding). 1522 o GSS_S_FAILURE indicates that the environment is recognized, but 1523 that the requested operation could not be performed for reasons 1524 unspecified at the IDUP-GSS-API level. 1526 Adams Document Expiration: 11 Dec. 1996 29 1527 Using the security environment referenced by env_handle, initialize 1528 the data structures required to begin the process of unprotecting a 1529 P-IDU. The caller will be alerted as to which services were applied 1530 to the P-IDU in the returned Services_to_Receive set of parameters. 1532 If unprotection will be applied more than once to a given P-IDU, it 1533 is the responsibility of the calling application to remember if a 1534 service solicitation has been responded to previously (i.e., if the 1535 requested service has already been generated / sent for that P-IDU) 1536 and thus ignore subsequent solicitations on unprotect. 1538 The time flags indicate whether to consult trusted, untrusted, or no 1539 time (if both flags are FALSE) during the unprotection operation. If 1540 the current time is not to be checked, then unprotection may be 1541 successful even if the protector's key has expired since the P-IDU 1542 was generated (that is, if the Validity period -- as specified in 1543 the Quality parameter bundle -- has expired). 1545 If the underlying mechanism supports it and if this information is 1546 contained in the token, information regarding the originator (that 1547 is, the entity which used the protection set of calls to generate 1548 this token) is returned in the Prot_Information parameter bundle. 1550 2.3.8. IDUP_Unprotect call 1552 Inputs: 1554 o env_handle ENVIRONMENT HANDLE, 1556 o input_buffer OCTET STRING 1558 Outputs: 1560 o major_status INTEGER, 1562 o minor_status INTEGER, 1564 o output_buffer OCTET STRING 1566 Return major_status codes: 1568 o GSS_S_COMPLETE indicates that the input_buffer has successfully 1569 been included in the unprotection computation. 1571 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1572 for the env_handle provided. 1574 o GSS_S_FAILURE indicates that the environment is recognized, but 1575 that the requested operation could not be performed for reasons 1576 unspecified at the IDUP-GSS-API level. 1578 Using the security environment referenced by env_handle, continue the 1579 unprotection processing on the data in input_buffer, putting any 1580 resulting IDU data in output_buffer (if required). 1582 Adams Document Expiration: 11 Dec. 1996 30 1583 2.3.9. IDUP_End_Unprotect call 1585 Inputs: 1587 o env_handle ENVIRONMENT HANDLE, 1589 Outputs: 1591 o major_status INTEGER, 1593 o minor_status INTEGER, 1595 o Prot_Information PARAMETER BUNDLE, 1597 o Services_to_Receive SET OF Unprot_Service, 1599 o final_idu_buffer OCTET STRING, 1601 o Service_Verification_Info PARAMETER BUNDLE, 1602 -- used only if target is on "service_to" list in Unprot_Service 1604 o service_verification_info_id INTEGER, 1605 -- used only if target is on "service_to" list in Unprot_Service 1607 Return major_status codes: 1609 o GSS_S_COMPLETE indicates that the unprotect computation was 1610 successful. Any residual IDU data will be returned in 1611 final_idu_buffer. 1613 o IDUP_S_INCOMPLETE indicates that the unprotection of the P-IDU 1614 is not yet complete (i.e., a determination cannot yet be made on 1615 the validity of the P-IDU). The application should call 1616 IDUP_Form_Complete_PIDU and then should call this function again 1617 with the complete P-IDU. 1619 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1620 supplied is too small to hold the generated data. The application 1621 should continue calling this routine (until GSS_S_COMPLETE is 1622 returned) in order to get all remaining data. 1624 o GSS_S_BAD_SIG indicates that the received P-IDU contains an 1625 incorrect integrity field (e.g., signature or MAC) for the data. 1627 o IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU 1628 data origin auth. / integ. has either expired or been revoked. 1630 o IDUP_S_BAD_KE_KEY indicates that the key used to establish a key 1631 for confidentiality purposes between originator and target has 1632 either expired or been revoked. 1634 o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU 1635 cannot be completed because the encrypted IDU was invalid/defec- 1636 tive (e.g., the final block was short or had incorrect padding). 1638 Adams Document Expiration: 11 Dec. 1996 31 1639 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1640 for the env_handle provided. 1642 o GSS_S_FAILURE indicates that the environment is recognized, but 1643 that the requested operation could not be performed for reasons 1644 unspecified at the IDUP-GSS-API level. 1646 Using the security environment referenced by env_handle, complete the 1647 unprotection processing on the data and return the appropriate status 1648 code. If there is any residual IDU data it will be returned in 1649 final_idu_buffer. 1651 If the IDUP_S_INCOMPLETE major status value is returned, all output 1652 parameters are conditionally valid; the unprotection set of functions 1653 will have to be called again (perhaps with a complete P-IDU, as 1654 produced by IDUP_Form_Complete_PIDU) in order to get valid values for 1655 all parameters. "Conditional validity" may arise, for example, if 1656 all relevant certificates verify correctly, but it is not yet past 1657 the time up to which the current policy allows the authorities 1658 involved to repudiate their keys. 1660 If the underlying mechanism supports it and if this information is 1661 contained in the token, information regarding the originator (that 1662 is, the entity which used the protection set of calls to generate 1663 this token) is returned in the Prot_Information parameter bundle. 1664 This information may or may not be omitted if it was returned by the 1665 IDUP_Start_Unprotect() call. 1667 Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the 1668 concept of error tokens transferred between sender and recipient 1669 since the protection and unprotection of an IDU may be separated by 1670 an indefinite amount of time and may or may not be performed by the 1671 same entity. 1673 2.3.10. IDUP_File_Unprotect call 1675 Inputs: 1677 o env_handle ENVIRONMENT HANDLE, 1679 o Mech_Specific_Info PARAMETER BUNDLE, 1680 -- NULL selects the mechanism-defined default values 1682 o input_filename INTERNAL FILE NAME, 1684 o Special_Conditions PARAMETER BUNDLE, 1686 Adams Document Expiration: 11 Dec. 1996 32 1687 Outputs: 1689 o major_status INTEGER, 1691 o minor_status INTEGER, 1693 o Services_to_Receive SET OF Unprot_Service, 1695 o Prot_Information PARAMETER BUNDLE, 1697 o output_filename INTERNAL FILE NAME, 1699 o Service_Verification_Info PARAMETER BUNDLE, 1700 -- used only if target is on "service_to" list in Unprot_Service 1702 o service_verification_info_id INTEGER, 1703 -- used only if target is on "service_to" list in Unprot_Service 1705 Return major_status codes: 1707 o GSS_S_COMPLETE indicates that unprotection processing can begin 1708 (or has completed, if single_idu_buffer has non-zero length). 1710 o IDUP_S_INCOMPLETE indicates that the unprotection of the P-IDU 1711 file is not yet complete (i.e., a determination cannot yet be made 1712 on the validity of the P-IDU). The application should call 1713 IDUP_Form_Complete_PIDU and then should call this function again 1714 with the complete P-IDU. 1716 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 1717 on the received P-IDU failed, preventing further processing 1718 from being performed. 1720 o GSS_S_DEFECTIVE_VERIF indicates that consistency checks performed 1721 on Service_Verification_Info failed, preventing further processing 1722 from being performed with that parameter. 1724 o IDUP_S_NO_MATCH indicates that Service_Verification_Info and 1725 the P-IDU to be verified do not match. 1727 o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 1728 does not support the service requested. 1730 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 1731 requested (TTIME or UTIME) is not available in the environment. 1733 o IDUP_S_SERV_VERIF_INFO_NEEDED indicates that the 1734 Service_Verification_Info parameter bundle must be input in order 1735 for service verification to proceed. The output parameter 1736 service_verification_info_id contains an identifier which may be 1737 used by the calling application to locate the necessary 1738 information. 1740 o IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied 1741 do not contain the information necessary for P-IDU unprotection. 1743 Adams Document Expiration: 11 Dec. 1996 33 1744 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 1745 recognized, but that its associated credentials have expired, so 1746 that the requested operation cannot be performed. 1748 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1749 for the env_handle provided. 1751 o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 1752 is not recognized or supported in the underlying mechanism. 1754 o GSS_S_BAD_QOP indicates that the qop_algs value specified in P-IDU 1755 for at least one of the services is unavailable in the local 1756 mechanism, so processing cannot continue. 1758 o GSS_S_BAD_SIG indicates that the received P-IDU contains an 1759 incorrect integrity field (e.g., signature or MAC) for the data. 1761 o IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU 1762 data origin auth. / integ. has either expired or been revoked. 1764 o IDUP_S_BAD_KE_KEY indicates that the key used to establish a key 1765 for confidentiality purposes between originator and target has 1766 either expired or been revoked. 1768 o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU 1769 cannot be completed because the encrypted IDU was invalid/defec- 1770 tive (e.g., the final block was short or had incorrect padding). 1772 o GSS_S_FAILURE indicates that the environment is recognized, but 1773 that the requested operation could not be performed for reasons 1774 unspecified at the IDUP-GSS-API level. 1776 This call is almost identical to the IDUP_Start_Unprotect call except 1777 that instead of single_pidu_buffer, partial_pidu_buffer, or 1778 final_pidu_buffer the input is a filename and instead of 1779 single_idu_buffer or initial_idu_buffer the output is again a 1780 filename. This can greatly simplify and improve the performance of 1781 applications which work primarily with files instead of buffers of 1782 data. It is important, however, to note two caveats. Firstly, for 1783 reasons of simplicity, unencapsulation is not available to callers of 1784 this function (as it is to callers of IDUP_Start_Unprotect); 1785 encapsulation is the only option available. Secondly, and more 1786 importantly, because of the INTERNAL FILE NAME parameters 1787 (input_filename and output_filename), callers of this function are 1788 very likely to be non-portable across different computing platforms 1789 (since handles to files may differ from platform to platform). 1791 Because of the above caveats, this call is specified to be optional, 1792 and may not be supported by all underlying mechanisms or 1793 implementations. 1795 Adams Document Expiration: 11 Dec. 1996 34 1796 2.4. Special-Purpose Calls 1798 2.4.1. Relationship to GSS-API 1800 The special-purpose call described in this section has no analog 1801 in GSS-API [RFC-1508]. This call is used to complete a P-IDU (that 1802 is, to generate a P-IDU which can be unprotected successfully with 1803 no additional data at any time during its validity period). This 1804 call may not be supported by all underlying IDUP mechanisms or 1805 implementations. 1807 2.4.2. IDUP_Form_Complete_PIDU call 1809 Inputs: 1811 o env_handle ENVIRONMENT HANDLE, 1813 o single_pidu_buffer OCTET STRING, 1815 o partial_pidu_buffer OCTET STRING, 1816 -- an arbitrary-sized piece of the full pidu token. Used if pidu 1817 -- will be input a buffer at a time (except that the final buffer 1818 -- must be passed in final_pidu_buffer rather than 1819 -- partial_pidu_buffer). Only one of single_pidu_buffer and 1820 -- partial(final)_pidu_buffer can have nonzero length. 1822 o final_pidu_buffer OCTET STRING, 1824 Outputs: 1826 o major_status INTEGER, 1828 o minor_status INTEGER, 1830 o pidu_token_out OCTET STRING 1832 o call_again_before INTEGER, 1834 o call_again_after INTEGER, 1836 Adams Document Expiration: 11 Dec. 1996 35 1837 Return major_status codes: 1839 o GSS_S_COMPLETE indicates that the completion of P-IDU generation 1840 was successful. 1842 o GSS_S_CONTINUE_NEEDED indicates that the buffer supplied for 1843 pidu_token_out is too small to hold the generated data. The 1844 application should continue calling this routine (until 1845 GSS_S_COMPLETE is returned) in order to get all remaining data. 1847 o IDUP_S_INCOMPLETE indicates that the generation of the P-IDU 1848 is not yet complete. The application should call this function 1849 again before the time given in call_again_before (if not NULL), 1850 or after the time given in call_again_after (if not NULL), or 1851 both (if neither are NULL). 1853 o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 1854 does not support the service requested. 1856 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 1857 on the input P-IDU token failed, preventing further processing 1858 from being performed with that token. 1860 o GSS_S_FAILURE indicates that the environment is recognized, but 1861 that the requested operation could not be performed for reasons 1862 unspecified at the IDUP-GSS-API level. 1864 Using the security environment referenced by env_handle, complete the 1865 generation of a P-IDU token and return the appropriate status value 1866 along with the completed token (if available). Such a call may be 1867 used, for example, for the purpose of batch evidence generation on an 1868 "evidence server". A local machine may be able to use the protection 1869 set of calls to fill out most of an evidence token and then send a 1870 number of these to a batch processor which forms the complete 1871 evidence tokens (perhaps by adding a certification path, or a 1872 timestamp and signature from a timestamping authority). As another 1873 example, on the receiving end an application may make such a call in 1874 order to collect all the information necessary to unprotect a P-IDU 1875 (such as all relevant certificates and Certificate Revocation Lists); 1876 this will ensure that the calls to the unprotection set of operations 1877 will be entirely local (i.e., can be performed off-line) and fast. 1879 Note that the complete P-IDU generated will be formed using trusted 1880 time if this is available in the environment referenced by env_handle 1881 and will use untrusted time or no time otherwise (depending on what 1882 is available). 1884 Adams Document Expiration: 11 Dec. 1996 36 1885 2.5. Support calls 1887 2.5.1. Relationship to GSS-API 1889 Support calls in IDUP-GSS-API are to be understood and used as 1890 described in GSS-API [RFC-1508]. The calls GSS_Display_status(), 1891 GSS_Indicate_mechs(), GSS_Compare_name(), GSS_Display_name(), 1892 GSS_Import_name(), GSS_Release_name(), GSS_Release_buffer(), and 1893 GSS_Release_oid_set() are unchanged. 1895 2.5.2. IDUP_Parse_token call 1897 Inputs: 1899 o input_token OCTET STRING 1901 Outputs: 1903 o major_status INTEGER, 1905 o minor_status INTEGER, 1907 o mech_type OBJECT IDENTIFIER, 1909 Return major_status codes: 1911 o GSS_S_COMPLETE indicates that the input_token could be parsed for 1912 all relevant fields. 1914 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 1915 recognized, but that its associated credentials have expired, so 1916 that the requested operation cannot be performed. 1918 o GSS_S_DEFECTIVE_TOKEN indicates that the mechanism type could be 1919 parsed, but that either the other fields could not be determined 1920 from the input_token, or their values did not correspond to valid 1921 values for that mechanism. 1923 o GSS_S_FAILURE indicates that the mechanism type could not be 1924 parsed (for example, the token may be corrupted). 1926 IDUP_Parse_Token() is used to return to an application the attributes 1927 which correspond to a given input token. Since IDUP-GSS-API tokens 1928 are meant to be opaque to the calling application, this function 1929 allows the application to determine information about the token 1930 without having to violate the opaqueness intention of IDUP. Of 1931 primary importance is the mechanism type, which the application can 1932 then use as input to the IDUP_Establish_Env() call in order to 1933 establish the correct environment in which to have the token 1934 processed. Other token attributes may be added as outputs of this 1935 call in future versions of this specification, if required. 1937 Adams Document Expiration: 11 Dec. 1996 37 1938 If all tokens are framed as suggested in RFC-1508, Appendix B 1939 (mandated in the Kerberos V5 GSS mechanism [KRB5], in the SPKM GSS 1940 Mechanism [SPKM], and in this document), then any mechanism 1941 implementation should be able to return the mech_type parameter for 1942 any uncorrupted input token. If the mechanism implementation whose 1943 IDUP_Parse_token() function is being called does recognize the token, 1944 it can return other token attributes, if specified. 1946 2.5.3. IDUP_Get_policy_info call 1948 Inputs: 1950 o policy_id OBJECT IDENTIFIER 1952 Outputs: 1954 o major_status INTEGER, 1956 o minor_status INTEGER, 1958 o policy_version INTEGER, 1960 o policy_effective_time INTEGER, 1962 o policy_expiry_time INTEGER, 1964 o supported_services SET OF Service_Descriptor, 1966 o supported_mechanisms SET OF Mechanism_Descriptor 1968 Return major_status codes: 1970 o GSS_S_COMPLETE indicates that the policy_id was recognized and 1971 all relevant fields have been returned. 1973 o GSS_S_FAILURE indicates that the policy_id was not recognized. 1975 This call (which need not be supported by all underlying mechanisms 1976 or implementations) allows the application to retrieve information 1977 pertaining to a given policy_id. Policies define the following: 1979 - rules for the protection of IDUs, such as trusted third 1980 parties which may be involved in P-IDU generation, the roles 1981 in which they may be involved, and the duration for which the 1982 generated P-IDU is valid; 1984 Adams Document Expiration: 11 Dec. 1996 38 1985 - rules for the unprotection of P-IDUs, such as the interval 1986 during which a trusted third party may legitimately declare its 1987 key to have been compromised or revoked; and 1989 - rules for adjudication, such as which authorities may be used 1990 to adjudicate disputes. 1992 The policy itself may be used by an adjudicator when resolving a 1993 dispute. For example, the adjudicator might refer to the policy to 1994 determine whether the rules for generation of the P-IDU have been 1995 followed. 1997 The following parameter bundles are associated with this call. 1999 o Service_Descriptor PARAMETER BUNDLE, 2001 o service_type OBJECT IDENTIFIER, 2003 o service_validity_duration INTEGER, 2005 o must_use_trusted_time BOOLEAN 2007 o Mechanism_Descriptor PARAMETER BUNDLE, 2009 o mechanism_type OBJECT IDENTIFIER, 2011 o Authority_List PARAMETER BUNDLE, 2013 o maximum_time_skew INTEGER 2014 -- maximum permissible difference between P-IDU generation 2015 -- time and the time of countersignature from a time 2016 -- service (if required). This parameter is unused if 2017 -- trusted time is not required. 2019 o Authority_List PARAMETER BUNDLE, 2021 o authority_name INTERNAL NAME, 2023 o authority_role OCTET STRING, 2025 o last_revocation_check_offset INTEGER 2026 -- may be greater than 0 or less than 0. The value of 2027 -- this parameter is added to P-IDU generation time to 2028 -- get latest time at which the mechanism will check to 2029 -- see if this authority's key has been revoked. 2031 An example of the use of the last parameter in Authority_List is as 2032 follows. If an authority has a defined last_revocation_check_offset 2033 of negative one hour, then all revocations taking effect earlier than 2034 one hour before the generation of a P-IDU will render that P-IDU 2035 invalid; no revocation taking place later than one hour before the 2036 generation of the P-IDU will affect the P-IDU's validity. 2038 Note that both the maximum_time_skew and the 2039 last_revocation_check_offset values are given in minutes. 2041 Adams Document Expiration: 11 Dec. 1996 39 2042 3. Related Activities 2044 In order to implement the IDUP-GSS-API atop existing, emerging, and 2045 future security mechanisms, the following is necessary: 2047 - object identifiers must be assigned to candidate IDUP-GSS-API 2048 mechanisms and the name types which they support; and 2050 - concrete data element (i.e., token and parameter bundle) formats 2051 must be defined for candidate mechanisms. 2053 Calling applications must implement formatting conventions which will 2054 enable them to distinguish IDUP-GSS-API P-IDUs from other 2055 IDUs in their environment. 2057 Concrete language bindings are required for the programming 2058 environments in which the IDUP-GSS-API is to be employed; such a 2059 binding for the C language are available in the Internet Draft 2060 [IDUP-C]. 2062 4. Acknowledgments 2064 Many thanks are due to Warwick Ford, Paul Van Oorschot, and Tim Moses 2065 of Bell-Northern Research, and to Denis Pinkas of Bull, for a number 2066 of helpful comments. 2068 5. Security Considerations 2070 Security issues are discussed throughout this memo. 2072 Adams Document Expiration: 11 Dec. 1996 40 2073 6. REFERENCES 2075 [MSP]: U.S. National Security Agency, "Message Security 2076 Protocol", Secure Data Network System SDN.701, March 1994. 2078 [RFC-1421]: J. Linn, "Privacy Enhancement for Internet Electronic 2079 Mail: Part I: Message Encryption and Authentication Procedures", 2080 RFC 1421. 2082 [RFC-1508]: J. Linn, "Generic Security Service Application Program 2083 Interface", RFC 1508. 2085 [GSSv2]: J. Linn, "Generic Security Service Application Program 2086 Interface, Version 2", Internet Draft draft-ietf-cat-gssv2-0x.txt 2087 (work in progress). 2089 [KRB5]: J. Linn, "The Kerberos Version 5 GSS-API Mechanism", 2090 Internet Draft draft-ietf-cat-kerb5gss-0x.txt (work in progress). 2092 [SPKM]: C. Adams, "The Simple Public-Key GSS-API Mechanism 2093 (SPKM)", Internet Draft draft-ietf-cat-spkmgss-0x.txt (work in 2094 progress). 2096 [IDUP-C]: D. Thakkar, D. Grebovich, "Independent Data Unit 2097 Protection Generic Security Service Application Program Interface: C- 2098 bindings", Internet Draft draft-ietf-cat-idup-cbind-0x.txt (work in 2099 progress). 2101 [ISO/IEC]: 2nd ISO/IEC CD 13888-1, "Information technology - 2102 Security techniques - Non-repudiation - Part 1: General Model", 2103 ISO/IEC JTC 1/SC 27, May 30, 1995 2105 7. Author's Address 2107 Carlisle Adams 2108 NORTEL Secure Networks 2109 P.O.Box 3511, Station C 2110 Ottawa, Ontario, CANADA K1Y 4H7 2112 Phone: +1 613.763.9008 2113 E-mail: cadams@nortel.ca 2115 Adams Document Expiration: 11 Dec. 1996 41 2116 APPENDIX A 2118 MECHANISM-INDEPENDENT TOKEN FORMAT 2120 This appendix specifies a mechanism-independent level of 2121 encapsulating representation for IDUP-GSS-API tokens, incorporating 2122 an identifier of the mechanism type to be used when processing those 2123 tokens. Use of this format (with ASN.1-encoded data elements 2124 represented in BER, constrained in the interests of parsing 2125 simplicity to the Distinguished Encoding Rule (DER) BER subset 2126 defined in X.509, clause 8.7) is recommended to the designers of 2127 IDUP-GSS-API implementations based on various mechanisms, so that 2128 tokens can be interpreted unambiguously at IDUP-GSS-API peers. There 2129 is no requirement that the mechanism-specific token data element be 2130 encoded in ASN.1 BER. 2132 -- top-level token definition to frame different mechanisms 2134 IDUP-GSS-API DEFINITIONS ::= 2135 BEGIN 2136 MechType ::= OBJECT IDENTIFIER 2138 Token ::= [APPLICATION 0] IMPLICIT SEQUENCE { 2139 thisMech MechType, 2140 token ANY DEFINED BY thisMech 2141 -- contents mechanism-specific 2142 } 2143 END 2145 APPENDIX B 2147 MECHANISM DESIGN CONSTRAINTS 2149 The following constrain on IDUP-GSS-API mechanism designs is 2150 adopted in response to observed caller protocol requirements, and 2151 adherence thereto is anticipated in subsequent descriptions of 2152 IDUP-GSS-API mechanisms to be documented in standards-track Internet 2153 specifications. 2155 Use of the approach defined in Appendix A of this specification, 2156 applying a mechanism type tag to the Token is required. 2158 Adams Document Expiration: 11 Dec. 1996 42 2159 APPENDIX C 2161 EXAMPLES OF IDUP USE 2163 This appendix provides examples of the use of IDUP to do IDU protec- 2164 tion and unprotection. It should not be regarded as constrictive to 2165 implementations or as defining the only means through which 2166 IDUP-GSS-API functions can be realized with particular underlying 2167 technology, and does not demonstrate all IDUP-GSS-API features. 2169 C.1. Simple Mechanism, Single Buffer 2171 To illustrate the simplest possible case, consider an underlying IDUP 2172 mechanism which does straightforward encryption/decryption and 2173 signing/verification only; none of the other possible services, such 2174 as creation of proof-of-origin evidence, requests for proof-of- 2175 delivery evidence, or use of trusted time, are supported. PEM 2176 [RFC-1421] is one example of a mechanism which fits this description. 2177 Furthermore (again for simplicity), assume that encapsulation is 2178 chosen by the calling application during IDU protection. 2180 The following parameter bundle uses and defaults would therefore be 2181 specified in the relevant IDUP mechanism document. 2183 Mech_Specific_Info 2184 - NOT USED (the only acceptable input, therefore, is NULL) 2186 Idu_Sensitivity 2187 - NOT USED (the only acceptable input, therefore, is NULL) 2189 Service_Creation_Info 2190 - NOT USED (the only acceptable input, therefore, is NULL) 2192 Service_Verification_Info 2193 - NOT USED (the only acceptable input, therefore, is NULL) 2195 Quality 2196 - the qop_algs parameter must be supported, with a suitable 2197 DEFAULT value specified; 2198 - suitable DEFAULT values for validity, policy_id, and 2199 allow_policy_mapping must be specified (it may be an 2200 implementation option as to whether these parameters are 2201 explicitly modifiable by the calling application, or whether 2202 NULLs are the only acceptable input) 2204 Idu_Information 2205 - the idu_type parameter must have a value representing a suitable 2206 IDU type (for example, in PEM a value representing the string 2207 "RFC822" or some other valid "Content-Domain" would be used), 2208 with a suitable DEFAULT value specified; 2209 - the idu_title parameter is NOT USED (the only acceptable input, 2210 therefore, is NULL) 2212 Adams Document Expiration: 11 Dec. 1996 43 2213 Prot_Information 2214 - the originator_name and idu_type (in Idu_Information) parameters 2215 are read from the encapsulating information and output by 2216 IDUP_Start_Unprotect; 2217 - all other parameters are NOT USED (and therefore NULL) 2219 Special_Conditions 2220 - NOT USED (the only acceptable input, therefore, is NULL) 2222 Target_Info 2223 - this bundle is used as described in IDUP; no DEFAULT values are 2224 specified 2226 General_Service_Data 2227 - the unencapsulated_token parameter is used if 2228 encapsulation_request is FALSE; 2229 - the minor_status parameter is used to return minor status values 2230 as specified by the mechanism document 2232 Prot_Service 2233 - the prot_service_type parameter may have a value of "1" 2234 ("perform unsolicited service") or NULL (which specifies the 2235 DEFAULT value of "1"); 2236 - the service_id parameter must have a value representing 2237 "PER_CONF" or "PER_DOA"; 2238 - the parameters Service_Creation_Info, service_to, 2239 Service_Verification_Info, and service_verification_info_id are 2240 NOT USED (and therefore NULL) 2242 Unprot_Service 2243 - the unprot_service_type parameter will always have a value of 2244 "1" ("receive unsolicited service"); 2245 - the service_id parameter will have a value representing 2246 "REC_CONF" or "REC_DOA"; 2247 - the parameters service_verification_info_id, 2248 Service_Verification_Info, service_to, and 2249 Service_Creation_Info, are NOT USED (and therefore NULL) 2251 Assuming that the calling application has only a single buffer of 2252 data to protect/unprotect, the following sequence of operations must 2253 be performed by the sender and receivers (subsequent to environment 2254 establishment). 2256 SENDER (any parameters not listed below are given the value NULL): 2258 Set 2259 env_handle = environment handle in use; 2260 encapsulation_request = TRUE; 2261 single_idu_buffer = data buffer; 2262 Target_Info.targ_names = receiver names; 2263 P_Services.Prot_Service_1.service_id = PER_CONF; 2264 P_Services.Prot_Service_2.service_id = PER_DOA; 2266 Adams Document Expiration: 11 Dec. 1996 44 2267 Call 2268 IDUP_Start_Protect() with above input parameters 2269 Check 2270 major_status. If not GSS_S_COMPLETE, check 2271 minor_status, 2272 Target_Info.bad_targ_names / Target_Info.bad_targ_status, 2273 P_Services.Prot_Service_1.General_Service_Data.minor_status, 2274 P_Services.Prot_Service_2.General_Service_Data.minor_status 2275 (as required) for more detailed information. 2277 Send 2278 Output parameter pidu_buffer to receiver. 2280 RECEIVER (any parameters not listed below are given the value NULL): 2282 Set 2283 env_handle = environment handle in use; 2284 single_pidu_buffer = received data buffer; 2286 Call 2287 IDUP_Start_Unprotect() with above input parameters 2288 Check 2289 major_status. If not GSS_S_COMPLETE, check 2290 minor_status, 2291 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2292 R_Services.Unprot_Service_2.General_Service_Data.minor_status 2293 (as required) for more detailed information 2295 Utilize 2296 R_Services.Unprot_Service_1/2.service_id, 2297 (to determine which services were applied by the originator) 2298 R_Services.Unprot_Service_1/2.Quality, 2299 (to determine the corresponding qualities of the services) 2300 Prot_Information.originator_name, 2301 (to determine the name of the originator) 2302 single_idu_buffer 2303 (to retrieve the unprotected data). 2305 Adams Document Expiration: 11 Dec. 1996 45 2306 C.2. Simple Mechanism, Multiple Buffers 2308 To illustrate the next step up in complexity, consider the use of the 2309 simple IDUP mechanism described above with multiple data buffers. In 2310 particular, consider the case in which a large data file is to be 2311 signed. For this example, assume that the calling application does 2312 not wish to use encapsulation. 2314 Note that the parameter bundle uses and defaults are as specified in 2315 C.1. above. 2317 SENDER (any parameters not listed below are given the value NULL): 2319 Set 2320 env_handle = environment handle in use; 2321 encapsulation_request = FALSE; 2322 P_Services.Prot_Service.service_id = PER_DOA; 2324 Call 2325 IDUP_Start_Protect() with above input parameters 2326 Check 2327 major_status. If not GSS_S_COMPLETE, check 2328 minor_status, 2329 P_Services.Prot_Service.General_Service_Data.minor_status 2330 (as required) for more detailed information. 2332 For each buffer of input data: 2333 Set 2334 input_buffer = buffer 2335 Call 2336 IDUP_Protect() with above input parameter 2337 Check 2338 major_status. If not GSS_S_COMPLETE, check 2339 minor_status 2341 Call 2342 IDUP_End_Protect() 2343 Check 2344 major_status. If not GSS_S_COMPLETE, check 2345 minor_status, 2346 P_Services.Prot_Service.General_Service_Data.minor_status 2347 (as required) for more detailed information. 2349 Send 2350 P_Services.Prot_Service.General_Service_Data.unencapsulated_token, 2351 the file for which the signature was calculated (if required) 2352 to receiver. 2354 Adams Document Expiration: 11 Dec. 1996 46 2355 RECEIVER (any parameters not listed below are given the value NULL): 2357 Set 2358 env_handle = environment handle in use; 2359 partial_pidu_buffer = received unencapsulated token; 2361 Call 2362 IDUP_Start_Unprotect() with above input parameters 2363 Check 2364 major_status. If not GSS_S_COMPLETE, check 2365 minor_status, 2366 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2367 (as required) for more detailed information 2369 For each buffer of input data: 2370 Set 2371 input_buffer = buffer 2372 Call 2373 IDUP_Unprotect() with above input parameter 2374 Check 2375 major_status. If not GSS_S_COMPLETE, check 2376 minor_status 2378 Call 2379 IDUP_End_Unprotect() 2380 Check 2381 major_status. If not GSS_S_COMPLETE, check 2382 minor_status, 2383 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2384 (as required) for more detailed information. 2386 Utilize 2387 R_Services.Unprot_Service_1.service_id, 2388 (to determine which service was applied by the originator; note 2389 that Unprot_Service_2 will have NULL in unprot_service_type 2390 to indicate that it is not used) 2391 R_Services.Unprot_Service_1.Quality, 2392 (to determine the corresponding quality of the service) 2393 Prot_Information.originator_name, (from IDUP_Start_Unprotect) 2394 (to determine the name of the signer) 2395 major_status (from IDUP_End_Unprotect) 2396 (to determine pass/fail status of signature verification). 2398 Adams Document Expiration: 11 Dec. 1996 47 2399 C.3. More Sophisticated Mechanism, Small Application Buffers 2401 To illustrate a higher level of complexity, consider the use of a 2402 more sophisticated IDUP mechanism and a calling application with 2403 small data buffers. In particular, consider the case in which a very 2404 small e-mail message is to be encrypted for a relatively large 2405 receiver list (R), some subset of whom (r) will be asked to send 2406 proofs of receipt of the message to some other subset (L) (which 2407 includes the originator). So that the example is not unnecessarily 2408 complicated, assume again that the originating application uses 2409 encapsulation. 2411 The uses and defaults for the various parameter bundles for this 2412 mechanism would be specified in the relevant IDUP mechanism document 2413 as follows. 2415 Mech_Specific_Info 2416 - NOT USED (the only acceptable input, therefore, is NULL) 2418 Idu_Sensitivity 2419 - NOT USED (the only acceptable input, therefore, is NULL) 2421 Service_Creation_Info 2422 - used to create "proof of delivery" evidence (but actual 2423 structure is opaque to calling application) 2425 Service_Verification_Info 2426 - used to verify "proof of delivery" evidence (but actual 2427 structure is opaque to calling application) 2429 Quality 2430 - the qop_algs parameter must be supported, with a suitable 2431 DEFAULT value specified; 2432 - suitable DEFAULT values for validity, policy_id, and 2433 allow_policy_mapping must be specified (it may be an 2434 implementation option as to whether these parameters are 2435 explicitly modifiable by the calling application, or whether 2436 NULLs are the only acceptable input) 2438 Idu_Information 2439 - the idu_type parameter must have a value representing a suitable 2440 IDU type, with a suitable DEFAULT value specified; 2441 - the idu_title parameter must have a value representing a 2442 suitable IDU title, with a suitable DEFAULT value specified 2444 Prot_Information 2445 - the originator_name, protection_time, and idu_type / idu_title 2446 (in Idu_Information) parameters are read from the contained 2447 header information and output by IDUP_Start_Unprotect; 2449 Special_Conditions 2450 - the parameter prot_oper_id is NOT USED (the only acceptable 2451 input, therefore, is NULL); 2452 - trusted or untrusted time may be selected by the calling 2453 application, with a suitable DEFAULT value specified 2455 Adams Document Expiration: 11 Dec. 1996 48 2456 Target_Info 2457 - this bundle is used as described in IDUP; no DEFAULT values are 2458 specified 2460 General_Service_Data 2461 - the unencapsulated_token parameter is used if 2462 encapsulation_request is FALSE; 2463 - the minor_status parameter is used to return minor status values 2464 as specified by the mechanism document 2466 Prot_Service 2467 - the prot_service_type parameter may have a value of "1" 2468 ("perform unsolicited service"), "2" ("perform solicited 2469 service"), "3" (perform service solicitation), or NULL (which 2470 specifies the DEFAULT value of "1"); 2471 - the service_id parameter must have a value representing 2472 "PER_CONF", "PER_DOA", "PER_POO", or "PER_POD"; 2473 - the parameters Service_Creation_Info, service_to, 2474 Service_Verification_Info, and service_verification_info_id are 2475 used when required by the IDUP operation 2477 Unprot_Service 2478 - the unprot_service_type parameter may have a value of "1" 2479 ("receive unsolicited service"), "2" ("receive solicited 2480 service"), or "3" (receive service solicitation); 2481 - the service_id parameter will have a value representing 2482 "REC_CONF", "REC_DOA", "REC_POO", or "REC_POD"; 2483 - the parameters service_verification_info_id, 2484 Service_Verification_Info, service_to, and 2485 Service_Creation_Info, are used when required by the IDUP 2486 operation 2488 SENDER (any parameters not listed below are given the value NULL): 2490 Set 2491 env_handle = environment handle in use; 2492 Idu_Information.idu_type = value for "e-mail document"; 2493 Idu_Information.idu_title = "Contract 1234"; 2494 Special_Conditions.use_trusted_time = TRUE; 2495 encapsulation_request = TRUE; 2496 single_idu_buffer = very small e-mail message; 2497 Target_Info.targ_names = receiver names (R); 2498 Prot_Service_1.prot_service_type = "1"; 2499 Prot_Service_1.service_id = PER_CONF; 2500 Prot_Service_2.prot_service_type = "3"; 2501 Prot_Service_2.service_id = PER_POD; 2502 Prot_Service_2.General_Service_Data.Target_Info.targ_names 2503 = "receipts from" list (r); 2504 Prot_Service_2.service_to = "receipts to" list (L); 2505 P_Services.Prot_Service_1 = Prot_Service_1; 2506 P_Services.Prot_Service_2 = Prot_Service_2; 2508 Adams Document Expiration: 11 Dec. 1996 49 2509 Call 2510 IDUP_Start_Protect() with above input parameters 2511 Check 2512 major_status. If not GSS_S_COMPLETE, 2513 while major_status == GSS_S_CONTINUE_NEEDED 2514 Save 2515 pidu_buffer, 2516 Call 2517 IDUP_Start_Protect() (to get next portion of pidu_buffer) 2518 Check 2519 major_status, 2520 minor_status, 2521 Target_Info.bad_targ_names / Target_Info.bad_targ_status, 2522 P_Services.Prot_Service_1.General_Service_Data.minor_status, 2523 P_Services.Prot_Service_2.General_Service_Data.minor_status 2524 (as required) for more detailed information. 2526 Save 2527 Prot_Service_2.Service_Verification_Info, 2528 Prot_Service_2.service_verification_info_id 2530 Send 2531 All saved buffers of pidu_buffer to receiver list (R). 2533 RECEIVER (ON RECEIVER LIST (R)): 2534 (any parameters not listed below are given the value NULL) 2536 Set 2537 env_handle = environment handle in use; 2538 partial_pidu_buffer = initial buffer of received p-idu; 2540 Call 2541 IDUP_Start_Unprotect() with above input parameters 2542 While major_status == IDUP_S_MORE_PIDU_NEEDED, 2543 Set 2544 partial_pidu_buffer = next buffer of p-idu 2545 Call 2546 IDUP_Start_Unprotect() 2547 Check 2548 major_status, 2549 minor_status, 2550 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2551 R_Services.Unprot_Service_2.General_Service_Data.minor_status, 2552 (as required) for more detailed information 2554 Save 2555 initial_idu_buffer (if non-empty) 2557 Adams Document Expiration: 11 Dec. 1996 50 2558 Set 2559 input_buffer = remaining p-idu buffer 2560 Call 2561 IDUP_Unprotect() with above input parameter 2562 Check 2563 major_status. If not GSS_S_COMPLETE, check 2564 minor_status 2565 Save 2566 output_buffer 2568 Call 2569 IDUP_End_Unprotect() 2570 Check 2571 major_status. If not GSS_S_COMPLETE, check 2572 minor_status, 2573 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2574 R_Services.Unprot_Service_2.General_Service_Data.minor_status, 2575 (as required) for more detailed information. 2577 Utilize 2578 R_Services.Unprot_Service_1/2.service_id, 2579 (to determine which services were applied by the originator) 2580 R_Services.Unprot_Service_1/2.Quality, 2581 (to determine the corresponding qualities of the service) 2582 Prot_Information.originator_name/protection_time and 2583 Prot_Information.Idu_Information.idu_type/idu_title, 2584 (from IDUP_Start_Unprotect) (to determine originator info.) 2585 R_Services.Unprot_Service_2.General_Service_Data.Target_Info. 2586 targ.names, (to determine if rec. is in "receipts from" (r)) 2587 Service_Verification_Info/service_verification_info_id 2588 (to determine if receiver is in "receipts to" list (L)) 2590 If receiver is in "receipts from" list (r) 2591 Save 2592 R_Services.Unprot_Service_2.service_to, 2593 R_Services.Unprot_Service_2.Service_Creation_Info 2595 If receiver is in "receipts to" list (L) 2596 Save 2597 Service_Verification_Info, 2598 service_verification_info_id 2600 Adams Document Expiration: 11 Dec. 1996 51 2601 RECEIVER (ON "RECEIPTS FROM" LIST (r)): 2602 (procedure to generate receipt) 2604 Set 2605 env_handle = environment handle in use; 2606 Target_Info.targ_names = service_to 2607 Prot_Service_1.prot_service_type = "2"; 2608 Prot_Service_1.service_id = "PER_POD"; 2609 Prot_Service_1.Service_Creation_Info = Service_Creation_Info; 2610 P_Services.Prot_Service_1 = Prot_Service_1 2612 Call 2613 IDUP_Start_Protect() with above input parameters 2614 Check 2615 major_status. If not GSS_S_COMPLETE, check 2616 minor_status, 2617 P_Services.Prot_Service_1.General_Service_Data.minor_status 2618 (as required) for more detailed information. 2620 Send 2621 pidu_buffer to "receipts to" list (L) 2623 RECEIVER (ON "RECEIPTS TO" LIST (L)): 2624 (procedure to process received receipt) 2626 Set 2627 env_handle = environment handle in use; 2628 single_pidu_buffer = received p-idu buffer (if it fits in a single 2629 buffer; otherwise use partial_pidu_buffer and make multiple 2630 calls, as above) 2632 Call 2633 IDUP_Start_Unprotect() with above input parameters 2634 If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED 2635 Utilize 2636 R_Services.Unprot_Service_1.service_verification_info.id 2637 (to assist in locating necessary Service_Verification_Info) 2638 Set 2639 R_Services.Unprot_Service_1.Service_Verification_Info 2640 = Service_Verification_Info 2641 Call 2642 IDUP_Start_Unprotect() with above input parameters 2643 Check 2644 major_status, 2645 minor_status, 2646 R_Services.Unprot_Service_1.General_Service_Data.minor_status 2647 (as required) for more detailed information. 2649 Utilize 2650 R_Services.Unprot_Service_1.service_id, 2651 (to determine that this is a "proof of delivery" evidence) 2652 R_Services.Unprot_Service_1.Quality, 2653 Prot_Information.originator_name, (for evidence generator info.) 2654 major_status (to determine pass/fail status of evi. verif.). 2656 Adams Document Expiration: 11 Dec. 1996 52