| blob | 8413bcaeb33418a65fd2d21d4bf10de82cb0cec9 |
7 Network Working Group C. Adams
8 Request for Comments: 2479 Entrust Technologies
9 Category: Informational December 1998
12 Independent Data Unit Protection Generic Security Service
13 Application Program Interface (IDUP-GSS-API)
15 Status of this Memo
17 This memo provides information for the Internet community. It does
18 not specify an Internet standard of any kind. Distribution of this
19 memo is unlimited.
21 Copyright Notice
23 Copyright (C) The Internet Society (1998). All Rights Reserved.
25 ABSTRACT
27 The IDUP-GSS-API extends the GSS-API [RFC-2078] for applications
28 requiring protection of a generic data unit (such as a file or
29 message) in a way which is independent of the protection of any other
30 data unit and independent of any concurrent contact with designated
31 "receivers" of the data unit. Thus, it is suitable for applications
32 such as secure electronic mail where data needs to be protected
33 without any on-line connection with the intended recipient(s) of that
34 data. The protection offered by IDUP includes services such as data
35 origin authentication with data integrity, data confidentiality with
36 data integrity, and support for non-repudiation services. Subsequent
37 to being protected, the data unit can be transferred to the
38 recipient(s) - or to an archive - perhaps to be processed
39 ("unprotected") only days or years later.
41 Throughout the remainder of this document, the "unit" of data
42 described in the above paragraph will be referred to as an IDU
43 (Independent Data Unit). The IDU can be of any size (the application
44 may, if it wishes, split the IDU into pieces and have the protection
45 computed a piece at a time, but the resulting protection token
46 applies to the entire IDU). However, the primary characteristic of
47 an IDU is that it represents a stand-alone unit of data whose
48 protection is entirely independent of any other unit of data. If an
49 application protects several IDUs and sends them all to a single
50 receiver, the IDUs may be unprotected by that receiver in any order
51 over any time span; no logical connection of any kind is implied by
52 the protection process itself.
58 Adams Informational [Page 1]
59 \f
60 RFC 2479 IDUP-GSS-API December 1998
63 As with RFC-2078, this IDUP-GSS-API definition provides security
64 services to callers in a generic fashion, supportable with a range of
65 underlying mechanisms and technologies and hence allowing source-
66 level portability of applications to different environments. This
67 specification defines IDUP-GSS-API services and primitives at a level
68 independent of underlying mechanism and programming language
69 environment, and is to be complemented by other, related
70 specifications:
72 - documents defining specific parameter bindings for particular
73 language environments;
74 - documents defining token formats, protocols, and procedures to
75 be implemented in order to realize IDUP-GSS-API services atop
76 particular security mechanisms.
78 TABLE OF CONTENTS
80 1. IDUP-GSS-API Characteristics and Concepts .................. 3
81 1.1. IDUP-GSS-API Constructs .................................. 5
82 1.1.1. Credentials ............................................ 5
83 1.1.2. Tokens ................................................. 5
84 1.1.3. Security Environment ................................... 6
85 1.1.4. Mechanism Types ........................................ 6
86 1.1.5. Naming ................................................. 6
87 1.1.6. Channel Bindings ....................................... 6
88 1.2. IDUP-GSS-API Features and Issues ......................... 6
89 1.2.1. Status Reporting ....................................... 6
90 1.2.2. Per-IDU Security Service Availability .................. 9
91 1.2.3. Per-IDU Replay Detection and Sequencing ................ 9
92 1.2.4. Quality of Protection .................................. 9
93 1.2.5. The Provision of Time .................................. 12
94 2. Interface Descriptions ..................................... 13
95 2.1. Credential management calls .............................. 14
96 2.1.1. Relationship to GSS-API ................................ 14
97 2.2. Environment-level calls .................................. 15
98 2.2.1. Relationship to GSS-API ................................ 15
99 2.2.2. IDUP_Establish_Env call ................................ 15
100 2.2.3. IDUP_Abolish_Env call .................................. 19
101 2.2.4. IDUP_Inquire_Env call .................................. 19
102 2.3. Per-IDU protection/unprotection calls .................... 20
103 2.3.1. Relationship to GSS-API ................................ 20
104 2.3.2. The "SE" Calls ......................................... 21
105 2.3.3. The "EV" Calls ......................................... 27
106 2.3.4. The "GP" Calls ......................................... 36
107 2.4. Special-Purpose calls .................................... 47
108 2.4.1. Relationship to GSS-API ................................ 47
109 2.4.2. IDUP_Form_Complete_PIDU ................................ 48
110 2.5. Support calls ............................................ 49
114 Adams Informational [Page 2]
115 \f
116 RFC 2479 IDUP-GSS-API December 1998
119 2.5.1. Relationship to GSS-API ................................ 49
120 2.5.2. IDUP_Acquire_Cred_With_Auth ............................ 49
121 2.5.3. IDUP_Get_Token_Details ................................. 50
122 2.5.4. IDUP_Get_Policy_Info ................................... 53
123 2.5.5. IDUP_Cancel_Multibuffer_Op ............................. 55
124 3. Related Activities ......................................... 55
125 4. Acknowledgments ............................................ 56
126 5. Security Considerations .................................... 56
127 6. References ........................................... 56
128 7. Author's Address ........................................... 56
129 Appendix A Mechanism-Independent Token Format ................. 57
130 Appendix B Examples of IDUP Use ............................... 58
131 Full Copyright Statement ....................................... 70
133 1. IDUP-GSS-API Characteristics and Concepts
135 The paradigm within which IDUP-GSS-API operates is as follows. An
136 IDUP-GSS-API caller is any application that works with IDUs, calling
137 on IDUP-GSS-API in order to protect its IDUs with services such as
138 data origin authentication with integrity (DOA), confidentiality with
139 integrity (CONF), and/or support for non-repudiation (e.g., evidence
140 generation, where "evidence" is information that either by itself, or
141 when used in conjunction with other information, is used to establish
142 proof about an event or action (note: the evidence itself does not
143 necessarily prove truth or existence of something, but contributes to
144 establish proof) -- see [ISO/IEC] for fuller discussion regarding
145 evidence and its role in various types of non-repudiation). An
146 IDUP-GSS-API caller passes an IDU to, and accepts a token from, its
147 local IDUP-GSS-API implementation, transferring the resulting
148 protected IDU (P-IDU) to a peer or to any storage medium. When a P-
149 IDU is to be "unprotected", it is passed to an IDUP-GSS-API
150 implementation for processing. The security services available
151 through IDUP-GSS-API in this fashion are implementable over a range
152 of underlying mechanisms based on secret-key and/or public-key
153 cryptographic technologies.
155 During the protection operation, the input IDU buffers may be
156 modified (for example, the data may be encrypted or encoded in some
157 way) or may remain unchanged. In any case, the result is termed a
158 "M-IDU" (Modified IDU) in order to distinguish it from the original
159 IDU. Depending on the desire of the calling application and the
160 capabilities of the underlying IDUP mechanism, the output produced by
161 the protection processing may or may not encapsulate the M-IDU. Thus,
162 the P-IDU may be the contents of a single output parameter (if
163 encapsulation is done) or may be the logical concatenation of an
164 unencapsulated token parameter and a M-IDU parameter (if
165 encapsulation is not done). In the latter case, the protecting
166 application may choose whatever method it wishes to concatenate or
170 Adams Informational [Page 3]
171 \f
172 RFC 2479 IDUP-GSS-API December 1998
175 combine the unencapsulated token and the M-IDU into a P-IDU, provided
176 the unprotecting application knows how to de-couple the P-IDU back
177 into its component parts prior to calling the IDUP unprotection set
178 of functions.
180 It is expected that any output buffer returned by IDUP (i.e., P-IDU
181 or portion thereof) is ready for immediate transmission to the
182 intended receiver(s) by the calling application, if this is desired.
183 In other words, an application wishing to transmit data buffers as
184 they appear from IDUP should not be unduly restricted from doing so
185 by the underlying mechanism.
187 The IDUP-GSS-API separates the operation of initializing a security
188 environment (the IDUP_Establish_Env() call) from the operations of
189 providing per-IDU protection, for IDUs subsequently protected in
190 conjunction with that environment. Per-IDU protection and
191 unprotection calls provide DOA, CONF, evidence, and other services,
192 as requested by the calling application and as supported by the
193 underlying mechanism.
195 The following paragraphs provide an example illustrating the
196 dataflows involved in the use of the IDUP-GSS-API by the sender and
197 receiver of a P-IDU in a mechanism-independent fashion. The example
198 assumes that credential acquisition has already been completed by
199 both sides. Furthermore, the example does not cover all possible
200 options available in the protection/unprotection calls.
202 The sender first calls IDUP_Establish_Env() to establish a
203 security environment. Then, for the IDU to be protected the
204 sender calls the appropriate protection calls (SE, EV, or GP) to
205 perform the IDU protection. The resulting P-IDU, which may
206 (depending on whether or not encapsulation was chosen/available)
207 be either the token itself or the logical concatenation of the
208 token and the M-IDU, is now ready to be sent to the target. The
209 sender then calls IDUP_Abolish_Env() to flush all environment-
210 specific information.
212 The receiver first calls IDUP_Establish_Env() to establish a
213 security environment in order to unprotect the P-IDU. Then, for
214 the received P-IDU the receiver calls the appropriate unprotection
215 calls (SE, EV, or GP (known a priori, or possibly determined
216 through the use of the IDUP_Get_token_details call)) to perform
217 the P-IDU unprotection. The receiver then calls
218 IDUP_Abolish_Env() to flush all environment-specific information.
220 It is important to note that absolutely no synchronization is implied
221 or expected between the data buffer size used by the sender as input
222 to the protection calls, the data buffer size used by the receiver as
226 Adams Informational [Page 4]
227 \f
228 RFC 2479 IDUP-GSS-API December 1998
231 input to the unprotection calls, and the block sizes required by the
232 underlying protection algorithms (integrity and confidentiality). All
233 these sizes are meant to be independent; furthermore, the data buffer
234 sizes used for the protection and unprotection calls are purely a
235 function of the local environment where the calls are made.
237 The IDUP-GSS-API design assumes and addresses several basic goals,
238 including the following.
240 Mechanism independence: The IDUP-GSS-API defines an interface to
241 cryptographically implemented security services at a generic level
242 which is independent of particular underlying mechanisms. For
243 example, IDUP-GSS-API-provided services can be implemented by
244 secret-key technologies or public-key approaches.
246 Protocol environment independence: The IDUP-GSS-API is independent
247 of the communications protocol suites which may be used to
248 transfer P-IDUs, permitting use in a broad range of protocol
249 environments.
251 Protocol association independence: The IDUP-GSS-API's security
252 environment construct has nothing whatever to do with
253 communications protocol association constructs, so that IDUP-GSS-
254 API services can be invoked by applications, wholly independent of
255 protocol associations.
257 Suitability for a range of implementation placements: IDUP-GSS-API
258 clients are not constrained to reside within any Trusted Computing
259 Base (TCB) perimeter defined on a system where the IDUP-GSS-API is
260 implemented; security services are specified in a manner suitable
261 for both intra-TCB and extra-TCB callers.
263 1.1. IDUP-GSS-API Constructs
265 This section describes the basic elements comprising the IDUP-GSS-
266 API.
268 1.1.1. Credentials
270 Credentials in IDUP-GSS-API are to be understood and used as
271 described in GSS-API [RFC-2078].
273 1.1.2. Tokens
275 Tokens in IDUP-GSS-API are to be understood and used as described in
276 GSS-API [RFC-2078] with the exception that there are no context-level
277 tokens generated by IDUP-GSS-API. The IDUP-GSS-API token may
278 (depending on the underlying mechanism) encapsulate the M-IDU or may
282 Adams Informational [Page 5]
283 \f
284 RFC 2479 IDUP-GSS-API December 1998
287 be logically concatenated with the M-IDU prior to transfer to a
288 target; furthermore, for some evidence services the token may be sent
289 independently of any other data transfer.
291 1.1.3. Security Environment
293 The "security environment" in IDUP-GSS-API is entirely different from
294 the concept of security contexts used in GSS-API [RFC-2078]. Here, a
295 security environment exists within a calling application (that is, it
296 is purely local to the caller) for the purpose of protecting or
297 unprotecting one or more IDUs using a particular caller credential or
298 set of credentials. In GSS-API, on the other hand, a security
299 context exists between peers (the initiator and the target) for the
300 purpose of protecting, in real time, the data that is exchanged
301 between them. Although they are different concepts, the env_handle
302 in IDUP-GSS-API is similar to the context_handle in GSS-API in that
303 it is a convenient way of tying together the entire process of
304 protecting or unprotecting one or more IDUs using a particular
305 underlying mechanism. As with the GSS-API security contexts, a
306 caller can initiate and maintain multiple environments using the same
307 or different credentials.
309 1.1.4. Mechanism Types
311 Mechanism types in IDUP-GSS-API are to be understood and used as
312 described in GSS-API [RFC-2078].
314 1.1.5. Naming
316 Naming in IDUP-GSS-API is to be understood and used as described in
317 GSS-API [RFC-2078].
319 1.1.6. Channel Bindings
321 The concept of channel bindings discussed in GSS-API [RFC-2078] is
322 not relevant to the IDUP-GSS-API.
324 1.2. IDUP-GSS-API Features and Issues
326 This section describes aspects of IDUP-GSS-API operations and of the
327 security services which the IDUP-GSS-API provides. It also provides
328 commentary on design issues.
330 1.2.1. Status Reporting
332 Status reporting in IDUP-GSS-API is to be understood and used as
333 described in GSS-API [RFC-2078], with the addition of a number of
334 IDUP-specific status codes. Descriptions of the major_status codes
338 Adams Informational [Page 6]
339 \f
340 RFC 2479 IDUP-GSS-API December 1998
343 used in IDUP are provided in Table 1. Codes that are informatory
344 (i.e., that do not cause the requested operation to fail) are
345 indicated with the symbol "(I)".
347 As with GSS-API, minor_status codes, which provide more detailed
348 status information than major_status codes, and which may include
349 status codes specific to the underlying security mechanism, are not
350 specified in this document.
352 Table 1: IDUP-GSS-API Major Status Codes
354 GSS_S_BAD_MECH indicates that a mech_type unsupported by the
355 IDUP_GSS-API implementation was requested, causing the environment
356 establishment operation to fail.
358 GSS_S_BAD_QOP indicates that the provided qop_alg value is not
359 recognized or supported for the environment.
361 GSS_S_BAD_MIC indicates that the received P-IDU contains an
362 incorrect integrity field (e.g., signature or MAC) for the data.
364 GSS_S_COMPLETE indicates that the requested operation was
365 successful.
367 GSS_S_CREDENTIALS_EXPIRED indicates that the credentials
368 associated with this operation have expired, so that the requested
369 operation cannot be performed.
371 GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
372 performed on the credential structure referenced by
373 claimant_cred_handle failed, preventing further processing from
374 being performed using that credential structure.
376 GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
377 on the received P-IDU failed, preventing further processing from
378 being performed.
380 GSS_S_FAILURE indicates that the requested operation could not be
381 accomplished for reasons unspecified at the IDUP-GSS-API level,
382 and that no interface-defined recovery action is available.
384 GSS_S_NO_CRED indicates that no environment was established,
385 either because the input cred_handle was invalid or because the
386 caller lacks authorization to access the referenced credentials.
388 IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU data
389 origin auth. / integ. has either expired or been revoked.
394 Adams Informational [Page 7]
395 \f
396 RFC 2479 IDUP-GSS-API December 1998
399 IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU
400 cannot be completed because the encrypted IDU was
401 invalid/defective (e.g., the final block was short or had
402 incorrect padding).
404 IDUP_S_BAD_KE_KEY indicates that the key used to establish a key
405 for confidentiality purposes between originator and target has
406 either expired or been revoked.
408 IDUP_S_BAD_TARG_INFO indicates that the full set of supplied
409 information regarding the target(s) is invalid or is insufficient
410 for the protection of an IDU, so P-IDU cannot be created.
412 IDUP_S_DEFECTIVE_VERIF indicates that consistency checks performed
413 on Service_Verification_Info failed, preventing further processing
414 from being performed with that parameter.
416 IDUP_S_ENCAPSULATION_UNAVAIL (I) indicates that the underlying
417 mechanism does not support encapsulation of the M-IDU into the
418 token.
420 IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied
421 do not contain the information necessary for P-IDU unprotection.
423 IDUP_S_INCOMPLETE (I) indicates that the unprotection of the P-IDU
424 is not yet complete (i.e., a determination cannot yet be made on
425 the validity of the P-IDU). The application should call
426 IDUP_Form_Complete_PIDU and then should call this function again
427 with the complete P-IDU.
429 IDUP_S_INCONSISTENT_PARAMS indicates that the supplied parameters
430 are inconsistent (e.g., only one or the other of two parameters
431 may be supplied, but both have been input).
433 IDUP_S_MORE_OUTBUFFER_NEEDED (I) indicates that the output buffer
434 supplied is too small to hold the generated data. The application
435 should continue calling this routine (until GSS_S_COMPLETE is
436 returned) in order to get all remaining output data.
438 IDUP_S_MORE_PIDU_NEEDED (I) indicates that not enough of the P-IDU
439 has been input yet for the completion of StartUnprotect. The
440 application should call this routine again with another buffer of
441 P-IDU in partial(initial)_pidu_buffer.
443 IDUP_S_NO_ENV indicates that no valid environment was recognized
444 for the env_handle provided.
450 Adams Informational [Page 8]
451 \f
452 RFC 2479 IDUP-GSS-API December 1998
455 IDUP_S_NO_MATCH indicates that Service_Verification_Info (or
456 evidence_check) and the P-IDU to be verified do not match.
458 IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service
459 requested (TTIME or UTIME) is not available in the environment.
461 IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism
462 does not support the service requested.
464 IDUP_S_SERV_VERIF_INFO_NEEDED (I) indicates that the
465 Service_Verification_Info parameter bundle must be input in order
466 for service verification to proceed. The output parameter
467 service_verification_info_id contains an identifier which may be
468 used by the calling application to locate the necessary
469 information.
471 IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
472 is not recognized or supported in the underlying mechanism.
474 1.2.2. Per-IDU Security Service Availability
476 Per-IDU security service availability in IDUP-GSS-API is to be
477 understood and used as described in GSS-API [RFC-2078], with the
478 exception that combinations of services requested by the calling
479 application and supported by the underlying mechanism may be applied
480 simultaneously to any IDU (true for both the SE and the EV calls, but
481 true in the fullest sense for the GP calls).
483 GSS-API callers desiring per-message security services should check
484 the relevant service OBJECT IDs at environment establishment time to
485 ensure that what is available in the established environment is
486 suitable for their security needs.
488 1.2.3. Per-IDU Replay Detection and Sequencing
490 The concept of per-IDU replay detection and sequencing discussed in
491 GSS-API [RFC-2078] is not relevant to the IDUP-GSS-API.
493 1.2.4. Quality of Protection
495 The concept of QOP control in IDUP-GSS-API is to be understood
496 essentially as described in GSS-API [RFC-2078]. However, the actual
497 description and use of the QOP parameter is given as follows.
499 The qop_algs parameter for IDUP is defined to be a 32-bit unsigned
500 integer with the following bit-field assignments:
506 Adams Informational [Page 9]
507 \f
508 RFC 2479 IDUP-GSS-API December 1998
511 31 (MSB) (LSB) 0
512 ----------------------------------------------
513 | U(19) | TS(5) | IA(4) | MA(4) |
514 ----------------------------------------------
516 where
518 U is a 19-bit Unspecified field (available for future
519 use/expansion) -- must be set to zero;
521 TS is a 5-bit Type Specifier (a semantic qualifier whose value
522 specifies the type of algorithm which may be used to protect the
523 corresponding IDU -- see below for details);
525 IA is a 4-bit field enumerating Implementation-specific
526 Algorithms; and
528 MA is a 4-bit field enumerating Mechanism-defined Algorithms.
530 The interpretation of the qop_algs parameter is as follows. The MA
531 field is examined first. If it is non-zero then the algorithm used
532 to protect the IDU is the mechanism-specified algorithm corresponding
533 to that integer value.
535 If MA is zero then IA is examined. If this field value is non-zero
536 then the algorithm used to protect the IDU is the implementation-
537 specified algorithm corresponding to that integer value. Note that
538 use of this field may hinder portability since a particular value may
539 specify one algorithm in one implementation of the mechanism and may
540 not be supported or may specify a completely different algorithm in
541 another implementation of the mechanism.
543 Finally, if both MA and IA are zero then TS is examined. A value of
544 zero for TS specifies the default algorithm for the established
545 mechanism. A non-zero value for TS corresponds to a particular
546 algorithm qualifier and selects any algorithm from the mechanism
547 specification which satisfies that qualifier (which actual algorithm
548 is selected is an implementation choice; the calling application need
549 not be aware of the choice made).
551 The following TS values (i.e., algorithm qualifiers) are specified;
552 other values may be added in the future.
562 Adams Informational [Page 10]
563 \f
564 RFC 2479 IDUP-GSS-API December 1998
567 When qop_algs is used to select a confidentiality algorithm:
569 00000 (0) = default confidentiality algorithm
570 00001 (1) = IDUP_SYM_ALG_STRENGTH_STRONG
571 00010 (2) = IDUP_SYM_ALG_STRENGTH_MEDIUM
572 00011 (3) = IDUP_SYM_ALG_STRENGTH_WEAK
573 11111 (31) = IDUP_NO_CONFIDENTIALITY
575 When qop_algs is used to select a DOA/integrity algorithm:
577 00000 (0) = default integrity algorithm
578 00001 (1) = IDUP_INT_ALG_DIG_SIGNATURE
579 (integrity provided through a digital signature)
580 00010 (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE
581 (integrity without a dig. sig. (e.g., with a MAC))
582 11111 (31) = IDUP_NO_INTEGRITY
584 Clearly, qualifiers such as strong, medium, and weak are debatable
585 and likely to change with time, but for the purposes of this version
586 of the specification we define these terms as follows. A
587 confidentiality algorithm is "weak" if the effective key length of
588 the cipher is 40 bits or less; it is "medium-strength" if the
589 effective key length is strictly between 40 and 80 bits; and it is
590 "strong" if the effective key length is 80 bits or greater.
591 ("Effective key length" describes the computational effort required
592 to break a cipher using the best-known cryptanalytic attack against
593 that cipher.)
595 A five-bit TS field allows up to 30 qualifiers for each of
596 confidentiality and integrity (since "0" is reserved for "default"
597 and "31" is reserved for "none", as shown above). This document
598 specifies three for confidentiality and two for integrity, leaving a
599 lot of room for future specification. Suggestions of qualifiers such
600 as "fast", "medium-speed", and "slow" have been made, but such terms
601 are difficult to quantify (and in any case are platform- and
602 processor-dependent), and so have been left out of this initial
603 specification. The intention is that the TS terms be quantitative,
604 environment-independent qualifiers of algorithms, as much as this is
605 possible.
607 Use of the qop_algs parameter as defined above is ultimately meant to
608 be as follows.
610 - TS values are specified at the IDUP-GSS-API level and are
611 therefore portable across mechanisms. Applications which know
612 nothing about algorithms are still able to choose "quality" of
613 protection for their message tokens.
618 Adams Informational [Page 11]
619 \f
620 RFC 2479 IDUP-GSS-API December 1998
623 - MA values are specified at the mechanism level and are therefore
624 portable across implementations of a mechanism.
626 - IA values are specified at the implementation level (in user
627 documentation, for example) and are therefore typically non-
628 portable. An application which is aware of its own mechanism
629 implementation and the mechanism implementation of its intended
630 P-IDU recipient, however, is free to use these values since they
631 will be perfectly valid and meaningful for protecting IDUs between
632 those entities.
634 The receiver of a P-IDU must pass back to its calling application (in
635 IDUP_Start_Unprotect()) a qop_algs parameter with all relevant fields
636 set. For example, if triple-DES has been specified by a mechanism as
637 algorithm 8, then a receiver of a triple-DES-protected P-IDU must
638 pass to its application (TS=1, IA=0, MA=8). In this way, the
639 application is free to read whatever part of the qop_algs parameter
640 it understands (TS or IA/MA).
642 1.2.5. The Provision of Time
644 IDUP mechanisms should make provision in their protocols for the
645 carrying of time information from originator to target(s). That is,
646 a target (a legitimate recipient) should get some indication during
647 unprotection regarding the time at which the protection operation
648 took place. This is particularly important if the mechanism offers
649 non-repudiation services because in some cases evidence verification
650 may only be achievable if the time at which the evidence was
651 generated is known.
653 Depending upon the platform and resources available to the
654 implementation, an IDUP environment may have access to a source of
655 trusted (secure) time, untrusted (local) time, both kinds of time, or
656 no time. OBJECT IDs indicating such availability are returned by the
657 IDUP_Establish_Env() call. When starting a protection operation, an
658 application may specify which time services it wishes to have applied
659 to the IDU. Similarly, for unprotection, an application may specify
660 which kind of time (if any) to consult when the validity of the P-IDU
661 is to be established. Specifying both kinds of time is interpreted
662 to mean that the calling application does not care which kind of time
663 is used.
665 The IDUP calls which use a time parameter specify the type of that
666 parameter to be INTEGER. This INTEGER is defined in all cases to be
667 the number of seconds which have elapsed since midnight, January 1,
668 1970, coordinated universal time.
674 Adams Informational [Page 12]
675 \f
676 RFC 2479 IDUP-GSS-API December 1998
679 2. Interface Descriptions
681 This section describes the IDUP-GSS-API's operational interface,
682 dividing the set of calls offered into five groups. Credential
683 management calls are related to the acquisition and release of
684 credentials by API callers. Environment-level calls are related to
685 the management of the security environment by an API caller. Per-IDU
686 calls are related to the protection or unprotection of individual
687 IDUs in established security environments. Special-purpose calls
688 deal with unusual or auxiliary evidence generation/verification
689 requirements. Support calls provide extra functions useful to IDUP-
690 GSS-API callers. Table 2 groups and summarizes the calls in tabular
691 fashion.
693 Table 2: IDUP-GSS-API Calls
695 CREDENTIAL MANAGEMENT
696 (see the calls given in Section 2.1 of GSS-API [RFC-2078])
698 ENVIRONMENT-LEVEL CALLS
699 IDUP_Establish_Env
700 IDUP_Abolish_Env
701 IDUP_Inquire_Env
703 PER-IDU CALLS
704 SE (SIGN,ENCRYPT) CALLS
705 IDUP_SE_SingleBuffer_Protect
706 IDUP_SE_SingleBuffer_Unprotect
707 IDUP_SE_MultiBuffer_StartProtect
708 IDUP_SE_MultiBuffer_EndProtect
709 IDUP_SE_MultiBuffer_StartUnprotect
710 IDUP_SE_MultiBuffer_EndUnprotect
711 IDUP_SE_Process_Buffer
712 EV (EVIDENCE) CALLS
713 IDUP_EV_SingleBuffer_Generate
714 IDUP_EV_SingleBuffer_Verify
715 IDUP_EV_MultiBuffer_StartGenerate
716 IDUP_EV_MultiBuffer_EndGenerate
717 IDUP_EV_MultiBuffer_StartVerify
718 IDUP_EV_MultiBuffer_EndVerify
719 IDUP_EV_Process_Buffer
720 GP (GENERAL PROTECTION) CALLS
721 IDUP_Start_Protect
722 IDUP_Protect
723 IDUP_End_Protect
724 IDUP_Start_Unprotect
725 IDUP_Unprotect
726 IDUP_End_Unprotect
730 Adams Informational [Page 13]
731 \f
732 RFC 2479 IDUP-GSS-API December 1998
735 SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms)
736 IDUP_Form_Complete_PIDU
738 SUPPORT CALLS
739 IDUP_Acquire_cred_with_auth
740 IDUP_Get_Token_Details
741 IDUP_Get_Policy_Info
742 IDUP_Cancel_Multibuffer_Op
743 (see also the calls given in Section 2.4 of GSS-API [RFC-2078])
745 In terms of conformance to this specification, IDUP-GSS-API
746 implementations must support the credential management calls, the
747 environment-level calls, some subset of the per-IDU calls, and the
748 support calls (except where explicitly stated otherwise in Section
749 2.5). The subset of per-IDU calls supported will depend upon the
750 underlying mechanisms supported and will typically be the SE calls,
751 or the EV calls, or both. As stated in Section 2.3.2.1,
752 implementations are encouraged to support the more powerful GP calls
753 to anticipate the future needs of applications developers, but this
754 is not required for conformance.
756 2.1. Credential management calls
758 2.1.1. Relationship to GSS-API
760 Credential management in IDUP-GSS-API is to be understood and used as
761 described in GSS-API [RFC-2078]. The calls given in Section 2.1 of
762 GSS-API (including all associated parameters) are unchanged, although
763 the interpretation of the cred_usage parameter in the GSS-API calls
764 for IDUP purposes is as follows.
766 ENCRYPT_ONLY 8
767 DECRYPT_ONLY 16
768 SIGN_ONLY 32
769 VERIFY_ONLY 64
771 The values above may be logically OR'ed together in any desired
772 combination to restrict credential usage (where OR'ing all values
773 results in NO_RESTRICTION). Future possible values for this
774 parameter are for further study.
776 The call IDUP_Acquire_cred_with_auth has been added as a support call
777 in this specification to permit authenticated credential acquirement;
778 see Section 2.5.2 for details.
786 Adams Informational [Page 14]
787 \f
788 RFC 2479 IDUP-GSS-API December 1998
791 2.2. Environment-level calls
793 This group of calls is devoted to the establishment and management of
794 an environment for the purpose of IDU protection and unprotection.
795 Before protecting or unprotecting any IDU, an application must call
796 IDUP_Establish_Env() to initialize environment information and select
797 the underlying IDUP-GSS mechanism to be used. A series of protection
798 or unprotection calls is made to process each IDU, the protection
799 calls resulting in a P-IDU for each. Finally, IDUP_Abolish_Env() is
800 called to flush all environment information.
802 Semantically, acquiring credentials and establishing an environment
803 is (in many cases) analogous to logging in to a system -- it
804 authenticates a local user to the system and gives that user access
805 to a set of operations which can be performed.
807 2.2.1. Relationship to GSS-API
809 The set of calls described in this section is used in place of the
810 calls described in Section 2.2 of GSS-API [RFC-2078], since those
811 calls are specific to a session-oriented environment.
813 2.2.2. IDUP_Establish_Env call
815 Inputs: o claimant_cred_handle CREDENTIAL HANDLE,
816 -- NULL parameter specifies "use default"
818 o req_mech_type OBJECT IDENTIFIER,
819 -- NULL parameter specifies "use default"
820 o req_environmentPolicies EnvironmentPolicies,
821 -- NULL parameter specifies "use default"
822 o req_services SET OF OBJECT IDENTIFIER,
823 -- GSS_C_NO_OID_SET requests full set of services available
824 -- for req_mech_type
826 Outputs:
827 o major_status INTEGER,
828 o minor_status INTEGER,
829 o env_handle ENVIRONMENT HANDLE,
830 o actual_mech_type OBJECT IDENTIFIER,
831 -- actual mechanism always indicated, never NULL
832 o actual_environmentPolicies EnvironmentPolicies,
833 -- actual values always indicated, never NULL
834 o ret_services SET OF OBJECT IDENTIFIER,
836 Return major_status codes:
837 o GSS_S_COMPLETE
838 -- environment-level information was successfully initialized,
842 Adams Informational [Page 15]
843 \f
844 RFC 2479 IDUP-GSS-API December 1998
847 -- and IDU / P-IDU processing can begin.
848 o GSS_S_DEFECTIVE_CREDENTIAL
849 o GSS_S_NO_CRED
850 o GSS_S_CREDENTIALS_EXPIRED
851 -- the credentials provided through claimant_cred_handle are
852 -- no longer valid, so environment cannot be established.
853 o GSS_S_BAD_MECH
854 o GSS_S_FAILURE
856 The following structures are defined to facilitate environment policy
857 input and output:
859 EnvironmentPolicies ::= SEQUENCE {
860 confPolicy [0] PolicyAndTime OPTIONAL,
861 -- NULL parameter (on input) specifies "use default"
862 integPolicy [1] PolicyAndTime OPTIONAL,
863 -- NULL parameter (on input) specifies "use default"
864 evidencePolicy [2] PolicyAndTime OPTIONAL }
865 -- NULL parameter (on input) specifies "use default"
867 PolicyAndTime ::= SEQUENCE {
868 policy OBJECT IDENTIFIER,
869 -- this environment-level policy identifier is separate from
870 -- the policy provisions connected with credentials, if they exist
871 time INTEGER
872 -- on input: the policy rules available at the specified time
873 -- on output: the time at which the policy rules came into effect
874 -- (defined to be the number of seconds elapsed since midnight,
875 -- January 1, 1970, coordinated universal time)
876 endTime INTEGER OPTIONAL }
877 -- on input: unused
878 -- on output: the expiration time of the given policy rules
880 This routine is used by an application which protects or unprotects
881 IDUs. Using information in the credentials structure referenced by
882 claimant_cred_handle, IDUP_Establish_Env() initializes the data
883 structures required to protect or unprotect IDUs. The
884 claimant_cred_handle, if non-NULL, must correspond to a valid
885 credentials structure.
887 This routine returns an env_handle for all future references to this
888 environment; when protection, unprotection, or IDUP_Abolish_Env()
889 calls are made, this handle value will be used as the input
890 env_handle argument. It is the caller's responsibility to establish
891 a communications path to the intended recipients of the P-IDU, and to
892 transmit the P-IDU to those recipients over that path. This may
893 occur subsequent to the IDUP_Abolish_Env() call.
898 Adams Informational [Page 16]
899 \f
900 RFC 2479 IDUP-GSS-API December 1998
903 The req_services parameter may be used by the calling application to
904 request that data origin authentication with integrity,
905 confidentiality with integrity, evidence generation, and/or evidence
906 verification services be available in the established environment.
907 Requests can also be made for "trusted" or "untrusted" time services.
908 Requesting evidence generation or verification indicates that the
909 calling application may wish to generate or verify evidence
910 information for non-repudiation purposes (note: an IDU protector may
911 request that a flag be inserted into a P-IDU asking a recipient to
912 provide an evidence of the type "non-repudiation of delivery";
913 however, the IDUP-GSS-API cannot by itself guarantee that the
914 evidence will be sent because there is no way to force a target to
915 send an evidence_token back to the IDU protector).
917 Not all features will be available in all underlying mech_types; the
918 returned value of ret_services indicates, as a function of mech_type
919 processing capabilities and the initiator-provided input OBJECT IDs,
920 the set of features which will be available in the environment. The
921 value of this parameter is undefined unless the routine's
922 major_status indicates COMPLETE. Failure to provide the precise set
923 of services desired by the caller does not cause environment
924 establishment to fail; it is the caller's choice to abolish the
925 environment if the service set provided is unsuitable for the
926 caller's use. The returned mech_type value indicates the specific
927 mechanism employed in the environment and will never indicate the
928 value for "default".
930 The following OBJECT IDs are defined for protection and unprotection
931 services (the OBJECT ID iso.org.dod.internet.security.services,
932 1.3.6.1.5.7, has been assigned by IANA, and some of the security
933 services under that node are assigned as shown below). It is
934 recognized that this list may grow over time.
936 PER_CONF = { 1.3.6.1.5.7.1.1 }
937 -- perform data confidentiality (i.e., encrypt data)
938 PER_CONF_FULL = { 1.3.6.1.5.7.1.3 }
939 -- perform full confidentiality (i.e., encrypt data and sig)
940 -- (may be used only when PER_DOA is requested simultaneously)
941 PER_DOA = { 1.3.6.1.5.7.3.1 }
942 -- perform data origin authentication with data integrity
943 PER_DOA_CIPH = { 1.3.6.1.5.7.3.3 }
944 -- perform DOA with DI over ciphertext (rather than plaintext)
945 -- (may be used only when PER_CONF is requested simultaneously)
946 PER_POO = { 1.3.6.1.5.7.4.1 }
947 -- perform (i.e., create) non-repudiable "proof of origin"
948 PER_POD = { 1.3.6.1.5.7.4.3 }
949 -- perform (i.e., create) non-repudiable "proof of delivery"
954 Adams Informational [Page 17]
955 \f
956 RFC 2479 IDUP-GSS-API December 1998
959 REC_CONF = { 1.3.6.1.5.7.1.2 }
960 -- receive data confidentiality (i.e., decrypt data)
961 REC_CONF_FULL = { 1.3.6.1.5.7.1.4 }
962 -- receive full confidentiality (i.e., decrypt data and sig)
963 -- (may be used only when REC_DOA is received simultaneously)
964 REC_DOA = { 1.3.6.1.5.7.3.2 }
965 -- receive / verify DOA with data integrity
966 REC_DOA_CIPH = { 1.3.6.1.5.7.3.4 }
967 -- verify DOA with DI over ciphertext (rather than plaintext)
968 -- (may be used only when PER_CONF is received simultaneously)
969 REC_POO = { 1.3.6.1.5.7.4.2 }
970 -- receive / verify "proof of origin"
971 REC_POD = { 1.3.6.1.5.7.4.4 }
972 -- receive / verify "proof of delivery"
973 TTIME = { 1.3.6.1.5.7.7.1 }
974 -- trusted time availability
975 UTIME = { 1.3.6.1.5.7.7.2 }
976 -- untrusted time availability
978 The PER_CONF return value (in the ret_services paramater) indicates
979 whether the environment supports confidentiality services, and so
980 informs the caller whether or not a request for encryption can be
981 honored. In similar fashion, the PER_DOA return value indicates
982 whether DOA services are available in the established environment,
983 and the PER_POO and PER_POD return values indicate whether evidence
984 generation services are available. The TTIME and UTIME values
985 indicate whether trusted time and untrusted time are available for
986 protection / unprotection services.
988 Note that, unlike a GSS "context", an IDUP environment does not have
989 an explicit lifetime associated with it. Instead, it relies on the
990 lifetime of the calling entity's credential (set by the caller in the
991 GSS_Acquire_cred() call). When the credential expires (or is
992 explicitly deleted in any other way), no new operations are allowed
993 in the IDUP environment (although operations which have begun, such
994 as the Protection set of calls, can be taken to completion).
1010 Adams Informational [Page 18]
1011 \f
1012 RFC 2479 IDUP-GSS-API December 1998
1015 2.2.3. IDUP_Abolish_Env call
1017 Input:
1018 o env_handle ENVIRONMENT HANDLE
1020 Outputs:
1021 o major_status INTEGER,
1022 o minor_status INTEGER,
1024 Return major_status codes:
1025 o GSS_S_COMPLETE
1026 -- the relevant environment-specific information was flushed.
1027 o IDUP_S_NO_ENV
1028 o GSS_S_FAILURE
1030 This call is made to flush environment-specific information. (Once an
1031 environment is established, cached credential and environment-related
1032 info. is expected to be retained until an IDUP_Abolish_Env() call is
1033 made or until the cred. lifetime expires.) Attempts to perform IDU
1034 processing on a deleted environment will result in error returns.
1036 2.2.4. IDUP_Inquire_Env call
1038 Input:
1039 o env_handle ENVIRONMENT HANDLE,
1041 Outputs:
1042 o major_status INTEGER,
1043 o minor_status INTEGER,
1044 o mech_type OBJECT IDENTIFIER,
1045 -- the mechanism supporting this environment
1046 o environmentPolicies EnvironmentPolicies,
1047 -- the environment policies in effect
1048 o ret_services SET OF OBJECT IDENTIFIER,
1050 Return major_status codes:
1051 o GSS_S_COMPLETE
1052 -- referenced environment is valid and mech_type and other return
1053 -- values describe the characteristics of the environment.
1054 o GSS_S_CREDENTIALS_EXPIRED
1055 o IDUP_S_NO_ENV
1056 o GSS_S_FAILURE
1058 This routine provides environment-related information to the caller.
1066 Adams Informational [Page 19]
1067 \f
1068 RFC 2479 IDUP-GSS-API December 1998
1071 2.3. Per-IDU calls
1073 This group of calls is used to perform IDU protection and
1074 unprotection processing on an established IDUP environment. Some of
1075 these calls may block pending network interactions (depending on the
1076 underlying mechanism in use). These calls may be invoked by an IDU's
1077 protector or by the P-IDU's recipient. Members of this group form
1078 pairs; the output from the protection types of calls is typically
1079 meant to be input to the unprotection types of calls.
1081 The per-IDU calls can support caller-requested data origin
1082 authentication with data integrity, confidentiality with data
1083 integrity, evidence, and evidence-requested-from-target services.
1085 The protection operations output a token which encapsulates all the
1086 information required to unprotect the IDU. The token is passed to
1087 the target (possibly separate from the M-IDU) and is processed by the
1088 unprotection calls at that system. Unprotection performs
1089 decipherment, DOA verification, evidence verification, or
1090 notification of evidence requested, as required.
1092 Each of the two main operations (protection and unprotection) may be
1093 separated into three parts: "Start_Operation"; "Operation" (which
1094 may be called once for each buffer of input data); and
1095 "End_Operation". This separation is available for the case where the
1096 IDU or P-IDU is to be processed one buffer at a time.
1097 "Start_Operation" allows the caller to specify or retrieve the
1098 appropriate "Quality" used during the processing. "Operation" is
1099 concerned with the processing itself, receiving a buffer of input
1100 data and potentially returning a buffer of output data.
1101 "End_Operation" performs any required clean-up and creates the
1102 appropriate token or states whether the input token was verified.
1104 If the IDU or P-IDU is wholly contained in a single buffer, the
1105 three-part protection/unprotection processing need not be done.
1106 Instead, protection or unprotection can be accomplished using only a
1107 single call, simplifying application code.
1109 2.3.1. Relationship to GSS-API
1111 The set of calls described in this section is used in place of the
1112 calls GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() which
1113 are specified in [RFC-2078], since those calls are specific to a
1114 session-oriented environment.
1122 Adams Informational [Page 20]
1123 \f
1124 RFC 2479 IDUP-GSS-API December 1998
1127 2.3.2. The "SE" Calls
1129 2.3.2.1. IDUP_SE Purpose
1131 The "SE" group of calls provides a very simple, high-level interface
1132 to underlying IDUP mechanisms when application developers need access
1133 only to signature and encryption protection/unprotection services.
1134 It includes both the single-buffer and multiple-buffer IDU cases and
1135 can be used for signing only, encrypting only, signing and encrypting
1136 (in either order, and with or without visibility of the resulting
1137 signature), and "clear signing" (where the data is not modified in
1138 any way and the signature itself is returned as a separate item).
1139 [Note that encapsulation occurs in all cases except for clear
1140 signing, so that these calls provide functionality similar to the
1141 GSS_Wrap call.]
1143 Note that the term "signing" is used in its most generic sense, not
1144 necessarily implying the use of public-key techniques. This concept
1145 has also been called "sealing" in other contexts (e.g., in other
1146 standardization efforts).
1148 The SE calls may be viewed by mechanism implementors as an "API" to
1149 the more powerful GP calls defined later and so may be implemented as
1150 simple mapping functions to those calls (when those optional calls
1151 are supported). Application callers, on the other hand, may find
1152 that the SE calls are all they currently need for many environments.
1153 At some time in the future when they have need of non-repudiation or
1154 "directed receipts" types of services, they may consider using the EV
1155 calls (or the GP calls -- when these are supported -- if complex and
1156 sophisticated combinations of services are required). To assist in
1157 this migration path, mechanism implementors are encouraged to support
1158 the full set of IDUP calls (i.e., the SE, EV, and GP calls) even
1159 though some calling applications will only use the SE calls in the
1160 short term.
1162 2.3.2.2. IDUP_SE Parameter Bundles
1164 The concept of "parameter bundles" is used in the calls presented in
1165 the following subsections in order to simplify their presentation and
1166 clarify their intended purpose and use. See Section 2.3.4.1 for a
1167 more complete description of parameter bundles.
1169 The following parameter bundles are used in the "SE" protection and
1170 unprotection sets of calls.
1178 Adams Informational [Page 21]
1179 \f
1180 RFC 2479 IDUP-GSS-API December 1998
1183 o Protect_Options PARAMETER BUNDLE
1184 o protect_operation INTEGER {
1185 sign_only (0),
1186 encrypt_only (1),
1187 sign_and_encrypt (2),
1188 -- let mechanism choose order (and readability of signature)
1189 sign_then_encrypt_data (3),
1190 -- sign, then encrypt plaintext (leaving signature in clear)
1191 sign_then_encrypt_full (4),
1192 -- sign, then encrypt everything (including signature)
1193 encrypt_then_sign (5),
1194 -- encrypt, then sign the ciphertext
1195 clear_sign_only (6)
1196 } OPTIONAL,
1197 o protect_oper_oid OBJECT IDENTIFIER OPTIONAL,
1198 -- may be used in place of above parameter if OID is known
1199 o sign_qop_alg UNSIGNED INTEGER,
1200 o sign_qop_algID AlgorithmIdentifier, --overrides sign_qop_alg
1201 o enc_qop_alg UNSIGNED INTEGER,
1202 o enc_qop_algID AlgorithmIdentifier, --overrides enc_qop_alg
1203 o idu_type_string OCTET STRING,
1204 -- type of the IDU ("data", "e-mail doc", MIME type, etc.)
1205 o pidu_type_string OCTET STRING,
1206 o mech_indep_encap_req BOOLEAN -- (see Appendix A)
1208 o PIDU_Information PARAMETER BUNDLE
1209 o protect_options Protect_Options,
1210 o originator_name INTERNAL NAME,
1211 o originator_role Originator_Role, -- (see Section 2.3.4.1)
1212 o protection_time INTEGER,
1213 o Bad_Target_Name PARAMETER BUNDLE, -- same as in Section 2.3.3.2
1214 o bad_targ_name INTERNAL NAME,
1215 o bad_targ_status INTEGER,
1216 -- a status flag giving the reason for rejection of the name
1217 -- in bad_targ_name. Specified reasons include:
1218 -- SYNTAX_INVALID (0) the syntax of the name is invalid;
1219 -- NAME_UNRECOGNIZED (1) the name is not recognized;
1220 -- NAME_AMBIGUOUS (2) the name cannot be resolved;
1221 -- ACCESS_DENIED (3) access to this target is denied;
1222 -- CERTIFICATE_NOT_FOUND (4) the encryption certificate of the
1223 target could not be found.
1225 o Target_Info PARAMETER BUNDLE, -- same as in Section 2.3.3.2
1226 o targ_names SET OF INTERNAL NAME,
1227 o bad_targ_count INTEGER,
1228 o bad_target_names SET OF Bad_Target_Name,
1234 Adams Informational [Page 22]
1235 \f
1236 RFC 2479 IDUP-GSS-API December 1998
1239 2.3.2.3. IDUP_SE major_status codes
1241 The following major_status return codes are defined for the "SE"
1242 calls in this section:
1244 o GSS_S_COMPLETE
1245 o IDUP_S_MORE_OUTBUFFER_NEEDED
1246 -- returned (by any SE call) to indicate that there is more output
1247 -- data than can fit into the supplied buffers. The application
1248 -- should save the returned data and call again to retrieve the
1249 -- remaining output.
1250 o IDUP_S_MORE_PIDU_NEEDED
1251 -- indicates that more PIDU data is needed for the StartUnprotect
1252 -- operation (e.g., so that PIDU_Information or initial_idu_buffer
1253 -- may be returned).
1254 o IDUP_S_INCONSISTENT_PARAMS
1255 o GSS_S_CREDENTIALS_EXPIRED
1256 o IDUP_S_NO_ENV
1257 o GSS_S_BAD_QOP
1258 o GSS_S_FAILURE
1260 If Target_Info is used as an input parameter (e.g., if an encryption
1261 operation is being performed), the following major_status return code
1262 is also defined:
1264 o IDUP_S_BAD_TARG_INFO
1266 Note for this return code that if one or more of the targets in
1267 targ_names cannot be used as a valid recipient of the P-IDU, these
1268 names will be returned in bad_targ_names (with associated status
1269 codes in bad_targ_status). As long as at least one of the targets
1270 can be used, however, this does not cause this call to fail (i.e.,
1271 the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the
1272 caller's choice to discontinue IDU protection if the target set which
1273 can be used is unsuitable for the caller's purposes.
1275 2.3.2.4. IDUP_SE_SingleBuffer_Protect call
1277 Inputs:
1278 o env_handle ENVIRONMENT HANDLE,
1279 o Protect_Options PARAMETER BUNDLE,
1280 o Target_Info PARAMETER BUNDLE,
1281 o idu_buffer OCTET STRING
1282 o additional_protection BOOLEAN
1283 -- TRUE if idu_buffer is the output of a previous protection
1284 -- operation (i.e., if this is the second (or higher) in a
1285 -- series of SE/EV protection calls)
1290 Adams Informational [Page 23]
1291 \f
1292 RFC 2479 IDUP-GSS-API December 1998
1295 Outputs:
1296 o major_status INTEGER,
1297 o minor_status INTEGER,
1298 o pidu_buffer OCTET STRING,
1299 o sig_token OCTET STRING
1300 -- used if Protect_Options is clear_sign_only
1302 Using the security environment referenced by env_handle, encrypt
1303 and/or sign the supplied IDU. If "clear signing" is performed, the
1304 signature will be returned in sig_token and pidu_buffer may be empty
1305 (depends on underlying mechanism).
1307 2.3.2.5. IDUP_SE_SingleBuffer_Unprotect call
1309 Inputs:
1310 o env_handle ENVIRONMENT HANDLE,
1311 o pidu_buffer OCTET STRING,
1312 -- may contain an IDU if sig_token is non-NULL (i.e., if
1313 -- clear_sign_only protection was applied)
1314 o sig_token OCTET STRING
1316 Outputs:
1317 o major_status INTEGER,
1318 o minor_status INTEGER,
1319 o idu_buffer OCTET STRING,
1320 -- may be empty if clear_sign_only protection was applied (depends
1321 -- on underlying mechanism)
1322 o PIDU_Information PARAMETER BUNDLE
1323 o additional_unprotection BOOLEAN
1324 -- TRUE if idu_buffer should be input to another unprotection
1325 -- operation (i.e., if this should not be the last in a series
1326 -- of SE/EV unprotection calls)
1328 Using the security environment referenced by env_handle, decrypt
1329 and/or verify the supplied PIDU and return the contained IDU along
1330 with all available PIDU_Information.
1332 2.3.2.6. IDUP_SE_MultiBuffer_StartProtect call
1334 Inputs:
1335 o env_handle ENVIRONMENT HANDLE,
1336 o Protect_Options PARAMETER BUNDLE,
1337 o Target_Info PARAMETER BUNDLE,
1338 o additional_protection BOOLEAN, -- (see Section 2.3.2.4)
1339 o idu_size INTEGER -- (see Section 2.3.4.2)
1346 Adams Informational [Page 24]
1347 \f
1348 RFC 2479 IDUP-GSS-API December 1998
1351 Outputs:
1352 o major_status INTEGER,
1353 o minor_status INTEGER,
1354 o initial_pidu_buffer OCTET STRING
1355 -- may be empty (depends on underlying mechanism)
1357 Using the security environment referenced by env_handle, initialize
1358 the data structures required to begin the process of signing and/or
1359 encrypting the IDU (which will be supplied in multiple buffers to the
1360 Process_Buffer call).
1362 2.3.2.7. IDUP_SE_MultiBuffer_EndProtect call
1364 Inputs:
1365 o env_handle ENVIRONMENT HANDLE
1367 Outputs:
1368 o major_status INTEGER,
1369 o minor_status INTEGER,
1370 o final_pidu_buffer OCTET STRING,
1371 o sig_token OCTET STRING
1372 -- used if Protect_Options was clear_sign_only
1374 Using the security environment referenced by env_handle, complete the
1375 protection processing on the data and place the computed output in
1376 final_pidu_buffer and/or sig_token. Successful application of
1377 IDUP_SE_MultiBuffer_EndProtect() does not guarantee that unprotection
1378 can necessarily be performed successfully when the P-IDU arrives at
1379 the target (for example, it may be damaged in transit).
1381 2.3.2.8. IDUP_SE_MultiBuffer_StartUnprotect call
1383 Inputs:
1384 o env_handle ENVIRONMENT HANDLE,
1385 o initial_pidu_buffer OCTET STRING,
1386 o sign_qop_alg_in UNSIGNED INTEGER,
1387 -- used if Protect_Options was clear_sign_only (and calling
1388 -- application has prior knowledge of signing alg. applied);
1389 -- if NULL, then sig_token must be supplied
1390 o sig_token OCTET STRING
1391 -- used if Protect_Options was clear_sign_only;
1392 -- if NULL, then sign_qop_alg_in must be supplied
1394 Outputs:
1395 o major_status INTEGER,
1396 o minor_status INTEGER,
1397 o PIDU_Information PARAMETER BUNDLE,
1398 -- returns all available information
1402 Adams Informational [Page 25]
1403 \f
1404 RFC 2479 IDUP-GSS-API December 1998
1407 o initial_idu_buffer OCTET STRING
1408 -- may be empty
1410 Using the security environment referenced by env_handle, initialize
1411 the data structures required to begin the process of decrypting
1412 and/or verifying the PIDU (which will be supplied in multiple buffers
1413 to the Process_Buffer call).
1415 The parameters sign_qop_alg_in and sig_token should not both be
1416 supplied (i.e., they should not both be non-NULL). If they are both
1417 non-NULL, however, sig_token is taken to be authoritative since this
1418 is the token created at protection time and therefore is guaranteed
1419 to carry the information needed to unprotect.
1421 2.3.2.9. IDUP_SE_MultiBuffer_EndUnprotect call
1423 Inputs:
1424 o env_handle ENVIRONMENT HANDLE,
1425 o sig_token OCTET STRING OPTIONAL
1426 -- used if Protect_Options was clear_sign_only and sig_token was
1427 -- not available when StartUnprotect was called
1429 Outputs:
1430 o major_status INTEGER,
1431 o minor_status INTEGER,
1432 o PIDU_Information PARAMETER BUNDLE,
1433 -- returns all available information
1434 o final_idu_buffer OCTET STRING -- may be empty
1435 o additional_unprotection BOOLEAN -- (see Section 2.3.2.5)
1437 Using the security environment referenced by env_handle, complete the
1438 decryption and/or verification processing on the data and place any
1439 residual output in final_idu_buffer.
1441 2.3.2.10. IDUP_SE_Process_Buffer call
1443 Inputs:
1444 o env_handle ENVIRONMENT HANDLE,
1445 o input_buffer OCTET STRING,
1447 Outputs:
1448 o major_status INTEGER,
1449 o minor_status INTEGER,
1450 o output_buffer OCTET STRING
1451 -- may be zero length (depends on underlying mechanism and
1452 -- corresponding Start() call and Protect_Options value)
1458 Adams Informational [Page 26]
1459 \f
1460 RFC 2479 IDUP-GSS-API December 1998
1463 Using the security environment referenced by env_handle, continue the
1464 processing on the data in input_buffer and, if it is available, put
1465 any resulting output data in output_buffer. The application calls
1466 this routine over and over again with new buffers of data until it
1467 has processed all the data buffers of the IDU/PIDU. It then calls the
1468 appropriate End() call to complete the processing.
1470 2.3.3. The "EV" Calls
1472 2.3.3.1. IDUP_EV Purpose
1474 The "EV" group of calls provides a simple, high-level interface to
1475 underlying IDUP mechanisms when application developers need to deal
1476 only with evidence but not with encryption or integrity services. It
1477 includes both the single-buffer and multiple-buffer IDU cases and can
1478 be used for the generation and verification of evidence tokens
1479 embodying several different types of evidences.
1481 The following list of evidence types is supported. This list is by no
1482 means exhaustive and it is anticipated that it may be extended in
1483 future versions of this specification.
1485 "Non-repudiation of Origin" prevents a message creator's false
1486 denial of creating and sending a message.
1488 "Non-repudiation of Creation" prevents a message creator's false
1489 denial of creating a message.
1491 "Non-repudiation of Sender" prevents a message creator's false
1492 denial of sending a message (that was not necessarily created by
1493 the sender).
1495 "Non-repudiation of Delivery" prevents a message recipient's false
1496 denial of having received and looked at the content of a message.
1498 "Non-repudiation of Receipt" prevents a message recipient's false
1499 denial of having received a message (whose content was not
1500 necessarily looked at by the recipient).
1502 "Non-repudiation of Approval" prevents a message recipient's false
1503 denial of having approved the content of a received message.
1505 An evidence is provided in the form of a evidence token. Two forms of
1506 evidence tokens are supported:
1508 o Tokens including the associated data,
1514 Adams Informational [Page 27]
1515 \f
1516 RFC 2479 IDUP-GSS-API December 1998
1519 o Tokens without included data (but with a unique reference to
1520 the associated data).
1522 Evidence tokens may be freely distributed. Any possessor of an
1523 evidence token (and of the associated data, if not included in the
1524 token) can verify the evidence if it has the appropriate credentials
1525 which include the definition of security policies (i.e., keys alone
1526 do not permit the verification of evidence tokens). Any holder of an
1527 evidence token may store it (along with the associated data, if not
1528 included in the token) for later verification.
1530 Calls that are specific to the support of evidence include:
1532 * Generate_token, which generates a non-repudiation token using the
1533 current environment. The generated token may consist of:
1535 1 - an evidence token
1536 2 - a token containing a request for an evidence, which carries
1537 information describing which evidence type should be generated
1538 by the recipient(s) and sent back to some entities (that may
1539 or may not include the sender).
1540 3 - a token containing an evidence token which is an answer to an
1541 evidence that has been previously requested.
1542 4 - a token including both an evidence and a request for another
1543 evidence to be provided.
1545 * Verify_evidence, which verifies the evidence token using the
1546 current environment. This operation returns a major_status code
1547 which can be used to determine whether the evidence contained in a
1548 token is complete (i.e., can be successfully verified (perhaps
1549 years) later). If a token's evidence is not complete, the token can
1550 be passed to form_complete_pidu to complete it.
1552 Additional useful calls for evidence services include:
1553 * IDUP_Get_token_details (see Section 2.5.3);
1554 * IDUP_Form_Complete_PIDU (see Section 2.4.2).
1556 2.3.3.2. IDUP_EV Parameters
1558 The following parameter bundles are used in the "EV" protection and
1559 unprotection sets of calls.
1561 o Nr_Options PARAMETER BUNDLE
1562 o evidence_type INTEGER {
1563 no_evidence (0)
1564 -- used when request-only token desired
1565 proof_of_receipt (1),
1566 proof_of_delivery (2),
1570 Adams Informational [Page 28]
1571 \f
1572 RFC 2479 IDUP-GSS-API December 1998
1575 proof_of_approval (3),
1576 proof_of_creation (4),
1577 proof_of_sender (5),
1578 proof_of_origin (6)
1579 } OPTIONAL,
1580 o evidence_type_oid OBJECT IDENTIFIER OPTIONAL,
1581 -- may be used in place of above parameter if OID is known
1582 o evidence_validity_duration INTEGER,
1583 -- duration_in_minutes
1584 -- DURATION_HOUR = 60;
1585 -- DURATION_DAY = 1440;
1586 -- DURATION_WEEK = 10080;
1587 -- DURATION_MONTH = 43200;// 30 days
1588 -- DURATION_YEAR = 525600;//365 days
1589 o mech_indep_encap_req BOOLEAN -- (see Appendix A)
1591 o Originator_Information PARAMETER BUNDLE
1592 o token_generator_name INTERNAL NAME,
1593 -- obtained from the credentials of the originator
1594 -- (e.g., from its public key certificate)
1595 o token_generator_role Originator_Role OPTIONAL,
1596 -- (see Section 2.3.4.1)
1597 o protection_time INTEGER OPTIONAL
1599 o Bad_Target_Name PARAMETER BUNDLE -- (see Section 2.3.2.2)
1600 o bad_targ_name INTERNAL NAME,
1601 o bad_targ_status INTEGER
1602 -- a status flag giving the reason for rejection of the
1603 -- name in bad_targ_name
1605 o Target_Info PARAMETER BUNDLE -- same as in Section 2.3.2.2
1606 o targ_names SET OF INTERNAL NAME,
1607 o bad_targ_count INTEGER,
1608 o bad_target_names SET OF Bad_Target_Name
1610 o Request_Features PARAMETER BUNDLE
1611 o requested_evidence_type INTEGER {
1612 no_evidence (0), - used when no token desired
1613 proof_of_receipt (1),
1614 proof_of_delivery (2),
1615 proof_of_approval (3), },
1616 o nr_req_policy OBJECT IDENTIFIER,
1617 o evidence_from Target_Info,
1618 o evidence_to Target_Info,
1619 o include_received_token_in_evidence BOOLEAN
1621 The following data_type is used in the "EV" protection calls.
1626 Adams Informational [Page 29]
1627 \f
1628 RFC 2479 IDUP-GSS-API December 1998
1631 o Nr_Operation INTEGER {
1632 evidence_and_or_evidence_request (1),
1633 returned_evidence (2) }
1635 2.3.3.3. IDUP_EV major_status codes
1637 The following major_status return codes are defined for the "EV"
1638 calls in this section:
1640 o GSS_S_COMPLETE
1641 -- indicates that the evidence is complete
1642 o IDUP_S_INCOMPLETE
1643 o IDUP_S_MORE_OUTBUFFER_NEEDED
1644 -- returned (by any EV call) to indicate that there is more output
1645 -- data than can fit into the supplied buffers. The application
1646 -- should save the returned data and call again to retrieve the
1647 -- remaining output.
1648 o IDUP_S_INCONSISTENT_PARAMS
1649 o GSS_S_CREDENTIALS_EXPIRED
1650 o IDUP_S_NO_MATCH
1651 o IDUP_S_NO_ENV
1652 o GSS_S_FAILURE
1654 If Target_Info is used as an input parameter (i.e., if an evidence is
1655 being requested ), the following major_status return code is also
1656 defined:
1658 o IDUP_S_BAD_TARG_INFO
1660 Note for this return code that if one or more of the targets in
1661 targ_names cannot be used as a valid recipient of the P-IDU, these
1662 names will be returned in bad_targ_names (with associated status
1663 codes in bad_targ_status). As long as at least one of the targets
1664 can be used, however, this does not cause this call to fail (i.e.,
1665 the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the
1666 caller's choice to discontinue IDU protection if the target set which
1667 can be used is unsuitable for the caller's purposes.
1669 2.3.3.4. IDUP_EV_SingleBuffer_Generate call
1671 Inputs:
1672 o env_handle ENVIRONMENT HANDLE,
1673 o nr_operation Nr_Operation,
1674 o Nr_Options PARAMETER BUNDLE,
1675 o idu_buffer OCTET STRING,
1676 o form_complete_pidu BOOLEAN,
1677 -- if TRUE the implementation will attempt to form a complete PIDU
1678 o include_data_in_token BOOLEAN,
1682 Adams Informational [Page 30]
1683 \f
1684 RFC 2479 IDUP-GSS-API December 1998
1687 -- if TRUE, data provided in idu_buffer will be included in the
1688 -- generated token; if FALSE, the data will not be included
1689 o Request_Features PARAMETER BUNDLE
1690 -- the type of the evidence that is requested;
1691 -- policy under which the returned evidence should be generated;
1692 -- the recipients that are supposed to send back an evidence;
1693 -- the recipients that should receive the requested evidence;
1694 -- an indicator include_received_token_in_evidence:
1695 -- if TRUE, the evidence token incorporating the request will be
1696 -- included in the data for which recipients will generate
1697 -- evidence; if FALSE, evidence will be generated using only
1698 -- the data (and not the token incorporating the request).
1699 o additional_protection BOOLEAN -- (see Section 2.3.2.4)
1701 Outputs:
1702 o major_status INTEGER,
1703 o minor_status INTEGER,
1704 o token OCTET STRING,
1705 o evidence_check OCTET STRING,
1706 -- present only if an evidence is requested. Consists of data to
1707 -- be used to verify the requested token(s) (if any) when they are
1708 -- received.
1710 Description:
1712 This operation generates a non-repudiation token associated with the
1713 data passed in an input buffer. Two kinds of operations can be
1714 performed (using the Nr_Operation parameter):
1716 a) generating a token that includes either an evidence only, or
1717 an evidence request only, or both an evidence and an evidence
1718 request;
1720 b) generating a response token for some recipients that includes an
1721 evidence generated as a response to a request (in this case the
1722 idu_buffer is used to enter the request token that was received).
1724 It is possible to request the generation of complete evidence. This
1725 may succeed or fail; if it fails, a subsequent call to
1726 Form_Complete_PIDU can be made.
1728 2.3.3.5. IDUP_EV_SingleBuffer_Verify call
1730 Inputs:
1731 o env_handle ENVIRONMENT HANDLE,
1732 o token OCTET STRING,
1733 o external_idu_buffer OCTET STRING,
1734 -- if not present within the token
1738 Adams Informational [Page 31]
1739 \f
1740 RFC 2479 IDUP-GSS-API December 1998
1743 o evidence_check OCTET STRING,
1744 -- present only if the input token is a response to a previous
1745 -- request for evidence (this parameter is used to validate that
1746 -- evidence).
1748 Outputs:
1749 o major_status INTEGER,
1750 o minor_status INTEGER,
1751 o Nr_Options PARAMETER BUNDLE,
1752 o Originator_Information PARAMETER BUNDLE,
1753 o Request_Features PARAMETER BUNDLE,
1754 o trusted_time_stamping_time INTEGER OPTIONAL,
1755 -- present for informational purposes only
1756 o complete_evidence_before INTEGER OPTIONAL,
1757 -- if the major status code that is returned is
1758 -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called
1759 -- with the same token before this time.
1760 -- This may be required, for example, in order to insure that
1761 -- the time skew between the evidence generation time and
1762 -- the trusted time service's countersignature on the evidence
1763 -- falls within the interval allowed by the current NR policy.
1764 o complete_evidence_after INTEGER OPTIONAL,
1765 -- if the major status code that is returned is
1766 -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called
1767 -- with the same token after this time.
1768 -- This may be required, for example, to insure that all
1769 -- authorities involved in generating the evidence have passed
1770 -- the last time at which the current NR policy allows them to
1771 -- repudiate their keys.
1772 o encapsulated_idu_buffer OCTET STRING
1773 -- if the IDU was present within the token
1774 o additional_unprotection BOOLEAN -- (see Section 2.3.2.5)
1776 Description:
1778 Verifies the validity and discloses the content of a nr_token.
1780 If the token containing the evidence to be verified was provided to
1781 the calling application by a partner responding to the calling
1782 application's request, then the calling application must pass the
1783 evidence check it received when it generated the request as a
1784 parameter along with the token it received from the partner.
1786 Output indicators are provided which give guidance about the time or
1787 times at which form_complete_pidu should be called; see the parameter
1788 descriptions for explanations of these indicators and their use. Note
1789 that the time specified by complete_evidence_before may be earlier
1790 than that specified by complete_evidence_after; in this case it will
1794 Adams Informational [Page 32]
1795 \f
1796 RFC 2479 IDUP-GSS-API December 1998
1799 be necessary to call form_complete_pidu twice.
1801 Because keys can be revoked or declared compromised, the return from
1802 verify_evidence cannot in all cases be a definitive "valid" or
1803 "invalid"; sometimes "conditionally valid" may be returned, depending
1804 upon the policy in use. IDUP_S_INCOMPLETE will be returned, for
1805 example, if:
1807 - the interval during which the generator of the evidence may
1808 permissibly declare his key invalid has not yet expired (and
1809 therefore it is possible that the evidence may be declared invalid
1810 in the future), or
1812 - trusted time is required for verification, and the time obtained
1813 from the token is not trusted.
1815 2.3.3.6. IDUP_EV_MultiBuffer_StartGenerate call
1817 Inputs:
1818 o env_handle ENVIRONMENT HANDLE,
1819 o nr_operation Nr_Operation,
1820 o Nr_Options PARAMETER BUNDLE,
1821 o form_complete_pidu BOOLEAN,
1822 o include_data_in_token BOOLEAN,
1823 o idu_size INTEGER, -- (see Section 2.3.4.2)
1824 o Request_Features PARAMETER BUNDLE
1825 o additional_protection BOOLEAN -- (see Section 2.3.2.4)
1827 Outputs:
1828 o major_status INTEGER,
1829 o minor_status INTEGER,
1830 o initial_pidu_buffer OCTET STRING
1831 -- may be empty (depends on underlying mechanism)
1833 Description:
1835 Using the security environment referenced by env_handle, initialize
1836 the data structures required to begin the generation of a token. The
1837 IDU will be supplied in multiple buffers to the
1838 IDUP_EV_Process_Buffer call). Two kinds of operations can be
1839 performed (using the Nr_Operation parameter) :
1841 a) generating a token that includes either an evidence only, or
1842 an evidence request only, or both an evidence and an evidence
1843 request.
1850 Adams Informational [Page 33]
1851 \f
1852 RFC 2479 IDUP-GSS-API December 1998
1855 b) generating a return token for some recipients that includes an
1856 evidence generated as a response to a request. In that case the
1857 received token will be passed into the subsequent
1858 IDUP_EV_Process_Buffer calls. The boolean include_data_in_token
1859 is ignored as the output will always be contained in a single
1860 token. The Request_Features are ignored in that case at this
1861 time in order to keep things simple and to avoid the piggy-
1862 backing that is theoretically possible.
1864 It is possible to request the generation of complete evidence. This
1865 may succeed or fail; if it fails, a subsequent call to
1866 Form_Complete_PIDU can be made.
1868 2.3.3.7. IDUP_EV_MultiBuffer_EndGenerate call
1870 Inputs:
1871 o env_handle ENVIRONMENT HANDLE
1873 Outputs:
1874 o major_status INTEGER,
1875 o minor_status INTEGER,
1876 o final_pidu OCTET STRING,
1877 o token OCTET STRING,
1878 o evidence_check OCTET STRING
1879 -- present only if an evidence is requested.
1881 Description:
1883 Using the security environment referenced by env_handle, provide the
1884 requested token or the final P-IDU. A token will be generated if
1885 encapsulation was not requested; otherwise, the final P-IDU is
1886 provided.
1888 2.3.3.8. IDUP_EV_MultiBuffer_StartVerify call
1890 Inputs:
1891 o env_handle ENVIRONMENT HANDLE,
1892 o token OCTET STRING,
1893 o evidence_check OCTET STRING,
1894 -- present only if an evidence has been previously requested.
1896 Outputs:
1897 o major_status INTEGER,
1898 o minor_status INTEGER
1906 Adams Informational [Page 34]
1907 \f
1908 RFC 2479 IDUP-GSS-API December 1998
1911 Description:
1913 Using the security environment referenced by env_handle, initialize
1914 the data structures required to begin the process of verifying the
1915 token. The P-IDU will be supplied in multiple buffers to the
1916 IDUP_EV_Process_Buffer call.
1918 2.3.3.9. IDUP_EV_MultiBuffer_EndVerify call
1920 Input:
1921 o env_handle ENVIRONMENT HANDLE
1923 Outputs:
1924 o major_status INTEGER,
1925 o minor_status INTEGER,
1926 o Nr_Options PARAMETER BUNDLE,
1927 o Originator_Information PARAMETER BUNDLE,
1928 o Request_Features PARAMETER BUNDLE,
1929 o trusted_time_stamping_time INTEGER OPTIONAL,
1930 o complete_evidence_before INTEGER OPTIONAL,
1931 o complete_evidence_after INTEGER OPTIONAL,
1932 o idu_buffer OCTET STRING
1933 -- if the IDU was present within the token
1934 o additional_unprotection BOOLEAN -- (see Section 2.3.2.5)
1936 Description:
1938 Using the security environment referenced by env_handle, complete the
1939 verification processing on the data and provide verified output
1940 parameters to the caller when the major status code is either:
1942 o GSS_S_COMPLETE or
1943 o IDUP_S_INCOMPLETE
1945 2.3.3.10. IDUP_EV_Process_Buffer call
1947 Inputs:
1948 o env_handle ENVIRONMENT HANDLE,
1949 o input_buffer OCTET STRING
1951 Outputs:
1952 o major_status INTEGER,
1953 o minor_status INTEGER,
1954 o output_buffer OCTET STRING
1955 -- may be zero length (depends on underlying mechanism and
1956 -- corresponding Generate () call and options
1957 -- (e.g., data_included_in_token)
1962 Adams Informational [Page 35]
1963 \f
1964 RFC 2479 IDUP-GSS-API December 1998
1967 Description:
1969 Using the security environment referenced by env_handle, continue the
1970 processing on the data in input_buffer and, if it is available, put
1971 any resulting output data in output_buffer. The application calls
1972 this routine over and over again with new buffers of data until it
1973 has processed all the data buffers of the IDU/PIDU. It then calls the
1974 appropriate End() call to complete the processing.
1976 2.3.4. The "GP" Calls
1978 The "GP" group of calls provides a powerful interface to flexible and
1979 sophisticated combinations of protection and unprotection services.
1980 This power and flexibility, however, necessitates a more complex
1981 interface than either the SE or the EV calls. Furthermore, such
1982 combinations of services are not needed in many of the security
1983 mechanisms in common use today (although this is likely to change as
1984 time goes on). The GP calls are therefore specified to be OPTIONAL
1985 and need not be supported by IDUP-conformant implementations. Note,
1986 however, that the structure of IDUP tokens should be such that the
1987 SE/EV and GP calls may be used interchangably by the receiver.
1989 2.3.4.1. Parameter Bundles
1991 The concept of "parameter bundles" is used in the calls presented in
1992 the following subsections in order to simplify their presentation and
1993 clarify their intended purpose and use (note that specific language
1994 bindings may or may not use parameter bundles for its actual calling
1995 conventions). A parameter bundle is simply a set of closely-related
1996 parameters of a call which are either all used by / available to the
1997 calling application or all not used by / unavailable to the calling
1998 application. These parameters may be all input parameters, all
1999 output parameters, or any combination of the two.
2001 An example use envisioned for parameter bundles in a language such as
2002 C would be as a structure, where individual parameters in the bundle
2003 are structure members. The calling application wishing to use a
2004 particular bundle would then allocate the appropriate structure
2005 variable, assign the desired input values to the appropriate members,
2006 and pass the address of the structure as the bundle "parameter". On
2007 output, the values of the appropriate output members may be read. An
2008 application not wishing to use a particular bundle (or one which is
2009 satisfied with default values for all input parameters of the bundle
2010 and which doesn't care about output values), can pass NULL as the
2011 bundle "parameter". From the mechanism implementor's perspective, if
2012 a parameter bundle is not supported (for example, if it represents a
2013 security service which is not supported by the implementation), then
2014 any non-NULL value passed as the bundle parameter will generate an
2018 Adams Informational [Page 36]
2019 \f
2020 RFC 2479 IDUP-GSS-API December 1998
2023 error status return code.
2025 [Note that the parameter bundles given below, except where explicitly
2026 referenced by the SE and EV calls, are specific to the (optional) GP
2027 calls. Thus, these bundles need not be supported by IDUP-conformant
2028 implementations if the GP calls are not supported.]
2030 The following parameter bundles are used in the subsequent protection
2031 and unprotection sets of calls. A parameter preceded by "(I)" is an
2032 input parameter; one preceded by "(O)" is an output parameter; one
2033 preceded by neither is an input if the bundle itself is an input and
2034 is an output if the bundle itself is an output; one preceded by "(X)"
2035 is the opposite: an output if the bundle itself is an input and an
2036 input if the bundle itself is an output.
2038 o Mech_Specific_Info PARAMETER BUNDLE
2039 -- actual parameters included in this bundle are defined by (and
2040 -- specific to) the underlying mechanism
2042 o Sensitivity PARAMETER BUNDLE,
2043 -- actual parameters included in this bundle are defined by (and
2044 -- specific to) the underlying mechanism, but may include
2045 -- codified values for "Unclassified", "Secret", "Top Secret",
2046 -- and so on
2048 o Service_Creation_Info PARAMETER BUNDLE
2049 -- actual parameters included in this bundle are defined by (and
2050 -- specific to) the underlying mechanism, but it is mandatory
2051 -- that they include at least service_id and Quality
2053 o Service_Verification_Info PARAMETER BUNDLE
2054 -- actual parameters included in this bundle are defined by (and
2055 -- specific to) the underlying mechanism, but it is mandatory
2056 -- that they include at least service_id and Quality
2058 o Quality PARAMETER BUNDLE
2059 o qop_algs UNSIGNED INTEGER,
2060 o qop_algID AlgorithmIdentifier, --overrides qop_algs
2061 o validity UNSIGNED INTEGER,
2062 -- protection guaranteed to be valid until time specified
2063 o policy_id OBJECT IDENTIFIER,
2064 -- security policy under which protection is/was carried out
2065 o allow_policy_mapping BOOLEAN,
2066 -- determines whether mapping between policy IDs is allowed
2067 o actual_policy_time INTEGER
2068 -- time at which the above policy rules came into effect
2074 Adams Informational [Page 37]
2075 \f
2076 RFC 2479 IDUP-GSS-API December 1998
2079 o Idu_Information PARAMETER BUNDLE,
2080 o idu_type_oid OBJECT IDENTIFIER,
2081 o idu_type_string OCTET STRING,
2082 o idu_title OCTET STRING,
2083 o idu_sensitivity Sensitivity,
2084 o pidu_type_oid OBJECT IDENTIFIER,
2085 o pidu_type_string OCTET STRING,
2086 o pidu_title OCTET STRING,
2087 o pidu_sensitivity Sensitivity,
2089 o Prot_Information PARAMETER BUNDLE,
2090 o originator_name INTERNAL NAME,
2091 o originator_role Originator_Role,
2092 o idu_information Idu_Information,
2093 o protection_time INTEGER,
2095 o Originator_Role PARAMETER BUNDLE, -- role in organization
2096 o domain_name INTERNAL NAME OPTIONAL,
2097 o role PRINTABLE STRING,
2098 o role_info_is_authenticated BOOLEAN
2099 -- TRUE if info. is authenticated (e.g., inside a cert.)
2101 o Special_Conditions PARAMETER BUNDLE,
2102 o prot_oper_id INTEGER,
2103 o form_complete_pidu BOOLEAN,
2104 -- input to protection operations for evidence generation
2105 o pidu_in_solic_service BOOLEAN,
2106 -- in protection operations, used as input for service
2107 -- solicitation to request that receiver include the
2108 -- received PIDU when generating the response. In unprot.
2109 -- operations, used as output to inform receiver that PIDU
2110 -- should be included when generating the response.
2111 o use_trusted_time BOOLEAN,
2112 o use_untrusted_time BOOLEAN,
2113 o mech_indep_encap_req BOOLEAN -- (see Appendix A)
2115 o Bad_Target_Name PARAMETER BUNDLE,
2116 o (O) bad_targ_name INTERNAL NAME,
2117 o (O) bad_targ_status INTEGER,
2118 -- a status flag giving the reason for rejection of
2119 -- the name in bad_targ_name. Specified reasons include:
2120 -- SYNTAX_INVALID (0)
2121 -- the syntax of the name is invalid;
2122 -- NAME_UNRECOGNIZED (1)
2123 -- the name is not recognized;
2124 -- NAME_AMBIGUOUS (2)
2125 -- the name cannot be resolved;
2126 -- ACCESS_DENIED (3)
2130 Adams Informational [Page 38]
2131 \f
2132 RFC 2479 IDUP-GSS-API December 1998
2135 -- access to this target is denied;
2136 -- CERTIFICATE_NOT_FOUND (4)
2137 -- the encryption certificate of the target could
2138 -- not be found.
2140 o Target_Info PARAMETER BUNDLE,
2141 o targ_names SET OF INTERNAL NAME,
2142 o (O) bad_targ_count INTEGER,
2143 o (O) bad_target_names SET OF Bad_Target_Name,
2145 o General_Service_Data PARAMETER BUNDLE,
2146 o target_info Target_Info,
2147 o (X) unencapsulated_token OCTET STRING,
2148 -- zero length if encapsulation_request is TRUE
2149 o (O) minor_status INTEGER,
2151 Three types of protection services are defined in IDUP. These are:
2153 1. perform unsolicited service (i.e., act on a locally-generated
2154 service request),
2155 2. perform solicited service (i.e., act on a remotely-generated
2156 service request), and
2157 3. perform service solicitation (i.e., send a service request to
2158 the remote end).
2160 As an originator, applying data confidentiality with data integrity,
2161 or data origin authentication with data integrity, or proof of origin
2162 evidence is an example of service type 1. As a target, creating a
2163 proof of delivery (i.e., receipt) evidence token as the result of a
2164 request received from the originator is an example of service type 2.
2165 Finally, as an originator, submitting a request that one or more
2166 targets return a receipt for the data sent is an example of service
2167 type 3.
2169 The first four parameters in the Prot_Service parameter bundle
2170 pertain to all service types; the fifth parameter is used if and only
2171 if service type 2 is desired; parameters 6-8 are used if and only if
2172 service type 3 is desired.
2174 o Prot_Service PARAMETER BUNDLE
2175 o (I) prot_service_type INTEGER,
2176 o (I) service_id OBJECT IDENTIFIER,
2177 o (I) quality Quality, -- NULL specifies default Quality
2178 o (I) general_service_data General_Service_Data,
2179 o (I) service_creation_info Service_Creation_Info,
2180 o (I) service_to SET OF INTERNAL NAME,
2181 o (O) service_verification_info Service_Verification_Info,
2182 o (O) service_verification_info_id INTEGER,
2186 Adams Informational [Page 39]
2187 \f
2188 RFC 2479 IDUP-GSS-API December 1998
2191 Also, three types of unprotection services are defined. These are:
2193 1. receive unsolicited service (i.e., process unrequested
2194 remotely-generated service),
2195 2. receive solicited service (i.e., process remotely-generated
2196 response to locally-generated request), and
2197 3. receive service solicitation (i.e., process req. from rem. end)
2199 As a target, unprotecting an encrypted message, or verifying the
2200 originator's proof of origin is an example of service type 1. As an
2201 originator, verifying a proof of delivery which you requested from a
2202 target is an example of service type 2. Finally, as a target,
2203 receiving a request from an originator for a proof of delivery is an
2204 example of service type 3.
2206 The first four parameters in the Unprot_Service parameter bundle
2207 pertain to all service types; parameters 5-6 are used if and only if
2208 service type 2 is required; parameters 7-8 are used only if service
2209 type 3 is required.
2211 o Unprot_Service PARAMETER BUNDLE
2212 o (O) unprot_service_type INTEGER,
2213 o (O) service_id OBJECT IDENTIFIER,
2214 o (O) quality Quality,
2215 -- actual Quality specified (never NULL)
2216 o (O) general_service_data General_Service_Data,
2217 o (O) service_verification_info_id INTEGER,
2218 o (I) service_verification_info Service_Verification_Info,
2219 o (O) service_to SET OF INTERNAL NAME,
2220 o (O) service_creation_info Service_Creation_Info,
2222 2.3.4.2. IDUP_Start_Protect call
2224 Inputs:
2225 o env_handle ENVIRONMENT HANDLE,
2226 o Mech_Specific_Info PARAMETER BUNDLE,
2227 -- NULL selects the mechanism-defined default values
2228 o Idu_Information PARAMETER BUNDLE,
2229 o Special_Conditions PARAMETER BUNDLE,
2230 o encapsulation_request BOOLEAN,
2231 o single_idu_buffer OCTET STRING,
2232 -- non-zero length for this buffer means that Protect/End_Protect
2233 -- won't be called (i.e., entire IDU is contained in this buffer)
2234 o idu_size INTEGER,
2235 -- size (in bytes) of the IDU to be protected;
2236 -- may be "-1" signifying "UNKNOWN" (note that some mechanisms
2237 -- may not support encapsulation in such a case)
2238 o Target_Info PARAMETER BUNDLE,
2242 Adams Informational [Page 40]
2243 \f
2244 RFC 2479 IDUP-GSS-API December 1998
2247 o Services_to_Perform SET OF Prot_Service,
2249 Outputs:
2250 o major_status INTEGER,
2251 o minor_status INTEGER,
2252 o midu_buffer OCTET STRING,
2253 -- zero length if encapsulation_request is TRUE;
2254 -- may be zero length otherwise (depends on underlying mechanism)
2255 o pidu_buffer OCTET STRING,
2256 -- zero length if encapsulation_request is FALSE;
2257 -- may be zero length otherwise (depends on underlying mechanism)
2259 Return major_status codes:
2260 o GSS_S_COMPLETE
2261 -- the protection process can begin (or has completed, if
2262 -- single_idu_buffer has non-zero length).
2263 o IDUP_S_MORE_OUTBUFFER_NEEDED
2264 o GSS_S_CREDENTIALS_EXPIRED
2265 o IDUP_S_NO_ENV
2266 o IDUP_S_ENCAPSULATION_UNAVAIL
2267 o IDUP_S_SERVICE_UNAVAIL
2268 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL
2269 o IDUP_S_UNKNOWN_OPER_ID
2270 o GSS_S_BAD_QOP
2271 o IDUP_S_BAD_TARG_INFO
2272 o GSS_S_FAILURE
2274 Using the security environment referenced by env_handle, initialize
2275 the data structures required to begin the process of protecting the
2276 IDU buffers. The caller requests specific protection services by
2277 supplying the appropriate Prot_Service parameter bundles in
2278 Services_to_Perform. Each service is able to return a minor status
2279 code to the calling application, if necessary.
2281 The calling application, knowing the size of the IDU it wishes to
2282 protect and the buffer size which it has available to it, can choose
2283 to input the entire IDU in a single buffer and omit the subsequent
2284 IDUP_Protect() and IDUP_End_Protect() calls. Furthermore, the
2285 application can request that the resulting M-IDU be encapsulated in
2286 the token -- so that the token contains the entire P-IDU -- rather
2287 than having it be returned separately in midu_buffer. Encapsulation,
2288 however, may not be supported by all underlying mechanisms or
2289 implementations; if this is the case, the
2290 IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and
2291 M-IDU will be returned in midu_buffer.
2298 Adams Informational [Page 41]
2299 \f
2300 RFC 2479 IDUP-GSS-API December 1998
2303 For those mechanisms which allow or require multiple stages of
2304 processing, each producing a different aspect of protection for the
2305 IDU, the operation identifier prot_oper_id is used to specify which
2306 stage is currently being requested by the application. An example
2307 where this would be useful is a mechanism which implements the signed
2308 Message Security Protocol [MSP]. As another example, a mechanism may
2309 choose to do a digital signature in two stages: one for the hashing
2310 of the message and another for the signature on the hash. The
2311 calling application would therefore use the protection set of calls
2312 on the IDU in stage 1 and then use the protection set of calls on the
2313 token (from stage 1) in stage 2.
2315 Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where
2316 "n" is the number of stages as defined by the mechanism (typically 1
2317 or 2)). The calling application uses this parameter to indicate to
2318 the underlying mechanism whether it wishes to do stage 1 of
2319 protection / unprotection processing, or stage 2, and so on. Portable
2320 applications may pass "0" to let the mechanism choose the stage (note
2321 that mechanism implementers may still iterate when prot_oper_id = 0
2322 (e.g., use output as next input, et cetera).
2324 If one or more of the targets in targ_names cannot be used as a valid
2325 recipient of the P-IDU, these names will be returned in
2326 bad_targ_names (with associated status codes in bad_targ_status). As
2327 long as at least one of the targets can be used, this does not cause
2328 this call to fail; it is the caller's choice to discontinue IDU
2329 protection if the target set which can be used is unsuitable for the
2330 caller's purposes. Note that each Prot_Service parameter bundle can
2331 also input a list of targ_names; this is used if a separate list is
2332 to be used for that service only (the general list of targets is to
2333 be used for all services unless overridden in this way).
2335 2.3.4.3. IDUP_Protect call
2337 Inputs:
2338 o env_handle ENVIRONMENT HANDLE,
2339 o input_buffer OCTET STRING,
2341 Outputs:
2342 o major_status INTEGER,
2343 o minor_status INTEGER,
2344 o output_buffer OCTET STRING
2345 -- may be zero length if encapsulation_request was set to TRUE in
2346 -- IDUP_Start_Protect() (depends on underlying mechanism)
2348 Return major_status codes:
2349 o GSS_S_COMPLETE
2350 o IDUP_S_NO_ENV
2354 Adams Informational [Page 42]
2355 \f
2356 RFC 2479 IDUP-GSS-API December 1998
2359 o GSS_S_FAILURE
2361 Using the security environment referenced by env_handle, continue the
2362 protection processing on the data in input_buffer and, if the
2363 underlying mechanism defines this, put any resulting P-IDU/M-IDU data
2364 in output_buffer. The application calls this routine over and over
2365 again with new buffers of data until it has protected all the data
2366 buffers of the IDU. It then calls IDUP_End_Protect() to complete the
2367 protection processing.
2369 2.3.4.4. IDUP_End_Protect call
2371 Inputs:
2372 o env_handle ENVIRONMENT HANDLE,
2374 Outputs:
2375 o major_status INTEGER,
2376 o minor_status INTEGER,
2377 o Services_to_Perform SET OF Prot_Service,
2378 o final_midu_buffer OCTET STRING,
2379 -- zero length if encapsulation_request was set to TRUE in
2380 -- IDUP_Start_Protect(), in which case pidu is used
2381 o final_pidu_buffer OCTET STRING,
2382 -- zero length if encapsulation_request was set to FALSE in
2383 -- IDUP_Start_Protect(), in which case token and midu are used
2385 Return major_status codes:
2386 o GSS_S_COMPLETE
2387 -- protection has successfully completed and the resulting P-IDU
2388 -- is ready for transfer. If defined by the underlying mechanism,
2389 -- final_midu_buffer will contain any residual M-IDU data.
2390 o IDUP_S_MORE_OUTBUFFER_NEEDED
2391 o IDUP_S_NO_ENV
2392 o GSS_S_FAILURE
2394 Using the security environment referenced by env_handle, complete the
2395 protection processing on the data and place the computed output in
2396 final_pidu_buffer (or final_midu_buffer and the unencapsulated_token
2397 parameter for each Prot_Service). If a service was requested from
2398 one or more targets in Start_Protect() - and if this is supported by
2399 the underlying mechanism - Service_Verification_Info will hold
2400 whatever data is necessary for the mechanism to verify a service
2401 returned by a target (unprotector) of the P-IDU. Successful
2402 application of IDUP_End_Protect() does not guarantee that the
2403 corresponding unprotection set of calls can necessarily be performed
2404 successfully when the P-IDU arrives at the target (for example, it
2405 may be damaged in transit).
2410 Adams Informational [Page 43]
2411 \f
2412 RFC 2479 IDUP-GSS-API December 1998
2415 2.3.4.5. IDUP_Start_Unprotect call
2417 Inputs:
2418 o env_handle ENVIRONMENT HANDLE,
2419 o Mech_Specific_Info PARAMETER BUNDLE,
2420 -- NULL selects the mechanism-defined default values
2421 o single_pidu_buffer OCTET STRING,
2422 -- non-zero length for this buffer means that IDUP_Unprotect() and
2423 -- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU
2424 -- (if encapsulation is used) or M-IDU (if encap. is not used)
2425 -- is contained in this buffer)
2426 o partial_pidu_buffer OCTET STRING,
2427 -- may be an arbitrary-sized piece of the full pidu (if the
2428 -- application's buffer isn't large enough to hold entire pidu).
2429 -- Used if pidu_buffer will be input a buffer at a time (except
2430 -- that the final buffer must be passed in final_pidu_buffer
2431 -- rather than partial_pidu_buffer). Only one of
2432 -- single_pidu_buffer and partial(final)_pidu_buffer can have
2433 -- nonzero length.
2434 o final_pidu_buffer OCTET STRING,
2435 o Special_Conditions PARAMETER BUNDLE,
2437 Outputs:
2438 o major_status INTEGER,
2439 o minor_status INTEGER,
2440 o Services_to_Receive SET OF Unprot_Service,
2441 o Prot_Information PARAMETER BUNDLE,
2442 o single_idu_buffer OCTET STRING,
2443 -- if this buffer has non-zero length, then service processing has
2444 -- been completed on the data in single_pidu_buffer
2445 o initial_idu_buffer OCTET STRING,
2446 -- holds any data from partial(final)_pidu_buffer which has been
2447 -- unprotected; remaining data will be returned by Unprotect and
2448 -- End_Unprotect as they are called with successive buffers of
2449 -- pidu
2450 o Service_Verification_Info PARAMETER BUNDLE,
2451 -- used only if target is on "service_to" list in Unprot_Service
2452 o service_verification_info_id INTEGER,
2453 -- used only if target is on "service_to" list in Unprot_Service
2466 Adams Informational [Page 44]
2467 \f
2468 RFC 2479 IDUP-GSS-API December 1998
2471 Return major_status codes:
2472 o GSS_S_COMPLETE
2473 -- unprotection processing can begin (or has completed, if
2474 -- single_idu_buffer has non-zero length).
2475 o IDUP_S_INCOMPLETE
2476 -- used only if single_idu_buffer has non-zero length.
2477 o IDUP_S_MORE_OUTBUFFER_NEEDED
2478 o IDUP_S_MORE_PIDU_NEEDED
2479 o GSS_S_DEFECTIVE_TOKEN
2480 o IDUP_S_INAPPROPRIATE_CRED
2481 o IDUP_S_INCONSISTENT_PARAMS
2482 o IDUP_S_DEFECTIVE_VERIF
2483 o IDUP_S_NO_MATCH
2484 o IDUP_S_SERVICE_UNAVAIL
2485 o IDUP_S_REQ_TIME_SERVICE_UNAVAIL
2486 o IDUP_S_SERV_VERIF_INFO_NEEDED
2487 o GSS_S_CREDENTIALS_EXPIRED
2488 o IDUP_S_NO_ENV
2489 o IDUP_S_UNKNOWN_OPER_ID
2490 o GSS_S_BAD_QOP
2491 -- the qop_algs value specified in P-IDU for at least one of the
2492 -- services is unavailable in the local mechanism, so processing
2493 -- cannot continue.
2494 o GSS_S_BAD_MIC
2495 o IDUP_S_BAD_DOA_KEY
2496 o IDUP_S_BAD_KE_KEY
2497 o IDUP_S_BAD_ENC_IDU
2498 o GSS_S_FAILURE
2500 Using the security environment referenced by env_handle, initialize
2501 the data structures required to begin the process of unprotecting a
2502 P-IDU. The caller will be alerted as to which services were applied
2503 to the P-IDU in the returned Services_to_Receive set of parameters.
2505 If encapsulation was not used by the originator, it is the receiving
2506 application's responsibility to separate the received P-IDU into a
2507 M-IDU and one or more unencapsulated_token buffers (the latter being
2508 input in separate Unprot_Service bundles in the Services_to_Receive
2509 parameter). These unencapsulated_token buffers should be input
2510 before the M-IDU (i.e., in IDUP_Start_Unprotect) or after the M-IDU
2511 (i.e., in IDUP_End_Unprotect) as appropriate; this order may be
2512 dictated, for example, by their placement in the in-coming message.
2514 If unprotection will be applied more than once to a given P-IDU, it
2515 is the responsibility of the calling application to remember if a
2516 service solicitation has been responded to previously (i.e., if the
2517 requested service has already been generated / sent for that P-IDU)
2518 and thus ignore subsequent solicitations on unprotect.
2522 Adams Informational [Page 45]
2523 \f
2524 RFC 2479 IDUP-GSS-API December 1998
2527 The time flags indicate whether to consult trusted, untrusted, or no
2528 time (if both flags are FALSE) during the unprotection operation. If
2529 the current time is not to be checked, then unprotection may be
2530 successful even if the protector's key has expired since the P-IDU
2531 was generated (that is, if the Validity period -- as specified in the
2532 Quality parameter bundle -- has expired).
2534 If the underlying mechanism supports it and if this information is
2535 contained in the P-IDU, information regarding the originator (that
2536 is, the entity which used the protection set of calls to generate
2537 this P-IDU) is returned in the Prot_Information parameter bundle.
2539 2.3.4.6. IDUP_Unprotect call
2541 Inputs:
2542 o env_handle ENVIRONMENT HANDLE,
2543 o input_buffer OCTET STRING
2545 Outputs:
2546 o major_status INTEGER,
2547 o minor_status INTEGER,
2548 o output_buffer OCTET STRING
2550 Return major_status codes:
2551 o GSS_S_COMPLETE
2552 o IDUP_S_NO_ENV
2553 o GSS_S_FAILURE
2555 Using the security environment referenced by env_handle, continue the
2556 unprotection processing on the data in input_buffer, putting any
2557 resulting IDU data in output_buffer (if required).
2559 2.3.4.7. IDUP_End_Unprotect call
2561 Inputs:
2562 o env_handle ENVIRONMENT HANDLE,
2564 Outputs:
2565 o major_status INTEGER,
2566 o minor_status INTEGER,
2567 o Prot_Information PARAMETER BUNDLE,
2568 o Services_to_Receive SET OF Unprot_Service,
2569 o final_idu_buffer OCTET STRING,
2570 o Service_Verification_Info PARAMETER BUNDLE,
2571 -- used only if target is on "service_to" list in Unprot_Service
2572 o service_verification_info_id INTEGER,
2573 -- used only if target is on "service_to" list in Unprot_Service
2578 Adams Informational [Page 46]
2579 \f
2580 RFC 2479 IDUP-GSS-API December 1998
2583 Return major_status codes:
2584 o GSS_S_COMPLETE
2585 -- residual IDU data will be returned in final_idu_buffer.
2586 o IDUP_S_INCOMPLETE
2587 o IDUP_S_MORE_OUTBUFFER_NEEDED
2588 o GSS_S_BAD_MIC
2589 o IDUP_S_BAD_DOA_KEY
2590 o IDUP_S_BAD_KE_KEY
2591 o IDUP_S_BAD_ENC_IDU
2592 o IDUP_S_NO_ENV
2593 o GSS_S_FAILURE
2595 Using the security environment referenced by env_handle, complete the
2596 unprotection processing on the data and return the appropriate status
2597 code. If there is any residual IDU data it will be returned in
2598 final_idu_buffer.
2600 If the IDUP_S_INCOMPLETE major status value is returned, all output
2601 parameters are conditionally valid; the unprotection set of functions
2602 will have to be called again (perhaps with a complete P-IDU, as
2603 produced by IDUP_Form_Complete_PIDU) in order to get valid values for
2604 all parameters. "Conditional validity" may arise, for example, if
2605 all relevant certificates verify correctly, but it is not yet past
2606 the time up to which the current policy allows the authorities
2607 involved to repudiate their keys.
2609 If the underlying mechanism supports it and if this information is
2610 contained in the token, information regarding the originator (that
2611 is, the entity which used the protection set of calls to generate
2612 this token) is returned in the Prot_Information parameter bundle.
2613 This information may or may not be omitted if it was returned by the
2614 IDUP_Start_Unprotect() call.
2616 Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the
2617 concept of error tokens transferred between sender and recipient
2618 since the protection and unprotection of an IDU may be separated by
2619 an indefinite amount of time and may or may not be performed by the
2620 same entity.
2622 2.4. Special-Purpose Calls
2624 2.4.1. Relationship to GSS-API
2626 The special-purpose call described in this section has no analog in
2627 GSS-API [RFC-2078]. This call is used to complete a P-IDU (that is,
2628 to generate a P-IDU which can be unprotected successfully with no
2629 additional data at any time during its validity period). This call
2630 may not be supported by all underlying IDUP mechanisms or
2634 Adams Informational [Page 47]
2635 \f
2636 RFC 2479 IDUP-GSS-API December 1998
2639 implementations.
2641 2.4.2. IDUP_Form_Complete_PIDU call
2643 Inputs:
2644 o env_handle ENVIRONMENT HANDLE,
2645 o single_pidu_buffer OCTET STRING,
2646 o partial_pidu_buffer OCTET STRING,
2647 -- an arbitrary-sized piece of the full pidu token. Used if pidu
2648 -- will be input a buffer at a time (except that the final buffer
2649 -- must be passed in final_pidu_buffer rather than
2650 -- partial_pidu_buffer). Only one of single_pidu_buffer and
2651 -- partial(final)_pidu_buffer can have nonzero length.
2652 o final_pidu_buffer OCTET STRING,
2654 Outputs:
2655 o major_status INTEGER,
2656 o minor_status INTEGER,
2657 o pidu_token_out OCTET STRING -- the augmented PIDU; may be complete
2658 o call_again_before INTEGER,
2659 o call_again_after INTEGER,
2660 o trusted_time_stamping_time INTEGER -- for information only
2662 Return major_status codes:
2663 o GSS_S_COMPLETE
2664 o IDUP_S_MORE_OUTBUFFER_NEEDED
2665 o IDUP_S_INCOMPLETE
2666 -- generation of the P-IDU is not yet complete. The application
2667 -- should call this function again before the time given in
2668 -- call_again_before (if not NULL), or after the time given in
2669 -- call_again_after (if not NULL), or both (if neither are NULL).
2670 o IDUP_S_INCONSISTENT_PARAMS
2671 o IDUP_S_SERVICE_UNAVAIL
2672 o GSS_S_DEFECTIVE_TOKEN
2673 o GSS_S_FAILURE
2675 Form_Complete_PIDU is used primarily by the evidence services; in
2676 particular, when the evidence token itself does not contain all the
2677 data required for its verification and it is anticipated that some of
2678 the data not stored in the token may become unavailable during the
2679 interval between generation of the evidence token and verification
2680 unless it is stored in the token. The Form_Complete_PIDU operation
2681 gathers the missing information and includes it in the token so that
2682 verification can be guaranteed to be possible at any future time.
2684 This call generates a PIDU which can be unprotected successfully with
2685 no additional data at any time during its validity period. [For
2686 background information on the notion of "complete" evidence, see
2690 Adams Informational [Page 48]
2691 \f
2692 RFC 2479 IDUP-GSS-API December 1998
2695 "CORBA Security Service v1.2 Draft D02", 18 June 1997.]
2697 Using the security environment referenced by env_handle, complete the
2698 generation of a P-IDU token and return the appropriate status value
2699 along with the completed token (if available). Such a call may be
2700 used, for example, for the purpose of batch evidence generation on an
2701 "evidence server". A local machine may be able to use the protection
2702 set of calls to fill out most of an evidence token and then send a
2703 number of these to a batch processor which forms the complete
2704 evidence tokens (perhaps by adding a certification path, or a
2705 timestamp and signature from a timestamping authority). As another
2706 example, on the receiving end an application may make such a call in
2707 order to collect all the information necessary to unprotect a P-IDU
2708 (such as all relevant certificates and Certificate Revocation Lists);
2709 this will ensure that the calls to the unprotection set of operations
2710 will be entirely local (i.e., can be performed off-line) and fast.
2712 Note that the complete P-IDU generated will be formed using trusted
2713 time if this is available in the environment referenced by env_handle
2714 and will use untrusted time or no time otherwise (depending on what
2715 is available).
2717 2.5. Support calls
2719 2.5.1. Relationship to GSS-API
2721 Support calls in IDUP-GSS-API are to be understood and used as
2722 described in GSS-API [RFC-2078]. The calls described in Section 2.4
2723 of GSS-API (including all associated parameters) are unchanged. The
2724 following additional calls are specified for IDUP-GSS-API.
2726 2.5.2: IDUP_Acquire_cred_with_auth call
2728 Inputs:
2729 o desired_name INTERNAL NAME,
2730 -- NULL requests locally-determined default
2731 o authenticator OCTET STRING
2732 -- string which authenticates the caller claiming to be
2733 -- desired_name
2734 o lifetime_req INTEGER,
2735 -- in seconds; 0 requests default
2736 o desired_mechs SET OF OBJECT IDENTIFIER,
2737 -- empty set requests system-selected default
2738 o cred_usage BIT STRING
2739 -- actual values which can be used currently correspond to those
2740 -- given in Section 2.1.1 (i.e.,
2741 -- ENCRYPT_ONLY 8
2742 -- DECRYPT_ONLY 16
2746 Adams Informational [Page 49]
2747 \f
2748 RFC 2479 IDUP-GSS-API December 1998
2751 -- SIGN_ONLY 32
2752 -- VERIFY_ONLY 64
2753 -- with the values logically OR'ed together in any desired
2754 -- combination to restrict credential usage; OR'ing all values
2755 -- results in NO_RESTRICTION).
2756 -- Future possible values for this parameter are for further
2757 -- study (note that the type of this parameter is BIT STRING
2758 -- (rather than INTEGER as in GSS_Acquire_cred) to facilitate
2759 -- such future expansion).
2761 Outputs:
2762 o major_status INTEGER,
2763 o minor_status INTEGER,
2764 o output_cred_handle CREDENTIAL HANDLE,
2765 o actual_mechs SET OF OBJECT IDENTIFIER,
2766 o actual_cred_usage BIT STRING,
2767 o lifetime_rec INTEGER
2768 -- in seconds, or reserved value for INDEFINITE
2770 This call (which need not be supported by all underlying mechanisms
2771 or implementations) is identical to the GSS_Acquire_cred call, with
2772 the exception of the added input parameter "authenticator" and the
2773 added output parameter "actual_cred_usage". The authenticator
2774 (typically a password, pass-phrase, or PIN) is used to authenticate
2775 the caller claiming to be desired_name to the underlying GSS (or
2776 mechanism) code. The actual_cred_usage specifies the actual uses
2777 available for these credentials; it is up to the caller to determine
2778 if this is sufficient for its purposes.
2780 Implementations that are able to authenticate the caller in some
2781 other way are encouraged to use the GSS_Acquire_cred call; those
2782 having no other means available to them, or wishing to explicitly
2783 authenticate the caller at the time of credential acquisition, should
2784 use the IDUP_Acquire_cred_with_auth call (if supported).
2786 Note that the return major status codes for this call are identical
2787 to those given for the GSS_Acquire_cred call. If the authentication
2788 fails (e.g., the wrong authenticator is supplied for the given
2789 desired_name), the major status GSS_S_FAILURE is returned (along with
2790 an appropriate minor status code).
2792 2.5.3. IDUP_Get_token_details call
2794 Inputs:
2795 o token OCTET STRING,
2796 -- all the data to be returned shall be within the first 4 KB of
2797 -- the token; hence, a single call is needed. It is not necessary
2798 -- to provide the entire token when the token includes the IDU.
2802 Adams Informational [Page 50]
2803 \f
2804 RFC 2479 IDUP-GSS-API December 1998
2807 o mech_type SET OF OBJECT IDENTIFIER
2808 -- input if known (typically SET will contain a single member)
2810 Outputs:
2811 o major_status INTEGER,
2812 o minor_status INTEGER,
2813 o actual_mech_type OBJECT IDENTIFIER,
2814 o data_included_in_token BOOLEAN,
2815 -- true if the data is encapsulated
2816 o idu_size INTEGER,
2817 o has_SE_protection BOOLEAN,
2818 o has_EV_protection BOOLEAN,
2819 o PIDU_Information PARAMETER BUNDLE,
2820 o nr_policy OBJECT IDENTIFIER,
2821 -- this and subsequent parameters pertain only to evidence tokens
2822 o Nr_Options PARAMETER BUNDLE,
2823 o Originator_Information PARAMETER BUNDLE,
2824 o time_stamping_time INTEGER OPTIONAL
2825 o Request_Features PARAMETER BUNDLE,
2826 -- describes the included request, if any.
2827 o requested_evidence_back BOOLEAN,
2828 -- true if this is an evidence generated in response to a
2829 -- previously-sent request
2830 o evidence_check OCTET STRING,
2831 -- meaningful if the boolean above is true
2833 Return major_status codes:
2834 o GSS_S_COMPLETE
2835 -- input_token could be parsed for all relevant fields.
2836 o GSS_S_CREDENTIALS_EXPIRED
2837 o GSS_S_DEFECTIVE_TOKEN
2838 -- the mechanism type could be parsed, but either the other fields
2839 -- could not be determined from the input_token, or their values
2840 -- did not correspond to valid values for that mechanism.
2841 o GSS_S_FAILURE
2842 -- the mechanism type was missing or corrupted.
2844 IDUP_Get_token_details() is used to return to an application the
2845 attributes that correspond to a given input token. Since IDUP-GSS-
2846 API tokens are meant to be opaque to the calling application, this
2847 function allows the application to determine information about the
2848 token without having to violate the opaqueness intention of IDUP. Of
2849 primary importance is the mechanism type, which the application can
2850 then use as input to the IDUP_Establish_Env() call in order to
2851 establish the correct environment in which to have the token
2852 processed.
2858 Adams Informational [Page 51]
2859 \f
2860 RFC 2479 IDUP-GSS-API December 1998
2863 If all tokens are framed as suggested in Section 3.1 of [RFC-2078]
2864 (mandated in the Kerberos V5 GSS mechanism [RFC 1964] and in the SPKM
2865 GSS Mechanism [RFC 2025]), then any mechanism implementation should
2866 be able to return the mech_type parameter for any uncorrupted input
2867 token. If the mechanism implementation whose IDUP_Get_token_details()
2868 function is being called does recognize the token, it can return any
2869 further relevant information in the other token attributes, as
2870 specified. In particular, this function can set has_SE_protection if
2871 the SE calls may be used to unprotect it, or has_EV_protection if the
2872 EV calls may be used to unprotect it, or both if both kinds of
2873 protection have been applied (so that SE or EV calls may be used in
2874 any order for unprotection) [note that GP calls, when supported,
2875 should be usable for unprotection of any IDUP token].
2877 IDUP_Get_token_details (which need not be supported by all underlying
2878 mechanisms or implementations) gives only a hint about the content of
2879 the token, there is no integrity check of any kind performed.
2880 Regardless of the token type, it is possible to check that this
2881 information is correct only by doing a proper unprotection of the
2882 token. It is recommended that IDUP callers supply a token buffer at
2883 least 4 KB in length in order to ensure that the desired data can
2884 easily flow across this interface.
2886 The OID of the mechanism and whether the token contains the
2887 associated data is returned. In addition the size of the associated
2888 data, whether inside or outside the token, is included if known.
2889 [Note: data size will typically be unknown if the data was protected
2890 using multibuffer calls. A value of "-1" may be used to indicate
2891 "UNKNOWN".]
2893 When the input token contains only an evidence generated
2894 spontaneously, the following is returned:
2895 - the evidence type;
2896 - the Non-Repudiation policy under which the evidence was generated;
2897 - the name of the generator of the evidence;
2898 - the date and time when the evidence was generated (if available);
2899 - the date and time when it was time stamped (if available).
2901 When the input token contains only an evidence generated in response
2902 to a request from another entity, the following additional
2903 information is returned:
2904 - an indicator to state that this evidence relates to a request;
2905 - a string significant for the requester that will allow him to
2906 check whether the answer corresponds to the requested evidence.
2908 When the input token only contains a request, the following is
2909 returned:
2910 - the name of the requestor of the evidence,
2914 Adams Informational [Page 52]
2915 \f
2916 RFC 2479 IDUP-GSS-API December 1998
2919 - the date and time when the request was made,
2920 - the evidence type to send back,
2921 - the non-repudiation policy under which the evidence to send back
2922 should be generated,
2923 - the names of the recipients which should generate and distribute
2924 the requested evidence,
2925 - the names of the recipients to whom the requested evidence should
2926 be sent after it has been generated.
2928 When the input token contains both evidence and a request, an
2929 indicator is returned describing whether the new evidence should be
2930 generated using only the data in the input token, or using both the
2931 data and the evidence in the input token.
2933 When the input token contains only CONF and DOA services, the
2934 PIDU_Information bundle is returned. Other relevant parameters (such
2935 as idu_size and time_stamping_time) may also be returned if this data
2936 is available.
2938 2.5.4. IDUP_Get_policy_info call
2940 Inputs:
2941 o policy_id OBJECT IDENTIFIER
2943 Outputs:
2944 o major_status INTEGER,
2945 o minor_status INTEGER,
2946 o policy_version INTEGER,
2947 o policy_effective_time INTEGER,
2948 o policy_expiry_time INTEGER,
2949 o supported_services SET OF Service_Descriptor,
2950 -- services supported by this particular policy_id (equal to the
2951 -- intersection of the services supported by the mechanisms
2952 -- listed in supported_mechanisms)
2953 o supported_mechanisms SET OF Mechanism_Descriptor
2954 -- mechanisms supported by this particular policy_id
2956 Return major_status codes:
2957 o GSS_S_COMPLETE
2958 -- policy_id recognized; all relevant fields have been returned.
2959 o GSS_S_FAILURE
2960 -- the policy_id was not recognized.
2962 This call (which need not be supported by all underlying mechanisms
2963 or implementations) allows the application to retrieve information
2964 pertaining to a given policy_id. Policies define the following:
2965 - rules for the protection of IDUs, such as trusted third
2966 parties which may be involved in P-IDU generation, the roles in
2970 Adams Informational [Page 53]
2971 \f
2972 RFC 2479 IDUP-GSS-API December 1998
2975 which they may be involved, and the duration for which the
2976 generated P-IDU is valid;
2978 - rules for the unprotection of P-IDUs, such as the interval
2979 during which a trusted third party may legitimately declare its
2980 key to have been compromised or revoked; and
2982 - rules for adjudication, such as which authorities may be used
2983 to adjudicate disputes.
2985 The policy itself may be used by an adjudicator when resolving a
2986 dispute. For example, the adjudicator might refer to the policy to
2987 determine whether the rules for generation of the P-IDU have been
2988 followed.
2990 The following parameter bundles are associated with this call.
2992 o Service_Descriptor PARAMETER BUNDLE,
2993 o service_type OBJECT IDENTIFIER,
2994 o service_validity_duration INTEGER,
2995 o must_use_trusted_time BOOLEAN
2997 o Mechanism_Descriptor PARAMETER BUNDLE,
2998 o mechanism_type OBJECT IDENTIFIER,
2999 o Authority_List PARAMETER BUNDLE,
3000 o maximum_time_skew INTEGER
3001 -- maximum permissible difference between P-IDU generation
3002 -- time and the time of countersignature from a time
3003 -- service (if required). This parameter is unused if
3004 -- trusted time is not required.
3006 o Authority_List PARAMETER BUNDLE,
3007 o authority_name INTERNAL NAME,
3008 o authority_role OCTET STRING,
3009 o last_revocation_check_offset INTEGER
3010 -- may be 0, greater than 0, or less than 0. The value of
3011 -- this parameter is added to P-IDU generation time to
3012 -- get latest time at which the mechanism will check to
3013 -- see if this authority's key has been revoked.
3015 An example of the use of the last parameter in Authority_List is as
3016 follows. If an authority has a defined last_revocation_check_offset
3017 of negative one hour, then all revocations taking effect earlier than
3018 one hour before the generation of a P-IDU will render that P-IDU
3019 invalid; no revocation taking place later than one hour before the
3020 generation of the P-IDU will affect the P-IDU's validity.
3026 Adams Informational [Page 54]
3027 \f
3028 RFC 2479 IDUP-GSS-API December 1998
3031 Note that both the maximum_time_skew and the
3032 last_revocation_check_offset values are given in minutes.
3034 2.5.5. IDUP_Cancel_multibuffer_op call
3036 Inputs:
3037 o env_handle ENVIRONMENT HANDLE,
3039 Outputs:
3040 o major_status INTEGER,
3041 o minor_status INTEGER,
3043 Return major_status codes:
3044 o GSS_S_COMPLETE
3045 -- operation cancelled; state purged.
3046 o GSS_S_FAILURE
3047 -- unable to cancel operation; state retained.
3049 This call (which need not be supported by all underlying mechanisms
3050 or implementations) allows the application to cancel a multibuffer
3051 operation prior to normal completion (e.g., subsequent to calling
3052 Start_operation and zero or more Process_operation, but prior to
3053 calling End_operation). When successful, this call purges any
3054 internal state information which would have been used to continue
3055 processing for the full set of multibuffer calls.
3057 3. Related Activities
3059 In order to implement the IDUP-GSS-API atop existing, emerging, and
3060 future security mechanisms, the following is necessary:
3062 - object identifiers must be assigned to candidate IDUP-GSS-API
3063 mechanisms and the name types which they support; and
3065 - concrete data element (i.e., token and parameter bundle) formats
3066 must be defined for candidate mechanisms.
3068 Calling applications must implement formatting conventions which will
3069 enable them to distinguish IDUP-GSS-API P-IDUs from other IDUs in
3070 their environment.
3072 Concrete language bindings are required for the programming
3073 environments in which the IDUP-GSS-API is to be employed.
3082 Adams Informational [Page 55]
3083 \f
3084 RFC 2479 IDUP-GSS-API December 1998
3087 4. Acknowledgments
3089 Many thanks are due to Tim Moses and Dhanya Thakkar of Entrust
3090 Technologies, Denis Pinkas of Bull, and David Kurn of Tandem
3091 Computers for a number of helpful comments and contributions.
3093 5. Security Considerations
3095 Security issues are discussed throughout this memo.
3097 6. REFERENCES
3099 [MSP] U.S. National Security Agency, "Message Security
3100 Protocol", Secure Data Network System SDN.701, March
3101 1994.
3103 [RFC-1421] Linn, J., "Privacy Enhancement for Internet Electronic
3104 Mail: Part I: Message Encryption and Authentication
3105 Procedures", RFC 1421, February 1993.
3107 [RFC-2078] Linn, J., "Generic Security Service Application Program
3108 Interface, Version 2", RFC 2078, January 1997..
3110 [RFC 1964] Linn, J, "The Kerberos Version 5 GSS-API Mechanism", RFC
3111 1964, June 1996.
3113 [RFC 2025] Adams, C., "The Simple Public-Key GSS-API Mechanism
3114 (SPKM)", RFC 2025, October 1996.
3116 [ISO/IEC] 2nd ISO/IEC CD 13888-1, "Information technology -
3117 Security techniques - Non-repudiation - Part 1: General
3118 Model", ISO/IEC JTC 1/SC 27, May 30, 1995
3120 7. Author's Address
3122 Carlisle Adams
3123 Entrust Technologies
3124 750 Heron Road, Suite E08,
3125 Ottawa, Ontario, CANADA K1V 1A7
3127 Phone: +1 613.247.3180
3128 EMail: cadams@entrust.com
3138 Adams Informational [Page 56]
3139 \f
3140 RFC 2479 IDUP-GSS-API December 1998
3143 APPENDIX A: MECHANISM-INDEPENDENT TOKEN FORMAT
3145 This appendix specifies the use, for IDUP-GSS-API tokens, of the
3146 mechanism-independent level of encapsulating representation for
3147 tokens given in Section 3.1 of GSS-API [RFC-2078]. The
3148 representation given there incorporates an identifier of the
3149 mechanism type to be used when processing the associated tokens. Use
3150 of that octet format is recommended to the designers of IDUP-GSS-API
3151 implementations based on various mechanisms so that tokens can be
3152 interpreted unambiguously at IDUP-GSS-API peers. It is recognized,
3153 however, that for interoperability purposes with peers not using IDUP
3154 for specific IDU protection/unprotection protocols, the encapsulating
3155 representation may need to be omitted. (In such a case it is
3156 necessary that the underlying mechanism provides some sort of
3157 internal or external identification that allows it to recognize its
3158 own tokens.) When the mechanism-independent level of encapsulating
3159 representation is not desired, callers SHOULD set
3160 mech_indep_encap_req to FALSE (note that some underlying mechanisms
3161 may default this parameter to FALSE).
3163 For purely descriptive purposes, the following simple ASN.1 structure
3164 is used to illustrate the structural relationships among token and
3165 tag objects. For interoperability purposes, token and tag encoding
3166 shall be performed using the concrete encoding procedures described
3167 in Section 3.1 of GSS-API [RFC-2078].
3169 -- top-level token definition to frame different mechanisms
3171 IDUP-GSS-API DEFINITIONS ::=
3172 BEGIN
3173 MechType ::= OBJECT IDENTIFIER
3175 Token ::= [APPLICATION 0] IMPLICIT SEQUENCE {
3176 thisMech MechType,
3177 token ANY DEFINED BY thisMech
3178 -- contents mechanism-specific
3179 }
3180 END
3194 Adams Informational [Page 57]
3195 \f
3196 RFC 2479 IDUP-GSS-API December 1998
3199 APPENDIX B: EXAMPLES OF IDUP USE
3201 This appendix provides examples of the use of IDUP to do IDU
3202 protection and unprotection. It should not be regarded as
3203 constrictive to implementations or as defining the only means through
3204 which IDUP-GSS-API functions can be realized with particular
3205 underlying technology, and does not demonstrate all IDUP-GSS-API
3206 features.
3208 Most of the examples below only illustrate the use of CONF/DOA
3209 protection services. Note that when both CONF/DOA and Evidence
3210 services are required, calling applications may use a series of SE
3211 and EV calls, or may use the GP calls (when these are supported).
3212 Using the former approach implies multiple calls (e.g., the SE calls
3213 are used to protect some data and the resulting token is then input
3214 to the EV calls to add evidence information), but some callers may
3215 find this to be more attractive than coding to the GP calls because
3216 of the simpler SE/EV interface. Depending upon the underlying
3217 mechanism, the series of SE/EV calls may result in a single token
3218 that can be unprotected using the SE and EV calls in any order (for
3219 example, because it is a single ASN.1 SEQUENCE that incorporates all
3220 the specified protection services at one level), or the series may
3221 result in a token that can only be unprotected in the reverse order
3222 of protection (for example, because each SE/EV output token was
3223 effectively embedded in the token of the subsequent call). The
3224 IDUP_Get_token_details call can assist callers in determining how to
3225 unprotect any received token.
3227 B.1. Simple Mechanism, Single Buffer
3229 To illustrate the simplest possible case, consider an underlying IDUP
3230 mechanism which does straightforward encryption/decryption and
3231 signing/verification only using public-key techniques; none of the
3232 other possible services, such as creation of proof-of-origin
3233 evidence, requests for proof-of-delivery evidence, or use of trusted
3234 time, are supported. PEM[RFC-1421] is one example of a mechanism
3235 which fits this description. Furthermore (again for simplicity),
3236 assume that encapsulation is chosen by the calling application during
3237 IDU protection.
3239 Such a mechanism would likely use the "SE" set of IDUP-GSS-API calls.
3240 The following parameter bundle uses and defaults would therefore be
3241 specified in the relevant IDUP mechanism document.
3250 Adams Informational [Page 58]
3251 \f
3252 RFC 2479 IDUP-GSS-API December 1998
3255 SENDER:
3257 Set
3258 env_handle = environment handle in use;
3259 idu_buffer = data buffer;
3260 Target_Info.targ_names = receiver names;
3261 Protect_Options = as necessary;
3263 Call
3264 IDUP_SE_SingleBuffer_Protect() with above input parameters
3266 Check
3267 major_status. If not GSS_S_COMPLETE, check
3268 minor_status,
3269 Target_Info.Bad_Targ_Name,
3270 (as required) for more detailed information.
3272 Send
3273 Output parameter pidu_buffer to receiver.
3275 RECEIVER (any parameters not listed below are given the value NULL):
3277 Set
3278 env_handle = environment handle in use;
3279 pidu_buffer = received data buffer;
3281 Call
3282 IDUP_SE_SingleBuffer_Unprotect() with above input parameters
3283 Check
3284 major_status. If not GSS_S_COMPLETE, check
3285 minor_status,
3286 (as required) for more detailed information
3288 Utilize
3289 PIDU_Information.Protect_Options.Protect_Operation,
3290 (to determine which services were applied by the originator)
3291 PIDU_Information.Protect_Options.sign_qop_alg / enc_qop_alg,
3292 (to determine the corresponding qualities of the services)
3293 Prot_Information.originator_name,
3294 (to determine the name of the originator)
3295 Prot_Information.protection_time,
3296 (to determine when the IDU was protected)
3297 idu_buffer
3298 (to retrieve the unprotected data).
3306 Adams Informational [Page 59]
3307 \f
3308 RFC 2479 IDUP-GSS-API December 1998
3311 B.2. Simple Mechanism, Single Buffer (Again)
3313 To illustrate a slight variation on the simplest possible case,
3314 assume that everything is as in the previous scenario except that the
3315 "GP" calls are used.
3317 The following parameter bundle uses and defaults would therefore be
3318 specified in the relevant IDUP mechanism document.
3320 Mech_Specific_Info
3321 - NOT USED (the only acceptable input, therefore, is NULL)
3323 Idu_Sensitivity
3324 - NOT USED (the only acceptable input, therefore, is NULL)
3326 Service_Creation_Info
3327 - NOT USED (the only acceptable input, therefore, is NULL)
3329 Service_Verification_Info
3330 - NOT USED (the only acceptable input, therefore, is NULL)
3332 Quality
3333 - the qop_algs parameter must be supported, with a suitable
3334 DEFAULT value specified;
3335 - suitable DEFAULT values for validity, policy_id, and
3336 allow_policy_mapping must be specified (it may be an
3337 implementation option as to whether these parameters are
3338 explicitly modifiable by the calling application, or whether
3339 NULLs are the only acceptable input)
3341 Idu_Information
3342 - the idu_type parameter must have a value representing a suitable
3343 IDU type (for example, in PEM a value representing the string
3344 "RFC822" or some other valid "Content-Domain" would be used),
3345 with a suitable DEFAULT value specified;
3346 - the idu_title parameter is NOT USED (the only acceptable input,
3347 therefore, is NULL)
3349 Prot_Information
3350 - the originator_name and idu_type (in Idu_Information) parameters
3351 are read from the encapsulating information and output by
3352 IDUP_Start_Unprotect;
3353 - all other parameters are NOT USED (and therefore NULL)
3355 Special_Conditions
3356 - NOT USED (the only acceptable input, therefore, is NULL)
3362 Adams Informational [Page 60]
3363 \f
3364 RFC 2479 IDUP-GSS-API December 1998
3367 Target_Info
3368 - this bundle is used as described in IDUP; no DEFAULT values are
3369 specified
3371 General_Service_Data
3372 - the unencapsulated_token parameter is used if
3373 encapsulation_request is FALSE;
3374 - the minor_status parameter is used to return minor status values
3375 as specified by the mechanism document
3377 Prot_Service
3378 - the prot_service_type parameter may have a value of "1"
3379 ("perform unsolicited service") or NULL (which specifies the
3380 DEFAULT value of "1");
3381 - the service_id parameter must have a value representing
3382 "PER_CONF" or "PER_DOA";
3383 - the parameters Service_Creation_Info, service_to,
3384 Service_Verification_Info, and service_verification_info_id are
3385 NOT USED (and therefore NULL)
3387 Unprot_Service
3388 - the unprot_service_type parameter will always have a value of
3389 "1" ("receive unsolicited service");
3390 - the service_id parameter will have a value representing
3391 "REC_CONF" or "REC_DOA";
3392 - the parameters service_verification_info_id,
3393 Service_Verification_Info, service_to, and
3394 Service_Creation_Info, are NOT USED (and therefore NULL)
3396 Assuming that the calling application has only a single buffer of
3397 data to protect/unprotect, the following sequence of operations must
3398 be performed by the sender and receivers (subsequent to environment
3399 establishment).
3401 SENDER (any parameters not listed below are given the value NULL):
3403 Set
3404 env_handle = environment handle in use;
3405 encapsulation_request = TRUE;
3406 single_idu_buffer = data buffer;
3407 Target_Info.targ_names = receiver names;
3408 P_Services.Prot_Service_1.service_id = PER_CONF;
3409 P_Services.Prot_Service_2.service_id = PER_DOA;
3411 Call
3412 IDUP_Start_Protect() with above input parameters
3418 Adams Informational [Page 61]
3419 \f
3420 RFC 2479 IDUP-GSS-API December 1998
3423 Check
3424 major_status. If not GSS_S_COMPLETE, check
3425 minor_status,
3426 Target_Info.bad_targ_names / Target_Info.bad_targ_status,
3427 P_Services.Prot_Service_1.General_Service_Data.minor_status,
3428 P_Services.Prot_Service_2.General_Service_Data.minor_status
3429 (as required) for more detailed information.
3431 Send
3432 Output parameter pidu_buffer to receiver.
3435 RECEIVER (any parameters not listed below are given the value NULL):
3437 Set
3438 env_handle = environment handle in use;
3439 single_pidu_buffer = received data buffer;
3441 Call
3442 IDUP_Start_Unprotect() with above input parameters
3443 Check
3444 major_status. If not GSS_S_COMPLETE, check
3445 minor_status,
3446 R_Services.Unprot_Service_1.General_Service_Data.minor_status,
3447 R_Services.Unprot_Service_2.General_Service_Data.minor_status
3448 (as required) for more detailed information
3450 Utilize
3451 R_Services.Unprot_Service_1/2.service_id,
3452 (to determine which services were applied by the originator)
3453 R_Services.Unprot_Service_1/2.Quality,
3454 (to determine the corresponding qualities of the services)
3455 Prot_Information.originator_name,
3456 (to determine the name of the originator)
3457 single_idu_buffer
3458 (to retrieve the unprotected data).
3460 B.3. Simple Mechanism, Multiple Buffers
3462 To illustrate the next step up in complexity, consider the use of the
3463 simple IDUP mechanism described in B.2 above with multiple data
3464 buffers. In particular, consider the case in which a large data file
3465 is to be signed. For this example, assume that the calling
3466 application does not wish to use encapsulation.
3468 Note that the parameter bundle uses and defaults are as specified in
3469 B.2. above.
3474 Adams Informational [Page 62]
3475 \f
3476 RFC 2479 IDUP-GSS-API December 1998
3479 SENDER (any parameters not listed below are given the value NULL):
3481 Set
3482 env_handle = environment handle in use;
3483 encapsulation_request = FALSE;
3484 P_Services.Prot_Service.service_id = PER_DOA;
3486 Call
3487 IDUP_Start_Protect() with above input parameters
3488 Check
3489 major_status. If not GSS_S_COMPLETE, check
3490 minor_status,
3491 P_Services.Prot_Service.General_Service_Data.minor_status
3492 (as required) for more detailed information.
3494 For each buffer of input data:
3495 Set
3496 input_buffer = buffer
3497 Call
3498 IDUP_Protect() with above input parameter
3499 Check
3500 major_status. If not GSS_S_COMPLETE, check
3501 minor_status
3503 Call
3504 IDUP_End_Protect()
3505 Check
3506 major_status. If not GSS_S_COMPLETE, check
3507 minor_status,
3508 P_Services.Prot_Service.General_Service_Data.minor_status
3509 (as required) for more detailed information.
3511 Send
3512 P_Services.Prot_Service.General_Service_Data.unencapsulated_token,
3513 and the file for which the signature was calculated (if required),
3514 to receiver.
3516 RECEIVER (any parameters not listed below are given the value NULL):
3518 Set
3519 env_handle = environment handle in use;
3520 R_Services.Unprot_Service_1.General_Service_Data.
3521 unencapsulated_token = received unencapsulated token;
3523 Call
3524 IDUP_Start_Unprotect() with above input parameters
3525 Check
3526 major_status. If not GSS_S_COMPLETE, check
3530 Adams Informational [Page 63]
3531 \f
3532 RFC 2479 IDUP-GSS-API December 1998
3535 minor_status,
3536 R_Services.Unprot_Service_1.General_Service_Data.minor_status,
3537 (as required) for more detailed information
3539 For each buffer of input data:
3540 Set
3541 input_buffer = buffer
3542 Call
3543 IDUP_Unprotect() with above input parameter
3544 Check
3545 major_status. If not GSS_S_COMPLETE, check
3546 minor_status
3548 Call
3549 IDUP_End_Unprotect()
3550 Check
3551 major_status. If not GSS_S_COMPLETE, check
3552 minor_status,
3553 R_Services.Unprot_Service_1.General_Service_Data.minor_status,
3554 (as required) for more detailed information.
3556 Utilize
3557 R_Services.Unprot_Service_1.service_id,
3558 (to determine which service was applied by the originator; note
3559 that Unprot_Service_2 will have NULL in unprot_service_type
3560 to indicate that it is not used)
3561 R_Services.Unprot_Service_1.Quality,
3562 (to determine the corresponding quality of the service)
3563 Prot_Information.originator_name, (from IDUP_Start_Unprotect)
3564 (to determine the name of the signer)
3565 major_status (from IDUP_End_Unprotect)
3566 (to determine pass/fail status of signature verification).
3568 B.4. More Sophisticated Mechanism, Small Application Buffers
3570 To illustrate a higher level of complexity, consider the use of a
3571 more sophisticated IDUP mechanism and a calling application with
3572 small data buffers. In particular, consider the case in which a very
3573 small e-mail message is to be encrypted for a relatively large
3574 receiver list (R), some subset of whom (r) will be asked to send
3575 proofs of receipt of the message to some other subset (L) (which
3576 includes the originator). So that the example is not unnecessarily
3577 complicated, assume again that the originating application uses
3578 encapsulation.
3580 The uses and defaults for the various parameter bundles for this
3581 mechanism would be specified in the relevant IDUP mechanism document
3582 as follows.
3586 Adams Informational [Page 64]
3587 \f
3588 RFC 2479 IDUP-GSS-API December 1998
3591 Mech_Specific_Info
3592 - NOT USED (the only acceptable input, therefore, is NULL)
3594 Idu_Sensitivity
3595 - NOT USED (the only acceptable input, therefore, is NULL)
3597 Service_Creation_Info
3598 - used to create "proof of delivery" evidence (but actual
3599 structure is opaque to calling application)
3601 Service_Verification_Info
3602 - used to verify "proof of delivery" evidence (but actual
3603 structure is opaque to calling application)
3605 Quality
3606 - the qop_algs parameter must be supported, with a suitable
3607 DEFAULT value specified;
3608 - suitable DEFAULT values for validity, policy_id, and
3609 allow_policy_mapping must be specified (it may be an
3610 implementation option as to whether these parameters are
3611 explicitly modifiable by the calling application, or whether
3612 NULLs are the only acceptable input)
3614 Idu_Information
3615 - the idu_type parameter must have a value representing a suitable
3616 IDU type, with a suitable DEFAULT value specified;
3617 - the idu_title parameter must have a value representing a
3618 suitable IDU title, with a suitable DEFAULT value specified
3620 Prot_Information
3621 - the originator_name, protection_time, and idu_type / idu_title
3622 (in Idu_Information) parameters are read from the contained
3623 header information and output by IDUP_Start_Unprotect;
3625 Special_Conditions
3626 - the parameter prot_oper_id is NOT USED (the only acceptable
3627 input, therefore, is NULL);
3628 - trusted or untrusted time may be selected by the calling
3629 application, with a suitable DEFAULT value specified
3631 Target_Info
3632 - this bundle is used as described in IDUP; no DEFAULT values are
3633 specified
3635 General_Service_Data
3636 - the unencapsulated_token parameter is used if
3637 encapsulation_request is FALSE;
3638 - the minor_status parameter is used to return minor status values
3642 Adams Informational [Page 65]
3643 \f
3644 RFC 2479 IDUP-GSS-API December 1998
3647 as specified by the mechanism document
3649 Prot_Service
3650 - the prot_service_type parameter may have a value of "1"
3651 ("perform unsolicited service"), "2" ("perform solicited
3652 service"), "3" (perform service solicitation), or NULL (which
3653 specifies the DEFAULT value of "1");
3654 - the service_id parameter must have a value representing
3655 "PER_CONF", "PER_DOA", "PER_POO", or "PER_POD";
3656 - the parameters Service_Creation_Info, service_to,
3657 Service_Verification_Info, and service_verification_info_id are
3658 used when required by the IDUP operation
3660 Unprot_Service
3661 - the unprot_service_type parameter may have a value of "1"
3662 ("receive unsolicited service"), "2" ("receive solicited
3663 service"), or "3" (receive service solicitation);
3664 - the service_id parameter will have a value representing
3665 "REC_CONF", "REC_DOA", "REC_POO", or "REC_POD";
3666 - the parameters service_verification_info_id,
3667 Service_Verification_Info, service_to, and
3668 Service_Creation_Info, are used when required by the IDUP
3669 operation
3672 SENDER (any parameters not listed below are given the value NULL):
3674 Set
3675 env_handle = environment handle in use;
3676 Idu_Information.idu_type = value for "e-mail document";
3677 Idu_Information.idu_title = "Contract 1234";
3678 Special_Conditions.use_trusted_time = TRUE;
3679 encapsulation_request = TRUE;
3680 single_idu_buffer = very small e-mail message;
3681 Target_Info.targ_names = receiver names (R);
3682 Prot_Service_1.prot_service_type = "1";
3683 Prot_Service_1.service_id = PER_CONF;
3684 Prot_Service_2.prot_service_type = "3";
3685 Prot_Service_2.service_id = PER_POD;
3686 Prot_Service_2.General_Service_Data.Target_Info.targ_names
3687 = "receipts from" list (r);
3688 Prot_Service_2.service_to = "receipts to" list (L);
3689 P_Services.Prot_Service_1 = Prot_Service_1;
3690 P_Services.Prot_Service_2 = Prot_Service_2;
3692 Call
3693 IDUP_Start_Protect() with above input parameters
3698 Adams Informational [Page 66]
3699 \f
3700 RFC 2479 IDUP-GSS-API December 1998
3703 Check
3704 major_status. If not GSS_S_COMPLETE,
3705 while major_status == IDUP_S_MORE_OUTBUFFER_NEEDED
3706 Save
3707 pidu_buffer,
3708 Call
3709 IDUP_Start_Protect() (to get next portion of pidu_buffer)
3710 Check
3711 major_status,
3712 minor_status,
3713 Target_Info.bad_targ_names / Target_Info.bad_targ_status,
3714 P_Services.Prot_Service_1.General_Service_Data.minor_status,
3715 P_Services.Prot_Service_2.General_Service_Data.minor_status
3716 (as required) for more detailed information.
3718 Save
3719 Prot_Service_2.Service_Verification_Info,
3720 Prot_Service_2.service_verification_info_id
3722 Send
3723 All saved buffers of pidu_buffer to receiver list (R).
3726 RECEIVER (ON RECEIVER LIST (R)):
3727 (any parameters not listed below are given the value NULL)
3729 Set
3730 env_handle = environment handle in use;
3731 partial_pidu_buffer = initial buffer of received p-idu;
3733 Call
3734 IDUP_Start_Unprotect() with above input parameters
3735 While major_status == IDUP_S_MORE_PIDU_NEEDED,
3736 Set
3737 partial_pidu_buffer = next buffer of p-idu
3738 Call
3739 IDUP_Start_Unprotect()
3740 Check
3741 major_status,
3742 minor_status,
3743 R_Services.Unprot_Service_1.General_Service_Data.minor_status,
3744 R_Services.Unprot_Service_2.General_Service_Data.minor_status,
3745 (as required) for more detailed information
3747 Save
3748 initial_idu_buffer (if non-empty)
3754 Adams Informational [Page 67]
3755 \f
3756 RFC 2479 IDUP-GSS-API December 1998
3759 Set
3760 input_buffer = remaining p-idu buffer
3761 Call
3762 IDUP_Unprotect() with above input parameter
3763 Check
3764 major_status. If not GSS_S_COMPLETE, check
3765 minor_status
3766 Save
3767 output_buffer
3769 Call
3770 IDUP_End_Unprotect()
3771 Check
3772 major_status. If not GSS_S_COMPLETE, check
3773 minor_status,
3774 R_Services.Unprot_Service_1.General_Service_Data.minor_status,
3775 R_Services.Unprot_Service_2.General_Service_Data.minor_status,
3776 (as required) for more detailed information.
3778 Utilize
3779 R_Services.Unprot_Service_1/2.service_id,
3780 (to determine which services were applied by the originator)
3781 R_Services.Unprot_Service_1/2.Quality,
3782 (to determine the corresponding qualities of the service)
3783 Prot_Information.originator_name/protection_time and
3784 Prot_Information.Idu_Information.idu_type/idu_title,
3785 (from IDUP_Start_Unprotect) (to determine originator info.)
3786 R_Services.Unprot_Service_2.General_Service_Data.Target_Info.
3787 targ.names, (to determine if rec. is in "receipts from" (r))
3788 Service_Verification_Info/service_verification_info_id
3789 (to determine if receiver is in "receipts to" list (L))
3791 If receiver is in "receipts from" list (r)
3792 Save
3793 R_Services.Unprot_Service_2.service_to,
3794 R_Services.Unprot_Service_2.Service_Creation_Info
3796 If receiver is in "receipts to" list (L)
3797 Save
3798 Service_Verification_Info,
3799 service_verification_info_id
3801 RECEIVER (ON "RECEIPTS FROM" LIST (r)):
3802 (procedure to generate receipt)
3804 Set
3805 env_handle = environment handle in use;
3806 Target_Info.targ_names = service_to
3810 Adams Informational [Page 68]
3811 \f
3812 RFC 2479 IDUP-GSS-API December 1998
3815 Prot_Service_1.prot_service_type = "2";
3816 Prot_Service_1.service_id = "PER_POD";
3817 Prot_Service_1.Service_Creation_Info = Service_Creation_Info;
3818 P_Services.Prot_Service_1 = Prot_Service_1
3820 Call
3821 IDUP_Start_Protect() with above input parameters
3822 Check
3823 major_status. If not GSS_S_COMPLETE, check
3824 minor_status,
3825 P_Services.Prot_Service_1.General_Service_Data.minor_status
3826 (as required) for more detailed information.
3828 Send
3829 pidu_buffer to "receipts to" list (L)
3831 RECEIVER (ON "RECEIPTS TO" LIST (L)):
3832 (procedure to process received receipt)
3834 Set
3835 env_handle = environment handle in use;
3836 single_pidu_buffer = received p-idu buffer (if it fits in a single
3837 buffer; otherwise use partial_pidu_buffer and make multiple
3838 calls, as above)
3840 Call
3841 IDUP_Start_Unprotect() with above input parameters
3842 If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED
3843 Utilize
3844 R_Services.Unprot_Service_1.service_verification_info.id
3845 (to assist in locating necessary Service_Verification_Info)
3846 Set
3847 R_Services.Unprot_Service_1.Service_Verification_Info
3848 = Service_Verification_Info
3849 Call
3850 IDUP_Start_Unprotect() with above input parameters
3851 Check
3852 major_status,
3853 minor_status,
3854 R_Services.Unprot_Service_1.General_Service_Data.minor_status
3855 (as required) for more detailed information.
3857 Utilize
3858 R_Services.Unprot_Service_1.service_id,
3859 (to determine that this is a "proof of delivery" evidence)
3860 R_Services.Unprot_Service_1.Quality,
3861 Prot_Information.originator_name, (for evidence generator info.)
3862 major_status (to determine pass/fail status of evi. verif.).
3866 Adams Informational [Page 69]
3867 \f
3868 RFC 2479 IDUP-GSS-API December 1998
3871 Full Copyright Statement
3873 Copyright (C) The Internet Society (1998). All Rights Reserved.
3875 This document and translations of it may be copied and furnished to
3876 others, and derivative works that comment on or otherwise explain it
3877 or assist in its implementation may be prepared, copied, published
3878 and distributed, in whole or in part, without restriction of any
3879 kind, provided that the above copyright notice and this paragraph are
3880 included on all such copies and derivative works. However, this
3881 document itself may not be modified in any way, such as by removing
3882 the copyright notice or references to the Internet Society or other
3883 Internet organizations, except as needed for the purpose of
3884 developing Internet standards in which case the procedures for
3885 copyrights defined in the Internet Standards process must be
3886 followed, or as required to translate it into languages other than
3887 English.
3889 The limited permissions granted above are perpetual and will not be
3890 revoked by the Internet Society or its successors or assigns.
3892 This document and the information contained herein is provided on an
3893 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
3894 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
3895 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
3896 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
3897 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3922 Adams Informational [Page 70]
3923 \f