2.4. Special-Purpose Calls

2.4.1.  Relationship to GSS-API

   The special-purpose call described in this section has no analog in
   GSS-API [RFC-2078].  This call is used to complete a P-IDU (that is,
   to generate a P-IDU which can be unprotected successfully with no
   additional data at any time during its validity period).  This call
   may not be supported by all underlying IDUP mechanisms or

   implementations.

2.4.2. IDUP_Form_Complete_PIDU call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  single_pidu_buffer OCTET STRING,
   o  partial_pidu_buffer OCTET STRING,
      -- an arbitrary-sized piece of the full pidu token.  Used if pidu
      -- will be input a buffer at a time (except that the final buffer
      -- must be passed in final_pidu_buffer rather than
      -- partial_pidu_buffer).  Only one of single_pidu_buffer and
      -- partial(final)_pidu_buffer can have nonzero length.
   o  final_pidu_buffer OCTET STRING,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  pidu_token_out OCTET STRING -- the augmented PIDU; may be complete
   o  call_again_before INTEGER,
   o  call_again_after INTEGER,
   o  trusted_time_stamping_time INTEGER  -- for information only

   Return major_status codes:
   o  GSS_S_COMPLETE
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
   o  IDUP_S_INCOMPLETE
      -- generation of the P-IDU is not yet complete.  The application
      -- should call this function again before the time given in
      -- call_again_before (if not NULL), or after the time given in
      -- call_again_after (if not NULL), or both (if neither are NULL).
   o  IDUP_S_INCONSISTENT_PARAMS
   o  IDUP_S_SERVICE_UNAVAIL
   o  GSS_S_DEFECTIVE_TOKEN
   o  GSS_S_FAILURE

   Form_Complete_PIDU is used primarily by the evidence services; in
   particular, when the evidence token itself does not contain all the
   data required for its verification and it is anticipated that some of
   the data not stored in the token may become unavailable during the
   interval between generation of the evidence token and verification
   unless it is stored in the token. The Form_Complete_PIDU operation
   gathers the missing information and includes it in the token so that
   verification can be guaranteed to be possible at any future time.

   This call generates a PIDU which can be unprotected successfully with
   no additional data at any time during its validity period.  [For
   background information on the notion of "complete" evidence, see

   "CORBA Security Service v1.2 Draft D02", 18 June 1997.]

   Using the security environment referenced by env_handle, complete the
   generation of a P-IDU token and return the appropriate status value
   along with the completed token (if available).  Such a call may be
   used, for example, for the purpose of batch evidence generation on an
   "evidence server".  A local machine may be able to use the protection
   set of calls to fill out most of an evidence token and then send a
   number of these to a batch processor which forms the complete
   evidence tokens (perhaps by adding a certification path, or a
   timestamp and signature from a timestamping authority).  As another
   example, on the receiving end an application may make such a call in
   order to collect all the information necessary to unprotect a P-IDU
   (such as all relevant certificates and Certificate Revocation Lists);
   this will ensure that the calls to the unprotection set of operations
   will be entirely local (i.e., can be performed off-line) and fast.

   Note that the complete P-IDU generated will be formed using trusted
   time if this is available in the environment referenced by env_handle
   and will use untrusted time or no time otherwise (depending on what
   is available).

2.5.  Support calls

2.5.1.  Relationship to GSS-API

   Support calls in IDUP-GSS-API are to be understood and used as
   described in GSS-API [RFC-2078].  The calls described in Section 2.4
   of GSS-API (including all associated parameters) are unchanged.  The
   following additional calls are specified for IDUP-GSS-API.

