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.
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
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
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
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
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
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.
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.
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:
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.
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.
- 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.
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
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.
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,
-- 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.
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"
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).
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.
2.3. Per-IDU calls
This group of calls is used to perform IDU protection and
unprotection processing on an established IDUP environment. Some of
these calls may block pending network interactions (depending on the
underlying mechanism in use). These calls may be invoked by an IDU's
protector or by the P-IDU's recipient. Members of this group form
pairs; the output from the protection types of calls is typically
meant to be input to the unprotection types of calls.
The per-IDU calls can support caller-requested data origin
authentication with data integrity, confidentiality with data
integrity, evidence, and evidence-requested-from-target services.
The protection operations output a token which encapsulates all the
information required to unprotect the IDU. The token is passed to
the target (possibly separate from the M-IDU) and is processed by the
unprotection calls at that system. Unprotection performs
decipherment, DOA verification, evidence verification, or
notification of evidence requested, as required.
Each of the two main operations (protection and unprotection) may be
separated into three parts: "Start_Operation"; "Operation" (which
may be called once for each buffer of input data); and
"End_Operation". This separation is available for the case where the
IDU or P-IDU is to be processed one buffer at a time.
"Start_Operation" allows the caller to specify or retrieve the
appropriate "Quality" used during the processing. "Operation" is
concerned with the processing itself, receiving a buffer of input
data and potentially returning a buffer of output data.
"End_Operation" performs any required clean-up and creates the
appropriate token or states whether the input token was verified.
If the IDU or P-IDU is wholly contained in a single buffer, the
three-part protection/unprotection processing need not be done.
Instead, protection or unprotection can be accomplished using only a
single call, simplifying application code.
2.3.1. Relationship to GSS-API
The set of calls described in this section is used in place of the
calls GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() which
are specified in [RFC-2078], since those calls are specific to a
session-oriented environment.
2.3.2. The "SE" Calls
2.3.2.1. IDUP_SE Purpose
The "SE" group of calls provides a very simple, high-level interface
to underlying IDUP mechanisms when application developers need access
only to signature and encryption protection/unprotection services.
It includes both the single-buffer and multiple-buffer IDU cases and
can be used for signing only, encrypting only, signing and encrypting
(in either order, and with or without visibility of the resulting
signature), and "clear signing" (where the data is not modified in
any way and the signature itself is returned as a separate item).
[Note that encapsulation occurs in all cases except for clear
signing, so that these calls provide functionality similar to the
GSS_Wrap call.]
Note that the term "signing" is used in its most generic sense, not
necessarily implying the use of public-key techniques. This concept
has also been called "sealing" in other contexts (e.g., in other
standardization efforts).
The SE calls may be viewed by mechanism implementors as an "API" to
the more powerful GP calls defined later and so may be implemented as
simple mapping functions to those calls (when those optional calls
are supported). Application callers, on the other hand, may find
that the SE calls are all they currently need for many environments.
At some time in the future when they have need of non-repudiation or
"directed receipts" types of services, they may consider using the EV
calls (or the GP calls -- when these are supported -- if complex and
sophisticated combinations of services are required). To assist in
this migration path, mechanism implementors are encouraged to support
the full set of IDUP calls (i.e., the SE, EV, and GP calls) even
though some calling applications will only use the SE calls in the
short term.
2.3.2.2. IDUP_SE Parameter Bundles
The concept of "parameter bundles" is used in the calls presented in
the following subsections in order to simplify their presentation and
clarify their intended purpose and use. See Section 2.3.4.1 for a
more complete description of parameter bundles.
The following parameter bundles are used in the "SE" protection and
unprotection sets of calls.
o Protect_Options PARAMETER BUNDLE
o protect_operation INTEGER {
sign_only (0),
encrypt_only (1),
sign_and_encrypt (2),
-- let mechanism choose order (and readability of signature)
sign_then_encrypt_data (3),
-- sign, then encrypt plaintext (leaving signature in clear)
sign_then_encrypt_full (4),
-- sign, then encrypt everything (including signature)
encrypt_then_sign (5),
-- encrypt, then sign the ciphertext
clear_sign_only (6)
} OPTIONAL,
o protect_oper_oid OBJECT IDENTIFIER OPTIONAL,
-- may be used in place of above parameter if OID is known
o sign_qop_alg UNSIGNED INTEGER,
o sign_qop_algID AlgorithmIdentifier, --overrides sign_qop_alg
o enc_qop_alg UNSIGNED INTEGER,
o enc_qop_algID AlgorithmIdentifier, --overrides enc_qop_alg
o idu_type_string OCTET STRING,
-- type of the IDU ("data", "e-mail doc", MIME type, etc.)
o pidu_type_string OCTET STRING,
o mech_indep_encap_req BOOLEAN -- (see Appendix A)
o PIDU_Information PARAMETER BUNDLE
o protect_options Protect_Options,
o originator_name INTERNAL NAME,
o originator_role Originator_Role, -- (see Section 2.3.4.1)
o protection_time INTEGER,
o Bad_Target_Name PARAMETER BUNDLE, -- same as in Section 2.3.3.2
o bad_targ_name INTERNAL NAME,
o bad_targ_status INTEGER,
-- a status flag giving the reason for rejection of the name
-- in bad_targ_name. Specified reasons include:
-- SYNTAX_INVALID (0) the syntax of the name is invalid;
-- NAME_UNRECOGNIZED (1) the name is not recognized;
-- NAME_AMBIGUOUS (2) the name cannot be resolved;
-- ACCESS_DENIED (3) access to this target is denied;
-- CERTIFICATE_NOT_FOUND (4) the encryption certificate of the
target could not be found.
o Target_Info PARAMETER BUNDLE, -- same as in Section 2.3.3.2
o targ_names SET OF INTERNAL NAME,
o bad_targ_count INTEGER,
o bad_target_names SET OF Bad_Target_Name,
2.3.2.3. IDUP_SE major_status codes
The following major_status return codes are defined for the "SE"
calls in this section:
o GSS_S_COMPLETE
o IDUP_S_MORE_OUTBUFFER_NEEDED
-- returned (by any SE call) to indicate that there is more output
-- data than can fit into the supplied buffers. The application
-- should save the returned data and call again to retrieve the
-- remaining output.
o IDUP_S_MORE_PIDU_NEEDED
-- indicates that more PIDU data is needed for the StartUnprotect