home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_a_c / draft-ietf-cat-idup-gss-06.txt < prev    next >
Text File  |  1996-12-03  |  117KB  |  3,140 lines
  1.  
  2. Internet Draft                                          C. Adams, Nortel
  3. draft-ietf-cat-idup-gss-06.txt                             Nov. 26, 1996
  4.  
  5.  
  6.         Independent Data Unit Protection Generic Security Service
  7.              Application Program Interface  (IDUP-GSS-API)
  8.  
  9. STATUS OF THIS MEMO
  10.  
  11.    This document is an Internet-Draft. Internet-Drafts are working
  12.    documents of the Internet Engineering Task Force (IETF), its areas,
  13.    and its working groups. Note that other groups may also distribute
  14.    working documents as Internet-Drafts.
  15.  
  16.    Internet-Drafts are draft documents valid for a maximum of six 
  17.    months and may be updated, replaced, or obsoleted by 
  18.    other documents at any time. It is inappropriate to use Internet-
  19.    Drafts as reference material or to cite them other than as 
  20.    "work in progress."
  21.  
  22.    To learn the current status of any Internet Draft, please check the 
  23.    "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
  24.    Directories on ds.internic.net (US East Coast), nic.nordu.net 
  25.    (Europe), ftp.isi.edu (US West Coast) or munnari.oz.au (Pacific Rim).
  26.  
  27.    Comments on this document should be sent to "cat-ietf@mit.edu", the 
  28.    IETF Common Authentication Technology WG discussion list.
  29.  
  30. ABSTRACT
  31.  
  32.    The IDUP-GSS-API extends the GSS-API [RFC-1508] for applications 
  33.    requiring protection of a generic data unit (such as a file or 
  34.    message) in a way which is independent of the protection of any other 
  35.    data unit and independent of any concurrent contact with designated 
  36.    "receivers" of the data unit.  Thus, it is suitable for applications 
  37.    such as secure electronic mail where data needs to be protected 
  38.    without any on-line connection with the intended recipient(s) of that 
  39.    data.  The protection offered by IDUP includes services such as data 
  40.    origin authentication with data integrity, data confidentiality with 
  41.    data integrity, and support for non-repudiation services.  Subsequent 
  42.    to being protected, the data unit can be transferred to the 
  43.    recipient(s) - or to an archive - perhaps to be processed 
  44.    ("unprotected") only days or years later.
  45.  
  46.    Throughout the remainder of this document, the "unit" of data 
  47.    described in the above paragraph will be referred to as an IDU 
  48.    (Independent Data Unit).  The IDU can be of any size (the application 
  49.    may, if it wishes, split the IDU into pieces and have the protection 
  50.    computed a piece at a time, but the resulting protection token 
  51.    applies to the entire IDU).  However, the primary characteristic of 
  52.    an IDU is that it represents a stand-alone unit of data whose 
  53.    protection is entirely independent of any other unit of data.  If an 
  54.    application protects several IDUs and sends them all to a single 
  55.    receiver, the IDUs may be unprotected by that receiver in any order 
  56.    over any time span; no logical connection of any kind is implied by 
  57.    the protection process itself.
  58. Adams               Document Expiration:  26 May  1997                 1
  59.  
  60.  
  61.    As with RFC-1508, this IDUP-GSS-API definition provides security 
  62.    services to callers in a generic fashion, supportable with a range of 
  63.    underlying mechanisms and technologies and hence allowing source-
  64.    level portability of applications to different environments. This 
  65.    specification defines IDUP-GSS-API services and primitives at a level 
  66.    independent of underlying mechanism and programming language environ-
  67.    ment, and is to be complemented by other, related specifications:
  68.  
  69.       - documents defining specific parameter bindings for particular
  70.         language environments;
  71.       - documents defining token formats, protocols, and procedures to
  72.         be implemented in order to realize IDUP-GSS-API services atop
  73.         particular security mechanisms.
  74.  
  75. TABLE OF CONTENTS
  76.    1.  IDUP-GSS-API Characteristics and Concepts ..................    3
  77.    1.1.  IDUP-GSS-API Constructs ..................................    5
  78.    1.1.1.  Credentials ............................................    5
  79.    1.1.2.  Tokens .................................................    5
  80.    1.1.3.  Security Environment ...................................    5
  81.    1.1.4.  Mechanism Types ........................................    5
  82.    1.1.5.  Naming .................................................    5
  83.    1.1.6.  Channel Bindings .......................................    6
  84.    1.2.  IDUP-GSS-API Features and Issues .........................    6
  85.    1.2.1.  Status Reporting .......................................    6
  86.    1.2.2.  Per-IDU Security Service Availability ..................    7
  87.    1.2.3.  Per-IDU Replay Detection and Sequencing ................    7
  88.    1.2.4.  Quality of Protection ..................................    7
  89.    1.2.5.  The Provision of Time ..................................   10
  90.    2.  Interface Descriptions .....................................   10
  91.    2.1.  Credential management calls ..............................   11
  92.    2.1.1.  Relationship to GSS-API ................................   11
  93.    2.2.  Environment-level calls ..................................   12
  94.    2.2.1.  Relationship to GSS-API ................................   12
  95.    2.2.2.  IDUP_Establish_Env call ................................   13
  96.    2.2.3.  IDUP_Abolish_Env call ..................................   15
  97.    2.2.4.  IDUP_Inquire_Env call ..................................   16
  98.    2.3.  Per-IDU calls ............................................   17
  99.    2.3.1.  Relationship to GSS-API ................................   17
  100.    2.3.2.  Parameter Bundles ......................................   17
  101.    2.3.3.  IDUP_Start_Protect .....................................   21
  102.    2.3.4.  IDUP_Protect ...........................................   24
  103.    2.3.5.  IDUP_End_Protect .......................................   25
  104.    2.3.7.  IDUP_Start_Unprotect ...................................   27
  105.    2.3.8.  IDUP_Unprotect .........................................   30
  106.    2.3.9.  IDUP_End_Unprotect .....................................   31
  107.    2.4.  Special-Purpose calls ....................................   35
  108.    2.4.1.  Relationship to GSS-API ................................   35
  109.    2.4.5.  IDUP_Form_Complete_PIDU ................................   35
  110.    2.5.  Support calls ............................................   37
  111.    2.5.1.  Relationship to GSS-API ................................   37
  112.    2.5.2.  IDUP_Parse_token call ..................................   37
  113.    2.5.3.  IDUP_Get_Policy_Info ...................................   38
  114.  
  115.  
  116.  
  117. Adams               Document Expiration:  26 May  1997                 2
  118.  
  119.  
  120.    3.  Related Activities .........................................   40
  121.    4.  Acknowledgments ............................................   40
  122.    5.  Security Considerations ....................................   40
  123.    6.  References       ...........................................   41
  124.    7.  Author's Address ...........................................   41
  125.    Appendix  A, ...................................................   42
  126.    Appendix  B ....................................................   43
  127.  
  128. 1. IDUP-GSS-API Characteristics and Concepts
  129.  
  130.    The paradigm within which IDUP-GSS-API operates is as follows.  An 
  131.    IDUP-GSS-API caller is any application which works with IDUs, calling 
  132.    on IDUP-GSS-API in order to protect its IDUs with services such as 
  133.    data origin authentication with integrity (DOA), confidentiality with 
  134.    integrity (CONF), and/or support for non-repudiation (e.g., evidence 
  135.    generation, where "evidence" is information that either by itself or 
  136.    when used in conjunction with other information is used to establish 
  137.    proof about an event or action (note:  the evidence itself does not 
  138.    necessarily prove truth or existence of something, but contributes to 
  139.    establish proof) -- see [ISO/IEC] for fuller discussion regarding 
  140.    evidence and its role in various types of non-repudiation).  An 
  141.    IDUP-GSS-API caller passes an IDU to, and accepts a token from, its 
  142.    local IDUP-GSS-API implementation, transferring the resulting 
  143.    protected IDU (P-IDU) to a peer or to any storage medium.  When a 
  144.    P-IDU is to be "unprotected", it must be passed to an IDUP-GSS-API 
  145.    implementation for processing.  The security services available 
  146.    through IDUP-GSS-API in this fashion are implementable over a range 
  147.    of underlying mechanisms based on secret-key and/or public-key 
  148.    cryptographic technologies.  
  149.  
  150.    During the protection operation, the input IDU buffers may be 
  151.    modified (for example, the data may be encrypted or encoded in some 
  152.    way) or may remain unchanged.  In any case, the result is termed a 
  153.    "M-IDU" (Modified IDU) in order to distinguish it from the original 
  154.    IDU.  Depending on the desire of the calling application and the 
  155.    capabilities of the underlying IDUP mechanism, the token produced by 
  156.    the protection processing may or may not encapsulate the M-IDU.  
  157.    Thus, the P-IDU may be the token alone (if encapsulation is done) or 
  158.    may be the logical concatenation of the token and the M-IDU (if 
  159.    encapsulation is not done).  In the latter case, the protecting 
  160.    application may choose whatever method it wishes to concatenate or 
  161.    combine the token and the M-IDU into a P-IDU, provided the 
  162.    unprotecting application knows how to de-couple the P-IDU back into 
  163.    its component parts prior to calling the IDUP unprotection set of 
  164.    functions.
  165.  
  166.    The IDUP-GSS-API separates the operation of initializing a security
  167.    environment (the IDUP_Establish_Env() call) from the operations of 
  168.    providing per-IDU protection, for IDUs subsequently protected in 
  169.    conjunction with that environment. Per-IDU protection and 
  170.    unprotection calls provide DOA, CONF, evidence, and other services, 
  171.    as requested by the calling application and as supported by the 
  172.    underlying mechanism.
  173.  
  174.  
  175.  
  176. Adams               Document Expiration:  26 May  1997                 3
  177.  
  178.  
  179.  
  180.    The following paragraphs provide an example illustrating the 
  181.    dataflows involved in the use of the IDUP-GSS-API by the sender and 
  182.    receiver of a P-IDU in a mechanism-independent fashion.  The example 
  183.    assumes that credential acquisition has already been completed by 
  184.    both sides.  Furthermore, the example does not cover all possible 
  185.    options available in the protection/unprotection calls.
  186.  
  187.       The sender first calls IDUP_Establish_Env() to establish a 
  188.       security environment.  Then, for the IDU to be protected the 
  189.       sender calls IDUP_Start_Protect(), IDUP_Protect() for each buffer 
  190.       of data, and IDUP_End_Protect() to complete the IDU protection.  
  191.       The resulting P-IDU, which may (depending on whether or not 
  192.       encapsulation was chosen/available) be either the token itself 
  193.       or the logical concatenation of the token and the M-IDU, is now 
  194.       ready to be sent to the target.  The sender then calls 
  195.       IDUP_Abolish_Env() to flush all environment-specific information.
  196.  
  197.       The receiver first calls IDUP_Establish_Env() to establish a 
  198.       security environment in order to unprotect the P-IDU.  Then, for 
  199.       the received P-IDU the receiver calls IDUP_Start_Unprotect(), 
  200.       IDUP_Unprotect() for each buffer of data, and IDUP_End_Unprotect() 
  201.       to complete the P-IDU unprotection.  The receiver then calls 
  202.       IDUP_Abolish_Env() to flush all environment-specific information.
  203.  
  204.  
  205.    It is important to note that absolutely no synchronization is implied 
  206.    or expected between the data buffer size used by the sender as input 
  207.    to the protection calls, the data buffer size used by the receiver as 
  208.    input to the unprotection calls, and the block sizes required by the 
  209.    underlying protection algorithms (integrity and confidentiality).  
  210.    All these sizes are meant to be independent; furthermore, the data 
  211.    buffer sizes used for the protection and unprotection calls are 
  212.    purely a function of the local environment where the calls are made.
  213.  
  214.    The IDUP-GSS-API design assumes and addresses several basic goals,
  215.    including the following.
  216.  
  217.       Mechanism independence:  The IDUP-GSS-API defines an interface to 
  218.       cryptographically implemented security services at a generic level 
  219.       which is independent of particular underlying mechanisms. For 
  220.       example, IDUP-GSS-API-provided services can be implemented by 
  221.       secret-key technologies or public-key approaches.
  222.  
  223.       Protocol environment independence: The IDUP-GSS-API is independent 
  224.       of the communications protocol suites which may be used to 
  225.       transfer P-IDUs, permitting use in a broad range of protocol 
  226.       environments.
  227.  
  228.       Protocol association independence: The IDUP-GSS-API's security 
  229.       environment construct has nothing whatever to do with 
  230.       communications protocol association constructs, so that 
  231.       IDUP-GSS-API services can be invoked by applications, wholly 
  232.       independent of protocol associations.
  233.  
  234.  
  235. Adams               Document Expiration:  26 May  1997                 4
  236.  
  237.  
  238.       Suitability for a range of implementation placements: IDUP-GSS-API
  239.       clients are not constrained to reside within any Trusted Computing
  240.       Base (TCB) perimeter defined on a system where the IDUP-GSS-API is
  241.       implemented; security services are specified in a manner suitable
  242.       for both intra-TCB and extra-TCB callers.
  243.  
  244. 1.1. IDUP-GSS-API Constructs
  245.  
  246.    This section describes the basic elements comprising the 
  247.    IDUP-GSS-API.
  248.  
  249.  
  250. 1.1.1.  Credentials
  251.  
  252.    Credentials in IDUP-GSS-API are to be understood and used as 
  253.    described in GSS-API [RFC-1508].
  254.  
  255. 1.1.2. Tokens
  256.  
  257.    Tokens in IDUP-GSS-API are to be understood and used as described in 
  258.    GSS-API [RFC-1508] with the exception that there are no context-level 
  259.    tokens generated by IDUP-GSS-API.  The IDUP-GSS-API token 
  260.    may (depending on the underlying mechanism) encapsulate the M-IDU or 
  261.    may be logically concatenated with M-IDU prior to transfer to a 
  262.    target; furthermore, for some evidence services the token may be sent 
  263.    independently of any other data transfer.
  264.  
  265. 1.1.3.  Security Environment
  266.  
  267.    The "security environment" in IDUP-GSS-API is entirely different from 
  268.    the concept of security contexts used in GSS-API [RFC-1508].  Here, a 
  269.    security environment exists within a calling application (that is, it 
  270.    is purely local to the caller) for the purpose of protecting or 
  271.    unprotecting one or more IDUs using a particular caller credential or 
  272.    set of credentials.  In GSS-API, on the other hand, a security 
  273.    context exists between peers (the initiator and the target) for the 
  274.    purpose of protecting, in real time, the data that is exchanged 
  275.    between them.  Although they are different concepts, the env_handle 
  276.    in IDUP-GSS-API is similar to the context_handle in GSS-API in that 
  277.    it is a convenient way of tying together the entire process of 
  278.    protecting or unprotecting one or more IDUs using a particular 
  279.    underlying mechanism.  As with the GSS-API security contexts, a 
  280.    caller can initiate and maintain multiple environments using the same 
  281.    or different credentials.
  282.  
  283. 1.1.4.  Mechanism Types
  284.  
  285.    Mechanism types in IDUP-GSS-API are to be understood and used as 
  286.    described in GSS-API [RFC-1508].
  287.  
  288. 1.1.5.  Naming
  289.  
  290.    Naming in IDUP-GSS-API is to be understood and used as described in 
  291.    GSS-API [RFC-1508].
  292.  
  293.  
  294. Adams               Document Expiration:  26 May  1997                 5
  295.  
  296.  
  297. 1.1.6.  Channel Bindings
  298.  
  299.    The concept of channel bindings discussed in GSS-API [RFC-1508] is 
  300.    not relevant to the IDUP-GSS-API.
  301.  
  302.  
  303.  
  304. 1.2.  IDUP-GSS-API Features and Issues
  305.  
  306.    This section describes aspects of IDUP-GSS-API operations and of the 
  307.    security services which the IDUP-GSS-API provides.  It also provides 
  308.    commentary on design issues.
  309.  
  310.  
  311. 1.2.1.  Status Reporting
  312.  
  313.    Status reporting in IDUP-GSS-API is to be understood and used as 
  314.    described in GSS-API [RFC-1508], with the addition of the following 
  315.    IDUP-GSS-API major status codes.
  316.  
  317.    As with GSS-API, minor_status codes, which provide more detailed 
  318.    status information than major_status codes, and which may include 
  319.    status codes specific to the underlying security mechanism, are not 
  320.    specified in this document.
  321.  
  322.  
  323.  
  324.    Table 1: IDUP-GSS-API Major Status Codes
  325.  
  326.  
  327.       Fatal Error Codes
  328.  
  329.       IDUP_S_BAD_TARG_INFO     all target information is invalid or 
  330.                                unsuitable for IDU protection
  331.  
  332.       IDUP_S_BAD_DOA_KEY       DOA key has expired or been revoked
  333.  
  334.       IDUP_S_BAD_KE_KEY        key used for key establishment between 
  335.                                orig. and targ. has exp. or been revoked
  336.  
  337.       IDUP_S_BAD_ENC_IDU       encrypted IDU is defective/invalid
  338.  
  339.       IDUP_S_INCOMPLETE
  340.          there is not enough info. in token for P-IDU verification
  341.  
  342.       IDUP_S_SERV_VERIF_INFO_NEEDED 
  343.          the Service_Verification_Info parameter bundle is required
  344.  
  345.       IDUP_S_SERVICE_UNAVAIL  mech. does not support requested service
  346.  
  347.       IDUP_S_REQ_TIME_SERVICE_UNAVAIL
  348.          the time service requested is not avail. in this environment
  349.  
  350.       IDUP_S_INAPPROPRIATE_CRED 
  351.          the credentials supplied cannot be used to unprotect P-IDU
  352.  
  353. Adams               Document Expiration:  26 May  1997                 6
  354.  
  355.  
  356.       IDUP_S_NO_ENV            no environment recognized for env_handle
  357.  
  358.  
  359.       IDUP_S_NO_MATCH          Service_Verification_Info and input token 
  360.                                do not match
  361.  
  362.       IDUP_S_UNKNOWN_OPER_ID   requested operation id. is unsupported
  363.  
  364.  
  365.       Informatory Status Codes
  366.  
  367.       IDUP_S_ENCAPSULATION_UNAVAIL 
  368.          encapsulation of M-IDU into pidu_buffer is not supported 
  369.  
  370.       IDUP_S_MORE_PIDU_NEEDED 
  371.          more p-idu data is needed for IDUP_Start_Unprotect()
  372.  
  373.       IDUP_S_MORE_DATA_NEEDED 
  374.          more data is needed for protection or unprotection 
  375.  
  376.  
  377. 1.2.2. Per-IDU Security Service Availability
  378.  
  379.    Per-IDU security service availability in IDUP-GSS-API is to be 
  380.    understood and used as described in GSS-API [RFC-1508], with the 
  381.    exception that any combination of services requested by the calling 
  382.    application and supported by the underlying mechanism can be applied 
  383.    simultaneously to any IDU.
  384.  
  385.    GSS-API callers desiring per-message security services should check 
  386.    the relevant service OBJECT IDs at environment establishment time to 
  387.    ensure that what is available in the established environment is 
  388.    suitable for their security needs.
  389.  
  390.  
  391. 1.2.3. Per-IDU Replay Detection and Sequencing
  392.  
  393.    The concept of per-IDU replay detection and sequencing discussed 
  394.    in GSS-API [RFC-1508] is not relevant to the IDUP-GSS-API.
  395.  
  396.  
  397. 1.2.4.  Quality of Protection
  398.  
  399.    The concept of QOP control in IDUP-GSS-API is to be understood 
  400.    essentially as described in GSS-API [RFC-1508].  However, the actual 
  401.    description and use of the QOP parameter is given as follows.
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412. Adams               Document Expiration:  26 May  1997                 7
  413.  
  414.  
  415.    The qop_algs parameter for IDUP is defined to be a 32-bit unsigned 
  416.    integer with the following bit-field assignments:
  417.  
  418.             31 (MSB)                               (LSB) 0
  419.             ----------------------------------------------
  420.             |        U(19)       | TS(5) | IA(4) | MA(4) |
  421.             ----------------------------------------------
  422.  
  423.    where 
  424.  
  425.       U is a 19-bit Unspecified field (available for future 
  426.       use/expansion) -- must be set to zero;
  427.  
  428.       TS is a 5-bit Type Specifier (a semantic qualifier whose value 
  429.       specifies the type of algorithm which may be used to protect the 
  430.       corresponding IDU -- see below for details);
  431.  
  432.       IA is a 4-bit field enumerating Implementation-specific 
  433.       Algorithms; and
  434.  
  435.       MA is a 4-bit field enumerating Mechanism-defined Algorithms.
  436.  
  437.    The interpretation of the qop_algs parameter is as follows.  The MA 
  438.    field is examined first.  If it is non-zero then the algorithm used 
  439.    to protect the IDU is the mechanism-specified algorithm corresponding 
  440.    to that integer value.
  441.  
  442.    If MA is zero then IA is examined.  If this field value is non-zero 
  443.    then the algorithm used to protect the IDU is the implementation-
  444.    specified algorithm corresponding to that integer value.  Note that 
  445.    use of this field may hinder portability since a particular value may 
  446.    specify one algorithm in one implementation of the mechanism and may 
  447.    not be supported or may specify a completely different algorithm in 
  448.    another implementation of the mechanism.
  449.  
  450.    Finally, if both MA and IA are zero then TS is examined.  A value of 
  451.    zero for TS specifies the default algorithm for the established 
  452.    mechanism.  A non-zero value for TS corresponds to a particular 
  453.    algorithm qualifier and selects any algorithm from the mechanism 
  454.    specification which satisfies that qualifier (which actual algorithm 
  455.    is selected is an implementation choice; the calling application need 
  456.    not be aware of the choice made).
  457.  
  458.  
  459.    The following TS values (i.e., algorithm qualifiers) are specified; 
  460.    other values may be added in the future.
  461.  
  462.    When qop_algs is used to select a confidentiality algorithm:
  463.  
  464.       00000  (0) = default confidentiality algorithm
  465.       00001  (1) = IDUP_SYM_ALG_STRENGTH_STRONG
  466.       00010  (2) = IDUP_SYM_ALG_STRENGTH_MEDIUM
  467.       00011  (3) = IDUP_SYM_ALG_STRENGTH_WEAK
  468.       11111 (31) = IDUP_NO_CONFIDENTIALITY
  469.  
  470.  
  471. Adams               Document Expiration:  26 May  1997                 8
  472.  
  473.    When qop_algs is used to select a DOA/integrity algorithm:
  474.  
  475.       00000  (0) = default integrity algorithm
  476.       00001  (1) = IDUP_INT_ALG_DIG_SIGNATURE
  477.                    (integrity provided through a digital signature)
  478.       00010  (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE
  479.                    (integrity without a dig. sig. (e.g., with a MAC))
  480.       11111 (31) = IDUP_NO_INTEGRITY
  481.  
  482.    Clearly, qualifiers such as strong, medium, and weak are debatable 
  483.    and likely to change with time, but for the purposes of this version 
  484.    of the specification we define these terms as follows.  A confiden-
  485.    tiality algorithm is "weak" if the effective key length of the cipher 
  486.    is 40 bits or less; it is "medium-strength" if the effective key 
  487.    length is strictly between 40 and 80 bits; and it is "strong" if the 
  488.    effective key length is 80 bits or greater.  ("Effective key length" 
  489.    describes the computational effort required to break a cipher using 
  490.    the best-known cryptanalytic attack against that cipher.)
  491.  
  492.    A five-bit TS field allows up to 30 qualifiers for each of confiden-
  493.    tiality and integrity (since "0" is reserved for "default" and "31" 
  494.    is reserved for "none", as shown above).  This document specifies 
  495.    three for confidentiality and two for integrity, leaving a lot of 
  496.    room for future specification.  Suggestions of qualifiers such as 
  497.    "fast", "medium-speed", and "slow" have been made, but such terms are 
  498.    difficult to quantify (and in any case are platform- and processor-
  499.    dependent), and so have been left out of this initial specification.  
  500.    The intention is that the TS terms be quantitative, environment-
  501.    independent qualifiers of algorithms, as much as this is possible.
  502.  
  503.    Use of the qop_algs parameter as defined above is ultimately meant to 
  504.    be as follows.
  505.  
  506.     - TS values are specified at the IDUP-GSS-API level and are 
  507.       therefore portable across mechanisms.  Applications which know 
  508.       nothing about algorithms are still able to choose "quality" of 
  509.       protection for their message tokens.
  510.  
  511.     - MA values are specified at the mechanism level and are therefore 
  512.       portable across implementations of a mechanism.
  513.  
  514.     - IA values are specified at the implementation level (in user 
  515.       documentation, for example) and are therefore typically non-
  516.       portable.  An application which is aware of its own mechanism 
  517.       implementation and the mechanism implementation of its intended 
  518.       P-IDU recipient, however, is free to use these values since they 
  519.       will be perfectly valid and meaningful for protecting IDUs 
  520.       between those entities.
  521.  
  522.    The receiver of a P-IDU must pass back to its calling application 
  523.    (in IDUP_Start_Unprotect()) a qop_algs parameter with all relevant 
  524.    fields set.  For example, if triple-DES has been specified by a 
  525.    mechanism as algorithm 8, then a receiver of a triple-DES-protected 
  526.    P-IDU must pass to its application (TS=1, IA=0, MA=8).  In this way, 
  527.    the application is free to read whatever part of the qop_algs 
  528.    parameter it understands (TS or IA/MA).
  529.  
  530. Adams               Document Expiration:  26 May  1997                 9
  531.  
  532.  
  533. 1.2.5.  The Provision of Time
  534.  
  535.    IDUP mechanisms should make provision in their protocols for the 
  536.    carrying of time information from originator to target(s).  That is, 
  537.    a target (a legitimate recipient) should get some indication during 
  538.    unprotection regarding the time at which the protection operation 
  539.    took place.  This is particularly important if the mechanism offers 
  540.    non-repudiation services because in some cases evidence verification 
  541.    may only be achievable if the time at which the evidence was 
  542.    generated is known.
  543.  
  544.    Depending upon the platform and resources available to the 
  545.    implementation, an IDUP environment may have access to a source of 
  546.    trusted (secure) time, untrusted (local) time, both kinds of time, or 
  547.    no time.  OBJECT IDs indicating such availability are returned by the 
  548.    IDUP_Establish_Env() call.  When starting a protection operation, an 
  549.    application may specify which time services it wishes to have applied 
  550.    to the IDU.  Similarly, for unprotection, an application may specify 
  551.    which kind of time (if any) to consult when the validity of the P-IDU 
  552.    is to be established.  Specifying both kinds of time is interpreted 
  553.    to mean that the calling application does not care which kind of time 
  554.    is used.
  555.  
  556.  
  557.  
  558. 2.  Interface Descriptions
  559.  
  560.    This section describes the IDUP-GSS-API's operational interface, 
  561.    dividing the set of calls offered into five groups.  Credential 
  562.    management calls are related to the acquisition and release of 
  563.    credentials by API callers. Environment-level calls are related to 
  564.    the management of the security environment by an API caller.  Per-IDU 
  565.    calls are related to the protection or unprotection of individual 
  566.    IDUs in established security environments.  Special-purpose calls 
  567.    deal with unusual or auxiliary evidence generation/verification 
  568.    requirements.  Support calls provide extra functions useful to 
  569.    IDUP-GSS-API callers. Table 2 groups and summarizes the calls in 
  570.    tabular fashion (an asterisk marks the calls which are identical to 
  571.    the GSS-API specification).
  572.  
  573.       Table 2:  IDUP-GSS-API Calls
  574.  
  575.       CREDENTIAL MANAGEMENT
  576.  
  577.     * GSS_Acquire_cred     acquire credentials for use
  578.     * GSS_Release_cred     release credentials after use
  579.     * GSS_Inquire_cred     display information about credentials
  580.     * GSS_Add_cred         add credential info. (see [GSSv2])
  581.  
  582.       ENVIRONMENT-LEVEL CALLS
  583.  
  584.       IDUP_Establish_Env   establish IDUP environment (to protect and 
  585.                            unprotect IDUs)
  586.       IDUP_Abolish_Env     abolish env. when no longer needed
  587.       IDUP_Inquire_Env     indicate characteristics of env.
  588.  
  589. Adams               Document Expiration:  26 May  1997                10
  590.  
  591.  
  592.       PER-IDU CALLS
  593.  
  594.       IDUP_Start_Protect   begin the protection process
  595.       IDUP_Protect         protect the IDU (perhaps 1 buffer at a time)
  596.       IDUP_End_Protect     end the protection process; create a token 
  597.                            which contains info. necessary for the 
  598.                            legitimate receiver(s) of the P-IDU to 
  599.                            unprotect it
  600.       IDUP_File_Protect    protect an IDU (input as a file)
  601.  
  602.       IDUP_Start_Unprotect begin the unprotect process
  603.       IDUP_Unprotect       use the token to unprotect the P-IDU 
  604.                            (possibly one buffer at a time)
  605.       IDUP_End_Unprotect   end the unprotect process
  606.       IDUP_File_Unprotect  unprotect a P-IDU (input as a file)
  607.  
  608.       SPECIAL-PURPOSE CALLS  (might not be supported by all mechanisms)
  609.  
  610.       IDUP_Form_Complete_PIDU  insert in P-IDU any data not provided 
  611.                               by the protection call(s)
  612.  
  613.  
  614.       SUPPORT CALLS
  615.  
  616.     * GSS_Display_status   translate status codes to printable form
  617.     * GSS_Indicate_mechs   indicate mech_types supported on local 
  618.                            system
  619.     * GSS_Compare_name     compare two names for equality
  620.     * GSS_Display_name     translate name to printable form
  621.     * GSS_Import_name      convert printable name to normalize form
  622.     * GSS_Release_name     free storage of normalized-form name
  623.     * GSS_Release_buffer   free storage of printable name
  624.     * GSS_Release_oid_set  free storage of OID set 
  625.       IDUP_Parse_Token     examine an input token to determine mech_type 
  626.       IDUP_Get_Policy_Info return policy info. for a given policy_id
  627.  
  628.  
  629.  
  630. 2.1.  Credential management calls
  631.  
  632.  
  633. 2.1.1.  Relationship to GSS-API
  634.  
  635.    Credential management in IDUP-GSS-API is to be understood and used as 
  636.    described in GSS-API [RFC-1508].  The calls GSS_Acquire_cred(),
  637.    GSS_Release_cred(), and GSS_Inquire_cred() are unchanged (the call 
  638.    GSS_Add_cred() from GSS-API v2 [GSSv2] is also included).  However, 
  639.    the interpretation (and possible modification) of the cred_usage 
  640.    parameter for IDUP purposes is for further study.
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648. Adams               Document Expiration:  26 May  1997                11
  649.  
  650.  
  651. 2.2.  Environment-level calls
  652.  
  653.    This group of calls is devoted to the establishment and management of
  654.    an environment for the purpose of IDU protection and unprotection.  
  655.    Before protecting or unprotecting any IDU, an application must call 
  656.    IDUP_Establish_Env() to initialize environment information and select 
  657.    the underlying IDUP-GSS mechanism to be used.  A series of protection 
  658.    or unprotection calls is made to process each IDU, the protection 
  659.    calls resulting in a P-IDU for each.  Finally, IDUP_Abolish_Env() 
  660.    is called to flush all environment information.
  661.  
  662.    Semantically, acquiring credentials and establishing an environment 
  663.    is (in many cases) analogous to logging in to a system -- it 
  664.    authenticates a local user to the system and gives that user access 
  665.    to a set of operations which can be performed.
  666.  
  667.  
  668. 2.2.1.  Relationship to GSS-API
  669.  
  670.    The set of calls described in this section are used in place of the 
  671.    calls GSS_Init_sec_context(), GSS_Accept_sec_context(), 
  672.    GSS_Delete_sec_context(), GSS_Process_context_token(), and 
  673.    GSS_Context_time() which are described in [RFC-1508], since those 
  674.    calls are specific to a session-oriented environment.
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707. Adams               Document Expiration:  26 May  1997                12
  708.  
  709.  
  710. 2.2.2.  IDUP_Establish_Env call
  711.  
  712.    Inputs:
  713.  
  714.    o  claimant_cred_handle CREDENTIAL HANDLE, 
  715.       -- NULL parameter specifies "use default"
  716.  
  717.    o  req_mech_type OBJECT IDENTIFIER, 
  718.       -- NULL parameter specifies "use default"
  719.  
  720.    o  req_policy OBJECT IDENTIFIER, 
  721.       -- NULL parameter specifies "use default".
  722.       -- This environment-level policy identifier is separate from 
  723.       -- the policy provisions connected with credentials, if they exist 
  724.  
  725.    o  policy_time INTEGER, 
  726.       -- the security policy rules available at the specified time 
  727.       -- NULL parameter specifies "use default"
  728.  
  729.    o  req_services SET OF OBJECT IDENTIFIER,
  730.  
  731.    Outputs:
  732.  
  733.    o  major_status INTEGER,
  734.  
  735.    o  minor_status INTEGER,
  736.  
  737.    o  env_handle ENVIRONMENT HANDLE,
  738.  
  739.    o  actual_mech_type OBJECT IDENTIFIER, 
  740.       -- actual mechanism always indicated, never NULL 
  741.  
  742.    o  actual_policy OBJECT IDENTIFIER, 
  743.       -- actual policy always indicated, never NULL 
  744.  
  745.    o  actual_policy_time, 
  746.       -- actual time at which the above policy rules came into effect
  747.  
  748.    o  ret_services SET OF OBJECT IDENTIFIER,
  749.  
  750.  
  751.    Return major_status codes:
  752.  
  753.    o  GSS_S_COMPLETE indicates that environment-level information was
  754.       successfully initialized, and that IDU / P-IDU processing can 
  755.       begin on the newly-established environment.
  756.  
  757.    o  GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
  758.       performed on the credential structure referenced by
  759.       claimant_cred_handle failed, preventing further processing from
  760.       being performed using that credential structure.
  761.  
  762.    o  GSS_S_NO_CRED indicates that no environment was established, 
  763.       either because the input cred_handle was invalid or because the 
  764.       caller lacks authorization to access the referenced credentials.
  765.  
  766. Adams               Document Expiration:  26 May  1997                13
  767.  
  768.  
  769.    o  GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided
  770.       through the input claimant_cred_handle argument are no longer
  771.       valid, so environment establishment cannot be completed.
  772.  
  773.    o  GSS_S_BAD_MECH indicates that a mech_type unsupported by the
  774.       IDUP_GSS-API implementation was requested, causing the
  775.       environment establishment operation to fail.
  776.  
  777.    o  GSS_S_FAILURE indicates that environment setup could not be 
  778.       accomplished for reasons unspecified at the IDUP-GSS-API level, 
  779.       and that no interface-defined recovery action is available.
  780.  
  781.    This routine is used by an application which protects or unprotects 
  782.    IDUs.  Using information in the credentials structure referenced by 
  783.    claimant_cred_handle, IDUP_Establish_Env() initializes the data 
  784.    structures required to protect or unprotect IDUs.  The 
  785.    claimant_cred_handle, if non-NULL, must correspond to a valid 
  786.    credentials structure.
  787.  
  788.    This routine returns an env_handle for all future references to 
  789.    this environment; when protection, unprotection, or 
  790.    IDUP_Abolish_Env() calls are made, this handle value will be used 
  791.    as the input env_handle argument.
  792.  
  793.    It is the caller's responsibility to establish a communications path
  794.    to the intended recipients of the P-IDU, and to transmit the P-IDU to 
  795.    those recipients over that path.  This may occur subsequent to the 
  796.    IDUP_Abolish_Env() call.
  797.  
  798.    The req_services parameter may be used by the calling application to 
  799.    request that data origin authentication with integrity, 
  800.    confidentiality with integrity, evidence generation, and/or evidence 
  801.    verification services be available in the established environment.  
  802.    Requests can also be made for "trusted" or "untrusted" time services.
  803.    Requesting evidence generation or verification indicates that the 
  804.    calling application may wish to generate or verify evidence 
  805.    information for non-repudiation purposes (note:  an IDU protector may 
  806.    request that a flag be inserted into a P-IDU asking a recipient to 
  807.    provide an evidence of the type "non-repudiation of delivery"; 
  808.    however, the IDUP-GSS-API cannot by itself guarantee that the 
  809.    evidence will be sent because there is no way to force a target to 
  810.    send an evidence_token back to the IDU protector).
  811.  
  812.    Not all features will be available in all underlying mech_types; the 
  813.    returned value of ret_services indicates, as a function 
  814.    of mech_type processing capabilities and the initiator-provided input 
  815.    OBJECT IDs, the set of features which will be available in the 
  816.    environment. The value of this parameter is undefined unless the 
  817.    routine's major_status indicates COMPLETE.  Failure to provide the 
  818.    precise set of services desired by the caller does not cause 
  819.    environment establishment to fail; it is the caller's prerogative to 
  820.    abolish the environment if the service set provided is unsuitable for 
  821.    the caller's use.  The returned mech_type value indicates the 
  822.    specific mechanism employed in the environment, and will never 
  823.    indicate the value for "default".
  824.  
  825. Adams               Document Expiration:  26 May  1997                14
  826.  
  827.  
  828.    The following OBJECT IDs are defined for protection and unprotection 
  829.    services.  It is recognized that this list may grow over time.
  830.  
  831.       PER_CONF = { xx } 
  832.          -- perform data confidentiality (i.e., encrypt data) 
  833.       PER_DOA  = { xx } 
  834.          -- perform data origin authentication with data integrity 
  835.       PER_POO  = { xx } 
  836.          -- perform (i.e., create) non-repudiable "proof of origin" 
  837.       PER_POD  = { xx } 
  838.          -- perform (i.e., create) non-repudiable "proof of delivery" 
  839.       REC_CONF = { xx } 
  840.          -- receive data confidentiality (i.e., decrypt data) 
  841.       REC_DOA  = { xx } 
  842.          -- receive / verify DOA with data integrity 
  843.       REC_POO  = { xx } 
  844.          -- receive / verify "proof of origin" 
  845.       REC_POD  = { xx } 
  846.          -- receive / verify "proof of delivery" 
  847.       TTIME    = { xx }
  848.          -- trusted time availability 
  849.       UTIME    = { xx }
  850.          -- untrusted time availability 
  851.  
  852.    The PER_CONF return value (in the ret_services paramater) indicates 
  853.    whether the environment supports confidentiality services, and so 
  854.    informs the caller whether or not a request for encryption through 
  855.    a confidentiality service input to IDUP_Start_Protect() can be 
  856.    honored.  In similar fashion, the PER_DOA return value indicates 
  857.    whether DOA services are available in the established environment, 
  858.    and the PER_POO and PER_POD return values indicate whether evidence 
  859.    generation services are available.  The TTIME and UTIME values 
  860.    indicate whether trusted time and untrusted time are available for 
  861.    protection / unprotection services.
  862.  
  863.    Note that, unlike a GSS "context", an IDUP environment does not have 
  864.    an explicit lifetime associated with it.  Instead, it relies on the 
  865.    lifetime of the calling entity's credential (set by the caller in the 
  866.    GSS_Acquire_cred() call).  When the credential expires (or is 
  867.    explicitly deleted using the gss_release_cred() call), no new 
  868.    operations are allowed in the IDUP environment (although operations 
  869.    which have begun, such as the Protection set of calls, can be taken 
  870.    to completion).
  871.  
  872. 2.2.3. IDUP_Abolish_Env call
  873.  
  874.    Input:
  875.  
  876.    o  env_handle ENVIRONMENT HANDLE
  877.  
  878.    Outputs:
  879.  
  880.    o  major_status INTEGER,
  881.  
  882.    o  minor_status INTEGER,
  883.  
  884. Adams               Document Expiration:  26 May  1997                15
  885.  
  886.    Return major_status codes:
  887.  
  888.    o  GSS_S_COMPLETE indicates that the environment was recognized and 
  889.       that relevant environment-specific information was flushed.
  890.  
  891.    o  IDUP_S_NO_ENV indicates that no valid environment was recognized 
  892.       for the env_handle provided, so no deletion was performed.
  893.  
  894.    o  GSS_S_FAILURE indicates that the environment is recognized, but 
  895.       that the requested operation could not be performed for reasons 
  896.       unspecified at the IDUP-GSS-API level.
  897.  
  898.    This call is made to flush environment-specific information. (Once an 
  899.    environment is established, cached credential and environment-related 
  900.    info. is expected to be retained until an IDUP_Abolish_Env() call is 
  901.    made or until the cred. lifetime expires.)  Attempts to perform IDU 
  902.    processing on a deleted environment will result in error returns.
  903.  
  904. 2.2.4:   IDUP_Inquire_Env call
  905.  
  906.    Input:
  907.  
  908.    o  env_handle ENVIRONMENT HANDLE,
  909.  
  910.    Outputs:
  911.  
  912.    o  major_status INTEGER,
  913.  
  914.    o  minor_status INTEGER,
  915.  
  916.    o  mech_type OBJECT IDENTIFIER, -- the mechanism supporting this env. 
  917.  
  918.    o  policy OBJECT IDENTIFIER, -- the policy used in this env.
  919.  
  920.    o  policy_time, -- time at which the policy rules came into effect
  921.  
  922.    o  ret_services SET OF OBJECT IDENTIFIER,
  923.  
  924.    Return major_status codes:
  925.  
  926.    o  GSS_S_COMPLETE indicates that the referenced environment is valid
  927.       and that mech_type and other return values describe the 
  928.       corresponding characteristics of the environment.
  929.  
  930.    o  GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 
  931.       recognized, but that its associated credentials have expired, so 
  932.       that the requested operation cannot be performed.
  933.  
  934.    o  IDUP_S_NO_ENV indicates that no valid environment was recognized 
  935.       for the env_handle provided, so no return values can be provided.
  936.  
  937.    o  GSS_S_FAILURE indicates that the environment is recognized, but 
  938.       that the requested operation could not be performed for reasons 
  939.       unspecified at the IDUP-GSS-API level.
  940.  
  941.    This routine provides environment-related information to the caller.
  942.  
  943. Adams               Document Expiration:  26 May  1997                16
  944.  
  945.  
  946. 2.3.  Per-IDU calls
  947.  
  948.    This group of calls is used to perform IDU protection and 
  949.    unprotection processing on an established IDUP environment. Some of 
  950.    these calls may block pending network interactions (depending on the 
  951.    underlying mechanism in use).  These calls may be invoked by an IDU's 
  952.    protector or by the P-IDU's recipient.  The two sets of members of 
  953.    this group form a pair; the output from the protection set is 
  954.    typically meant to be input to the unprotection set.
  955.  
  956.    The per-IDU calls can support caller-requested data origin 
  957.    authentication with data integrity, confidentiality with data 
  958.    integrity, evidence, and evidence-requested-from-target services.  
  959.    The protection operations output a token which encapsulates all the 
  960.    information required to unprotect the IDU.  The token is passed to 
  961.    the target (possibly separate from the M-IDU) and is processed by the 
  962.    unprotection calls at that system.  Unprotection performs 
  963.    decipherment, DOA verification, evidence verification, or 
  964.    notification of evidence requested, as required.
  965.  
  966.    Each of the two main operations (protection and unprotection) may be 
  967.    separated into three parts:  "Start_Operation"; "Operation" (which 
  968.    may be called once for each buffer of input data); and 
  969.    "End_Operation".  This separation is available for the case where the 
  970.    IDU or P-IDU is to be processed one buffer at a time.  
  971.    "Start_Operation" allows the caller to specify or retrieve the 
  972.    appropriate "Quality" used during the processing.  "Operation" is 
  973.    concerned with the processing itself, receiving a buffer of input 
  974.    data and potentially returning a buffer of output data.  
  975.    "End_Operation" performs any required clean-up and creates the 
  976.    appropriate token or states whether the input token was verified.  
  977.  
  978.    If the IDU or P-IDU is wholly contained in a single buffer, the 
  979.    three-part protection/unprotection processing need not be done.  
  980.    Instead, protection and unprotection can be accomplished using only 
  981.    the "Start_Operation" call, simplifying application code.
  982.  
  983. 2.3.1.  Relationship to GSS-API
  984.  
  985.    The set of calls described in this section are used in place of the 
  986.    calls GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() -- now 
  987.    named GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() -- 
  988.    which are specified in [RFC-1508], since those calls are specific to 
  989.    a session-oriented environment.
  990.  
  991. Adams               Document Expiration:  26 May  1997                17
  992.  
  993.  
  994. 2.3.2.  The "SE" Calls
  995.  
  996. 2.3.2.1. IDUP_SE Parameter Bundles
  997.  
  998.    The concept of "parameter bundles" is used in the calls presented in 
  999.    the following subsections in order to simplify their presentation and 
  1000.    clarify their intended purpose and use.  See Section 2.3.2 for a more 
  1001.    complete description of parameter bundles.
  1002.  
  1003.    The following parameter bundles are used in the "SE" protection and 
  1004.    unprotection sets of calls. 
  1005.  
  1006.    o  Protect_Options PARAMETER BUNDLE
  1007.       o  Protect_Operation INTEGER {
  1008.             sign_only        (0), 
  1009.             encrypt_only     (1), 
  1010.             sign_and_encrypt (2), 
  1011.             clear_sign_only  (3) 
  1012.          }
  1013.       o  sign_qop_alg      UNSIGNED INTEGER,
  1014.       o  enc_qop_alg       UNSIGNED INTEGER,
  1015.       o  idu_type_string   OCTET STRING
  1016.  
  1017.    o  PIDU_Information PARAMETER BUNDLE
  1018.       o  Protect_Options   PARAMETER BUNDLE,
  1019.       o  originator_name   INTERNAL NAME,
  1020.       o  protection_time   INTEGER
  1021.  
  1022.    o  Bad_Target_Name PARAMETER BUNDLE, 
  1023.       o  bad_targ_name INTERNAL NAME, 
  1024.       o  bad_targ_status INTEGER, 
  1025.          -- a (mechanism-defined) status flag giving the reason 
  1026.          -- for rejection of the name in bad_targ_name
  1027.  
  1028.    o  Target_Info PARAMETER BUNDLE, 
  1029.       o  targ_names SET OF INTERNAL NAME, 
  1030.       o  bad_targ_count INTEGER, 
  1031.       o  Bad_Target_Name PARAMETER BUNDLE, 
  1032.  
  1033.  
  1034. 2.3.2.2. IDUP_SE major_status codes
  1035.  
  1036.    The following major_status return codes are defined for the "SE" 
  1037.    calls in this section:
  1038.  
  1039.    o  GSS_S_COMPLETE indicates that the requested operation has 
  1040.       completed successfully.
  1041.  
  1042.    o  GSS_S_CONTINUE_NEEDED indicates that the output buffer 
  1043.       supplied is too small to hold the generated data.  The application 
  1044.       should continue calling this routine (until GSS_S_COMPLETE is 
  1045.       returned) in order to get all remaining data.
  1046.  
  1047.    o  IDUP_S_MORE_DATA_NEEDED indicates that more input data is needed 
  1048.       for the StartUnprotect operation (e.g., so that PIDU_Information 
  1049.       or initial_idu_buffer may be returned).
  1050.  
  1051.    o  GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 
  1052.       recognized, but that its associated credentials have expired, so 
  1053.       that the requested operation cannot be performed.
  1054.  
  1055. Adams               Document Expiration:  26 May  1997                18
  1056.  
  1057.  
  1058.    o  IDUP_S_NO_ENV indicates that no valid environment was recognized 
  1059.       for the env_handle provided.
  1060.  
  1061.    o  GSS_S_BAD_QOP indicates that the provided qop_alg value is not 
  1062.       recognized or supported for the environment.
  1063.  
  1064.    o  GSS_S_FAILURE indicates that the environment is recognized, but 
  1065.       that the requested operation could not be performed for reasons 
  1066.       unspecified at the IDUP-GSS-API level.
  1067.  
  1068.    If Target_Info is used as an input parameter (i.e., if an encryption 
  1069.    operation is being performed), the following major_status return code 
  1070.    is also defined:
  1071.  
  1072.    o  IDUP_S_BAD_TARG_INFO indicates that all the information regarding 
  1073.       the target(s) is invalid or is insufficient for the protection of 
  1074.       an IDU, so P-IDU cannot be created.
  1075.  
  1076.    Note for this return code that if one or more of the targets in 
  1077.    targ_names cannot be used as a valid recipient of the P-IDU, these 
  1078.    names will be returned in bad_targ_names (with associated status 
  1079.    codes in bad_targ_status).  As long as at least one of the targets 
  1080.    can be used, however, this does not cause this call to fail (i.e., 
  1081.    the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the 
  1082.    caller's prerogative to discontinue IDU protection if the target set 
  1083.    which can be used is unsuitable for the caller's purposes.
  1084.  
  1085.  
  1086. 2.3.2.3. IDUP_SE Purpose
  1087.  
  1088.    The "SE" group of calls provides a very simple, high-level 
  1089.    interface to underlying IDUP mechanisms when application developers 
  1090.    need access only to signature and encryption protection/unprotection 
  1091.    services.  It includes both the single-buffer and multiple-buffer IDU 
  1092.    cases and can be used for signing only, encrypting only, signing and 
  1093.    encrypting (where the signature is computed on the cleartext data and 
  1094.    the signature itself is not encrypted), and "clear signing" (where 
  1095.    the data is not modified in any way and the signature itself is 
  1096.    returned (unencapsulated) as a separate item).
  1097.  
  1098.    The SE calls may be viewed by mechanism implementors as an "API" to 
  1099.    the more powerful Protection and Unprotection sets of calls defined 
  1100.    later and so may be implemented as simple mapping functions to those 
  1101.    calls.  Application callers, on the other hand, may find that the SE 
  1102.    calls are all they currently need for many environments and may 
  1103.    migrate to the more general calls only at some time in the future 
  1104.    when they have need of data labeling, non-repudiation, or "directed 
  1105.    receipts" types of services.  To assist in this migration path, it 
  1106.    is recommended that mechanism implementors support the full set of 
  1107.    IDUP calls (i.e., both the SE calls and the more powerful calls) even 
  1108.    though some calling applications will only use the SE calls in the 
  1109.    short term.
  1110.  
  1111.  
  1112. Adams               Document Expiration:  26 May  1997                19
  1113.  
  1114. 2.3.2.4. IDUP_SE_SingleBuffer_Protect call
  1115.  
  1116.    Inputs:
  1117.    o  env_handle ENVIRONMENT HANDLE,
  1118.    o  Protect_Options PARAMETER BUNDLE,
  1119.    o  Target_Info PARAMETER BUNDLE, 
  1120.       -- used if Protect_Options is encrypt_only or sign_and_encrypt 
  1121.    o  idu_buffer OCTET STRING
  1122.  
  1123.    Outputs:
  1124.    o  major_status INTEGER,
  1125.    o  minor_status INTEGER,
  1126.    o  pidu_buffer OCTET STRING, 
  1127.    o  sig_token OCTET STRING
  1128.       -- used if Protect_Options is clear_sign_only 
  1129.  
  1130.    Using the security environment referenced by env_handle, encrypt 
  1131.    and/or sign the supplied IDU.  If "clear signing" is performed, the 
  1132.    signature will be returned in sig_token and pidu_buffer may be empty 
  1133.    (depends on underlying mechanism).
  1134.  
  1135. 2.3.2.5. IDUP_SE_SingleBuffer_Unprotect call
  1136.  
  1137.    Inputs:
  1138.    o  env_handle ENVIRONMENT HANDLE,
  1139.    o  pidu_buffer OCTET STRING,
  1140.       -- may contain an IDU if sig_token is non-NULL (i.e., if 
  1141.       -- clear_sign_only protection was applied)
  1142.    o  sig_token OCTET STRING
  1143.  
  1144.    Outputs:
  1145.    o  major_status INTEGER,
  1146.    o  minor_status INTEGER,
  1147.    o  idu_buffer OCTET STRING, 
  1148.       -- may be empty if clear_sign_only protection was applied (depends 
  1149.       -- on underlying mechanism)
  1150.    o  PIDU_Information PARAMETER BUNDLE
  1151.  
  1152.    Using the security environment referenced by env_handle, decrypt 
  1153.    and/or verify the supplied PIDU and return the contained IDU along 
  1154.    with all available PIDU_Information. 
  1155.  
  1156.  
  1157. 2.3.2.6. IDUP_SE_MultiBuffer_StartProtect call
  1158.  
  1159.    Inputs:
  1160.    o  env_handle ENVIRONMENT HANDLE,
  1161.    o  Protect_Options PARAMETER BUNDLE,
  1162.    o  Target_Info PARAMETER BUNDLE
  1163.       -- used if Protect_Options is encrypt_only or sign_and_encrypt
  1164.  
  1165.    Outputs:
  1166.    o  major_status INTEGER,
  1167.    o  minor_status INTEGER,
  1168.    o  initial_pidu_buffer OCTET STRING
  1169.       -- may be empty (depends on underlying mechanism)
  1170.  
  1171.    Using the security environment referenced by env_handle, initialize 
  1172.    the data structures required to begin the process of signing 
  1173.    and/or encrypting the IDU (which will be supplied in multiple buffers
  1174.    to the Process_Buffer call).
  1175.  
  1176. Adams               Document Expiration:  26 May  1997                20
  1177.  
  1178. 2.3.2.7. IDUP_SE_MultiBuffer_EndProtect call
  1179.  
  1180.    Inputs:
  1181.    o  env_handle ENVIRONMENT HANDLE
  1182.  
  1183.    Outputs:
  1184.    o  major_status INTEGER,
  1185.    o  minor_status INTEGER,
  1186.    o  final_pidu_buffer OCTET STRING,
  1187.    o  sig_token OCTET STRING
  1188.       -- used if Protect_Options was clear_sign_only 
  1189.  
  1190.    Using the security environment referenced by env_handle, complete the 
  1191.    protection processing on the data and place the computed output in 
  1192.    final_pidu_buffer and/or sig_token. Successful application of 
  1193.    IDUP_SE_MultiBuffer_EndProtect() does not guarantee that unprotection 
  1194.    can necessarily be performed successfully when the P-IDU arrives at 
  1195.    the target (for example, it may be damaged in transit).
  1196.  
  1197. 2.3.2.8. IDUP_SE_MultiBuffer_StartUnprotect call
  1198.  
  1199.    Inputs:
  1200.    o  env_handle ENVIRONMENT HANDLE,
  1201.    o  initial_pidu_buffer OCTET STRING,
  1202.    o  sign_qop_alg_in UNSIGNED INTEGER,
  1203.       -- used if Protect_Options was clear_sign_only; 
  1204.       -- if NULL, then sig_token must be supplied
  1205.    o  sig_token OCTET STRING
  1206.       -- used if Protect_Options was clear_sign_only; 
  1207.       -- if NULL, then sign_qop_alg_in must be supplied
  1208.  
  1209.    Outputs:
  1210.    o  major_status INTEGER,
  1211.    o  minor_status INTEGER,
  1212.    o  PIDU_Information PARAMETER BUNDLE,
  1213.       -- returns all available information 
  1214.    o  initial_idu_buffer OCTET STRING
  1215.       -- may be empty 
  1216.  
  1217.    Using the security environment referenced by env_handle, initialize 
  1218.    the data structures required to begin the process of decrypting 
  1219.    and/or verifying the PIDU (which will be supplied in multiple buffers
  1220.    to the Process_Buffer call).
  1221.  
  1222. 2.3.2.9. IDUP_SE_MultiBuffer_EndUnprotect call
  1223.  
  1224.    Inputs:
  1225.    o  env_handle ENVIRONMENT HANDLE,
  1226.    o  sig_token OCTET STRING
  1227.       -- used if Protect_Options was clear_sign_only 
  1228.  
  1229.    Outputs:
  1230.    o  major_status INTEGER,
  1231.    o  minor_status INTEGER,
  1232.    o  PIDU_Information PARAMETER BUNDLE,
  1233.       -- returns all available information 
  1234.    o  final_idu_buffer OCTET STRING
  1235.       -- may be empty 
  1236.  
  1237.    Using the security environment referenced by env_handle, complete the 
  1238.    decryption and/or verification processing on the data and place any 
  1239.    residual output in final_idu_buffer. 
  1240.  
  1241. Adams               Document Expiration:  26 May  1997                21
  1242.  
  1243.  
  1244.  
  1245. 2.3.2.10. IDUP_SE_Process_Buffer call
  1246.  
  1247.    Inputs:
  1248.    o  env_handle ENVIRONMENT HANDLE,
  1249.    o  input_buffer OCTET STRING,
  1250.  
  1251.    Outputs:
  1252.    o  major_status INTEGER,
  1253.    o  minor_status INTEGER,
  1254.    o  output_buffer OCTET STRING
  1255.       -- may be zero length (depends on underlying mechanism and 
  1256.       -- corresponding Start() call and Protect_Options value)
  1257.  
  1258.    Using the security environment referenced by env_handle, continue the 
  1259.    processing on the data in input_buffer and, if it is available, put
  1260.    any resulting output data in output_buffer.  The application calls 
  1261.    this routine over and over again with new buffers of data until it
  1262.    has processed all the data buffers of the IDU/PIDU. It then calls
  1263.    the appropriate End() call to complete the processing.
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269. 2.3.2. Parameter Bundles
  1270.  
  1271.    The concept of "parameter bundles" is used in the calls presented in 
  1272.    the following subsections in order to simplify their presentation and 
  1273.    (hopefully) clarify their intended purpose and use.  A parameter 
  1274.    bundle is simply a set of closely-related parameters of a call which 
  1275.    are either all used by / available to the calling application or all 
  1276.    not used by / unavailable to the calling application.  These 
  1277.    parameters may be all input parameters, all output parameters, or 
  1278.    any combination of the two.
  1279.  
  1280. Adams               Document Expiration:  26 May  1997                22
  1281.  
  1282.    A typical use envisioned for parameter bundles in a language such as 
  1283.    C would be as a structure, where individual parameters in the bundle 
  1284.    are structure members.  The calling application wishing to use a 
  1285.    particular bundle would then allocate the appropriate structure 
  1286.    variable, assign the desired input values to the appropriate members, 
  1287.    and pass the address of the structure as the bundle "parameter".  On 
  1288.    output, the values of the appropriate output members may be read.  An 
  1289.    application not wishing to use a particular bundle (or one which is 
  1290.    satisfied with default values for all input parameters of the bundle 
  1291.    and which doesn't care about output values), can pass NULL as the 
  1292.    bundle "parameter".  From the mechanism implementor's perspective, if 
  1293.    a parameter bundle is not supported (for example, if it represents a 
  1294.    security service which is not supported by the implementation), then 
  1295.    any non-NULL value passed as the bundle parameter will generate an 
  1296.    error status return code.
  1297.  
  1298.    The following parameter bundles are used in the subsequent protection 
  1299.    and unprotection sets of calls.  A parameter preceded by "(I)" is an 
  1300.    input parameter; one preceded by "(O)" is an output parameter; one 
  1301.    preceded by neither is an input if the bundle itself is an input and 
  1302.    is an output if the bundle itself is an output; one preceded by "(X)" 
  1303.    is the opposite:  an output if the bundle itself is an input and an 
  1304.    input if the bundle itself is an output.
  1305.  
  1306.       o Mech_Specific_Info PARAMETER BUNDLE
  1307.         -- actual parameters included in this bundle are defined by (and 
  1308.         -- specific to) the underlying mechanism 
  1309.  
  1310.  
  1311.       o Sensitivity PARAMETER BUNDLE, 
  1312.         -- actual parameters included in this bundle are defined by (and 
  1313.         -- specific to) the underlying mechanism, but may include 
  1314.         -- codified values for "Unclassified", "Secret", "Top Secret", 
  1315.         -- and so on 
  1316.  
  1317.  
  1318.       o Service_Creation_Info PARAMETER BUNDLE 
  1319.         -- actual parameters included in this bundle are defined by (and 
  1320.         -- specific to) the underlying mechanism, but it is mandatory 
  1321.         -- that they include at least service_id and Quality 
  1322.  
  1323.  
  1324.       o Service_Verification_Info PARAMETER BUNDLE 
  1325.         -- actual parameters included in this bundle are defined by (and 
  1326.         -- specific to) the underlying mechanism, but it is mandatory 
  1327.         -- that they include at least service_id and Quality 
  1328.  
  1329.  
  1330.       o  Quality PARAMETER BUNDLE 
  1331.          o  qop_algs UNSIGNED INTEGER, 
  1332.          o  validity UNSIGNED INTEGER, 
  1333.             -- protection guaranteed to be valid until time specified 
  1334.          o  policy_id OBJECT IDENTIFIER, 
  1335.             -- security policy under which protection is/was carried out 
  1336.          o  allow_policy_mapping BOOLEAN, 
  1337.             -- determines whether mapping between policy IDs is allowed 
  1338.  
  1339. Adams               Document Expiration:  26 May  1997                23
  1340.  
  1341.  
  1342.       o  Idu_Information PARAMETER BUNDLE, 
  1343.          o  idu_type_oid OBJECT IDENTIFIER, 
  1344.          o  idu_type_string OCTET STRING, 
  1345.          o  idu_title OCTET STRING, 
  1346.          o  idu_sensitivity Sensitivity, 
  1347.          o  pidu_type_oid OBJECT IDENTIFIER, 
  1348.          o  pidu_type_string OCTET STRING, 
  1349.          o  pidu_title OCTET STRING, 
  1350.          o  pidu_sensitivity Sensitivity, 
  1351.  
  1352.  
  1353.       o  Prot_Information PARAMETER BUNDLE, 
  1354.          o  originator_name INTERNAL NAME, 
  1355.          o  idu_information Idu_Information, 
  1356.          o  protection_time INTEGER, 
  1357.  
  1358.  
  1359.       o  Special_Conditions PARAMETER BUNDLE, 
  1360.          o  prot_oper_id INTEGER, 
  1361.          o  use_trusted_time BOOLEAN, 
  1362.          o  use_untrusted_time BOOLEAN, 
  1363.  
  1364.  
  1365.       o  Bad_Target_Name PARAMETER BUNDLE, 
  1366.          o  (O) bad_targ_name INTERNAL NAME, 
  1367.          o  (O) bad_targ_status INTEGER, 
  1368.                 -- a (mechanism-defined) status flag giving the reason 
  1369.                 -- for rejection of the name in bad_targ_name
  1370.  
  1371.  
  1372.       o  Target_Info PARAMETER BUNDLE, 
  1373.          o      targ_names SET OF INTERNAL NAME, 
  1374.          o  (O) bad_targ_count INTEGER, 
  1375.          o  (O) bad_target_name Bad_Target_Name, 
  1376.  
  1377.  
  1378.       o  General_Service_Data PARAMETER BUNDLE, 
  1379.          o      target_info Target_Info, 
  1380.          o  (X) unencapsulated_token OCTET STRING, 
  1381.                 -- zero length if encapsulation_request is TRUE 
  1382.          o  (O) minor_status INTEGER, 
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398. Adams               Document Expiration:  26 May  1997                24
  1399.  
  1400.  
  1401.    Three types of protection services are defined in IDUP.  These are 
  1402.  
  1403.       1. perform unsolicited service (i.e., act on a locally-generated 
  1404.          service request), 
  1405.       2. perform solicited service (i.e., act on a remotely-generated 
  1406.          service request), and 
  1407.       3. perform service solicitation (i.e., send a service request to 
  1408.          the remote end).
  1409.  
  1410.    As an originator, applying data confidentiality with data integrity, 
  1411.    or data origin authentication with data integrity, or proof of origin 
  1412.    evidence is an example of service type 1.  As a target, creating a 
  1413.    proof of delivery (i.e., receipt) evidence token as the result of a 
  1414.    request received from the originator is an example of service type 2.  
  1415.    Finally, as an originator, submitting a request that one or more 
  1416.    targets return a receipt for the data sent is an example of service 
  1417.    type 3.
  1418.  
  1419.    The first four parameters in the Prot_Service parameter bundle 
  1420.    pertain to all service types; the fifth parameter is used if and only 
  1421.    if service type 2 is desired; parameters 6-8 are used if and only if 
  1422.    service type 3 is desired. 
  1423.  
  1424.       o  Prot_Service PARAMETER BUNDLE
  1425.          o  (I) prot_service_type INTEGER, 
  1426.          o  (I) service_id OBJECT IDENTIFIER, 
  1427.          o  (I) quality Quality, 
  1428.                 -- NULL specifies default Quality
  1429.          o  (I) general_service_data General_Service_Data, 
  1430.          o  (I) service_creation_info Service_Creation_Info,
  1431.          o  (I) service_to SET OF INTERNAL NAME,
  1432.          o  (O) service_verification_info Service_Verification_Info, 
  1433.          o  (O) service_verification_info_id INTEGER, 
  1434.  
  1435.    Also, three types of unprotection services are defined.  These are
  1436.  
  1437.       1. receive unsolicited service (i.e., process unrequested 
  1438.          remotely-generated service), 
  1439.       2. receive solicited service (i.e., process remotely-generated 
  1440.          response to locally-generated request), and 
  1441.       3. receive service solicitation (i.e., process req. from rem. end)
  1442.  
  1443.    As a target, unprotecting an encrypted message, or verifying the 
  1444.    originator's proof of origin is an example of service type 1.  As an 
  1445.    originator, verifying a proof of delivery which you requested from a 
  1446.    target is an example of service type 2.  Finally, as a target, 
  1447.    receiving a request from an originator for a proof of delivery is an 
  1448.    example of service type 3.
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457. Adams               Document Expiration:  26 May  1997                25
  1458.  
  1459.  
  1460.    The first four parameters in the Unprot_Service parameter bundle 
  1461.    pertain to all service types; parameters 5-6 are used if and only if 
  1462.    service type 2 is required; parameters 7-8 are used only if service 
  1463.    type 3 is required.
  1464.  
  1465.       o  Unprot_Service PARAMETER BUNDLE
  1466.          o  (O) unprot_service_type INTEGER, 
  1467.          o  (O) service_id OBJECT IDENTIFIER, 
  1468.          o  (O) quality Quality, 
  1469.                 -- actual Quality specified (never NULL)
  1470.          o  (O) general_service_data General_Service_Data, 
  1471.          o  (O) service_verification_info_id INTEGER, 
  1472.          o  (I) service_verification_info Service_Verification_Info, 
  1473.          o  (O) service_to SET OF INTERNAL NAME,
  1474.          o  (O) service_creation_info Service_Creation_Info, 
  1475.  
  1476.  
  1477. 2.3.3. IDUP_Start_Protect call
  1478.  
  1479.    Inputs:
  1480.  
  1481.    o  env_handle ENVIRONMENT HANDLE,
  1482.  
  1483.    o  Mech_Specific_Info PARAMETER BUNDLE, 
  1484.       -- NULL selects the mechanism-defined default values 
  1485.  
  1486.    o  Idu_Information PARAMETER BUNDLE,
  1487.  
  1488.    o  Special_Conditions PARAMETER BUNDLE, 
  1489.  
  1490.    o  encapsulation_request BOOLEAN, 
  1491.  
  1492.    o  single_idu_buffer OCTET STRING,
  1493.       -- non-zero length for this buffer means that Protect/End_Protect 
  1494.       -- won't be called (i.e., entire IDU is contained in this buffer)
  1495.  
  1496.    o  Target_Info PARAMETER BUNDLE, 
  1497.  
  1498.    o  Services_to_Perform SET OF Prot_Service, 
  1499.  
  1500.    Outputs:
  1501.  
  1502.    o  major_status INTEGER,
  1503.  
  1504.    o  minor_status INTEGER,
  1505.  
  1506.    o  midu_buffer OCTET STRING,
  1507.       -- zero length if encapsulation_request is TRUE; 
  1508.       -- may be zero length otherwise (depends on underlying mechanism) 
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516. Adams               Document Expiration:  26 May  1997                26
  1517.  
  1518.  
  1519.    o  pidu_buffer OCTET STRING, 
  1520.       -- zero length if encapsulation_request is FALSE; 
  1521.       -- may be zero length otherwise (depends on underlying mechanism) 
  1522.  
  1523.    Return major_status codes:
  1524.  
  1525.    o  GSS_S_COMPLETE indicates that the protection process can begin
  1526.       (or has completed, if single_idu_buffer has non-zero length).
  1527.  
  1528.    o  GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 
  1529.       supplied is too small to hold the generated data.  The application 
  1530.       should continue calling this routine (until GSS_S_COMPLETE is 
  1531.       returned) in order to get all remaining data.
  1532.  
  1533.    o  GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 
  1534.       recognized, but that its associated credentials have expired, so 
  1535.       that the requested operation cannot be performed.
  1536.  
  1537.    o  IDUP_S_NO_ENV indicates that no valid environment was recognized 
  1538.       for the env_handle provided.
  1539.  
  1540.    o  IDUP_S_ENCAPSULATION_UNAVAIL indicates that the underlying 
  1541.       mechanism does not support encapsulation of the M-IDU into the 
  1542.       token.
  1543.  
  1544.    o  IDUP_S_MORE_DATA_NEEDED indicates whether protection is completed 
  1545.       by this call or by IDUP_End_Protect()  (e.g., whether more data 
  1546.       buffers are required for evidence generation) 
  1547.  
  1548.    o  IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 
  1549.       does not support the service requested.
  1550.  
  1551.    o  IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 
  1552.       requested (TTIME or UTIME) is not available in the environment.
  1553.  
  1554.    o  IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 
  1555.       is not recognized or supported in the underlying mechanism.
  1556.  
  1557.    o  GSS_S_BAD_QOP indicates that the provided qop_algs value is not 
  1558.       recognized or supported for the environment.
  1559.  
  1560.    o  IDUP_S_BAD_TARG_INFO indicates that all the information regarding 
  1561.       the target(s) is invalid or is insufficient for the protection of 
  1562.       an IDU, so P-IDU cannot be created.
  1563.  
  1564.    o  GSS_S_FAILURE indicates that the environment is recognized, but 
  1565.       that the requested operation could not be performed for reasons 
  1566.       unspecified at the IDUP-GSS-API level.
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575. Adams               Document Expiration:  26 May  1997                27
  1576.  
  1577.  
  1578.    Using the security environment referenced by env_handle, initialize 
  1579.    the data structures required to begin the process of protecting the 
  1580.    IDU buffers.  The caller requests specific protection services by 
  1581.    supplying the appropriate Prot_Service parameter bundles in 
  1582.    Services_to_Perform.  Each service is able to return a minor status 
  1583.    code to the calling application, if necessary.
  1584.  
  1585.    The calling application, knowing the size of the IDU it wishes to 
  1586.    protect and the buffer size which it has available to it, can choose 
  1587.    to input the entire IDU in a single buffer and omit the subsequent 
  1588.    IDUP_Protect() and IDUP_End_Protect() calls.  Furthermore, the 
  1589.    application can request that the resulting M-IDU be encapsulated in 
  1590.    the token -- so that the token contains the entire P-IDU -- rather 
  1591.    than having it be returned separately in midu_buffer.  Encapsulation, 
  1592.    however, may not be supported by all underlying mechanisms or 
  1593.    implementations; if this is the case, the 
  1594.    IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and 
  1595.    M-IDU will be returned in midu_buffer.
  1596.  
  1597.    For those mechanisms which allow or require multiple stages of 
  1598.    processing, each producing a different aspect of protection for the 
  1599.    IDU, the operation identifier prot_oper_id is used to specify 
  1600.    which stage is currently being requested by the application.  An 
  1601.    example where this would be useful is a mechanism which implements 
  1602.    the signed Message Security Protocol [MSP].  As another example, a 
  1603.    mechanism may choose to do a digital signature in two stages:  one 
  1604.    for the hashing of the message and another for the signature on the 
  1605.    hash.  The calling application would therefore use the protection set 
  1606.    of calls on the IDU in stage 1 and then use the protection set of 
  1607.    calls on the token (from stage 1) in stage 2.  
  1608.  
  1609.    Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where 
  1610.    "n" is the number of stages as defined by the mechanism (typically 1 
  1611.    or 2)).  The calling application uses this parameter to indicate to 
  1612.    the underlying mechanism whether it wishes to do stage 1 of 
  1613.    protection / unprotection processing, or stage 2, and so on.
  1614.  
  1615.    If one or more of the targets in targ_names cannot be used as a valid 
  1616.    recipient of the P-IDU, these names will be returned in 
  1617.    bad_targ_names (with associated status codes in bad_targ_status).  As 
  1618.    long as at least one of the targets can be used, this does not cause 
  1619.    this call to fail; it is the caller's prerogative to discontinue IDU 
  1620.    protection if the target set which can be used is unsuitable for the 
  1621.    caller's purposes.  Note that each Prot_Service parameter bundle can 
  1622.    also input a list of targ_names; this is used if a separate list is 
  1623.    to be used for that service only (the general list of targets is to 
  1624.    be used for all services unless overridden in this way).
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634. Adams               Document Expiration:  26 May  1997                28
  1635.  
  1636.  
  1637. 2.3.4. IDUP_Protect call
  1638.  
  1639.    Inputs:
  1640.  
  1641.    o  env_handle ENVIRONMENT HANDLE,
  1642.  
  1643.    o  input_buffer OCTET STRING,
  1644.  
  1645.    Outputs:
  1646.  
  1647.    o  major_status INTEGER,
  1648.  
  1649.    o  minor_status INTEGER,
  1650.  
  1651.    o  output_buffer OCTET STRING
  1652.       -- may be zero length if encapsulation_request was set to TRUE in 
  1653.       -- IDUP_Start_Protect() (depends on underlying mechanism)
  1654.  
  1655.    Return major_status codes:
  1656.  
  1657.    o  GSS_S_COMPLETE indicates that the input_buffer has successfully 
  1658.       been included in the protection computation.
  1659.  
  1660.    o  IDUP_S_NO_ENV indicates that no valid environment was recognized 
  1661.       for the env_handle provided.
  1662.  
  1663.    o  GSS_S_FAILURE indicates that the environment is recognized, but 
  1664.       that the required operation could not be performed for reasons 
  1665.       unspecified at the IDUP-GSS-API level.
  1666.  
  1667.    Using the security environment referenced by env_handle, continue the 
  1668.    protection processing on the data in input_buffer and, if the 
  1669.    underlying mechanism defines this, put any resulting P-IDU/M-IDU data 
  1670.    in output_buffer.  The application calls this routine over and over 
  1671.    again with new buffers of data until it has protected all the data 
  1672.    buffers of the IDU.  It then calls IDUP_End_Protect() to complete the 
  1673.    protection processing.
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693. Adams               Document Expiration:  26 May  1997                29
  1694.  
  1695.  
  1696. 2.3.5. IDUP_End_Protect call
  1697.  
  1698.    Inputs:
  1699.  
  1700.    o  env_handle ENVIRONMENT HANDLE,
  1701.  
  1702.    Outputs:
  1703.  
  1704.    o  major_status INTEGER,
  1705.  
  1706.    o  minor_status INTEGER,
  1707.  
  1708.    o  Services_to_Perform SET OF Prot_Service, 
  1709.  
  1710.    o  final_midu_buffer OCTET STRING,
  1711.       -- zero length if encapsulation_request was set to TRUE in 
  1712.       -- IDUP_Start_Protect(), in which case pidu is used
  1713.  
  1714.    o  final_pidu_buffer OCTET STRING,
  1715.       -- zero length if encapsulation_request was set to FALSE in 
  1716.       -- IDUP_Start_Protect(), in which case token and midu are used
  1717.  
  1718.  
  1719.    Return major_status codes:
  1720.  
  1721.    o  GSS_S_COMPLETE indicates that the protection computation has been 
  1722.       successfully completed and the resulting P-IDU is ready for 
  1723.       transfer.  If defined by the underlying mechanism, 
  1724.       final_midu_buffer will contain any residual M-IDU data.
  1725.  
  1726.    o  GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 
  1727.       supplied is too small to hold the generated data.  The application 
  1728.       should continue calling this routine (until GSS_S_COMPLETE is 
  1729.       returned) in order to get all remaining data.
  1730.  
  1731.    o  IDUP_S_NO_ENV indicates that no valid environment was recognized 
  1732.       for the env_handle provided.
  1733.  
  1734.    o  GSS_S_FAILURE indicates that the environment is recognized, but 
  1735.       that the requested operation could not be performed for reasons 
  1736.       unspecified at the IDUP-GSS-API level.
  1737.  
  1738.    Using the security environment referenced by env_handle, complete the 
  1739.    protection processing on the data and place the computed output in 
  1740.    final_pidu_buffer (or final_midu_buffer and the unencapsulated_token 
  1741.    parameter for each Prot_Service).  If a service was requested from 
  1742.    one or more targets in Start_Protect() - and if this is supported by 
  1743.    the underlying mechanism - Service_Verification_Info will hold 
  1744.    whatever data is necessary for the mechanism to verify a service 
  1745.    returned by a target (unprotector) of the P-IDU.  Successful 
  1746.    application of IDUP_End_Protect() does not guarantee that the 
  1747.    corresponding unprotection set of calls can necessarily be performed 
  1748.    successfully when the P-IDU arrives at the target (for example, it 
  1749.    may be damaged in transit).
  1750.  
  1751.  
  1752. Adams               Document Expiration:  26 May  1997                30
  1753.  
  1754.  
  1755. 2.3.6. IDUP_Start_Unprotect call
  1756.  
  1757.    Inputs:
  1758.  
  1759.    o  env_handle ENVIRONMENT HANDLE,
  1760.  
  1761.    o  Mech_Specific_Info PARAMETER BUNDLE, 
  1762.       -- NULL selects the mechanism-defined default values 
  1763.  
  1764.    o  single_data_buffer OCTET STRING,
  1765.       -- non-zero length for this buffer means that IDUP_Unprotect() and 
  1766.       -- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU 
  1767.       -- (if encapsulation is used) or M-IDU (if encap. is not used) 
  1768.       -- is contained in this buffer) 
  1769.  
  1770.    o  partial_pidu_buffer OCTET STRING,
  1771.       -- may be an arbitrary-sized piece of the full pidu (if the 
  1772.       -- application's buffer isn't large enough to hold entire pidu). 
  1773.       -- Used if pidu_buffer will be input a buffer at a time (except 
  1774.       -- that the final buffer must be passed in final_pidu_buffer 
  1775.       -- rather than partial_pidu_buffer).  Only one of 
  1776.       -- single_pidu_buffer and partial(final)_pidu_buffer can have 
  1777.       -- nonzero length.
  1778.  
  1779.    o  final_pidu_buffer OCTET STRING,
  1780.  
  1781.    o  Special_Conditions PARAMETER BUNDLE, 
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787. Adams               Document Expiration:  26 May  1997                31
  1788.  
  1789.  
  1790.    Outputs:
  1791.  
  1792.    o  major_status INTEGER,
  1793.  
  1794.    o  minor_status INTEGER,
  1795.  
  1796.    o  Services_to_Receive SET OF Unprot_Service, 
  1797.  
  1798.    o  Prot_Information PARAMETER BUNDLE, 
  1799.  
  1800.    o  single_idu_buffer OCTET STRING,
  1801.       -- if this buffer has non-zero length, then service processing has 
  1802.       -- been completed on the data in single_pidu_buffer 
  1803.  
  1804.    o  initial_idu_buffer OCTET STRING,
  1805.       -- holds any data from partial(final)_pidu_buffer which has been 
  1806.       -- unprotected; remaining data will be returned by Unprotect and 
  1807.       -- End_Unprotect as they are called with successive buffers of 
  1808.       -- pidu 
  1809.  
  1810.    o  Service_Verification_Info PARAMETER BUNDLE, 
  1811.       -- used only if target is on "service_to" list in Unprot_Service 
  1812.  
  1813.    o  service_verification_info_id INTEGER, 
  1814.       -- used only if target is on "service_to" list in Unprot_Service 
  1815.  
  1816.    Return major_status codes:
  1817.  
  1818.    o  GSS_S_COMPLETE indicates that unprotection processing can begin
  1819.       (or has completed, if single_idu_buffer has non-zero length).
  1820.  
  1821.    o  IDUP_S_INCOMPLETE indicates that the unprotection of the P-IDU 
  1822.       is not yet complete (i.e., a determination cannot yet be made on 
  1823.       the validity of the P-IDU).  The application should call 
  1824.       IDUP_Form_Complete_PIDU and then should call this function again 
  1825.       with the complete P-IDU.  (This status code is used in 
  1826.       IDUP_Start_Unprotect only if single_idu_buffer has non-zero 
  1827.       length) 
  1828.  
  1829.    o  GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 
  1830.       supplied is too small to hold the generated data.  The application 
  1831.       should continue calling this routine (until GSS_S_COMPLETE is 
  1832.       returned) in order to get all remaining data.
  1833.  
  1834.    o  IDUP_S_MORE_PIDU_NEEDED indicates that not enough of the P-IDU 
  1835.       has been input yet for the completion of Start_Protect.  The 
  1836.       application should call this routine again with another buffer 
  1837.       of P-IDU in partial_pidu_buffer. 
  1838.  
  1839.    o  GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 
  1840.       on the received P-IDU failed, preventing further processing
  1841.       from being performed.
  1842.  
  1843.    o  IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied 
  1844.       do not contain the information necessary for P-IDU unprotection.
  1845.  
  1846. Adams               Document Expiration:  26 May  1997                32
  1847.  
  1848.  
  1849.    o  IDUP_S_MORE_DATA_NEEDED indicates whether unprotection is 
  1850.       completed by this call or by IDUP_End_Unprotect()  (e.g., whether 
  1851.       more data buffers are required for unprotection) 
  1852.  
  1853.    o  GSS_S_DEFECTIVE_VERIF indicates that consistency checks performed 
  1854.       on Service_Verification_Info failed, preventing further processing 
  1855.       from being performed with that parameter.
  1856.  
  1857.    o  IDUP_S_NO_MATCH indicates that Service_Verification_Info and 
  1858.       the P-IDU to be verified do not match.
  1859.  
  1860.    o  IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 
  1861.       does not support the service requested.
  1862.  
  1863.    o  IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service 
  1864.       requested (TTIME or UTIME) is not available in the environment.
  1865.  
  1866.    o  IDUP_S_SERV_VERIF_INFO_NEEDED indicates that the 
  1867.       Service_Verification_Info parameter bundle must be input in order 
  1868.       for service verification to proceed.  The output parameter 
  1869.       service_verification_info_id contains an identifier which may be 
  1870.       used by the calling application to locate the necessary 
  1871.       information.
  1872.  
  1873.    o  GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 
  1874.       recognized, but that its associated credentials have expired, so 
  1875.       that the requested operation cannot be performed.
  1876.  
  1877.    o  IDUP_S_NO_ENV indicates that no valid environment was recognized 
  1878.       for the env_handle provided.
  1879.  
  1880.    o  IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value 
  1881.       is not recognized or supported in the underlying mechanism.
  1882.  
  1883.    o  GSS_S_BAD_QOP indicates that the qop_algs value specified in P-IDU 
  1884.       for at least one of the services is unavailable in the local 
  1885.       mechanism, so processing cannot continue.
  1886.  
  1887.    o  GSS_S_BAD_SIG indicates that the received P-IDU contains an
  1888.       incorrect integrity field (e.g., signature or MAC) for the data.
  1889.  
  1890.    o  IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU 
  1891.       data origin auth. / integ. has either expired or been revoked.
  1892.  
  1893.    o  IDUP_S_BAD_KE_KEY indicates that the key used to establish a key 
  1894.       for confidentiality purposes between originator and target has 
  1895.       either expired or been revoked.
  1896.  
  1897.    o  IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU 
  1898.       cannot be completed because the encrypted IDU was invalid/defec- 
  1899.       tive (e.g., the final block was short or had incorrect padding).
  1900.  
  1901.    o  GSS_S_FAILURE indicates that the environment is recognized, but 
  1902.       that the requested operation could not be performed for reasons 
  1903.       unspecified at the IDUP-GSS-API level.
  1904.  
  1905. Adams               Document Expiration:  26 May  1997                33
  1906.  
  1907.  
  1908.    Using the security environment referenced by env_handle, initialize 
  1909.    the data structures required to begin the process of unprotecting a 
  1910.    P-IDU.  The caller will be alerted as to which services were applied 
  1911.    to the P-IDU in the returned Services_to_Receive set of parameters.
  1912.  
  1913.    If unprotection will be applied more than once to a given P-IDU, it 
  1914.    is the responsibility of the calling application to remember if a 
  1915.    service solicitation has been responded to previously (i.e., if the 
  1916.    requested service has already been generated / sent for that P-IDU) 
  1917.    and thus ignore subsequent solicitations on unprotect. 
  1918.  
  1919.    The time flags indicate whether to consult trusted, untrusted, or no 
  1920.    time (if both flags are FALSE) during the unprotection operation.  If 
  1921.    the current time is not to be checked, then unprotection may be 
  1922.    successful even if the protector's key has expired since the P-IDU 
  1923.    was generated (that is, if the Validity period -- as specified in 
  1924.    the Quality parameter bundle -- has expired).
  1925.  
  1926.    If the underlying mechanism supports it and if this information is 
  1927.    contained in the token, information regarding the originator (that 
  1928.    is, the entity which used the protection set of calls to generate 
  1929.    this token) is returned in the Prot_Information parameter bundle.
  1930.  
  1931.  
  1932. 2.3.7. IDUP_Unprotect call
  1933.  
  1934.    Inputs:
  1935.  
  1936.    o  env_handle ENVIRONMENT HANDLE,
  1937.  
  1938.    o  input_buffer OCTET STRING
  1939.  
  1940.    Outputs:
  1941.  
  1942.    o  major_status INTEGER,
  1943.  
  1944.    o  minor_status INTEGER,
  1945.  
  1946.    o  output_buffer OCTET STRING
  1947.  
  1948.    Return major_status codes:
  1949.  
  1950.    o  GSS_S_COMPLETE indicates that the input_buffer has successfully 
  1951.       been included in the unprotection computation.
  1952.  
  1953.    o  IDUP_S_NO_ENV indicates that no valid environment was recognized 
  1954.       for the env_handle provided.
  1955.  
  1956.    o  GSS_S_FAILURE indicates that the environment is recognized, but 
  1957.       that the requested operation could not be performed for reasons 
  1958.       unspecified at the IDUP-GSS-API level.
  1959.  
  1960.    Using the security environment referenced by env_handle, continue the 
  1961.    unprotection processing on the data in input_buffer, putting any 
  1962.    resulting IDU data in output_buffer (if required).
  1963.  
  1964. Adams               Document Expiration:  26 May  1997                34
  1965.  
  1966.  
  1967. 2.3.8. IDUP_End_Unprotect call
  1968.  
  1969.    Inputs:
  1970.  
  1971.    o  env_handle ENVIRONMENT HANDLE,
  1972.  
  1973.    Outputs:
  1974.  
  1975.    o  major_status INTEGER,
  1976.  
  1977.    o  minor_status INTEGER,
  1978.  
  1979.    o  Prot_Information PARAMETER BUNDLE, 
  1980.  
  1981.    o  Services_to_Receive SET OF Unprot_Service, 
  1982.  
  1983.    o  final_idu_buffer OCTET STRING,
  1984.  
  1985.    o  Service_Verification_Info PARAMETER BUNDLE, 
  1986.       -- used only if target is on "service_to" list in Unprot_Service 
  1987.  
  1988.    o  service_verification_info_id INTEGER, 
  1989.       -- used only if target is on "service_to" list in Unprot_Service 
  1990.  
  1991.    Return major_status codes:
  1992.  
  1993.    o  GSS_S_COMPLETE indicates that the unprotect computation was 
  1994.       successful.  Any residual IDU data will be returned in 
  1995.       final_idu_buffer.
  1996.  
  1997.    o  IDUP_S_INCOMPLETE indicates that the unprotection of the P-IDU 
  1998.       is not yet complete (i.e., a determination cannot yet be made on 
  1999.       the validity of the P-IDU).  The application should call 
  2000.       IDUP_Form_Complete_PIDU and then should call this function again 
  2001.       with the complete P-IDU. 
  2002.  
  2003.    o  GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers 
  2004.       supplied is too small to hold the generated data.  The application 
  2005.       should continue calling this routine (until GSS_S_COMPLETE is 
  2006.       returned) in order to get all remaining data.
  2007.  
  2008.    o  GSS_S_BAD_SIG indicates that the received P-IDU contains an
  2009.       incorrect integrity field (e.g., signature or MAC) for the data.
  2010.  
  2011.    o  IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU 
  2012.       data origin auth. / integ. has either expired or been revoked.
  2013.  
  2014.    o  IDUP_S_BAD_KE_KEY indicates that the key used to establish a key 
  2015.       for confidentiality purposes between originator and target has 
  2016.       either expired or been revoked.
  2017.  
  2018.    o  IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU 
  2019.       cannot be completed because the encrypted IDU was invalid/defec- 
  2020.       tive (e.g., the final block was short or had incorrect padding).
  2021.  
  2022.  
  2023. Adams               Document Expiration:  26 May  1997                35
  2024.  
  2025.  
  2026.    o  IDUP_S_NO_ENV indicates that no valid environment was recognized 
  2027.       for the env_handle provided.
  2028.  
  2029.    o  GSS_S_FAILURE indicates that the environment is recognized, but 
  2030.       that the requested operation could not be performed for reasons 
  2031.       unspecified at the IDUP-GSS-API level.
  2032.  
  2033.    Using the security environment referenced by env_handle, complete the 
  2034.    unprotection processing on the data and return the appropriate status 
  2035.    code.  If there is any residual IDU data it will be returned in 
  2036.    final_idu_buffer.  
  2037.  
  2038.    If the IDUP_S_INCOMPLETE major status value is returned, all output 
  2039.    parameters are conditionally valid; the unprotection set of functions 
  2040.    will have to be called again (perhaps with a complete P-IDU, as 
  2041.    produced by IDUP_Form_Complete_PIDU) in order to get valid values for 
  2042.    all parameters.  "Conditional validity" may arise, for example, if 
  2043.    all relevant certificates verify correctly, but it is not yet past 
  2044.    the time up to which the current policy allows the authorities 
  2045.    involved to repudiate their keys. 
  2046.  
  2047.    If the underlying mechanism supports it and if this information is 
  2048.    contained in the token, information regarding the originator (that 
  2049.    is, the entity which used the protection set of calls to generate 
  2050.    this token) is returned in the Prot_Information parameter bundle.  
  2051.    This information may or may not be omitted if it was returned by the 
  2052.    IDUP_Start_Unprotect() call.
  2053.  
  2054.    Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the 
  2055.    concept of error tokens transferred between sender and recipient 
  2056.    since the protection and unprotection of an IDU may be separated by 
  2057.    an indefinite amount of time and may or may not be performed by the 
  2058.    same entity.
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070. Adams               Document Expiration:  26 May  1997                36
  2071.  
  2072.  
  2073. 2.4. Special-Purpose Calls
  2074.  
  2075. 2.4.1.  Relationship to GSS-API
  2076.  
  2077.    The special-purpose call described in this section has no analog 
  2078.    in GSS-API [RFC-1508].  This call is used to complete a P-IDU (that 
  2079.    is, to generate a P-IDU which can be unprotected successfully with 
  2080.    no additional data at any time during its validity period).  This 
  2081.    call may not be supported by all underlying IDUP mechanisms or 
  2082.    implementations. 
  2083.  
  2084. 2.4.2. IDUP_Form_Complete_PIDU call
  2085.  
  2086.    Inputs:
  2087.  
  2088.    o  env_handle ENVIRONMENT HANDLE,
  2089.  
  2090.    o  single_pidu_buffer OCTET STRING, 
  2091.  
  2092.    o  partial_pidu_buffer OCTET STRING, 
  2093.       -- an arbitrary-sized piece of the full pidu token.  Used if pidu 
  2094.       -- will be input a buffer at a time (except that the final buffer 
  2095.       -- must be passed in final_pidu_buffer rather than 
  2096.       -- partial_pidu_buffer).  Only one of single_pidu_buffer and 
  2097.       -- partial(final)_pidu_buffer can have nonzero length.
  2098.  
  2099.    o  final_pidu_buffer OCTET STRING, 
  2100.  
  2101.    Outputs:
  2102.  
  2103.    o  major_status INTEGER,
  2104.  
  2105.    o  minor_status INTEGER,
  2106.  
  2107.    o  pidu_token_out OCTET STRING 
  2108.  
  2109.    o  call_again_before INTEGER,
  2110.  
  2111.    o  call_again_after INTEGER,
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.  
  2120.  
  2121.  
  2122.  
  2123.  
  2124.  
  2125.  
  2126.  
  2127.  
  2128.  
  2129. Adams               Document Expiration:  26 May  1997                37
  2130.  
  2131.  
  2132.    Return major_status codes:
  2133.  
  2134.    o  GSS_S_COMPLETE indicates that the completion of P-IDU generation 
  2135.       was successful.
  2136.  
  2137.    o  GSS_S_CONTINUE_NEEDED indicates that the buffer supplied for 
  2138.       pidu_token_out is too small to hold the generated data.  The 
  2139.       application should continue calling this routine (until 
  2140.       GSS_S_COMPLETE is returned) in order to get all remaining data.
  2141.  
  2142.    o  IDUP_S_INCOMPLETE indicates that the generation of the P-IDU 
  2143.       is not yet complete.  The application should call this function 
  2144.       again before the time given in call_again_before (if not NULL), 
  2145.       or after the time given in call_again_after (if not NULL), or 
  2146.       both (if neither are NULL).
  2147.  
  2148.    o  IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism 
  2149.       does not support the service requested.
  2150.  
  2151.    o  GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 
  2152.       on the input P-IDU token failed, preventing further processing 
  2153.       from being performed with that token.
  2154.  
  2155.    o  GSS_S_FAILURE indicates that the environment is recognized, but 
  2156.       that the requested operation could not be performed for reasons 
  2157.       unspecified at the IDUP-GSS-API level.
  2158.  
  2159.    Using the security environment referenced by env_handle, complete the 
  2160.    generation of a P-IDU token and return the appropriate status value 
  2161.    along with the completed token (if available).  Such a call may be 
  2162.    used, for example, for the purpose of batch evidence generation on an 
  2163.    "evidence server".  A local machine may be able to use the protection 
  2164.    set of calls to fill out most of an evidence token and then send a 
  2165.    number of these to a batch processor which forms the complete 
  2166.    evidence tokens (perhaps by adding a certification path, or a 
  2167.    timestamp and signature from a timestamping authority).  As another 
  2168.    example, on the receiving end an application may make such a call in 
  2169.    order to collect all the information necessary to unprotect a P-IDU 
  2170.    (such as all relevant certificates and Certificate Revocation Lists); 
  2171.    this will ensure that the calls to the unprotection set of operations 
  2172.    will be entirely local (i.e., can be performed off-line) and fast.  
  2173.  
  2174.    Note that the complete P-IDU generated will be formed using trusted 
  2175.    time if this is available in the environment referenced by env_handle 
  2176.    and will use untrusted time or no time otherwise (depending on what 
  2177.    is available).
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.  
  2184.  
  2185.  
  2186.  
  2187.  
  2188. Adams               Document Expiration:  26 May  1997                38
  2189.  
  2190.  
  2191. 2.5.  Support calls
  2192.  
  2193.  
  2194. 2.5.1.  Relationship to GSS-API
  2195.  
  2196.    Support calls in IDUP-GSS-API are to be understood and used as 
  2197.    described in GSS-API [RFC-1508].  The calls GSS_Display_status(),
  2198.    GSS_Indicate_mechs(), GSS_Compare_name(), GSS_Display_name(), 
  2199.    GSS_Import_name(), GSS_Release_name(), GSS_Release_buffer(), and 
  2200.    GSS_Release_oid_set() are unchanged.
  2201.  
  2202.  
  2203. 2.5.2. IDUP_Parse_token call
  2204.  
  2205.    Inputs:
  2206.  
  2207.    o  input_token OCTET STRING
  2208.  
  2209.    Outputs:
  2210.  
  2211.    o  major_status INTEGER,
  2212.  
  2213.    o  minor_status INTEGER,
  2214.  
  2215.    o  mech_type OBJECT IDENTIFIER,
  2216.  
  2217.  
  2218.    Return major_status codes:
  2219.  
  2220.    o  GSS_S_COMPLETE indicates that the input_token could be parsed for 
  2221.       all relevant fields.
  2222.  
  2223.    o  GSS_S_CREDENTIALS_EXPIRED indicates that the environment is 
  2224.       recognized, but that its associated credentials have expired, so 
  2225.       that the requested operation cannot be performed.
  2226.  
  2227.    o  GSS_S_DEFECTIVE_TOKEN indicates that the mechanism type could be 
  2228.       parsed, but that either the other fields could not be determined 
  2229.       from the input_token, or their values did not correspond to valid 
  2230.       values for that mechanism.
  2231.  
  2232.    o  GSS_S_FAILURE indicates that the mechanism type could not be 
  2233.       parsed (for example, the token may be corrupted).
  2234.  
  2235.    IDUP_Parse_Token() is used to return to an application the attributes 
  2236.    which correspond to a given input token.  Since IDUP-GSS-API tokens 
  2237.    are meant to be opaque to the calling application, this function 
  2238.    allows the application to determine information about the token 
  2239.    without having to violate the opaqueness intention of IDUP.  Of 
  2240.    primary importance is the mechanism type, which the application can 
  2241.    then use as input to the IDUP_Establish_Env() call in order to 
  2242.    establish the correct environment in which to have the token 
  2243.    processed.  Other token attributes may be added as outputs of this 
  2244.    call in future versions of this specification, if required.
  2245.  
  2246.  
  2247. Adams               Document Expiration:  26 May  1997                39
  2248.  
  2249.  
  2250.    If all tokens are framed as suggested in RFC-1508, Appendix B 
  2251.    (mandated in the Kerberos V5 GSS mechanism [RFC 1964] and in the SPKM 
  2252.    GSS Mechanism [RFC 2025], then any mechanism implementation should be 
  2253.    able to return the mech_type parameter for any uncorrupted input 
  2254.    token.  If the mechanism implementation whose IDUP_Parse_token() 
  2255.    function is being called does recognize the token, it can return 
  2256.    other token attributes, if specified.
  2257.  
  2258.  
  2259. 2.5.3. IDUP_Get_policy_info call
  2260.  
  2261.    Inputs:
  2262.  
  2263.    o  policy_id OBJECT IDENTIFIER
  2264.  
  2265.    Outputs:
  2266.  
  2267.    o  major_status INTEGER,
  2268.  
  2269.    o  minor_status INTEGER,
  2270.  
  2271.    o  policy_version INTEGER,
  2272.  
  2273.    o  policy_effective_time INTEGER,
  2274.  
  2275.    o  policy_expiry_time INTEGER,
  2276.  
  2277.    o  supported_services SET OF Service_Descriptor,
  2278.  
  2279.    o  supported_mechanisms SET OF Mechanism_Descriptor
  2280.  
  2281.  
  2282.    Return major_status codes:
  2283.  
  2284.    o  GSS_S_COMPLETE indicates that the policy_id was recognized and 
  2285.       all relevant fields have been returned.
  2286.  
  2287.    o  GSS_S_FAILURE indicates that the policy_id was not recognized.
  2288.  
  2289.  
  2290.    This call (which need not be supported by all underlying mechanisms 
  2291.    or implementations) allows the application to retrieve information 
  2292.    pertaining to a given policy_id.  Policies define the following:  
  2293.  
  2294.       -  rules for the protection of IDUs, such as trusted third 
  2295.          parties which may be involved in P-IDU generation, the roles 
  2296.          in which they may be involved, and the duration for which the 
  2297.          generated P-IDU is valid;
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306. Adams               Document Expiration:  26 May  1997                40
  2307.  
  2308.  
  2309.       -  rules for the unprotection of P-IDUs, such as the interval 
  2310.          during which a trusted third party may legitimately declare its 
  2311.          key to have been compromised or revoked; and 
  2312.  
  2313.       -  rules for adjudication, such as which authorities may be used 
  2314.          to adjudicate disputes.
  2315.  
  2316.    The policy itself may be used by an adjudicator when resolving a 
  2317.    dispute.  For example, the adjudicator might refer to the policy to 
  2318.    determine whether the rules for generation of the P-IDU have been 
  2319.    followed.
  2320.  
  2321.    The following parameter bundles are associated with this call.  
  2322.  
  2323.       o  Service_Descriptor PARAMETER BUNDLE, 
  2324.  
  2325.          o  service_type OBJECT IDENTIFIER, 
  2326.  
  2327.          o  service_validity_duration INTEGER, 
  2328.  
  2329.          o  must_use_trusted_time BOOLEAN 
  2330.  
  2331.       o  Mechanism_Descriptor PARAMETER BUNDLE, 
  2332.  
  2333.          o  mechanism_type OBJECT IDENTIFIER, 
  2334.  
  2335.          o  Authority_List PARAMETER BUNDLE, 
  2336.  
  2337.          o  maximum_time_skew INTEGER 
  2338.               -- maximum permissible difference between P-IDU generation 
  2339.               -- time and the time of countersignature from a time 
  2340.               -- service (if required).  This parameter is unused if 
  2341.               -- trusted time is not required.
  2342.  
  2343.       o  Authority_List PARAMETER BUNDLE, 
  2344.  
  2345.          o  authority_name INTERNAL NAME, 
  2346.  
  2347.          o  authority_role OCTET STRING, 
  2348.  
  2349.          o  last_revocation_check_offset INTEGER 
  2350.               -- may be greater than 0 or less than 0.  The value of  
  2351.               -- this parameter is added to P-IDU generation time to 
  2352.               -- get latest time at which the mechanism will check to 
  2353.               -- see if this authority's key has been revoked.
  2354.  
  2355.    An example of the use of the last parameter in Authority_List is as 
  2356.    follows.  If an authority has a defined last_revocation_check_offset 
  2357.    of negative one hour, then all revocations taking effect earlier than 
  2358.    one hour before the generation of a P-IDU will render that P-IDU 
  2359.    invalid; no revocation taking place later than one hour before the 
  2360.    generation of the P-IDU will affect the P-IDU's validity.  
  2361.  
  2362.    Note that both the maximum_time_skew and the 
  2363.    last_revocation_check_offset values are given in minutes.
  2364.  
  2365. Adams               Document Expiration:  26 May  1997                41
  2366.  
  2367.  
  2368. 3.  Related Activities
  2369.  
  2370.    In order to implement the IDUP-GSS-API atop existing, emerging, and 
  2371.    future security mechanisms, the following is necessary:
  2372.  
  2373.     - object identifiers must be assigned to candidate IDUP-GSS-API
  2374.       mechanisms and the name types which they support; and 
  2375.  
  2376.     - concrete data element (i.e., token and parameter bundle) formats 
  2377.       must be defined for candidate mechanisms.
  2378.  
  2379.    Calling applications must implement formatting conventions which will
  2380.    enable them to distinguish IDUP-GSS-API P-IDUs from other 
  2381.    IDUs in their environment.
  2382.  
  2383.    Concrete language bindings are required for the programming
  2384.    environments in which the IDUP-GSS-API is to be employed; such a 
  2385.    binding for the C language are available in the Internet Draft 
  2386.    [IDUP-C].
  2387.  
  2388.  
  2389.  
  2390. 4.  Acknowledgments
  2391.  
  2392.    Many thanks are due to Tim Moses and Dhanya Thakkar of Nortel, 
  2393.    Denis Pinkas of Bull, and David Kurn of Tandem Computers for a number 
  2394.    of helpful comments.
  2395.  
  2396.  
  2397.  
  2398. 5. Security Considerations
  2399.  
  2400.    Security issues are discussed throughout this memo.
  2401.  
  2402.  
  2403.  
  2404.  
  2405.  
  2406.  
  2407.  
  2408.  
  2409.  
  2410.  
  2411.  
  2412.  
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424. Adams               Document Expiration:  26 May  1997                42
  2425.  
  2426.  
  2427.  
  2428. 6. REFERENCES
  2429.  
  2430.    [MSP]:       U.S. National Security Agency, "Message Security 
  2431.    Protocol", Secure Data Network System SDN.701, March 1994.
  2432.  
  2433.    [RFC-1421]:  J. Linn, "Privacy Enhancement for Internet Electronic 
  2434.    Mail:  Part I: Message Encryption and Authentication Procedures", 
  2435.    RFC 1421.
  2436.  
  2437.    [RFC-1508]:  J. Linn, "Generic Security Service Application Program 
  2438.    Interface", RFC 1508.
  2439.  
  2440.    [GSSv2]:     J. Linn, "Generic Security Service Application Program 
  2441.    Interface, Version 2", Internet Draft draft-ietf-cat-gssv2-0x.txt 
  2442.    (work in progress).
  2443.  
  2444.    [RFC 1964]:  J. Linn, "The Kerberos Version 5 GSS-API Mechanism",  
  2445.    RFC 1964.
  2446.  
  2447.    [RFC 2025]:  C. Adams, "The Simple Public-Key GSS-API Mechanism 
  2448.    (SPKM)", RFC 2025.
  2449.  
  2450.    [IDUP-C]:    D. Thakkar, D. Grebovich, "Independent Data Unit 
  2451.    Protection Generic Security Service Application Program Interface: C-
  2452.    bindings", Internet Draft draft-ietf-cat-idup-cbind-0x.txt (work in 
  2453.    progress).
  2454.  
  2455.    [ISO/IEC]:   2nd ISO/IEC CD 13888-1, "Information technology - 
  2456.    Security techniques - Non-repudiation - Part 1:  General Model", 
  2457.    ISO/IEC JTC 1/SC 27, May 30, 1995
  2458.  
  2459.  
  2460.  
  2461.  
  2462.  
  2463.  
  2464.  
  2465.  
  2466.  
  2467.  
  2468. 7. Author's Address
  2469.  
  2470.    Carlisle Adams
  2471.    Nortel Secure Networks
  2472.    P.O.Box 3511, Station C
  2473.    Ottawa, Ontario, CANADA  K1Y 4H7
  2474.  
  2475.    Phone: +1 613.763.9008
  2476.    E-mail: cadams@entrust.com
  2477.  
  2478.  
  2479.  
  2480.  
  2481.  
  2482.  
  2483. Adams               Document Expiration:  26 May  1997                43
  2484.  
  2485.  
  2486. APPENDIX  A
  2487.  
  2488. MECHANISM-INDEPENDENT TOKEN FORMAT
  2489.  
  2490.    This appendix specifies a mechanism-independent level of 
  2491.    encapsulating representation for IDUP-GSS-API tokens, incorporating 
  2492.    an identifier of the mechanism type to be used when processing those 
  2493.    tokens.  Use of this format (with ASN.1-encoded data elements 
  2494.    represented in BER, constrained in the interests of parsing 
  2495.    simplicity to the Distinguished Encoding Rule (DER) BER subset 
  2496.    defined in X.509, clause 8.7) is recommended to the designers of 
  2497.    IDUP-GSS-API implementations based on various mechanisms, so that 
  2498.    tokens can be interpreted unambiguously at IDUP-GSS-API peers. There
  2499.    is no requirement that the mechanism-specific token data element be 
  2500.    encoded in ASN.1 BER.
  2501.  
  2502.  
  2503.           -- top-level token definition to frame different mechanisms
  2504.  
  2505.           IDUP-GSS-API DEFINITIONS ::=
  2506.           BEGIN
  2507.           MechType ::= OBJECT IDENTIFIER
  2508.  
  2509.           Token ::= [APPLICATION 0] IMPLICIT SEQUENCE {
  2510.                   thisMech MechType,
  2511.                   token ANY DEFINED BY thisMech
  2512.                      -- contents mechanism-specific
  2513.                   }
  2514.           END
  2515.  
  2516.  
  2517.  
  2518.  
  2519.  
  2520.  
  2521.  
  2522.  
  2523.  
  2524.  
  2525.  
  2526.  
  2527.  
  2528.  
  2529.  
  2530.  
  2531.  
  2532.  
  2533.  
  2534.  
  2535.  
  2536.  
  2537.  
  2538.  
  2539.  
  2540.  
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549. Adams               Document Expiration:  26 May  1997                44
  2550.  
  2551.  
  2552. APPENDIX  B
  2553.  
  2554. EXAMPLES OF IDUP USE
  2555.  
  2556.    This appendix provides examples of the use of IDUP to do IDU protec-
  2557.    tion and unprotection.  It should not be regarded as constrictive to 
  2558.    implementations or as defining the only means through which 
  2559.    IDUP-GSS-API functions can be realized with particular underlying 
  2560.    technology, and does not demonstrate all IDUP-GSS-API features.
  2561.  
  2562.  
  2563. B.1.  Simple Mechanism, Single Buffer
  2564.  
  2565.    To illustrate the simplest possible case, consider an underlying IDUP 
  2566.    mechanism which does straightforward encryption/decryption and 
  2567.    signing/verification only; none of the other possible services, such 
  2568.    as creation of proof-of-origin evidence, requests for proof-of-
  2569.    delivery evidence, or use of trusted time, are supported.  PEM 
  2570.    [RFC-1421] is one example of a mechanism which fits this description.  
  2571.    Furthermore (again for simplicity), assume that encapsulation is 
  2572.    chosen by the calling application during IDU protection.
  2573.  
  2574.    The following parameter bundle uses and defaults would therefore be 
  2575.    specified in the relevant IDUP mechanism document.
  2576.  
  2577.  
  2578.    Mech_Specific_Info
  2579.       - NOT USED (the only acceptable input, therefore, is NULL)
  2580.  
  2581.    Idu_Sensitivity
  2582.       - NOT USED (the only acceptable input, therefore, is NULL)
  2583.  
  2584.    Service_Creation_Info
  2585.       - NOT USED (the only acceptable input, therefore, is NULL)
  2586.  
  2587.    Service_Verification_Info
  2588.       - NOT USED (the only acceptable input, therefore, is NULL)
  2589.  
  2590.    Quality
  2591.       - the qop_algs parameter must be supported, with a suitable 
  2592.         DEFAULT value specified;
  2593.       - suitable DEFAULT values for validity, policy_id, and 
  2594.         allow_policy_mapping must be specified (it may be an 
  2595.         implementation option as to whether these parameters are 
  2596.         explicitly modifiable by the calling application, or whether 
  2597.         NULLs are the only acceptable input)
  2598.  
  2599.    Idu_Information
  2600.       - the idu_type parameter must have a value representing a suitable 
  2601.         IDU type (for example, in PEM a value representing the string 
  2602.         "RFC822" or some other valid "Content-Domain" would be used), 
  2603.         with a suitable DEFAULT value specified;
  2604.       - the idu_title parameter is NOT USED (the only acceptable input, 
  2605.         therefore, is NULL)
  2606.  
  2607.  
  2608. Adams               Document Expiration:  26 May  1997                45
  2609.  
  2610.  
  2611.    Prot_Information
  2612.       - the originator_name and idu_type (in Idu_Information) parameters 
  2613.         are read from the encapsulating information and output by 
  2614.         IDUP_Start_Unprotect;
  2615.       - all other parameters are NOT USED (and therefore NULL)
  2616.  
  2617.    Special_Conditions
  2618.       - NOT USED (the only acceptable input, therefore, is NULL)
  2619.  
  2620.    Target_Info
  2621.       - this bundle is used as described in IDUP; no DEFAULT values are 
  2622.         specified
  2623.  
  2624.    General_Service_Data
  2625.       - the unencapsulated_token parameter is used if 
  2626.         encapsulation_request is FALSE;
  2627.       - the minor_status parameter is used to return minor status values
  2628.         as specified by the mechanism document
  2629.  
  2630.    Prot_Service
  2631.       - the prot_service_type parameter may have a value of "1" 
  2632.         ("perform unsolicited service") or NULL (which specifies the 
  2633.         DEFAULT value of "1");
  2634.       - the service_id parameter must have a value representing 
  2635.         "PER_CONF" or "PER_DOA";
  2636.       - the parameters Service_Creation_Info, service_to, 
  2637.         Service_Verification_Info, and service_verification_info_id are
  2638.         NOT USED (and therefore NULL)
  2639.  
  2640.    Unprot_Service
  2641.       - the unprot_service_type parameter will always have a value of 
  2642.         "1" ("receive unsolicited service");
  2643.       - the service_id parameter will have a value representing 
  2644.         "REC_CONF" or "REC_DOA";
  2645.       - the parameters service_verification_info_id, 
  2646.         Service_Verification_Info, service_to, and 
  2647.         Service_Creation_Info, are NOT USED (and therefore NULL)
  2648.  
  2649.  
  2650.  
  2651.    Assuming that the calling application has only a single buffer of 
  2652.    data to protect/unprotect, the following sequence of operations must 
  2653.    be performed by the sender and receivers (subsequent to environment 
  2654.    establishment).
  2655.  
  2656.  
  2657.    SENDER (any parameters not listed below are given the value NULL):
  2658.  
  2659.    Set
  2660.       env_handle                           = environment handle in use;
  2661.       encapsulation_request                = TRUE;
  2662.       single_idu_buffer                    = data buffer;
  2663.       Target_Info.targ_names               = receiver names;
  2664.       P_Services.Prot_Service_1.service_id = PER_CONF;
  2665.       P_Services.Prot_Service_2.service_id = PER_DOA;
  2666.  
  2667. Adams               Document Expiration:  26 May  1997                46
  2668.  
  2669.  
  2670.    Call
  2671.       IDUP_Start_Protect() with above input parameters
  2672.    Check
  2673.       major_status.  If not GSS_S_COMPLETE, check 
  2674.          minor_status, 
  2675.          Target_Info.bad_targ_names / Target_Info.bad_targ_status, 
  2676.          P_Services.Prot_Service_1.General_Service_Data.minor_status,
  2677.          P_Services.Prot_Service_2.General_Service_Data.minor_status
  2678.       (as required) for more detailed information.
  2679.  
  2680.    Send
  2681.       Output parameter pidu_buffer to receiver.
  2682.  
  2683.  
  2684.    RECEIVER (any parameters not listed below are given the value NULL):
  2685.  
  2686.    Set
  2687.       env_handle         = environment handle in use;
  2688.       single_pidu_buffer = received data buffer;
  2689.  
  2690.    Call
  2691.       IDUP_Start_Unprotect() with above input parameters
  2692.    Check
  2693.       major_status.  If not GSS_S_COMPLETE, check 
  2694.          minor_status, 
  2695.          R_Services.Unprot_Service_1.General_Service_Data.minor_status,
  2696.          R_Services.Unprot_Service_2.General_Service_Data.minor_status
  2697.       (as required) for more detailed information
  2698.  
  2699.    Utilize
  2700.       R_Services.Unprot_Service_1/2.service_id, 
  2701.          (to determine which services were applied by the originator)
  2702.       R_Services.Unprot_Service_1/2.Quality, 
  2703.          (to determine the corresponding qualities of the services)
  2704.       Prot_Information.originator_name,
  2705.          (to determine the name of the originator)
  2706.       single_idu_buffer
  2707.          (to retrieve the unprotected data).
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.  
  2714.  
  2715.  
  2716.  
  2717.  
  2718.  
  2719.  
  2720.  
  2721.  
  2722.  
  2723.  
  2724.  
  2725.  
  2726. Adams               Document Expiration:  26 May  1997                47
  2727.  
  2728.  
  2729. B.2.  Simple Mechanism, Multiple Buffers
  2730.  
  2731.    To illustrate the next step up in complexity, consider the use of the 
  2732.    simple IDUP mechanism described above with multiple data buffers.  In 
  2733.    particular, consider the case in which a large data file is to be 
  2734.    signed.  For this example, assume that the calling application does 
  2735.    not wish to use encapsulation.
  2736.  
  2737.    Note that the parameter bundle uses and defaults are as specified in 
  2738.    C.1. above.
  2739.  
  2740.  
  2741.    SENDER (any parameters not listed below are given the value NULL):
  2742.  
  2743.    Set
  2744.       env_handle                           = environment handle in use;
  2745.       encapsulation_request                = FALSE;
  2746.       P_Services.Prot_Service.service_id   = PER_DOA;
  2747.  
  2748.    Call
  2749.       IDUP_Start_Protect() with above input parameters
  2750.    Check
  2751.       major_status.  If not GSS_S_COMPLETE, check 
  2752.          minor_status, 
  2753.          P_Services.Prot_Service.General_Service_Data.minor_status
  2754.       (as required) for more detailed information.
  2755.  
  2756.    For each buffer of input data:
  2757.       Set
  2758.          input_buffer = buffer
  2759.       Call
  2760.          IDUP_Protect() with above input parameter
  2761.       Check
  2762.          major_status.  If not GSS_S_COMPLETE, check 
  2763.             minor_status
  2764.  
  2765.    Call
  2766.       IDUP_End_Protect()
  2767.    Check
  2768.       major_status.  If not GSS_S_COMPLETE, check 
  2769.          minor_status, 
  2770.          P_Services.Prot_Service.General_Service_Data.minor_status
  2771.       (as required) for more detailed information.
  2772.  
  2773.    Send
  2774.       P_Services.Prot_Service.General_Service_Data.unencapsulated_token,
  2775.          the file for which the signature was calculated (if required)
  2776.       to receiver.
  2777.  
  2778.  
  2779.  
  2780.  
  2781.  
  2782.  
  2783.  
  2784.  
  2785. Adams               Document Expiration:  26 May  1997                48
  2786.  
  2787.  
  2788.    RECEIVER (any parameters not listed below are given the value NULL):
  2789.  
  2790.    Set
  2791.       env_handle          = environment handle in use;
  2792.       partial_pidu_buffer = received unencapsulated token;
  2793.  
  2794.    Call
  2795.       IDUP_Start_Unprotect() with above input parameters
  2796.    Check
  2797.       major_status.  If not GSS_S_COMPLETE, check 
  2798.          minor_status, 
  2799.          R_Services.Unprot_Service_1.General_Service_Data.minor_status,
  2800.       (as required) for more detailed information
  2801.  
  2802.    For each buffer of input data:
  2803.       Set
  2804.          input_buffer = buffer
  2805.       Call
  2806.          IDUP_Unprotect() with above input parameter
  2807.       Check
  2808.          major_status.  If not GSS_S_COMPLETE, check 
  2809.             minor_status
  2810.  
  2811.    Call
  2812.       IDUP_End_Unprotect()
  2813.    Check
  2814.       major_status.  If not GSS_S_COMPLETE, check 
  2815.          minor_status, 
  2816.          R_Services.Unprot_Service_1.General_Service_Data.minor_status,
  2817.       (as required) for more detailed information.
  2818.  
  2819.    Utilize
  2820.       R_Services.Unprot_Service_1.service_id, 
  2821.          (to determine which service was applied by the originator; note
  2822.           that Unprot_Service_2 will have NULL in unprot_service_type
  2823.           to indicate that it is not used)
  2824.       R_Services.Unprot_Service_1.Quality, 
  2825.          (to determine the corresponding quality of the service)
  2826.       Prot_Information.originator_name, (from IDUP_Start_Unprotect)
  2827.          (to determine the name of the signer)
  2828.       major_status (from IDUP_End_Unprotect)
  2829.          (to determine pass/fail status of signature verification).
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844. Adams               Document Expiration:  26 May  1997                49
  2845.  
  2846.  
  2847. B.3.  More Sophisticated Mechanism, Small Application Buffers
  2848.  
  2849.    To illustrate a higher level of complexity, consider the use of a 
  2850.    more sophisticated IDUP mechanism and a calling application with 
  2851.    small data buffers.  In particular, consider the case in which a very 
  2852.    small e-mail message is to be encrypted for a relatively large 
  2853.    receiver list (R), some subset of whom (r) will be asked to send 
  2854.    proofs of receipt of the message to some other subset (L) (which 
  2855.    includes the originator).  So that the example is not unnecessarily 
  2856.    complicated, assume again that the originating application uses 
  2857.    encapsulation.
  2858.  
  2859.    The uses and defaults for the various parameter bundles for this 
  2860.    mechanism would be specified in the relevant IDUP mechanism document 
  2861.    as follows.
  2862.  
  2863.    Mech_Specific_Info
  2864.       - NOT USED (the only acceptable input, therefore, is NULL)
  2865.  
  2866.    Idu_Sensitivity
  2867.       - NOT USED (the only acceptable input, therefore, is NULL)
  2868.  
  2869.    Service_Creation_Info
  2870.       - used to create "proof of delivery" evidence (but actual 
  2871.         structure is opaque to calling application)
  2872.  
  2873.    Service_Verification_Info
  2874.       - used to verify "proof of delivery" evidence (but actual 
  2875.         structure is opaque to calling application)
  2876.  
  2877.    Quality
  2878.       - the qop_algs parameter must be supported, with a suitable 
  2879.         DEFAULT value specified;
  2880.       - suitable DEFAULT values for validity, policy_id, and 
  2881.         allow_policy_mapping must be specified (it may be an 
  2882.         implementation option as to whether these parameters are 
  2883.         explicitly modifiable by the calling application, or whether 
  2884.         NULLs are the only acceptable input)
  2885.  
  2886.    Idu_Information
  2887.       - the idu_type parameter must have a value representing a suitable 
  2888.         IDU type, with a suitable DEFAULT value specified;
  2889.       - the idu_title parameter must have a value representing a 
  2890.         suitable IDU title, with a suitable DEFAULT value specified
  2891.  
  2892.    Prot_Information
  2893.       - the originator_name, protection_time, and idu_type / idu_title 
  2894.         (in Idu_Information) parameters are read from the contained 
  2895.         header information and output by IDUP_Start_Unprotect;
  2896.  
  2897.    Special_Conditions
  2898.       - the parameter prot_oper_id is NOT USED (the only acceptable 
  2899.         input, therefore, is NULL);
  2900.       - trusted or untrusted time may be selected by the calling 
  2901.         application, with a suitable DEFAULT value specified
  2902.  
  2903. Adams               Document Expiration:  26 May  1997                50
  2904.  
  2905.  
  2906.    Target_Info
  2907.       - this bundle is used as described in IDUP; no DEFAULT values are 
  2908.         specified
  2909.  
  2910.    General_Service_Data
  2911.       - the unencapsulated_token parameter is used if 
  2912.         encapsulation_request is FALSE;
  2913.       - the minor_status parameter is used to return minor status values
  2914.         as specified by the mechanism document
  2915.  
  2916.    Prot_Service
  2917.       - the prot_service_type parameter may have a value of "1" 
  2918.         ("perform unsolicited service"), "2" ("perform solicited 
  2919.         service"), "3" (perform service solicitation), or NULL (which 
  2920.         specifies the DEFAULT value of "1");
  2921.       - the service_id parameter must have a value representing 
  2922.         "PER_CONF", "PER_DOA", "PER_POO", or "PER_POD";
  2923.       - the parameters Service_Creation_Info, service_to, 
  2924.         Service_Verification_Info, and service_verification_info_id are
  2925.         used when required by the IDUP operation
  2926.  
  2927.    Unprot_Service
  2928.       - the unprot_service_type parameter may have a value of "1" 
  2929.         ("receive unsolicited service"), "2" ("receive solicited 
  2930.         service"), or "3" (receive service solicitation);
  2931.       - the service_id parameter will have a value representing 
  2932.         "REC_CONF", "REC_DOA", "REC_POO", or "REC_POD";
  2933.       - the parameters service_verification_info_id, 
  2934.         Service_Verification_Info, service_to, and 
  2935.         Service_Creation_Info, are used when required by the IDUP 
  2936.         operation
  2937.  
  2938.  
  2939.    SENDER (any parameters not listed below are given the value NULL):
  2940.  
  2941.    Set
  2942.       env_handle                          = environment handle in use;
  2943.       Idu_Information.idu_type            = value for "e-mail document";
  2944.       Idu_Information.idu_title           = "Contract 1234";
  2945.       Special_Conditions.use_trusted_time = TRUE;
  2946.       encapsulation_request               = TRUE;
  2947.       single_idu_buffer                   = very small e-mail message;
  2948.       Target_Info.targ_names              = receiver names (R);
  2949.       Prot_Service_1.prot_service_type    = "1";
  2950.       Prot_Service_1.service_id           = PER_CONF;
  2951.       Prot_Service_2.prot_service_type    = "3";
  2952.       Prot_Service_2.service_id           = PER_POD;
  2953.       Prot_Service_2.General_Service_Data.Target_Info.targ_names
  2954.                                           = "receipts from" list (r);
  2955.       Prot_Service_2.service_to           = "receipts to" list (L);
  2956.       P_Services.Prot_Service_1           = Prot_Service_1;
  2957.       P_Services.Prot_Service_2           = Prot_Service_2;
  2958.  
  2959.  
  2960.  
  2961.  
  2962. Adams               Document Expiration:  26 May  1997                51
  2963.  
  2964.  
  2965.    Call
  2966.       IDUP_Start_Protect() with above input parameters
  2967.    Check
  2968.       major_status.  If not GSS_S_COMPLETE, 
  2969.          while major_status == GSS_S_CONTINUE_NEEDED
  2970.             Save 
  2971.                pidu_buffer,
  2972.             Call 
  2973.                IDUP_Start_Protect() (to get next portion of pidu_buffer)
  2974.          Check
  2975.             major_status,
  2976.             minor_status, 
  2977.             Target_Info.bad_targ_names / Target_Info.bad_targ_status, 
  2978.             P_Services.Prot_Service_1.General_Service_Data.minor_status,
  2979.             P_Services.Prot_Service_2.General_Service_Data.minor_status
  2980.          (as required) for more detailed information.
  2981.  
  2982.    Save
  2983.       Prot_Service_2.Service_Verification_Info,
  2984.       Prot_Service_2.service_verification_info_id
  2985.  
  2986.    Send
  2987.       All saved buffers of pidu_buffer to receiver list (R).
  2988.  
  2989.  
  2990.    RECEIVER (ON RECEIVER LIST (R)):
  2991.       (any parameters not listed below are given the value NULL)
  2992.  
  2993.    Set
  2994.       env_handle          = environment handle in use;
  2995.       partial_pidu_buffer = initial buffer of received p-idu;
  2996.  
  2997.    Call
  2998.       IDUP_Start_Unprotect() with above input parameters
  2999.    While major_status == IDUP_S_MORE_PIDU_NEEDED, 
  3000.       Set
  3001.          partial_pidu_buffer = next buffer of p-idu
  3002.       Call
  3003.          IDUP_Start_Unprotect()
  3004.    Check
  3005.       major_status,
  3006.       minor_status, 
  3007.       R_Services.Unprot_Service_1.General_Service_Data.minor_status,
  3008.       R_Services.Unprot_Service_2.General_Service_Data.minor_status,
  3009.    (as required) for more detailed information
  3010.  
  3011.    Save
  3012.       initial_idu_buffer (if non-empty)
  3013.  
  3014.  
  3015.  
  3016.  
  3017.  
  3018.  
  3019.  
  3020.  
  3021. Adams               Document Expiration:  26 May  1997                52
  3022.  
  3023.  
  3024.    Set
  3025.       input_buffer = remaining p-idu buffer
  3026.    Call
  3027.       IDUP_Unprotect() with above input parameter
  3028.    Check
  3029.       major_status.  If not GSS_S_COMPLETE, check 
  3030.          minor_status
  3031.    Save
  3032.       output_buffer
  3033.  
  3034.    Call
  3035.       IDUP_End_Unprotect()
  3036.    Check
  3037.       major_status.  If not GSS_S_COMPLETE, check 
  3038.          minor_status, 
  3039.          R_Services.Unprot_Service_1.General_Service_Data.minor_status,
  3040.          R_Services.Unprot_Service_2.General_Service_Data.minor_status,
  3041.       (as required) for more detailed information.
  3042.  
  3043.    Utilize
  3044.       R_Services.Unprot_Service_1/2.service_id, 
  3045.          (to determine which services were applied by the originator)
  3046.       R_Services.Unprot_Service_1/2.Quality, 
  3047.          (to determine the corresponding qualities of the service)
  3048.       Prot_Information.originator_name/protection_time and 
  3049.          Prot_Information.Idu_Information.idu_type/idu_title, 
  3050.          (from IDUP_Start_Unprotect) (to determine originator info.)
  3051.       R_Services.Unprot_Service_2.General_Service_Data.Target_Info.
  3052.          targ.names, (to determine if rec. is in "receipts from" (r))
  3053.       Service_Verification_Info/service_verification_info_id
  3054.          (to determine if receiver is in "receipts to" list (L))
  3055.  
  3056.    If receiver is in "receipts from" list (r)
  3057.       Save
  3058.          R_Services.Unprot_Service_2.service_to,
  3059.          R_Services.Unprot_Service_2.Service_Creation_Info
  3060.  
  3061.    If receiver is in "receipts to" list (L) 
  3062.       Save
  3063.          Service_Verification_Info,
  3064.          service_verification_info_id
  3065.  
  3066.  
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080. Adams               Document Expiration:  26 May  1997                53
  3081.  
  3082.  
  3083.    RECEIVER (ON "RECEIPTS FROM" LIST (r)):
  3084.       (procedure to generate receipt)
  3085.  
  3086.    Set
  3087.       env_handle                           = environment handle in use;
  3088.       Target_Info.targ_names               = service_to
  3089.       Prot_Service_1.prot_service_type     = "2";
  3090.       Prot_Service_1.service_id            = "PER_POD";
  3091.       Prot_Service_1.Service_Creation_Info = Service_Creation_Info;
  3092.       P_Services.Prot_Service_1            = Prot_Service_1
  3093.  
  3094.    Call
  3095.       IDUP_Start_Protect() with above input parameters 
  3096.    Check
  3097.       major_status.  If not GSS_S_COMPLETE, check 
  3098.          minor_status, 
  3099.          P_Services.Prot_Service_1.General_Service_Data.minor_status
  3100.       (as required) for more detailed information.
  3101.  
  3102.    Send
  3103.       pidu_buffer to "receipts to" list (L)
  3104.  
  3105.  
  3106.    RECEIVER (ON "RECEIPTS TO" LIST (L)):
  3107.       (procedure to process received receipt)
  3108.  
  3109.    Set 
  3110.       env_handle         = environment handle in use;
  3111.       single_pidu_buffer = received p-idu buffer (if it fits in a single 
  3112.          buffer; otherwise use partial_pidu_buffer and make multiple 
  3113.          calls, as above)
  3114.  
  3115.    Call
  3116.       IDUP_Start_Unprotect() with above input parameters
  3117.    If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED 
  3118.       Utilize
  3119.          R_Services.Unprot_Service_1.service_verification_info.id
  3120.          (to assist in locating necessary Service_Verification_Info)
  3121.       Set
  3122.          R_Services.Unprot_Service_1.Service_Verification_Info
  3123.             = Service_Verification_Info
  3124.       Call
  3125.          IDUP_Start_Unprotect() with above input parameters
  3126.    Check
  3127.       major_status,
  3128.       minor_status, 
  3129.       R_Services.Unprot_Service_1.General_Service_Data.minor_status
  3130.    (as required) for more detailed information.
  3131.  
  3132.    Utilize
  3133.       R_Services.Unprot_Service_1.service_id, 
  3134.          (to determine that this is a "proof of delivery" evidence)
  3135.       R_Services.Unprot_Service_1.Quality, 
  3136.       Prot_Information.originator_name, (for evidence generator info.)
  3137.       major_status (to determine pass/fail status of evi. verif.).
  3138.  
  3139. Adams               Document Expiration:  26 May  1997                54
  3140.