RFC relevance of mechanism

As per Relevance of the word mechanism, we have this rfc below:

Network Working Group C.
Request for Comments: 2479 Entrust
Category: Informational December 1998

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

Status of this

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

Copyright

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

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

Throughout the remainder of this document, the "unit" of
described in the above paragraph will be referred to as an
(Independent Data Unit). The IDU can be of any size (the
may, if it wishes, split the IDU into pieces and have the
computed a piece at a time, but the resulting protection
applies to the entire IDU). However, the primary characteristic
an IDU is that it represents a stand-alone unit of data
protection is entirely independent of any other unit of data. If
application protects several IDUs and sends them all to a
receiver, the IDUs may be unprotected by that receiver in any
over any time span; no logical connection of any kind is implied
the protection process itself

Adams Informational [Page 1]

RFC 2479 IDUP-GSS-API December 1998

As with RFC-2078, this IDUP-GSS-API definition provides
services to callers in a generic fashion, supportable with a range
underlying mechanisms and technologies and hence allowing source
level portability of applications to different environments.
specification defines IDUP-GSS-API services and primitives at a
independent of underlying mechanism and programming
environment, and is to be complemented by other,
specifications

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

TABLE OF

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

Adams Informational [Page 2]

RFC 2479 IDUP-GSS-API December 1998

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

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

During the protection operation, the input IDU buffers may
modified (for example, the data may be encrypted or encoded in
way) or may remain unchanged. In any case, the result is termed
"M-IDU" (Modified IDU) in order to distinguish it from the
IDU. Depending on the desire of the calling application and
capabilities of the underlying IDUP mechanism, the output produced
the protection processing may or may not encapsulate the M-IDU. Thus
the P-IDU may be the contents of a single output parameter (
encapsulation is done) or may be the logical concatenation of
unencapsulated token parameter and a M-IDU parameter (
encapsulation is not done). In the latter case, the
application may choose whatever method it wishes to concatenate

Adams Informational [Page 3]

RFC 2479 IDUP-GSS-API December 1998

combine the unencapsulated token and the M-IDU into a P-IDU,
the unprotecting application knows how to de-couple the P-IDU
into its component parts prior to calling the IDUP unprotection
of functions

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

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

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

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

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

It is important to note that absolutely no synchronization is
or expected between the data buffer size used by the sender as
to the protection calls, the data buffer size used by the receiver

Adams Informational [Page 4]

RFC 2479 IDUP-GSS-API December 1998

input to the unprotection calls, and the block sizes required by
underlying protection algorithms (integrity and confidentiality).
these sizes are meant to be independent; furthermore, the data
sizes used for the protection and unprotection calls are purely
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
cryptographically implemented security services at a generic
which is independent of particular underlying mechanisms.
example, IDUP-GSS-API-provided services can be implemented
secret-key technologies or public-key approaches

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

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

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

1.1. IDUP-GSS-API

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

1.1.1.

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

1.1.2.

Tokens in IDUP-GSS-API are to be understood and used as described
GSS-API [RFC-2078] with the exception that there are no context-
tokens generated by IDUP-GSS-API. The IDUP-GSS-API token
(depending on the underlying mechanism) encapsulate the M-IDU or

Adams Informational [Page 5]

RFC 2479 IDUP-GSS-API December 1998

be logically concatenated with the M-IDU prior to transfer to
target; furthermore, for some evidence services the token may be
independently of any other data transfer

1.1.3. Security

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

1.1.4. Mechanism

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

1.1.5.

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

1.1.6. Channel

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

1.2. IDUP-GSS-API Features and

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

1.2.1. Status

Status reporting in IDUP-GSS-API is to be understood and used
described in GSS-API [RFC-2078], with the addition of a number
IDUP-specific status codes. Descriptions of the major_status

Adams Informational [Page 6]

RFC 2479 IDUP-GSS-API December 1998

used in IDUP are provided in Table 1. Codes that are
(i.e., that do not cause the requested operation to fail)
indicated with the symbol "(I)".

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

Table 1: IDUP-GSS-API Major Status

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

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

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

GSS_S_COMPLETE indicates that the requested operation
successful

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

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

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

GSS_S_FAILURE indicates that the requested operation could not
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
caller lacks authorization to access the referenced credentials

IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU
origin auth. / integ. has either expired or been revoked

Adams Informational [Page 7]

RFC 2479 IDUP-GSS-API December 1998

IDUP_S_BAD_ENC_IDU indicates that decryption of the received
cannot be completed because the encrypted IDU
invalid/defective (e.g., the final block was short or
incorrect padding).

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

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

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

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

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

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

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

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

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

IDUP_S_NO_ENV indicates that no valid environment was
for the env_handle provided

Adams Informational [Page 8]

RFC 2479 IDUP-GSS-API December 1998

IDUP_S_NO_MATCH indicates that Service_Verification_Info (
evidence_check) and the P-IDU to be verified do not match

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

IDUP_S_SERVICE_UNAVAIL indicates that the underlying
does not support the service requested

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

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

1.2.2. Per-IDU Security Service

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

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

1.2.3. Per-IDU Replay Detection and

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

1.2.4. Quality of

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

The qop_algs parameter for IDUP is defined to be a 32-bit
integer with the following bit-field assignments

Adams Informational [Page 9]

RFC 2479 IDUP-GSS-API December 1998

31 (MSB) (LSB) 0
----------------------------------------------
| U(19) | TS(5) | IA(4) | MA(4) |
----------------------------------------------

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

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

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

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

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

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

Finally, if both MA and IA are zero then TS is examined. A value
zero for TS specifies the default algorithm for the
mechanism. A non-zero value for TS corresponds to a
algorithm qualifier and selects any algorithm from the
specification which satisfies that qualifier (which actual
is selected is an implementation choice; the calling application
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

Adams Informational [Page 10]

RFC 2479 IDUP-GSS-API December 1998

When qop_algs is used to select a confidentiality algorithm

00000 (0) = default confidentiality
00001 (1) = IDUP_SYM_ALG_STRENGTH_
00010 (2) = IDUP_SYM_ALG_STRENGTH_
00011 (3) = IDUP_SYM_ALG_STRENGTH_
11111 (31) = IDUP_NO_

When qop_algs is used to select a DOA/integrity algorithm

00000 (0) = default integrity
00001 (1) = IDUP_INT_ALG_DIG_
(integrity provided through a digital signature
00010 (2) = IDUP_INT_ALG_NON_DIG_
(integrity without a dig. sig. (e.g., with a MAC))
11111 (31) = IDUP_NO_

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

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

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

- TS values are specified at the IDUP-GSS-API level and
therefore portable across mechanisms. Applications which
nothing about algorithms are still able to choose "quality"
protection for their message tokens

Adams Informational [Page 11]

RFC 2479 IDUP-GSS-API December 1998

- MA values are specified at the mechanism level and are
portable across implementations of a mechanism

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

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

1.2.5. The Provision of

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

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

The IDUP calls which use a time parameter specify the type of
parameter to be INTEGER. This INTEGER is defined in all cases to
the number of seconds which have elapsed since midnight, January 1,
1970, coordinated universal time

Adams Informational [Page 12]

RFC 2479 IDUP-GSS-API December 1998

2. Interface

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

Table 2: IDUP-GSS-API

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

ENVIRONMENT-LEVEL
IDUP_Establish_
IDUP_Abolish_
IDUP_Inquire_

PER-IDU
SE (SIGN,ENCRYPT)
IDUP_SE_SingleBuffer_
IDUP_SE_SingleBuffer_
IDUP_SE_MultiBuffer_
IDUP_SE_MultiBuffer_
IDUP_SE_MultiBuffer_
IDUP_SE_MultiBuffer_
IDUP_SE_Process_
EV (EVIDENCE)
IDUP_EV_SingleBuffer_
IDUP_EV_SingleBuffer_
IDUP_EV_MultiBuffer_
IDUP_EV_MultiBuffer_
IDUP_EV_MultiBuffer_
IDUP_EV_MultiBuffer_
IDUP_EV_Process_
GP (GENERAL PROTECTION)
IDUP_Start_
IDUP_
IDUP_End_
IDUP_Start_
IDUP_
IDUP_End_

Adams Informational [Page 13]

RFC 2479 IDUP-GSS-API December 1998

SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms
IDUP_Form_Complete_

SUPPORT
IDUP_Acquire_cred_with_
IDUP_Get_Token_
IDUP_Get_Policy_
IDUP_Cancel_Multibuffer_
(see also the calls given in Section 2.4 of GSS-API [RFC-2078])

In terms of conformance to this specification, IDUP-GSS-
implementations must support the credential management calls,
environment-level calls, some subset of the per-IDU calls, and
support calls (except where explicitly stated otherwise in
2.5). The subset of per-IDU calls supported will depend upon
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
to anticipate the future needs of applications developers, but
is not required for conformance

2.1. Credential management

2.1.1. Relationship to GSS-

Credential management in IDUP-GSS-API is to be understood and used
described in GSS-API [RFC-2078]. The calls given in Section 2.1
GSS-API (including all associated parameters) are unchanged,
the interpretation of the cred_usage parameter in the GSS-API
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
combination to restrict credential usage (where OR'ing all
results in NO_RESTRICTION). Future possible values for
parameter are for further study

The call IDUP_Acquire_cred_with_auth has been added as a support
in this specification to permit authenticated credential acquirement
see Section 2.5.2 for details

Adams Informational [Page 14]

RFC 2479 IDUP-GSS-API December 1998

2.2. Environment-level

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

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

2.2.1. Relationship to GSS-

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

2.2.2. IDUP_Establish_Env

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
-- for req_mech_

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
o actual_environmentPolicies EnvironmentPolicies
-- actual values always indicated, never
o ret_services SET OF OBJECT IDENTIFIER

Return major_status codes
o GSS_S_
-- environment-level information was successfully initialized

Adams Informational [Page 15]

RFC 2479 IDUP-GSS-API December 1998

-- and IDU / P-IDU processing can begin
o GSS_S_DEFECTIVE_
o GSS_S_NO_
o GSS_S_CREDENTIALS_
-- the credentials provided through claimant_cred_handle
-- no longer valid, so environment cannot be established
o GSS_S_BAD_
o GSS_S_

The following structures are defined to facilitate environment
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
-- the policy provisions connected with credentials, if they
time
-- on input: the policy rules available at the specified
-- on output: the time at which the policy rules came into
-- (defined to be the number of seconds elapsed since midnight
-- January 1, 1970, coordinated universal time
endTime INTEGER OPTIONAL }
-- on input:
-- on output: the expiration time of the given policy

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

This routine returns an env_handle for all future references to
environment; when protection, unprotection, or IDUP_Abolish_Env()
calls are made, this handle value will be used as the
env_handle argument. It is the caller's responsibility to
a communications path to the intended recipients of the P-IDU, and
transmit the P-IDU to those recipients over that path. This
occur subsequent to the IDUP_Abolish_Env() call

Adams Informational [Page 16]

RFC 2479 IDUP-GSS-API December 1998

The req_services parameter may be used by the calling application
request that data origin authentication with integrity
confidentiality with integrity, evidence generation, and/or
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
calling application may wish to generate or verify
information for non-repudiation purposes (note: an IDU protector
request that a flag be inserted into a P-IDU asking a recipient
provide an evidence of the type "non-repudiation of delivery";
however, the IDUP-GSS-API cannot by itself guarantee that
evidence will be sent because there is no way to force a target
send an evidence_token back to the IDU protector).

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

The following OBJECT IDs are defined for protection and
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
services under that node are assigned as shown below). It
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
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

Adams Informational [Page 17]

RFC 2479 IDUP-GSS-API December 1998

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
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
UTIME = { 1.3.6.1.5.7.7.2 }
-- untrusted time

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

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

Adams Informational [Page 18]

RFC 2479 IDUP-GSS-API December 1998

2.2.3. IDUP_Abolish_Env

Input
o env_handle ENVIRONMENT

Outputs
o major_status INTEGER
o minor_status INTEGER

Return major_status codes
o GSS_S_
-- the relevant environment-specific information was flushed
o IDUP_S_NO_
o GSS_S_

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

2.2.4. IDUP_Inquire_Env

Input
o env_handle ENVIRONMENT HANDLE

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

Return major_status codes
o GSS_S_
-- referenced environment is valid and mech_type and other
-- values describe the characteristics of the environment
o GSS_S_CREDENTIALS_
o IDUP_S_NO_
o GSS_S_

This routine provides environment-related information to the caller

Adams Informational [Page 19]

RFC 2479 IDUP-GSS-API December 1998

2.3. Per-IDU

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

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

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

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

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

2.3.1. Relationship to GSS-

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

Adams Informational [Page 20]

RFC 2479 IDUP-GSS-API December 1998

2.3.2. The "SE"

2.3.2.1. IDUP_SE

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

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

The SE calls may be viewed by mechanism implementors as an "API"
the more powerful GP calls defined later and so may be implemented
simple mapping functions to those calls (when those optional
are supported). Application callers, on the other hand, may
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
"directed receipts" types of services, they may consider using the
calls (or the GP calls -- when these are supported -- if complex
sophisticated combinations of services are required). To assist
this migration path, mechanism implementors are encouraged to
the full set of IDUP calls (i.e., the SE, EV, and GP calls)
though some calling applications will only use the SE calls in
short term

2.3.2.2. IDUP_SE Parameter

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

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

Adams Informational [Page 21]

RFC 2479 IDUP-GSS-API December 1998

o Protect_Options PARAMETER
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
clear_sign_only (6)
} OPTIONAL
o protect_oper_oid OBJECT IDENTIFIER OPTIONAL
-- may be used in place of above parameter if OID is
o sign_qop_alg UNSIGNED INTEGER
o sign_qop_algID AlgorithmIdentifier, --overrides sign_qop_
o enc_qop_alg UNSIGNED INTEGER
o enc_qop_algID AlgorithmIdentifier, --overrides enc_qop_
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
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
-- 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
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

