idnits 2.17.1 draft-ietf-cat-idup-gss-04.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-19) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 2654 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 535 has weird spacing: '...ish_Env esta...' == Line 544 has weird spacing: '...Protect begi...' == Line 554 has weird spacing: '...protect end ...' == Line 558 has weird spacing: '...vidence inser...' == Line 563 has weird spacing: '..._status tran...' == (3 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'APPLICATION 0' is mentioned on line 1821, 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, Bell-Northern Research 2 draft-ietf-cat-idup-gss-04.txt Feb. 18, 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: 18 Aug. 1996 1 58 As with RFC-1508, this IDUP-GSS-API definition provides security 59 services to callers in a generic fashion, supportable with a range of 60 underlying mechanisms and technologies and hence allowing source- 61 level portability of applications to different environments. This 62 specification defines IDUP-GSS-API services and primitives at a level 63 independent of underlying mechanism and programming language environ- 64 ment, and is to be complemented by other, related specifications: 66 - documents defining specific parameter bindings for particular 67 language environments; 68 - documents defining token formats, protocols, and procedures to 69 be implemented in order to realize IDUP-GSS-API services atop 70 particular security mechanisms. 72 TABLE OF CONTENTS 73 1. IDUP-GSS-API Characteristics and Concepts .................. 3 74 1.1. IDUP-GSS-API Constructs .................................. 5 75 1.1.1. Credentials ............................................ 5 76 1.1.2. Tokens ................................................. 5 77 1.1.3. Security Environment ................................... 5 78 1.1.4. Mechanism Types ........................................ 5 79 1.1.5. Naming ................................................. 5 80 1.1.6. Channel Bindings ....................................... 6 81 1.2. IDUP-GSS-API Features and Issues ......................... 6 82 1.2.1. Status Reporting ....................................... 6 83 1.2.2. Per-IDU Security Service Availability .................. 7 84 1.2.3. Per-IDU Replay Detection and Sequencing ................ 7 85 1.2.4. Quality of Protection .................................. 7 86 1.2.5. The Provision of Time .................................. 10 87 2. Interface Descriptions ..................................... 10 88 2.1. Credential management calls .............................. 11 89 2.1.1. Relationship to GSS-API ................................ 11 90 2.2. Environment-level calls .................................. 12 91 2.2.1. Relationship to GSS-API ................................ 12 92 2.2.2. IDUP_Establish_Env call ................................ 13 93 2.2.3. IDUP_Abolish_Env call .................................. 15 94 2.2.4. IDUP_Inquire_Env call .................................. 16 95 2.3. Per-IDU calls ............................................ 17 96 2.3.1. Relationship to GSS-API ................................ 17 97 2.3.2. Parameter Bundles ...................................... 17 98 2.3.3. IDUP_Start_Protect ..................................... 21 99 2.3.4. IDUP_Protect ........................................... 24 100 2.3.5. IDUP_End_Protect ....................................... 25 101 2.3.6. IDUP_Start_Unprotect ................................... 26 102 2.3.7. IDUP_Unprotect ......................................... 29 103 2.3.8. IDUP_End_Unprotect ..................................... 29 104 2.4. Special-Purpose calls .................................... 31 105 2.4.1. Relationship to GSS-API ................................ 31 106 2.4.5. IDUP_Form_Complete_Evidence ............................ 31 108 Adams Document Expiration: 18 Aug. 1996 2 110 2.5. Support calls ............................................ 32 111 2.5.1. Relationship to GSS-API ................................ 32 112 2.5.2. IDUP_Parse_token call .................................. 32 113 3. Related Activities ......................................... 33 114 4. Acknowledgments ............................................ 33 115 5. Security Considerations .................................... 33 116 6. References ........................................... 34 117 7. Author's Address ........................................... 34 118 Appendix A, B ................................................. 35 120 1. IDUP-GSS-API Characteristics and Concepts 122 The paradigm within which IDUP-GSS-API operates is as follows. An 123 IDUP-GSS-API caller is any application which works with IDUs, calling 124 on IDUP-GSS-API in order to protect its IDUs with services such as 125 data origin authentication with integrity (DOA), confidentiality with 126 integrity (CONF), and/or support for non-repudiation (e.g., evidence 127 generation, where "evidence" is information that either by itself or 128 when used in conjunction with other information is used to establish 129 proof about an event or action (note: the evidence itself does not 130 necessarily prove truth or existence of something, but contributes to 131 establish proof) -- see [ISO/IEC] for fuller discussion regarding 132 evidence and its role in various types of non-repudiation). An 133 IDUP-GSS-API caller passes an IDU to, and accepts a token from, its 134 local IDUP-GSS-API implementation, transfering the resulting 135 protected IDU (P-IDU) to a peer or to any storage medium. When a 136 P-IDU is to be "unprotected", it must be passed to an IDUP-GSS-API 137 implementation for processing. The security services available 138 through IDUP-GSS-API in this fashion are implementable over a range 139 of underlying mechanisms based on secret-key and/or public-key 140 cryptographic technologies. 142 During the protection operation, the input IDU buffers may be 143 modified (for example, the data may be encrypted or encoded in some 144 way) or may remain unchanged. In any case, the result is termed a 145 "M-IDU" (Modified IDU) in order to distinguish it from the original 146 IDU. Depending on the desire of the calling application and the 147 capabilities of the underlying IDUP mechanism, the token produced by 148 the protection processing may or may not encapsulate the M-IDU. 149 Thus, the P-IDU may be the token alone (if encapsulation is done) or 150 may be the logical concatenation of the token and the M-IDU (if 151 encapsulation is not done). In the latter case, the protecting 152 application may choose whatever method it wishes to concatenate or 153 combine the token and the M-IDU into a P-IDU, provided the 154 unprotecting application knows how to de-couple the P-IDU back into 155 its component parts prior to calling the IDUP unprotection set of 156 functions. 158 The IDUP-GSS-API separates the operation of initializing a security 159 environment (the IDUP_Establish_Env() call) from the operations of 160 providing per-IDU protection, for IDUs subsequently protected in 161 conjunction with that environment. Per-IDU protection and 162 unprotection calls provide DOA, CONF, evidence, and other services, 163 as requested by the calling application and as supported by the 164 underlying mechanism. 166 Adams Document Expiration: 18 Aug. 1996 3 168 The following paragraphs provide an example illustrating the 169 dataflows involved in the use of the IDUP-GSS-API by the sender and 170 receiver of a P-IDU in a mechanism-independent fashion. The example 171 assumes that credential acquisition has already been completed by 172 both sides. Furthermore, the example does not cover all possible 173 options available in the protection/unprotection calls. 175 The sender first calls IDUP_Establish_Env() to establish a 176 security environment. Then, for the IDU to be protected the 177 sender calls IDUP_Start_Protect(), IDUP_Protect() for each buffer 178 of data, and IDUP_End_Protect() to complete the IDU protection. 179 The resulting P-IDU, which may (depending on whether or not 180 encapsulation was chosen/available) be either the token itself 181 or the logical concatenation of the token and the M-IDU, is now 182 ready to be sent to the target. The sender then calls 183 IDUP_Abolish_Env() to flush all environment-specific information. 185 The receiver first calls IDUP_Establish_Env() to establish a 186 security environment in order to unprotect the P-IDU. Then, for 187 the received P-IDU the receiver calls IDUP_Start_Unprotect(), 188 IDUP_Unprotect() for each buffer of data, and IDUP_End_Unprotect() 189 to complete the P-IDU unprotection. The receiver then calls 190 IDUP_Abolish_Env() to flush all environment-specific information. 192 It is important to note that absolutely no synchronization is implied 193 or expected between the data buffer size used by the sender as input 194 to the protection calls, the data buffer size used by the receiver as 195 input to the unprotection calls, and the block sizes required by the 196 underlying protection algorithms (integrity and confidentiality). 197 All these sizes are meant to be independent; furthermore, the data 198 buffer sizes used for the protection and unprotection calls are 199 purely a function of the local environment where the calls are made. 201 The IDUP-GSS-API design assumes and addresses several basic goals, 202 including the following. 204 Mechanism independence: The IDUP-GSS-API defines an interface to 205 cryptographically implemented security services at a generic level 206 which is independent of particular underlying mechanisms. For 207 example, IDUP-GSS-API-provided services can be implemented by 208 secret-key technologies or public-key approaches. 210 Protocol environment independence: The IDUP-GSS-API is independent 211 of the communications protocol suites which may be used to 212 transfer P-IDUs, permitting use in a broad range of protocol 213 environments. 215 Protocol association independence: The IDUP-GSS-API's security 216 environment construct has nothing whatever to do with 217 communications protocol association constructs, so that 218 IDUP-GSS-API services can be invoked by applications, wholly 219 independent of protocol associations. 221 Adams Document Expiration: 18 Aug. 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: 18 Aug. 1996 5 279 1.1.6. Channel Bindings 281 The concept of channel bindings discussed in GSS-API [RFC-1508] is 282 not relevant to the IDUP-GSS-API. 284 1.2. IDUP-GSS-API Features and Issues 286 This section describes aspects of IDUP-GSS-API operations and of the 287 security services which the IDUP-GSS-API provides. It also provides 288 commentary on design issues. 290 1.2.1. Status Reporting 292 Status reporting in IDUP-GSS-API is to be understood and used as 293 described in GSS-API [RFC-1508], with the addition of the following 294 IDUP-GSS-API major status codes. 296 As with GSS-API, minor_status codes, which provide more detailed 297 status information than major_status codes, and which may include 298 status codes specific to the underlying security mechanism, are not 299 specified in this document. 301 Table 1: IDUP-GSS-API Major Status Codes 303 Fatal Error Codes 305 IDUP_S_BAD_TARG_INFO all target information is invalid or 306 unsuitable for IDU protection 308 IDUP_S_BAD_DOA_KEY DOA key has expired or been revoked 310 IDUP_S_BAD_KE_KEY key used for key establishment between 311 orig. and targ. has exp. or been revoked 313 IDUP_S_BAD_ENC_IDU encrypted IDU is defective/invalid 315 IDUP_S_EVIDENCE_TOKEN_INCOMPLETE 316 there is not enough info. in token for evidence verification 318 IDUP_S_SERV_VERIF_INFO_NEEDED 319 the Service_Verification_Info parameter bundle is required 321 IDUP_S_SERVICE_UNAVAIL mech. does not support requested service 323 IDUP_S_REQ_TIME_SERVICE_UNAVAIL 324 the time service requested is not avail. in this environment 326 Adams Document Expiration: 18 Aug. 1996 6 328 IDUP_S_NO_ENV no environment recognized for env_handle 330 IDUP_S_NO_MATCH Service_Verification_Info and input token 331 do not match 333 IDUP_S_UNKNOWN_OPER_ID requested operation id. is unsupported 335 Informatory Status Codes 337 IDUP_S_ENCAPSULATION_UNAVAIL 338 encapsulation of M-IDU into pidu_buffer is not supported 340 IDUP_S_MORE_PIDU_NEEDED 341 more p-idu data is needed for IDUP_Start_Unprotect() 343 IDUP_S_MORE_DATA_NEEDED 344 more data is needed for protection or unprotection 346 1.2.2. Per-IDU Security Service Availability 348 Per-IDU security service availability in IDUP-GSS-API is to be 349 understood and used as described in GSS-API [RFC-1508], with the 350 exception that any combination of services requested by the calling 351 application and supported by the underlying mechanism can be applied 352 simultaneously to any IDU. 354 GSS-API callers desiring per-message security services should check 355 the relevant service OBJECT IDs at environment establishment time to 356 ensure that what is available in the established environment is 357 suitable for their security needs. 359 1.2.3. Per-IDU Replay Detection and Sequencing 361 The concept of per-IDU replay detection and sequencing discussed 362 in GSS-API [RFC-1508] is not relevant to the IDUP-GSS-API. 364 1.2.4. Quality of Protection 366 The concept of QOP control in IDUP-GSS-API is to be understood 367 essentially as described in GSS-API [RFC-1508]. However, the actual 368 description and use of the QOP parameter is given as follows. 370 Adams Document Expiration: 18 Aug. 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: 18 Aug. 1996 8 428 When qop_algs is used to select a DOA/integrity algorithm: 430 00000 (0) = default integrity algorithm 431 00001 (1) = IDUP_INT_ALG_DIG_SIGNATURE 432 00010 (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE 433 11111 (31) = IDUP_NO_INTEGRITY 435 Clearly, qualifiers such as strong, medium, and weak are debatable 436 and likely to change with time, but for the purposes of this version 437 of the specification we define these terms as follows. A confiden- 438 tiality algorithm is "weak" if the effective key length of the cipher 439 is 40 bits or less; it is "medium-strength" if the effective key 440 length is strictly between 40 and 80 bits; and it is "strong" if the 441 effective key length is 80 bits or greater. ("Effective key length" 442 describes the computational effort required to break a cipher using 443 the best-known cryptanalytic attack against that cipher.) 445 A five-bit TS field allows up to 30 qualifiers for each of 446 confidentiality and integrity (since "0" is reserved for "default" 447 and "31" is reserved for "none", as shown above). This document 448 specifies three for confidentiality and two for integrity, leaving a 449 lot of room for future specification. Suggestions of qualifiers such 450 as "fast", "medium-speed", and "slow" have been made, but such terms 451 are difficult to quantify (and in any case are platform- and 452 processor-dependent), and so have been left out of this initial 453 specification. The intention is that the TS terms be quantitative, 454 environment-independent qualifiers of algorithms, as much as this is 455 possible. 457 Use of the qop_algs parameter as defined above is ultimately meant to 458 be as follows. 460 - TS values are specified at the IDUP-GSS-API level and are 461 therefore portable across mechanisms. Applications which know 462 nothing about algorithms are still able to choose "quality" of 463 protection for their message tokens. 465 - MA values are specified at the mechanism level and are therefore 466 portable across implementations of a mechanism. 468 - IA values are specified at the implementation level (in user 469 documentation, for example) and are therefore typically non- 470 portable. An application which is aware of its own mechanism 471 implementation and the mechanism implementation of its intended 472 P-IDU recipient, however, is free to use these values since they 473 will be perfectly valid and meaningful for protecting IDUs 474 between those entities. 476 The receiver of a P-IDU must pass back to its calling application 477 (in IDUP_Start_Unprotect()) a qop_algs parameter with all relevant 478 fields set. For example, if triple-DES has been specified by a 479 mechanism as algorithm 8, then a receiver of a triple-DES-protected 480 P-IDU must pass to its application (TS=1, IA=0, MA=8). In this way, 481 the application is free to read whatever part of the qop_algs 482 paramater it understands (TS or IA/MA). 484 Adams Document Expiration: 18 Aug. 1996 9 486 1.2.5. The Provision of Time 488 IDUP mechanisms should make provision in their protocols for the 489 carrying of time information from originator to target(s). That is, 490 a target (a legitimate recipient) should get some indication during 491 unprotection regarding the time at which the protection operation 492 took place. This is particularly important if the mechanism offers 493 non-repudiation services because in some cases evidence verification 494 may only be achievable if the time at which the evidence was 495 generated is known. 497 Depending upon the platform and resources available to the 498 implementation, an IDUP environment may have access to a source of 499 trusted (secure) time, untrusted (local) time, both kinds of time, or 500 no time. OBJECT IDs indicating such availability are returned by the 501 IDUP_Establish_Env() call. When starting a protection operation, an 502 application may specify which time services it wishes to have applied 503 to the IDU. Similarly, for unprotection, an application may specify 504 which kind of time (if any) to consult when the validity of the P-IDU 505 is to be established. Specifying both kinds of time is interpreted 506 to mean that the calling application does not care which kind of time 507 is used. 509 2. Interface Descriptions 511 This section describes the IDUP-GSS-API's operational interface, 512 dividing the set of calls offered into five groups. Credential 513 management calls are related to the acquisition and release of 514 credentials by API callers. Environment-level calls are related to 515 the management of the security environment by an API caller. Per-IDU 516 calls are related to the protection or unprotection of individual 517 IDUs in established security environments. Special-purpose calls 518 deal with unusual or auxiliary evidence generation/verification 519 requirements. Support calls provide extra functions useful to 520 IDUP-GSS-API callers. Table 2 groups and summarizes the calls in 521 tabular fashion (an asterisk marks the calls which are identical to 522 the GSS-API specification). 524 Table 2: IDUP-GSS-API Calls 526 CREDENTIAL MANAGEMENT 528 * GSS_Acquire_cred acquire credentials for use 529 * GSS_Release_cred release credentials after use 530 * GSS_Inquire_cred display information about credentials 531 * GSS_Add_cred add credential info. (see [GSSv2]) 533 ENVIRONMENT-LEVEL CALLS 535 IDUP_Establish_Env establish IDUP environment (to protect and 536 unprotect IDUs) 537 IDUP_Abolish_Env abolish env. when no longer needed 538 IDUP_Inquire_Env indicate characteristics of env. 540 Adams Document Expiration: 18 Aug. 1996 10 542 PER-IDU CALLS 544 IDUP_Start_Protect begin the protection process 545 IDUP_Protect protect the IDU (perhaps 1 buffer at a time) 546 IDUP_End_Protect end the protection process; create a token 547 which contains info. necessary for the 548 legitimate receiver(s) of the P-IDU to 549 unprotect it 551 IDUP_Start_Unprotect begin the unprotect process 552 IDUP_Unprotect use the token to unprotect the P-IDU 553 (possibly one buffer at a time) 554 IDUP_End_Unprotect end the unprotect process 556 SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms) 558 IDUP_Form_Complete_Evidence insert in evidence_token any data not 559 provided by the protection calls 561 SUPPORT CALLS 563 * GSS_Display_status translate status codes to printable form 564 * GSS_Indicate_mechs indicate mech_types supported on local 565 system 566 * GSS_Compare_name compare two names for equality 567 * GSS_Display_name translate name to printable form 568 * GSS_Import_name convert printable name to normalize form 569 * GSS_Release_name free storage of normalized-form name 570 * GSS_Release_buffer free storage of printable name 571 * GSS_Release_oid_set free storage of OID set 572 IDUP_Parse_Token examine an input token to determine mech_type 574 2.1. Credential management calls 576 2.1.1. Relationship to GSS-API 578 Credential management in IDUP-GSS-API is to be understood and used as 579 described in GSS-API [RFC-1508]. The calls GSS_Acquire_cred(), 580 GSS_Release_cred(), and GSS_Inquire_cred() are unchanged (the call 581 GSS_Add_cred() from GSS-API v2 [GSSv2] is also included). However, 582 the interpretation (and possible modification) of the cred_usage 583 parameter for IDUP purposes is for further study. 585 Adams Document Expiration: 18 Aug. 1996 11 587 2.2. Environment-level calls 589 This group of calls is devoted to the establishment and management of 590 an environment for the purpose of IDU protection and unprotection. 591 Before protecting or unprotecting any IDU, an application must call 592 IDUP_Establish_Env() to initialize environment information and select 593 the underlying IDUP-GSS mechanism to be used. A series of protection 594 or unprotection calls is made to process each IDU, the protection 595 calls resulting in a P-IDU for each. Finally, IDUP_Abolish_Env() 596 is called to flush all environment information. 598 Semantically, acquiring credentials and establishing an environment 599 is analogous to logging in to a system -- it authenticates a local 600 user to the system and gives that user access to a set of operations 601 which can be performed. 603 2.2.1. Relationship to GSS-API 605 The set of calls described in this section are used in place of the 606 calls GSS_Init_sec_context(), GSS_Accept_sec_context(), 607 GSS_Delete_sec_context(), GSS_Process_context_token(), and 608 GSS_Context_time() which are described in [RFC-1508], since those 609 calls are specific to a session-oriented environment. 611 Adams Document Expiration: 18 Aug. 1996 12 613 2.2.2. IDUP_Establish_Env call 615 Inputs: 617 o claimant_cred_handle CREDENTIAL HANDLE, 618 -- NULL parameter specifies "use default" 620 o req_mech_type OBJECT IDENTIFIER, 621 -- NULL parameter specifies "use default" 623 o req_policy OBJECT IDENTIFIER, 624 -- NULL parameter specifies "use default". 625 -- This environment-level policy identifier is separate from 626 -- the policy provisions connected with credentials, if they exist 628 o policy_time INTEGER, 629 -- the security policy rules available at the specified time 630 -- NULL parameter specifies "use default" 632 o req_services SET OF OBJECT IDENTIFIER, 634 Outputs: 636 o major_status INTEGER, 638 o minor_status INTEGER, 640 o env_handle ENVIRONMENT HANDLE, 642 o actual_mech_type OBJECT IDENTIFIER, 643 -- actual mechanism always indicated, never NULL 645 o actual_policy OBJECT IDENTIFIER, 646 -- actual policy always indicated, never NULL 648 o actual_policy_time, 649 -- actual time at which the above policy rules came into effect 651 o ret_services SET OF OBJECT IDENTIFIER, 653 Return major_status codes: 655 o GSS_S_COMPLETE indicates that environment-level information was 656 successfully initialized, and that IDU / P-IDU processing can 657 begin on the newly-established environment. 659 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 660 performed on the credential structure referenced by 661 claimant_cred_handle failed, preventing further processing from 662 being performed using that credential structure. 664 o GSS_S_NO_CRED indicates that no environment was established, 665 either because the input cred_handle was invalid or because the 666 caller lacks authorization to access the referenced credentials. 668 Adams Document Expiration: 18 Aug. 1996 13 670 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided 671 through the input claimant_cred_handle argument are no longer 672 valid, so environment establishment cannot be completed. 674 o GSS_S_BAD_MECH indicates that a mech_type unsupported by the 675 IDUP_GSS-API implementation was requested, causing the 676 environment establishment operation to fail. 678 o GSS_S_FAILURE indicates that environment setup could not be 679 accomplished for reasons unspecified at the IDUP-GSS-API level, 680 and that no interface-defined recovery action is available. 682 This routine is used by an application which protects or unprotects 683 IDUs. Using information in the credentials structure referenced by 684 claimant_cred_handle, IDUP_Establish_Env() initializes the data 685 structures required to protect or unprotect IDUs. The 686 claimant_cred_handle, if non-NULL, must correspond to a valid 687 credentials structure. 689 This routine returns an env_handle for all future references to 690 this environment; when protection, unprotection, or 691 IDUP_Abolish_Env() calls are made, this handle value will be used 692 as the input env_handle argument. 694 It is the caller's responsibility to establish a communications path 695 to the intended recipients of the P-IDU, and to transmit the P-IDU to 696 those recipients over that path. This may occur subsequent to the 697 IDUP_Abolish_Env() call. 699 The req_services parameter may be used by the calling application to 700 request that data origin authentication with integrity, 701 confidentiality with integrity, evidence generation, and/or evidence 702 verification services be available in the established environment. 703 Requests can also be made for "trusted" or "untrusted" time services. 704 Requesting evidence generation or verification indicates that the 705 calling application may wish to generate or verify evidence 706 information for non-repudiation purposes (note: an IDU protector may 707 request that a flag be inserted into a P-IDU asking a recipient to 708 provide an evidence of the type "non-repudiation of delivery"; 709 however, the IDUP-GSS-API cannot by itself guarantee that the 710 evidence will be sent because there is no way to force a target to 711 send an evidence_token back to the IDU protector). 713 Not all features will be available in all underlying mech_types; the 714 returned value of ret_services indicates, as a function 715 of mech_type processing capabilities and the initiator-provided input 716 OBJECT IDs, the set of features which will be available in the 717 environment. The value of this parameter is undefined unless the 718 routine's major_status indicates COMPLETE. Failure to provide the 719 precise set of services desired by the caller does not cause 720 environment establishment to fail; it is the caller's prerogative to 721 abolish the environment if the service set provided is unsuitable for 722 the caller's use. The returned mech_type value indicates the 723 specific mechanism employed in the environment, and will never 724 indicate the value for "default". 726 Adams Document Expiration: 18 Aug. 1996 14 728 The following OBJECT IDs are defined for protection and unprotection 729 services. It is recognized that this list may grow over time. 731 PER_CONF = { xx } 732 -- perform data confidentiality (i.e., encrypt data) 733 PER_DOA = { xx } 734 -- perform data origin authentication with data integrity 735 PER_POO = { xx } 736 -- perform (i.e., create) non-repudiable "proof of origin" 737 PER_POD = { xx } 738 -- perform (i.e., create) non-repudiable "proof of delivery" 739 REC_CONF = { xx } 740 -- receive data confidentiality (i.e., decrypt data) 741 REC_DOA = { xx } 742 -- receive / verify DOA with data integrity 743 REC_POO = { xx } 744 -- receive / verify "proof of origin" 745 REC_POD = { xx } 746 -- receive / verify "proof of delivery" 747 TTIME = { xx } 748 -- trusted time availability 749 UTIME = { xx } 750 -- untrusted time availability 752 The PER_CONF return value (in the ret_services paramater) indicates 753 whether the environment supports confidentiality services, and so 754 informs the caller whether or not a request for encryption through 755 a confidentiality service input to IDUP_Start_Protect() can be 756 honored. In similar fashion, the PER_DOA return value indicates 757 whether DOA services are available in the established environment, 758 and the PER_POO and PER_POD return values indicate whether evidence 759 generation services are available. The TTIME and UTIME values 760 indicate whether trusted time and untrusted time are available for 761 protection / unprotection services. 763 Note that, unlike a GSS "context", an IDUP environment does not have 764 an explicit lifetime associated with it. Instead, it relies on the 765 lifetime of the calling entity's credential (set by the caller in the 766 GSS_Acquire_cred() call). When the credential expires (or is 767 explicitly deleted using the gss_release_cred() call), no new 768 operations are allowed in the IDUP environment (although operations 769 which have begun, such as the Protection set of calls, can be taken 770 to completion). 772 2.2.3. IDUP_Abolish_Env call 774 Input: 776 o env_handle ENVIRONMENT HANDLE 778 Outputs: 780 o major_status INTEGER, 782 o minor_status INTEGER, 784 Adams Document Expiration: 18 Aug. 1996 15 786 Return major_status codes: 788 o GSS_S_COMPLETE indicates that the environment was recognized and 789 that relevant environment-specific information was flushed. 791 o IDUP_S_NO_ENV indicates that no valid environment was recognized 792 for the env_handle provided, so no deletion was performed. 794 o GSS_S_FAILURE indicates that the environment is recognized, but 795 that the requested operation could not be performed for reasons 796 unspecified at the IDUP-GSS-API level. 798 This call is made to flush environment-specific information. (Once an 799 environment is established, cached credential and environment-related 800 info. is expected to be retained until an IDUP_Abolish_Env() call is 801 made or until the cred. lifetime expires.) Attempts to perform IDU 802 processing on a deleted environment will result in error returns. 804 2.2.4: IDUP_Inquire_Env call 806 Input: 808 o env_handle ENVIRONMENT HANDLE, 810 Outputs: 812 o major_status INTEGER, 814 o minor_status INTEGER, 816 o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this env. 818 o policy OBJECT IDENTIFIER, -- the policy used in this env. 820 o policy_time, -- time at which the policy rules came into effect 822 o ret_services SET OF OBJECT IDENTIFIER, 824 Return major_status codes: 826 o GSS_S_COMPLETE indicates that the referenced environment is valid 827 and that mech_type and other return values describe the 828 corresponding characteristics of the environment. 830 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 831 recognized, but that its associated credentials have expired, so 832 that the requested operation cannot be performed. 834 o IDUP_S_NO_ENV indicates that no valid environment was recognized 835 for the env_handle provided, so no return values can be provided. 837 o GSS_S_FAILURE indicates that the environment is recognized, but 838 that the requested operation could not be performed for reasons 839 unspecified at the IDUP-GSS-API level. 841 This routine provides environment-related information to the caller. 843 Adams Document Expiration: 18 Aug. 1996 16 845 2.3. Per-IDU calls 847 This group of calls is used to perform IDU protection and 848 unprotection processing on an established IDUP environment. Some of 849 these calls may block pending network interactions (depending on the 850 underlying mechanism in use). These calls may be invoked by an IDU's 851 protector or by the P-IDU's recipient. The two sets of members of 852 this group form a pair; the output from the protection set is 853 typically meant to be input to the unprotection set. 855 The per-IDU calls can support caller-requested data origin 856 authentication with data integrity, confidentiality with data 857 integrity, evidence, and evidence-requested-from-target services. 858 The protection operations output a token which encapsulates all the 859 information required to unprotect the IDU. The token is passed to 860 the target (possibly separate from the M-IDU) and is processed by the 861 unprotection calls at that system. Unprotection performs 862 decipherment, DOA verification, evidence verification, or 863 notification of evidence requested, as required. 865 Each of the two main operations (protection and unprotection) may be 866 separated into three parts: "Start_Operation"; "Operation" (which 867 may be called once for each buffer of input data); and 868 "End_Operation". This separation is available for the case where the 869 IDU or P-IDU is to be processed one buffer at a time. 870 "Start_Operation" allows the caller to specify or retrieve the 871 appropriate "Quality" used during the processing. "Operation" is 872 concerned with the processing itself, receiving a buffer of input 873 data and potentially returning a buffer of output data. 874 "End_Operation" performs any required clean-up and creates the 875 appropriate token or states whether the input token was verified. 877 If the IDU or P-IDU is wholly contained in a single buffer, the 878 three-part protection/unprotection processing need not be done. 879 Instead, protection and unprotection can be accomplished using only 880 the "Start_Operation" call, simplifying application code. 882 2.3.1. Relationship to GSS-API 884 The set of calls described in this section are used in place of the 885 calls GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() -- now 886 named GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() -- 887 which are specified in [RFC-1508], since those calls are specific to 888 a session-oriented environment. 890 2.3.2. Parameter Bundles 892 The concept of "parameter bundles" is used in the calls presented in 893 the following subsections in order to simplify their presentation and 894 (hopefully) clarify their intended purpose and use. A parameter 895 bundle is simply a set of closely-related parameters of a call which 896 are either all used by / available to the calling application or all 897 not used by / unavailable to the calling application. These 898 parameters may be all input parameters, all output parameters, or 899 any combination of the two. 901 Adams Document Expiration: 18 Aug. 1996 17 903 A typical use envisioned for parameter bundles in a language such as 904 C would be as a structure, where individual parameters in the bundle 905 are structure members. The calling application wishing to use a 906 particular bundle would then allocate the appropriate structure 907 variable, assign the desired input values to the appropriate members, 908 and pass the address of the structure as the bundle "parameter". On 909 output, the values of the appropriate output members may be read. An 910 application not wishing to use a particular bundle (or one which is 911 satisfied with default values for all input parameters of the bundle 912 and which doesn't care about output values), can pass NULL as the 913 bundle "parameter". From the mechanism implementor's perspective, if 914 a parameter bundle is not supported (for example, if it represents a 915 security service which is not supported by the implementation), then 916 any non-NULL value passed as the bundle parameter will generate an 917 error status return code. 919 The following parameter bundles are used in the subsequent protection 920 and unprotection sets of calls. A parameter preceeded by "(I)" is an 921 input parameter; one preceeded by "(O)" is an output parameter; one 922 preceeded by neither is an input if the bundle itself is an input and 923 is an output if the bundle itself is an output. 925 o Mech_Specific_Info PARAMETER BUNDLE 926 -- actual parameters included in this bundle are defined by (and 927 -- specific to) the underlying mechanism 929 o Idu_Sensitivity PARAMETER BUNDLE, 930 -- actual parameters included in this bundle are defined by (and 931 -- specific to) the underlying mechanism, but may include 932 -- codified values for "Unclassified", "Secret", "Top Secret", 933 -- and so on 935 o Service_Creation_Info PARAMETER BUNDLE 936 -- actual parameters included in this bundle are defined by (and 937 -- specific to) the underlying mechanism, but it is mandatory 938 -- that they include at least service_id and Quality. 940 o Service_Verification_Info PARAMETER BUNDLE 941 -- actual parameters included in this bundle are defined by (and 942 -- specific to) the underlying mechanism, but it is mandatory 943 -- that they include at least service_id and Quality. 945 o Quality PARAMETER BUNDLE 947 o qop_algs UNSIGNED INTEGER, 949 o validity UNSIGNED INTEGER, 950 -- protection guaranteed to be valid until time specified 952 o policy_id OBJECT IDENTIFIER, 953 -- security policy under which protection is/was carried out 955 o allow_policy_mapping BOOLEAN, 956 -- determines whether or not mapping between policy 957 -- identifiers is allowed 959 Adams Document Expiration: 18 Aug. 1996 18 961 o Idu_Information PARAMETER BUNDLE, 963 o idu_type OBJECT IDENTIFIER, 965 o idu_title OCTET STRING, 967 o Idu_Sensitivity PARAMETER BUNDLE, 969 o Prot_Information PARAMETER BUNDLE, 971 o originator_name INTERNAL NAME, 973 o Idu_Information PARAMETER BUNDLE, 975 o protection_time INTEGER, 977 o Special_Conditions PARAMETER BUNDLE, 979 o prot_oper_id INTEGER, 981 o use_trusted_time BOOLEAN, 983 o use_untrusted_time BOOLEAN, 985 o Bad_Target_Name PARAMETER BUNDLE, 987 o (O) bad_targ_name INTERNAL NAME, 989 o (O) bad_targ_status INTEGER, 990 -- a (mechanism-defined) status flag giving the reason 991 -- for rejection of the name in bad_targ_name 993 o Target_Info PARAMETER BUNDLE, 995 o targ_names SET OF INTERNAL NAME, 997 o (O) bad_targ_count INTEGER, 999 o (O) Bad_Target_Name PARAMETER BUNDLE, 1001 o General_Service_Data PARAMETER BUNDLE, 1003 o Target_Info PARAMETER BUNDLE, 1005 o (O) unencapsulated_token OCTET STRING, 1006 -- zero length if encapsulation_request is TRUE; 1007 -- unused in the unprotection set of calls 1009 o (O) minor_status INTEGER, 1011 Adams Document Expiration: 18 Aug. 1996 19 1013 Three types of protection services are defined in IDUP. These are 1015 1. perform unsolicited service (i.e., act on a locally-generated 1016 service request), 1017 2. perform solicited service (i.e., act on a remotely-generated 1018 service request), and 1019 3. perform service solicitation (i.e., send a service request to 1020 the remote end). 1022 As an originator, applying data confidentiality with data integrity, 1023 or data origin authentication with data integrity, or proof of origin 1024 evidence is an example of service type 1. As a target, creating a 1025 proof of delivery (i.e., receipt) evidence token as the result of a 1026 request received from the originator is an example of service type 2. 1027 Finally, as an originator, submitting a request that one or more 1028 targets return a receipt for the data sent is an example of service 1029 type 3. 1031 The first four parameters in the Prot_Service parameter bundle 1032 pertain to all service types; the fifth parameter is used if and only 1033 if service type 2 is desired; parameters 6-8 are used if and only if 1034 service type 3 is desired. 1036 o Prot_Service PARAMETER BUNDLE 1038 o (I) prot_service_type INTEGER, 1040 o (I) service_id OBJECT IDENTIFIER, 1042 o (I) Quality PARAMETER BUNDLE, 1043 -- NULL specifies default Quality 1045 o (I) General_Service_Data PARAMETER BUNDLE, 1047 o (I) Service_Creation_Info PARAMETER BUNDLE, 1049 o (I) service_to SET OF INTERNAL NAME, 1051 o (O) Service_Verification_Info PARAMETER BUNDLE, 1053 o (O) service_verification_info_id INTEGER, 1055 Also, three types of unprotection services are defined. These are 1057 1. receive unsolicited service (i.e., process unrequested 1058 remotely-generated service), 1059 2. receive solicited service (i.e., process remotely-generated 1060 response to locally-generated request), and 1061 3. receive service solicitation (i.e., process req. from rem. end) 1063 As a target, unprotecting an encrypted message, or verifying the 1064 originator's proof of origin is an example of service type 1. As an 1065 originator, verifying a proof of delivery which you requested from a 1066 target is an example of service type 2. Finally, as a target, 1067 receiving a request from an originator for a proof of delivery is an 1068 example of service type 3. 1070 Adams Document Expiration: 18 Aug. 1996 20 1072 The first four parameters in the Unprot_Service parameter bundle 1073 pertain to all service types; parameters 5-6 are used if and only if 1074 service type 2 is required; parameters 7-8 are used only if service 1075 type 3 is required. 1077 o Unprot_Service PARAMETER BUNDLE 1079 o (O) unprot_service_type INTEGER, 1081 o (O) service_id OBJECT IDENTIFIER, 1083 o (O) Quality PARAMETER BUNDLE, 1084 -- actual Quality specified (never NULL) 1086 o (O) General_Service_Data PARAMETER BUNDLE, 1088 o (O) service_verification_info_id INTEGER, 1090 o (I) Service_Verification_Info PARAMETER BUNDLE, 1092 o (O) service_to SET OF INTERNAL NAME, 1094 o (O) Service_Creation_Info PARAMETER BUNDLE, 1096 2.3.3. IDUP_Start_Protect call 1098 Inputs: 1100 o env_handle ENVIRONMENT HANDLE, 1102 o Mech_Specific_Info PARAMETER BUNDLE, 1103 -- NULL selects the mechanism-defined default values 1105 o Idu_Information PARAMETER BUNDLE, 1107 o Special_Conditions PARAMETER BUNDLE, 1109 o encapsulation_request BOOLEAN, 1111 o single_idu_buffer OCTET STRING, 1112 -- non-zero length for this buffer means that Protect/End_Protect 1113 -- won't be called (i.e., entire IDU is contained in this buffer) 1115 o Target_Info PARAMETER BUNDLE, 1117 o Services_to_Perform SET OF Prot_Service, 1119 Outputs: 1121 o major_status INTEGER, 1123 o minor_status INTEGER, 1125 o midu_buffer OCTET STRING, 1126 -- zero length if encapsulation_request is TRUE or if 1127 -- single_idu_buffer has zero length 1129 Adams Document Expiration: 18 Aug. 1996 21 1131 o pidu_buffer OCTET STRING, 1132 -- zero length if encapsulation_request is FALSE or if 1133 -- single_idu_buffer has zero length 1135 Return major_status codes: 1137 o GSS_S_COMPLETE indicates that the protection process can begin 1138 (or has completed, if single_idu_buffer has non-zero length). 1140 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1141 supplied is too small to hold the generated data. The application 1142 should continue calling this routine (until GSS_S_COMPLETE is 1143 returned) in order to get all remaining data. 1145 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 1146 recognized, but that its associated credentials have expired, so 1147 that the requested operation cannot be performed. 1149 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1150 for the env_handle provided. 1152 o IDUP_S_ENCAPSULATION_UNAVAIL indicates that the underlying 1153 mechanism does not support encapsulation of the M-IDU into the 1154 token. 1156 o IDUP_S_MORE_DATA_NEEDED indicates whether protection is completed 1157 by this call or by IDUP_End_Protect() (e.g., whether more data 1158 buffers are required for evidence generation) 1160 o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 1161 does not support the service requested. 1163 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 1164 requested (TTIME or UTIME) is not available in the environment. 1166 o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 1167 is not recognized or supported in the underlying mechanism. 1169 o GSS_S_BAD_QOP indicates that the provided qop_algs value is not 1170 recognized or supported for the environment. 1172 o IDUP_S_BAD_TARG_INFO indicates that all the information regarding 1173 the target(s) is invalid or is insufficient for the protection of 1174 an IDU, so P-IDU cannot be created. 1176 o GSS_S_FAILURE indicates that the environment is recognized, but 1177 that the requested operation could not be performed for reasons 1178 unspecified at the IDUP-GSS-API level. 1180 Adams Document Expiration: 18 Aug. 1996 22 1182 Using the security environment referenced by env_handle, initialize 1183 the data structures required to begin the process of protecting the 1184 IDU buffers. The caller requests specific protection services by 1185 supplying the appropriate Prot_Service parameter bundles in 1186 Services_to_Perform. Each service is able to return a minor status 1187 code to the calling application, if necessary. 1189 The calling application, knowing the size of the IDU it wishes to 1190 protect and the buffer size which it has available to it, can choose 1191 to input the entire IDU in a single buffer and omit the subsequent 1192 IDUP_Protect() and IDUP_End_Protect() calls. Furthermore, the 1193 application can request that the resulting M-IDU be encapsulated in 1194 the token -- so that the token contains the entire P-IDU -- rather 1195 than having it be returned separately in midu_buffer. Encapsulation, 1196 however, may not be supported by all underlying mechanisms or 1197 implementations; if this is the case, the 1198 IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and 1199 M-IDU will be returned in midu_buffer. 1201 For those mechanisms which allow or require multiple stages of 1202 processing, each producing a different aspect of protection for the 1203 IDU, the operation identifier prot_oper_id is used to specify 1204 which stage is currently being requested by the application. An 1205 example where this would be useful is a mechanism which implements 1206 the signed Message Security Protocol [MSP]. As another example, a 1207 mechanism may choose to do a digital signature in two stages: one 1208 for the hashing of the message and another for the signature on the 1209 hash. The calling application would therefore use the protection set 1210 of calls on the IDU in stage 1 and then use the protection set of 1211 calls on the token (from stage 1) in stage 2. 1213 Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where 1214 "n" is the number of stages as defined by the mechanism (typically 1 1215 or 2)). The calling application uses this parameter to indicate to 1216 the underlying mechanism whether it wishes to do stage 1 of 1217 protection / unprotection processing, or stage 2, and so on. 1219 If one or more of the targets in targ_names cannot be used as a valid 1220 recipient of the P-IDU, these names will be returned in 1221 bad_targ_names (with associated status codes in bad_targ_status). As 1222 long as at least one of the targets can be used, this does not cause 1223 this call to fail; it is the caller's prerogative to discontinue IDU 1224 protection if the target set which can be used is unsuitable for the 1225 caller's purposes. Note that each Prot_Service parameter bundle can 1226 also input a list of targ_names; this is used if a separate list is 1227 to be used for that service only (the general list of targets is to 1228 be used for all services unless overridden in this way). 1230 Adams Document Expiration: 18 Aug. 1996 23 1232 2.3.4. IDUP_Protect call 1234 Inputs: 1236 o env_handle ENVIRONMENT HANDLE, 1238 o input_buffer OCTET STRING, 1240 Outputs: 1242 o major_status INTEGER, 1244 o minor_status INTEGER, 1246 o output_buffer OCTET STRING 1247 -- zero length if encapsulation_request was set to TRUE in 1248 -- IDUP_Start_Protect() 1250 Return major_status codes: 1252 o GSS_S_COMPLETE indicates that the input_buffer has successfully 1253 been included in the protection computation. 1255 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1256 for the env_handle provided. 1258 o GSS_S_FAILURE indicates that the environment is recognized, but 1259 that the required operation could not be performed for reasons 1260 unspecified at the IDUP-GSS-API level. 1262 Using the security environment referenced by env_handle, continue the 1263 protection processing on the data in input_buffer and, if the 1264 underlying mechanism defines this, put any resulting M-IDU data in 1265 output_buffer. The application calls this routine over and over 1266 again with new buffers of data until it has protected all the data 1267 buffers of the IDU. It then calls IDUP_End_Protect() to complete the 1268 protection processing. 1270 Adams Document Expiration: 18 Aug. 1996 24 1272 2.3.5. IDUP_End_Protect call 1274 Inputs: 1276 o env_handle ENVIRONMENT HANDLE, 1278 Outputs: 1280 o major_status INTEGER, 1282 o minor_status INTEGER, 1284 o Services_to_Perform SET OF Prot_Service, 1286 o final_midu_buffer OCTET STRING, 1287 -- zero length if encapsulation_request was set to TRUE in 1288 -- IDUP_Start_Protect(), in which case pidu is used 1290 o final_pidu_buffer OCTET STRING, 1291 -- zero length if encapsulation_request was set to FALSE in 1292 -- IDUP_Start_Protect(), in which case token and midu are used 1294 Return major_status codes: 1296 o GSS_S_COMPLETE indicates that the protection computation has been 1297 successfully completed and the resulting P-IDU is ready for 1298 transfer. If defined by the underlying mechanism, 1299 final_midu_buffer will contain any residual M-IDU data. 1301 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1302 supplied is too small to hold the generated data. The application 1303 should continue calling this routine (until GSS_S_COMPLETE is 1304 returned) in order to get all remaining data. 1306 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1307 for the env_handle provided. 1309 o GSS_S_FAILURE indicates that the environment is recognized, but 1310 that the requested operation could not be performed for reasons 1311 unspecified at the IDUP-GSS-API level. 1313 Using the security environment referenced by env_handle, complete the 1314 protection processing on the data and place the computed output in 1315 final_pidu_buffer (or final_midu_buffer and the unencapsulated_token 1316 parameter for each Prot_Service). If a service was requested from 1317 one or more targets in Start_Protect() - and if this is supported by 1318 the underlying mechanism - Service_Verification_Info will hold 1319 whatever data is necessary for the mechanism to verify a service 1320 returned by a target (unprotector) of the P-IDU. Successful 1321 application of IDUP_End_Protect() does not guarantee that the 1322 corresponding unprotection set of calls can necessarily be performed 1323 successfully when the P-IDU arrives at the target (for example, it 1324 may be damaged in transit). 1326 Adams Document Expiration: 18 Aug. 1996 25 1328 2.3.6. IDUP_Start_Unprotect call 1330 Inputs: 1332 o env_handle ENVIRONMENT HANDLE, 1334 o Mech_Specific_Info PARAMETER BUNDLE, 1335 -- NULL selects the mechanism-defined default values 1337 o single_pidu_buffer OCTET STRING, 1338 -- non-zero length for this buffer means that IDUP_Unprotect() and 1339 -- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU 1340 -- is contained in this buffer) 1342 o partial_pidu_buffer OCTET STRING, 1343 -- may be an arbitrary-sized piece of the full pidu (if the 1344 -- applications buffer isnt large enough to hold entire pidu), 1345 -- or may be a service token (if encapsulation was not used). 1346 -- Used if pidu_buffer will be input a buffer at a time (except 1347 -- that the final buffer must be passed in final_pidu_buffer 1348 -- rather than partial_pidu_buffer). Only one of 1349 -- single_pidu_buffer and partial(final)_pidu_buffer can have 1350 -- nonzero length. 1352 o final_pidu_buffer OCTET STRING, 1354 o Special_Conditions PARAMETER BUNDLE, 1356 Outputs: 1358 o major_status INTEGER, 1360 o minor_status INTEGER, 1362 o Services_to_Receive SET OF Unprot_Service, 1364 o Prot_Information PARAMETER BUNDLE, 1366 o single_idu_buffer OCTET STRING, 1367 -- if this buffer has non-zero length, then service processing has 1368 -- been completed on the data in single_pidu_buffer 1370 o initial_idu_buffer OCTET STRING, 1371 -- holds any data from partial(final)_pidu_buffer which has been 1372 -- unprotected; remaining data will be returned by Unprotect and 1373 -- End_Unprotect as they are called with successive buffers of 1374 -- pidu 1376 o Service_Verification_Info PARAMETER BUNDLE, 1377 -- used only if target is on "service_to" list in Unprot_Service 1379 o service_verification_info_id INTEGER, 1380 -- used only if target is on "service_to" list in Unprot_Service 1382 Adams Document Expiration: 18 Aug. 1996 26 1384 Return major_status codes: 1386 o GSS_S_COMPLETE indicates that unprotection processing can begin 1387 (or has completed, if single_idu_buffer has non-zero length). 1389 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1390 supplied is too small to hold the generated data. The application 1391 should continue calling this routine (until GSS_S_COMPLETE is 1392 returned) in order to get all remaining data. 1394 o IDUP_S_MORE_PIDU_NEEDED indicates that not enough of the P-IDU 1395 has been input yet for the completion of Start_Protect. The 1396 application should call this routine again with another buffer 1397 of P-IDU in partial_pidu_buffer. 1399 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 1400 on the received P-IDU failed, preventing further processing 1401 from being performed. 1403 o IDUP_S_MORE_DATA_NEEDED indicates whether unprotection is 1404 completed by this call or by IDUP_End_Unprotect() (e.g., whether 1405 more data buffers are required for unprotection) 1407 o GSS_S_DEFECTIVE_VERIF indicates that consistency checks performed 1408 on Service_Verification_Info failed, preventing further processing 1409 from being performed with that parameter. 1411 o IDUP_S_NO_MATCH indicates that Service_Verification_Info and 1412 the P-IDU to be verified do not match. 1414 o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 1415 does not support the service requested. 1417 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 1418 requested (TTIME or UTIME) is not available in the environment. 1420 o IDUP_S_EVIDENCE_TOKEN_INCOMPLETE indicates that more information 1421 is needed in the P-IDU in order to verify it (this may, if 1422 specified by the underlying mechanism, be an indication that 1423 the token is incomplete and IDUP_Form_Complete_Evidence() needs to 1424 be called to complete it). 1426 o IDUP_S_SERV_VERIF_INFO_NEEDED indicates that the 1427 Service_Verification_Info parameter bundle must be input in order 1428 for service verification to proceed. The output parameter 1429 service_verification_info_id contains an identifier which may be 1430 used by the calling application to locate the necessary 1431 information. 1433 Adams Document Expiration: 18 Aug. 1996 27 1435 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 1436 recognized, but that its associated credentials have expired, so 1437 that the requested operation cannot be performed. 1439 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1440 for the env_handle provided. 1442 o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 1443 is not recognized or supported in the underlying mechanism. 1445 o GSS_S_BAD_QOP indicates that the qop_algs value specified in P-IDU 1446 for at least one of the services is unavailable in the local 1447 mechanism, so processing cannot continue. 1449 o GSS_S_BAD_SIG indicates that the received P-IDU contains an 1450 incorrect integrity field (e.g., signature or MAC) for the data. 1452 o IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU 1453 data origin auth. / integ. has either expired or been revoked. 1455 o IDUP_S_BAD_KE_KEY indicates that the key used to establish a key 1456 for confidentiality purposes between originator and target has 1457 either expired or been revoked. 1459 o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU 1460 cannot be completed because the encrypted IDU was invalid/defec- 1461 tive (e.g., the final block was short or had incorrect padding). 1463 o GSS_S_FAILURE indicates that the environment is recognized, but 1464 that the requested operation could not be performed for reasons 1465 unspecified at the IDUP-GSS-API level. 1467 Using the security environment referenced by env_handle, initialize 1468 the data structures required to begin the process of unprotecting a 1469 P-IDU. The caller will be alerted as to which services were applied 1470 to the P-IDU in the returned Services_to_Receive set of parameters. 1472 If unprotection will be applied more than once to a given P-IDU, it 1473 is the responsibility of the calling application to remember if a 1474 service solicitation has been responded to previously (i.e., if the 1475 requested service has already been generated / sent for that P-IDU) 1476 and thus ignore subsequent solicitations on unprotect. 1478 The time flags indicate whether to consult trusted, untrusted, or no 1479 time (if both flags are FALSE) during the unprotection operation. If 1480 the current time is not to be checked, then unprotection may be 1481 successful even if the protector's key has expired since the P-IDU 1482 was generated (that is, if the Validity period -- as specified in 1483 the Quality parameter bundle -- has expired). 1485 If the underlying mechanism supports it and if this information is 1486 contained in the token, information regarding the originator (that 1487 is, the entity which used the protection set of calls to generate 1488 this token) is returned in the Prot_Information parameter bundle. 1490 Adams Document Expiration: 18 Aug. 1996 28 1492 2.3.7. IDUP_Unprotect call 1494 Inputs: 1496 o env_handle ENVIRONMENT HANDLE, 1498 o input_buffer OCTET STRING 1500 Outputs: 1502 o major_status INTEGER, 1504 o minor_status INTEGER, 1506 o output_buffer OCTET STRING 1508 Return major_status codes: 1510 o GSS_S_COMPLETE indicates that the input_buffer has successfully 1511 been included in the unprotection computation. 1513 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1514 for the env_handle provided. 1516 o GSS_S_FAILURE indicates that the environment is recognized, but 1517 that the requested operation could not be performed for reasons 1518 unspecified at the IDUP-GSS-API level. 1520 Using the security environment referenced by env_handle, continue the 1521 unprotection processing on the data in input_buffer, putting any 1522 resulting IDU data in output_buffer (if required). 1524 2.3.8. IDUP_End_Unprotect call 1526 Inputs: 1528 o env_handle ENVIRONMENT HANDLE, 1530 Outputs: 1532 o major_status INTEGER, 1534 o minor_status INTEGER, 1536 o Services_to_Receive SET OF Unprot_Service, 1538 o final_idu_buffer OCTET STRING, 1540 o Service_Verification_Info PARAMETER BUNDLE, 1541 -- used only if target is on "service_to" list in Unprot_Service 1543 o service_verification_info_id INTEGER, 1544 -- used only if target is on "service_to" list in Unprot_Service 1546 Adams Document Expiration: 18 Aug. 1996 29 1548 Return major_status codes: 1550 o GSS_S_COMPLETE indicates that the unprotect computation was 1551 successful. Any residual IDU data will be returned in 1552 final_idu_buffer. 1554 o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 1555 supplied is too small to hold the generated data. The application 1556 should continue calling this routine (until GSS_S_COMPLETE is 1557 returned) in order to get all remaining data. 1559 o GSS_S_BAD_SIG indicates that the received P-IDU contains an 1560 incorrect integrity field (e.g., signature or MAC) for the data. 1562 o IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU 1563 data origin auth. / integ. has either expired or been revoked. 1565 o IDUP_S_BAD_KE_KEY indicates that the key used to establish a key 1566 for confidentiality purposes between originator and target has 1567 either expired or been revoked. 1569 o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU 1570 cannot be completed because the encrypted IDU was invalid/defec- 1571 tive (e.g., the final block was short or had incorrect padding). 1573 o IDUP_S_NO_ENV indicates that no valid environment was recognized 1574 for the env_handle provided. 1576 o GSS_S_FAILURE indicates that the environment is recognized, but 1577 that the requested operation could not be performed for reasons 1578 unspecified at the IDUP-GSS-API level. 1580 Using the security environment referenced by env_handle, complete the 1581 unprotection processing on the data and return the appropriate status 1582 code. If there is any residual IDU data it will be returned in 1583 final_idu_buffer. 1585 Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the 1586 concept of error tokens transferred between sender and recipient 1587 since the protection and unprotection of an IDU may be separated by 1588 an indefinite amount of time and may or may not be performed by the 1589 same entity. 1591 Adams Document Expiration: 18 Aug. 1996 30 1593 2.4. Special-Purpose Calls 1595 2.4.1. Relationship to GSS-API 1597 The special-purpose call described in this section has no analogue 1598 in GSS-API [RFC-1508]. This call is used to complete the portfolio 1599 of evidence services in the IDUP environment. This call may not be 1600 supported by all underlying IDUP mechanisms or implementations. 1602 2.4.2. IDUP_Form_Complete_Evidence call 1604 Inputs: 1606 o env_handle ENVIRONMNENT HANDLE, 1608 o single_evidence_buffer OCTET STRING, 1610 o partial_evidence_buffer OCTET STRING, 1611 -- an arbitrary-sized piece of the full evidence token. Used if 1612 -- evidence will be input a buffer at a time (except that the 1613 -- final buffer must be passed in final_evidence_buffer rather 1614 -- than partial_evidence_buffer). Only one of 1615 -- single_evidence_buffer and partial(final)_evidence_buffer can 1616 -- have nonzero length. 1618 o final_evidence_buffer OCTET STRING, 1620 Outputs: 1622 o major_status INTEGER, 1624 o minor_status INTEGER, 1626 o evidence_token_out OCTET STRING 1628 Return major_status codes: 1630 o GSS_S_COMPLETE indicates that the completion of evidence 1631 generation was successful. 1633 o GSS_S_CONTINUE_NEEDED indicates that the buffer supplied for 1634 evidence_token_out is too small to hold the generated data. The 1635 application should continue calling this routine (until 1636 GSS_S_COMPLETE is returned) in order to get all remaining data. 1638 o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 1639 does not support the service requested. 1641 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 1642 on the input evidence token failed, preventing further processing 1643 from being performed with that token. 1645 o GSS_S_FAILURE indicates that the environment is recognized, but 1646 that the requested operation could not be performed for reasons 1647 unspecified at the IDUP-GSS-API level. 1649 Adams Document Expiration: 18 Aug. 1996 31 1651 Using the security environment referenced by env_handle, complete the 1652 generation of an evidence token for non-repudiation purposes and 1653 return the appropriate status value along with the completed token. 1654 Such a call may be used, for example, for the purpose of batch 1655 evidence generation on an "evidence server". A local machine may be 1656 able to use the protection set of calls to fill out most of an 1657 evidence token and then send a number of these to a batch processor 1658 which forms the complete evidence tokens (perhaps by adding a 1659 certification path, or a timestamp and signature from a timestamping 1660 authority). 1662 2.5. Support calls 1664 2.5.1. Relationship to GSS-API 1666 Support calls in IDUP-GSS-API are to be understood and used as 1667 described in GSS-API [RFC-1508]. The calls GSS_Display_status(), 1668 GSS_Indicate_mechs(), GSS_Compare_name(), GSS_Display_name(), 1669 GSS_Import_name(), GSS_Release_name(), GSS_Release_buffer(), and 1670 GSS_Release_oid_set() are unchanged. 1672 2.5.2. IDUP_Parse_token call 1674 Inputs: 1676 o input_token OCTET STRING 1678 Outputs: 1680 o major_status INTEGER, 1682 o minor_status INTEGER, 1684 o mech_type OBJECT IDENTIFIER, 1686 Return major_status codes: 1688 o GSS_S_COMPLETE indicates that the input_token could be parsed for 1689 all relevant fields. 1691 o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 1692 recognized, but that its associated credentials have expired, so 1693 that the requested operation cannot be performed. 1695 o GSS_S_DEFECTIVE_TOKEN indicates that the mechanism type could be 1696 parsed, but that either the other fields could not be determined 1697 from the input_token, or their values did not correspond to valid 1698 values for that mechanism. 1700 o GSS_S_FAILURE indicates that the mechanism type could not be 1701 parsed (for example, the token may be corrupted). 1703 Adams Document Expiration: 18 Aug. 1996 32 1705 IDUP_Parse_Token() is used to return to an application the attributes 1706 which correspond to a given input token. Since IDUP-GSS-API tokens 1707 are meant to be opaque to the calling application, this function 1708 allows the application to determine information about the token 1709 without having to violate the opaqueness intention of IDUP. Of 1710 primary importance is the mechanism type, which the application can 1711 then use as input to the IDUP_Establish_Env() call in order to 1712 establish the correct environment in which to have the token 1713 processed. Other token attributes may be added as outputs of this 1714 call in future versions of this specification, if required. 1716 If all tokens are framed as suggested in RFC-1508, Appendix B 1717 (mandated in the Kerberos V5 GSS mechanism [KRB5], in the SPKM GSS 1718 Mechanism [SPKM], and in this document), then any mechanism 1719 implementation should be able to return the mech_type parameter for 1720 any uncorrupted input token. If the mechanism implementation whose 1721 IDUP_Parse_token() function is being called does recognize the token, 1722 it can return other token attributes, if specified. 1724 3. Related Activities 1726 In order to implement the IDUP-GSS-API atop existing, emerging, and 1727 future security mechanisms, the following is necessary: 1729 - object identifiers must be assigned to candidate IDUP-GSS-API 1730 mechanisms and the name types which they support; and 1732 - concrete data element (i.e., token and parameter bundle) formats 1733 must be defined for candidate mechanisms. 1735 Calling applications must implement formatting conventions which will 1736 enable them to distinguish IDUP-GSS-API P-IDUs from other 1737 IDUs in their environment. 1739 Concrete language bindings are required for the programming 1740 environments in which the IDUP-GSS-API is to be employed; such a 1741 binding for the C language are available in the Internet Draft 1742 [IDUP-C]. 1744 4. Acknowledgments 1746 Many thanks are due to Warwick Ford, Paul Van Oorschot, and Tim Moses 1747 of Bell-Northern Research, and to Denis Pinkas of Bull, for a number 1748 of helpful comments. 1750 5. Security Considerations 1752 Security issues are discussed throughout this memo. 1754 Adams Document Expiration: 18 Aug. 1996 33 1756 6. REFERENCES 1758 [MSP]: U.S. National Security Agency, "Message Security 1759 Protocol", Secure Data Network System SDN.701, March 1994. 1761 [RFC-1421]: J. Linn, "Privacy Enhancement for Internet Electronic 1762 Mail: Part I: Message Encryption and Authentication Procedures", 1763 RFC 1421. 1765 [RFC-1508]: J. Linn, "Generic Security Service Application Program 1766 Interface", RFC 1508. 1768 [GSSv2]: J. Linn, "Generic Security Service Application Program 1769 Interface, Version 2", Internet Draft draft-ietf-cat-gssv2-0x.txt 1770 (work in progress). 1772 [KRB5]: J. Linn, "The Kerberos Version 5 GSS-API Mechanism", 1773 Internet Draft draft-ietf-cat-kerb5gss-0x.txt (work in progress). 1775 [SPKM]: C. Adams, "The Simple Public-Key GSS-API Mechanism 1776 (SPKM)", Internet Draft draft-ietf-cat-spkmgss-0x.txt (work in 1777 progress). 1779 [IDUP-C]: D. Grebovich, "Independent Data Unit Protection Generic 1780 Security Service Application Program Interface: C-bindings", Internet 1781 Draft draft-ietf-cat-idup-cbind-0x.txt (work in progress). 1783 [ISO/IEC]: 2nd ISO/IEC CD 13888-1, "Information technology - 1784 Security techniques - Non-repudiation - Part 1: General Model", 1785 ISO/IEC JTC 1/SC 27, May 30, 1995 1787 7. Author's Address 1789 Carlisle Adams 1790 Bell-Northern Research 1791 P.O.Box 3511, Station C 1792 Ottawa, Ontario, CANADA K1Y 4H7 1794 Phone: +1 613.763.9008 1795 E-mail: cadams@bnr.ca 1797 Adams Document Expiration: 18 Aug. 1996 34 1799 APPENDIX A 1801 MECHANISM-INDEPENDENT TOKEN FORMAT 1803 This appendix specifies a mechanism-independent level of 1804 encapsulating representation for IDUP-GSS-API tokens, incorporating 1805 an identifier of the mechanism type to be used when processing those 1806 tokens. Use of this format (with ASN.1-encoded data elements 1807 represented in BER, constrained in the interests of parsing 1808 simplicity to the Distinguished Encoding Rule (DER) BER subset 1809 defined in X.509, clause 8.7) is recommended to the designers of 1810 IDUP-GSS-API implementations based on various mechanisms, so that 1811 tokens can be interpreted unambiguously at IDUP-GSS-API peers. There 1812 is no requirement that the mechanism-specific token data element be 1813 encoded in ASN.1 BER. 1815 -- top-level token definition to frame different mechanisms 1817 IDUP-GSS-API DEFINITIONS ::= 1818 BEGIN 1819 MechType ::= OBJECT IDENTIFIER 1821 Token ::= [APPLICATION 0] IMPLICIT SEQUENCE { 1822 thisMech MechType, 1823 token ANY DEFINED BY thisMech 1824 -- contents mechanism-specific 1825 } 1826 END 1828 APPENDIX B 1830 MECHANISM DESIGN CONSTRAINTS 1832 The following constrain on IDUP-GSS-API mechanism designs is 1833 adopted in response to observed caller protocol requirements, and 1834 adherence thereto is anticipated in subsequent descriptions of 1835 IDUP-GSS-API mechanisms to be documented in standards-track Internet 1836 specifications. 1838 Use of the approach defined in Appendix A of this specification, 1839 applying a mechanism type tag to the Token is required. 1841 Adams Document Expiration: 18 Aug. 1996 35 1843 APPENDIX C 1845 EXAMPLES OF IDUP USE 1847 This appendix provides examples of the use of IDUP to do IDU protec- 1848 tion and unprotection. It should not be regarded as constrictive to 1849 implementations or as defining the only means through which 1850 IDUP-GSS-API functions can be realized with particular underlying 1851 technology, and does not demonstrate all IDUP-GSS-API features. 1853 C.1. Simple Mechanism, Single Buffer 1855 To illustrate the simplest possible case, consider an underlying IDUP 1856 mechanism which does straightforward encryption/decryption and 1857 signing/verification only; none of the other possible services, such 1858 as creation of proof-of-origin evidence, requests for proof-of- 1859 delivery evidence, or use of trusted time, are supported. PEM 1860 [RFC-1421] is one example of a mechanism which fits this description. 1861 Furthermore (again for simplicity), assume that encapsulation is 1862 chosen by the calling application during IDU protection. 1864 The following parameter bundle uses and defaults would therefore be 1865 specified in the relevant IDUP mechanism document. 1867 Mech_Specific_Info 1868 - NOT USED (the only acceptable input, therefore, is NULL) 1870 Idu_Sensitivity 1871 - NOT USED (the only acceptable input, therefore, is NULL) 1873 Service_Creation_Info 1874 - NOT USED (the only acceptable input, therefore, is NULL) 1876 Service_Verification_Info 1877 - NOT USED (the only acceptable input, therefore, is NULL) 1879 Quality 1880 - the qop_algs parameter must be supported, with a suitable 1881 DEFAULT value specified; 1882 - suitable DEFAULT values for validity, policy_id, and 1883 allow_policy_mapping must be specified (it may be an 1884 implementation option as to whether these parameters are 1885 explicitly modifiable by the calling application, or whether 1886 NULLs are the only acceptable input) 1888 Idu_Information 1889 - the idu_type parameter must have a value representing a suitable 1890 IDU type (for example, in PEM a value representing the string 1891 "RFC822" or some other valid "Content-Domain" would be used), 1892 with a suitable DEFAULT value specified; 1893 - the idu_title parameter is NOT USED (the only acceptable input, 1894 therefore, is NULL) 1896 Adams Document Expiration: 18 Aug. 1996 36 1898 Prot_Information 1899 - the originator_name and idu_type (in Idu_Information) parameters 1900 are read from the encapsulating information and output by 1901 IDUP_Start_Unprotect; 1902 - all other parameters are NOT USED (and therefore NULL) 1904 Special_Conditions 1905 - NOT USED (the only acceptable input, therefore, is NULL) 1907 Target_Info 1908 - this bundle is used as described in IDUP; no DEFAULT values are 1909 specified 1911 General_Service_Data 1912 - the unencapsulated_token parameter is used if 1913 encapsulation_request is FALSE; 1914 - the minor_status parameter is used to return minor status values 1915 as specified by the mechanism document 1917 Prot_Service 1918 - the prot_service_type parameter may have a value of "1" 1919 ("perform unsolicited service") or NULL (which specifies the 1920 DEFAULT value of "1"); 1921 - the service_id parameter must have a value representing 1922 "PER_CONF" or "PER_DOA"; 1923 - the parameters Service_Creation_Info, service_to, 1924 Service_Verification_Info, and service_verification_info_id are 1925 NOT USED (and therefore NULL) 1927 Unprot_Service 1928 - the unprot_service_type parameter will always have a value of 1929 "1" ("receive unsolicited service"); 1930 - the service_id parameter will have a value representing 1931 "REC_CONF" or "REC_DOA"; 1932 - the parameters service_verification_info_id, 1933 Service_Verification_Info, service_to, and 1934 Service_Creation_Info, are NOT USED (and therefore NULL) 1936 Assuming that the calling application has only a single buffer of 1937 data to protect/unprotect, the following sequence of operations must 1938 be performed by the sender and receivers (subsequent to environment 1939 establishment). 1941 SENDER (any parameters not listed below are given the value NULL): 1943 Set 1944 env_handle = environment handle in use; 1945 encapsulation_request = TRUE; 1946 single_idu_buffer = data buffer; 1947 Target_Info.targ_names = receiver names; 1948 P_Services.Prot_Service_1.service_id = PER_CONF; 1949 P_Services.Prot_Service_2.service_id = PER_DOA; 1951 Adams Document Expiration: 18 Aug. 1996 37 1953 Call 1954 IDUP_Start_Protect() with above input parameters 1955 Check 1956 major_status. If not GSS_S_COMPLETE, check 1957 minor_status, 1958 Target_Info.bad_targ_names / Target_Info.bad_targ_status, 1959 P_Services.Prot_Service_1.General_Service_Data.minor_status, 1960 P_Services.Prot_Service_2.General_Service_Data.minor_status 1961 (as required) for more detailed information. 1963 Send 1964 Output parameter pidu_buffer to receiver. 1966 RECEIVER (any parameters not listed below are given the value NULL): 1968 Set 1969 env_handle = environment handle in use; 1970 single_pidu_buffer = received data buffer; 1972 Call 1973 IDUP_Start_Unprotect() with above input parameters 1974 Check 1975 major_status. If not GSS_S_COMPLETE, check 1976 minor_status, 1977 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 1978 R_Services.Unprot_Service_2.General_Service_Data.minor_status 1979 (as required) for more detailed information 1981 Utilize 1982 R_Services.Unprot_Service_1/2.service_id, 1983 (to determine which services were applied by the originator) 1984 R_Services.Unprot_Service_1/2.Quality, 1985 (to determine the corresponding qualities of the services) 1986 Prot_Information.originator_name, 1987 (to determine the name of the originator) 1988 single_idu_buffer 1989 (to retrieve the unprotected data). 1991 Adams Document Expiration: 18 Aug. 1996 38 1993 C.2. Simple Mechanism, Multiple Buffers 1995 To illustrate the next step up in complexity, consider the use of the 1996 simple IDUP mechanism described above with multiple data buffers. In 1997 particular, consider the case in which a large data file is to be 1998 signed. For this example, assume that the calling application does 1999 not wish to use encapsulation. 2001 Note that the parameter bundle uses and defaults are as specified in 2002 C.1. above. 2004 SENDER (any parameters not listed below are given the value NULL): 2006 Set 2007 env_handle = environment handle in use; 2008 encapsulation_request = FALSE; 2009 P_Services.Prot_Service.service_id = PER_DOA; 2011 Call 2012 IDUP_Start_Protect() with above input parameters 2013 Check 2014 major_status. If not GSS_S_COMPLETE, check 2015 minor_status, 2016 P_Services.Prot_Service.General_Service_Data.minor_status 2017 (as required) for more detailed information. 2019 For each buffer of input data: 2020 Set 2021 input_buffer = buffer 2022 Call 2023 IDUP_Protect() with above input parameter 2024 Check 2025 major_status. If not GSS_S_COMPLETE, check 2026 minor_status 2028 Call 2029 IDUP_End_Protect() 2030 Check 2031 major_status. If not GSS_S_COMPLETE, check 2032 minor_status, 2033 P_Services.Prot_Service.General_Service_Data.minor_status 2034 (as required) for more detailed information. 2036 Send 2037 P_Services.Prot_Service.General_Service_Data.unencapsulated_token, 2038 the file for which the signature was calculated (if required) 2039 to receiver. 2041 Adams Document Expiration: 18 Aug. 1996 39 2043 RECEIVER (any parameters not listed below are given the value NULL): 2045 Set 2046 env_handle = environment handle in use; 2047 partial_pidu_buffer = received unencapsulated token; 2049 Call 2050 IDUP_Start_Unprotect() with above input parameters 2051 Check 2052 major_status. If not GSS_S_COMPLETE, check 2053 minor_status, 2054 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2055 (as required) for more detailed information 2057 For each buffer of input data: 2058 Set 2059 input_buffer = buffer 2060 Call 2061 IDUP_Unprotect() with above input parameter 2062 Check 2063 major_status. If not GSS_S_COMPLETE, check 2064 minor_status 2066 Call 2067 IDUP_End_Unprotect() 2068 Check 2069 major_status. If not GSS_S_COMPLETE, check 2070 minor_status, 2071 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2072 (as required) for more detailed information. 2074 Utilize 2075 R_Services.Unprot_Service_1.service_id, 2076 (to determine which service was applied by the originator; note 2077 that Unprot_Service_2 will have NULL in unprot_service_type 2078 to indicate that it is not used) 2079 R_Services.Unprot_Service_1.Quality, 2080 (to determine the corresponding quality of the service) 2081 Prot_Information.originator_name, (from IDUP_Start_Unprotect) 2082 (to determine the name of the signer) 2083 major_status (from IDUP_End_Unprotect) 2084 (to determine pass/fail status of signature verification). 2086 Adams Document Expiration: 18 Aug. 1996 40 2088 C.3. More Sophisticated Mechanism, Small Application Buffers 2090 To illustrate a higher level of complexity, consider the use of a 2091 more sophisticated IDUP mechanism and a calling application with 2092 small data buffers. In particular, consider the case in which a very 2093 small e-mail message is to be encrypted for a relatively large 2094 receiver list (R), some subset of whom (r) will be asked to send 2095 proofs of receipt of the message to some other subset (L) (which 2096 includes the originiator). So that the example is not unnecessarily 2097 complicated, assume again that the originating application uses 2098 encapsulation. 2100 The uses and defaults for the various parameter bundles for this 2101 mechanism would be specified in the relevant IDUP mechanism document 2102 as follows. 2104 Mech_Specific_Info 2105 - NOT USED (the only acceptable input, therefore, is NULL) 2107 Idu_Sensitivity 2108 - NOT USED (the only acceptable input, therefore, is NULL) 2110 Service_Creation_Info 2111 - used to create "proof of delivery" evidence (but actual 2112 structure is opaque to calling application) 2114 Service_Verification_Info 2115 - used to verify "proof of delivery" evidence (but actual 2116 structure is opaque to calling application) 2118 Quality 2119 - the qop_algs parameter must be supported, with a suitable 2120 DEFAULT value specified; 2121 - suitable DEFAULT values for validity, policy_id, and 2122 allow_policy_mapping must be specified (it may be an 2123 implementation option as to whether these parameters are 2124 explicitly modifiable by the calling application, or whether 2125 NULLs are the only acceptable input) 2127 Idu_Information 2128 - the idu_type parameter must have a value representing a suitable 2129 IDU type, with a sutiable DEFAULT value specified; 2130 - the idu_title parameter must have a value representing a 2131 suitable IDU title, with a sutiable DEFAULT value specified 2133 Prot_Information 2134 - the originator_name, protection_time, and idu_type / idu_title 2135 (in Idu_Information) parameters are read from the contained 2136 header information and output by IDUP_Start_Unprotect; 2138 Special_Conditions 2139 - the parameter prot_oper_id is NOT USED (the only acceptable 2140 input, therefore, is NULL); 2141 - trusted or untrusted time may be selected by the calling 2142 application, with a sutiable DEFAULT value specified 2144 Adams Document Expiration: 18 Aug. 1996 41 2146 Target_Info 2147 - this bundle is used as described in IDUP; no DEFAULT values are 2148 specified 2150 General_Service_Data 2151 - the unencapsulated_token parameter is used if 2152 encapsulation_request is FALSE; 2153 - the minor_status parameter is used to return minor status values 2154 as specified by the mechanism document 2156 Prot_Service 2157 - the prot_service_type parameter may have a value of "1" 2158 ("perform unsolicited service"), "2" ("perform solicited 2159 service"), "3" (perform service solicitation), or NULL (which 2160 specifies the DEFAULT value of "1"); 2161 - the service_id parameter must have a value representing 2162 "PER_CONF", "PER_DOA", "PER_POO", or "PER_POD"; 2163 - the parameters Service_Creation_Info, service_to, 2164 Service_Verification_Info, and service_verification_info_id are 2165 used when required by the IDUP operation 2167 Unprot_Service 2168 - the unprot_service_type parameter may have a value of "1" 2169 ("receive unsolicited service"), "2" ("receive solicited 2170 service"), or "3" (receive service solicitation); 2171 - the service_id parameter will have a value representing 2172 "REC_CONF", "REC_DOA", "REC_POO", or "REC_POD"; 2173 - the parameters service_verification_info_id, 2174 Service_Verification_Info, service_to, and 2175 Service_Creation_Info, are used when required by the IDUP 2176 operation 2178 SENDER (any parameters not listed below are given the value NULL): 2180 Set 2181 env_handle = environment handle in use; 2182 Idu_Information.idu_type = value for "e-mail document"; 2183 Idu_Information.idu_title = "Contract 1234"; 2184 Special_Conditions.use_trusted_time = TRUE; 2185 encapsulation_request = TRUE; 2186 single_idu_buffer = very small e-mail message; 2187 Target_Info.targ_names = receiver names (R); 2188 Prot_Service_1.prot_service_type = "1"; 2189 Prot_Service_1.service_id = PER_CONF; 2190 Prot_Service_2.prot_service_type = "3"; 2191 Prot_Service_2.service_id = PER_POD; 2192 Prot_Service_2.General_Service_Data.Target_Info.targ_names 2193 = "receipts from" list (r); 2194 Prot_Service_2.service_to = "receipts to" list (L); 2195 P_Services.Prot_Service_1 = Prot_Service_1; 2196 P_Services.Prot_Service_2 = Prot_Service_2; 2198 Adams Document Expiration: 18 Aug. 1996 42 2200 Call 2201 IDUP_Start_Protect() with above input parameters 2202 Check 2203 major_status. If not GSS_S_COMPLETE, 2204 while major_status == GSS_S_CONTINUE_NEEDED 2205 Save 2206 pidu_buffer, 2207 Call 2208 IDUP_Start_Protect() (to get next portion of pidu_buffer) 2209 Check 2210 major_status, 2211 minor_status, 2212 Target_Info.bad_targ_names / Target_Info.bad_targ_status, 2213 P_Services.Prot_Service_1.General_Service_Data.minor_status, 2214 P_Services.Prot_Service_2.General_Service_Data.minor_status 2215 (as required) for more detailed information. 2217 Save 2218 Prot_Service_2.Service_Verification_Info, 2219 Prot_Service_2.service_verification_info_id 2221 Send 2222 All saved buffers of pidu_buffer to receiver list (R). 2224 RECEIVER (ON RECEIVER LIST (R)): 2225 (any parameters not listed below are given the value NULL) 2227 Set 2228 env_handle = environment handle in use; 2229 partial_pidu_buffer = initial buffer of received p-idu; 2231 Call 2232 IDUP_Start_Unprotect() with above input parameters 2233 While major_status == IDUP_S_MORE_PIDU_NEEDED, 2234 Set 2235 partial_pidu_buffer = next buffer of p-idu 2236 Call 2237 IDUP_Start_Unprotect() 2238 Check 2239 major_status, 2240 minor_status, 2241 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2242 R_Services.Unprot_Service_2.General_Service_Data.minor_status, 2243 (as required) for more detailed information 2245 Save 2246 initial_idu_buffer (if non-empty) 2248 Adams Document Expiration: 18 Aug. 1996 43 2250 Set 2251 input_buffer = remaining p-idu buffer 2252 Call 2253 IDUP_Unprotect() with above input parameter 2254 Check 2255 major_status. If not GSS_S_COMPLETE, check 2256 minor_status 2257 Save 2258 output_buffer 2260 Call 2261 IDUP_End_Unprotect() 2262 Check 2263 major_status. If not GSS_S_COMPLETE, check 2264 minor_status, 2265 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2266 R_Services.Unprot_Service_2.General_Service_Data.minor_status, 2267 (as required) for more detailed information. 2269 Utilize 2270 R_Services.Unprot_Service_1/2.service_id, 2271 (to determine which services were applied by the originator) 2272 R_Services.Unprot_Service_1/2.Quality, 2273 (to determine the corresponding qualities of the service) 2274 Prot_Information.originator_name/protection_time and 2275 Prot_Information.Idu_Information.idu_type/idu_title, 2276 (from IDUP_Start_Unprotect) (to determine originator info.) 2277 R_Services.Unprot_Service_2.General_Service_Data.Target_Info. 2278 targ.names, (to determine if rec. is in "receipts from" (r)) 2279 Service_Verification_Info/service_verification_info_id 2280 (to determine if receiver is in "receipts to" list (L)) 2282 If receiver is in "receipts from" list (r) 2283 Save 2284 R_Services.Unprot_Service_2.service_to, 2285 R_Services.Unprot_Service_2.Service_Creation_Info 2287 If receiver is in "receipts to" list (L) 2288 Save 2289 Service_Verification_Info, 2290 service_verification_info_id 2292 Adams Document Expiration: 18 Aug. 1996 44 2294 RECEIVER (ON "RECEIPTS FROM" LIST (r)): 2295 (procedure to generate receipt) 2297 Set 2298 env_handle = environment handle in use; 2299 Target_Info.targ_names = service_to 2300 Prot_Service_1.prot_service_type = "2"; 2301 Prot_Service_1.service_id = "PER_POD"; 2302 Prot_Service_1.Service_Creation_Info = Service_Creation_Info; 2303 P_Services.Prot_Service_1 = Prot_Service_1 2305 Call 2306 IDUP_Start_Protect() with above input parameters 2307 Check 2308 major_status. If not GSS_S_COMPLETE, check 2309 minor_status, 2310 P_Services.Prot_Service_1.General_Service_Data.minor_status 2311 (as required) for more detailed information. 2313 Send 2314 pidu_buffer to "receipts to" list (L) 2316 RECEIVER (ON "RECEIPTS TO" LIST (L)): 2317 (procedure to process received receipt) 2319 Set 2320 env_handle = environment handle in use; 2321 single_pidu_buffer = received p-idu buffer (if it fits in a single 2322 buffer; otherwise use partial_pidu_buffer and make multiple 2323 calls, as above) 2325 Call 2326 IDUP_Start_Unprotect() with above input parameters 2327 If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED 2328 Utilize 2329 R_Services.Unprot_Service_1.service_verification_info.id 2330 (to assist in locating necessary Service_Verification_Info) 2331 Set 2332 R_Services.Unprot_Service_1.Service_Verification_Info 2333 = Service_Verification_Info 2334 Call 2335 IDUP_Start_Unprotect() with above input parameters 2336 Check 2337 major_status, 2338 minor_status, 2339 R_Services.Unprot_Service_1.General_Service_Data.minor_status 2340 (as required) for more detailed information. 2342 Utilize 2343 R_Services.Unprot_Service_1.service_id, 2344 (to determine that this is a "proof of delivery" evidence) 2345 R_Services.Unprot_Service_1.Quality, 2346 Prot_Information.originator_name, (for evidence generator info.) 2347 major_status (to determine pass/fail status of evi. verif.). 2349 Adams Document Expiration: 18 Aug. 1996 45