2.3.  Per-IDU calls

   This group of calls is used to perform IDU protection and
   unprotection processing on an established IDUP environment. Some of
   these calls may block pending network interactions (depending on the
   underlying mechanism in use).  These calls may be invoked by an IDU's
   protector or by the P-IDU's recipient.  Members of this group form
   pairs; the output from the protection types of calls is typically
   meant to be input to the unprotection types of calls.

   The per-IDU calls can support caller-requested data origin
   authentication with data integrity, confidentiality with data
   integrity, evidence, and evidence-requested-from-target services.

   The protection operations output a token which encapsulates all the
   information required to unprotect the IDU.  The token is passed to
   the target (possibly separate from the M-IDU) and is processed by the
   unprotection calls at that system.  Unprotection performs
   decipherment, DOA verification, evidence verification, or
   notification of evidence requested, as required.

   Each of the two main operations (protection and unprotection) may be
   separated into three parts:  "Start_Operation"; "Operation" (which
   may be called once for each buffer of input data); and
   "End_Operation".  This separation is available for the case where the
   IDU or P-IDU is to be processed one buffer at a time.
   "Start_Operation" allows the caller to specify or retrieve the
   appropriate "Quality" used during the processing.  "Operation" is
   concerned with the processing itself, receiving a buffer of input
   data and potentially returning a buffer of output data.
   "End_Operation" performs any required clean-up and creates the
   appropriate token or states whether the input token was verified.

   If the IDU or P-IDU is wholly contained in a single buffer, the
   three-part protection/unprotection processing need not be done.
   Instead, protection or unprotection can be accomplished using only a
   single call, simplifying application code.

2.3.1.  Relationship to GSS-API

   The set of calls described in this section is used in place of the
   calls GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() which
   are specified in [RFC-2078], since those calls are specific to a
   session-oriented environment.

2.3.2.  The "SE" Calls

2.3.2.1. IDUP_SE Purpose

   The "SE" group of calls provides a very simple, high-level interface
   to underlying IDUP mechanisms when application developers need access
   only to signature and encryption protection/unprotection services.
   It includes both the single-buffer and multiple-buffer IDU cases and
   can be used for signing only, encrypting only, signing and encrypting
   (in either order, and with or without visibility of the resulting
   signature), and "clear signing" (where the data is not modified in
   any way and the signature itself is returned as a separate item).
   [Note that encapsulation occurs in all cases except for clear
   signing, so that these calls provide functionality similar to the
   GSS_Wrap call.]

   Note that the term "signing" is used in its most generic sense, not
   necessarily implying the use of public-key techniques.  This concept
   has also been called "sealing" in other contexts (e.g., in other
   standardization efforts).

   The SE calls may be viewed by mechanism implementors as an "API" to
   the more powerful GP calls defined later and so may be implemented as
   simple mapping functions to those calls (when those optional calls
   are supported).  Application callers, on the other hand, may find
   that the SE calls are all they currently need for many environments.
   At some time in the future when they have need of non-repudiation or
   "directed receipts" types of services, they may consider using the EV
   calls (or the GP calls -- when these are supported -- if complex and
   sophisticated combinations of services are required).  To assist in
   this migration path, mechanism implementors are encouraged to support
   the full set of IDUP calls (i.e., the SE, EV, and GP calls) even
   though some calling applications will only use the SE calls in the
   short term.

2.3.2.2. IDUP_SE Parameter Bundles

   The concept of "parameter bundles" is used in the calls presented in
   the following subsections in order to simplify their presentation and
   clarify their intended purpose and use.  See Section 2.3.4.1 for a
   more complete description of parameter bundles.

   The following parameter bundles are used in the "SE" protection and
   unprotection sets of calls.

   o  Protect_Options PARAMETER BUNDLE
      o  protect_operation  INTEGER {
            sign_only              (0),
            encrypt_only           (1),
            sign_and_encrypt       (2),
            -- let mechanism choose order (and readability of signature)
            sign_then_encrypt_data (3),
            -- sign, then encrypt plaintext (leaving signature in clear)
            sign_then_encrypt_full (4),
            -- sign, then encrypt everything (including signature)
            encrypt_then_sign      (5),
            -- encrypt, then sign the ciphertext
            clear_sign_only        (6)
         } OPTIONAL,
      o  protect_oper_oid   OBJECT IDENTIFIER OPTIONAL,
         -- may be used in place of above parameter if OID is known
      o  sign_qop_alg      UNSIGNED INTEGER,
      o  sign_qop_algID    AlgorithmIdentifier, --overrides sign_qop_alg
      o  enc_qop_alg       UNSIGNED INTEGER,
      o  enc_qop_algID     AlgorithmIdentifier, --overrides enc_qop_alg
      o  idu_type_string    OCTET STRING,
         -- type of the IDU ("data", "e-mail doc", MIME type, etc.)
      o  pidu_type_string   OCTET STRING,
      o  mech_indep_encap_req BOOLEAN -- (see Appendix A)

   o  PIDU_Information PARAMETER BUNDLE
      o  protect_options    Protect_Options,
      o  originator_name    INTERNAL NAME,
      o  originator_role    Originator_Role, -- (see Section 2.3.4.1)
      o  protection_time    INTEGER,
   o  Bad_Target_Name PARAMETER BUNDLE,  -- same as in Section 2.3.3.2
      o  bad_targ_name     INTERNAL NAME,
      o  bad_targ_status   INTEGER,
         -- a status flag giving the reason for rejection of the name
         -- in bad_targ_name.  Specified reasons include:
         --  SYNTAX_INVALID        (0) the syntax of the name is invalid;
         --  NAME_UNRECOGNIZED     (1) the name is not recognized;
         --  NAME_AMBIGUOUS        (2) the name cannot be resolved;
         --  ACCESS_DENIED         (3) access to this target is denied;
         --  CERTIFICATE_NOT_FOUND (4) the encryption certificate of the
                                      target could not be found.

   o  Target_Info PARAMETER BUNDLE,      -- same as in Section 2.3.3.2
      o  targ_names        SET OF INTERNAL NAME,
      o  bad_targ_count    INTEGER,
      o  bad_target_names  SET OF Bad_Target_Name,