2.5.2:  IDUP_Acquire_cred_with_auth call

   Inputs:
   o  desired_name INTERNAL NAME,
      -- NULL requests locally-determined default
   o  authenticator OCTET STRING
      -- string which authenticates the caller claiming to be
      -- desired_name
   o  lifetime_req INTEGER,
      -- in seconds; 0 requests default
   o  desired_mechs SET OF OBJECT IDENTIFIER,
      -- empty set requests system-selected default
   o  cred_usage BIT STRING
      -- actual values which can be used currently correspond to those
      -- given in Section 2.1.1 (i.e.,
      --    ENCRYPT_ONLY    8
      --    DECRYPT_ONLY   16

      --    SIGN_ONLY      32
      --    VERIFY_ONLY    64
      -- with the values logically OR'ed together in any desired
      -- combination to restrict credential usage; OR'ing all values
      -- results in NO_RESTRICTION).
      -- Future possible values for this parameter are for further
      -- study (note that the type of this parameter is BIT STRING
      -- (rather than INTEGER as in GSS_Acquire_cred) to facilitate
      -- such future expansion).

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  output_cred_handle  CREDENTIAL HANDLE,
   o  actual_mechs SET OF OBJECT IDENTIFIER,
   o  actual_cred_usage   BIT STRING,
   o  lifetime_rec INTEGER
      -- in seconds, or reserved value for INDEFINITE

   This call (which need not be supported by all underlying mechanisms
   or implementations) is identical to the GSS_Acquire_cred call, with
   the exception of the added input parameter "authenticator" and the
   added output parameter "actual_cred_usage". The authenticator
   (typically a password, pass-phrase, or PIN) is used to authenticate
   the caller claiming to be desired_name to the underlying GSS (or
   mechanism) code.  The actual_cred_usage specifies the actual uses
   available for these credentials; it is up to the caller to determine
   if this is sufficient for its purposes.

   Implementations that are able to authenticate the caller in some
   other way are encouraged to use the GSS_Acquire_cred call; those
   having no other means available to them, or wishing to explicitly
   authenticate the caller at the time of credential acquisition, should
   use the IDUP_Acquire_cred_with_auth call (if supported).

   Note that the return major status codes for this call are identical
   to those given for the GSS_Acquire_cred call.  If the authentication
   fails (e.g., the wrong authenticator is supplied for the given
   desired_name), the major status GSS_S_FAILURE is returned (along with
   an appropriate minor status code).

2.5.3. IDUP_Get_token_details call

   Inputs:
   o  token                  OCTET STRING,
   -- all the data to be returned shall be within the first 4 KB of
   -- the token; hence, a single call is needed. It is not necessary
   -- to provide the entire token when the token includes the IDU.

   o  mech_type              SET OF OBJECT IDENTIFIER
   -- input if known (typically SET will contain a single member)

   Outputs:
   o  major_status                       INTEGER,
   o  minor_status                       INTEGER,
   o  actual_mech_type                   OBJECT IDENTIFIER,
   o  data_included_in_token             BOOLEAN,
      -- true if the data is encapsulated
   o  idu_size                           INTEGER,
   o  has_SE_protection                  BOOLEAN,
   o  has_EV_protection                  BOOLEAN,
   o  PIDU_Information                   PARAMETER BUNDLE,
   o  nr_policy                          OBJECT IDENTIFIER,
      -- this and subsequent parameters pertain only to evidence tokens
   o  Nr_Options                         PARAMETER BUNDLE,
   o  Originator_Information             PARAMETER BUNDLE,
   o  time_stamping_time                 INTEGER  OPTIONAL
   o  Request_Features                   PARAMETER BUNDLE,
      -- describes the included request, if any.
   o  requested_evidence_back            BOOLEAN,
      -- true if this is an evidence generated in response to a
      -- previously-sent request
   o  evidence_check                     OCTET STRING,
      -- meaningful if the boolean above is true

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- input_token could be parsed for all relevant fields.
   o  GSS_S_CREDENTIALS_EXPIRED
   o  GSS_S_DEFECTIVE_TOKEN
      -- the mechanism type could be parsed, but either the other fields
      -- could not be determined from the input_token, or their values
      -- did not correspond to valid values for that mechanism.
   o  GSS_S_FAILURE
      -- the mechanism type was missing or corrupted.

   IDUP_Get_token_details() is used to return to an application the
   attributes that correspond to a given input token.  Since IDUP-GSS-
   API tokens are meant to be opaque to the calling application, this
   function allows the application to determine information about the
   token without having to violate the opaqueness intention of IDUP. Of
   primary importance is the mechanism type, which the application can
   then use as input to the IDUP_Establish_Env() call in order to
   establish the correct environment in which to have the token
   processed.

   If all tokens are framed as suggested in Section 3.1 of [RFC-2078]
   (mandated in the Kerberos V5 GSS mechanism [RFC 1964] and in the SPKM
   GSS Mechanism [RFC 2025]), then any mechanism implementation should
   be able to return the mech_type parameter for any uncorrupted input
   token. If the mechanism implementation whose IDUP_Get_token_details()
   function is being called does recognize the token, it can return any
   further relevant information in the other token attributes, as
   specified.  In particular, this function can set has_SE_protection if
   the SE calls may be used to unprotect it, or has_EV_protection if the
   EV calls may be used to unprotect it, or both if both kinds of
   protection have been applied (so that SE or EV calls may be used in
   any order for unprotection) [note that GP calls, when supported,
   should be usable for unprotection of any IDUP token].

   IDUP_Get_token_details (which need not be supported by all underlying
   mechanisms or implementations) gives only a hint about the content of
   the token, there is no integrity check of any kind performed.
   Regardless of the token type, it is possible to check that this
   information is correct only by doing a proper unprotection of the
   token.  It is recommended that IDUP callers supply a token buffer at
   least 4 KB in length in order to ensure that the desired data can
   easily flow across this interface.

   The OID of the mechanism and whether the token contains the
   associated data is returned. In addition the size of the associated
   data, whether inside or outside the token, is included if known.
   [Note:  data size will typically be unknown if the data was protected
   using multibuffer calls.  A value of "-1" may be used to indicate
   "UNKNOWN".]

   When the input token contains only an evidence generated
   spontaneously, the following is returned:
    - the evidence type;
    - the Non-Repudiation policy under which the evidence was generated;
    - the name of the generator of the evidence;
    - the date and time when the evidence was generated (if available);
    - the date and time when it was time stamped (if available).

   When the input token contains only an evidence generated in response
   to  a request from another entity, the following additional
   information is returned:
    - an indicator to state that this evidence relates to a request;
    - a string significant for the requester that will allow him to
      check whether the answer corresponds to the requested evidence.

   When the input token only contains a request, the following is
   returned:
    - the name of the requestor of the evidence,

    - the date and time when the request was made,
    - the evidence type to send back,
    - the non-repudiation policy under which the evidence to send back
      should be generated,
    - the names of the recipients which should generate and distribute
      the requested evidence,
    - the names of the recipients to whom the requested evidence should
      be sent after it has been generated.

   When the input token contains both evidence and a request, an
   indicator is returned describing whether the new evidence should be
   generated using only the data in the input token, or using both the
   data and the evidence in the input token.

   When the input token contains only CONF and DOA services, the
   PIDU_Information bundle is returned.  Other relevant parameters (such
   as idu_size and time_stamping_time) may also be returned if this data
   is available.

