Tech-invite3GPPspaceIETFspace
96959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 2479

Independent Data Unit Protection Generic Security Service Application Program Interface (IDUP-GSS-API)

Pages: 70
Informational
Part 1 of 3 – Pages 1 to 19
None   None   Next

Top   ToC   RFC2479 - Page 1
Network Working Group                                           C. Adams
Request for Comments: 2479                          Entrust Technologies
Category: Informational                                    December 1998


       Independent Data Unit Protection Generic Security Service
              Application Program Interface (IDUP-GSS-API)

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

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

ABSTRACT

   The IDUP-GSS-API extends the GSS-API [RFC-2078] for applications
   requiring protection of a generic data unit (such as a file or
   message) in a way which is independent of the protection of any other
   data unit and independent of any concurrent contact with designated
   "receivers" of the data unit.  Thus, it is suitable for applications
   such as secure electronic mail where data needs to be protected
   without any on-line connection with the intended recipient(s) of that
   data.  The protection offered by IDUP includes services such as data
   origin authentication with data integrity, data confidentiality with
   data integrity, and support for non-repudiation services.  Subsequent
   to being protected, the data unit can be transferred to the
   recipient(s) - or to an archive - perhaps to be processed
   ("unprotected") only days or years later.

   Throughout the remainder of this document, the "unit" of data
   described in the above paragraph will be referred to as an IDU
   (Independent Data Unit).  The IDU can be of any size (the application
   may, if it wishes, split the IDU into pieces and have the protection
   computed a piece at a time, but the resulting protection token
   applies to the entire IDU).  However, the primary characteristic of
   an IDU is that it represents a stand-alone unit of data whose
   protection is entirely independent of any other unit of data.  If an
   application protects several IDUs and sends them all to a single
   receiver, the IDUs may be unprotected by that receiver in any order
   over any time span; no logical connection of any kind is implied by
   the protection process itself.
Top   ToC   RFC2479 - Page 2
   As with RFC-2078, this IDUP-GSS-API definition provides security
   services to callers in a generic fashion, supportable with a range of
   underlying mechanisms and technologies and hence allowing source-
   level portability of applications to different environments. This
   specification defines IDUP-GSS-API services and primitives at a level
   independent of underlying mechanism and programming language
   environment, and is to be complemented by other, related
   specifications:

      - documents defining specific parameter bindings for particular
        language environments;
      - documents defining token formats, protocols, and procedures to
        be implemented in order to realize IDUP-GSS-API services atop
        particular security mechanisms.

TABLE OF CONTENTS

   1.  IDUP-GSS-API Characteristics and Concepts ..................    3
   1.1.  IDUP-GSS-API Constructs ..................................    5
   1.1.1.  Credentials ............................................    5
   1.1.2.  Tokens .................................................    5
   1.1.3.  Security Environment ...................................    6
   1.1.4.  Mechanism Types ........................................    6
   1.1.5.  Naming .................................................    6
   1.1.6.  Channel Bindings .......................................    6
   1.2.  IDUP-GSS-API Features and Issues .........................    6
   1.2.1.  Status Reporting .......................................    6
   1.2.2.  Per-IDU Security Service Availability ..................    9
   1.2.3.  Per-IDU Replay Detection and Sequencing ................    9
   1.2.4.  Quality of Protection ..................................    9
   1.2.5.  The Provision of Time ..................................   12
   2.  Interface Descriptions .....................................   13
   2.1.  Credential management calls ..............................   14
   2.1.1.  Relationship to GSS-API ................................   14
   2.2.  Environment-level calls ..................................   15
   2.2.1.  Relationship to GSS-API ................................   15
   2.2.2.  IDUP_Establish_Env call ................................   15
   2.2.3.  IDUP_Abolish_Env call ..................................   19
   2.2.4.  IDUP_Inquire_Env call ..................................   19
   2.3.  Per-IDU protection/unprotection calls ....................   20
   2.3.1.  Relationship to GSS-API ................................   20
   2.3.2.  The "SE" Calls .........................................   21
   2.3.3.  The "EV" Calls .........................................   27
   2.3.4.  The "GP" Calls .........................................   36
   2.4.  Special-Purpose calls ....................................   47
   2.4.1.  Relationship to GSS-API ................................   47
   2.4.2.  IDUP_Form_Complete_PIDU ................................   48
   2.5.  Support calls ............................................   49
Top   ToC   RFC2479 - Page 3
   2.5.1.  Relationship to GSS-API ................................   49
   2.5.2.  IDUP_Acquire_Cred_With_Auth ............................   49
   2.5.3.  IDUP_Get_Token_Details .................................   50
   2.5.4.  IDUP_Get_Policy_Info ...................................   53
   2.5.5.  IDUP_Cancel_Multibuffer_Op .............................   55
   3.  Related Activities .........................................   55
   4.  Acknowledgments ............................................   56
   5.  Security Considerations ....................................   56
   6.  References       ...........................................   56
   7.  Author's Address ...........................................   56
   Appendix A Mechanism-Independent Token Format ..................   57
   Appendix B Examples of IDUP Use ................................   58
   Full Copyright Statement .......................................   70