2.3.2.3. IDUP_SE major_status codes

   The following major_status return codes are defined for the "SE"
   calls in this section:

   o  GSS_S_COMPLETE
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
      -- returned (by any SE call) to indicate that there is more output
      -- data than can fit into the supplied buffers.  The application
      -- should save the returned data and call again to retrieve the
      -- remaining output.
   o  IDUP_S_MORE_PIDU_NEEDED
      -- indicates that more PIDU data is needed for the StartUnprotect
      -- operation (e.g., so that PIDU_Information or initial_idu_buffer
      -- may be returned).
   o  IDUP_S_INCONSISTENT_PARAMS
   o  GSS_S_CREDENTIALS_EXPIRED
   o  IDUP_S_NO_ENV
   o  GSS_S_BAD_QOP
   o  GSS_S_FAILURE

   If Target_Info is used as an input parameter (e.g., if an encryption
   operation is being performed), the following major_status return code
   is also defined:

   o  IDUP_S_BAD_TARG_INFO

   Note for this return code that if one or more of the targets in
   targ_names cannot be used as a valid recipient of the P-IDU, these
   names will be returned in bad_targ_names (with associated status
   codes in bad_targ_status).  As long as at least one of the targets
   can be used, however, this does not cause this call to fail (i.e.,
   the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the
   caller's choice to discontinue IDU protection if the target set which
   can be used is unsuitable for the caller's purposes.

2.3.2.4. IDUP_SE_SingleBuffer_Protect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  Protect_Options PARAMETER BUNDLE,
   o  Target_Info PARAMETER BUNDLE,
   o  idu_buffer OCTET STRING
   o  additional_protection BOOLEAN
      -- TRUE if idu_buffer is the output of a previous protection
      -- operation (i.e., if this is the second (or higher) in a
      -- series of SE/EV protection calls)

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  pidu_buffer OCTET STRING,
   o  sig_token OCTET STRING
      -- used if Protect_Options is clear_sign_only

   Using the security environment referenced by env_handle, encrypt
   and/or sign the supplied IDU.  If "clear signing" is performed, the
   signature will be returned in sig_token and pidu_buffer may be empty
   (depends on underlying mechanism).

2.3.2.5. IDUP_SE_SingleBuffer_Unprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  pidu_buffer OCTET STRING,
      -- may contain an IDU if sig_token is non-NULL (i.e., if
      -- clear_sign_only protection was applied)
   o  sig_token OCTET STRING

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  idu_buffer OCTET STRING,
      -- may be empty if clear_sign_only protection was applied (depends
      -- on underlying mechanism)
   o  PIDU_Information PARAMETER BUNDLE
   o  additional_unprotection BOOLEAN
      -- TRUE if idu_buffer should be input to another unprotection
      -- operation (i.e., if this should not be the last in a series
      -- of SE/EV unprotection calls)

   Using the security environment referenced by env_handle, decrypt
   and/or verify the supplied PIDU and return the contained IDU along
   with all available PIDU_Information.

2.3.2.6. IDUP_SE_MultiBuffer_StartProtect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  Protect_Options PARAMETER BUNDLE,
   o  Target_Info PARAMETER BUNDLE,
   o  additional_protection BOOLEAN, -- (see Section 2.3.2.4)
   o  idu_size INTEGER               -- (see Section 2.3.4.2)

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  initial_pidu_buffer OCTET STRING
      -- may be empty (depends on underlying mechanism)

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the process of signing and/or
   encrypting the IDU (which will be supplied in multiple buffers to the
   Process_Buffer call).

2.3.2.7. IDUP_SE_MultiBuffer_EndProtect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  final_pidu_buffer OCTET STRING,
   o  sig_token OCTET STRING
      -- used if Protect_Options was clear_sign_only

   Using the security environment referenced by env_handle, complete the
   protection processing on the data and place the computed output in
   final_pidu_buffer and/or sig_token. Successful application of
   IDUP_SE_MultiBuffer_EndProtect() does not guarantee that unprotection
   can necessarily be performed successfully when the P-IDU arrives at
   the target (for example, it may be damaged in transit).

2.3.2.8. IDUP_SE_MultiBuffer_StartUnprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  initial_pidu_buffer OCTET STRING,
   o  sign_qop_alg_in UNSIGNED INTEGER,
      -- used if Protect_Options was clear_sign_only (and calling
      -- application has prior knowledge of signing alg. applied);
      -- if NULL, then sig_token must be supplied
   o  sig_token OCTET STRING
      -- used if Protect_Options was clear_sign_only;
      -- if NULL, then sign_qop_alg_in must be supplied

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  PIDU_Information PARAMETER BUNDLE,
      -- returns all available information

   o  initial_idu_buffer OCTET STRING
      -- may be empty

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the process of decrypting
   and/or verifying the PIDU (which will be supplied in multiple buffers
   to the Process_Buffer call).

   The parameters sign_qop_alg_in and sig_token should not both be
   supplied (i.e., they should not both be non-NULL).  If they are both
   non-NULL, however, sig_token is taken to be authoritative since this
   is the token created at protection time and therefore is guaranteed
   to carry the information needed to unprotect.

2.3.2.9. IDUP_SE_MultiBuffer_EndUnprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  sig_token OCTET STRING  OPTIONAL
      -- used if Protect_Options was clear_sign_only and sig_token was
      -- not available when StartUnprotect was called

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  PIDU_Information PARAMETER BUNDLE,
      -- returns all available information
   o  final_idu_buffer OCTET STRING   -- may be empty
   o  additional_unprotection BOOLEAN -- (see Section 2.3.2.5)

   Using the security environment referenced by env_handle, complete the
   decryption and/or verification processing on the data and place any
   residual output in final_idu_buffer.

2.3.2.10. IDUP_SE_Process_Buffer call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  input_buffer OCTET STRING,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  output_buffer OCTET STRING
      -- may be zero length (depends on underlying mechanism and
      -- corresponding Start() call and Protect_Options value)

   Using the security environment referenced by env_handle, continue the
   processing on the data in input_buffer and, if it is available, put
   any resulting output data in output_buffer.  The application calls
   this routine over and over again with new buffers of data until it
   has processed all the data buffers of the IDU/PIDU. It then calls the
   appropriate End() call to complete the processing.

2.3.3.  The "EV" Calls

2.3.3.1. IDUP_EV Purpose

   The "EV" group of calls provides a simple, high-level interface to
   underlying IDUP mechanisms when application developers need to deal
   only with evidence but not with encryption or integrity services. It
   includes both the single-buffer and multiple-buffer IDU cases and can
   be used for the generation and verification of evidence tokens
   embodying several different types of evidences.

   The following list of evidence types is supported. This list is by no
   means exhaustive and it is anticipated that it may be extended in
   future versions of this specification.

      "Non-repudiation of Origin" prevents a message creator's false
      denial of creating and sending a message.

      "Non-repudiation of Creation" prevents a message creator's false
      denial of creating a message.

      "Non-repudiation of Sender" prevents a message creator's false
      denial of sending a message (that was not necessarily created by
      the sender).

      "Non-repudiation of Delivery" prevents a message recipient's false
      denial of having received and looked at the content of a message.

      "Non-repudiation of Receipt" prevents a message recipient's false
      denial of having received a message (whose content was not
      necessarily looked at by the recipient).

      "Non-repudiation of Approval" prevents a message recipient's false
      denial of having approved the content of a received message.

   An evidence is provided in the form of a evidence token. Two forms of
   evidence tokens are supported:

      o  Tokens including the associated data,

      o  Tokens without included data (but with a unique reference to
         the associated data).

   Evidence tokens may be freely distributed. Any possessor of an
   evidence token (and of the associated data, if not included in the
   token) can verify the evidence if it has the appropriate credentials
   which include the definition of security policies (i.e., keys alone
   do not permit the verification of evidence tokens). Any holder of an
   evidence token may store it (along with the associated data, if not
   included in the token) for later verification.

   Calls that are specific to the support of evidence include:

   * Generate_token, which generates a non-repudiation token using the
     current environment. The generated token may consist of:

      1 - an evidence token
      2 - a token containing a request for an evidence, which carries
          information describing which evidence type should be generated
          by the recipient(s) and sent back to some entities (that may
          or may not include the sender).
      3 - a token containing an evidence token which is an answer to an
          evidence that has been previously requested.
      4 - a token including both an evidence and a request for another
          evidence to be provided.

   * Verify_evidence, which verifies the evidence token using the
     current environment. This operation returns a major_status code
     which can be used to determine whether the evidence contained in a
     token is complete (i.e., can be successfully verified (perhaps
     years) later). If a token's evidence is not complete, the token can
     be passed to form_complete_pidu to complete it.

   Additional useful calls for evidence services include:
   * IDUP_Get_token_details (see Section 2.5.3);
   * IDUP_Form_Complete_PIDU (see Section 2.4.2).

2.3.3.2. IDUP_EV Parameters

   The following parameter bundles are used in the "EV" protection and
   unprotection sets of calls.

   o  Nr_Options PARAMETER BUNDLE
      o  evidence_type  INTEGER {
                   no_evidence         (0)
                   -- used when request-only token desired
                   proof_of_receipt    (1),
                   proof_of_delivery   (2),

                   proof_of_approval   (3),
                   proof_of_creation   (4),
                   proof_of_sender     (5),
                   proof_of_origin     (6)
         } OPTIONAL,
      o  evidence_type_oid  OBJECT IDENTIFIER OPTIONAL,
         -- may be used in place of above parameter if OID is known
      o  evidence_validity_duration     INTEGER,
         -- duration_in_minutes
         -- DURATION_HOUR  = 60;
         -- DURATION_DAY   = 1440;
         -- DURATION_WEEK  = 10080;
         -- DURATION_MONTH = 43200;// 30 days
         -- DURATION_YEAR  = 525600;//365 days
      o  mech_indep_encap_req BOOLEAN -- (see Appendix A)

   o  Originator_Information PARAMETER BUNDLE
      o  token_generator_name INTERNAL NAME,
         -- obtained from the credentials of the originator
         -- (e.g., from its public key certificate)
      o  token_generator_role Originator_Role OPTIONAL,
         -- (see Section 2.3.4.1)
      o  protection_time      INTEGER OPTIONAL

   o  Bad_Target_Name  PARAMETER BUNDLE  -- (see Section 2.3.2.2)
      o  bad_targ_name          INTERNAL NAME,
      o  bad_targ_status        INTEGER
         -- a status flag giving the reason for rejection of the
         -- name in bad_targ_name

   o  Target_Info PARAMETER BUNDLE       -- same as in Section 2.3.2.2
      o  targ_names           SET OF INTERNAL NAME,
      o  bad_targ_count       INTEGER,
      o  bad_target_names     SET OF Bad_Target_Name

   o  Request_Features PARAMETER BUNDLE
      o  requested_evidence_type  INTEGER {
                 no_evidence         (0), - used when no token desired
                 proof_of_receipt    (1),
                 proof_of_delivery   (2),
                 proof_of_approval   (3), },
      o  nr_req_policy                        OBJECT IDENTIFIER,
      o  evidence_from                        Target_Info,
      o  evidence_to                          Target_Info,
      o  include_received_token_in_evidence   BOOLEAN

   The following data_type is used in the "EV" protection calls.

   o  Nr_Operation  INTEGER {
            evidence_and_or_evidence_request  (1),
            returned_evidence                 (2) }

2.3.3.3. IDUP_EV major_status codes

   The following major_status return codes are defined for the "EV"
   calls in this section:

   o  GSS_S_COMPLETE
      -- indicates that the evidence is complete
   o  IDUP_S_INCOMPLETE
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
      -- returned (by any EV call) to indicate that there is more output
      -- data than can fit into the supplied buffers.  The application
      -- should save the returned data and call again to retrieve the
      -- remaining output.
   o  IDUP_S_INCONSISTENT_PARAMS
   o  GSS_S_CREDENTIALS_EXPIRED
   o  IDUP_S_NO_MATCH
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   If Target_Info is used as an input parameter (i.e., if an evidence is
   being requested ), the following major_status return code is also
   defined:

   o  IDUP_S_BAD_TARG_INFO

   Note for this return code that if one or more of the targets in
   targ_names cannot be used as a valid recipient of the P-IDU, these
   names will be returned in bad_targ_names (with associated status
   codes in bad_targ_status).  As long as at least one of the targets
   can be used, however, this does not cause this call to fail (i.e.,
   the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the
   caller's choice to discontinue IDU protection if the target set which
   can be used is unsuitable for the caller's purposes.

2.3.3.4. IDUP_EV_SingleBuffer_Generate call

   Inputs:
   o  env_handle                 ENVIRONMENT HANDLE,
   o  nr_operation               Nr_Operation,
   o  Nr_Options                 PARAMETER BUNDLE,
   o  idu_buffer                 OCTET STRING,
   o  form_complete_pidu         BOOLEAN,
      -- if TRUE the implementation will attempt to form a complete PIDU
   o  include_data_in_token      BOOLEAN,

      -- if TRUE, data provided in idu_buffer will be included in the
      -- generated token; if FALSE, the data will not be included
   o  Request_Features           PARAMETER BUNDLE
      -- the type of the evidence that is requested;
      -- policy under which the returned evidence should be generated;
      -- the recipients that are supposed to send back an evidence;
      -- the recipients that should receive the requested evidence;
      -- an indicator include_received_token_in_evidence:
      --   if TRUE, the evidence token incorporating the request will be
      --   included in the data for which recipients will generate
      --   evidence; if FALSE, evidence will be generated using only
      --   the data (and not the token incorporating the request).
   o  additional_protection BOOLEAN -- (see Section 2.3.2.4)

   Outputs:
   o  major_status               INTEGER,
   o  minor_status               INTEGER,
   o  token                      OCTET STRING,
   o  evidence_check             OCTET STRING,
      -- present only if an evidence is requested.  Consists of data to
      -- be used to verify the requested token(s) (if any) when they are
      -- received.

   Description:

   This operation generates a non-repudiation token associated with the
   data passed in an input buffer. Two kinds of operations can be
   performed (using the Nr_Operation parameter):

   a) generating a token that includes either an evidence only, or
      an evidence request only, or both an evidence and an evidence
      request;

   b) generating a response token for some recipients that includes an
      evidence generated as a response to a request (in this case the
      idu_buffer is used to enter the request token that was received).

   It is possible to request the generation of complete evidence. This
   may succeed or fail; if it fails, a subsequent call to
   Form_Complete_PIDU can be made.