2.5.4. IDUP_Get_policy_info call

   Inputs:
   o  policy_id OBJECT IDENTIFIER

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  policy_version INTEGER,
   o  policy_effective_time INTEGER,
   o  policy_expiry_time INTEGER,
   o  supported_services SET OF Service_Descriptor,
      -- services supported by this particular policy_id (equal to the
      -- intersection of the services supported by the mechanisms
      -- listed in supported_mechanisms)
   o  supported_mechanisms SET OF Mechanism_Descriptor
      -- mechanisms supported by this particular policy_id

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- policy_id recognized; all relevant fields have been returned.
   o  GSS_S_FAILURE
      -- the policy_id was not recognized.

   This call (which need not be supported by all underlying mechanisms
   or implementations) allows the application to retrieve information
   pertaining to a given policy_id.  Policies define the following:
      -  rules for the protection of IDUs, such as trusted third
         parties which may be involved in P-IDU generation, the roles in

         which they may be involved, and the duration for which the
         generated P-IDU is valid;

      -  rules for the unprotection of P-IDUs, such as the interval
         during which a trusted third party may legitimately declare its
         key to have been compromised or revoked; and

      -  rules for adjudication, such as which authorities may be used
         to adjudicate disputes.

   The policy itself may be used by an adjudicator when resolving a
   dispute.  For example, the adjudicator might refer to the policy to
   determine whether the rules for generation of the P-IDU have been
   followed.

   The following parameter bundles are associated with this call.

      o  Service_Descriptor PARAMETER BUNDLE,
         o  service_type OBJECT IDENTIFIER,
         o  service_validity_duration INTEGER,
         o  must_use_trusted_time BOOLEAN

      o  Mechanism_Descriptor PARAMETER BUNDLE,
         o  mechanism_type OBJECT IDENTIFIER,
         o  Authority_List PARAMETER BUNDLE,
         o  maximum_time_skew INTEGER
            -- maximum permissible difference between P-IDU generation
            -- time and the time of countersignature from a time
            -- service (if required).  This parameter is unused if
            -- trusted time is not required.

      o  Authority_List PARAMETER BUNDLE,
         o  authority_name INTERNAL NAME,
         o  authority_role OCTET STRING,
         o  last_revocation_check_offset INTEGER
            -- may be 0, greater than 0, or less than 0.  The value of
            -- this parameter is added to P-IDU generation time to
            -- get latest time at which the mechanism will check to
            -- see if this authority's key has been revoked.

   An example of the use of the last parameter in Authority_List is as
   follows.  If an authority has a defined last_revocation_check_offset
   of negative one hour, then all revocations taking effect earlier than
   one hour before the generation of a P-IDU will render that P-IDU
   invalid; no revocation taking place later than one hour before the
   generation of the P-IDU will affect the P-IDU's validity.

   Note that both the maximum_time_skew and the
   last_revocation_check_offset values are given in minutes.