1. IDUP-GSS-API Characteristics and Concepts

   The paradigm within which IDUP-GSS-API operates is as follows.  An
   IDUP-GSS-API caller is any application that works with IDUs, calling
   on IDUP-GSS-API in order to protect its IDUs with services such as
   data origin authentication with integrity (DOA), confidentiality with
   integrity (CONF), and/or support for non-repudiation (e.g., evidence
   generation, where "evidence" is information that either by itself, or
   when used in conjunction with other information, is used to establish
   proof about an event or action (note:  the evidence itself does not
   necessarily prove truth or existence of something, but contributes to
   establish proof) -- see [ISO/IEC] for fuller discussion regarding
   evidence and its role in various types of non-repudiation).  An
   IDUP-GSS-API caller passes an IDU to, and accepts a token from, its
   local IDUP-GSS-API implementation, transferring the resulting
   protected IDU (P-IDU) to a peer or to any storage medium.  When a P-
   IDU is to be "unprotected", it is passed to an IDUP-GSS-API
   implementation for processing.  The security services available
   through IDUP-GSS-API in this fashion are implementable over a range
   of underlying mechanisms based on secret-key and/or public-key
   cryptographic technologies.

   During the protection operation, the input IDU buffers may be
   modified (for example, the data may be encrypted or encoded in some
   way) or may remain unchanged.  In any case, the result is termed a
   "M-IDU" (Modified IDU) in order to distinguish it from the original
   IDU.  Depending on the desire of the calling application and the
   capabilities of the underlying IDUP mechanism, the output produced by
   the protection processing may or may not encapsulate the M-IDU. Thus,
   the P-IDU may be the contents of a single output parameter (if
   encapsulation is done) or may be the logical concatenation of an
   unencapsulated token parameter and a M-IDU parameter (if
   encapsulation is not done).  In the latter case, the protecting
   application may choose whatever method it wishes to concatenate or
Top   ToC   RFC2479 - Page 4
   combine the unencapsulated token and the M-IDU into a P-IDU, provided
   the unprotecting application knows how to de-couple the P-IDU back
   into its component parts prior to calling the IDUP unprotection set
   of functions.

   It is expected that any output buffer returned by IDUP (i.e., P-IDU
   or portion thereof) is ready for immediate transmission to the
   intended receiver(s) by the calling application, if this is desired.
   In other words, an application wishing to transmit data buffers as
   they appear from IDUP should not be unduly restricted from doing so
   by the underlying mechanism.

   The IDUP-GSS-API separates the operation of initializing a security
   environment (the IDUP_Establish_Env() call) from the operations of
   providing per-IDU protection, for IDUs subsequently protected in
   conjunction with that environment. Per-IDU protection and
   unprotection calls provide DOA, CONF, evidence, and other services,
   as requested by the calling application and as supported by the
   underlying mechanism.

   The following paragraphs provide an example illustrating the
   dataflows involved in the use of the IDUP-GSS-API by the sender and
   receiver of a P-IDU in a mechanism-independent fashion.  The example
   assumes that credential acquisition has already been completed by
   both sides.  Furthermore, the example does not cover all possible
   options available in the protection/unprotection calls.

      The sender first calls IDUP_Establish_Env() to establish a
      security environment.  Then, for the IDU to be protected the
      sender calls the appropriate protection calls (SE, EV, or GP) to
      perform the IDU protection.  The resulting P-IDU, which may
      (depending on whether or not encapsulation was chosen/available)
      be either the token itself or the logical concatenation of the
      token and the M-IDU, is now ready to be sent to the target.  The
      sender then calls IDUP_Abolish_Env() to flush all environment-
      specific information.

      The receiver first calls IDUP_Establish_Env() to establish a
      security environment in order to unprotect the P-IDU.  Then, for
      the received P-IDU the receiver calls the appropriate unprotection
      calls (SE, EV, or GP (known a priori, or possibly determined
      through the use of the IDUP_Get_token_details call)) to perform
      the P-IDU unprotection.  The receiver then calls
      IDUP_Abolish_Env() to flush all environment-specific information.

   It is important to note that absolutely no synchronization is implied
   or expected between the data buffer size used by the sender as input
   to the protection calls, the data buffer size used by the receiver as