2.3.3.5. IDUP_EV_SingleBuffer_Verify call

   Inputs:
   o  env_handle                     ENVIRONMENT HANDLE,
   o  token                          OCTET STRING,
   o  external_idu_buffer            OCTET STRING,
      -- if not present within the token

   o  evidence_check                 OCTET STRING,
      -- present only if the input token is a response to a previous
      -- request for evidence (this parameter is used to validate that
      -- evidence).

   Outputs:
   o  major_status                   INTEGER,
   o  minor_status                   INTEGER,
   o  Nr_Options                     PARAMETER BUNDLE,
   o  Originator_Information         PARAMETER BUNDLE,
   o  Request_Features               PARAMETER BUNDLE,
   o  trusted_time_stamping_time     INTEGER OPTIONAL,
      -- present for informational purposes only
   o  complete_evidence_before       INTEGER OPTIONAL,
      -- if the major status code that is returned is
      -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called
      -- with the same token before this time.
      --    This may be required, for example, in order to insure that
      --    the time skew between the evidence generation time and
      --    the trusted time service's countersignature on the evidence
      --    falls within the interval allowed by the current NR policy.
   o  complete_evidence_after        INTEGER OPTIONAL,
      -- if the major status code that is returned is
      -- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called
      -- with the same token after this time.
      --    This may be required, for example, to insure that all
      --    authorities involved in generating the evidence have passed
      --    the last time at which the current NR policy allows them to
      --    repudiate their keys.
   o  encapsulated_idu_buffer         OCTET STRING
      -- if the IDU was present within the token
   o  additional_unprotection BOOLEAN -- (see Section 2.3.2.5)

   Description:

   Verifies the validity and discloses the content of a nr_token.

   If the token containing the evidence to be verified was provided to
   the calling application by a partner responding to the calling
   application's request, then the calling application must pass the
   evidence check it received when it generated the request as a
   parameter along with the token it received from the partner.

   Output indicators are provided which give guidance about the time or
   times at which form_complete_pidu should be called; see the parameter
   descriptions for explanations of these indicators and their use. Note
   that the time specified by complete_evidence_before may be earlier
   than that specified by complete_evidence_after; in this case it will

   be necessary to call form_complete_pidu twice.

   Because keys can be revoked or declared compromised, the return from
   verify_evidence cannot in all cases be a definitive "valid" or
   "invalid"; sometimes "conditionally valid" may be returned, depending
   upon the policy in use. IDUP_S_INCOMPLETE will be returned, for
   example, if:

    - the interval during which the generator of the evidence may
      permissibly declare his key invalid has not yet expired (and
      therefore it is possible that the evidence may be declared invalid
      in the future), or

    - trusted time is required for verification, and the time obtained
      from the token is not trusted.

