One document matched: draft-ietf-cat-idup-gss-02.txt
Differences from draft-ietf-cat-idup-gss-01.txt
Independent Data Unit Protection Generic Security Service
Application Program Interface (IDUP-GSS-API)
STATUS OF THIS MEMO
This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by
other documents at any time. It is inappropriate to use Internet-
Drafts as reference material or to cite them other than as
"work in progress."
To learn the current status of any Internet Draft, please check the
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
Directories on ds.internic.net (US East Coast), nic.nordu.net
(Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific
Rim).
Comments on this document should be sent to "cat-ietf@mit.edu", the
IETF Common Authentication Technology WG discussion list.
ABSTRACT
The IDUP-GSS-API extends the GSS-API [RFC-1508] 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. 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.
Adams Document Expiration: 5 Jan. 1996 1
As with RFC-1508, 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 environ-
ment, 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 .................................. 4
1.1.1. Credentials ............................................ 4
1.1.2. Tokens ................................................. 5
1.1.3. Security Environment ................................... 5
1.1.4. Mechanism Types ........................................ 5
1.1.5. Naming ................................................. 5
1.1.6. Channel Bindings ....................................... 5
1.2. IDUP-GSS-API Features and Issues ......................... 5
1.2.1. Status Reporting ....................................... 5
1.2.2. Per-IDU Security Service Availability .................. 6
1.2.3. Per-IDU Replay Detection and Sequencing ................ 6
1.2.4. Quality of Protection .................................. 6
2. Interface Descriptions ..................................... 9
2.1. Credential management calls .............................. 10
2.1.1. Relationship to GSS-API ................................ 10
2.2. Environment-level calls .................................. 10
2.2.1. Relationship to GSS-API ................................ 10
2.2.2. IDUP_Establish_Env call ................................ 11
2.2.3. IDUP_Abolish_Env call .................................. 13
2.2.4. IDUP_Inquire_Env call .................................. 13
2.3. Per-IDU calls ............................................ 14
2.3.1. Relationship to GSS-API ................................ 15
2.3.2. IDUP_Start_Protect ..................................... 15
2.3.3. IDUP_Protect ........................................... 17
2.3.4. IDUP_End_Protect ....................................... 17
2.3.5. IDUP_Start_Unprotect ................................... 18
2.3.6. IDUP_Unprotect ......................................... 20
2.3.7. IDUP_End_Unprotect ..................................... 20
2.4. Special-Purpose calls .................................... 21
2.4.1. Relationship to GSS-API ................................ 21
2.4.2. IDUP_Start_Generate_Receipt ............................ 21
2.4.3. IDUP_Generate_Receipt .................................. 23
2.4.4. IDUP_End_Generate_Receipt .............................. 23
2.4.5. IDUP_Process_Receipt ................................... 24
2.4.6. IDUP_Generate_Evidence ................................. 25
2.4.7. IDUP_Process_Evidence .................................. 26
2.5. Support calls ............................................ 28
2.5.1. Relationship to GSS-API ................................ 28
2.5.2. IDUP_Parse_token call .................................. 28
Adams Document Expiration: 5 Jan. 1996 2
3. Mechanism-Specific Example Scenarios ....................... 29
3.1. PEM-compliant file protection ............................ 30
3.2. Signed-MSP-compliant file protection ..................... 31
4. Related Activities ......................................... 31
5. Acknowledgments ............................................ 32
6. Security Considerations .................................... 32
7. References ........................................... 32
8. Author's Address ........................................... 32
Appendix A, B ................................................. 33
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 which works with IDUs, calling
on IDUP-GSS-API in order to protect its IDUs with origin
authentication, integrity, confidentiality, and/or (support for)
non-repudiation security services. An IDUP-GSS-API caller passes
IDUs to, and accepts tokens from, its local IDUP-GSS-API
implementation; it logically concatenates the token(s) and the IDU,
thereby creating a protected IDU (P-IDU); finally, it transfers the
P-IDU to a peer or to any storage medium. When the P-IDU is to be
"unprotected", the token(s) and the IDU must be 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. The protecting application may
choose whatever method it wishes to concatenate or combine the
token(s) and the 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.
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 the data origin authentication / data
integrity services, or confidentiality services, or both, as a caller
option. Additional calls provide supportive or special-purpose
functions to the IDUP-GSS-API's users.
The following paragraphs provide an example illustrating the
dataflows involved in 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.
The sender first calls IDUP_Establish_Env() to establish a
security environment. Then, for the IDU to be protected the
sender calls IDUP_Start_Protect(), IDUP_Protect() for each buffer
of data, and IDUP_End_Protect() to complete the IDU protection.
The prot_token output by IDUP_End_Protect() and the possibly
modified IDU (i.e., the IDU with confidentiality applied if this
was requested in IDUP_Start_Protect()) are logically concatenated
to form the P-IDU, which is now ready to be sent to the target.
The sender then calls IDUP_Abolish_Env() to flush all environment-
specific information.
Adams Document Expiration: 5 Jan. 1996 3
The receiver first calls IDUP_Establish_Env() to establish a
security environment for unprotecting P-IDUs. Then, for the
received P-IDU the receiver calls IDUP_Start_Unprotect(),
IDUP_Unprotect() for each buffer of data, and IDUP_End_Unprotect()
to complete 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
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 is independent of 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-1508].
Adams Document Expiration: 5 Jan. 1996 4
1.1.2. Tokens
Tokens in IDUP-GSS-API are to be understood and used as described in
GSS-API [RFC-1508] with the exception that there are no context-level
tokens generated by IDUP-GSS-API. Only three tokens, prot_token,
receipt_token, and evidence_token, are defined by IDUP-GSS-API. The
first is meant to be logically concatenated with an IDU prior to
transfer to a target; the latter two can 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-1508]. 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.
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 IDUP_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. 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-1508].
1.1.5. Naming
Naming in IDUP-GSS-API is to be understood and used as described in
GSS-API [RFC-1508].
1.1.6. Channel Bindings
The concept of channel bindings discussed in GSS-API [RFC-1508] 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-1508], with the addition of the following
IDUP-GSS-API major status codes:
Adams Document Expiration: 5 Jan. 1996 5
Table 1: IDUP-GSS-API Major Status Codes
Fatal Error Codes
IDUP_S_BAD_TARG_INFO target information is invalid or
unsuitable for IDU protection.
IDUP_S_BAD_DIGEST_ALG requested digest algorithm unsupported
IDUP_S_BAD_CONF_ALG requested conf. algorithm unsupported
o IDUP_S_BAD_AI_KEY key used for IDU origin auth. and/or
IDU integrity has expired or been revoked.
o IDUP_S_BAD_KE_KEY key used for key establishment between
orig. and targ. has exp. or been revoked.
IDUP_S_BAD_ENC_IDU encrypted IDU is defective/invalid
IDUP_S_NO_ENV no environment recognized for env_handle
IDUP_S_UNKNOWN_OPER_ID requested operation id. is unsupported
IDUP_S_NO_MATCH receipt_check and receipt_token do not
match in the first eight bytes
Informatory Status Codes
IDUP_S_RECEIPTS_UNAVAIL mechanism does not support receipts
IDUP_S_EVIDENCE_UNAVAIL mechanism does not support evidence
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-1508], with the
exception that integrity or confidentiality or both can be applied to
any IDU.
1.2.3. Per-IDU Replay Detection and Sequencing
The concept of per-IDU replay detection and sequencing discussed
in GSS-API [RFC-1508] 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-1508]. However, the actual
description and use of the QOP parameter is given as follows.
Adams Document Expiration: 5 Jan. 1996 6
The QOP parameter for IDUP is defined to be a 32-bit unsigned integer
with the following bit-field assignments:
Confidentiality Integrity
31 (MSB) 16 15 (LSB) 0
------------------------------------|-----------------------------------
| TS (5) | U(3) | IA (4) | MA (4) | TS (5) | U(3) | IA (4) | MA(4) |
------------------------------------|-----------------------------------
where
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);
U is a 3-bit Unspecified field (available for future
use/expansion);
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 parameter is as follows (note that the
same procedure is used for both the confidentiality and the integrity
halves of the parameter). 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, if a default is defined in the mechanism specification
(confidentiality or integrity, depending on which half of QOP is
being examined). 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.
For the Confidentiality TS field:
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
Adams Document Expiration: 5 Jan. 1996 7
For the Integrity TS field:
00001 (1) = IDUP_INT_ALG_DIG_SIGNATURE
00010 (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE
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. (Note
that "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 31 qualifiers for each of
confidentiality and integrity (since "0" is reserved for "default").
This document specifies four for confidentiality and three 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 structure 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.
- 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 peer,
however, is free to use these values since they will be perfectly
valid and meaningful for protecting IDUs between those peers.
The receiver of a P-IDU must pass back to its calling application
(in IDUP_Start_Unprotect()) a QOP 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 (QOP Confidentiality TS=1, IA=0, MA=8). In
this way, the application is free to read whatever part of the QOP it
understands (TS or IA/MA).
Adams Document Expiration: 5 Jan. 1996 8
Furthermore, two additional QOP parameters are defined specifically
for evidence generation and processing for non-repudiation purposes.
Those parameters are described in Section 2.4: Special-Purpose Calls.
2. Interface Descriptions
This section describes the IDUP-GSS-API's service 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 receipt
generation/processing and with evidence generation/processing for
non-repudiation purposes. Support calls provide ancillary functions
useful to IDUP-GSS-API callers. Table 2 groups and summarizes the
calls in tabular fashion (an asterisk marks the calls which are
identical to the GSS-API specification).
Table 2: IDUP-GSS-API Calls
CREDENTIAL MANAGEMENT
* GSS_Acquire_cred acquire credentials for use
* GSS_Release_cred release credentials after use
* GSS_Inquire_cred display information about credentials
ENVIRONMENT-LEVEL CALLS
IDUP_Establish_Env estbablish IDUP environment (to protect and
unprotect IDUs)
IDUP_Abolish_Env abolish env. when no longer needed
IDUP_Inquire_Env indicate characteristics of env.
PER-IDU CALLS
IDUP_Start_Protect begin the protection process
IDUP_Protect protect the IDU (perhaps 1 buffer at a time)
IDUP_End_Protect end the protection process; create a "protect
token" which contains info. necessary for the
legitimate receiver(s) of the P-IDU to
unprotect it
IDUP_Start_Unprotect begin the unprotect process
IDUP_Unprotect use the "protect token" to unprotect the
P-IDU (possibly one buffer at a time)
IDUP_End_Unprotect end the unprotect process; create a receipt
token if this was requested and if underlying
mechanism supports it
SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms)
IDUP_Start_Generate_Receipt begin to generate receipt_token
IDUP_Generate_Receipt continue generating receipt_token
IDUP_End_Generate_Receipt complete generation of receipt_token
IDUP_Process_Receipt process the receipt_token
Adams Document Expiration: 5 Jan. 1996 9
IDUP_Generate_Evidence generate evidence for non-repudiation
IDUP_Process_Evidence process evidence for non-repudiation
SUPPORT CALLS
* GSS_Display_status translate status codes to printable form
* GSS_Indicate_mechs indicate mech_types supported on local
system
* GSS_Compare_name compare two names for equality
* GSS_Display_name translate name to printable form
* GSS_Import_name convert printable name to normalize form
* GSS_Release_name free storage of normalized-form name
* GSS_Release_buffer free storage of printable name
* GSS_Release_oid_set free storage of OID set
IDUP_Parse_Token examine an input token to determine
mech_type and token_type
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-1508]. The calls GSS_Acquire_cred(),
GSS_Release_cred(), and GSS_Inquire_cred() are unchanged.
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 are made to process each IDU, resulting in a
"prot_token" or a "receipt_token" (if supported) for each. Finally,
IDUP_Abolish_Env() is called to flush all environment information.
Semantically, acquiring credentials and establishing an environment
is 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 are used in place of the
calls GSS_Init_sec_context(), GSS_Accept_sec_context(),
GSS_Delete_sec_context(), GSS_Process_context_token(), and
GSS_Context_time() which are specified in [RFC-1508], since those
calls are specific to a session-oriented environment.
Adams Document Expiration: 5 Jan. 1996 10
2.2.2. IDUP_Establish_Env call
Inputs:
o claimant_cred_handle CREDENTIAL HANDLE, -NULL specifies "use
default"
o req_mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use
default"
o req_flags INTEGER,
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 ret_flags INTEGER,
Return major_status codes:
o GSS_S_COMPLETE indicates that environment-level information was
successfully initialized, and that IDU processing can begin on
the newly-established environment.
o 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.
o 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.
o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided
through the input claimant_cred_handle argument are no longer
valid, so environment establishment cannot be completed.
o 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.
o GSS_S_FAILURE indicates that environment setup could not be
accomplished for reasons unspecified at the IDUP-GSS-API level,
and that no interface-defined recovery action is available.
Adams Document Expiration: 5 Jan. 1996 11
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, receipt, evidence,
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.
The req_flags parameter may be used by the calling application to
request that integrity, confidentiality, receipt processing, and/or
evidence processing be available in the established environment.
Requesting receipt processing indicates that the calling application
may wish to generate or process a proof of receipt of a P-IDU.
Requesting evidence processing indicates that the calling application
may wish to generate or process evidence information for
non-repudiation purposes (note: this is non-repudiation of origin;
the IDUP-GSS-API cannot guarantee non-repudiation of delivery -- even
if the receipt calls provide this in the underlying mechanism --
because there is no way to force a target to send a receipt_token
back to the IDU protector).
Not all features will be available in all underlying mech_types; the
returned value of ret_flags (receipts_avail, evidence_avail,
conf_avail, integ_avail) indicates, as a function of mech_type
processing capabilities and the initiator-provided input flags, the
set of features which will be available in the environment. These
state indicators' values are undefined unless the routine's
major_status indicates COMPLETE. Failure to provide the precise set
of features desired by the caller does not cause environment
establishment to fail; it is the caller's prerogative to abolish the
environment if the feature 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 conf_avail return value (in the ret_flags paramater) indicates
whether the environment supports confidentiality services, and so
informs the caller whether or not a request for encryption through
the conf_req_flag input to IDUP_Protect() can be honored. In similar
fashion, the integ_avail return value indicates whether integrity
services are available in the established environment, the
receipts_avail return value indicates whether receipt generation and
processing services are available, and the evidence_avail return
value indicates whether evidence generation and processing services
are available.
Adams Document Expiration: 5 Jan. 1996 12
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, 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).
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 indicates that the environment was recognized and
that relevant environment-specific information was flushed.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided, so no deletion was performed.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
This call is made to flush environment-specific information. (Once an
environment is established, cached credential and environment-related
information is expected to be retained until an IDUP_Abolish_Env()
call is made or until the credential 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 env.
o ret_flags INTEGER,
Adams Document Expiration: 5 Jan. 1996 13
Return major_status codes:
o GSS_S_COMPLETE indicates that the referenced environment is valid
and that mech_type and ret_flags return values describe the
corresponding characteristics of the environment.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided, so no return values can be provided.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
This call is used to extract information describing characteristics
of the security environment.
2.3. Per-IDU calls
This group of calls is used to perform IDU protection 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. The two sets of members of this group form a
pair; the output from the protection set is meant to be input to the
unprotection set.
The per-IDU calls support caller-requested confidentiality in
addition to data origin authentication / data integrity / non-
repudiation services. IDUP_End_Protect() outputs a token which
encapsulates all the information required to unprotect the IDU. The
token from IDUP_End_Protect() is passed to the target along with the
IDU and is processed by the unprotection calls at that system.
Unprotection performs decipherment and/or validation (e.g.,
verification of MAC or digital signature) of P-IDUs, as required.
Each of the two main operations (protection and unprotection) is
separated into three parts: "Start_Operation"; "Operation", called
once for each buffer of input data; and "End_Operation". This
separation is done for convenience since the parts require different
parameters. "Start_Operation" allows the caller to specify or
retrieve the algorithms (through the QOP value) used during the
processing. "Operation" is concerned with the processing itself,
receiving a buffer of input data and, if confidentiality is involved,
returning a buffer of output data. "End_Operation" performs any
required clean-up and creates the appropriate token or states whether
the input token and IDU were valid.
Adams Document Expiration: 5 Jan. 1996 14
2.3.1. Relationship to GSS-API
The set of calls described in this section are used in place of the
calls GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() -- now
named GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() --
which are specified in [RFC-1508], since those calls are specific to
a session-oriented environment.
2.3.2. IDUP_Start_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o qop_req INTEGER, -0 specifies default QOP
o targ_names SEQUENCE OF INTERNAL NAME, -- the set of recipients
o receipt_req_flag BOOLEAN,
o receipts_from SEQUENCE OF INTERNAL NAME,
-must be a subset of targ_names
o receipts_to SEQUENCE OF INTERNAL NAME,
o prot_oper_id INTEGER
-stage of protection operation to be performed
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o digest_state BOOLEAN,
o conf_state BOOLEAN,
o receipt_state BOOLEAN,
o bad_targ_names SEQUENCE OF INTERNAL NAME,
Return major_status codes:
o GSS_S_COMPLETE indicates that the protection process can begin.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o IDUP_S_BAD_DIGEST_ALG indicates that the digest algorithm
specified (through qop_req) is unavailable in the requested
mechanism, so processing cannot continue.
Adams Document Expiration: 5 Jan. 1996 15
o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
is not recognized or supported in the underlying mechanism.
o GSS_S_BAD_QOP indicates that the provided QOP value is not
recognized or supported for the environment.
o IDUP_S_BAD_CONF_ALG indicates that the confidentiality algorithm
specified (through qop_req) is unavailable in the requested
mechanism, so processing cannot continue.
o IDUP_S_BAD_TARG_INFO indicates that the information regarding the
target(s) is invalid or is insufficient for the protection of an
IDU, so prot_token cannot be created.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of protecting the
IDU buffers. If the qop_req parameter specifies an integrity
algorithm, the caller requests that data origin authentication and/or
data integrity services be applied to the IDU buffers (the
choice of the digest algorithm determines whether non-repudiation
services are requested for the IDU). If the qop_req parameter
specifies a confidentiality algorithm, the caller requests that
confidentiality be applied to the IDU buffers. If the receipt_req
flag is TRUE, the caller requests that a proof of receipt of the
P-IDU be returned by one or more recipients. Confidentiality,
authentication/integrity, and receipt processing might not be
supported in all mech_types or by all implementations; the returned
conf_state, digest_state, and receipt_state flags indicate whether
confidentiality, authentication/integrity, or receipt processing can
be provided for the IDU.
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] -- see Section 3.2 for
details. 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 prot_token (from stage 1)
in stage 2.
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. 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 prerogative
to discontinue IDU protection if the target set which can be used is
unsuitable for the caller's purposes.
Adams Document Expiration: 5 Jan. 1996 16
2.3.3. IDUP_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o prot_oper_id INTEGER
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 indicates that the input_buffer has successfully
been included in the protection computation.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
is not recognized or supported in the underlying mechanism.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the required operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, continue the
protection processing on the data in input_buffer and, if
confidentially was requested in IDUP_Start_Protect(), put the
encrypted result in output_buffer.
2.3.4. IDUP_End_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o prot_oper_id INTEGER
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_buffer OCTET STRING
o prot_token OCTET STRING -- resulting "protection token"
o receipt_check OCTET STRING -- first 8 bytes contain random value
Adams Document Expiration: 5 Jan. 1996 17
Return major_status codes:
o GSS_S_COMPLETE indicates that the protection computation has been
successfully completed and the result has been placed in
prot_token. If confidentiality was requested in Start_Protect()
output_buffer will contain any residual ciphertext.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
is not recognized or supported in the underlying mechanism.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, complete the
protection processing on the data and place the computed protection
token in prot_token. If a receipt was requested in Start_Protect()
-- and if receipt generation and processing is supported by the
underlying mechanism -- receipt_check will hold whatever data is
necessary for the mechanism to validate a receipt returned by the
receiver of the P-IDU. The first 8 bytes of receipt_check contain a
random (i.e., previously unused) value which can be used by the
calling application to match receipt_check with the IDU used to
generate it and with the receipt_token returned by the receiver 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).
Note that the IDU itself (whether or not confidentiality was applied)
is not encapsulated into an output token (similar in concept to the
GetMIC call of GSS [RFC-1508], where the data is not encapsulated
into the GetMIC token). This ensures that no constraints whatsoever
are placed on the buffer sizes used in the Unprotection set of calls
-- all buffer sizes are a purely local matter requiring no agreement,
to any degree, between originator and target.
2.3.5. IDUP_Start_Unprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o prot_token OCTET STRING
o prot_oper_id INTEGER --stage of unprotection to be performed
Outputs:
o major_status INTEGER,
Adams Document Expiration: 5 Jan. 1996 18
o minor_status INTEGER,
o qop_state INTEGER,
o receipt_request_state BOOLEAN,
--if TRUE then a receipt was requested during the IDU prot. oper.
o originator_info OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that unprotection processing can begin.
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the received prot_token failed, preventing further processing
from being performed with that token.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
is not recognized or supported in the underlying mechanism.
o IDUP_S_BAD_DIGEST_ALG indicates that the digest algorithm
specified in prot_token is unavailable in the local mechanism, so
processing cannot continue.
o IDUP_S_BAD_CONF_ALG indicates that the confidentiality algorithm
specified in prot_token is unavailable in the local mechanism, so
processing cannot continue.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of unprotecting a
P-IDU. If confidentiality was applied to the IDU, then the
confidentiality portion of qop_state specifies the algorithm which
was used. Similarly, if data integrity / data origin authentication
services were applied to the IDU, then the integrity portion of
qop_state specifies the algorithm which was used. If a receipt was
requested by the sender of the P-IDU (and the underlying mechanism
supports this), receipt_state will be TRUE (the Generate_Receipt set
of calls can be used to generate this receipt in a form suitable for
immediate transfer back to the sender).
If the underlying mechanism supports it and if this information is
contained in prot_token, information regarding the originator (that
is, the entity which used the protection set of calls to protect this
IDU) is returned in originator_info.
Adams Document Expiration: 5 Jan. 1996 19
2.3.6. IDUP_Unprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o prot_oper_id INTEGER
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 indicates that the input_buffer has successfully
been included in the unprotection computation.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
is not recognized or supported in the underlying mechanism.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, continue the
unprotect processing on the data in input_buffer. If confidentiality
was applied to the IDU, put the decrypted data in output_buffer.
2.3.7. IDUP_End_Unprotect call
Inputs:
o env_handle ENVIRONMNENT HANDLE,
o prot_oper_id INTEGER
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_buffer OCTET STRING
Adams Document Expiration: 5 Jan. 1996 20
Return major_status codes:
o GSS_S_COMPLETE indicates that the unprotect computation was
successful. If confidentiality was applied to the IDU,
output_buffer will contain any residual plaintext.
o GSS_S_BAD_SIG indicates that the received prot_token contains an
incorrect integrity field (e.g., signature or MAC) for the data.
o IDUP_S_BAD_AI_KEY indicates that the key used to provide IDU
origin auth. and/or integ. has either expired or been revoked.
o 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.
o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU
cannot be completed because the encrypted IDU was invalid/defec-
tive (e.g., the final block was short or had incorrect padding).
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
is not recognized or supported in the underlying mechanism.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, complete the
unprotect processing on the data and return the appropriate status
code. If confidentiality was applied to the IDU, put the final
decrypted buffer of data in output_buffer.
Note: 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.
2.4. Special-Purpose Calls
2.4.1. Relationship to GSS-API
The special-purpose calls described in this section have no analogue
in GSS-API [RFC-1508]. These calls are used to generate and process
a receipt (proof of delivery of a P-IDU) and to generate and process
evidence for non-repudiation purposes in the IDUP environment. These
calls may not be supported by all underlying IDUP mechanisms.
2.4.2. IDUP_Start_Generate_Receipt call
Inputs:
o env_handle ENVIRONMENT HANDLE,
Adams Document Expiration: 5 Jan. 1996 21
o prot_token OCTET STRING --IDUP protection token
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o p_idu_needed BOOLEAN -- indicates whether receipt_token is
-- generated by this call or by
-- IDUP_End_Generate_Receipt() (i.e.,
-- whether the entire P-IDU is needed
-- for receipt generation or just the
-- prot_token)
o receipt_token OCTET STRING -- first 8 bytes contain random value
-- identical to that in receipt_check
Return major_status codes:
o GSS_S_COMPLETE indicates that receipt generation was successfully
started. Depending on the value of idu_needed, receipt_token is
either returned by this call or by IDUP_End_Generate_Receipt().
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the input prot_token failed, preventing further processing from
being performed with that token.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism
does not support the generation or processing of receipts.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, initialize
the data structures required to generate a receipt for prot_token
and return the appropriate status value. If p_idu_needed is FALSE
then receipt generation is complete and receipt_token is returned by
this call; otherwise, IDUP_Generate_Receipt() should be called for
for each buffer of P-IDU data and IDUP_End_Generate_Receipt() should
be called to complete receipt_token generation.
The first 8 bytes of the returned receipt_token contains a random
value which can be used by the application which originally protected
the IDU to match receipt_check (which it has saved) with
receipt_token and with the IDU used to generate receipt_check.
Adams Document Expiration: 5 Jan. 1996 22
2.4.3. IDUP_Generate_Receipt call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o input_buffer OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
Return major_status codes:
o GSS_S_COMPLETE indicates that the input_buffer has successfully
been included in the receipt generation computation.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism
does not support the generation or processing of receipts.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, continue the
receipt generation processing on the data in input_buffer.
2.4.4. IDUP_End_Generate_Receipt call
Inputs:
o env_handle ENVIRONMNENT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o receipt_token OCTET STRING -- first 8 bytes contain random value
-- identical to that in receipt_check
Return major_status codes:
o GSS_S_COMPLETE indicates that receipt generation was successful.
o IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism
does not support the generation or processing of receipts.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
Adams Document Expiration: 5 Jan. 1996 23
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, complete
the processing required to generate a receipt for the P-IDU and
return the appropriate status value.
The first 8 bytes of the returned receipt_token contains a random
value which can be used by the application which originally protected
the IDU to match receipt_check (which it has saved) with
receipt_token and with the IDU used to generate receipt_check.
2.4.5. IDUP_Process_Receipt call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o receipt_check OCTET STRING -- first 8 bytes contain a random value
o receipt_token OCTET STRING -- 1st 8 bytes contain same random val.
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o rec_originator_info OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that receipt processing was successful.
o GSS_S_DEFECTIVE_CHECK indicates that consistency checks performed
on the receipt_check failed, preventing further processing from
being performed with that token.
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the received receipt_token failed, preventing further
processing from being performed with that token.
o IDUP_S_NO_MATCH indicates that the first 8 bytes of receipt_check
and receipt_token do not match.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism
does not support the generation or processing of receipts.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
Adams Document Expiration: 5 Jan. 1996 24
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, process the
received receipt_token and return the appropriate status value.
Information regarding the creator of the receipt_token may be
returned in rec_originator_info, if the underlying mechanism supports
it.
2.4.6. IDUP_Generate_Evidence call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o gen_evidence_qop INTEGER
o prot_token OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o evidence_token OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that evidence generation was successful.
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the input prot_token failed, preventing further processing from
being performed with that token.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_EVIDENCE_UNAVAIL indicates that the underlying mechanism
does not support the generation or processing of non-repudiation
evidence.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Adams Document Expiration: 5 Jan. 1996 25
Using the security environment referenced by env_handle, generate an
evidence_token for non-repudiation purposes and return the
appropriate status value. An evidence_token is a signed testimony
(typically by a trusted third party such as a Timestamp Authority)
that the prot_token was "good" (e.g., was associated with valid,
non-revoked keys) on a particular date. The evidence_token will be
valid for a specified period of time from that date (this will
typically be the validity period of the evidence signer's key). The
input parameter gen_evidence_qop is used to choose an appropriate
quality of protection for non-repudiation.
The gen_evidence_QOP parameter for IDUP is defined to be a 32-bit
unsigned integer with the following bit-field assignments:
31 (MSB) (LSB) 0
--------------------------------
| U(28) | V(4) |
--------------------------------
where
U is a 28-bit Unspecified field (available for future
use/expansion);
V is a 4-bit field enumerating a range of values for the Validity
of the evidence_token.
The following V values (i.e., validity periods) are specified; other
values may be added in the future.
0001 (1) = IDUP_ONE_HOUR
-- evidence_token valid for up to 1 hour after generation
0010 (2) = IDUP_ONE_DAY
0011 (3) = IDUP_ONE_YEAR
0100 (4) = IDUP_FIVE_YEARS
0101 (5) = IDUP_TEN_YEARS
2.4.7. IDUP_Process_Evidence call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o evidence_token OCTET STRING
o proc_evidence_qop INTEGER
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o prot_token OCTET STRING
-- extracted from evidence_token by IDUP mechanism
Adams Document Expiration: 5 Jan. 1996 26
o evidence_info OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that evidence processing was successful.
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the received receipt_token failed, preventing further
processing from being performed with that token.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_EVIDENCE_UNAVAIL indicates that the underlying mechanism
does not support the generation or processing of non-repudiation
evidence.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle and the input
proc_evidence_qop, process the evidence_token and return the
appropriate status value, prot_token, and evidence information.
The proc_evidence_QOP parameter for IDUP is defined to be a 32-bit
unsigned integer with the following bit-field assignments:
31 (MSB) (LSB) 0
--------------------------------
| U(28) | F(4) |
--------------------------------
where
U is a 28-bit Unspecified field (available for future
use/expansion);
F is a 4-bit Flag field (a set of flags whose values specify the
type of environment used to validate the non-repudiation evidence)
The following F values (i.e., environment qualifiers) are specified;
other values may be added in the future.
xx0x = Certificate Revocation Lists (CRLs) not used
xx1x = CRLs used
xxx0 = Trusted time not used
xxx1 = Trusted time used
Adams Document Expiration: 5 Jan. 1996 27
The CRL flag indicates whether or not checking of Certificate
Revocation Lists is to be done during the IDUP_Process_Evidence()
call. If CRLs are not to be checked, then verification may be
successful even if the evidence signer's key has been revoked since
the evidence_token was generated.
The Trusted Time flag indicates whether or not to check the current
local time during the IDUP_Process_Evidence() call. If the current
time is not to be checked (e.g., if the local time is not trusted),
then verification may be successful even if the evidence signer's key
has expired since the evidence_token was generated (that is, if the
Validity period -- as specified by the V field of gen_evidence_qop in
IDUP_Generate_Evidence() -- has expired).
2.5. Support calls
2.5.1. Relationship to GSS-API
Support calls in IDUP-GSS-API are to be understood and used as
described in GSS-API [RFC-1508]. The calls GSS_Display_status(),
GSS_Indicate_mechs(), GSS_Compare_name(), GSS_Display_name(),
GSS_Import_name(), GSS_Release_name(), GSS_Release_buffer(), and
GSS_Release_oid_set() are unchanged.
2.5.2. IDUP_Parse_token call
Inputs:
o input_token OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o mech_type OBJECT IDENTIFIER,
o token_type INTEGER,
Return major_status codes:
o GSS_S_COMPLETE indicates that the input_token could be parsed for
both fields. The resulting values are stored in mech_type and
token_type.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o GSS_S_DEFECTIVE_TOKEN indicates that the mechanism type could be
parsed, but that either the token type could not be determined
from the input token, or the value determined did not correspond
to any valid token_type.
Adams Document Expiration: 5 Jan. 1996 28
o GSS_S_FAILURE indicates that the mechanism type could not be
parsed (for example, the token may be corrupted).
IDUP_Parse_Token() is used to return to an application the mechanism
type and token type which correspond to a given input token. Since
IDUP-GSS-API tokens are meant to be opaque to the calling
application, this function allows the application to determine
information about the token without having to violate the opaqueness
intention of IDUP. Of primary importance is the mechanism type,
which the application can then use as input to the
IDUP_Establish_Env() call in order to establish the correct
environment in which to have the token processed. The token_type may
be used to allow the application to determine whether to pass the
token to the IDUP_Start_Unprotect() call, the IDUP_Process_Evidence()
call, or the IDUP_Process_Receipt() call.
If all tokens are framed as suggested in RFC-1508, Appendix B
(mandated in the Kerberos V5 GSS mechanism [KRB5], in the SPKM GSS
Mechanism [SPKM], and in this document), then any mechanism
implementation should be able to return at least the mech_type
parameter (the token_type parameter being NULL) for any uncorrupted
input token. If the mechanism implementation whose
IDUP_Parse_token() function is being called does recognize the token,
it can return token_type so that the application can subsequently
call IDUP_Start_Unprotect(), IDUP_Process_Evidence(), or
IDUP_Process_Receipt().
No minor status return codes have been defined for this function at
this time.
2.5.2.1. The token_type Output Parameter
The following token types are defined:
IDUP_PROT_TOKEN = 1
IDUP_RECEIPT_TOKEN = 2
IDUP_RECEIPT_CHECK = 3
IDUP_EVIDENCE_TOKEN = 4
Every mechanism must be able to perform the mapping from a valid
input token to one of the above token types (for any token generated
by that mechanism).
3. Mechanism-Specific Example Scenarios
This section provides an illustrative overview of the use of two
candidate mechanism types to support the IDUP-GSS-API. This
discussion is intended primarily for readers familiar with the
specific security technologies, demonstrating how IDUP-GSS-API
functions can be used and implemented by the candidate underlying
mechanisms. It should not be regarded as constrictive to
implementations or as defining the only means through which
IDUP-GSS-API functions can be realized with each particular
underlying technology, and does not demonstrate all IDUP-GSS-API
features.
Adams Document Expiration: 5 Jan. 1996 29
3.1. PEM-compliant file protection
A PEM-compliant IDUP-GSS-API mechanism would have as its prot_token
a PEM-compliant header for a protected (encrypted and/or signed) file
[RFC-1421]. A calling application wishing to encrypt and sign a data
file would initiate an environment using IDUP_Establish_Env(),
passing in the appropriate mech_type and a FALSE receipt request in
req_flags. IDUP_Start_Protect() is called next to specify that both
encryption and authentication/integrity are desired, using the QOP
parameter to specify either particular algorithms (if the application
is aware of algorithms supported by the underlying mechanism) or
"generic" values. As well, the targ_names (possibly a set of X.500
Distinguished Names) are specified at this time to be used in the
construction of prot_token. Any targets which cannot be used as
valid recipients (for example, because they do not have public-key
certificates which can be accessed by the mechanism) are returned in
bad_targ_names.
The file is then encrypted and signed one buffer at a time using
IDUP_Protect(). As each IDUP_Protect() call returns, the application
writes output_buffer (which contains ciphertext) to the end of an
output file. After the last input_buffer has been protected, the
application calls IDUP_End_Protect(). Any residual ciphertext is
returned in output_buffer, which is then written to the end of the
output file. As well, the returned prot_token is prepended to the
beginning of the output file. The output file is the "P-IDU" which
can be transferred by any means (electronic mail, for example) to the
intended recipient(s).
Assuming that this is the only IDU to be protected at this time,
the application terminates the environment by calling
IDUP_Abolish_Env().
The recipient of the P-IDU begins by calling IDUP_Parse_Token()
to determine the mech_type of the received token (the token_type
may be redundant information for a PEM-compliant IDUP-GSS-API
mechanism, since receipts and evidence are not required for such a
mechanism). IDUP_Establish_Env() is then called to initialize the
environment.
The recipient then calls IDUP_Start_Unprotect() (passing it the
prot_token), IDUP_Unprotect() (once for each buffer of data),
and IDUP_End_Unprotect(). The decrypted output buffers are written
to an output file; after IDUP_End_Unprotect() has been called and the
returned status code indicates success, it has been verified that
this file is the original IDU which the sender protected.
The recipient then abolishes the environment by calling
IDUP_Abolish_Env().
Adams Document Expiration: 5 Jan. 1996 30
3.2. Signed-MSP-compliant file protection
An MSP-compliant IDUP-GSS-API mechanism would be virtually identical
to the PEM-compliant mechanism described above (for details regarding
MSP see [MSP]). A Signed-MSP-compliant mechanism, however, requires
a signature on the MSP IDU itself -- that is, on the MSP header and
the encapsulated (possibly encrypted) content. This can be achieved
using the prot_oper_id parameter of the IDUP_Start_Protect() call.
For example, if prot_oper_id = 1 then the protection set of calls
would produce a prot_token which is the MSP header and which is then
concatenated with the (possibly encrypted) IDU to create an MSP IDU.
If the protection set were then called again on MSP IDU with
prot_oper_id = 2, prot_token would be the signature on MSP IDU, which
would be appended to MSP IDU to create the Signed-MSP IDU (i.e., the
final P-IDU).
MSP recognizes at least two kinds of recipients, intermediate Message
Transfer Agents (MTAs) and end User Agents (UAs). An MTA may be able
to validate that a Signed-MSP IDU is valid, but only end UAs should
be able to retrieve MSP-protected data. Thus, the MTA would call the
unprotection set of calls with prot_oper_id = 2 to verify the
signature on the MSP IDU, but would be unable to successfully call
the unprotection set with prot_oper_id = 1 since it would lack the
proper credentials. A valid end UA (one of the specified targets of
the P-IDU), on the other hand, would be able to unprotect the Signed-
MSP IDU with either value of prot_oper_id.
A receipt generated by an MSP-compliant mechanism will be sent to the
IDU protector as a receipt_token and will be processed using the
IDUP_Process_Receipt() call.
4. Related Activities
In order to implement the IDUP-GSS-API atop existing, emerging, and
future security mechanisms, the following is necessary:
- object identifiers must be assigned to candidate IDUP-GSS-API
mechanisms and the name types which they support; and
- concrete data element (i.e., token) formats must be defined for
candidate mechanisms.
Calling applications must implement formatting conventions which will
enable them to distinguish IDUP-GSS-API P-IDUs from other
IDUs in their environment.
Concrete language bindings are required for the programming
environments in which the IDUP-GSS-API is to be employed; such a
binding for the C language are available in the Internet Draft
[IDUP-C].
Adams Document Expiration: 5 Jan. 1996 31
5. Acknowledgments
Many thanks are due to Warwick Ford and Paul Van Oorschot of
Bell-Northern Research, and to Denis Pinkas of Bull, for a number of
helpful comments.
6. Security Considerations
Security issues are discussed throughout this memo.
7. REFERENCES
[MSP]: U.S. National Security Agency, "Message Security
Protocol", Secure Data Network System SDN.701, March 1994.
[RFC-1421]: J. Linn, "Privacy Enhancement for Internet Electronic
Mail: Part I: Message Encryption and Authentication Procedures",
RFC 1421.
[RFC-1508]: J. Linn, "Generic Security Service Application Program
Interface", RFC 1508.
[KRB5]: J. Linn, "The Kerberos Version 5 GSS-API Mechanism",
Internet Draft draft-ietf-cat-kerb5gss-02.txt.
[SPKM]: C. Adams, "The Simple Public-Key GSS-API Mechanism
(SPKM)", Internet Draft draft-ietf-cat-spkmgss-04.txt.
[IDUP-C]: D. Grebovich, "Independent Data Unit Protection Generic
Security Service Application Program Interface: C-bindings", Internet
Draft draft-ietf-cat-idup-cbind-01.txt.
8. Author's Address
Carlisle Adams
Bell-Northern Research
P.O.Box 3511, Station C
Ottawa, Ontario, CANADA K1Y 4H7
Phone: +1 613.763.9008
E-mail: cadams@bnr.ca
Adams Document Expiration: 5 Jan. 1996 32
APPENDIX A
MECHANISM-INDEPENDENT TOKEN FORMAT
This appendix specifies a mechanism-independent level of
encapsulating representation for IDUP-GSS-API tokens, incorporating
an identifier of the mechanism type to be used when processing those
tokens. Use of this format (with ASN.1-encoded data elements
represented in BER, constrained in the interests of parsing
simplicity to the Distinguished Encoding Rule (DER) BER subset
defined in X.509, clause 8.7) is recommended to the designers of
IDUP-GSS-API implementations based on various mechanisms, so that
tokens can be interpreted unambiguously at IDUP-GSS-API peers. There
is no requirement that the mechanism-specific protToken data element
be encoded in ASN.1 BER.
-- top-level token definition to frame different mechanisms
IDUP-GSS-API DEFINITIONS ::=
BEGIN
MechType ::= OBJECT IDENTIFIER
ProtToken ::= [APPLICATION 0] IMPLICIT SEQUENCE {
thisMech MechType,
protToken ANY DEFINED BY thisMech
-- contents mechanism-specific
}
ReceiptToken ::= [APPLICATION 0] IMPLICIT SEQUENCE {
thisMech MechType,
receiptToken ANY DEFINED BY thisMech
-- contents mechanism-specific
}
EvidenceToken ::= [APPLICATION 0] IMPLICIT SEQUENCE {
thisMech MechType,
evidenceToken ANY DEFINED BY thisMech
-- contents mechanism-specific
}
END
APPENDIX B
MECHANISM DESIGN CONSTRAINTS
The following constrain on IDUP-GSS-API mechanism designs is
adopted in response to observed caller protocol requirements, and
adherence thereto is anticipated in subsequent descriptions of
IDUP-GSS-API mechanisms to be documented in standards-track Internet
specifications.
Use of the approach defined in Appendix A of this specification,
applying a mechanism type tag to the ProtToken, the ReceiptToken
(if defined), and the EvidenceToken (if defined) is required.
Adams Document Expiration: 5 Jan. 1996 33
| PAFTECH AB 2003-2026 | 2026-04-23 06:11:14 |