Adams Informational [Page 22]

RFC 2479 IDUP-GSS-API December 1998

2.3.2.3. IDUP_SE major_status

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

o GSS_S_
o IDUP_S_MORE_OUTBUFFER_
-- returned (by any SE call) to indicate that there is more
-- data than can fit into the supplied buffers. The
-- should save the returned data and call again to retrieve
-- remaining output
o IDUP_S_MORE_PIDU_
-- indicates that more PIDU data is needed for the
-- operation (e.g., so that PIDU_Information or initial_idu_
-- may be returned).
o IDUP_S_INCONSISTENT_
o GSS_S_CREDENTIALS_
o IDUP_S_NO_
o GSS_S_BAD_
o GSS_S_

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

o IDUP_S_BAD_TARG_

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

2.3.2.4. IDUP_SE_SingleBuffer_Protect

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

Adams Informational [Page 23]

RFC 2479 IDUP-GSS-API December 1998

Outputs
o major_status INTEGER
o minor_status INTEGER
o pidu_buffer OCTET STRING
o sig_token OCTET
-- used if Protect_Options is clear_sign_

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

2.3.2.5. IDUP_SE_SingleBuffer_Unprotect

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

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

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

2.3.2.6. IDUP_SE_MultiBuffer_StartProtect

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

Adams Informational [Page 24]

RFC 2479 IDUP-GSS-API December 1998

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

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

2.3.2.7. IDUP_SE_MultiBuffer_EndProtect

Inputs
o env_handle ENVIRONMENT

Outputs
o major_status INTEGER
o minor_status INTEGER
o final_pidu_buffer OCTET STRING
o sig_token OCTET
-- used if Protect_Options was clear_sign_

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

2.3.2.8. IDUP_SE_MultiBuffer_StartUnprotect

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

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

Adams Informational [Page 25]

RFC 2479 IDUP-GSS-API December 1998

o initial_idu_buffer OCTET
-- may be

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

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

2.3.2.9. IDUP_SE_MultiBuffer_EndUnprotect

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

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

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

2.3.2.10. IDUP_SE_Process_Buffer

Inputs
o env_handle ENVIRONMENT HANDLE
o input_buffer OCTET STRING

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

Adams Informational [Page 26]

RFC 2479 IDUP-GSS-API December 1998

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

2.3.3. The "EV"

2.3.3.1. IDUP_EV

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

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

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

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

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

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

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

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

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

o Tokens including the associated data

Adams Informational [Page 27]

RFC 2479 IDUP-GSS-API December 1998

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

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

Calls that are specific to the support of evidence include

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

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

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