Top   ToC   RFC2479 - Page 5
   input to the unprotection calls, and the block sizes required by the
   underlying protection algorithms (integrity and confidentiality). All
   these sizes are meant to be independent; furthermore, the data buffer
   sizes used for the protection and unprotection calls are purely a
   function of the local environment where the calls are made.

   The IDUP-GSS-API design assumes and addresses several basic goals,
   including the following.

      Mechanism independence:  The IDUP-GSS-API defines an interface to
      cryptographically implemented security services at a generic level
      which is independent of particular underlying mechanisms. For
      example, IDUP-GSS-API-provided services can be implemented by
      secret-key technologies or public-key approaches.

      Protocol environment independence: The IDUP-GSS-API is independent
      of the communications protocol suites which may be used to
      transfer P-IDUs, permitting use in a broad range of protocol
      environments.

      Protocol association independence: The IDUP-GSS-API's security
      environment construct has nothing whatever to do with
      communications protocol association constructs, so that IDUP-GSS-
      API services can be invoked by applications, wholly independent of
      protocol associations.

      Suitability for a range of implementation placements: IDUP-GSS-API
      clients are not constrained to reside within any Trusted Computing
      Base (TCB) perimeter defined on a system where the IDUP-GSS-API is
      implemented; security services are specified in a manner suitable
      for both intra-TCB and extra-TCB callers.

1.1. IDUP-GSS-API Constructs

   This section describes the basic elements comprising the IDUP-GSS-
   API.

1.1.1.  Credentials

   Credentials in IDUP-GSS-API are to be understood and used as
   described in GSS-API [RFC-2078].

1.1.2. Tokens

   Tokens in IDUP-GSS-API are to be understood and used as described in
   GSS-API [RFC-2078] with the exception that there are no context-level
   tokens generated by IDUP-GSS-API.  The IDUP-GSS-API token may
   (depending on the underlying mechanism) encapsulate the M-IDU or may
Top   ToC   RFC2479 - Page 6
   be logically concatenated with the M-IDU prior to transfer to a
   target; furthermore, for some evidence services the token may be sent
   independently of any other data transfer.

1.1.3.  Security Environment

   The "security environment" in IDUP-GSS-API is entirely different from
   the concept of security contexts used in GSS-API [RFC-2078].  Here, a
   security environment exists within a calling application (that is, it
   is purely local to the caller) for the purpose of protecting or
   unprotecting one or more IDUs using a particular caller credential or
   set of credentials.  In GSS-API, on the other hand, a security
   context exists between peers (the initiator and the target) for the
   purpose of protecting, in real time, the data that is exchanged
   between them.  Although they are different concepts, the env_handle
   in IDUP-GSS-API is similar to the context_handle in GSS-API in that
   it is a convenient way of tying together the entire process of
   protecting or unprotecting one or more IDUs using a particular
   underlying mechanism.  As with the GSS-API security contexts, a
   caller can initiate and maintain multiple environments using the same
   or different credentials.

1.1.4.  Mechanism Types

   Mechanism types in IDUP-GSS-API are to be understood and used as
   described in GSS-API [RFC-2078].

1.1.5.  Naming

   Naming in IDUP-GSS-API is to be understood and used as described in
   GSS-API [RFC-2078].

1.1.6.  Channel Bindings

   The concept of channel bindings discussed in GSS-API [RFC-2078] is
   not relevant to the IDUP-GSS-API.

1.2.  IDUP-GSS-API Features and Issues

   This section describes aspects of IDUP-GSS-API operations and of the
   security services which the IDUP-GSS-API provides.  It also provides
   commentary on design issues.

1.2.1.  Status Reporting

   Status reporting in IDUP-GSS-API is to be understood and used as
   described in GSS-API [RFC-2078], with the addition of a number of
   IDUP-specific status codes.  Descriptions of the major_status codes
Top   ToC   RFC2479 - Page 7
   used in IDUP are provided in Table 1.  Codes that are informatory
   (i.e., that do not cause the requested operation to fail) are
   indicated with the symbol "(I)".

   As with GSS-API, minor_status codes, which provide more detailed
   status information than major_status codes, and which may include
   status codes specific to the underlying security mechanism, are not
   specified in this document.

    Table 1: IDUP-GSS-API Major Status Codes

      GSS_S_BAD_MECH indicates that a mech_type unsupported by the
      IDUP_GSS-API implementation was requested, causing the environment
      establishment operation to fail.

      GSS_S_BAD_QOP indicates that the provided qop_alg value is not
      recognized or supported for the environment.

      GSS_S_BAD_MIC indicates that the received P-IDU contains an
      incorrect integrity field (e.g., signature or MAC) for the data.

      GSS_S_COMPLETE indicates that the requested operation was
      successful.

      GSS_S_CREDENTIALS_EXPIRED indicates that the credentials
      associated with this operation have expired, so that the requested
      operation cannot be performed.

      GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
      performed on the credential structure referenced by
      claimant_cred_handle failed, preventing further processing from
      being performed using that credential structure.

      GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
      on the received P-IDU failed, preventing further processing from
      being performed.

      GSS_S_FAILURE indicates that the requested operation could not be
      accomplished for reasons unspecified at the IDUP-GSS-API level,
      and that no interface-defined recovery action is available.

      GSS_S_NO_CRED indicates that no environment was established,
      either because the input cred_handle was invalid or because the
      caller lacks authorization to access the referenced credentials.

      IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU data
      origin auth. / integ. has either expired or been revoked.