2.5.5. IDUP_Cancel_multibuffer_op call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- operation cancelled; state purged.
   o  GSS_S_FAILURE
      -- unable to cancel operation; state retained.

   This call (which need not be supported by all underlying mechanisms
   or implementations) allows the application to cancel a multibuffer
   operation prior to normal completion (e.g., subsequent to calling
   Start_operation and zero or more Process_operation, but prior to
   calling End_operation).  When successful, this call purges any
   internal state information which would have been used to continue
   processing for the full set of multibuffer calls.

3.  Related Activities

   In order to implement the IDUP-GSS-API atop existing, emerging, and
   future security mechanisms, the following is necessary:

    - object identifiers must be assigned to candidate IDUP-GSS-API
      mechanisms and the name types which they support; and

    - concrete data element (i.e., token and parameter bundle) formats
      must be defined for candidate mechanisms.

   Calling applications must implement formatting conventions which will
   enable them to distinguish IDUP-GSS-API P-IDUs from other IDUs in
   their environment.

   Concrete language bindings are required for the programming
   environments in which the IDUP-GSS-API is to be employed.

4.  Acknowledgments

   Many thanks are due to Tim Moses and Dhanya Thakkar of Entrust
   Technologies, Denis Pinkas of Bull, and David Kurn of Tandem
   Computers for a number of helpful comments and contributions.

5. Security Considerations

   Security issues are discussed throughout this memo.

6. REFERENCES

   [MSP]       U.S. National Security Agency, "Message Security
               Protocol", Secure Data Network System SDN.701, March
               1994.

   [RFC-1421]  Linn, J., "Privacy Enhancement for Internet Electronic
               Mail:  Part I: Message Encryption and Authentication
               Procedures", RFC 1421, February 1993.

   [RFC-2078]  Linn, J., "Generic Security Service Application Program
               Interface, Version 2", RFC 2078, January 1997..

   [RFC 1964]  Linn, J, "The Kerberos Version 5 GSS-API Mechanism", RFC
               1964, June 1996.

   [RFC 2025]  Adams, C., "The Simple Public-Key GSS-API Mechanism
               (SPKM)", RFC 2025, October 1996.

   [ISO/IEC]   2nd ISO/IEC CD 13888-1, "Information technology -
               Security techniques - Non-repudiation - Part 1:  General
               Model", ISO/IEC JTC 1/SC 27, May 30, 1995

7. Author's Address

   Carlisle Adams
   Entrust Technologies
   750 Heron Road, Suite E08,
   Ottawa, Ontario, CANADA  K1V 1A7

   Phone:  +1 613.247.3180
   EMail: cadams@entrust.com

APPENDIX  A:  MECHANISM-INDEPENDENT TOKEN FORMAT

   This appendix specifies the use, for IDUP-GSS-API tokens, of the
   mechanism-independent level of encapsulating representation for
   tokens given in Section 3.1 of GSS-API [RFC-2078].  The
   representation given there incorporates an identifier of the
   mechanism type to be used when processing the associated tokens. Use
   of that octet format is recommended to the designers of IDUP-GSS-API
   implementations based on various mechanisms so that tokens can be
   interpreted unambiguously at IDUP-GSS-API peers. It is recognized,
   however, that for interoperability purposes with peers not using IDUP
   for specific IDU protection/unprotection protocols, the encapsulating
   representation may need to be omitted.  (In such a case it is
   necessary that the underlying mechanism provides some sort of
   internal or external identification that allows it to recognize its
   own tokens.)  When the mechanism-independent level of encapsulating
   representation is not desired, callers SHOULD set
   mech_indep_encap_req to FALSE (note that some underlying mechanisms
   may default this parameter to FALSE).

   For purely descriptive purposes, the following simple ASN.1 structure
   is used to illustrate the structural relationships among token and
   tag objects.  For interoperability purposes, token and tag encoding
   shall be performed using the concrete encoding procedures described
   in Section 3.1 of GSS-API [RFC-2078].

          -- top-level token definition to frame different mechanisms

          IDUP-GSS-API DEFINITIONS ::=
          BEGIN
          MechType ::= OBJECT IDENTIFIER

          Token ::= [APPLICATION 0] IMPLICIT SEQUENCE {
                  thisMech MechType,
                  token ANY DEFINED BY thisMech
                     -- contents mechanism-specific
                  }
          END