2.3.3.6. IDUP_EV_MultiBuffer_StartGenerate call

   Inputs:
   o  env_handle                 ENVIRONMENT HANDLE,
   o  nr_operation               Nr_Operation,
   o  Nr_Options                 PARAMETER BUNDLE,
   o  form_complete_pidu         BOOLEAN,
   o  include_data_in_token      BOOLEAN,
   o  idu_size                   INTEGER, -- (see Section 2.3.4.2)
   o  Request_Features           PARAMETER BUNDLE
   o  additional_protection BOOLEAN -- (see Section 2.3.2.4)

   Outputs:
   o  major_status               INTEGER,
   o  minor_status               INTEGER,
   o  initial_pidu_buffer        OCTET STRING
      -- may be empty (depends on underlying mechanism)

   Description:

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the generation of a token. The
   IDU will be supplied in multiple buffers to the
   IDUP_EV_Process_Buffer call). Two kinds of operations can be
   performed (using the Nr_Operation parameter) :

     a) generating a token that includes either an evidence only, or
        an evidence request only, or both an evidence and an evidence
        request.

     b) generating a return token for some recipients that includes an
        evidence generated as a response to a request. In that case the
        received token will be passed into the subsequent
        IDUP_EV_Process_Buffer calls. The boolean include_data_in_token
        is ignored as the output will always be contained in a single
        token. The Request_Features are ignored in that case at this
        time in order to keep things simple and to avoid the piggy-
        backing that is theoretically possible.

   It is possible to request the generation of complete evidence. This
   may succeed or fail; if it fails, a subsequent call to
   Form_Complete_PIDU can be made.