Top   ToC   RFC2479 - Page 8
      IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU
      cannot be completed because the encrypted IDU was
      invalid/defective (e.g., the final block was short or had
      incorrect padding).

      IDUP_S_BAD_KE_KEY indicates that the key used to establish a key
      for confidentiality purposes between originator and target has
      either expired or been revoked.

      IDUP_S_BAD_TARG_INFO indicates that the full set of supplied
      information regarding the target(s) is invalid or is insufficient
      for the protection of an IDU, so P-IDU cannot be created.

      IDUP_S_DEFECTIVE_VERIF indicates that consistency checks performed
      on Service_Verification_Info failed, preventing further processing
      from being performed with that parameter.

      IDUP_S_ENCAPSULATION_UNAVAIL (I) indicates that the underlying
      mechanism does not support encapsulation of the M-IDU into the
      token.

      IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied
      do not contain the information necessary for P-IDU unprotection.

      IDUP_S_INCOMPLETE (I) indicates that the unprotection of the P-IDU
      is not yet complete (i.e., a determination cannot yet be made on
      the validity of the P-IDU).  The application should call
      IDUP_Form_Complete_PIDU and then should call this function again
      with the complete P-IDU.

      IDUP_S_INCONSISTENT_PARAMS indicates that the supplied parameters
      are inconsistent (e.g., only one or the other of two parameters
      may be supplied, but both have been input).

      IDUP_S_MORE_OUTBUFFER_NEEDED (I) indicates that the output buffer
      supplied is too small to hold the generated data.  The application
      should continue calling this routine (until GSS_S_COMPLETE is
      returned) in order to get all remaining output data.

      IDUP_S_MORE_PIDU_NEEDED (I) indicates that not enough of the P-IDU
      has been input yet for the completion of StartUnprotect.  The
      application should call this routine again with another buffer of
      P-IDU in partial(initial)_pidu_buffer.

      IDUP_S_NO_ENV indicates that no valid environment was recognized
      for the env_handle provided.
Top   ToC   RFC2479 - Page 9
      IDUP_S_NO_MATCH indicates that Service_Verification_Info (or
      evidence_check) and the P-IDU to be verified do not match.

      IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service
      requested (TTIME or UTIME) is not available in the environment.

      IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism
      does not support the service requested.

      IDUP_S_SERV_VERIF_INFO_NEEDED (I) indicates that the
      Service_Verification_Info parameter bundle must be input in order
      for service verification to proceed.  The output parameter
      service_verification_info_id contains an identifier which may be
      used by the calling application to locate the necessary
      information.

      IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
      is not recognized or supported in the underlying mechanism.

1.2.2. Per-IDU Security Service Availability

   Per-IDU security service availability in IDUP-GSS-API is to be
   understood and used as described in GSS-API [RFC-2078], with the
   exception that combinations of services requested by the calling
   application and supported by the underlying mechanism may be applied
   simultaneously to any IDU (true for both the SE and the EV calls, but
   true in the fullest sense for the GP calls).

   GSS-API callers desiring per-message security services should check
   the relevant service OBJECT IDs at environment establishment time to
   ensure that what is available in the established environment is
   suitable for their security needs.

1.2.3. Per-IDU Replay Detection and Sequencing

   The concept of per-IDU replay detection and sequencing discussed in
   GSS-API [RFC-2078] is not relevant to the IDUP-GSS-API.

1.2.4.  Quality of Protection

   The concept of QOP control in IDUP-GSS-API is to be understood
   essentially as described in GSS-API [RFC-2078].  However, the actual
   description and use of the QOP parameter is given as follows.

   The qop_algs parameter for IDUP is defined to be a 32-bit unsigned
   integer with the following bit-field assignments:
Top   ToC   RFC2479 - Page 10
            31 (MSB)                               (LSB) 0
            ----------------------------------------------
            |        U(19)       | TS(5) | IA(4) | MA(4) |
            ----------------------------------------------

   where

      U is a 19-bit Unspecified field (available for future
      use/expansion) -- must be set to zero;

      TS is a 5-bit Type Specifier (a semantic qualifier whose value
      specifies the type of algorithm which may be used to protect the
      corresponding IDU -- see below for details);

      IA is a 4-bit field enumerating Implementation-specific
      Algorithms; and

      MA is a 4-bit field enumerating Mechanism-defined Algorithms.

   The interpretation of the qop_algs parameter is as follows.  The MA
   field is examined first.  If it is non-zero then the algorithm used
   to protect the IDU is the mechanism-specified algorithm corresponding
   to that integer value.

   If MA is zero then IA is examined.  If this field value is non-zero
   then the algorithm used to protect the IDU is the implementation-
   specified algorithm corresponding to that integer value.  Note that
   use of this field may hinder portability since a particular value may
   specify one algorithm in one implementation of the mechanism and may
   not be supported or may specify a completely different algorithm in
   another implementation of the mechanism.

   Finally, if both MA and IA are zero then TS is examined.  A value of
   zero for TS specifies the default algorithm for the established
   mechanism.  A non-zero value for TS corresponds to a particular
   algorithm qualifier and selects any algorithm from the mechanism
   specification which satisfies that qualifier (which actual algorithm
   is selected is an implementation choice; the calling application need
   not be aware of the choice made).

   The following TS values (i.e., algorithm qualifiers) are specified;
   other values may be added in the future.