APPENDIX  B:  EXAMPLES OF IDUP USE

   This appendix provides examples of the use of IDUP to do IDU
   protection and unprotection.  It should not be regarded as
   constrictive to implementations or as defining the only means through
   which IDUP-GSS-API functions can be realized with particular
   underlying technology, and does not demonstrate all IDUP-GSS-API
   features.

   Most of the examples below only illustrate the use of CONF/DOA
   protection services.  Note that when both CONF/DOA and Evidence
   services are required, calling applications may use a series of SE
   and EV calls, or may use the GP calls (when these are supported).
   Using the former approach implies multiple calls (e.g., the SE calls
   are used to protect some data and the resulting token is then input
   to the EV calls to add evidence information), but some callers may
   find this to be more attractive than coding to the GP calls because
   of the simpler SE/EV interface.  Depending upon the underlying
   mechanism, the series of SE/EV calls may result in a single token
   that can be unprotected using the SE and EV calls in any order (for
   example, because it is a single ASN.1 SEQUENCE that incorporates all
   the specified protection services at one level), or the series may
   result in a token that can only be unprotected in the reverse order
   of protection (for example, because each SE/EV output token was
   effectively embedded in the token of the subsequent call). The
   IDUP_Get_token_details call can assist callers in determining how to
   unprotect any received token.

B.1.  Simple Mechanism, Single Buffer

   To illustrate the simplest possible case, consider an underlying IDUP
   mechanism which does straightforward encryption/decryption and
   signing/verification only using public-key techniques; none of the
   other possible services, such as creation of proof-of-origin
   evidence, requests for proof-of-delivery evidence, or use of trusted
   time, are supported.  PEM[RFC-1421] is one example of a mechanism
   which fits this description.  Furthermore (again for simplicity),
   assume that encapsulation is chosen by the calling application during
   IDU protection.

   Such a mechanism would likely use the "SE" set of IDUP-GSS-API calls.
   The following parameter bundle uses and defaults would therefore be
   specified in the relevant IDUP mechanism document.

   SENDER:

   Set
      env_handle                = environment handle in use;
      idu_buffer                = data buffer;
      Target_Info.targ_names    = receiver names;
      Protect_Options           = as necessary;

   Call
      IDUP_SE_SingleBuffer_Protect() with above input parameters

   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         Target_Info.Bad_Targ_Name,
      (as required) for more detailed information.

   Send
      Output parameter pidu_buffer to receiver.

   RECEIVER (any parameters not listed below are given the value NULL):

   Set
      env_handle         = environment handle in use;
      pidu_buffer        = received data buffer;

   Call
      IDUP_SE_SingleBuffer_Unprotect() with above input parameters
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
      (as required) for more detailed information

   Utilize
      PIDU_Information.Protect_Options.Protect_Operation,
         (to determine which services were applied by the originator)
      PIDU_Information.Protect_Options.sign_qop_alg / enc_qop_alg,
         (to determine the corresponding qualities of the services)
      Prot_Information.originator_name,
         (to determine the name of the originator)
      Prot_Information.protection_time,
         (to determine when the IDU was protected)
      idu_buffer
         (to retrieve the unprotected data).