2.3.3.7. IDUP_EV_MultiBuffer_EndGenerate call

   Inputs:
   o  env_handle                 ENVIRONMENT HANDLE

   Outputs:
   o  major_status               INTEGER,
   o  minor_status               INTEGER,
   o  final_pidu                 OCTET STRING,
   o  token                      OCTET STRING,
   o  evidence_check             OCTET STRING
      -- present only if an evidence is requested.

   Description:

   Using the security environment referenced by env_handle, provide the
   requested token or the final P-IDU. A token will be generated if
   encapsulation was not requested; otherwise, the final P-IDU is
   provided.

2.3.3.8. IDUP_EV_MultiBuffer_StartVerify call

   Inputs:
   o  env_handle                     ENVIRONMENT HANDLE,
   o  token                          OCTET STRING,
   o  evidence_check                 OCTET STRING,
      -- present only if an evidence has been previously requested.

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER

   Description:

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the process of verifying the
   token.  The P-IDU will be supplied in multiple buffers to the
   IDUP_EV_Process_Buffer call.

2.3.3.9. IDUP_EV_MultiBuffer_EndVerify call

   Input:
   o  env_handle                     ENVIRONMENT HANDLE

   Outputs:
   o  major_status                   INTEGER,
   o  minor_status                   INTEGER,
   o  Nr_Options                     PARAMETER BUNDLE,
   o  Originator_Information         PARAMETER BUNDLE,
   o  Request_Features               PARAMETER BUNDLE,
   o  trusted_time_stamping_time     INTEGER OPTIONAL,
   o  complete_evidence_before       INTEGER OPTIONAL,
   o  complete_evidence_after        INTEGER OPTIONAL,
   o  idu_buffer                     OCTET STRING
      -- if the IDU was present within the token
   o  additional_unprotection BOOLEAN -- (see Section 2.3.2.5)

   Description:

   Using the security environment referenced by env_handle, complete the
   verification processing on the data and provide verified output
   parameters to the caller when the major status code is either:

   o GSS_S_COMPLETE or
   o IDUP_S_INCOMPLETE