Top   ToC   RFC2479 - Page 11
   When qop_algs is used to select a confidentiality algorithm:

      00000  (0) = default confidentiality algorithm
      00001  (1) = IDUP_SYM_ALG_STRENGTH_STRONG
      00010  (2) = IDUP_SYM_ALG_STRENGTH_MEDIUM
      00011  (3) = IDUP_SYM_ALG_STRENGTH_WEAK
      11111 (31) = IDUP_NO_CONFIDENTIALITY

   When qop_algs is used to select a DOA/integrity algorithm:

      00000  (0) = default integrity algorithm
      00001  (1) = IDUP_INT_ALG_DIG_SIGNATURE
                   (integrity provided through a digital signature)
      00010  (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE
                   (integrity without a dig. sig. (e.g., with a MAC))
      11111 (31) = IDUP_NO_INTEGRITY

   Clearly, qualifiers such as strong, medium, and weak are debatable
   and likely to change with time, but for the purposes of this version
   of the specification we define these terms as follows.  A
   confidentiality algorithm is "weak" if the effective key length of
   the cipher is 40 bits or less; it is "medium-strength" if the
   effective key length is strictly between 40 and 80 bits; and it is
   "strong" if the effective key length is 80 bits or greater.
   ("Effective key length" describes the computational effort required
   to break a cipher using the best-known cryptanalytic attack against
   that cipher.)

   A five-bit TS field allows up to 30 qualifiers for each of
   confidentiality and integrity (since "0" is reserved for "default"
   and "31" is reserved for "none", as shown above).  This document
   specifies three for confidentiality and two for integrity, leaving a
   lot of room for future specification.  Suggestions of qualifiers such
   as "fast", "medium-speed", and "slow" have been made, but such terms
   are difficult to quantify (and in any case are platform- and
   processor-dependent), and so have been left out of this initial
   specification.  The intention is that the TS terms be quantitative,
   environment-independent qualifiers of algorithms, as much as this is
   possible.

   Use of the qop_algs parameter as defined above is ultimately meant to
   be as follows.

    - TS values are specified at the IDUP-GSS-API level and are
      therefore portable across mechanisms.  Applications which know
      nothing about algorithms are still able to choose "quality" of
      protection for their message tokens.
Top   ToC   RFC2479 - Page 12
    - MA values are specified at the mechanism level and are therefore
      portable across implementations of a mechanism.

    - IA values are specified at the implementation level (in user
      documentation, for example) and are therefore typically non-
      portable.  An application which is aware of its own mechanism
      implementation and the mechanism implementation of its intended
      P-IDU recipient, however, is free to use these values since they
      will be perfectly valid and meaningful for protecting IDUs between
      those entities.

   The receiver of a P-IDU must pass back to its calling application (in
   IDUP_Start_Unprotect()) a qop_algs parameter with all relevant fields
   set.  For example, if triple-DES has been specified by a mechanism as
   algorithm 8, then a receiver of a triple-DES-protected P-IDU must
   pass to its application (TS=1, IA=0, MA=8).  In this way, the
   application is free to read whatever part of the qop_algs parameter
   it understands (TS or IA/MA).

1.2.5.  The Provision of Time

   IDUP mechanisms should make provision in their protocols for the
   carrying of time information from originator to target(s).  That is,
   a target (a legitimate recipient) should get some indication during
   unprotection regarding the time at which the protection operation
   took place.  This is particularly important if the mechanism offers
   non-repudiation services because in some cases evidence verification
   may only be achievable if the time at which the evidence was
   generated is known.

   Depending upon the platform and resources available to the
   implementation, an IDUP environment may have access to a source of
   trusted (secure) time, untrusted (local) time, both kinds of time, or
   no time.  OBJECT IDs indicating such availability are returned by the
   IDUP_Establish_Env() call.  When starting a protection operation, an
   application may specify which time services it wishes to have applied
   to the IDU.  Similarly, for unprotection, an application may specify
   which kind of time (if any) to consult when the validity of the P-IDU
   is to be established.  Specifying both kinds of time is interpreted
   to mean that the calling application does not care which kind of time
   is used.

   The IDUP calls which use a time parameter specify the type of that
   parameter to be INTEGER.  This INTEGER is defined in all cases to be
   the number of seconds which have elapsed since midnight, January 1,
   1970, coordinated universal time.
Top   ToC   RFC2479 - Page 13
2.  Interface Descriptions

   This section describes the IDUP-GSS-API's operational interface,
   dividing the set of calls offered into five groups.  Credential
   management calls are related to the acquisition and release of
   credentials by API callers. Environment-level calls are related to
   the management of the security environment by an API caller.  Per-IDU
   calls are related to the protection or unprotection of individual
   IDUs in established security environments.  Special-purpose calls
   deal with unusual or auxiliary evidence generation/verification
   requirements.  Support calls provide extra functions useful to IDUP-
   GSS-API callers.  Table 2 groups and summarizes the calls in tabular
   fashion.

    Table 2:  IDUP-GSS-API Calls

      CREDENTIAL MANAGEMENT
      (see the calls given in Section 2.1 of GSS-API [RFC-2078])

      ENVIRONMENT-LEVEL CALLS
      IDUP_Establish_Env
      IDUP_Abolish_Env
      IDUP_Inquire_Env

      PER-IDU CALLS
      SE (SIGN,ENCRYPT) CALLS
         IDUP_SE_SingleBuffer_Protect
         IDUP_SE_SingleBuffer_Unprotect
         IDUP_SE_MultiBuffer_StartProtect
         IDUP_SE_MultiBuffer_EndProtect
         IDUP_SE_MultiBuffer_StartUnprotect
         IDUP_SE_MultiBuffer_EndUnprotect
         IDUP_SE_Process_Buffer
      EV (EVIDENCE) CALLS
         IDUP_EV_SingleBuffer_Generate
         IDUP_EV_SingleBuffer_Verify
         IDUP_EV_MultiBuffer_StartGenerate
         IDUP_EV_MultiBuffer_EndGenerate
         IDUP_EV_MultiBuffer_StartVerify
         IDUP_EV_MultiBuffer_EndVerify
         IDUP_EV_Process_Buffer
      GP (GENERAL PROTECTION) CALLS
         IDUP_Start_Protect
         IDUP_Protect
         IDUP_End_Protect
         IDUP_Start_Unprotect
         IDUP_Unprotect
         IDUP_End_Unprotect
Top   ToC   RFC2479 - Page 14
      SPECIAL-PURPOSE CALLS  (might not be supported by all mechanisms)
      IDUP_Form_Complete_PIDU

      SUPPORT CALLS
      IDUP_Acquire_cred_with_auth
      IDUP_Get_Token_Details
      IDUP_Get_Policy_Info
      IDUP_Cancel_Multibuffer_Op
      (see also the calls given in Section 2.4 of GSS-API [RFC-2078])

   In terms of conformance to this specification, IDUP-GSS-API
   implementations must support the credential management calls, the
   environment-level calls, some subset of the per-IDU calls, and the
   support calls (except where explicitly stated otherwise in Section
   2.5).  The subset of per-IDU calls supported will depend upon the
   underlying mechanisms supported and will typically be the SE calls,
   or the EV calls, or both.  As stated in Section 2.3.2.1,
   implementations are encouraged to support the more powerful GP calls
   to anticipate the future needs of applications developers, but this
   is not required for conformance.

2.1.  Credential management calls

2.1.1.  Relationship to GSS-API

   Credential management in IDUP-GSS-API is to be understood and used as
   described in GSS-API [RFC-2078].  The calls given in Section 2.1 of
   GSS-API (including all associated parameters) are unchanged, although
   the interpretation of the cred_usage parameter in the GSS-API calls
   for IDUP purposes is as follows.

      ENCRYPT_ONLY    8
      DECRYPT_ONLY   16
      SIGN_ONLY      32
      VERIFY_ONLY    64

   The values above may be logically OR'ed together in any desired
   combination to restrict credential usage (where OR'ing all values
   results in NO_RESTRICTION).  Future possible values for this
   parameter are for further study.

   The call IDUP_Acquire_cred_with_auth has been added as a support call
   in this specification to permit authenticated credential acquirement;
   see Section 2.5.2 for details.
Top   ToC   RFC2479 - Page 15
2.2.  Environment-level calls

   This group of calls is devoted to the establishment and management of
   an environment for the purpose of IDU protection and unprotection.
   Before protecting or unprotecting any IDU, an application must call
   IDUP_Establish_Env() to initialize environment information and select
   the underlying IDUP-GSS mechanism to be used.  A series of protection
   or unprotection calls is made to process each IDU, the protection
   calls resulting in a P-IDU for each.  Finally, IDUP_Abolish_Env() is
   called to flush all environment information.

   Semantically, acquiring credentials and establishing an environment
   is (in many cases) analogous to logging in to a system -- it
   authenticates a local user to the system and gives that user access
   to a set of operations which can be performed.

2.2.1.  Relationship to GSS-API

   The set of calls described in this section is used in place of the
   calls described in Section 2.2 of GSS-API [RFC-2078], since those
   calls are specific to a session-oriented environment.

2.2.2.  IDUP_Establish_Env call

   Inputs: o  claimant_cred_handle CREDENTIAL HANDLE,
      -- NULL parameter specifies "use default"

   o  req_mech_type OBJECT IDENTIFIER,
      -- NULL parameter specifies "use default"
   o  req_environmentPolicies EnvironmentPolicies,
      -- NULL parameter specifies "use default"
   o  req_services SET OF OBJECT IDENTIFIER,
      -- GSS_C_NO_OID_SET requests full set of services available
      -- for req_mech_type

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  env_handle ENVIRONMENT HANDLE,
   o  actual_mech_type OBJECT IDENTIFIER,
      -- actual mechanism always indicated, never NULL
   o  actual_environmentPolicies EnvironmentPolicies,
      -- actual values always indicated, never NULL
   o  ret_services SET OF OBJECT IDENTIFIER,

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- environment-level information was successfully initialized,
Top   ToC   RFC2479 - Page 16
      -- and IDU / P-IDU processing can begin.
   o  GSS_S_DEFECTIVE_CREDENTIAL
   o  GSS_S_NO_CRED
   o  GSS_S_CREDENTIALS_EXPIRED
      -- the credentials provided through claimant_cred_handle are
      -- no longer valid, so environment cannot be established.
   o  GSS_S_BAD_MECH
   o  GSS_S_FAILURE

   The following structures are defined to facilitate environment policy
   input and output:

   EnvironmentPolicies ::= SEQUENCE {
      confPolicy     [0] PolicyAndTime OPTIONAL,
      -- NULL parameter (on input) specifies "use default"
      integPolicy    [1] PolicyAndTime OPTIONAL,
      -- NULL parameter (on input) specifies "use default"
      evidencePolicy [2] PolicyAndTime OPTIONAL }
      -- NULL parameter (on input) specifies "use default"

   PolicyAndTime ::= SEQUENCE {
      policy             OBJECT IDENTIFIER,
      -- this environment-level policy identifier is separate from
      -- the policy provisions connected with credentials, if they exist
      time               INTEGER
      -- on input:  the policy rules available at the specified time
      -- on output: the time at which the policy rules came into effect
      -- (defined to be the number of seconds elapsed since midnight,
      -- January 1, 1970, coordinated universal time)
      endTime            INTEGER OPTIONAL }
      -- on input:  unused
      -- on output: the expiration time of the given policy rules

   This routine is used by an application which protects or unprotects
   IDUs.  Using information in the credentials structure referenced by
   claimant_cred_handle, IDUP_Establish_Env() initializes the data
   structures required to protect or unprotect IDUs.  The
   claimant_cred_handle, if non-NULL, must correspond to a valid
   credentials structure.

   This routine returns an env_handle for all future references to this
   environment; when protection, unprotection, or IDUP_Abolish_Env()
   calls are made, this handle value will be used as the input
   env_handle argument.  It is the caller's responsibility to establish
   a communications path to the intended recipients of the P-IDU, and to
   transmit the P-IDU to those recipients over that path.  This may
   occur subsequent to the IDUP_Abolish_Env() call.
Top   ToC   RFC2479 - Page 17
   The req_services parameter may be used by the calling application to
   request that data origin authentication with integrity,
   confidentiality with integrity, evidence generation, and/or evidence
   verification services be available in the established environment.
   Requests can also be made for "trusted" or "untrusted" time services.
   Requesting evidence generation or verification indicates that the
   calling application may wish to generate or verify evidence
   information for non-repudiation purposes (note:  an IDU protector may
   request that a flag be inserted into a P-IDU asking a recipient to
   provide an evidence of the type "non-repudiation of delivery";
   however, the IDUP-GSS-API cannot by itself guarantee that the
   evidence will be sent because there is no way to force a target to
   send an evidence_token back to the IDU protector).

   Not all features will be available in all underlying mech_types; the
   returned value of ret_services indicates, as a function of mech_type
   processing capabilities and the initiator-provided input OBJECT IDs,
   the set of features which will be available in the environment. The
   value of this parameter is undefined unless the routine's
   major_status indicates COMPLETE.  Failure to provide the precise set
   of services desired by the caller does not cause environment
   establishment to fail; it is the caller's choice to abolish the
   environment if the service set provided is unsuitable for the
   caller's use.  The returned mech_type value indicates the specific
   mechanism employed in the environment and will never indicate the
   value for "default".

   The following OBJECT IDs are defined for protection and unprotection
   services (the OBJECT ID iso.org.dod.internet.security.services,
   1.3.6.1.5.7, has been assigned by IANA, and some of the security
   services under that node are assigned as shown below).  It is
   recognized that this list may grow over time.

      PER_CONF = { 1.3.6.1.5.7.1.1 }
         -- perform data confidentiality (i.e., encrypt data)
      PER_CONF_FULL = { 1.3.6.1.5.7.1.3 }
         -- perform full confidentiality (i.e., encrypt data and sig)
         -- (may be used only when PER_DOA is requested simultaneously)
      PER_DOA  = { 1.3.6.1.5.7.3.1 }
         -- perform data origin authentication with data integrity
      PER_DOA_CIPH  = { 1.3.6.1.5.7.3.3 }
         -- perform DOA with DI over ciphertext (rather than plaintext)
         -- (may be used only when PER_CONF is requested simultaneously)
      PER_POO  = { 1.3.6.1.5.7.4.1 }
         -- perform (i.e., create) non-repudiable "proof of origin"
      PER_POD  = { 1.3.6.1.5.7.4.3 }
         -- perform (i.e., create) non-repudiable "proof of delivery"
Top   ToC   RFC2479 - Page 18
      REC_CONF = { 1.3.6.1.5.7.1.2 }
         -- receive data confidentiality (i.e., decrypt data)
      REC_CONF_FULL = { 1.3.6.1.5.7.1.4 }
         -- receive full confidentiality (i.e., decrypt data and sig)
         -- (may be used only when REC_DOA is received simultaneously)
      REC_DOA  = { 1.3.6.1.5.7.3.2 }
         -- receive / verify DOA with data integrity
      REC_DOA_CIPH  = { 1.3.6.1.5.7.3.4 }
         -- verify DOA with DI over ciphertext (rather than plaintext)
         -- (may be used only when PER_CONF is received simultaneously)
      REC_POO  = { 1.3.6.1.5.7.4.2 }
         -- receive / verify "proof of origin"
      REC_POD  = { 1.3.6.1.5.7.4.4 }
         -- receive / verify "proof of delivery"
      TTIME    = { 1.3.6.1.5.7.7.1 }
         -- trusted time availability
      UTIME    = { 1.3.6.1.5.7.7.2 }
         -- untrusted time availability

   The PER_CONF return value (in the ret_services paramater) indicates
   whether the environment supports confidentiality services, and so
   informs the caller whether or not a request for encryption can be
   honored.  In similar fashion, the PER_DOA return value indicates
   whether DOA services are available in the established environment,
   and the PER_POO and PER_POD return values indicate whether evidence
   generation services are available.  The TTIME and UTIME values
   indicate whether trusted time and untrusted time are available for
   protection / unprotection services.

   Note that, unlike a GSS "context", an IDUP environment does not have
   an explicit lifetime associated with it.  Instead, it relies on the
   lifetime of the calling entity's credential (set by the caller in the
   GSS_Acquire_cred() call).  When the credential expires (or is
   explicitly deleted in any other way), no new operations are allowed
   in the IDUP environment (although operations which have begun, such
   as the Protection set of calls, can be taken to completion).