B.2.  Simple Mechanism, Single Buffer (Again)

   To illustrate a slight variation on the simplest possible case,
   assume that everything is as in the previous scenario except that the
   "GP" calls are used.

   The following parameter bundle uses and defaults would therefore be
   specified in the relevant IDUP mechanism document.

   Mech_Specific_Info
      - NOT USED (the only acceptable input, therefore, is NULL)

   Idu_Sensitivity
      - NOT USED (the only acceptable input, therefore, is NULL)

   Service_Creation_Info
      - NOT USED (the only acceptable input, therefore, is NULL)

   Service_Verification_Info
      - NOT USED (the only acceptable input, therefore, is NULL)

   Quality
      - the qop_algs parameter must be supported, with a suitable
        DEFAULT value specified;
      - suitable DEFAULT values for validity, policy_id, and
        allow_policy_mapping must be specified (it may be an
        implementation option as to whether these parameters are
        explicitly modifiable by the calling application, or whether
        NULLs are the only acceptable input)

    Idu_Information
      - the idu_type parameter must have a value representing a suitable
        IDU type (for example, in PEM a value representing the string
        "RFC822" or some other valid "Content-Domain" would be used),
        with a suitable DEFAULT value specified;
      - the idu_title parameter is NOT USED (the only acceptable input,
        therefore, is NULL)

   Prot_Information
      - the originator_name and idu_type (in Idu_Information) parameters
        are read from the encapsulating information and output by
        IDUP_Start_Unprotect;
      - all other parameters are NOT USED (and therefore NULL)

   Special_Conditions
      - NOT USED (the only acceptable input, therefore, is NULL)

   Target_Info
      - this bundle is used as described in IDUP; no DEFAULT values are
        specified

   General_Service_Data
      - the unencapsulated_token parameter is used if
        encapsulation_request is FALSE;
      - the minor_status parameter is used to return minor status values
        as specified by the mechanism document

   Prot_Service
      - the prot_service_type parameter may have a value of "1"
        ("perform unsolicited service") or NULL (which specifies the
        DEFAULT value of "1");
      - the service_id parameter must have a value representing
        "PER_CONF" or "PER_DOA";
      - the parameters Service_Creation_Info, service_to,
        Service_Verification_Info, and service_verification_info_id are
        NOT USED (and therefore NULL)

   Unprot_Service
      - the unprot_service_type parameter will always have a value of
        "1" ("receive unsolicited service");
      - the service_id parameter will have a value representing
        "REC_CONF" or "REC_DOA";
      - the parameters service_verification_info_id,
        Service_Verification_Info, service_to, and
        Service_Creation_Info, are NOT USED (and therefore NULL)

   Assuming that the calling application has only a single buffer of
   data to protect/unprotect, the following sequence of operations must
   be performed by the sender and receivers (subsequent to environment
   establishment).

   SENDER (any parameters not listed below are given the value NULL):

   Set
      env_handle                           = environment handle in use;
      encapsulation_request                = TRUE;
      single_idu_buffer                    = data buffer;
      Target_Info.targ_names               = receiver names;
      P_Services.Prot_Service_1.service_id = PER_CONF;
      P_Services.Prot_Service_2.service_id = PER_DOA;

   Call
      IDUP_Start_Protect() with above input parameters

   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         Target_Info.bad_targ_names / Target_Info.bad_targ_status,
         P_Services.Prot_Service_1.General_Service_Data.minor_status,
         P_Services.Prot_Service_2.General_Service_Data.minor_status
      (as required) for more detailed information.

   Send
      Output parameter pidu_buffer to receiver.


   RECEIVER (any parameters not listed below are given the value NULL):

   Set
      env_handle         = environment handle in use;
      single_pidu_buffer = received data buffer;

   Call
      IDUP_Start_Unprotect() with above input parameters
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         R_Services.Unprot_Service_1.General_Service_Data.minor_status,
         R_Services.Unprot_Service_2.General_Service_Data.minor_status
      (as required) for more detailed information

   Utilize
      R_Services.Unprot_Service_1/2.service_id,
         (to determine which services were applied by the originator)
      R_Services.Unprot_Service_1/2.Quality,
         (to determine the corresponding qualities of the services)
      Prot_Information.originator_name,
         (to determine the name of the originator)
      single_idu_buffer
         (to retrieve the unprotected data).

B.3.  Simple Mechanism, Multiple Buffers

   To illustrate the next step up in complexity, consider the use of the
   simple IDUP mechanism described in B.2 above with multiple data
   buffers.  In particular, consider the case in which a large data file
   is to be signed.  For this example, assume that the calling
   application does not wish to use encapsulation.

   Note that the parameter bundle uses and defaults are as specified in
   B.2. above.

   SENDER (any parameters not listed below are given the value NULL):

   Set
      env_handle                           = environment handle in use;
      encapsulation_request                = FALSE;
      P_Services.Prot_Service.service_id   = PER_DOA;

   Call
      IDUP_Start_Protect() with above input parameters
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         P_Services.Prot_Service.General_Service_Data.minor_status
      (as required) for more detailed information.

   For each buffer of input data:
      Set
         input_buffer = buffer
      Call
         IDUP_Protect() with above input parameter
      Check
         major_status.  If not GSS_S_COMPLETE, check
            minor_status

   Call
      IDUP_End_Protect()
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         P_Services.Prot_Service.General_Service_Data.minor_status
      (as required) for more detailed information.

   Send
      P_Services.Prot_Service.General_Service_Data.unencapsulated_token,
      and the file for which the signature was calculated (if required),
      to receiver.

   RECEIVER (any parameters not listed below are given the value NULL):

   Set
      env_handle            = environment handle in use;
      R_Services.Unprot_Service_1.General_Service_Data.
      unencapsulated_token  = received unencapsulated token;

   Call
      IDUP_Start_Unprotect() with above input parameters
   Check
      major_status.  If not GSS_S_COMPLETE, check

         minor_status,
         R_Services.Unprot_Service_1.General_Service_Data.minor_status,
      (as required) for more detailed information

   For each buffer of input data:
      Set
         input_buffer = buffer
      Call
         IDUP_Unprotect() with above input parameter
      Check
         major_status.  If not GSS_S_COMPLETE, check
            minor_status

   Call
      IDUP_End_Unprotect()
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         R_Services.Unprot_Service_1.General_Service_Data.minor_status,
      (as required) for more detailed information.

   Utilize
      R_Services.Unprot_Service_1.service_id,
         (to determine which service was applied by the originator; note
          that Unprot_Service_2 will have NULL in unprot_service_type
          to indicate that it is not used)
      R_Services.Unprot_Service_1.Quality,
         (to determine the corresponding quality of the service)
      Prot_Information.originator_name, (from IDUP_Start_Unprotect)
         (to determine the name of the signer)
      major_status (from IDUP_End_Unprotect)
         (to determine pass/fail status of signature verification).

