idnits 2.17.1 draft-ietf-cat-idup-gss-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-27) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 3599 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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. ** There are 3 instances of too long lines in the document, the longest one being 1 character in excess of 72. ** The abstract seems to contain references ([RFC-2078]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 751: '... confPolicy [0] PolicyAndTime OPTIONAL,...' RFC 2119 keyword, line 753: '... integPolicy [1] PolicyAndTime OPTIONAL,...' RFC 2119 keyword, line 755: '... evidencePolicy [2] PolicyAndTime OPTIONAL...' RFC 2119 keyword, line 768: '... endTime INTEGER OPTIONAL...' RFC 2119 keyword, line 1038: '... } OPTIONAL,...' (13 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 2552 has weird spacing: '... to a reque...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 751 -- Looks like a reference, but probably isn't: '1' on line 753 -- Looks like a reference, but probably isn't: '2' on line 755 == Missing Reference: 'APPLICATION 0' is mentioned on line 2755, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'MSP' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Obsolete normative reference: RFC 2078 (Obsoleted by RFC 2743) Summary: 12 errors (**), 0 flaws (~~), 4 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Draft C. Adams, Entrust Technologies 2 draft-ietf-cat-idup-gss-09.txt November, 1997 4 Independent Data Unit Protection Generic Security Service 5 Application Program Interface (IDUP-GSS-API) 7 STATUS OF THIS MEMO 9 This document is an Internet-Draft. Internet-Drafts are working 10 documents of the Internet Engineering Task Force (IETF), its areas, 11 and its working groups. Note that other groups may also distribute 12 working documents as Internet-Drafts. 14 Internet-Drafts are draft documents valid for a maximum of six 15 months and may be updated, replaced, or obsoleted by 16 other documents at any time. It is inappropriate to use Internet- 17 Drafts as reference material or to cite them other than as 18 "work in progress." 20 To learn the current status of any Internet Draft, please check the 21 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 22 Directories on ds.internic.net (US East Coast), ftp.nordu.net 23 (Europe), ftp.isi.edu (US West Coast) or munnari.oz.au (Pacific Rim). 25 Comments on this document should be sent to "cat-ietf@mit.edu", the 26 IETF Common Authentication Technology WG discussion list. 28 ABSTRACT 30 The IDUP-GSS-API extends the GSS-API [RFC-2078] for applications 31 requiring protection of a generic data unit (such as a file or 32 message) in a way which is independent of the protection of any other 33 data unit and independent of any concurrent contact with designated 34 ''receivers'' of the data unit. Thus, it is suitable for applications 35 such as secure electronic mail where data needs to be protected 36 without any on-line connection with the intended recipient(s) of that 37 data. The protection offered by IDUP includes services such as data 38 origin authentication with data integrity, data confidentiality with 39 data integrity, and support for non-repudiation services. Subsequent 40 to being protected, the data unit can be transferred to the 41 recipient(s) - or to an archive - perhaps to be processed 42 (''unprotected'') only days or years later. 44 Throughout the remainder of this document, the ''unit'' of data 45 described in the above paragraph will be referred to as an IDU 46 (Independent Data Unit). The IDU can be of any size (the application 47 may, if it wishes, split the IDU into pieces and have the protection 48 computed a piece at a time, but the resulting protection token 49 applies to the entire IDU). However, the primary characteristic of 50 an IDU is that it represents a stand-alone unit of data whose 51 protection is entirely independent of any other unit of data. If an 52 application protects several IDUs and sends them all to a single 54 Adams Document Expiration: May 1998 1 56 receiver, the IDUs may be unprotected by that receiver in any order 57 over any time span; no logical connection of any kind is implied by 58 the protection process itself. 60 As with RFC-2078, this IDUP-GSS-API definition provides security 61 services to callers in a generic fashion, supportable with a range of 62 underlying mechanisms and technologies and hence allowing source- 63 level portability of applications to different environments. This 64 specification defines IDUP-GSS-API services and primitives at a level 65 independent of underlying mechanism and programming language environ- 66 ment, and is to be complemented by other, related specifications: 68 - documents defining specific parameter bindings for particular 69 language environments; 70 - documents defining token formats, protocols, and procedures to 71 be implemented in order to realize IDUP-GSS-API services atop 72 particular security mechanisms. 74 TABLE OF CONTENTS 75 1. IDUP-GSS-API Characteristics and Concepts .................. 3 76 1.1. IDUP-GSS-API Constructs .................................. 5 77 1.1.1. Credentials ............................................ 5 78 1.1.2. Tokens ................................................. 5 79 1.1.3. Security Environment ................................... 5 80 1.1.4. Mechanism Types ........................................ 6 81 1.1.5. Naming ................................................. 6 82 1.1.6. Channel Bindings ....................................... 6 83 1.2. IDUP-GSS-API Features and Issues ......................... 6 84 1.2.1. Status Reporting ....................................... 6 85 1.2.2. Per-IDU Security Service Availability .................. 8 86 1.2.3. Per-IDU Replay Detection and Sequencing ................ 8 87 1.2.4. Quality of Protection .................................. 9 88 1.2.5. The Provision of Time .................................. 11 89 2. Interface Descriptions ..................................... 11 90 2.1. Credential management calls .............................. 13 91 2.1.1. Relationship to GSS-API ................................ 13 92 2.2. Environment-level calls .................................. 13 93 2.2.1. Relationship to GSS-API ................................ 13 94 2.2.2. IDUP_Establish_Env call ................................ 13 95 2.2.3. IDUP_Abolish_Env call .................................. 16 96 2.2.4. IDUP_Inquire_Env call .................................. 17 97 2.3. Per-IDU protection/unprotection calls .................... 17 98 2.3.1. Relationship to GSS-API ................................ 18 99 2.3.2. The "SE" Calls ......................................... 18 100 2.3.3. The "EV" Calls ......................................... 23 101 2.3.4. The "GP" Calls ......................................... 32 102 2.4. Special-Purpose calls .................................... 42 103 2.4.1. Relationship to GSS-API ................................ 42 104 2.4.2. IDUP_Form_Complete_PIDU ................................ 42 105 2.5. Support calls ............................................ 44 106 2.5.1. Relationship to GSS-API ................................ 44 107 2.5.2. IDUP_Acquire_Cred_With_Auth ............................ 44 108 2.5.3. IDUP_Get_Token_Details ................................. 45 109 2.5.4. IDUP_Get_Policy_Info ................................... 47 111 Adams Document Expiration: May 1998 2 113 3. Related Activities ......................................... 48 114 4. Acknowledgments ............................................ 49 115 5. Security Considerations .................................... 49 116 6. References ........................................... 49 117 7. Author's Address ........................................... 49 118 Appendix A Mechanism-Independent Token Format ................. 50 119 Appendix B Examples of IDUP Use ............................... 51 121 1. IDUP-GSS-API Characteristics and Concepts 123 The paradigm within which IDUP-GSS-API operates is as follows. An 124 IDUP-GSS-API caller is any application that works with IDUs, calling 125 on IDUP-GSS-API in order to protect its IDUs with services such as 126 data origin authentication with integrity (DOA), confidentiality with 127 integrity (CONF), and/or support for non-repudiation (e.g., evidence 128 generation, where "evidence" is information that either by itself, or 129 when used in conjunction with other information, is used to establish 130 proof about an event or action (note: the evidence itself does not 131 necessarily prove truth or existence of something, but contributes to 132 establish proof) -- see [ISO/IEC] for fuller discussion regarding 133 evidence and its role in various types of non-repudiation). An 134 IDUP-GSS-API caller passes an IDU to, and accepts a token from, its 135 local IDUP-GSS-API implementation, transferring the resulting 136 protected IDU (P-IDU) to a peer or to any storage medium. When a 137 P-IDU is to be "unprotected", it is passed to an IDUP-GSS-API 138 implementation for processing. The security services available 139 through IDUP-GSS-API in this fashion are implementable over a range 140 of underlying mechanisms based on secret-key and/or public-key 141 cryptographic technologies. 143 During the protection operation, the input IDU buffers may be 144 modified (for example, the data may be encrypted or encoded in some 145 way) or may remain unchanged. In any case, the result is termed a 146 "M-IDU" (Modified IDU) in order to distinguish it from the original 147 IDU. Depending on the desire of the calling application and the 148 capabilities of the underlying IDUP mechanism, the output produced by 149 the protection processing may or may not encapsulate the M-IDU. 150 Thus, the P-IDU may be the contents of a single output parameter (if 151 encapsulation is done) or may be the logical concatenation of an 152 unencapsulated token parameter and a M-IDU parameter (if 153 encapsulation is not done). In the latter case, the protecting 154 application may choose whatever method it wishes to concatenate or 155 combine the unencapsulated token and the M-IDU into a P-IDU, provided 156 the unprotecting application knows how to de-couple the P-IDU back 157 into its component parts prior to calling the IDUP unprotection set 158 of functions. 160 It is expected that any output buffer returned by IDUP (i.e., P-IDU 161 or portion thereof) is ready for immediate transmission to the 162 intended receiver(s) by the calling application, if this is desired. 163 In other words, an application wishing to transmit data buffers as 164 they appear from IDUP should not be unduly restricted from doing 165 so by the underlying mechanism. 167 Adams Document Expiration: May 1998 3 169 The IDUP-GSS-API separates the operation of initializing a security 170 environment (the IDUP_Establish_Env() call) from the operations of 171 providing per-IDU protection, for IDUs subsequently protected in 172 conjunction with that environment. Per-IDU protection and 173 unprotection calls provide DOA, CONF, evidence, and other services, 174 as requested by the calling application and as supported by the 175 underlying mechanism. 177 The following paragraphs provide an example illustrating the 178 dataflows involved in the use of the IDUP-GSS-API by the sender and 179 receiver of a P-IDU in a mechanism-independent fashion. The example 180 assumes that credential acquisition has already been completed by 181 both sides. Furthermore, the example does not cover all possible 182 options available in the protection/unprotection calls. 184 The sender first calls IDUP_Establish_Env() to establish a 185 security environment. Then, for the IDU to be protected the 186 sender calls the appropriate protection calls (SE, EV, or GP) to 187 perform the IDU protection. The resulting P-IDU, which may 188 (depending on whether or not encapsulation was chosen/available) 189 be either the token itself or the logical concatenation of the 190 token and the M-IDU, is now ready to be sent to the target. The 191 sender then calls IDUP_Abolish_Env() to flush all 192 environment-specific information. 194 The receiver first calls IDUP_Establish_Env() to establish a 195 security environment in order to unprotect the P-IDU. Then, for 196 the received P-IDU the receiver calls the appropriate unprotection 197 calls (SE, EV, or GP (known a priori, or possibly determined 198 through the use of the IDUP_Get_token_details call)) to perform 199 the P-IDU unprotection. The receiver then calls 200 IDUP_Abolish_Env() to flush all environment-specific information. 202 It is important to note that absolutely no synchronization is implied 203 or expected between the data buffer size used by the sender as input 204 to the protection calls, the data buffer size used by the receiver as 205 input to the unprotection calls, and the block sizes required by the 206 underlying protection algorithms (integrity and confidentiality). 207 All these sizes are meant to be independent; furthermore, the data 208 buffer sizes used for the protection and unprotection calls are 209 purely a function of the local environment where the calls are made. 211 The IDUP-GSS-API design assumes and addresses several basic goals, 212 including the following. 214 Mechanism independence: The IDUP-GSS-API defines an interface to 215 cryptographically implemented security services at a generic level 216 which is independent of particular underlying mechanisms. For 217 example, IDUP-GSS-API-provided services can be implemented by 218 secret-key technologies or public-key approaches. 220 Adams Document Expiration: May 1998 4 222 Protocol environment independence: The IDUP-GSS-API is independent 223 of the communications protocol suites which may be used to 224 transfer P-IDUs, permitting use in a broad range of protocol 225 environments. 227 Protocol association independence: The IDUP-GSS-API's security 228 environment construct has nothing whatever to do with 229 communications protocol association constructs, so that 230 IDUP-GSS-API services can be invoked by applications, wholly 231 independent of protocol associations. 233 Suitability for a range of implementation placements: IDUP-GSS-API 234 clients are not constrained to reside within any Trusted Computing 235 Base (TCB) perimeter defined on a system where the IDUP-GSS-API is 236 implemented; security services are specified in a manner suitable 237 for both intra-TCB and extra-TCB callers. 239 1.1. IDUP-GSS-API Constructs 241 This section describes the basic elements comprising the 242 IDUP-GSS-API. 244 1.1.1. Credentials 246 Credentials in IDUP-GSS-API are to be understood and used as 247 described in GSS-API [RFC-2078]. 249 1.1.2. Tokens 251 Tokens in IDUP-GSS-API are to be understood and used as described in 252 GSS-API [RFC-2078] with the exception that there are no context-level 253 tokens generated by IDUP-GSS-API. The IDUP-GSS-API token 254 may (depending on the underlying mechanism) encapsulate the M-IDU or 255 may be logically concatenated with the M-IDU prior to transfer to a 256 target; furthermore, for some evidence services the token may be sent 257 independently of any other data transfer. 259 1.1.3. Security Environment 261 The "security environment" in IDUP-GSS-API is entirely different from 262 the concept of security contexts used in GSS-API [RFC-2078]. Here, a 263 security environment exists within a calling application (that is, it 264 is purely local to the caller) for the purpose of protecting or 265 unprotecting one or more IDUs using a particular caller credential or 266 set of credentials. In GSS-API, on the other hand, a security 267 context exists between peers (the initiator and the target) for the 268 purpose of protecting, in real time, the data that is exchanged 269 between them. Although they are different concepts, the env_handle 270 in IDUP-GSS-API is similar to the context_handle in GSS-API in that 271 it is a convenient way of tying together the entire process of 272 protecting or unprotecting one or more IDUs using a particular 273 underlying mechanism. As with the GSS-API security contexts, a 274 caller can initiate and maintain multiple environments using the same 275 or different credentials. 277 Adams Document Expiration: May 1998 5 279 1.1.4. Mechanism Types 281 Mechanism types in IDUP-GSS-API are to be understood and used as 282 described in GSS-API [RFC-2078]. 284 1.1.5. Naming 286 Naming in IDUP-GSS-API is to be understood and used as described in 287 GSS-API [RFC-2078]. 289 1.1.6. Channel Bindings 291 The concept of channel bindings discussed in GSS-API [RFC-2078] is 292 not relevant to the IDUP-GSS-API. 294 1.2. IDUP-GSS-API Features and Issues 296 This section describes aspects of IDUP-GSS-API operations and of the 297 security services which the IDUP-GSS-API provides. It also provides 298 commentary on design issues. 300 1.2.1. Status Reporting 302 Status reporting in IDUP-GSS-API is to be understood and used as 303 described in GSS-API [RFC-2078], with the addition of a number of 304 IDUP-specific status codes. Descriptions of the major_status codes 305 used in IDUP are provided in Table 1. Codes that are informatory 306 (i.e., that do not cause the requested operation to fail) are 307 indicated with the symbol "(I)". 309 As with GSS-API, minor_status codes, which provide more detailed 310 status information than major_status codes, and which may include 311 status codes specific to the underlying security mechanism, are not 312 specified in this document. 314 Table 1: IDUP-GSS-API Major Status Codes 316 GSS_S_BAD_MECH indicates that a mech_type unsupported by the 317 IDUP_GSS-API implementation was requested, causing the 318 environment establishment operation to fail. 320 GSS_S_BAD_QOP indicates that the provided qop_alg value is not 321 recognized or supported for the environment. 323 GSS_S_BAD_MIC indicates that the received P-IDU contains an 324 incorrect integrity field (e.g., signature or MAC) for the data. 326 GSS_S_COMPLETE indicates that the requested operation was 327 successful. 329 Adams Document Expiration: May 1998 6 331 GSS_S_CREDENTIALS_EXPIRED indicates that the credentials associated 332 with this operation have expired, so that the requested operation 333 cannot be performed. 335 GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 336 performed on the credential structure referenced by 337 claimant_cred_handle failed, preventing further processing from 338 being performed using that credential structure. 340 GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 341 on the received P-IDU failed, preventing further processing 342 from being performed. 344 GSS_S_FAILURE indicates that the requested operation could not be 345 accomplished for reasons unspecified at the IDUP-GSS-API level, 346 and that no interface-defined recovery action is available. 348 GSS_S_NO_CRED indicates that no environment was established, 349 either because the input cred_handle was invalid or because the 350 caller lacks authorization to access the referenced credentials. 352 IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU 353 data origin auth. / integ. has either expired or been revoked. 355 IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU 356 cannot be completed because the encrypted IDU was invalid/defec- 357 tive (e.g., the final block was short or had incorrect padding). 359 IDUP_S_BAD_KE_KEY indicates that the key used to establish a key 360 for confidentiality purposes between originator and target has 361 either expired or been revoked. 363 IDUP_S_BAD_TARG_INFO indicates that the full set of supplied 364 information regarding the target(s) is invalid or is insufficient 365 for the protection of an IDU, so P-IDU cannot be created. 367 IDUP_S_DEFECTIVE_VERIF indicates that consistency checks performed 368 on Service_Verification_Info failed, preventing further processing 369 from being performed with that parameter. 371 IDUP_S_ENCAPSULATION_UNAVAIL (I) indicates that the underlying 372 mechanism does not support encapsulation of the M-IDU into the 373 token. 375 IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied 376 do not contain the information necessary for P-IDU unprotection. 378 IDUP_S_INCOMPLETE (I) indicates that the unprotection of the P-IDU 379 is not yet complete (i.e., a determination cannot yet be made on 380 the validity of the P-IDU). The application should call 381 IDUP_Form_Complete_PIDU and then should call this function again 382 with the complete P-IDU. 384 Adams Document Expiration: May 1998 7 386 IDUP_S_MORE_OUTBUFFER_NEEDED (I) indicates that the output buffer 387 supplied is too small to hold the generated data. The application 388 should continue calling this routine (until GSS_S_COMPLETE is 389 returned) in order to get all remaining output data. 391 IDUP_S_MORE_PIDU_NEEDED (I) indicates that not enough of the P-IDU 392 has been input yet for the completion of StartUnprotect. The 393 application should call this routine again with another buffer of 394 P-IDU in partial(initial)_pidu_buffer. 396 IDUP_S_NO_ENV indicates that no valid environment was recognized 397 for the env_handle provided. 399 IDUP_S_NO_MATCH indicates that Service_Verification_Info (or 400 evidence_check) and the P-IDU to be verified do not match. 402 IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 403 requested (TTIME or UTIME) is not available in the environment. 405 IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 406 does not support the service requested. 408 IDUP_S_SERV_VERIF_INFO_NEEDED (I) indicates that the 409 Service_Verification_Info parameter bundle must be input in order 410 for service verification to proceed. The output parameter 411 service_verification_info_id contains an identifier which may be 412 used by the calling application to locate the necessary 413 information. 415 IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 416 is not recognized or supported in the underlying mechanism. 418 1.2.2. Per-IDU Security Service Availability 420 Per-IDU security service availability in IDUP-GSS-API is to be 421 understood and used as described in GSS-API [RFC-2078], with the 422 exception that combinations of services requested by the calling 423 application and supported by the underlying mechanism may be applied 424 simultaneously to any IDU (true for both the SE and the EV calls, 425 but true in the fullest sense for the GP calls). 427 GSS-API callers desiring per-message security services should check 428 the relevant service OBJECT IDs at environment establishment time to 429 ensure that what is available in the established environment is 430 suitable for their security needs. 432 1.2.3. Per-IDU Replay Detection and Sequencing 434 The concept of per-IDU replay detection and sequencing discussed 435 in GSS-API [RFC-2078] is not relevant to the IDUP-GSS-API. 437 Adams Document Expiration: May 1998 8 439 1.2.4. Quality of Protection 441 The concept of QOP control in IDUP-GSS-API is to be understood 442 essentially as described in GSS-API [RFC-2078]. However, the actual 443 description and use of the QOP parameter is given as follows. 445 The qop_algs parameter for IDUP is defined to be a 32-bit unsigned 446 integer with the following bit-field assignments: 448 31 (MSB) (LSB) 0 449 ---------------------------------------------- 450 | U(19) | TS(5) | IA(4) | MA(4) | 451 ---------------------------------------------- 453 where 455 U is a 19-bit Unspecified field (available for future 456 use/expansion) -- must be set to zero; 458 TS is a 5-bit Type Specifier (a semantic qualifier whose value 459 specifies the type of algorithm which may be used to protect the 460 corresponding IDU -- see below for details); 462 IA is a 4-bit field enumerating Implementation-specific 463 Algorithms; and 465 MA is a 4-bit field enumerating Mechanism-defined Algorithms. 467 The interpretation of the qop_algs parameter is as follows. The MA 468 field is examined first. If it is non-zero then the algorithm used 469 to protect the IDU is the mechanism-specified algorithm corresponding 470 to that integer value. 472 If MA is zero then IA is examined. If this field value is non-zero 473 then the algorithm used to protect the IDU is the implementation- 474 specified algorithm corresponding to that integer value. Note that 475 use of this field may hinder portability since a particular value may 476 specify one algorithm in one implementation of the mechanism and may 477 not be supported or may specify a completely different algorithm in 478 another implementation of the mechanism. 480 Finally, if both MA and IA are zero then TS is examined. A value of 481 zero for TS specifies the default algorithm for the established 482 mechanism. A non-zero value for TS corresponds to a particular 483 algorithm qualifier and selects any algorithm from the mechanism 484 specification which satisfies that qualifier (which actual algorithm 485 is selected is an implementation choice; the calling application need 486 not be aware of the choice made). 488 The following TS values (i.e., algorithm qualifiers) are specified; 489 other values may be added in the future. 491 Adams Document Expiration: May 1998 9 493 When qop_algs is used to select a confidentiality algorithm: 495 00000 (0) = default confidentiality algorithm 496 00001 (1) = IDUP_SYM_ALG_STRENGTH_STRONG 497 00010 (2) = IDUP_SYM_ALG_STRENGTH_MEDIUM 498 00011 (3) = IDUP_SYM_ALG_STRENGTH_WEAK 499 11111 (31) = IDUP_NO_CONFIDENTIALITY 501 When qop_algs is used to select a DOA/integrity algorithm: 503 00000 (0) = default integrity algorithm 504 00001 (1) = IDUP_INT_ALG_DIG_SIGNATURE 505 (integrity provided through a digital signature) 506 00010 (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE 507 (integrity without a dig. sig. (e.g., with a MAC)) 508 11111 (31) = IDUP_NO_INTEGRITY 510 Clearly, qualifiers such as strong, medium, and weak are debatable 511 and likely to change with time, but for the purposes of this version 512 of the specification we define these terms as follows. A confiden- 513 tiality algorithm is "weak" if the effective key length of the cipher 514 is 40 bits or less; it is "medium-strength" if the effective key 515 length is strictly between 40 and 80 bits; and it is "strong" if the 516 effective key length is 80 bits or greater. ("Effective key length" 517 describes the computational effort required to break a cipher using 518 the best-known cryptanalytic attack against that cipher.) 520 A five-bit TS field allows up to 30 qualifiers for each of confiden- 521 tiality and integrity (since "0" is reserved for "default" and "31" 522 is reserved for "none", as shown above). This document specifies 523 three for confidentiality and two for integrity, leaving a lot of 524 room for future specification. Suggestions of qualifiers such as 525 "fast", "medium-speed", and "slow" have been made, but such terms are 526 difficult to quantify (and in any case are platform- and processor- 527 dependent), and so have been left out of this initial specification. 528 The intention is that the TS terms be quantitative, environment- 529 independent qualifiers of algorithms, as much as this is possible. 531 Use of the qop_algs parameter as defined above is ultimately meant to 532 be as follows. 534 - TS values are specified at the IDUP-GSS-API level and are 535 therefore portable across mechanisms. Applications which know 536 nothing about algorithms are still able to choose "quality" of 537 protection for their message tokens. 539 - MA values are specified at the mechanism level and are therefore 540 portable across implementations of a mechanism. 542 - IA values are specified at the implementation level (in user 543 documentation, for example) and are therefore typically non- 544 portable. An application which is aware of its own mechanism 545 implementation and the mechanism implementation of its intended 546 P-IDU recipient, however, is free to use these values since they 548 Adams Document Expiration: May 1998 10 550 will be perfectly valid and meaningful for protecting IDUs 551 between those entities. 553 The receiver of a P-IDU must pass back to its calling application 554 (in IDUP_Start_Unprotect()) a qop_algs parameter with all relevant 555 fields set. For example, if triple-DES has been specified by a 556 mechanism as algorithm 8, then a receiver of a triple-DES-protected 557 P-IDU must pass to its application (TS=1, IA=0, MA=8). In this way, 558 the application is free to read whatever part of the qop_algs 559 parameter it understands (TS or IA/MA). 561 1.2.5. The Provision of Time 563 IDUP mechanisms should make provision in their protocols for the 564 carrying of time information from originator to target(s). That is, 565 a target (a legitimate recipient) should get some indication during 566 unprotection regarding the time at which the protection operation 567 took place. This is particularly important if the mechanism offers 568 non-repudiation services because in some cases evidence verification 569 may only be achievable if the time at which the evidence was 570 generated is known. 572 Depending upon the platform and resources available to the 573 implementation, an IDUP environment may have access to a source of 574 trusted (secure) time, untrusted (local) time, both kinds of time, or 575 no time. OBJECT IDs indicating such availability are returned by the 576 IDUP_Establish_Env() call. When starting a protection operation, an 577 application may specify which time services it wishes to have applied 578 to the IDU. Similarly, for unprotection, an application may specify 579 which kind of time (if any) to consult when the validity of the P-IDU 580 is to be established. Specifying both kinds of time is interpreted 581 to mean that the calling application does not care which kind of time 582 is used. 584 The IDUP calls which use a time parameter specify the type of that 585 parameter to be INTEGER. This INTEGER is defined in all cases to be 586 the number of seconds which have elapsed since midnight, January 1, 587 1970, coordinated universal time. 589 2. Interface Descriptions 591 This section describes the IDUP-GSS-API's operational interface, 592 dividing the set of calls offered into five groups. Credential 593 management calls are related to the acquisition and release of 594 credentials by API callers. Environment-level calls are related to 595 the management of the security environment by an API caller. Per-IDU 596 calls are related to the protection or unprotection of individual 597 IDUs in established security environments. Special-purpose calls 598 deal with unusual or auxiliary evidence generation/verification 599 requirements. Support calls provide extra functions useful to 600 IDUP-GSS-API callers. Table 2 groups and summarizes the calls in 601 tabular fashion. 603 Adams Document Expiration: May 1998 11 605 Table 2: IDUP-GSS-API Calls 607 CREDENTIAL MANAGEMENT 608 (see the calls given in Section 2.1 of GSS-API [RFC-2078]) 610 ENVIRONMENT-LEVEL CALLS 611 IDUP_Establish_Env 612 IDUP_Abolish_Env 613 IDUP_Inquire_Env 615 PER-IDU CALLS 616 SE (SIGN,ENCRYPT) CALLS 617 IDUP_SE_SingleBuffer_Protect 618 IDUP_SE_SingleBuffer_Unprotect 619 IDUP_SE_MultiBuffer_StartProtect 620 IDUP_SE_MultiBuffer_EndProtect 621 IDUP_SE_MultiBuffer_StartUnprotect 622 IDUP_SE_MultiBuffer_EndUnprotect 623 IDUP_SE_Process_Buffer 624 EV (EVIDENCE) CALLS 625 IDUP_EV_SingleBuffer_Generate 626 IDUP_EV_SingleBuffer_Verify 627 IDUP_EV_MultiBuffer_StartGenerate 628 IDUP_EV_MultiBuffer_EndGenerate 629 IDUP_EV_MultiBuffer_StartVerify 630 IDUP_EV_MultiBuffer_EndVerify 631 IDUP_EV_Process_Buffer 632 GP (GENERAL PROTECTION) CALLS 633 IDUP_Start_Protect 634 IDUP_Protect 635 IDUP_End_Protect 636 IDUP_Start_Unprotect 637 IDUP_Unprotect 638 IDUP_End_Unprotect 640 SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms) 641 IDUP_Form_Complete_PIDU 643 SUPPORT CALLS 644 IDUP_Acquire_cred_with_auth 645 IDUP_Get_Token_Details 646 IDUP_Get_Policy_Info 647 (see also the calls given in Section 2.4 of GSS-API [RFC-2078]) 649 In terms of conformance to this specification, IDUP-GSS-API 650 implementations must support the credential management calls, the 651 environment-level calls, some subset of the per-IDU calls, and the 652 support calls (except where explicitly stated otherwise in Section 653 2.5). The subset of per-IDU calls supported will depend upon the 654 underlying mechanisms supported and will typically be the SE calls, 655 or the EV calls, or both. As stated in Section 2.3.2.1, 656 implementations are encouraged to support the more powerful GP calls 657 to anticipate the future needs of applications developers, but this 658 is not required for conformance. 660 Adams Document Expiration: May 1998 12 662 2.1. Credential management calls 664 2.1.1. Relationship to GSS-API 666 Credential management in IDUP-GSS-API is to be understood and used as 667 described in GSS-API [RFC-2078]. The calls given in Section 2.1 of 668 GSS-API (including all associated parameters) are unchanged, although 669 the interpretation of the cred_usage parameter in the GSS-API calls 670 for IDUP purposes is as follows. 672 NO_RESTRICTION 4 673 ENCRYPT_ONLY 8 674 DECRYPT_ONLY 16 675 SIGN_ONLY 32 676 VERIFY_ONLY 64 678 The values above may be logically OR'ed together in any desired 679 combination to restrict credential usage. Future possible values for 680 this parameter are for further study. 682 The call IDUP_Acquire_cred_with_auth has been added as a support call 683 in this specification to permit authenticated credential acquirement; 684 see Section 2.5.2 for details. 686 2.2. Environment-level calls 688 This group of calls is devoted to the establishment and management of 689 an environment for the purpose of IDU protection and unprotection. 690 Before protecting or unprotecting any IDU, an application must call 691 IDUP_Establish_Env() to initialize environment information and select 692 the underlying IDUP-GSS mechanism to be used. A series of protection 693 or unprotection calls is made to process each IDU, the protection 694 calls resulting in a P-IDU for each. Finally, IDUP_Abolish_Env() 695 is called to flush all environment information. 697 Semantically, acquiring credentials and establishing an environment 698 is (in many cases) analogous to logging in to a system -- it 699 authenticates a local user to the system and gives that user access 700 to a set of operations which can be performed. 702 2.2.1. Relationship to GSS-API 704 The set of calls described in this section is used in place of the 705 calls described in Section 2.2 of GSS-API [RFC-2078], since those 706 calls are specific to a session-oriented environment. 708 2.2.2. IDUP_Establish_Env call 710 Inputs: 712 o claimant_cred_handle CREDENTIAL HANDLE, 713 -- NULL parameter specifies "use default" 715 Adams Document Expiration: May 1998 13 717 o req_mech_type OBJECT IDENTIFIER, 718 -- NULL parameter specifies "use default" 719 o req_environmentPolicies EnvironmentPolicies, 720 -- NULL parameter specifies "use default" 721 o req_services SET OF OBJECT IDENTIFIER, 723 Outputs: 725 o major_status INTEGER, 726 o minor_status INTEGER, 727 o env_handle ENVIRONMENT HANDLE, 728 o actual_mech_type OBJECT IDENTIFIER, 729 -- actual mechanism always indicated, never NULL 730 o actual_environmentPolicies EnvironmentPolicies, 731 -- actual values always indicated, never NULL 732 o ret_services SET OF OBJECT IDENTIFIER, 734 Return major_status codes: 736 o GSS_S_COMPLETE 737 -- environment-level information was successfully initialized, 738 -- and IDU / P-IDU processing can begin. 739 o GSS_S_DEFECTIVE_CREDENTIAL 740 o GSS_S_NO_CRED 741 o GSS_S_CREDENTIALS_EXPIRED 742 -- the credentials provided through claimant_cred_handle are 743 -- no longer valid, so environment cannot be established. 744 o GSS_S_BAD_MECH 745 o GSS_S_FAILURE 747 The following structures are defined to facilitate environment policy 748 input and output: 750 EnvironmentPolicies ::= SEQUENCE { 751 confPolicy [0] PolicyAndTime OPTIONAL, 752 -- NULL parameter (on input) specifies "use default" 753 integPolicy [1] PolicyAndTime OPTIONAL, 754 -- NULL parameter (on input) specifies "use default" 755 evidencePolicy [2] PolicyAndTime OPTIONAL 756 -- NULL parameter (on input) specifies "use default" 757 } 759 PolicyAndTime ::= SEQUENCE { 760 policy OBJECT IDENTIFIER, 761 -- this environment-level policy identifier is separate from 762 -- the policy provisions connected with credentials, if they exist 763 time INTEGER 764 -- on input: the policy rules available at the specified time 765 -- on output: the time at which the policy rules came into effect 766 -- (defined to be the number of seconds elapsed since midnight, 767 -- January 1, 1970, coordinated universal time) 768 endTime INTEGER OPTIONAL 769 -- on input: unused 770 -- on output: the expiration time of the given policy rules 771 } 773 Adams Document Expiration: May 1998 14 775 This routine is used by an application which protects or unprotects 776 IDUs. Using information in the credentials structure referenced by 777 claimant_cred_handle, IDUP_Establish_Env() initializes the data 778 structures required to protect or unprotect IDUs. The 779 claimant_cred_handle, if non-NULL, must correspond to a valid 780 credentials structure. 782 This routine returns an env_handle for all future references to 783 this environment; when protection, unprotection, or 784 IDUP_Abolish_Env() calls are made, this handle value will be used 785 as the input env_handle argument. 786 It is the caller's responsibility to establish a communications path 787 to the intended recipients of the P-IDU, and to transmit the P-IDU to 788 those recipients over that path. This may occur subsequent to the 789 IDUP_Abolish_Env() call. 791 The req_services parameter may be used by the calling application to 792 request that data origin authentication with integrity, 793 confidentiality with integrity, evidence generation, and/or evidence 794 verification services be available in the established environment. 795 Requests can also be made for "trusted" or "untrusted" time services. 796 Requesting evidence generation or verification indicates that the 797 calling application may wish to generate or verify evidence 798 information for non-repudiation purposes (note: an IDU protector may 799 request that a flag be inserted into a P-IDU asking a recipient to 800 provide an evidence of the type "non-repudiation of delivery"; 801 however, the IDUP-GSS-API cannot by itself guarantee that the 802 evidence will be sent because there is no way to force a target to 803 send an evidence_token back to the IDU protector). 805 Not all features will be available in all underlying mech_types; the 806 returned value of ret_services indicates, as a function 807 of mech_type processing capabilities and the initiator-provided input 808 OBJECT IDs, the set of features which will be available in the 809 environment. The value of this parameter is undefined unless the 810 routine's major_status indicates COMPLETE. Failure to provide the 811 precise set of services desired by the caller does not cause 812 environment establishment to fail; it is the caller's choice to 813 abolish the environment if the service set provided is unsuitable for 814 the caller's use. The returned mech_type value indicates the 815 specific mechanism employed in the environment and will never 816 indicate the value for "default". 818 The following OBJECT IDs are defined for protection and unprotection 819 services (the OBJECT ID iso.org.dod.internet.security.services, 820 1.3.6.1.5.7, has been assigned by IANA, and some of the security 821 services under that node are assigned as shown below). It is 822 recognized that this list may grow over time. 824 PER_CONF = { 1.3.6.1.5.7.1.1 } 825 -- perform data confidentiality (i.e., encrypt data) 826 PER_CONF_FULL = { 1.3.6.1.5.7.1.3 } 827 -- perform full confidentiality (i.e., encrypt data and sig) 828 -- (may be used only when PER_DOA is requested simultaneously) 829 PER_DOA = { 1.3.6.1.5.7.3.1 } 830 -- perform data origin authentication with data integrity 832 Adams Document Expiration: May 1998 15 834 PER_DOA_CIPH = { 1.3.6.1.5.7.3.3 } 835 -- perform DOA with DI over ciphertext (rather than plaintext) 836 -- (may be used only when PER_CONF is requested simultaneously) 837 PER_POO = { 1.3.6.1.5.7.4.1 } 838 -- perform (i.e., create) non-repudiable "proof of origin" 839 PER_POD = { 1.3.6.1.5.7.4.3 } 840 -- perform (i.e., create) non-repudiable "proof of delivery" 841 REC_CONF = { 1.3.6.1.5.7.1.2 } 842 -- receive data confidentiality (i.e., decrypt data) 843 REC_CONF_FULL = { 1.3.6.1.5.7.1.4 } 844 -- receive full confidentiality (i.e., decrypt data and sig) 845 -- (may be used only when REC_DOA is received simultaneously) 846 REC_DOA = { 1.3.6.1.5.7.3.2 } 847 -- receive / verify DOA with data integrity 848 REC_DOA_CIPH = { 1.3.6.1.5.7.3.4 } 849 -- verify DOA with DI over ciphertext (rather than plaintext) 850 -- (may be used only when PER_CONF is received simultaneously) 851 REC_POO = { 1.3.6.1.5.7.4.2 } 852 -- receive / verify "proof of origin" 853 REC_POD = { 1.3.6.1.5.7.4.4 } 854 -- receive / verify "proof of delivery" 855 TTIME = { 1.3.6.1.5.7.7.1 } 856 -- trusted time availability 857 UTIME = { 1.3.6.1.5.7.7.2 } 858 -- untrusted time availability 860 The PER_CONF return value (in the ret_services paramater) indicates 861 whether the environment supports confidentiality services, and so 862 informs the caller whether or not a request for encryption can be 863 honored. In similar fashion, the PER_DOA return value indicates 864 whether DOA services are available in the established environment, 865 and the PER_POO and PER_POD return values indicate whether evidence 866 generation services are available. The TTIME and UTIME values 867 indicate whether trusted time and untrusted time are available for 868 protection / unprotection services. 870 Note that, unlike a GSS "context", an IDUP environment does not have 871 an explicit lifetime associated with it. Instead, it relies on the 872 lifetime of the calling entity's credential (set by the caller in the 873 GSS_Acquire_cred() call). When the credential expires (or is 874 explicitly deleted in any other way), no new operations are allowed 875 in the IDUP environment (although operations which have begun, such 876 as the Protection set of calls, can be taken to completion). 878 2.2.3. IDUP_Abolish_Env call 880 Input: 882 o env_handle ENVIRONMENT HANDLE 884 Outputs: 886 o major_status INTEGER, 887 o minor_status INTEGER, 889 Adams Document Expiration: May 1998 16 891 Return major_status codes: 893 o GSS_S_COMPLETE 894 -- the relevant environment-specific information was flushed. 895 o IDUP_S_NO_ENV 896 o GSS_S_FAILURE 898 This call is made to flush environment-specific information. (Once an 899 environment is established, cached credential and environment-related 900 info. is expected to be retained until an IDUP_Abolish_Env() call is 901 made or until the cred. lifetime expires.) Attempts to perform IDU 902 processing on a deleted environment will result in error returns. 904 2.2.4. IDUP_Inquire_Env call 906 Input: 908 o env_handle ENVIRONMENT HANDLE, 910 Outputs: 912 o major_status INTEGER, 913 o minor_status INTEGER, 914 o mech_type OBJECT IDENTIFIER, 915 -- the mechanism supporting this environment 916 o environmentPolicies EnvironmentPolicies, 917 -- the environment policies in effect 918 o ret_services SET OF OBJECT IDENTIFIER, 920 Return major_status codes: 922 o GSS_S_COMPLETE 923 -- referenced environment is valid and mech_type and other return 924 -- values describe the characteristics of the environment. 925 o GSS_S_CREDENTIALS_EXPIRED 926 o IDUP_S_NO_ENV 927 o GSS_S_FAILURE 929 This routine provides environment-related information to the caller. 931 2.3. Per-IDU calls 933 This group of calls is used to perform IDU protection and 934 unprotection processing on an established IDUP environment. Some of 935 these calls may block pending network interactions (depending on the 936 underlying mechanism in use). These calls may be invoked by an IDU's 937 protector or by the P-IDU's recipient. Members of this group form 938 pairs; the output from the protection types of calls is typically 939 meant to be input to the unprotection types of calls. 941 The per-IDU calls can support caller-requested data origin 942 authentication with data integrity, confidentiality with data 943 integrity, evidence, and evidence-requested-from-target services. 945 Adams Document Expiration: May 1998 17 947 The protection operations output a token which encapsulates all the 948 information required to unprotect the IDU. The token is passed to 949 the target (possibly separate from the M-IDU) and is processed by the 950 unprotection calls at that system. Unprotection performs 951 decipherment, DOA verification, evidence verification, or 952 notification of evidence requested, as required. 954 Each of the two main operations (protection and unprotection) may be 955 separated into three parts: "Start_Operation"; "Operation" (which 956 may be called once for each buffer of input data); and 957 "End_Operation". This separation is available for the case where the 958 IDU or P-IDU is to be processed one buffer at a time. 959 "Start_Operation" allows the caller to specify or retrieve the 960 appropriate "Quality" used during the processing. "Operation" is 961 concerned with the processing itself, receiving a buffer of input 962 data and potentially returning a buffer of output data. 963 "End_Operation" performs any required clean-up and creates the 964 appropriate token or states whether the input token was verified. 966 If the IDU or P-IDU is wholly contained in a single buffer, the 967 three-part protection/unprotection processing need not be done. 968 Instead, protection or unprotection can be accomplished using only 969 a single call, simplifying application code. 971 2.3.1. Relationship to GSS-API 973 The set of calls described in this section is used in place of the 974 calls GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() 975 which are specified in [RFC-2078], since those calls are specific to 976 a session-oriented environment. 978 2.3.2. The "SE" Calls 980 2.3.2.1. IDUP_SE Purpose 982 The "SE" group of calls provides a very simple, high-level 983 interface to underlying IDUP mechanisms when application developers 984 need access only to signature and encryption protection/unprotection 985 services. It includes both the single-buffer and multiple-buffer IDU 986 cases and can be used for signing only, encrypting only, signing and 987 encrypting (in either order, and with or without visibility of the 988 resulting signature), and "clear signing" (where the data is not 989 modified in any way and the signature itself is returned as a 990 separate item). [Note that encapsulation occurs in all cases except 991 for clear signing, so that these calls provide functionality similar 992 to the GSS_Wrap call.] 994 Note that the term "signing" is used in its most generic sense, not 995 necessarily implying the use of public-key techniques. This concept 996 has also been called "sealing" in other contexts (e.g., in other 997 standardization efforts). 999 Adams Document Expiration: May 1998 18 1001 The SE calls may be viewed by mechanism implementors as an "API" to 1002 the more powerful GP calls defined later and so may be implemented 1003 as simple mapping functions to those calls (when those optional 1004 calls are supported). Application callers, on the other hand, may 1005 find that the SE calls are all they currently need for many 1006 environments. At some time in the future when they have need of 1007 non-repudiation or "directed receipts" types of services, they may 1008 consider using the EV calls (or the GP calls -- when these are 1009 supported -- if complex and sophisticated combinations of services 1010 are required). To assist in this migration path, mechanism 1011 implementors are encouraged to support the full set of IDUP calls 1012 (i.e., the SE, EV, and GP calls) even though some calling 1013 applications will only use the SE calls in the short term. 1015 2.3.2.2. IDUP_SE Parameter Bundles 1017 The concept of "parameter bundles" is used in the calls presented in 1018 the following subsections in order to simplify their presentation and 1019 clarify their intended purpose and use. See Section 2.3.4.1 for a 1020 more complete description of parameter bundles. 1022 The following parameter bundles are used in the "SE" protection and 1023 unprotection sets of calls. 1025 o Protect_Options PARAMETER BUNDLE 1026 o protect_operation INTEGER { 1027 sign_only (0), 1028 encrypt_only (1), 1029 sign_and_encrypt (2), 1030 -- let mechanism choose order (and readability of signature) 1031 sign_then_encrypt_data (3), 1032 -- sign, then encrypt plaintext (leaving signature in clear) 1033 sign_then_encrypt_full (4), 1034 -- sign, then encrypt everything (including signature) 1035 encrypt_then_sign (5), 1036 -- encrypt, then sign the ciphertext 1037 clear_sign_only (6) 1038 } OPTIONAL, 1039 o protect_oper_oid OBJECT IDENTIFIER OPTIONAL, 1040 -- may be used in place of above parameter if OID is known 1041 o sign_qop_alg UNSIGNED INTEGER, 1042 o enc_qop_alg UNSIGNED INTEGER, 1043 o idu_type_string OCTET STRING, 1044 -- type of the IDU ("data", "e-mail doc", MIME type, etc.) 1045 o pidu_type_string OCTET STRING 1047 o PIDU_Information PARAMETER BUNDLE 1048 o protect_options Protect_Options, 1049 o originator_name INTERNAL NAME, 1050 o protection_time INTEGER, 1052 Adams Document Expiration: May 1998 19 1054 o Bad_Target_Name PARAMETER BUNDLE, -- same as in Section 2.3.3.2 1055 o bad_targ_name INTERNAL NAME, 1056 o bad_targ_status INTEGER, 1057 -- a (mechanism-defined) status flag giving the reason 1058 -- for rejection of the name in bad_targ_name. 1059 -- Example reasons may include: 1060 -- SYNTAX_INVALID the syntax of the name is invalid; 1061 -- NAME_UNRECOGNIZED the name is not recognized; 1062 -- NAME_AMBIGUOUS the name cannot be resolved; 1063 -- ACCESS_DENIED access to this target is denied; 1064 -- CERTIFICATE_NOT_FOUND the encryption certificate of the 1065 target could not be found. 1067 o Target_Info PARAMETER BUNDLE, -- same as in Section 2.3.3.2 1068 o targ_names SET OF INTERNAL NAME, 1069 o bad_targ_count INTEGER, 1070 o bad_target_name Bad_Target_Name, 1072 2.3.2.3. IDUP_SE major_status codes 1074 The following major_status return codes are defined for the "SE" 1075 calls in this section: 1077 o GSS_S_COMPLETE 1078 o IDUP_S_MORE_OUTBUFFER_NEEDED 1079 -- returned (by any SE call) to indicate that there is more output 1080 -- data than can fit into the supplied buffers. The application 1081 -- should save the returned data and call again to retrieve the 1082 -- remaining output. 1083 o IDUP_S_MORE_PIDU_NEEDED 1084 -- indicates that more PIDU data is needed for the StartUnprotect 1085 -- operation (e.g., so that PIDU_Information or initial_idu_buffer 1086 -- may be returned). 1087 o GSS_S_CREDENTIALS_EXPIRED 1088 o IDUP_S_NO_ENV 1089 o GSS_S_BAD_QOP 1090 o GSS_S_FAILURE 1092 If Target_Info is used as an input parameter (e.g., if an encryption 1093 operation is being performed), the following major_status return code 1094 is also defined: 1096 o IDUP_S_BAD_TARG_INFO 1098 Note for this return code that if one or more of the targets in 1099 targ_names cannot be used as a valid recipient of the P-IDU, these 1100 names will be returned in bad_targ_names (with associated status 1101 codes in bad_targ_status). As long as at least one of the targets 1102 can be used, however, this does not cause this call to fail (i.e., 1103 the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the 1104 caller's choice to discontinue IDU protection if the target set 1105 which can be used is unsuitable for the caller's purposes. 1107 Adams Document Expiration: May 1998 20 1109 2.3.2.4. IDUP_SE_SingleBuffer_Protect call 1111 Inputs: 1112 o env_handle ENVIRONMENT HANDLE, 1113 o Protect_Options PARAMETER BUNDLE, 1114 o Target_Info PARAMETER BUNDLE, 1115 o idu_buffer OCTET STRING 1116 o additional_protection BOOLEAN 1117 -- TRUE if idu_buffer is the output of a previous protection 1118 -- operation (i.e., if this is the second (or higher) in a 1119 -- series of SE/EV protection calls) 1121 Outputs: 1122 o major_status INTEGER, 1123 o minor_status INTEGER, 1124 o pidu_buffer OCTET STRING, 1125 o sig_token OCTET STRING 1126 -- used if Protect_Options is clear_sign_only 1128 Using the security environment referenced by env_handle, encrypt 1129 and/or sign the supplied IDU. If "clear signing" is performed, the 1130 signature will be returned in sig_token and pidu_buffer may be empty 1131 (depends on underlying mechanism). 1133 2.3.2.5. IDUP_SE_SingleBuffer_Unprotect call 1135 Inputs: 1136 o env_handle ENVIRONMENT HANDLE, 1137 o pidu_buffer OCTET STRING, 1138 -- may contain an IDU if sig_token is non-NULL (i.e., if 1139 -- clear_sign_only protection was applied) 1140 o sig_token OCTET STRING 1142 Outputs: 1143 o major_status INTEGER, 1144 o minor_status INTEGER, 1145 o idu_buffer OCTET STRING, 1146 -- may be empty if clear_sign_only protection was applied (depends 1147 -- on underlying mechanism) 1148 o PIDU_Information PARAMETER BUNDLE 1149 o additional_unprotection BOOLEAN 1150 -- TRUE if idu_buffer should be input to another unprotection 1151 -- operation (i.e., if this should not be the last in a series 1152 -- of SE/EV unprotection calls) 1154 Using the security environment referenced by env_handle, decrypt 1155 and/or verify the supplied PIDU and return the contained IDU along 1156 with all available PIDU_Information. 1158 2.3.2.6. IDUP_SE_MultiBuffer_StartProtect call 1160 Inputs: 1161 o env_handle ENVIRONMENT HANDLE, 1162 o Protect_Options PARAMETER BUNDLE, 1163 o Target_Info PARAMETER BUNDLE, 1164 o additional_protection BOOLEAN -- (see Section 2.3.2.4) 1166 Adams Document Expiration: May 1998 21 1168 Outputs: 1169 o major_status INTEGER, 1170 o minor_status INTEGER, 1171 o initial_pidu_buffer OCTET STRING 1172 -- may be empty (depends on underlying mechanism) 1174 Using the security environment referenced by env_handle, initialize 1175 the data structures required to begin the process of signing 1176 and/or encrypting the IDU (which will be supplied in multiple buffers 1177 to the Process_Buffer call). 1179 2.3.2.7. IDUP_SE_MultiBuffer_EndProtect call 1181 Inputs: 1182 o env_handle ENVIRONMENT HANDLE 1184 Outputs: 1185 o major_status INTEGER, 1186 o minor_status INTEGER, 1187 o final_pidu_buffer OCTET STRING, 1188 o sig_token OCTET STRING 1189 -- used if Protect_Options was clear_sign_only 1191 Using the security environment referenced by env_handle, complete the 1192 protection processing on the data and place the computed output in 1193 final_pidu_buffer and/or sig_token. Successful application of 1194 IDUP_SE_MultiBuffer_EndProtect() does not guarantee that unprotection 1195 can necessarily be performed successfully when the P-IDU arrives at 1196 the target (for example, it may be damaged in transit). 1198 2.3.2.8. IDUP_SE_MultiBuffer_StartUnprotect call 1200 Inputs: 1201 o env_handle ENVIRONMENT HANDLE, 1202 o initial_pidu_buffer OCTET STRING, 1203 o sign_qop_alg_in UNSIGNED INTEGER, 1204 -- used if Protect_Options was clear_sign_only (and calling 1205 -- application has prior knowledge of signing alg. applied); 1206 -- if NULL, then sig_token must be supplied 1207 o sig_token OCTET STRING 1208 -- used if Protect_Options was clear_sign_only; 1209 -- if NULL, then sign_qop_alg_in must be supplied 1211 Outputs: 1212 o major_status INTEGER, 1213 o minor_status INTEGER, 1214 o PIDU_Information PARAMETER BUNDLE, 1215 -- returns all available information 1216 o initial_idu_buffer OCTET STRING 1217 -- may be empty 1219 Using the security environment referenced by env_handle, initialize 1220 the data structures required to begin the process of decrypting 1221 and/or verifying the PIDU (which will be supplied in multiple buffers 1222 to the Process_Buffer call). 1224 Adams Document Expiration: May 1998 22 1226 The parameters sign_qop_alg_in and sig_token should not both be 1227 supplied (i.e., they should not both be non-NULL). If they are both 1228 non-NULL, however, sig_token is taken to be authoritative since 1229 this is the token created at protection time and therefore is 1230 guaranteed to carry the information needed to unprotect. 1232 2.3.2.9. IDUP_SE_MultiBuffer_EndUnprotect call 1234 Inputs: 1235 o env_handle ENVIRONMENT HANDLE, 1236 o sig_token OCTET STRING OPTIONAL 1237 -- used if Protect_Options was clear_sign_only and sig_token was 1238 -- not available when StartUnprotect was called 1240 Outputs: 1241 o major_status INTEGER, 1242 o minor_status INTEGER, 1243 o PIDU_Information PARAMETER BUNDLE, 1244 -- returns all available information 1245 o final_idu_buffer OCTET STRING -- may be empty 1246 o additional_unprotection BOOLEAN -- (see Section 2.3.2.5) 1248 Using the security environment referenced by env_handle, complete the 1249 decryption and/or verification processing on the data and place any 1250 residual output in final_idu_buffer. 1252 2.3.2.10. IDUP_SE_Process_Buffer call 1254 Inputs: 1255 o env_handle ENVIRONMENT HANDLE, 1256 o input_buffer OCTET STRING, 1258 Outputs: 1259 o major_status INTEGER, 1260 o minor_status INTEGER, 1261 o output_buffer OCTET STRING 1262 -- may be zero length (depends on underlying mechanism and 1263 -- corresponding Start() call and Protect_Options value) 1265 Using the security environment referenced by env_handle, continue the 1266 processing on the data in input_buffer and, if it is available, put 1267 any resulting output data in output_buffer. The application calls 1268 this routine over and over again with new buffers of data until it 1269 has processed all the data buffers of the IDU/PIDU. It then calls 1270 the appropriate End() call to complete the processing. 1272 2.3.3. The "EV" Calls 1274 2.3.3.1. IDUP_EV Purpose 1276 The "EV" group of calls provides a simple, high-level interface 1277 to underlying IDUP mechanisms when application developers 1278 need to deal only with evidence but not with encryption or integrity 1279 services. It includes both the single-buffer and multiple-buffer 1280 IDU cases and can be used for the generation and verification of 1281 evidence tokens embodying several different types of evidences. 1283 Adams Document Expiration: May 1998 23 1285 The following list of evidence types is supported. This list 1286 is by no means exhaustive and it is anticipated that it may be 1287 extended in future versions of this specification. 1289 "Non-repudiation of Origin" prevents a message creator's 1290 false denial of creating and sending a message. 1292 "Non-repudiation of Creation" prevents a message creator's 1293 false denial of creating a message. 1295 "Non-repudiation of Sender" prevents a message creator's 1296 false denial of sending a message (that was not necessarily 1297 created by the sender). 1299 "Non-repudiation of Delivery" prevents a message recipient's 1300 false denial of having received and looked at the content of a 1301 message. 1303 "Non-repudiation of Receipt" prevents a message recipient's 1304 false denial of having received a message (whose content was 1305 not necessarily looked at by the recipient). 1307 "Non-repudiation of Approval" prevents a message recipient's 1308 false denial of having approved the content of a received 1309 message. 1311 An evidence is provided in the form of a evidence token. Two forms 1312 of evidence tokens are supported: 1314 o Tokens including the associated data, 1316 o Tokens without included data (but with a unique reference to 1317 the associated data). 1319 Evidence tokens may be freely distributed. Any possessor of an 1320 evidence token (and of the associated data, if not included in the 1321 token) can verify the evidence if it has the appropriate 1322 credentials which include the definition of security policies (i.e., 1323 keys alone do not permit the verification of evidence tokens). Any 1324 holder of an evidence token may store it (along with the associated 1325 data, if not included in the token) for later verification. 1327 Calls that are specific to the support of evidence include: 1329 * Generate_token, which generates a non-repudiation token using the 1330 current environment. The generated token may consist of: 1332 1 - an evidence token 1334 2 - a token containing a request for an evidence, which carries 1335 information describing which evidence type should be generated 1336 by the recipient(s) and sent back to some entities (that may or 1337 may not include the sender). 1339 3 - a token containing an evidence token which is an answer to 1340 an evidence that has been previously requested. 1342 Adams Document Expiration: May 1998 24 1344 4 - a token including both an evidence and a request for another 1345 evidence to be provided. 1347 * Verify_evidence, which verifies the evidence token using the 1348 current environment. This operation returns a major_status code 1349 which can be used to determine whether the evidence contained in 1350 a token is complete (i.e., can be successfully verified (perhaps 1351 years) later). If a token's evidence is not complete, the token 1352 can be passed to form_complete_pidu to complete it. 1354 Additional useful calls for evidence services include: 1356 * IDUP_Get_token_details (see Section 2.5.3); 1357 * IDUP_Form_Complete_PIDU (see Section 2.4.2). 1359 2.3.3.2. IDUP_EV Parameters 1361 The following parameter bundles are used in the "EV" protection and 1362 unprotection sets of calls. 1364 o Nr_Options PARAMETER BUNDLE 1365 o evidence_type INTEGER { 1366 no_evidence (0) 1367 -- used when request-only token desired 1368 proof_of_receipt (1), 1369 proof_of_delivery (2), 1370 proof_of_approval (3), 1371 proof_of_creation (4), 1372 proof_of_sender (5), 1373 proof_of_origin (6) 1374 } OPTIONAL, 1375 o evidence_type_oid OBJECT IDENTIFIER OPTIONAL, 1376 -- may be used in place of above parameter if OID is known 1377 o evidence_validity_duration INTEGER, 1378 -- duration_in_minutes 1379 -- DURATION_HOUR = 60; 1380 -- DURATION_DAY = 1440; 1381 -- DURATION_WEEK = 10080; 1382 -- DURATION_MONTH = 43200;// 30 days 1383 -- DURATION_YEAR = 525600;//365 days 1385 o Originator_Information PARAMETER BUNDLE 1386 o token_generator_name INTERNAL NAME, 1387 -- obtained from the credentials of the originator 1388 -- (e.g., from its public key certificate) 1389 o protection_time INTEGER OPTIONAL. 1391 o Bad_Target_Name PARAMETER BUNDLE -- same as in Section 2.3.2.2 1392 o bad_targ_name INTERNAL NAME, 1393 o bad_targ_status INTEGER 1394 -- a (mechanism-defined) status flag giving the reason 1395 -- for rejection of the name in bad_targ_name 1397 Adams Document Expiration: May 1998 25 1399 o Target_Info PARAMETER BUNDLE -- same as in Section 2.3.2.2 1400 o targ_names SET OF INTERNAL NAME, 1401 o bad_targ_count INTEGER, 1402 o Bad_Target_Name PARAMETER BUNDLE 1404 o Request_Features PARAMETER BUNDLE 1405 o requested_evidence_type INTEGER { 1406 no_evidence (0), - used when no token desired 1407 proof_of_receipt (1), 1408 proof_of_delivery (2), 1409 proof_of_approval (3), 1410 }, 1411 o nr_req_policy OBJECT IDENTIFIER, 1412 o evidence_from Target_Info, 1413 o evidence_to Target_Info, 1414 o include_received_token_in_evidence BOOLEAN 1416 The following data_type is used in the "EV" protection calls. 1418 o Nr_Operation INTEGER { 1419 evidence_and_or_evidence_request (1), 1420 returned_evidence (2) 1421 } 1423 2.3.3.3. IDUP_EV major_status codes 1425 The following major_status return codes are defined for the "EV" 1426 calls in this section: 1428 o GSS_S_COMPLETE 1429 -- indicates that the evidence is complete 1430 o IDUP_S_INCOMPLETE 1431 o IDUP_S_MORE_OUTBUFFER_NEEDED 1432 -- returned (by any EV call) to indicate that there is more output 1433 -- data than can fit into the supplied buffers. The application 1434 -- should save the returned data and call again to retrieve the 1435 -- remaining output. 1436 o GSS_S_CREDENTIALS_EXPIRED 1437 o IDUP_S_NO_MATCH 1438 o IDUP_S_NO_ENV 1439 o GSS_S_FAILURE 1441 If Target_Info is used as an input parameter (i.e., if an 1442 evidence is being requested ), the following major_status return 1443 code is also defined: 1445 o IDUP_S_BAD_TARG_INFO 1447 Note for this return code that if one or more of the targets in 1448 targ_names cannot be used as a valid recipient of the P-IDU, these 1449 names will be returned in bad_targ_names (with associated status 1450 codes in bad_targ_status). As long as at least one of the targets 1451 can be used, however, this does not cause this call to fail (i.e., 1452 the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the 1453 caller's choice to discontinue IDU protection if the target set 1454 which can be used is unsuitable for the caller's purposes. 1456 Adams Document Expiration: May 1998 26 1458 2.3.3.4. IDUP_EV_SingleBuffer_Generate call 1460 Inputs: 1462 o env_handle ENVIRONMENT HANDLE, 1463 o nr_operation Nr_Operation, 1464 o Nr_Options PARAMETER BUNDLE, 1465 o idu_buffer OCTET STRING, 1466 o form_complete_pidu BOOLEAN, 1467 -- if TRUE the implementation will attempt to form a complete PIDU 1468 o include_data_in_token BOOLEAN, 1469 -- if TRUE, data provided in idu_buffer will be included in the 1470 -- generated token; if FALSE, the data will not be included 1471 o Request_Features PARAMETER BUNDLE 1472 -- the type of the evidence that is requested; 1473 -- policy under which the returned evidence should be generated; 1474 -- the recipients that are supposed to send back an evidence; 1475 -- the recipients that should receive the requested evidence; 1476 -- an indicator include_received_token_in_evidence: 1477 -- if TRUE, the evidence token incorporating the request will be 1478 -- included in the data for which recipients will generate 1479 -- evidence; if FALSE, evidence will be generated using only 1480 -- the data (and not the token incorporating the request). 1481 o additional_protection BOOLEAN -- (see Section 2.3.2.4) 1483 Outputs: 1485 o major_status INTEGER, 1486 o minor_status INTEGER, 1487 o token OCTET STRING, 1488 o evidence_check OCTET STRING, 1489 -- present only if an evidence is requested. Consists of data to 1490 -- be used to verify the requested token(s) (if any) when they are 1491 -- received. 1493 Description: 1495 This operation generates a non-repudiation token associated with the 1496 data passed in an input buffer. Two kinds of operations can be 1497 performed (using the Nr_Operation parameter): 1499 a) generating a token that includes either an evidence only, or 1500 an evidence request only, or both an evidence and an evidence 1501 request; 1503 b) generating a response token for some recipients that includes an 1504 evidence generated as a response to a request (in this case 1505 the idu_buffer is used to enter the request token that was 1506 received). 1508 It is possible to request the generation of complete evidence. This 1509 may succeed or fail; if it fails, a subsequent call to 1510 Form_Complete_PIDU can be made. 1512 Adams Document Expiration: May 1998 27 1514 2.3.3.5. IDUP_EV_SingleBuffer_Verify call 1516 Inputs: 1518 o env_handle ENVIRONMENT HANDLE, 1519 o token OCTET STRING, 1520 o idu_buffer OCTET STRING, 1521 -- if not present within the token 1522 o evidence_check OCTET STRING, 1523 -- present only if the input token is a response to a previous 1524 -- request for evidence (this parameter is used to validate that 1525 -- evidence). 1527 Outputs: 1529 o major_status INTEGER, 1530 o minor_status INTEGER, 1531 o Nr_Options PARAMETER BUNDLE, 1532 o Originator_Information PARAMETER BUNDLE, 1533 o Request_Features PARAMETER BUNDLE, 1534 o trusted_time_stamping_time INTEGER OPTIONAL, 1535 -- present for informational purposes only 1536 o complete_evidence_before INTEGER OPTIONAL, 1537 -- if the major status code that is returned is 1538 -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called 1539 -- with the same token before this time. 1540 -- This may be required, for example, in order to insure that 1541 -- the time skew between the evidence generation time and 1542 -- the trusted time service's countersignature on the evidence 1543 -- falls within the interval allowed by the current NR policy. 1544 o complete_evidence_after INTEGER OPTIONAL, 1545 -- if the major status code that is returned is 1546 -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called 1547 -- with the same token after this time. 1548 -- This may be required, for example, to insure that all 1549 -- authorities involved in generating the evidence have passed 1550 -- the last time at which the current NR policy allows them to 1551 -- repudiate their keys. 1552 o idu_buffer OCTET STRING 1553 -- if the IDU was present within the token 1554 o additional_unprotection BOOLEAN -- (see Section 2.3.2.5) 1556 Description: 1558 Verifies the validity and discloses the content of a nr_token. 1560 If the token containing the evidence to be verified was provided to 1561 the calling application by a partner responding to the calling 1562 application's request, then the calling application must pass the 1563 evidence check it received when it generated the request as a 1564 parameter along with the token it received from the partner. 1566 Adams Document Expiration: May 1998 28 1568 Output indicators are provided which give guidance about the time or 1569 times at which form_complete_pidu should be called; see the 1570 parameter descriptions for explanations of these indicators and their 1571 use. Note that the time specified by complete_evidence_before may be 1572 earlier than that specified by complete_evidence_after; in this case 1573 it will be necessary to call form_complete_pidu twice. 1575 Because keys can be revoked or declared compromised, the return from 1576 verify_evidence cannot in all cases be a definitive "valid" or 1577 "invalid"; sometimes "conditionally valid" may be returned, 1578 depending upon the policy in use. IDUP_S_INCOMPLETE will be returned, 1579 for example, if: 1581 - the interval during which the generator of the evidence may 1582 permissibly declare his key invalid has not yet expired (and 1583 therefore it is possible that the evidence may be declared 1584 invalid in the future), or 1586 - trusted time is required for verification, and the time obtained 1587 from the token is not trusted. 1589 2.3.3.6. IDUP_EV_MultiBuffer_StartGenerate call 1591 Inputs: 1593 o env_handle ENVIRONMENT HANDLE, 1594 o nr_operation Nr_Operation, 1595 o Nr_Options PARAMETER BUNDLE, 1596 o form_complete_pidu BOOLEAN, 1597 o include_data_in_token BOOLEAN, 1598 o Request_Features PARAMETER BUNDLE 1599 o additional_protection BOOLEAN -- (see Section 2.3.2.4) 1601 Outputs: 1603 o major_status INTEGER, 1604 o minor_status INTEGER, 1605 o initial_pidu_buffer OCTET STRING 1606 -- may be empty (depends on underlying mechanism) 1608 Description: 1610 Using the security environment referenced by env_handle, initialize 1611 the data structures required to begin the generation of a token. 1612 The IDU will be supplied in multiple buffers to the 1613 IDUP_EV_Process_Buffer call). Two kinds of operations can be 1614 performed (using the Nr_Operation parameter) : 1616 a) generating a token that includes either an evidence only, or 1617 an evidence request only, or both an evidence and an evidence 1618 request. 1620 Adams Document Expiration: May 1998 29 1622 b) generating a return token for some recipients that includes an 1623 evidence generated as a response to a request. In that case 1624 the received token will be passed into the subsequent 1625 IDUP_EV_Process_Buffer calls. The boolean include_data_in_token 1626 is ignored as the output will always be contained in a single 1627 token. The Request_Features are ignored in that case at this 1628 time in order to keep things simple and to avoid the piggy- 1629 backing that is theoretically possible. 1631 It is possible to request the generation of complete evidence. This 1632 may succeed or fail; if it fails, a subsequent call to 1633 Form_Complete_PIDU can be made. 1635 2.3.3.7. IDUP_EV_MultiBuffer_EndGenerate call 1637 Inputs: 1639 o env_handle ENVIRONMENT HANDLE 1641 Outputs: 1643 o major_status INTEGER, 1644 o minor_status INTEGER, 1645 o final_pidu OCTET STRING, 1646 o token OCTET STRING, 1647 o evidence_check OCTET STRING 1648 -- present only if an evidence is requested. 1650 Description: 1652 Using the security environment referenced by env_handle, provide 1653 the requested token or the final P-IDU. A token will be generated 1654 if encapsulation was not requested; otherwise, the final P-IDU is 1655 provided. 1657 2.3.3.8. IDUP_EV_MultiBuffer_StartVerify call 1659 Inputs: 1661 o env_handle ENVIRONMENT HANDLE, 1662 o token OCTET STRING, 1663 o evidence_check OCTET STRING, 1664 -- present only if an evidence has been previously requested. 1666 Outputs: 1668 o major_status INTEGER, 1669 o minor_status INTEGER 1671 Adams Document Expiration: May 1998 30 1673 Description: 1675 Using the security environment referenced by env_handle, initialize 1676 the data structures required to begin the process of verifying the 1677 token. The P-IDU will be supplied in multiple buffers to the 1678 IDUP_EV_Process_Buffer call. 1680 2.3.3.9. IDUP_EV_MultiBuffer_EndVerify call 1682 Input: 1684 o env_handle ENVIRONMENT HANDLE 1686 Outputs: 1688 o major_status INTEGER, 1689 o minor_status INTEGER, 1690 o Nr_Options PARAMETER BUNDLE, 1691 o Originator_Information PARAMETER BUNDLE, 1692 o Request_Features PARAMETER BUNDLE, 1693 o trusted_time_stamping_time INTEGER OPTIONAL, 1694 o complete_evidence_before INTEGER OPTIONAL, 1695 o complete_evidence_after INTEGER OPTIONAL, 1696 o idu_buffer OCTET STRING 1697 -- if the IDU was present within the token 1698 o additional_unprotection BOOLEAN -- (see Section 2.3.2.5) 1700 Description: 1702 Using the security environment referenced by env_handle, complete 1703 the verification processing on the data and provide verified output 1704 parameters to the caller when the major status code is either: 1706 o GSS_S_COMPLETE or 1707 o IDUP_S_INCOMPLETE 1709 2.3.3.10. IDUP_EV_Process_Buffer call 1711 Inputs: 1713 o env_handle ENVIRONMENT HANDLE, 1714 o input_buffer OCTET STRING 1716 Outputs: 1718 o major_status INTEGER, 1719 o minor_status INTEGER, 1720 o output_buffer OCTET STRING 1721 -- may be zero length (depends on underlying mechanism and 1722 -- corresponding Generate () call and options 1723 -- (e.g., data_included_in_token) 1725 Adams Document Expiration: May 1998 31 1727 Description: 1729 Using the security environment referenced by env_handle, continue 1730 the processing on the data in input_buffer and, if it is available, 1731 put any resulting output data in output_buffer. The application 1732 calls this routine over and over again with new buffers of data 1733 until it has processed all the data buffers of the IDU/PIDU. It 1734 then calls the appropriate End() call to complete the processing. 1736 2.3.4. The "GP" Calls 1738 The "GP" group of calls provides a powerful interface to flexible 1739 and sophisticated combinations of protection and unprotection 1740 services. This power and flexibility, however, necessitates a 1741 more complex interface than either the SE or the EV calls. 1742 Furthermore, such combinations of services are not needed in many of 1743 the security mechanisms in common use today (although this is likely 1744 to change as time goes on). The GP calls are therefore specified to 1745 be OPTIONAL and need not be supported by IDUP-conformant 1746 implementations. 1748 2.3.4.1. Parameter Bundles 1750 The concept of "parameter bundles" is used in the calls presented in 1751 the following subsections in order to simplify their presentation and 1752 clarify their intended purpose and use (note that specific language 1753 bindings may or may not use parameter bundles for its actual calling 1754 conventions). A parameter bundle is simply a set of closely-related 1755 parameters of a call which are either all used by / available to the 1756 calling application or all not used by / unavailable to the calling 1757 application. These parameters may be all input parameters, all 1758 output parameters, or any combination of the two. 1760 An example use envisioned for parameter bundles in a language such as 1761 C would be as a structure, where individual parameters in the bundle 1762 are structure members. The calling application wishing to use a 1763 particular bundle would then allocate the appropriate structure 1764 variable, assign the desired input values to the appropriate members, 1765 and pass the address of the structure as the bundle "parameter". On 1766 output, the values of the appropriate output members may be read. An 1767 application not wishing to use a particular bundle (or one which is 1768 satisfied with default values for all input parameters of the bundle 1769 and which doesn't care about output values), can pass NULL as the 1770 bundle "parameter". From the mechanism implementor's perspective, if 1771 a parameter bundle is not supported (for example, if it represents a 1772 security service which is not supported by the implementation), then 1773 any non-NULL value passed as the bundle parameter will generate an 1774 error status return code. 1776 [Note that the parameter bundles given below are specific to the 1777 (optional) GP calls. Thus, these bundles need not be supported by 1778 IDUP-conformant implementations if the GP calls are not supported.] 1780 Adams Document Expiration: May 1998 32 1782 The following parameter bundles are used in the subsequent protection 1783 and unprotection sets of calls. A parameter preceded by "(I)" is an 1784 input parameter; one preceded by "(O)" is an output parameter; one 1785 preceded by neither is an input if the bundle itself is an input and 1786 is an output if the bundle itself is an output; one preceded by "(X)" 1787 is the opposite: an output if the bundle itself is an input and an 1788 input if the bundle itself is an output. 1790 o Mech_Specific_Info PARAMETER BUNDLE 1791 -- actual parameters included in this bundle are defined by (and 1792 -- specific to) the underlying mechanism 1794 o Sensitivity PARAMETER BUNDLE, 1795 -- actual parameters included in this bundle are defined by (and 1796 -- specific to) the underlying mechanism, but may include 1797 -- codified values for "Unclassified", "Secret", "Top Secret", 1798 -- and so on 1800 o Service_Creation_Info PARAMETER BUNDLE 1801 -- actual parameters included in this bundle are defined by (and 1802 -- specific to) the underlying mechanism, but it is mandatory 1803 -- that they include at least service_id and Quality 1805 o Service_Verification_Info PARAMETER BUNDLE 1806 -- actual parameters included in this bundle are defined by (and 1807 -- specific to) the underlying mechanism, but it is mandatory 1808 -- that they include at least service_id and Quality 1810 o Quality PARAMETER BUNDLE 1811 o qop_algs UNSIGNED INTEGER, 1812 o validity UNSIGNED INTEGER, 1813 -- protection guaranteed to be valid until time specified 1814 o policy_id OBJECT IDENTIFIER, 1815 -- security policy under which protection is/was carried out 1816 o allow_policy_mapping BOOLEAN, 1817 -- determines whether mapping between policy IDs is allowed 1818 o actual_policy_time INTEGER 1819 -- time at which the above policy rules came into effect 1821 o Idu_Information PARAMETER BUNDLE, 1822 o idu_type_oid OBJECT IDENTIFIER, 1823 o idu_type_string OCTET STRING, 1824 o idu_title OCTET STRING, 1825 o idu_sensitivity Sensitivity, 1826 o pidu_type_oid OBJECT IDENTIFIER, 1827 o pidu_type_string OCTET STRING, 1828 o pidu_title OCTET STRING, 1829 o pidu_sensitivity Sensitivity, 1831 o Prot_Information PARAMETER BUNDLE, 1832 o originator_name INTERNAL NAME, 1833 o idu_information Idu_Information, 1834 o protection_time INTEGER, 1836 Adams Document Expiration: May 1998 33 1838 o Special_Conditions PARAMETER BUNDLE, 1839 o prot_oper_id INTEGER, 1840 o form_complete_pidu BOOLEAN, 1841 -- input to protection operations for evidence generation 1842 o pidu_in_solic_service BOOLEAN, 1843 -- in protection operations, used as input for service 1844 -- solicitation to request that receiver include the 1845 -- received PIDU when generating the response. In unprot. 1846 -- operations, used as output to inform receiver that PIDU 1847 -- should be included when generating the response. 1848 o use_trusted_time BOOLEAN, 1849 o use_untrusted_time BOOLEAN, 1851 o Bad_Target_Name PARAMETER BUNDLE, 1852 o (O) bad_targ_name INTERNAL NAME, 1853 o (O) bad_targ_status INTEGER, 1854 -- a (mechanism-defined) status flag giving the reason 1855 -- for rejection of the name in bad_targ_name 1856 -- Example reasons may include: 1857 -- SYNTAX_INVALID 1858 -- the syntax of the name is invalid; 1859 -- NAME_UNRECOGNIZED 1860 -- the name is not recognized; 1861 -- NAME_AMBIGUOUS 1862 -- the name cannot be resolved; 1863 -- ACCESS_DENIED 1864 -- access to this target is denied; 1865 -- CERTIFICATE_NOT_FOUND 1866 -- the encryption certificate of the target could 1867 -- not be found. 1869 o Target_Info PARAMETER BUNDLE, 1870 o targ_names SET OF INTERNAL NAME, 1871 o (O) bad_targ_count INTEGER, 1872 o (O) bad_target_name Bad_Target_Name, 1874 o General_Service_Data PARAMETER BUNDLE, 1875 o target_info Target_Info, 1876 o (X) unencapsulated_token OCTET STRING, 1877 -- zero length if encapsulation_request is TRUE 1878 o (O) minor_status INTEGER, 1880 Three types of protection services are defined in IDUP. These are 1882 1. perform unsolicited service (i.e., act on a locally-generated 1883 service request), 1884 2. perform solicited service (i.e., act on a remotely-generated 1885 service request), and 1886 3. perform service solicitation (i.e., send a service request to 1887 the remote end). 1889 Adams Document Expiration: May 1998 34 1891 As an originator, applying data confidentiality with data integrity, 1892 or data origin authentication with data integrity, or proof of origin 1893 evidence is an example of service type 1. As a target, creating a 1894 proof of delivery (i.e., receipt) evidence token as the result of a 1895 request received from the originator is an example of service type 2. 1896 Finally, as an originator, submitting a request that one or more 1897 targets return a receipt for the data sent is an example of service 1898 type 3. 1900 The first four parameters in the Prot_Service parameter bundle 1901 pertain to all service types; the fifth parameter is used if and only 1902 if service type 2 is desired; parameters 6-8 are used if and only if 1903 service type 3 is desired. 1905 o Prot_Service PARAMETER BUNDLE 1906 o (I) prot_service_type INTEGER, 1907 o (I) service_id OBJECT IDENTIFIER, 1908 o (I) quality Quality, -- NULL specifies default Quality 1909 o (I) general_service_data General_Service_Data, 1910 o (I) service_creation_info Service_Creation_Info, 1911 o (I) service_to SET OF INTERNAL NAME, 1912 o (O) service_verification_info Service_Verification_Info, 1913 o (O) service_verification_info_id INTEGER, 1915 Also, three types of unprotection services are defined. These are 1917 1. receive unsolicited service (i.e., process unrequested 1918 remotely-generated service), 1919 2. receive solicited service (i.e., process remotely-generated 1920 response to locally-generated request), and 1921 3. receive service solicitation (i.e., process req. from rem. end) 1923 As a target, unprotecting an encrypted message, or verifying the 1924 originator's proof of origin is an example of service type 1. As an 1925 originator, verifying a proof of delivery which you requested from a 1926 target is an example of service type 2. Finally, as a target, 1927 receiving a request from an originator for a proof of delivery is an 1928 example of service type 3. 1930 The first four parameters in the Unprot_Service parameter bundle 1931 pertain to all service types; parameters 5-6 are used if and only if 1932 service type 2 is required; parameters 7-8 are used only if service 1933 type 3 is required. 1935 o Unprot_Service PARAMETER BUNDLE 1936 o (O) unprot_service_type INTEGER, 1937 o (O) service_id OBJECT IDENTIFIER, 1938 o (O) quality Quality, 1939 -- actual Quality specified (never NULL) 1940 o (O) general_service_data General_Service_Data, 1941 o (O) service_verification_info_id INTEGER, 1942 o (I) service_verification_info Service_Verification_Info, 1943 o (O) service_to SET OF INTERNAL NAME, 1944 o (O) service_creation_info Service_Creation_Info, 1946 Adams Document Expiration: May 1998 35 1948 2.3.4.2. IDUP_Start_Protect call 1950 Inputs: 1952 o env_handle ENVIRONMENT HANDLE, 1953 o Mech_Specific_Info PARAMETER BUNDLE, 1954 -- NULL selects the mechanism-defined default values 1955 o Idu_Information PARAMETER BUNDLE, 1956 o Special_Conditions PARAMETER BUNDLE, 1957 o encapsulation_request BOOLEAN, 1958 o single_idu_buffer OCTET STRING, 1959 -- non-zero length for this buffer means that Protect/End_Protect 1960 -- won't be called (i.e., entire IDU is contained in this buffer) 1961 o Target_Info PARAMETER BUNDLE, 1962 o Services_to_Perform SET OF Prot_Service, 1964 Outputs: 1966 o major_status INTEGER, 1967 o minor_status INTEGER, 1968 o midu_buffer OCTET STRING, 1969 -- zero length if encapsulation_request is TRUE; 1970 -- may be zero length otherwise (depends on underlying mechanism) 1971 o pidu_buffer OCTET STRING, 1972 -- zero length if encapsulation_request is FALSE; 1973 -- may be zero length otherwise (depends on underlying mechanism) 1975 Return major_status codes: 1977 o GSS_S_COMPLETE 1978 -- the protection process can begin (or has completed, if 1979 -- single_idu_buffer has non-zero length). 1980 o IDUP_S_MORE_OUTBUFFER_NEEDED 1981 o GSS_S_CREDENTIALS_EXPIRED 1982 o IDUP_S_NO_ENV 1983 o IDUP_S_ENCAPSULATION_UNAVAIL 1984 o IDUP_S_SERVICE_UNAVAIL 1985 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL 1986 o IDUP_S_UNKNOWN_OPER_ID 1987 o GSS_S_BAD_QOP 1988 o IDUP_S_BAD_TARG_INFO 1989 o GSS_S_FAILURE 1991 Using the security environment referenced by env_handle, initialize 1992 the data structures required to begin the process of protecting the 1993 IDU buffers. The caller requests specific protection services by 1994 supplying the appropriate Prot_Service parameter bundles in 1995 Services_to_Perform. Each service is able to return a minor status 1996 code to the calling application, if necessary. 1998 Adams Document Expiration: May 1998 36 2000 The calling application, knowing the size of the IDU it wishes to 2001 protect and the buffer size which it has available to it, can choose 2002 to input the entire IDU in a single buffer and omit the subsequent 2003 IDUP_Protect() and IDUP_End_Protect() calls. Furthermore, the 2004 application can request that the resulting M-IDU be encapsulated in 2005 the token -- so that the token contains the entire P-IDU -- rather 2006 than having it be returned separately in midu_buffer. Encapsulation, 2007 however, may not be supported by all underlying mechanisms or 2008 implementations; if this is the case, the 2009 IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and 2010 M-IDU will be returned in midu_buffer. 2012 For those mechanisms which allow or require multiple stages of 2013 processing, each producing a different aspect of protection for the 2014 IDU, the operation identifier prot_oper_id is used to specify 2015 which stage is currently being requested by the application. An 2016 example where this would be useful is a mechanism which implements 2017 the signed Message Security Protocol [MSP]. As another example, a 2018 mechanism may choose to do a digital signature in two stages: one 2019 for the hashing of the message and another for the signature on the 2020 hash. The calling application would therefore use the protection set 2021 of calls on the IDU in stage 1 and then use the protection set of 2022 calls on the token (from stage 1) in stage 2. 2024 Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where 2025 "n" is the number of stages as defined by the mechanism (typically 1 2026 or 2)). The calling application uses this parameter to indicate to 2027 the underlying mechanism whether it wishes to do stage 1 of 2028 protection / unprotection processing, or stage 2, and so on. Portable 2029 applications may pass "0" to let the mechanism choose the stage. 2031 If one or more of the targets in targ_names cannot be used as a valid 2032 recipient of the P-IDU, these names will be returned in 2033 bad_targ_names (with associated status codes in bad_targ_status). As 2034 long as at least one of the targets can be used, this does not cause 2035 this call to fail; it is the caller's choice to discontinue IDU 2036 protection if the target set which can be used is unsuitable for the 2037 caller's purposes. Note that each Prot_Service parameter bundle can 2038 also input a list of targ_names; this is used if a separate list is 2039 to be used for that service only (the general list of targets is to 2040 be used for all services unless overridden in this way). 2042 2.3.4.3. IDUP_Protect call 2044 Inputs: 2046 o env_handle ENVIRONMENT HANDLE, 2047 o input_buffer OCTET STRING, 2049 Outputs: 2051 o major_status INTEGER, 2052 o minor_status INTEGER, 2053 o output_buffer OCTET STRING 2054 -- may be zero length if encapsulation_request was set to TRUE in 2055 -- IDUP_Start_Protect() (depends on underlying mechanism) 2057 Adams Document Expiration: May 1998 37 2059 Return major_status codes: 2061 o GSS_S_COMPLETE 2062 o IDUP_S_NO_ENV 2063 o GSS_S_FAILURE 2065 Using the security environment referenced by env_handle, continue the 2066 protection processing on the data in input_buffer and, if the 2067 underlying mechanism defines this, put any resulting P-IDU/M-IDU data 2068 in output_buffer. The application calls this routine over and over 2069 again with new buffers of data until it has protected all the data 2070 buffers of the IDU. It then calls IDUP_End_Protect() to complete the 2071 protection processing. 2073 2.3.4.4. IDUP_End_Protect call 2075 Inputs: 2077 o env_handle ENVIRONMENT HANDLE, 2079 Outputs: 2081 o major_status INTEGER, 2082 o minor_status INTEGER, 2083 o Services_to_Perform SET OF Prot_Service, 2084 o final_midu_buffer OCTET STRING, 2085 -- zero length if encapsulation_request was set to TRUE in 2086 -- IDUP_Start_Protect(), in which case pidu is used 2087 o final_pidu_buffer OCTET STRING, 2088 -- zero length if encapsulation_request was set to FALSE in 2089 -- IDUP_Start_Protect(), in which case token and midu are used 2091 Return major_status codes: 2093 o GSS_S_COMPLETE 2094 -- protection has successfully completed and the resulting P-IDU 2095 -- is ready for transfer. If defined by the underlying mechanism, 2096 -- final_midu_buffer will contain any residual M-IDU data. 2097 o IDUP_S_MORE_OUTBUFFER_NEEDED 2098 o IDUP_S_NO_ENV 2099 o GSS_S_FAILURE 2101 Using the security environment referenced by env_handle, complete the 2102 protection processing on the data and place the computed output in 2103 final_pidu_buffer (or final_midu_buffer and the unencapsulated_token 2104 parameter for each Prot_Service). If a service was requested from 2105 one or more targets in Start_Protect() - and if this is supported by 2106 the underlying mechanism - Service_Verification_Info will hold 2107 whatever data is necessary for the mechanism to verify a service 2108 returned by a target (unprotector) of the P-IDU. Successful 2109 application of IDUP_End_Protect() does not guarantee that the 2110 corresponding unprotection set of calls can necessarily be performed 2111 successfully when the P-IDU arrives at the target (for example, it 2112 may be damaged in transit). 2114 Adams Document Expiration: May 1998 38 2116 2.3.4.5. IDUP_Start_Unprotect call 2118 Inputs: 2120 o env_handle ENVIRONMENT HANDLE, 2121 o Mech_Specific_Info PARAMETER BUNDLE, 2122 -- NULL selects the mechanism-defined default values 2123 o single_pidu_buffer OCTET STRING, 2124 -- non-zero length for this buffer means that IDUP_Unprotect() and 2125 -- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU 2126 -- (if encapsulation is used) or M-IDU (if encap. is not used) 2127 -- is contained in this buffer) 2128 o partial_pidu_buffer OCTET STRING, 2129 -- may be an arbitrary-sized piece of the full pidu (if the 2130 -- application's buffer isn't large enough to hold entire pidu). 2131 -- Used if pidu_buffer will be input a buffer at a time (except 2132 -- that the final buffer must be passed in final_pidu_buffer 2133 -- rather than partial_pidu_buffer). Only one of 2134 -- single_pidu_buffer and partial(final)_pidu_buffer can have 2135 -- nonzero length. 2136 o final_pidu_buffer OCTET STRING, 2137 o Special_Conditions PARAMETER BUNDLE, 2139 Outputs: 2141 o major_status INTEGER, 2142 o minor_status INTEGER, 2143 o Services_to_Receive SET OF Unprot_Service, 2144 o Prot_Information PARAMETER BUNDLE, 2145 o single_idu_buffer OCTET STRING, 2146 -- if this buffer has non-zero length, then service processing has 2147 -- been completed on the data in single_pidu_buffer 2148 o initial_idu_buffer OCTET STRING, 2149 -- holds any data from partial(final)_pidu_buffer which has been 2150 -- unprotected; remaining data will be returned by Unprotect and 2151 -- End_Unprotect as they are called with successive buffers of 2152 -- pidu 2153 o Service_Verification_Info PARAMETER BUNDLE, 2154 -- used only if target is on "service_to" list in Unprot_Service 2155 o service_verification_info_id INTEGER, 2156 -- used only if target is on "service_to" list in Unprot_Service 2158 Return major_status codes: 2160 o GSS_S_COMPLETE 2161 -- unprotection processing can begin (or has completed, if 2162 -- single_idu_buffer has non-zero length). 2163 o IDUP_S_INCOMPLETE 2164 -- used only if single_idu_buffer has non-zero length. 2165 o IDUP_S_MORE_OUTBUFFER_NEEDED 2166 o IDUP_S_MORE_PIDU_NEEDED 2167 o GSS_S_DEFECTIVE_TOKEN 2168 o IDUP_S_INAPPROPRIATE_CRED 2170 Adams Document Expiration: May 1998 39 2172 o IDUP_S_DEFECTIVE_VERIF 2173 o IDUP_S_NO_MATCH 2174 o IDUP_S_SERVICE_UNAVAIL 2175 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL 2176 o IDUP_S_SERV_VERIF_INFO_NEEDED 2177 o GSS_S_CREDENTIALS_EXPIRED 2178 o IDUP_S_NO_ENV 2179 o IDUP_S_UNKNOWN_OPER_ID 2180 o GSS_S_BAD_QOP 2181 -- the qop_algs value specified in P-IDU for at least one of the 2182 -- services is unavailable in the local mechanism, so processing 2183 -- cannot continue. 2184 o GSS_S_BAD_MIC 2185 o IDUP_S_BAD_DOA_KEY 2186 o IDUP_S_BAD_KE_KEY 2187 o IDUP_S_BAD_ENC_IDU 2188 o GSS_S_FAILURE 2190 Using the security environment referenced by env_handle, initialize 2191 the data structures required to begin the process of unprotecting a 2192 P-IDU. The caller will be alerted as to which services were applied 2193 to the P-IDU in the returned Services_to_Receive set of parameters. 2195 If encapsulation was not used by the originator, it is the receiving 2196 application's responsibility to separate the received P-IDU into a 2197 M-IDU and one or more unencapsulated_token buffers (the latter being 2198 input in separate Unprot_Service bundles in the Services_to_Receive 2199 parameter). These unencapsulated_token buffers should be input 2200 before the M-IDU (i.e., in IDUP_Start_Unprotect) or after the M-IDU 2201 (i.e., in IDUP_End_Unprotect) as appropriate; this order may be 2202 dictated, for example, by their placement in the in-coming message. 2204 If unprotection will be applied more than once to a given P-IDU, it 2205 is the responsibility of the calling application to remember if a 2206 service solicitation has been responded to previously (i.e., if the 2207 requested service has already been generated / sent for that P-IDU) 2208 and thus ignore subsequent solicitations on unprotect. 2210 The time flags indicate whether to consult trusted, untrusted, or no 2211 time (if both flags are FALSE) during the unprotection operation. If 2212 the current time is not to be checked, then unprotection may be 2213 successful even if the protector's key has expired since the P-IDU 2214 was generated (that is, if the Validity period -- as specified in 2215 the Quality parameter bundle -- has expired). 2217 If the underlying mechanism supports it and if this information is 2218 contained in the P-IDU, information regarding the originator (that 2219 is, the entity which used the protection set of calls to generate 2220 this P-IDU) is returned in the Prot_Information parameter bundle. 2222 Adams Document Expiration: May 1998 40 2224 2.3.4.6. IDUP_Unprotect call 2226 Inputs: 2228 o env_handle ENVIRONMENT HANDLE, 2229 o input_buffer OCTET STRING 2231 Outputs: 2233 o major_status INTEGER, 2234 o minor_status INTEGER, 2235 o output_buffer OCTET STRING 2237 Return major_status codes: 2239 o GSS_S_COMPLETE 2240 o IDUP_S_NO_ENV 2241 o GSS_S_FAILURE 2243 Using the security environment referenced by env_handle, continue the 2244 unprotection processing on the data in input_buffer, putting any 2245 resulting IDU data in output_buffer (if required). 2247 2.3.4.7. IDUP_End_Unprotect call 2249 Inputs: 2251 o env_handle ENVIRONMENT HANDLE, 2253 Outputs: 2255 o major_status INTEGER, 2256 o minor_status INTEGER, 2257 o Prot_Information PARAMETER BUNDLE, 2258 o Services_to_Receive SET OF Unprot_Service, 2259 o final_idu_buffer OCTET STRING, 2260 o Service_Verification_Info PARAMETER BUNDLE, 2261 -- used only if target is on "service_to" list in Unprot_Service 2262 o service_verification_info_id INTEGER, 2263 -- used only if target is on "service_to" list in Unprot_Service 2265 Return major_status codes: 2267 o GSS_S_COMPLETE 2268 -- residual IDU data will be returned in final_idu_buffer. 2269 o IDUP_S_INCOMPLETE 2270 o IDUP_S_MORE_OUTBUFFER_NEEDED 2271 o GSS_S_BAD_MIC 2272 o IDUP_S_BAD_DOA_KEY 2273 o IDUP_S_BAD_KE_KEY 2274 o IDUP_S_BAD_ENC_IDU 2275 o IDUP_S_NO_ENV 2276 o GSS_S_FAILURE 2278 Adams Document Expiration: May 1998 41 2280 Using the security environment referenced by env_handle, complete the 2281 unprotection processing on the data and return the appropriate status 2282 code. If there is any residual IDU data it will be returned in 2283 final_idu_buffer. 2285 If the IDUP_S_INCOMPLETE major status value is returned, all output 2286 parameters are conditionally valid; the unprotection set of functions 2287 will have to be called again (perhaps with a complete P-IDU, as 2288 produced by IDUP_Form_Complete_PIDU) in order to get valid values for 2289 all parameters. "Conditional validity" may arise, for example, if 2290 all relevant certificates verify correctly, but it is not yet past 2291 the time up to which the current policy allows the authorities 2292 involved to repudiate their keys. 2294 If the underlying mechanism supports it and if this information is 2295 contained in the token, information regarding the originator (that 2296 is, the entity which used the protection set of calls to generate 2297 this token) is returned in the Prot_Information parameter bundle. 2298 This information may or may not be omitted if it was returned by the 2299 IDUP_Start_Unprotect() call. 2301 Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the 2302 concept of error tokens transferred between sender and recipient 2303 since the protection and unprotection of an IDU may be separated by 2304 an indefinite amount of time and may or may not be performed by the 2305 same entity. 2307 2.4. Special-Purpose Calls 2309 2.4.1. Relationship to GSS-API 2311 The special-purpose call described in this section has no analog 2312 in GSS-API [RFC-2078]. This call is used to complete a P-IDU (that 2313 is, to generate a P-IDU which can be unprotected successfully with 2314 no additional data at any time during its validity period). This 2315 call may not be supported by all underlying IDUP mechanisms or 2316 implementations. 2318 2.4.2. IDUP_Form_Complete_PIDU call 2320 Inputs: 2322 o env_handle ENVIRONMENT HANDLE, 2323 o single_pidu_buffer OCTET STRING, 2324 o partial_pidu_buffer OCTET STRING, 2325 -- an arbitrary-sized piece of the full pidu token. Used if pidu 2326 -- will be input a buffer at a time (except that the final buffer 2327 -- must be passed in final_pidu_buffer rather than 2328 -- partial_pidu_buffer). Only one of single_pidu_buffer and 2329 -- partial(final)_pidu_buffer can have nonzero length. 2330 o final_pidu_buffer OCTET STRING, 2332 Adams Document Expiration: May 1998 42 2334 Outputs: 2336 o major_status INTEGER, 2337 o minor_status INTEGER, 2338 o pidu_token_out OCTET STRING -- the augmented PIDU; may be complete 2339 o call_again_before INTEGER, 2340 o call_again_after INTEGER, 2341 o trusted_time_stamping_time INTEGER -- for information only 2343 Return major_status codes: 2345 o GSS_S_COMPLETE 2346 o IDUP_S_MORE_OUTBUFFER_NEEDED 2347 o IDUP_S_INCOMPLETE 2348 -- generation of the P-IDU is not yet complete. The application 2349 -- should call this function again before the time given in 2350 -- call_again_before (if not NULL), or after the time given in 2351 -- call_again_after (if not NULL), or both (if neither are NULL). 2352 o IDUP_S_SERVICE_UNAVAIL 2353 o GSS_S_DEFECTIVE_TOKEN 2354 o GSS_S_FAILURE 2356 Form_Complete_PIDU is used primarily by the evidence services; in 2357 particular, when the evidence token itself does not contain all the 2358 data required for its verification and it is anticipated that some 2359 of the data not stored in the token may become unavailable during 2360 the interval between generation of the evidence token and 2361 verification unless it is stored in the token. The 2362 Form_Complete_PIDU operation gathers the missing information and 2363 includes it in the token so that verification can be guaranteed to 2364 be possible at any future time. 2366 This call generates a PIDU which can be unprotected successfully with 2367 no additional data at any time during its validity period. [For 2368 background information on the notion of "complete" evidence, see 2369 "CORBA Security Service v1.2 Draft D02", 18 June 1997.] 2371 Using the security environment referenced by env_handle, complete the 2372 generation of a P-IDU token and return the appropriate status value 2373 along with the completed token (if available). Such a call may be 2374 used, for example, for the purpose of batch evidence generation on an 2375 "evidence server". A local machine may be able to use the protection 2376 set of calls to fill out most of an evidence token and then send a 2377 number of these to a batch processor which forms the complete 2378 evidence tokens (perhaps by adding a certification path, or a 2379 timestamp and signature from a timestamping authority). As another 2380 example, on the receiving end an application may make such a call in 2381 order to collect all the information necessary to unprotect a P-IDU 2382 (such as all relevant certificates and Certificate Revocation Lists); 2383 this will ensure that the calls to the unprotection set of operations 2384 will be entirely local (i.e., can be performed off-line) and fast. 2386 Note that the complete P-IDU generated will be formed using trusted 2387 time if this is available in the environment referenced by env_handle 2388 and will use untrusted time or no time otherwise (depending on what 2389 is available). 2391 Adams Document Expiration: May 1998 43 2393 2.5. Support calls 2395 2.5.1. Relationship to GSS-API 2397 Support calls in IDUP-GSS-API are to be understood and used as 2398 described in GSS-API [RFC-2078]. The calls described in Section 2.4 2399 of GSS-API (including all associated parameters) are unchanged. The 2400 following additional calls are specified for IDUP-GSS-API. 2402 2.5.2: IDUP_Acquire_cred_with_auth call 2404 Inputs: 2406 o desired_name INTERNAL NAME, 2407 -- NULL requests locally-determined default 2408 o authenticator OCTET STRING 2409 -- string which authenticates the caller claiming to be 2410 -- desired_name 2411 o lifetime_req INTEGER, 2412 -- in seconds; 0 requests default 2413 o desired_mechs SET OF OBJECT IDENTIFIER, 2414 -- empty set requests system-selected default 2415 o cred_usage BIT STRING 2416 -- actual values which can be used currently correspond to those 2417 -- given in Section 2.1.1 (i.e., 2418 -- NO_RESTRICTION 4 2419 -- ENCRYPT_ONLY 8 2420 -- DECRYPT_ONLY 16 2421 -- SIGN_ONLY 32 2422 -- VERIFY_ONLY 64 2423 -- with the values logically OR'ed together in any desired 2424 -- combination to restrict credential usage). 2425 -- Future possible values for this parameter are for further 2426 -- study (note that the type of this parameter is BIT STRING 2427 -- (rather than INTEGER as in GSS_Acquire_cred) to facilitate 2428 -- such future expansion). 2430 Outputs: 2432 o major_status INTEGER, 2433 o minor_status INTEGER, 2434 o output_cred_handle CREDENTIAL HANDLE, 2435 o actual_mechs SET OF OBJECT IDENTIFIER, 2436 o lifetime_rec INTEGER 2437 -- in seconds, or reserved value for INDEFINITE 2439 This call (which need not be supported by all underlying mechanisms 2440 or implementations) is identical to the GSS_Acquire_cred call, with 2441 the exception of the added parameter "authenticator". This parameter 2442 (typically a password, pass-phrase, or PIN) is used to 2443 authenticate the caller claiming to be desired_name to the 2444 underlying GSS (or mechanism) code. 2446 Adams Document Expiration: May 1998 44 2448 Implementations that are able to authenticate the caller in some 2449 other way are encouraged to use the GSS_Acquire_cred call; those 2450 having no other means available to them, or wishing to explicitly 2451 authenticate the caller at the time of credential acquisition, 2452 should use the IDUP_Acquire_cred_with_auth call (if supported). 2454 Note that the return major status codes for this call are identical 2455 to those given for the GSS_Acquire_cred call. If the authentication 2456 fails (e.g., the wrong authenticator is supplied for the given 2457 desired_name), the major status GSS_S_FAILURE is returned (along with 2458 an appropriate minor status code). 2460 2.5.3. IDUP_Get_token_details call 2462 Inputs: 2464 o token OCTET STRING 2465 -- all the data to be returned shall be at the beginning of the 2466 -- token; hence, a single call is needed. It is not necessary to 2467 -- provide the entire token when the token includes the IDU. 2469 Outputs: 2471 o major_status INTEGER, 2472 o minor_status INTEGER, 2473 o mech_type OBJECT IDENTIFIER, 2474 o data_included_in_token BOOLEAN, 2475 -- true if the data is encapsulated 2476 o idu_size INTEGER, 2477 o has_SE_protection BOOLEAN, 2478 o has_EV_protection BOOLEAN, 2479 o PIDU_Information PARAMETER BUNDLE, 2480 o nr_policy OBJECT IDENTIFIER, 2481 -- this and subsequent parameters pertain only to evidence tokens 2482 o Nr_Options PARAMETER BUNDLE, 2483 o Originator_Information PARAMETER BUNDLE, 2484 o time_stamping_time INTEGER OPTIONAL 2485 o Request_Features PARAMETER BUNDLE, 2486 -- describes the included request, if any. 2487 o requested_evidence_back BOOLEAN, 2488 -- true if this is an evidence generated in response to a 2489 -- previously-sent request 2490 o evidence_check OCTET STRING, 2491 -- meaningful if the boolean above is true 2493 Return major_status codes: 2495 o GSS_S_COMPLETE 2496 -- input_token could be parsed for all relevant fields. 2497 o GSS_S_CREDENTIALS_EXPIRED 2498 o GSS_S_DEFECTIVE_TOKEN 2499 -- the mechanism type could be parsed, but either the other fields 2500 -- could not be determined from the input_token, or their values 2501 -- did not correspond to valid values for that mechanism. 2502 o GSS_S_FAILURE 2503 -- the mechanism type was missing or corrupted. 2505 Adams Document Expiration: May 1998 45 2507 IDUP_Get_token_details() is used to return to an application the 2508 attributes that correspond to a given input token. Since 2509 IDUP-GSS-API tokens are meant to be opaque to the calling application, 2510 this function allows the application to determine information about 2511 the token without having to violate the opaqueness intention of IDUP. 2512 Of primary importance is the mechanism type, which the application can 2513 then use as input to the IDUP_Establish_Env() call in order to 2514 establish the correct environment in which to have the token 2515 processed. 2517 If all tokens are framed as suggested in Section 3.1 of [RFC-2078] 2518 (mandated in the Kerberos V5 GSS mechanism [RFC 1964] and in the SPKM 2519 GSS Mechanism [RFC 2025]), then any mechanism implementation should 2520 be able to return the mech_type parameter for any uncorrupted input 2521 token. If the mechanism implementation whose IDUP_Get_token_details() 2522 function is being called does recognize the token, it can return any 2523 further relevant information in the other token attributes, as 2524 specified. In particular, this function can set has_SE_protection 2525 if the SE calls may be used to unprotect it, or has_EV_protection 2526 if the EV calls may be used to unprotect it, or both if both kinds 2527 of protection have been applied (so that SE or EV calls may be used 2528 in any order for unprotection) [note that GP calls, when supported, 2529 should be usable for unprotection of any IDUP token]. 2531 IDUP_Get_token_details (which need not be supported by all underlying 2532 mechanisms or implementations) gives only a hint about the content of 2533 the token, there is no integrity check of any kind performed. 2534 Regardless of the token type, it is possible to check that this 2535 information is correct only by doing a proper unprotection of the 2536 token. 2538 The OID of the mechanism and whether the token contains the 2539 associated data is returned. In addition the size of the associated 2540 data, whether inside or outside the token, is included. 2542 When the input token contains only an evidence generated 2543 spontaneously, the following is returned: 2545 - the evidence type; 2546 - the Non-Repudiation policy under which the evidence was generated; 2547 - the name of the generator of the evidence; 2548 - the date and time when the evidence was generated (if available); 2549 - the date and time when it was time stamped (if available). 2551 When the input token contains only an evidence generated in response 2552 to a request from another entity, the following additional 2553 information is returned: 2555 - an indicator to state that this evidence relates to a request; 2556 - a string significant for the requester that will allow him to 2557 check whether the answer corresponds to the requested evidence. 2559 Adams Document Expiration: May 1998 46 2561 When the input token only contains a request, the following is 2562 returned: 2564 - the name of the requestor of the evidence, 2565 - the date and time when the request was made, 2566 - the evidence type to send back, 2567 - the non-repudiation policy under which the evidence to send back 2568 should be generated, 2569 - the names of the recipients which should generate and distribute 2570 the requested evidence, 2571 - the names of the recipients to whom the requested evidence should 2572 be sent after it has been generated. 2574 When the input token contains both evidence and a request, an 2575 indicator is returned describing whether the new evidence should be 2576 generated using only the data in the input token, or using both the 2577 data and the evidence in the input token. 2579 When the input token contains only CONF and DOA services, the 2580 PIDU_Information bundle is returned. Other relevant parameters 2581 (such as idu_size and time_stamping_time) may also be returned if 2582 this data is available. 2584 2.5.4. IDUP_Get_policy_info call 2586 Inputs: 2588 o policy_id OBJECT IDENTIFIER 2590 Outputs: 2592 o major_status INTEGER, 2593 o minor_status INTEGER, 2594 o policy_version INTEGER, 2595 o policy_effective_time INTEGER, 2596 o policy_expiry_time INTEGER, 2597 o supported_services SET OF Service_Descriptor, 2598 o supported_mechanisms SET OF Mechanism_Descriptor 2600 Return major_status codes: 2602 o GSS_S_COMPLETE 2603 -- policy_id recognized; all relevant fields have been returned. 2604 o GSS_S_FAILURE 2605 -- the policy_id was not recognized. 2607 This call (which need not be supported by all underlying mechanisms 2608 or implementations) allows the application to retrieve information 2609 pertaining to a given policy_id. Policies define the following: 2611 - rules for the protection of IDUs, such as trusted third 2612 parties which may be involved in P-IDU generation, the roles 2613 in which they may be involved, and the duration for which the 2614 generated P-IDU is valid; 2616 Adams Document Expiration: May 1998 47 2618 - rules for the unprotection of P-IDUs, such as the interval 2619 during which a trusted third party may legitimately declare its 2620 key to have been compromised or revoked; and 2622 - rules for adjudication, such as which authorities may be used 2623 to adjudicate disputes. 2625 The policy itself may be used by an adjudicator when resolving a 2626 dispute. For example, the adjudicator might refer to the policy to 2627 determine whether the rules for generation of the P-IDU have been 2628 followed. 2630 The following parameter bundles are associated with this call. 2632 o Service_Descriptor PARAMETER BUNDLE, 2633 o service_type OBJECT IDENTIFIER, 2634 o service_validity_duration INTEGER, 2635 o must_use_trusted_time BOOLEAN 2637 o Mechanism_Descriptor PARAMETER BUNDLE, 2638 o mechanism_type OBJECT IDENTIFIER, 2639 o Authority_List PARAMETER BUNDLE, 2640 o maximum_time_skew INTEGER 2641 -- maximum permissible difference between P-IDU generation 2642 -- time and the time of countersignature from a time 2643 -- service (if required). This parameter is unused if 2644 -- trusted time is not required. 2646 o Authority_List PARAMETER BUNDLE, 2647 o authority_name INTERNAL NAME, 2648 o authority_role OCTET STRING, 2649 o last_revocation_check_offset INTEGER 2650 -- may be 0, greater than 0, or less than 0. The value of 2651 -- this parameter is added to P-IDU generation time to 2652 -- get latest time at which the mechanism will check to 2653 -- see if this authority's key has been revoked. 2655 An example of the use of the last parameter in Authority_List is as 2656 follows. If an authority has a defined last_revocation_check_offset 2657 of negative one hour, then all revocations taking effect earlier than 2658 one hour before the generation of a P-IDU will render that P-IDU 2659 invalid; no revocation taking place later than one hour before the 2660 generation of the P-IDU will affect the P-IDU's validity. 2662 Note that both the maximum_time_skew and the 2663 last_revocation_check_offset values are given in minutes. 2665 3. Related Activities 2667 In order to implement the IDUP-GSS-API atop existing, emerging, and 2668 future security mechanisms, the following is necessary: 2670 - object identifiers must be assigned to candidate IDUP-GSS-API 2671 mechanisms and the name types which they support; and 2673 Adams Document Expiration: May 1998 48 2675 - concrete data element (i.e., token and parameter bundle) formats 2676 must be defined for candidate mechanisms. 2678 Calling applications must implement formatting conventions which will 2679 enable them to distinguish IDUP-GSS-API P-IDUs from other 2680 IDUs in their environment. 2682 Concrete language bindings are required for the programming 2683 environments in which the IDUP-GSS-API is to be employed. 2685 4. Acknowledgments 2687 Many thanks are due to Tim Moses and Dhanya Thakkar of Entrust 2688 Technologies, Denis Pinkas of Bull, and David Kurn of Tandem 2689 Computers for a number of helpful comments and contributions. 2691 5. Security Considerations 2693 Security issues are discussed throughout this memo. 2695 6. REFERENCES 2697 [MSP]: U.S. National Security Agency, "Message Security 2698 Protocol", Secure Data Network System SDN.701, March 1994. 2700 [RFC-1421]: J. Linn, "Privacy Enhancement for Internet Electronic 2701 Mail: Part I: Message Encryption and Authentication Procedures", 2702 RFC 1421. 2704 [RFC-2078]: J. Linn, "Generic Security Service Application Program 2705 Interface, Version 2", RFC 2078. 2707 [RFC 1964]: J. Linn, "The Kerberos Version 5 GSS-API Mechanism", 2708 RFC 1964. 2710 [RFC 2025]: C. Adams, "The Simple Public-Key GSS-API Mechanism 2711 (SPKM)", RFC 2025. 2713 [ISO/IEC]: 2nd ISO/IEC CD 13888-1, "Information technology - 2714 Security techniques - Non-repudiation - Part 1: General Model", 2715 ISO/IEC JTC 1/SC 27, May 30, 1995 2717 7. Author's Address 2719 Carlisle Adams 2720 Entrust Technologies 2721 750 Heron Road, Suite E08, 2722 Ottawa, Ontario, CANADA K1V 1A7 2724 Phone: +1 613.763.9008 2725 E-mail: cadams@entrust.com 2727 Adams Document Expiration: May 1998 49 2729 APPENDIX A: MECHANISM-INDEPENDENT TOKEN FORMAT 2731 This appendix specifies the use, for IDUP-GSS-API tokens, of the 2732 mechanism-independent level of encapsulating representation for 2733 tokens given in Section 3.1 of GSS-API [RFC-2078]. The 2734 representation given there incorporates an identifier of the 2735 mechanism type to be used when processing the associated tokens. 2736 Use of that octet format is recommended to the designers of 2737 IDUP-GSS-API implementations based on various mechanisms so that 2738 tokens can be interpreted unambiguously at IDUP-GSS-API peers. It is 2739 recognized, however, that for interoperability purposes with peers 2740 not using IDUP for specific IDU protection/unprotection protocols, 2741 the encapsulating representation may need to be omitted. 2743 For purely descriptive purposes, the following simple ASN.1 structure 2744 is used to illustrate the structural relationships among token and 2745 tag objects. For interoperability purposes, token and tag encoding 2746 shall be performed using the concrete encoding procedures described 2747 in Section 3.1 of GSS-API [RFC-2078]. 2749 -- top-level token definition to frame different mechanisms 2751 IDUP-GSS-API DEFINITIONS ::= 2752 BEGIN 2753 MechType ::= OBJECT IDENTIFIER 2755 Token ::= [APPLICATION 0] IMPLICIT SEQUENCE { 2756 thisMech MechType, 2757 token ANY DEFINED BY thisMech 2758 -- contents mechanism-specific 2759 } 2760 END 2762 Adams Document Expiration: May 1998 50 2764 APPENDIX B: EXAMPLES OF IDUP USE 2766 This appendix provides examples of the use of IDUP to do IDU protec- 2767 tion and unprotection. It should not be regarded as constrictive to 2768 implementations or as defining the only means through which 2769 IDUP-GSS-API functions can be realized with particular underlying 2770 technology, and does not demonstrate all IDUP-GSS-API features. 2772 Most of the examples below only illustrate the use of CONF/DOA 2773 protection services. Note that when both CONF/DOA and Evidence 2774 services are required, calling applications may use a series of 2775 SE and EV calls, or may use the GP calls (when these are supported). 2776 Using the former approach implies multiple calls (e.g., the SE calls 2777 are used to protect some data and the resulting token is then input 2778 to the EV calls to add evidence information), but some callers may 2779 find this to be more attractive than coding to the GP calls because 2780 of the simpler SE/EV interface. Depending upon the underlying 2781 mechanism, the series of SE/EV calls may result in a single token 2782 that can be unprotected using the SE and EV calls in any order (for 2783 example, because it is a single ASN.1 SEQUENCE that incorporates 2784 all the specified protection services at one level), or 2785 the series may result in a token that can only be unprotected in the 2786 reverse order of protection (for example, because each SE/EV output 2787 token was effectively embedded in the token of the subsequent call). 2788 The IDUP_Get_token_details call can assist callers in determining 2789 how to unprotect any received token. 2791 B.1. Simple Mechanism, Single Buffer 2793 To illustrate the simplest possible case, consider an underlying IDUP 2794 mechanism which does straightforward encryption/decryption and 2795 signing/verification only using public-key techniques; none of the 2796 other possible services, such as creation of proof-of-origin 2797 evidence, requests for proof-of-delivery evidence, or use of trusted 2798 time, are supported. PEM[RFC-1421] is one example of a mechanism 2799 which fits this description. Furthermore (again for simplicity), 2800 assume that encapsulation is chosen by the calling application during 2801 IDU protection. 2803 Such a mechanism would likely use the "SE" set of IDUP-GSS-API calls. 2804 The following parameter bundle uses and defaults would therefore be 2805 specified in the relevant IDUP mechanism document. 2807 SENDER: 2809 Set 2810 env_handle = environment handle in use; 2811 idu_buffer = data buffer; 2812 Target_Info.targ_names = receiver names; 2813 Protect_Options = as necessary; 2815 Call 2816 IDUP_SE_SingleBuffer_Protect() with above input parameters 2818 Adams Document Expiration: May 1998 51 2820 Check 2821 major_status. If not GSS_S_COMPLETE, check 2822 minor_status, 2823 Target_Info.Bad_Targ_Name, 2824 (as required) for more detailed information. 2826 Send 2827 Output parameter pidu_buffer to receiver. 2829 RECEIVER (any parameters not listed below are given the value NULL): 2831 Set 2832 env_handle = environment handle in use; 2833 pidu_buffer = received data buffer; 2835 Call 2836 IDUP_SE_SingleBuffer_Unprotect() with above input parameters 2837 Check 2838 major_status. If not GSS_S_COMPLETE, check 2839 minor_status, 2840 (as required) for more detailed information 2842 Utilize 2843 PIDU_Information.Protect_Options.Protect_Operation, 2844 (to determine which services were applied by the originator) 2845 PIDU_Information.Protect_Options.sign_qop_alg / enc_qop_alg, 2846 (to determine the corresponding qualities of the services) 2847 Prot_Information.originator_name, 2848 (to determine the name of the originator) 2849 Prot_Information.protection_time, 2850 (to determine when the IDU was protected) 2851 idu_buffer 2852 (to retrieve the unprotected data). 2854 B.2. Simple Mechanism, Single Buffer (Again) 2856 To illustrate a slight variation on the simplest possible case, 2857 assume that everything is as in the previous scenario except that 2858 the "GP" calls are used. 2860 The following parameter bundle uses and defaults would therefore be 2861 specified in the relevant IDUP mechanism document. 2863 Mech_Specific_Info 2864 - NOT USED (the only acceptable input, therefore, is NULL) 2866 Idu_Sensitivity 2867 - NOT USED (the only acceptable input, therefore, is NULL) 2869 Service_Creation_Info 2870 - NOT USED (the only acceptable input, therefore, is NULL) 2872 Service_Verification_Info 2873 - NOT USED (the only acceptable input, therefore, is NULL) 2875 Adams Document Expiration: May 1998 52 2877 Quality 2878 - the qop_algs parameter must be supported, with a suitable 2879 DEFAULT value specified; 2880 - suitable DEFAULT values for validity, policy_id, and 2881 allow_policy_mapping must be specified (it may be an 2882 implementation option as to whether these parameters are 2883 explicitly modifiable by the calling application, or whether 2884 NULLs are the only acceptable input) 2886 Idu_Information 2887 - the idu_type parameter must have a value representing a suitable 2888 IDU type (for example, in PEM a value representing the string 2889 "RFC822" or some other valid "Content-Domain" would be used), 2890 with a suitable DEFAULT value specified; 2891 - the idu_title parameter is NOT USED (the only acceptable input, 2892 therefore, is NULL) 2894 Prot_Information 2895 - the originator_name and idu_type (in Idu_Information) parameters 2896 are read from the encapsulating information and output by 2897 IDUP_Start_Unprotect; 2898 - all other parameters are NOT USED (and therefore NULL) 2900 Special_Conditions 2901 - NOT USED (the only acceptable input, therefore, is NULL) 2903 Target_Info 2904 - this bundle is used as described in IDUP; no DEFAULT values are 2905 specified 2907 General_Service_Data 2908 - the unencapsulated_token parameter is used if 2909 encapsulation_request is FALSE; 2910 - the minor_status parameter is used to return minor status values 2911 as specified by the mechanism document 2913 Prot_Service 2914 - the prot_service_type parameter may have a value of "1" 2915 ("perform unsolicited service") or NULL (which specifies the 2916 DEFAULT value of "1"); 2917 - the service_id parameter must have a value representing 2918 "PER_CONF" or "PER_DOA"; 2919 - the parameters Service_Creation_Info, service_to, 2920 Service_Verification_Info, and service_verification_info_id are 2921 NOT USED (and therefore NULL) 2923 Unprot_Service 2924 - the unprot_service_type parameter will always have a value of 2925 "1" ("receive unsolicited service"); 2926 - the service_id parameter will have a value representing 2927 "REC_CONF" or "REC_DOA"; 2928 - the parameters service_verification_info_id, 2929 Service_Verification_Info, service_to, and 2930 Service_Creation_Info, are NOT USED (and therefore NULL) 2932 Adams Document Expiration: May 1998 53 2934 Assuming that the calling application has only a single buffer of 2935 data to protect/unprotect, the following sequence of operations must 2936 be performed by the sender and receivers (subsequent to environment 2937 establishment). 2939 SENDER (any parameters not listed below are given the value NULL): 2941 Set 2942 env_handle = environment handle in use; 2943 encapsulation_request = TRUE; 2944 single_idu_buffer = data buffer; 2945 Target_Info.targ_names = receiver names; 2946 P_Services.Prot_Service_1.service_id = PER_CONF; 2947 P_Services.Prot_Service_2.service_id = PER_DOA; 2949 Call 2950 IDUP_Start_Protect() with above input parameters 2951 Check 2952 major_status. If not GSS_S_COMPLETE, check 2953 minor_status, 2954 Target_Info.bad_targ_names / Target_Info.bad_targ_status, 2955 P_Services.Prot_Service_1.General_Service_Data.minor_status, 2956 P_Services.Prot_Service_2.General_Service_Data.minor_status 2957 (as required) for more detailed information. 2959 Send 2960 Output parameter pidu_buffer to receiver. 2962 RECEIVER (any parameters not listed below are given the value NULL): 2964 Set 2965 env_handle = environment handle in use; 2966 single_pidu_buffer = received data buffer; 2968 Call 2969 IDUP_Start_Unprotect() with above input parameters 2970 Check 2971 major_status. If not GSS_S_COMPLETE, check 2972 minor_status, 2973 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 2974 R_Services.Unprot_Service_2.General_Service_Data.minor_status 2975 (as required) for more detailed information 2977 Utilize 2978 R_Services.Unprot_Service_1/2.service_id, 2979 (to determine which services were applied by the originator) 2980 R_Services.Unprot_Service_1/2.Quality, 2981 (to determine the corresponding qualities of the services) 2982 Prot_Information.originator_name, 2983 (to determine the name of the originator) 2984 single_idu_buffer 2985 (to retrieve the unprotected data). 2987 Adams Document Expiration: May 1998 54 2989 B.3. Simple Mechanism, Multiple Buffers 2991 To illustrate the next step up in complexity, consider the use of the 2992 simple IDUP mechanism described in B.2 above with multiple data 2993 buffers. In particular, consider the case in which a large data file 2994 is to be signed. For this example, assume that the calling 2995 application does not wish to use encapsulation. 2997 Note that the parameter bundle uses and defaults are as specified in 2998 B.2. above. 3000 SENDER (any parameters not listed below are given the value NULL): 3002 Set 3003 env_handle = environment handle in use; 3004 encapsulation_request = FALSE; 3005 P_Services.Prot_Service.service_id = PER_DOA; 3007 Call 3008 IDUP_Start_Protect() with above input parameters 3009 Check 3010 major_status. If not GSS_S_COMPLETE, check 3011 minor_status, 3012 P_Services.Prot_Service.General_Service_Data.minor_status 3013 (as required) for more detailed information. 3015 For each buffer of input data: 3016 Set 3017 input_buffer = buffer 3018 Call 3019 IDUP_Protect() with above input parameter 3020 Check 3021 major_status. If not GSS_S_COMPLETE, check 3022 minor_status 3024 Call 3025 IDUP_End_Protect() 3026 Check 3027 major_status. If not GSS_S_COMPLETE, check 3028 minor_status, 3029 P_Services.Prot_Service.General_Service_Data.minor_status 3030 (as required) for more detailed information. 3032 Send 3033 P_Services.Prot_Service.General_Service_Data.unencapsulated_token, 3034 and the file for which the signature was calculated (if required), 3035 to receiver. 3037 Adams Document Expiration: May 1998 55 3039 RECEIVER (any parameters not listed below are given the value NULL): 3041 Set 3042 env_handle = environment handle in use; 3043 R_Services.Unprot_Service_1.General_Service_Data. 3044 unencapsulated_token = received unencapsulated token; 3046 Call 3047 IDUP_Start_Unprotect() with above input parameters 3048 Check 3049 major_status. If not GSS_S_COMPLETE, check 3050 minor_status, 3051 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 3052 (as required) for more detailed information 3054 For each buffer of input data: 3055 Set 3056 input_buffer = buffer 3057 Call 3058 IDUP_Unprotect() with above input parameter 3059 Check 3060 major_status. If not GSS_S_COMPLETE, check 3061 minor_status 3063 Call 3064 IDUP_End_Unprotect() 3065 Check 3066 major_status. If not GSS_S_COMPLETE, check 3067 minor_status, 3068 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 3069 (as required) for more detailed information. 3071 Utilize 3072 R_Services.Unprot_Service_1.service_id, 3073 (to determine which service was applied by the originator; note 3074 that Unprot_Service_2 will have NULL in unprot_service_type 3075 to indicate that it is not used) 3076 R_Services.Unprot_Service_1.Quality, 3077 (to determine the corresponding quality of the service) 3078 Prot_Information.originator_name, (from IDUP_Start_Unprotect) 3079 (to determine the name of the signer) 3080 major_status (from IDUP_End_Unprotect) 3081 (to determine pass/fail status of signature verification). 3083 Adams Document Expiration: May 1998 56 3085 B.4. More Sophisticated Mechanism, Small Application Buffers 3087 To illustrate a higher level of complexity, consider the use of a 3088 more sophisticated IDUP mechanism and a calling application with 3089 small data buffers. In particular, consider the case in which a very 3090 small e-mail message is to be encrypted for a relatively large 3091 receiver list (R), some subset of whom (r) will be asked to send 3092 proofs of receipt of the message to some other subset (L) (which 3093 includes the originator). So that the example is not unnecessarily 3094 complicated, assume again that the originating application uses 3095 encapsulation. 3097 The uses and defaults for the various parameter bundles for this 3098 mechanism would be specified in the relevant IDUP mechanism document 3099 as follows. 3101 Mech_Specific_Info 3102 - NOT USED (the only acceptable input, therefore, is NULL) 3104 Idu_Sensitivity 3105 - NOT USED (the only acceptable input, therefore, is NULL) 3107 Service_Creation_Info 3108 - used to create "proof of delivery" evidence (but actual 3109 structure is opaque to calling application) 3111 Service_Verification_Info 3112 - used to verify "proof of delivery" evidence (but actual 3113 structure is opaque to calling application) 3115 Quality 3116 - the qop_algs parameter must be supported, with a suitable 3117 DEFAULT value specified; 3118 - suitable DEFAULT values for validity, policy_id, and 3119 allow_policy_mapping must be specified (it may be an 3120 implementation option as to whether these parameters are 3121 explicitly modifiable by the calling application, or whether 3122 NULLs are the only acceptable input) 3124 Idu_Information 3125 - the idu_type parameter must have a value representing a suitable 3126 IDU type, with a suitable DEFAULT value specified; 3127 - the idu_title parameter must have a value representing a 3128 suitable IDU title, with a suitable DEFAULT value specified 3130 Prot_Information 3131 - the originator_name, protection_time, and idu_type / idu_title 3132 (in Idu_Information) parameters are read from the contained 3133 header information and output by IDUP_Start_Unprotect; 3135 Special_Conditions 3136 - the parameter prot_oper_id is NOT USED (the only acceptable 3137 input, therefore, is NULL); 3138 - trusted or untrusted time may be selected by the calling 3139 application, with a suitable DEFAULT value specified 3141 Adams Document Expiration: May 1998 57 3143 Target_Info 3144 - this bundle is used as described in IDUP; no DEFAULT values are 3145 specified 3147 General_Service_Data 3148 - the unencapsulated_token parameter is used if 3149 encapsulation_request is FALSE; 3150 - the minor_status parameter is used to return minor status values 3151 as specified by the mechanism document 3153 Prot_Service 3154 - the prot_service_type parameter may have a value of "1" 3155 ("perform unsolicited service"), "2" ("perform solicited 3156 service"), "3" (perform service solicitation), or NULL (which 3157 specifies the DEFAULT value of "1"); 3158 - the service_id parameter must have a value representing 3159 "PER_CONF", "PER_DOA", "PER_POO", or "PER_POD"; 3160 - the parameters Service_Creation_Info, service_to, 3161 Service_Verification_Info, and service_verification_info_id are 3162 used when required by the IDUP operation 3164 Unprot_Service 3165 - the unprot_service_type parameter may have a value of "1" 3166 ("receive unsolicited service"), "2" ("receive solicited 3167 service"), or "3" (receive service solicitation); 3168 - the service_id parameter will have a value representing 3169 "REC_CONF", "REC_DOA", "REC_POO", or "REC_POD"; 3170 - the parameters service_verification_info_id, 3171 Service_Verification_Info, service_to, and 3172 Service_Creation_Info, are used when required by the IDUP 3173 operation 3175 SENDER (any parameters not listed below are given the value NULL): 3177 Set 3178 env_handle = environment handle in use; 3179 Idu_Information.idu_type = value for "e-mail document"; 3180 Idu_Information.idu_title = "Contract 1234"; 3181 Special_Conditions.use_trusted_time = TRUE; 3182 encapsulation_request = TRUE; 3183 single_idu_buffer = very small e-mail message; 3184 Target_Info.targ_names = receiver names (R); 3185 Prot_Service_1.prot_service_type = "1"; 3186 Prot_Service_1.service_id = PER_CONF; 3187 Prot_Service_2.prot_service_type = "3"; 3188 Prot_Service_2.service_id = PER_POD; 3189 Prot_Service_2.General_Service_Data.Target_Info.targ_names 3190 = "receipts from" list (r); 3191 Prot_Service_2.service_to = "receipts to" list (L); 3192 P_Services.Prot_Service_1 = Prot_Service_1; 3193 P_Services.Prot_Service_2 = Prot_Service_2; 3195 Adams Document Expiration: May 1998 58 3197 Call 3198 IDUP_Start_Protect() with above input parameters 3199 Check 3200 major_status. If not GSS_S_COMPLETE, 3201 while major_status == IDUP_S_MORE_OUTBUFFER_NEEDED 3202 Save 3203 pidu_buffer, 3204 Call 3205 IDUP_Start_Protect() (to get next portion of pidu_buffer) 3206 Check 3207 major_status, 3208 minor_status, 3209 Target_Info.bad_targ_names / Target_Info.bad_targ_status, 3210 P_Services.Prot_Service_1.General_Service_Data.minor_status, 3211 P_Services.Prot_Service_2.General_Service_Data.minor_status 3212 (as required) for more detailed information. 3214 Save 3215 Prot_Service_2.Service_Verification_Info, 3216 Prot_Service_2.service_verification_info_id 3218 Send 3219 All saved buffers of pidu_buffer to receiver list (R). 3221 RECEIVER (ON RECEIVER LIST (R)): 3222 (any parameters not listed below are given the value NULL) 3224 Set 3225 env_handle = environment handle in use; 3226 partial_pidu_buffer = initial buffer of received p-idu; 3228 Call 3229 IDUP_Start_Unprotect() with above input parameters 3230 While major_status == IDUP_S_MORE_PIDU_NEEDED, 3231 Set 3232 partial_pidu_buffer = next buffer of p-idu 3233 Call 3234 IDUP_Start_Unprotect() 3235 Check 3236 major_status, 3237 minor_status, 3238 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 3239 R_Services.Unprot_Service_2.General_Service_Data.minor_status, 3240 (as required) for more detailed information 3242 Save 3243 initial_idu_buffer (if non-empty) 3245 Adams Document Expiration: May 1998 59 3247 Set 3248 input_buffer = remaining p-idu buffer 3249 Call 3250 IDUP_Unprotect() with above input parameter 3251 Check 3252 major_status. If not GSS_S_COMPLETE, check 3253 minor_status 3254 Save 3255 output_buffer 3257 Call 3258 IDUP_End_Unprotect() 3259 Check 3260 major_status. If not GSS_S_COMPLETE, check 3261 minor_status, 3262 R_Services.Unprot_Service_1.General_Service_Data.minor_status, 3263 R_Services.Unprot_Service_2.General_Service_Data.minor_status, 3264 (as required) for more detailed information. 3266 Utilize 3267 R_Services.Unprot_Service_1/2.service_id, 3268 (to determine which services were applied by the originator) 3269 R_Services.Unprot_Service_1/2.Quality, 3270 (to determine the corresponding qualities of the service) 3271 Prot_Information.originator_name/protection_time and 3272 Prot_Information.Idu_Information.idu_type/idu_title, 3273 (from IDUP_Start_Unprotect) (to determine originator info.) 3274 R_Services.Unprot_Service_2.General_Service_Data.Target_Info. 3275 targ.names, (to determine if rec. is in "receipts from" (r)) 3276 Service_Verification_Info/service_verification_info_id 3277 (to determine if receiver is in "receipts to" list (L)) 3279 If receiver is in "receipts from" list (r) 3280 Save 3281 R_Services.Unprot_Service_2.service_to, 3282 R_Services.Unprot_Service_2.Service_Creation_Info 3284 If receiver is in "receipts to" list (L) 3285 Save 3286 Service_Verification_Info, 3287 service_verification_info_id 3289 Adams Document Expiration: May 1998 60 3291 RECEIVER (ON "RECEIPTS FROM" LIST (r)): 3292 (procedure to generate receipt) 3294 Set 3295 env_handle = environment handle in use; 3296 Target_Info.targ_names = service_to 3297 Prot_Service_1.prot_service_type = "2"; 3298 Prot_Service_1.service_id = "PER_POD"; 3299 Prot_Service_1.Service_Creation_Info = Service_Creation_Info; 3300 P_Services.Prot_Service_1 = Prot_Service_1 3302 Call 3303 IDUP_Start_Protect() with above input parameters 3304 Check 3305 major_status. If not GSS_S_COMPLETE, check 3306 minor_status, 3307 P_Services.Prot_Service_1.General_Service_Data.minor_status 3308 (as required) for more detailed information. 3310 Send 3311 pidu_buffer to "receipts to" list (L) 3313 RECEIVER (ON "RECEIPTS TO" LIST (L)): 3314 (procedure to process received receipt) 3316 Set 3317 env_handle = environment handle in use; 3318 single_pidu_buffer = received p-idu buffer (if it fits in a single 3319 buffer; otherwise use partial_pidu_buffer and make multiple 3320 calls, as above) 3322 Call 3323 IDUP_Start_Unprotect() with above input parameters 3324 If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED 3325 Utilize 3326 R_Services.Unprot_Service_1.service_verification_info.id 3327 (to assist in locating necessary Service_Verification_Info) 3328 Set 3329 R_Services.Unprot_Service_1.Service_Verification_Info 3330 = Service_Verification_Info 3331 Call 3332 IDUP_Start_Unprotect() with above input parameters 3333 Check 3334 major_status, 3335 minor_status, 3336 R_Services.Unprot_Service_1.General_Service_Data.minor_status 3337 (as required) for more detailed information. 3339 Utilize 3340 R_Services.Unprot_Service_1.service_id, 3341 (to determine that this is a "proof of delivery" evidence) 3342 R_Services.Unprot_Service_1.Quality, 3343 Prot_Information.originator_name, (for evidence generator info.) 3344 major_status (to determine pass/fail status of evi. verif.). 3346 Adams Document Expiration: May 1998 61