Top   ToC   RFC2479 - Page 19
2.2.3. IDUP_Abolish_Env call

   Input:
   o  env_handle ENVIRONMENT HANDLE

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- the relevant environment-specific information was flushed.
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   This call is made to flush environment-specific information. (Once an
   environment is established, cached credential and environment-related
   info. is expected to be retained until an IDUP_Abolish_Env() call is
   made or until the cred. lifetime expires.)  Attempts to perform IDU
   processing on a deleted environment will result in error returns.

2.2.4. IDUP_Inquire_Env call

   Input:
   o  env_handle ENVIRONMENT HANDLE,

   Outputs:
   o  major_status INTEGER,
   o  minor_status INTEGER,
   o  mech_type OBJECT IDENTIFIER,
      -- the mechanism supporting this environment
   o  environmentPolicies EnvironmentPolicies,
      -- the environment policies in effect
   o  ret_services SET OF OBJECT IDENTIFIER,

   Return major_status codes:
   o  GSS_S_COMPLETE
      -- referenced environment is valid and mech_type and other return
      -- values describe the characteristics of the environment.
   o  GSS_S_CREDENTIALS_EXPIRED
   o  IDUP_S_NO_ENV
   o  GSS_S_FAILURE

   This routine provides environment-related information to the caller.


(next page on part 2)

Next Section