2.3.3.10. IDUP_EV_Process_Buffer call

   Inputs:
   o  env_handle         ENVIRONMENT HANDLE,
   o  input_buffer       OCTET STRING

   Outputs:
   o  major_status       INTEGER,
   o  minor_status       INTEGER,
   o  output_buffer      OCTET STRING
      -- may be zero length (depends on underlying mechanism and
      -- corresponding Generate () call and options
      -- (e.g., data_included_in_token)

   Description:

   Using the security environment referenced by env_handle, continue the
   processing on the data in input_buffer and, if it is available, put
   any resulting output data in output_buffer. The application calls
   this routine over and over again with new buffers of data until it
   has processed all the data buffers of the IDU/PIDU. It then calls the
   appropriate End() call to complete the processing.

2.3.4. The "GP" Calls

   The "GP" group of calls provides a powerful interface to flexible and
   sophisticated combinations of protection and unprotection services.
   This power and flexibility, however, necessitates a more complex
   interface than either the SE or the EV calls. Furthermore, such
   combinations of services are not needed in many of the security
   mechanisms in common use today (although this is likely to change as
   time goes on).  The GP calls are therefore specified to be OPTIONAL
   and need not be supported by IDUP-conformant implementations.  Note,
   however, that the structure of IDUP tokens should be such that the
   SE/EV and GP calls may be used interchangably by the receiver.

2.3.4.1. Parameter Bundles

   The concept of "parameter bundles" is used in the calls presented in
   the following subsections in order to simplify their presentation and
   clarify their intended purpose and use (note that specific language
   bindings may or may not use parameter bundles for its actual calling
   conventions).  A parameter bundle is simply a set of closely-related
   parameters of a call which are either all used by / available to the
   calling application or all not used by / unavailable to the calling
   application.  These parameters may be all input parameters, all
   output parameters, or any combination of the two.

   An example use envisioned for parameter bundles in a language such as
   C would be as a structure, where individual parameters in the bundle
   are structure members.  The calling application wishing to use a
   particular bundle would then allocate the appropriate structure
   variable, assign the desired input values to the appropriate members,
   and pass the address of the structure as the bundle "parameter".  On
   output, the values of the appropriate output members may be read.  An
   application not wishing to use a particular bundle (or one which is
   satisfied with default values for all input parameters of the bundle
   and which doesn't care about output values), can pass NULL as the
   bundle "parameter".  From the mechanism implementor's perspective, if
   a parameter bundle is not supported (for example, if it represents a
   security service which is not supported by the implementation), then
   any non-NULL value passed as the bundle parameter will generate an

   error status return code.

   [Note that the parameter bundles given below, except where explicitly
   referenced by the SE and EV calls, are specific to the (optional) GP
   calls.  Thus, these bundles need not be supported by IDUP-conformant
   implementations if the GP calls are not supported.]

   The following parameter bundles are used in the subsequent protection
   and unprotection sets of calls.  A parameter preceded by "(I)" is an
   input parameter; one preceded by "(O)" is an output parameter; one
   preceded by neither is an input if the bundle itself is an input and
   is an output if the bundle itself is an output; one preceded by "(X)"
   is the opposite:  an output if the bundle itself is an input and an
   input if the bundle itself is an output.

      o Mech_Specific_Info PARAMETER BUNDLE
        -- actual parameters included in this bundle are defined by (and
        -- specific to) the underlying mechanism

      o Sensitivity PARAMETER BUNDLE,
        -- actual parameters included in this bundle are defined by (and
        -- specific to) the underlying mechanism, but may include
        -- codified values for "Unclassified", "Secret", "Top Secret",
        -- and so on

      o Service_Creation_Info PARAMETER BUNDLE
        -- actual parameters included in this bundle are defined by (and
        -- specific to) the underlying mechanism, but it is mandatory
        -- that they include at least service_id and Quality

      o Service_Verification_Info PARAMETER BUNDLE
        -- actual parameters included in this bundle are defined by (and
        -- specific to) the underlying mechanism, but it is mandatory
        -- that they include at least service_id and Quality

      o  Quality PARAMETER BUNDLE
         o  qop_algs  UNSIGNED INTEGER,
         o  qop_algID AlgorithmIdentifier, --overrides qop_algs
         o  validity  UNSIGNED INTEGER,
            -- protection guaranteed to be valid until time specified
         o  policy_id OBJECT IDENTIFIER,
            -- security policy under which protection is/was carried out
         o  allow_policy_mapping BOOLEAN,
            -- determines whether mapping between policy IDs is allowed
         o  actual_policy_time INTEGER
            -- time at which the above policy rules came into effect

      o  Idu_Information PARAMETER BUNDLE,
         o  idu_type_oid OBJECT IDENTIFIER,
         o  idu_type_string OCTET STRING,
         o  idu_title OCTET STRING,
         o  idu_sensitivity Sensitivity,
         o  pidu_type_oid OBJECT IDENTIFIER,
         o  pidu_type_string OCTET STRING,
         o  pidu_title OCTET STRING,
         o  pidu_sensitivity Sensitivity,

      o  Prot_Information PARAMETER BUNDLE,
         o  originator_name INTERNAL NAME,
         o  originator_role Originator_Role,
         o  idu_information Idu_Information,
         o  protection_time INTEGER,

      o  Originator_Role PARAMETER BUNDLE, -- role in organization
         o  domain_name                 INTERNAL NAME OPTIONAL,
         o  role                        PRINTABLE STRING,
         o  role_info_is_authenticated  BOOLEAN
            -- TRUE if info. is authenticated (e.g., inside a cert.)

      o  Special_Conditions PARAMETER BUNDLE,
         o  prot_oper_id INTEGER,
         o  form_complete_pidu BOOLEAN,
            -- input to protection operations for evidence generation
         o  pidu_in_solic_service BOOLEAN,
            -- in protection operations, used as input for service
            -- solicitation to request that receiver include the
            -- received PIDU when generating the response.  In unprot.
            -- operations, used as output to inform receiver that PIDU
            -- should be included when generating the response.
         o  use_trusted_time BOOLEAN,
         o  use_untrusted_time BOOLEAN,
         o  mech_indep_encap_req BOOLEAN -- (see Appendix A)

      o  Bad_Target_Name PARAMETER BUNDLE,
         o  (O) bad_targ_name INTERNAL NAME,
         o  (O) bad_targ_status INTEGER,
                -- a status flag giving the reason for rejection of
                -- the name in bad_targ_name. Specified reasons include:
                --    SYNTAX_INVALID        (0)
                --       the syntax of the name is invalid;
                --    NAME_UNRECOGNIZED     (1)
                --       the name is not recognized;
                --    NAME_AMBIGUOUS        (2)
                --       the name cannot be resolved;
                --    ACCESS_DENIED         (3)

                --       access to this target is denied;
                --    CERTIFICATE_NOT_FOUND (4)
                --       the encryption certificate of the target could
                --       not be found.

      o  Target_Info PARAMETER BUNDLE,
         o      targ_names       SET OF INTERNAL NAME,
         o  (O) bad_targ_count   INTEGER,
         o  (O) bad_target_names SET OF Bad_Target_Name,

      o  General_Service_Data PARAMETER BUNDLE,
         o      target_info Target_Info,
         o  (X) unencapsulated_token OCTET STRING,
                -- zero length if encapsulation_request is TRUE
         o  (O) minor_status INTEGER,

   Three types of protection services are defined in IDUP.  These are:

      1. perform unsolicited service (i.e., act on a locally-generated
         service request),
      2. perform solicited service (i.e., act on a remotely-generated
         service request), and
      3. perform service solicitation (i.e., send a service request to
         the remote end).

   As an originator, applying data confidentiality with data integrity,
   or data origin authentication with data integrity, or proof of origin
   evidence is an example of service type 1.  As a target, creating a
   proof of delivery (i.e., receipt) evidence token as the result of a
   request received from the originator is an example of service type 2.
   Finally, as an originator, submitting a request that one or more
   targets return a receipt for the data sent is an example of service
   type 3.

   The first four parameters in the Prot_Service parameter bundle
   pertain to all service types; the fifth parameter is used if and only
   if service type 2 is desired; parameters 6-8 are used if and only if
   service type 3 is desired.

      o  Prot_Service PARAMETER BUNDLE
         o  (I) prot_service_type INTEGER,
         o  (I) service_id OBJECT IDENTIFIER,
         o  (I) quality Quality, -- NULL specifies default Quality
         o  (I) general_service_data General_Service_Data,
         o  (I) service_creation_info Service_Creation_Info,
         o  (I) service_to SET OF INTERNAL NAME,
         o  (O) service_verification_info Service_Verification_Info,
         o  (O) service_verification_info_id INTEGER,

   Also, three types of unprotection services are defined.  These are:

      1. receive unsolicited service (i.e., process unrequested
         remotely-generated service),
      2. receive solicited service (i.e., process remotely-generated
         response to locally-generated request), and
      3. receive service solicitation (i.e., process req. from rem. end)

   As a target, unprotecting an encrypted message, or verifying the
   originator's proof of origin is an example of service type 1.  As an
   originator, verifying a proof of delivery which you requested from a
   target is an example of service type 2.  Finally, as a target,
   receiving a request from an originator for a proof of delivery is an
   example of service type 3.

   The first four parameters in the Unprot_Service parameter bundle
   pertain to all service types; parameters 5-6 are used if and only if
   service type 2 is required; parameters 7-8 are used only if service
   type 3 is required.

      o  Unprot_Service PARAMETER BUNDLE
         o  (O) unprot_service_type INTEGER,
         o  (O) service_id OBJECT IDENTIFIER,
         o  (O) quality Quality,
                -- actual Quality specified (never NULL)
         o  (O) general_service_data General_Service_Data,
         o  (O) service_verification_info_id INTEGER,
         o  (I) service_verification_info Service_Verification_Info,
         o  (O) service_to SET OF INTERNAL NAME,
         o  (O) service_creation_info Service_Creation_Info,

2.3.4.2. IDUP_Start_Protect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  Mech_Specific_Info PARAMETER BUNDLE,
      -- NULL selects the mechanism-defined default values
   o  Idu_Information PARAMETER BUNDLE,
   o  Special_Conditions PARAMETER BUNDLE,
   o  encapsulation_request BOOLEAN,
   o  single_idu_buffer OCTET STRING,
      -- non-zero length for this buffer means that Protect/End_Protect
      -- won't be called (i.e., entire IDU is contained in this buffer)
   o  idu_size INTEGER,
      -- size (in bytes) of the IDU to be protected;
      -- may be "-1" signifying "UNKNOWN" (note that some mechanisms
      -- may not support encapsulation in such a case)
   o  Target_Info PARAMETER BUNDLE,

   o  Services_to_Perform SET OF Prot_Service,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  midu_buffer OCTET STRING,
      -- zero length if encapsulation_request is TRUE;
      -- may be zero length otherwise (depends on underlying mechanism)
   o  pidu_buffer OCTET STRING,
      -- zero length if encapsulation_request is FALSE;
      -- may be zero length otherwise (depends on underlying mechanism)

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- the protection process can begin (or has completed, if
      -- single_idu_buffer has non-zero length).
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
   o  GSS_S_CREDENTIALS_EXPIRED
   o  IDUP_S_NO_ENV
   o  IDUP_S_ENCAPSULATION_UNAVAIL
   o  IDUP_S_SERVICE_UNAVAIL
   o  IDUP_S_REQ_TIME_SERVICE_UNAVAIL
   o  IDUP_S_UNKNOWN_OPER_ID
   o  GSS_S_BAD_QOP
   o  IDUP_S_BAD_TARG_INFO
   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the process of protecting the
   IDU buffers.  The caller requests specific protection services by
   supplying the appropriate Prot_Service parameter bundles in
   Services_to_Perform.  Each service is able to return a minor status
   code to the calling application, if necessary.

   The calling application, knowing the size of the IDU it wishes to
   protect and the buffer size which it has available to it, can choose
   to input the entire IDU in a single buffer and omit the subsequent
   IDUP_Protect() and IDUP_End_Protect() calls.  Furthermore, the
   application can request that the resulting M-IDU be encapsulated in
   the token -- so that the token contains the entire P-IDU -- rather
   than having it be returned separately in midu_buffer.  Encapsulation,
   however, may not be supported by all underlying mechanisms or
   implementations; if this is the case, the
   IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and
   M-IDU will be returned in midu_buffer.

   For those mechanisms which allow or require multiple stages of
   processing, each producing a different aspect of protection for the
   IDU, the operation identifier prot_oper_id is used to specify which
   stage is currently being requested by the application.  An example
   where this would be useful is a mechanism which implements the signed
   Message Security Protocol [MSP].  As another example, a mechanism may
   choose to do a digital signature in two stages:  one for the hashing
   of the message and another for the signature on the hash.  The
   calling application would therefore use the protection set of calls
   on the IDU in stage 1 and then use the protection set of calls on the
   token (from stage 1) in stage 2.

   Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where
   "n" is the number of stages as defined by the mechanism (typically 1
   or 2)).  The calling application uses this parameter to indicate to
   the underlying mechanism whether it wishes to do stage 1 of
   protection / unprotection processing, or stage 2, and so on. Portable
   applications may pass "0" to let the mechanism choose the stage (note
   that mechanism implementers may still iterate when prot_oper_id = 0
   (e.g., use output as next input, et cetera).

   If one or more of the targets in targ_names cannot be used as a valid
   recipient of the P-IDU, these names will be returned in
   bad_targ_names (with associated status codes in bad_targ_status).  As
   long as at least one of the targets can be used, this does not cause
   this call to fail; it is the caller's choice to discontinue IDU
   protection if the target set which can be used is unsuitable for the
   caller's purposes.  Note that each Prot_Service parameter bundle can
   also input a list of targ_names; this is used if a separate list is
   to be used for that service only (the general list of targets is to
   be used for all services unless overridden in this way).

2.3.4.3. IDUP_Protect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  input_buffer OCTET STRING,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  output_buffer OCTET STRING
      -- may be zero length if encapsulation_request was set to TRUE in
      -- IDUP_Start_Protect() (depends on underlying mechanism)

   Return major_status codes:
   o  GSS_S_COMPLETE
   o  IDUP_S_NO_ENV

   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, continue the
   protection processing on the data in input_buffer and, if the
   underlying mechanism defines this, put any resulting P-IDU/M-IDU data
   in output_buffer.  The application calls this routine over and over
   again with new buffers of data until it has protected all the data
   buffers of the IDU.  It then calls IDUP_End_Protect() to complete the
   protection processing.

2.3.4.4. IDUP_End_Protect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  Services_to_Perform SET OF Prot_Service,
   o  final_midu_buffer OCTET STRING,
      -- zero length if encapsulation_request was set to TRUE in
      -- IDUP_Start_Protect(), in which case pidu is used
   o  final_pidu_buffer OCTET STRING,
      -- zero length if encapsulation_request was set to FALSE in
      -- IDUP_Start_Protect(), in which case token and midu are used

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- protection has successfully completed and the resulting P-IDU
      -- is ready for transfer.  If defined by the underlying mechanism,
      -- final_midu_buffer will contain any residual M-IDU data.
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, complete the
   protection processing on the data and place the computed output in
   final_pidu_buffer (or final_midu_buffer and the unencapsulated_token
   parameter for each Prot_Service).  If a service was requested from
   one or more targets in Start_Protect() - and if this is supported by
   the underlying mechanism - Service_Verification_Info will hold
   whatever data is necessary for the mechanism to verify a service
   returned by a target (unprotector) of the P-IDU.  Successful
   application of IDUP_End_Protect() does not guarantee that the
   corresponding unprotection set of calls can necessarily be performed
   successfully when the P-IDU arrives at the target (for example, it
   may be damaged in transit).

2.3.4.5. IDUP_Start_Unprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  Mech_Specific_Info PARAMETER BUNDLE,
      -- NULL selects the mechanism-defined default values
   o  single_pidu_buffer OCTET STRING,
      -- non-zero length for this buffer means that IDUP_Unprotect() and
      -- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU
      -- (if encapsulation is used) or M-IDU (if encap. is not used)
      -- is contained in this buffer)
   o  partial_pidu_buffer OCTET STRING,
      -- may be an arbitrary-sized piece of the full pidu (if the
      -- application's buffer isn't large enough to hold entire pidu).
      -- Used if pidu_buffer 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,
   o  Special_Conditions PARAMETER BUNDLE,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  Services_to_Receive SET OF Unprot_Service,
   o  Prot_Information PARAMETER BUNDLE,
   o  single_idu_buffer OCTET STRING,
      -- if this buffer has non-zero length, then service processing has
      -- been completed on the data in single_pidu_buffer
   o  initial_idu_buffer OCTET STRING,
      -- holds any data from partial(final)_pidu_buffer which has been
      -- unprotected; remaining data will be returned by Unprotect and
      -- End_Unprotect as they are called with successive buffers of
      -- pidu
   o  Service_Verification_Info PARAMETER BUNDLE,
      -- used only if target is on "service_to" list in Unprot_Service
   o  service_verification_info_id INTEGER,
      -- used only if target is on "service_to" list in Unprot_Service

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- unprotection processing can begin (or has completed, if
      -- single_idu_buffer has non-zero length).
   o  IDUP_S_INCOMPLETE
      -- used only if single_idu_buffer has non-zero length.
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
   o  IDUP_S_MORE_PIDU_NEEDED
   o  GSS_S_DEFECTIVE_TOKEN
   o  IDUP_S_INAPPROPRIATE_CRED
   o  IDUP_S_INCONSISTENT_PARAMS
   o  IDUP_S_DEFECTIVE_VERIF
   o  IDUP_S_NO_MATCH
   o  IDUP_S_SERVICE_UNAVAIL
   o  IDUP_S_REQ_TIME_SERVICE_UNAVAIL
   o  IDUP_S_SERV_VERIF_INFO_NEEDED
   o  GSS_S_CREDENTIALS_EXPIRED
   o  IDUP_S_NO_ENV
   o  IDUP_S_UNKNOWN_OPER_ID
   o  GSS_S_BAD_QOP
      -- the qop_algs value specified in P-IDU for at least one of the
      -- services is unavailable in the local mechanism, so processing
      -- cannot continue.
   o  GSS_S_BAD_MIC
   o  IDUP_S_BAD_DOA_KEY
   o  IDUP_S_BAD_KE_KEY
   o  IDUP_S_BAD_ENC_IDU
   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, initialize
   the data structures required to begin the process of unprotecting a
   P-IDU.  The caller will be alerted as to which services were applied
   to the P-IDU in the returned Services_to_Receive set of parameters.

   If encapsulation was not used by the originator, it is the receiving
   application's responsibility to separate the received P-IDU into a
   M-IDU and one or more unencapsulated_token buffers (the latter being
   input in separate Unprot_Service bundles in the Services_to_Receive
   parameter).  These unencapsulated_token buffers should be input
   before the M-IDU (i.e., in IDUP_Start_Unprotect) or after the M-IDU
   (i.e., in IDUP_End_Unprotect) as appropriate; this order may be
   dictated, for example, by their placement in the in-coming message.

   If unprotection will be applied more than once to a given P-IDU, it
   is the responsibility of the calling application to remember if a
   service solicitation has been responded to previously (i.e., if the
   requested service has already been generated / sent for that P-IDU)
   and thus ignore subsequent solicitations on unprotect.

   The time flags indicate whether to consult trusted, untrusted, or no
   time (if both flags are FALSE) during the unprotection operation.  If
   the current time is not to be checked, then unprotection may be
   successful even if the protector's key has expired since the P-IDU
   was generated (that is, if the Validity period -- as specified in the
   Quality parameter bundle -- has expired).

   If the underlying mechanism supports it and if this information is
   contained in the P-IDU, information regarding the originator (that
   is, the entity which used the protection set of calls to generate
   this P-IDU) is returned in the Prot_Information parameter bundle.

2.3.4.6. IDUP_Unprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,
   o  input_buffer OCTET STRING

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  output_buffer OCTET STRING

   Return major_status codes:
   o  GSS_S_COMPLETE
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, continue the
   unprotection processing on the data in input_buffer, putting any
   resulting IDU data in output_buffer (if required).

2.3.4.7. IDUP_End_Unprotect call

   Inputs:
   o  env_handle ENVIRONMENT HANDLE,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  Prot_Information PARAMETER BUNDLE,
   o  Services_to_Receive SET OF Unprot_Service,
   o  final_idu_buffer OCTET STRING,
   o  Service_Verification_Info PARAMETER BUNDLE,
      -- used only if target is on "service_to" list in Unprot_Service
   o  service_verification_info_id INTEGER,
      -- used only if target is on "service_to" list in Unprot_Service

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- residual IDU data will be returned in final_idu_buffer.
   o  IDUP_S_INCOMPLETE
   o  IDUP_S_MORE_OUTBUFFER_NEEDED
   o  GSS_S_BAD_MIC
   o  IDUP_S_BAD_DOA_KEY
   o  IDUP_S_BAD_KE_KEY
   o  IDUP_S_BAD_ENC_IDU
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   Using the security environment referenced by env_handle, complete the
   unprotection processing on the data and return the appropriate status
   code.  If there is any residual IDU data it will be returned in
   final_idu_buffer.

   If the IDUP_S_INCOMPLETE major status value is returned, all output
   parameters are conditionally valid; the unprotection set of functions
   will have to be called again (perhaps with a complete P-IDU, as
   produced by IDUP_Form_Complete_PIDU) in order to get valid values for
   all parameters.  "Conditional validity" may arise, for example, if
   all relevant certificates verify correctly, but it is not yet past
   the time up to which the current policy allows the authorities
   involved to repudiate their keys.

   If the underlying mechanism supports it and if this information is
   contained in the token, information regarding the originator (that
   is, the entity which used the protection set of calls to generate
   this token) is returned in the Prot_Information parameter bundle.
   This information may or may not be omitted if it was returned by the
   IDUP_Start_Unprotect() call.

   Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the
   concept of error tokens transferred between sender and recipient
   since the protection and unprotection of an IDU may be separated by
   an indefinite amount of time and may or may not be performed by the
   same entity.