B.4.  More Sophisticated Mechanism, Small Application Buffers

   To illustrate a higher level of complexity, consider the use of a
   more sophisticated IDUP mechanism and a calling application with
   small data buffers.  In particular, consider the case in which a very
   small e-mail message is to be encrypted for a relatively large
   receiver list (R), some subset of whom (r) will be asked to send
   proofs of receipt of the message to some other subset (L) (which
   includes the originator).  So that the example is not unnecessarily
   complicated, assume again that the originating application uses
   encapsulation.

   The uses and defaults for the various parameter bundles for this
   mechanism would be specified in the relevant IDUP mechanism document
   as follows.

   Mech_Specific_Info
      - NOT USED (the only acceptable input, therefore, is NULL)

   Idu_Sensitivity
      - NOT USED (the only acceptable input, therefore, is NULL)

   Service_Creation_Info
      - used to create "proof of delivery" evidence (but actual
        structure is opaque to calling application)

   Service_Verification_Info
      - used to verify "proof of delivery" evidence (but actual
        structure is opaque to calling application)

   Quality
      - the qop_algs parameter must be supported, with a suitable
        DEFAULT value specified;
      - suitable DEFAULT values for validity, policy_id, and
        allow_policy_mapping must be specified (it may be an
        implementation option as to whether these parameters are
        explicitly modifiable by the calling application, or whether
        NULLs are the only acceptable input)

   Idu_Information
      - the idu_type parameter must have a value representing a suitable
        IDU type, with a suitable DEFAULT value specified;
      - the idu_title parameter must have a value representing a
        suitable IDU title, with a suitable DEFAULT value specified

   Prot_Information
      - the originator_name, protection_time, and idu_type / idu_title
        (in Idu_Information) parameters are read from the contained
        header information and output by IDUP_Start_Unprotect;

   Special_Conditions
      - the parameter prot_oper_id is NOT USED (the only acceptable
        input, therefore, is NULL);
      - trusted or untrusted time may be selected by the calling
        application, with a suitable DEFAULT value specified

   Target_Info
      - this bundle is used as described in IDUP; no DEFAULT values are
        specified

   General_Service_Data
      - the unencapsulated_token parameter is used if
        encapsulation_request is FALSE;
      - the minor_status parameter is used to return minor status values

        as specified by the mechanism document

   Prot_Service
      - the prot_service_type parameter may have a value of "1"
        ("perform unsolicited service"), "2" ("perform solicited
        service"), "3" (perform service solicitation), or NULL (which
        specifies the DEFAULT value of "1");
      - the service_id parameter must have a value representing
        "PER_CONF", "PER_DOA", "PER_POO", or "PER_POD";
      - the parameters Service_Creation_Info, service_to,
        Service_Verification_Info, and service_verification_info_id are
        used when required by the IDUP operation

   Unprot_Service
      - the unprot_service_type parameter may have a value of "1"
        ("receive unsolicited service"), "2" ("receive solicited
        service"), or "3" (receive service solicitation);
      - the service_id parameter will have a value representing
        "REC_CONF", "REC_DOA", "REC_POO", or "REC_POD";
      - the parameters service_verification_info_id,
        Service_Verification_Info, service_to, and
        Service_Creation_Info, are used when required by the IDUP
        operation


   SENDER (any parameters not listed below are given the value NULL):

   Set
      env_handle                          = environment handle in use;
      Idu_Information.idu_type            = value for "e-mail document";
      Idu_Information.idu_title           = "Contract 1234";
      Special_Conditions.use_trusted_time = TRUE;
      encapsulation_request               = TRUE;
      single_idu_buffer                   = very small e-mail message;
      Target_Info.targ_names              = receiver names (R);
      Prot_Service_1.prot_service_type    = "1";
      Prot_Service_1.service_id           = PER_CONF;
      Prot_Service_2.prot_service_type    = "3";
      Prot_Service_2.service_id           = PER_POD;
      Prot_Service_2.General_Service_Data.Target_Info.targ_names
                                          = "receipts from" list (r);
      Prot_Service_2.service_to           = "receipts to" list (L);
      P_Services.Prot_Service_1           = Prot_Service_1;
      P_Services.Prot_Service_2           = Prot_Service_2;

   Call
      IDUP_Start_Protect() with above input parameters

   Check
      major_status.  If not GSS_S_COMPLETE,
         while major_status == IDUP_S_MORE_OUTBUFFER_NEEDED
            Save
               pidu_buffer,
            Call
               IDUP_Start_Protect() (to get next portion of pidu_buffer)
         Check
            major_status,
            minor_status,
            Target_Info.bad_targ_names / Target_Info.bad_targ_status,
            P_Services.Prot_Service_1.General_Service_Data.minor_status,
            P_Services.Prot_Service_2.General_Service_Data.minor_status
         (as required) for more detailed information.

   Save
      Prot_Service_2.Service_Verification_Info,
      Prot_Service_2.service_verification_info_id

   Send
      All saved buffers of pidu_buffer to receiver list (R).


   RECEIVER (ON RECEIVER LIST (R)):
      (any parameters not listed below are given the value NULL)

   Set
      env_handle          = environment handle in use;
      partial_pidu_buffer = initial buffer of received p-idu;

   Call
      IDUP_Start_Unprotect() with above input parameters
   While major_status == IDUP_S_MORE_PIDU_NEEDED,
      Set
         partial_pidu_buffer = next buffer of p-idu
      Call
         IDUP_Start_Unprotect()
   Check
      major_status,
      minor_status,
      R_Services.Unprot_Service_1.General_Service_Data.minor_status,
      R_Services.Unprot_Service_2.General_Service_Data.minor_status,
   (as required) for more detailed information

   Save
      initial_idu_buffer (if non-empty)

   Set
      input_buffer = remaining p-idu buffer
   Call
      IDUP_Unprotect() with above input parameter
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status
   Save
      output_buffer

   Call
      IDUP_End_Unprotect()
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         R_Services.Unprot_Service_1.General_Service_Data.minor_status,
         R_Services.Unprot_Service_2.General_Service_Data.minor_status,
      (as required) for more detailed information.

   Utilize
      R_Services.Unprot_Service_1/2.service_id,
         (to determine which services were applied by the originator)
      R_Services.Unprot_Service_1/2.Quality,
         (to determine the corresponding qualities of the service)
      Prot_Information.originator_name/protection_time and
         Prot_Information.Idu_Information.idu_type/idu_title,
         (from IDUP_Start_Unprotect) (to determine originator info.)
      R_Services.Unprot_Service_2.General_Service_Data.Target_Info.
         targ.names, (to determine if rec. is in "receipts from" (r))
      Service_Verification_Info/service_verification_info_id
         (to determine if receiver is in "receipts to" list (L))

   If receiver is in "receipts from" list (r)
      Save
         R_Services.Unprot_Service_2.service_to,
         R_Services.Unprot_Service_2.Service_Creation_Info

   If receiver is in "receipts to" list (L)
      Save
         Service_Verification_Info,
         service_verification_info_id

   RECEIVER (ON "RECEIPTS FROM" LIST (r)):
      (procedure to generate receipt)

   Set
      env_handle                           = environment handle in use;
      Target_Info.targ_names               = service_to

      Prot_Service_1.prot_service_type     = "2";
      Prot_Service_1.service_id            = "PER_POD";
      Prot_Service_1.Service_Creation_Info = Service_Creation_Info;
      P_Services.Prot_Service_1            = Prot_Service_1

   Call
      IDUP_Start_Protect() with above input parameters
   Check
      major_status.  If not GSS_S_COMPLETE, check
         minor_status,
         P_Services.Prot_Service_1.General_Service_Data.minor_status
      (as required) for more detailed information.

   Send
      pidu_buffer to "receipts to" list (L)

   RECEIVER (ON "RECEIPTS TO" LIST (L)):
      (procedure to process received receipt)

   Set
      env_handle         = environment handle in use;
      single_pidu_buffer = received p-idu buffer (if it fits in a single
         buffer; otherwise use partial_pidu_buffer and make multiple
         calls, as above)

   Call
      IDUP_Start_Unprotect() with above input parameters
   If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED
      Utilize
         R_Services.Unprot_Service_1.service_verification_info.id
         (to assist in locating necessary Service_Verification_Info)
      Set
         R_Services.Unprot_Service_1.Service_Verification_Info
            = Service_Verification_Info
      Call
         IDUP_Start_Unprotect() with above input parameters
   Check
      major_status,
      minor_status,
      R_Services.Unprot_Service_1.General_Service_Data.minor_status
   (as required) for more detailed information.

   Utilize
      R_Services.Unprot_Service_1.service_id,
         (to determine that this is a "proof of delivery" evidence)
      R_Services.Unprot_Service_1.Quality,
      Prot_Information.originator_name, (for evidence generator info.)
      major_status (to determine pass/fail status of evi. verif.).

Full Copyright Statement

   Copyright (C) The Internet Society (1998).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.