rfc2479.txt

RFC 的详细文档！

Adams                        Informational                     [Page 11]

RFC 2479                      IDUP-GSS-API                 December 1998


    - 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.





Adams                        Informational                     [Page 12]

RFC 2479                      IDUP-GSS-API                 December 1998


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



Adams                        Informational                     [Page 13]

RFC 2479                      IDUP-GSS-API                 December 1998


      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.







Adams                        Informational                     [Page 14]

RFC 2479                      IDUP-GSS-API                 December 1998


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,



Adams                        Informational                     [Page 15]

RFC 2479                      IDUP-GSS-API                 December 1998


      -- 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.




Adams                        Informational                     [Page 16]

RFC 2479                      IDUP-GSS-API                 December 1998


   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