One document matched: draft-ietf-cat-idup-gss-06.txt
Differences from draft-ietf-cat-idup-gss-05.txt
Internet Draft C. Adams, Nortel
draft-ietf-cat-idup-gss-06.txt Nov. 26, 1996
Independent Data Unit Protection Generic Security Service
Application Program Interface (IDUP-GSS-API)
STATUS OF THIS MEMO
This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by
other documents at any time. It is inappropriate to use Internet-
Drafts as reference material or to cite them other than as
"work in progress."
To learn the current status of any Internet Draft, please check the
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
Directories on ds.internic.net (US East Coast), nic.nordu.net
(Europe), ftp.isi.edu (US West Coast) or munnari.oz.au (Pacific Rim).
Comments on this document should be sent to "cat-ietf@mit.edu", the
IETF Common Authentication Technology WG discussion list.
ABSTRACT
The IDUP-GSS-API extends the GSS-API [RFC-1508] for applications
requiring protection of a generic data unit (such as a file or
message) in a way which is independent of the protection of any other
data unit and independent of any concurrent contact with designated
"receivers" of the data unit. Thus, it is suitable for applications
such as secure electronic mail where data needs to be protected
without any on-line connection with the intended recipient(s) of that
data. 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.
Adams Document Expiration: 26 May 1997 1
As with RFC-1508, this IDUP-GSS-API definition provides security
services to callers in a generic fashion, supportable with a range of
underlying mechanisms and technologies and hence allowing source-
level portability of applications to different environments. This
specification defines IDUP-GSS-API services and primitives at a level
independent of underlying mechanism and programming language environ-
ment, and is to be complemented by other, related specifications:
- documents defining specific parameter bindings for particular
language environments;
- documents defining token formats, protocols, and procedures to
be implemented in order to realize IDUP-GSS-API services atop
particular security mechanisms.
TABLE OF CONTENTS
1. IDUP-GSS-API Characteristics and Concepts .................. 3
1.1. IDUP-GSS-API Constructs .................................. 5
1.1.1. Credentials ............................................ 5
1.1.2. Tokens ................................................. 5
1.1.3. Security Environment ................................... 5
1.1.4. Mechanism Types ........................................ 5
1.1.5. Naming ................................................. 5
1.1.6. Channel Bindings ....................................... 6
1.2. IDUP-GSS-API Features and Issues ......................... 6
1.2.1. Status Reporting ....................................... 6
1.2.2. Per-IDU Security Service Availability .................. 7
1.2.3. Per-IDU Replay Detection and Sequencing ................ 7
1.2.4. Quality of Protection .................................. 7
1.2.5. The Provision of Time .................................. 10
2. Interface Descriptions ..................................... 10
2.1. Credential management calls .............................. 11
2.1.1. Relationship to GSS-API ................................ 11
2.2. Environment-level calls .................................. 12
2.2.1. Relationship to GSS-API ................................ 12
2.2.2. IDUP_Establish_Env call ................................ 13
2.2.3. IDUP_Abolish_Env call .................................. 15
2.2.4. IDUP_Inquire_Env call .................................. 16
2.3. Per-IDU calls ............................................ 17
2.3.1. Relationship to GSS-API ................................ 17
2.3.2. Parameter Bundles ...................................... 17
2.3.3. IDUP_Start_Protect ..................................... 21
2.3.4. IDUP_Protect ........................................... 24
2.3.5. IDUP_End_Protect ....................................... 25
2.3.7. IDUP_Start_Unprotect ................................... 27
2.3.8. IDUP_Unprotect ......................................... 30
2.3.9. IDUP_End_Unprotect ..................................... 31
2.4. Special-Purpose calls .................................... 35
2.4.1. Relationship to GSS-API ................................ 35
2.4.5. IDUP_Form_Complete_PIDU ................................ 35
2.5. Support calls ............................................ 37
2.5.1. Relationship to GSS-API ................................ 37
2.5.2. IDUP_Parse_token call .................................. 37
2.5.3. IDUP_Get_Policy_Info ................................... 38
Adams Document Expiration: 26 May 1997 2
3. Related Activities ......................................... 40
4. Acknowledgments ............................................ 40
5. Security Considerations .................................... 40
6. References ........................................... 41
7. Author's Address ........................................... 41
Appendix A, ................................................... 42
Appendix B .................................................... 43
1. IDUP-GSS-API Characteristics and Concepts
The paradigm within which IDUP-GSS-API operates is as follows. An
IDUP-GSS-API caller is any application which works with IDUs, calling
on IDUP-GSS-API in order to protect its IDUs with 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 must be passed to an IDUP-GSS-API
implementation for processing. The security services available
through IDUP-GSS-API in this fashion are implementable over a range
of underlying mechanisms based on secret-key and/or public-key
cryptographic technologies.
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 token produced by
the protection processing may or may not encapsulate the M-IDU.
Thus, the P-IDU may be the token alone (if encapsulation is done) or
may be the logical concatenation of the token and the M-IDU (if
encapsulation is not done). In the latter case, the protecting
application may choose whatever method it wishes to concatenate or
combine the 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.
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.
Adams Document Expiration: 26 May 1997 3
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 IDUP_Start_Protect(), IDUP_Protect() for each buffer
of data, and IDUP_End_Protect() to complete 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 IDUP_Start_Unprotect(),
IDUP_Unprotect() for each buffer of data, and IDUP_End_Unprotect()
to complete the P-IDU unprotection. The receiver then calls
IDUP_Abolish_Env() to flush all environment-specific information.
It is important to note that absolutely no synchronization is implied
or expected between the data buffer size used by the sender as input
to the protection calls, the data buffer size used by the receiver as
input to the unprotection calls, and the block sizes required by the
underlying protection algorithms (integrity and confidentiality).
All these sizes are meant to be independent; furthermore, the data
buffer sizes used for the protection and unprotection calls are
purely a function of the local environment where the calls are made.
The IDUP-GSS-API design assumes and addresses several basic goals,
including the following.
Mechanism independence: The IDUP-GSS-API defines an interface to
cryptographically implemented security services at a generic level
which is independent of particular underlying mechanisms. For
example, IDUP-GSS-API-provided services can be implemented by
secret-key technologies or public-key approaches.
Protocol environment independence: The IDUP-GSS-API is independent
of the communications protocol suites which may be used to
transfer P-IDUs, permitting use in a broad range of protocol
environments.
Protocol association independence: The IDUP-GSS-API's security
environment construct 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.
Adams Document Expiration: 26 May 1997 4
Suitability for a range of implementation placements: IDUP-GSS-API
clients are not constrained to reside within any Trusted Computing
Base (TCB) perimeter defined on a system where the IDUP-GSS-API is
implemented; security services are specified in a manner suitable
for both intra-TCB and extra-TCB callers.
1.1. IDUP-GSS-API Constructs
This section describes the basic elements comprising the
IDUP-GSS-API.
1.1.1. Credentials
Credentials in IDUP-GSS-API are to be understood and used as
described in GSS-API [RFC-1508].
1.1.2. Tokens
Tokens in IDUP-GSS-API are to be understood and used as described in
GSS-API [RFC-1508] with the exception that there are no context-level
tokens generated by IDUP-GSS-API. The IDUP-GSS-API token
may (depending on the underlying mechanism) encapsulate the M-IDU or
may be logically concatenated with 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-1508]. Here, a
security environment exists within a calling application (that is, it
is purely local to the caller) for the purpose of protecting or
unprotecting one or more IDUs using a particular caller credential 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-1508].
1.1.5. Naming
Naming in IDUP-GSS-API is to be understood and used as described in
GSS-API [RFC-1508].
Adams Document Expiration: 26 May 1997 5
1.1.6. Channel Bindings
The concept of channel bindings discussed in GSS-API [RFC-1508] is
not relevant to the IDUP-GSS-API.
1.2. IDUP-GSS-API Features and Issues
This section describes aspects of IDUP-GSS-API operations and of the
security services which the IDUP-GSS-API provides. It also provides
commentary on design issues.
1.2.1. Status Reporting
Status reporting in IDUP-GSS-API is to be understood and used as
described in GSS-API [RFC-1508], with the addition of the following
IDUP-GSS-API major status codes.
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
Fatal Error Codes
IDUP_S_BAD_TARG_INFO all target information is invalid or
unsuitable for IDU protection
IDUP_S_BAD_DOA_KEY DOA key has expired or been revoked
IDUP_S_BAD_KE_KEY key used for key establishment between
orig. and targ. has exp. or been revoked
IDUP_S_BAD_ENC_IDU encrypted IDU is defective/invalid
IDUP_S_INCOMPLETE
there is not enough info. in token for P-IDU verification
IDUP_S_SERV_VERIF_INFO_NEEDED
the Service_Verification_Info parameter bundle is required
IDUP_S_SERVICE_UNAVAIL mech. does not support requested service
IDUP_S_REQ_TIME_SERVICE_UNAVAIL
the time service requested is not avail. in this environment
IDUP_S_INAPPROPRIATE_CRED
the credentials supplied cannot be used to unprotect P-IDU
Adams Document Expiration: 26 May 1997 6
IDUP_S_NO_ENV no environment recognized for env_handle
IDUP_S_NO_MATCH Service_Verification_Info and input token
do not match
IDUP_S_UNKNOWN_OPER_ID requested operation id. is unsupported
Informatory Status Codes
IDUP_S_ENCAPSULATION_UNAVAIL
encapsulation of M-IDU into pidu_buffer is not supported
IDUP_S_MORE_PIDU_NEEDED
more p-idu data is needed for IDUP_Start_Unprotect()
IDUP_S_MORE_DATA_NEEDED
more data is needed for protection or unprotection
1.2.2. Per-IDU Security Service Availability
Per-IDU security service availability in IDUP-GSS-API is to be
understood and used as described in GSS-API [RFC-1508], with the
exception that any combination of services requested by the calling
application and supported by the underlying mechanism can be applied
simultaneously to any IDU.
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-1508] is not relevant to the IDUP-GSS-API.
1.2.4. Quality of Protection
The concept of QOP control in IDUP-GSS-API is to be understood
essentially as described in GSS-API [RFC-1508]. However, the actual
description and use of the QOP parameter is given as follows.
Adams Document Expiration: 26 May 1997 7
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
Adams Document Expiration: 26 May 1997 8
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 confiden-
tiality 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 confiden-
tiality 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).
Adams Document Expiration: 26 May 1997 9
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.
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 (an asterisk marks the calls which are identical to
the GSS-API specification).
Table 2: IDUP-GSS-API Calls
CREDENTIAL MANAGEMENT
* GSS_Acquire_cred acquire credentials for use
* GSS_Release_cred release credentials after use
* GSS_Inquire_cred display information about credentials
* GSS_Add_cred add credential info. (see [GSSv2])
ENVIRONMENT-LEVEL CALLS
IDUP_Establish_Env establish IDUP environment (to protect and
unprotect IDUs)
IDUP_Abolish_Env abolish env. when no longer needed
IDUP_Inquire_Env indicate characteristics of env.
Adams Document Expiration: 26 May 1997 10
PER-IDU CALLS
IDUP_Start_Protect begin the protection process
IDUP_Protect protect the IDU (perhaps 1 buffer at a time)
IDUP_End_Protect end the protection process; create a token
which contains info. necessary for the
legitimate receiver(s) of the P-IDU to
unprotect it
IDUP_File_Protect protect an IDU (input as a file)
IDUP_Start_Unprotect begin the unprotect process
IDUP_Unprotect use the token to unprotect the P-IDU
(possibly one buffer at a time)
IDUP_End_Unprotect end the unprotect process
IDUP_File_Unprotect unprotect a P-IDU (input as a file)
SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms)
IDUP_Form_Complete_PIDU insert in P-IDU any data not provided
by the protection call(s)
SUPPORT CALLS
* GSS_Display_status translate status codes to printable form
* GSS_Indicate_mechs indicate mech_types supported on local
system
* GSS_Compare_name compare two names for equality
* GSS_Display_name translate name to printable form
* GSS_Import_name convert printable name to normalize form
* GSS_Release_name free storage of normalized-form name
* GSS_Release_buffer free storage of printable name
* GSS_Release_oid_set free storage of OID set
IDUP_Parse_Token examine an input token to determine mech_type
IDUP_Get_Policy_Info return policy info. for a given policy_id
2.1. Credential management calls
2.1.1. Relationship to GSS-API
Credential management in IDUP-GSS-API is to be understood and used as
described in GSS-API [RFC-1508]. The calls GSS_Acquire_cred(),
GSS_Release_cred(), and GSS_Inquire_cred() are unchanged (the call
GSS_Add_cred() from GSS-API v2 [GSSv2] is also included). However,
the interpretation (and possible modification) of the cred_usage
parameter for IDUP purposes is for further study.
Adams Document Expiration: 26 May 1997 11
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 are used in place of the
calls GSS_Init_sec_context(), GSS_Accept_sec_context(),
GSS_Delete_sec_context(), GSS_Process_context_token(), and
GSS_Context_time() which are described in [RFC-1508], since those
calls are specific to a session-oriented environment.
Adams Document Expiration: 26 May 1997 12
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_policy OBJECT IDENTIFIER,
-- NULL parameter specifies "use default".
-- This environment-level policy identifier is separate from
-- the policy provisions connected with credentials, if they exist
o policy_time INTEGER,
-- the security policy rules available at the specified time
-- NULL parameter specifies "use default"
o req_services SET OF OBJECT IDENTIFIER,
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_policy OBJECT IDENTIFIER,
-- actual policy always indicated, never NULL
o actual_policy_time,
-- actual time at which the above policy rules came into effect
o ret_services SET OF OBJECT IDENTIFIER,
Return major_status codes:
o GSS_S_COMPLETE indicates that environment-level information was
successfully initialized, and that IDU / P-IDU processing can
begin on the newly-established environment.
o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
performed on the credential structure referenced by
claimant_cred_handle failed, preventing further processing from
being performed using that credential structure.
o GSS_S_NO_CRED indicates that no environment was established,
either because the input cred_handle was invalid or because the
caller lacks authorization to access the referenced credentials.
Adams Document Expiration: 26 May 1997 13
o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided
through the input claimant_cred_handle argument are no longer
valid, so environment establishment cannot be completed.
o GSS_S_BAD_MECH indicates that a mech_type unsupported by the
IDUP_GSS-API implementation was requested, causing the
environment establishment operation to fail.
o GSS_S_FAILURE indicates that environment setup could not be
accomplished for reasons unspecified at the IDUP-GSS-API level,
and that no interface-defined recovery action is available.
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 prerogative 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".
Adams Document Expiration: 26 May 1997 14
The following OBJECT IDs are defined for protection and unprotection
services. It is recognized that this list may grow over time.
PER_CONF = { xx }
-- perform data confidentiality (i.e., encrypt data)
PER_DOA = { xx }
-- perform data origin authentication with data integrity
PER_POO = { xx }
-- perform (i.e., create) non-repudiable "proof of origin"
PER_POD = { xx }
-- perform (i.e., create) non-repudiable "proof of delivery"
REC_CONF = { xx }
-- receive data confidentiality (i.e., decrypt data)
REC_DOA = { xx }
-- receive / verify DOA with data integrity
REC_POO = { xx }
-- receive / verify "proof of origin"
REC_POD = { xx }
-- receive / verify "proof of delivery"
TTIME = { xx }
-- trusted time availability
UTIME = { xx }
-- 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 through
a confidentiality service input to IDUP_Start_Protect() 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 using the gss_release_cred() call), 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,
Adams Document Expiration: 26 May 1997 15
Return major_status codes:
o GSS_S_COMPLETE indicates that the environment was recognized and
that relevant environment-specific information was flushed.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided, so no deletion was performed.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
This call is made to flush environment-specific information. (Once an
environment is established, cached credential and environment-related
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 env.
o policy OBJECT IDENTIFIER, -- the policy used in this env.
o policy_time, -- time at which the policy rules came into effect
o ret_services SET OF OBJECT IDENTIFIER,
Return major_status codes:
o GSS_S_COMPLETE indicates that the referenced environment is valid
and that mech_type and other return values describe the
corresponding characteristics of the environment.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided, so no return values can be provided.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
This routine provides environment-related information to the caller.
Adams Document Expiration: 26 May 1997 16
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. The two sets of members of
this group form a pair; the output from the protection set is
typically meant to be input to the unprotection set.
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 and unprotection can be accomplished using only
the "Start_Operation" call, simplifying application code.
2.3.1. Relationship to GSS-API
The set of calls described in this section are used in place of the
calls GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() -- now
named GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() --
which are specified in [RFC-1508], since those calls are specific to
a session-oriented environment.
Adams Document Expiration: 26 May 1997 17
2.3.2. The "SE" Calls
2.3.2.1. 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.2 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),
clear_sign_only (3)
}
o sign_qop_alg UNSIGNED INTEGER,
o enc_qop_alg UNSIGNED INTEGER,
o idu_type_string OCTET STRING
o PIDU_Information PARAMETER BUNDLE
o Protect_Options PARAMETER BUNDLE,
o originator_name INTERNAL NAME,
o protection_time INTEGER
o Bad_Target_Name PARAMETER BUNDLE,
o bad_targ_name INTERNAL NAME,
o bad_targ_status INTEGER,
-- a (mechanism-defined) status flag giving the reason
-- for rejection of the name in bad_targ_name
o Target_Info PARAMETER BUNDLE,
o targ_names SET OF INTERNAL NAME,
o bad_targ_count INTEGER,
o Bad_Target_Name PARAMETER BUNDLE,
2.3.2.2. IDUP_SE major_status codes
The following major_status return codes are defined for the "SE"
calls in this section:
o GSS_S_COMPLETE indicates that the requested operation has
completed successfully.
o GSS_S_CONTINUE_NEEDED 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 data.
o IDUP_S_MORE_DATA_NEEDED indicates that more input data is needed
for the StartUnprotect operation (e.g., so that PIDU_Information
or initial_idu_buffer may be returned).
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
Adams Document Expiration: 26 May 1997 18
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o GSS_S_BAD_QOP indicates that the provided qop_alg value is not
recognized or supported for the environment.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
If Target_Info is used as an input parameter (i.e., if an encryption
operation is being performed), the following major_status return code
is also defined:
o IDUP_S_BAD_TARG_INFO indicates that all the information regarding
the target(s) is invalid or is insufficient for the protection of
an IDU, so P-IDU cannot be created.
Note for this return code that if one or more of the targets in
targ_names cannot be used as a valid recipient of the P-IDU, these
names will be returned in bad_targ_names (with associated status
codes in bad_targ_status). As long as at least one of the targets
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 the
caller's prerogative to discontinue IDU protection if the target set
which can be used is unsuitable for the caller's purposes.
2.3.2.3. 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 (where the signature is computed on the cleartext data and
the signature itself is not encrypted), and "clear signing" (where
the data is not modified in any way and the signature itself is
returned (unencapsulated) as a separate item).
The SE calls may be viewed by mechanism implementors as an "API" to
the more powerful Protection and Unprotection sets of calls defined
later and so may be implemented as simple mapping functions to those
calls. Application callers, on the other hand, may find that the SE
calls are all they currently need for many environments and may
migrate to the more general calls only at some time in the future
when they have need of data labeling, non-repudiation, or "directed
receipts" types of services. To assist in this migration path, it
is recommended that mechanism implementors support the full set of
IDUP calls (i.e., both the SE calls and the more powerful calls) even
though some calling applications will only use the SE calls in the
short term.
Adams Document Expiration: 26 May 1997 19
2.3.2.4. IDUP_SE_SingleBuffer_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o Protect_Options PARAMETER BUNDLE,
o Target_Info PARAMETER BUNDLE,
-- used if Protect_Options is encrypt_only or sign_and_encrypt
o idu_buffer OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o pidu_buffer OCTET STRING,
o sig_token OCTET STRING
-- used if Protect_Options is clear_sign_only
Using the security environment referenced by env_handle, encrypt
and/or sign the supplied IDU. If "clear signing" is performed, the
signature will be returned in sig_token and pidu_buffer may be empty
(depends on underlying mechanism).
2.3.2.5. IDUP_SE_SingleBuffer_Unprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o pidu_buffer OCTET STRING,
-- may contain an IDU if sig_token is non-NULL (i.e., if
-- clear_sign_only protection was applied)
o sig_token OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o idu_buffer OCTET STRING,
-- may be empty if clear_sign_only protection was applied (depends
-- on underlying mechanism)
o PIDU_Information PARAMETER BUNDLE
Using the security environment referenced by env_handle, decrypt
and/or verify the supplied PIDU and return the contained IDU along
with all available PIDU_Information.
2.3.2.6. IDUP_SE_MultiBuffer_StartProtect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o Protect_Options PARAMETER BUNDLE,
o Target_Info PARAMETER BUNDLE
-- used if Protect_Options is encrypt_only or sign_and_encrypt
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o initial_pidu_buffer OCTET STRING
-- may be empty (depends on underlying mechanism)
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of signing
and/or encrypting the IDU (which will be supplied in multiple buffers
to the Process_Buffer call).
Adams Document Expiration: 26 May 1997 20
2.3.2.7. IDUP_SE_MultiBuffer_EndProtect call
Inputs:
o env_handle ENVIRONMENT HANDLE
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o final_pidu_buffer OCTET STRING,
o sig_token OCTET STRING
-- used if Protect_Options was clear_sign_only
Using the security environment referenced by env_handle, complete the
protection processing on the data and place the computed output in
final_pidu_buffer and/or sig_token. Successful application of
IDUP_SE_MultiBuffer_EndProtect() does not guarantee that unprotection
can necessarily be performed successfully when the P-IDU arrives at
the target (for example, it may be damaged in transit).
2.3.2.8. IDUP_SE_MultiBuffer_StartUnprotect call
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;
-- if NULL, then sig_token must be supplied
o sig_token OCTET STRING
-- used if Protect_Options was clear_sign_only;
-- if NULL, then sign_qop_alg_in must be supplied
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o PIDU_Information PARAMETER BUNDLE,
-- returns all available information
o initial_idu_buffer OCTET STRING
-- may be empty
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of decrypting
and/or verifying the PIDU (which will be supplied in multiple buffers
to the Process_Buffer call).
2.3.2.9. IDUP_SE_MultiBuffer_EndUnprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o sig_token OCTET STRING
-- used if Protect_Options was clear_sign_only
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o PIDU_Information PARAMETER BUNDLE,
-- returns all available information
o final_idu_buffer OCTET STRING
-- may be empty
Using the security environment referenced by env_handle, complete the
decryption and/or verification processing on the data and place any
residual output in final_idu_buffer.
Adams Document Expiration: 26 May 1997 21
2.3.2.10. IDUP_SE_Process_Buffer call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o input_buffer OCTET STRING,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_buffer OCTET STRING
-- may be zero length (depends on underlying mechanism and
-- corresponding Start() call and Protect_Options value)
Using the security environment referenced by env_handle, continue the
processing on the data in input_buffer and, if it is available, put
any resulting output data in output_buffer. The application calls
this routine over and over again with new buffers of data until it
has processed all the data buffers of the IDU/PIDU. It then calls
the appropriate End() call to complete the processing.
2.3.2. Parameter Bundles
The concept of "parameter bundles" is used in the calls presented in
the following subsections in order to simplify their presentation and
(hopefully) clarify their intended purpose and use. A parameter
bundle is simply a set of closely-related parameters of a call which
are either all used by / available to the calling application or all
not used by / unavailable to the calling application. These
parameters may be all input parameters, all output parameters, or
any combination of the two.
Adams Document Expiration: 26 May 1997 22
A typical use envisioned for parameter bundles in a language such as
C would be as a structure, where individual parameters in the bundle
are structure members. The calling application wishing to use a
particular bundle would then allocate the appropriate structure
variable, assign the desired input values to the appropriate members,
and pass the address of the structure as the bundle "parameter". On
output, the values of the appropriate output members may be read. An
application not wishing to use a particular bundle (or one which is
satisfied with default values for all input parameters of the bundle
and which doesn't care about output values), can pass NULL as the
bundle "parameter". From the mechanism implementor's perspective, if
a parameter bundle is not supported (for example, if it represents a
security service which is not supported by the implementation), then
any non-NULL value passed as the bundle parameter will generate an
error status return code.
The following parameter bundles are used in the subsequent protection
and unprotection sets of calls. A parameter preceded by "(I)" is an
input parameter; one preceded by "(O)" is an output parameter; one
preceded by neither is an input if the bundle itself is an input and
is an output if the bundle itself is an output; one preceded by "(X)"
is the opposite: an output if the bundle itself is an input and an
input if the bundle itself is an output.
o Mech_Specific_Info PARAMETER BUNDLE
-- actual parameters included in this bundle are defined by (and
-- specific to) the underlying mechanism
o Sensitivity PARAMETER BUNDLE,
-- actual parameters included in this bundle are defined by (and
-- specific to) the underlying mechanism, but may include
-- codified values for "Unclassified", "Secret", "Top Secret",
-- and so on
o Service_Creation_Info PARAMETER BUNDLE
-- actual parameters included in this bundle are defined by (and
-- specific to) the underlying mechanism, but it is mandatory
-- that they include at least service_id and Quality
o Service_Verification_Info PARAMETER BUNDLE
-- actual parameters included in this bundle are defined by (and
-- specific to) the underlying mechanism, but it is mandatory
-- that they include at least service_id and Quality
o Quality PARAMETER BUNDLE
o qop_algs UNSIGNED INTEGER,
o validity UNSIGNED INTEGER,
-- protection guaranteed to be valid until time specified
o policy_id OBJECT IDENTIFIER,
-- security policy under which protection is/was carried out
o allow_policy_mapping BOOLEAN,
-- determines whether mapping between policy IDs is allowed
Adams Document Expiration: 26 May 1997 23
o Idu_Information PARAMETER BUNDLE,
o idu_type_oid OBJECT IDENTIFIER,
o idu_type_string OCTET STRING,
o idu_title OCTET STRING,
o idu_sensitivity Sensitivity,
o pidu_type_oid OBJECT IDENTIFIER,
o pidu_type_string OCTET STRING,
o pidu_title OCTET STRING,
o pidu_sensitivity Sensitivity,
o Prot_Information PARAMETER BUNDLE,
o originator_name INTERNAL NAME,
o idu_information Idu_Information,
o protection_time INTEGER,
o Special_Conditions PARAMETER BUNDLE,
o prot_oper_id INTEGER,
o use_trusted_time BOOLEAN,
o use_untrusted_time BOOLEAN,
o Bad_Target_Name PARAMETER BUNDLE,
o (O) bad_targ_name INTERNAL NAME,
o (O) bad_targ_status INTEGER,
-- a (mechanism-defined) status flag giving the reason
-- for rejection of the name in bad_targ_name
o Target_Info PARAMETER BUNDLE,
o targ_names SET OF INTERNAL NAME,
o (O) bad_targ_count INTEGER,
o (O) bad_target_name Bad_Target_Name,
o General_Service_Data PARAMETER BUNDLE,
o target_info Target_Info,
o (X) unencapsulated_token OCTET STRING,
-- zero length if encapsulation_request is TRUE
o (O) minor_status INTEGER,
Adams Document Expiration: 26 May 1997 24
Three types of protection services are defined in IDUP. These are
1. perform unsolicited service (i.e., act on a locally-generated
service request),
2. perform solicited service (i.e., act on a remotely-generated
service request), and
3. perform service solicitation (i.e., send a service request to
the remote end).
As an originator, applying data confidentiality with data integrity,
or data origin authentication with data integrity, or proof of origin
evidence is an example of service type 1. As a target, creating a
proof of delivery (i.e., receipt) evidence token as the result of a
request received from the originator is an example of service type 2.
Finally, as an originator, submitting a request that one or more
targets return a receipt for the data sent is an example of service
type 3.
The first four parameters in the Prot_Service parameter bundle
pertain to all service types; the fifth parameter is used if and only
if service type 2 is desired; parameters 6-8 are used if and only if
service type 3 is desired.
o Prot_Service PARAMETER BUNDLE
o (I) prot_service_type INTEGER,
o (I) service_id OBJECT IDENTIFIER,
o (I) quality Quality,
-- NULL specifies default Quality
o (I) general_service_data General_Service_Data,
o (I) service_creation_info Service_Creation_Info,
o (I) service_to SET OF INTERNAL NAME,
o (O) service_verification_info Service_Verification_Info,
o (O) service_verification_info_id INTEGER,
Also, three types of unprotection services are defined. These are
1. receive unsolicited service (i.e., process unrequested
remotely-generated service),
2. receive solicited service (i.e., process remotely-generated
response to locally-generated request), and
3. receive service solicitation (i.e., process req. from rem. end)
As a target, unprotecting an encrypted message, or verifying the
originator's proof of origin is an example of service type 1. As an
originator, verifying a proof of delivery which you requested from a
target is an example of service type 2. Finally, as a target,
receiving a request from an originator for a proof of delivery is an
example of service type 3.
Adams Document Expiration: 26 May 1997 25
The first four parameters in the Unprot_Service parameter bundle
pertain to all service types; parameters 5-6 are used if and only if
service type 2 is required; parameters 7-8 are used only if service
type 3 is required.
o Unprot_Service PARAMETER BUNDLE
o (O) unprot_service_type INTEGER,
o (O) service_id OBJECT IDENTIFIER,
o (O) quality Quality,
-- actual Quality specified (never NULL)
o (O) general_service_data General_Service_Data,
o (O) service_verification_info_id INTEGER,
o (I) service_verification_info Service_Verification_Info,
o (O) service_to SET OF INTERNAL NAME,
o (O) service_creation_info Service_Creation_Info,
2.3.3. IDUP_Start_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o Mech_Specific_Info PARAMETER BUNDLE,
-- NULL selects the mechanism-defined default values
o Idu_Information PARAMETER BUNDLE,
o Special_Conditions PARAMETER BUNDLE,
o encapsulation_request BOOLEAN,
o single_idu_buffer OCTET STRING,
-- non-zero length for this buffer means that Protect/End_Protect
-- won't be called (i.e., entire IDU is contained in this buffer)
o Target_Info PARAMETER BUNDLE,
o Services_to_Perform SET OF Prot_Service,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o midu_buffer OCTET STRING,
-- zero length if encapsulation_request is TRUE;
-- may be zero length otherwise (depends on underlying mechanism)
Adams Document Expiration: 26 May 1997 26
o pidu_buffer OCTET STRING,
-- zero length if encapsulation_request is FALSE;
-- may be zero length otherwise (depends on underlying mechanism)
Return major_status codes:
o GSS_S_COMPLETE indicates that the protection process can begin
(or has completed, if single_idu_buffer has non-zero length).
o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers
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 data.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o IDUP_S_ENCAPSULATION_UNAVAIL indicates that the underlying
mechanism does not support encapsulation of the M-IDU into the
token.
o IDUP_S_MORE_DATA_NEEDED indicates whether protection is completed
by this call or by IDUP_End_Protect() (e.g., whether more data
buffers are required for evidence generation)
o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism
does not support the service requested.
o IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service
requested (TTIME or UTIME) is not available in the environment.
o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
is not recognized or supported in the underlying mechanism.
o GSS_S_BAD_QOP indicates that the provided qop_algs value is not
recognized or supported for the environment.
o IDUP_S_BAD_TARG_INFO indicates that all the information regarding
the target(s) is invalid or is insufficient for the protection of
an IDU, so P-IDU cannot be created.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Adams Document Expiration: 26 May 1997 27
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of protecting the
IDU buffers. The caller requests specific protection services by
supplying the appropriate Prot_Service parameter bundles in
Services_to_Perform. Each service is able to return a minor status
code to the calling application, if necessary.
The calling application, knowing the size of the IDU it wishes to
protect and the buffer size which it has available to it, can choose
to input the entire IDU in a single buffer and omit the subsequent
IDUP_Protect() and IDUP_End_Protect() calls. Furthermore, the
application can request that the resulting M-IDU be encapsulated in
the token -- so that the token contains the entire P-IDU -- rather
than having it be returned separately in midu_buffer. Encapsulation,
however, may not be supported by all underlying mechanisms or
implementations; if this is the case, the
IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and
M-IDU will be returned in midu_buffer.
For those mechanisms which allow or require multiple stages of
processing, each producing a different aspect of protection for the
IDU, the operation identifier prot_oper_id is used to specify
which stage is currently being requested by the application. An
example where this would be useful is a mechanism which implements
the signed Message Security Protocol [MSP]. As another example, a
mechanism may choose to do a digital signature in two stages: one
for the hashing of the message and another for the signature on the
hash. The calling application would therefore use the protection set
of calls on the IDU in stage 1 and then use the protection set of
calls on the token (from stage 1) in stage 2.
Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where
"n" is the number of stages as defined by the mechanism (typically 1
or 2)). The calling application uses this parameter to indicate to
the underlying mechanism whether it wishes to do stage 1 of
protection / unprotection processing, or stage 2, and so on.
If one or more of the targets in targ_names cannot be used as a valid
recipient of the P-IDU, these names will be returned in
bad_targ_names (with associated status codes in bad_targ_status). As
long as at least one of the targets can be used, this does not cause
this call to fail; it is the caller's prerogative to discontinue IDU
protection if the target set which can be used is unsuitable for the
caller's purposes. Note that each Prot_Service parameter bundle can
also input a list of targ_names; this is used if a separate list is
to be used for that service only (the general list of targets is to
be used for all services unless overridden in this way).
Adams Document Expiration: 26 May 1997 28
2.3.4. IDUP_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o input_buffer OCTET STRING,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_buffer OCTET STRING
-- may be zero length if encapsulation_request was set to TRUE in
-- IDUP_Start_Protect() (depends on underlying mechanism)
Return major_status codes:
o GSS_S_COMPLETE indicates that the input_buffer has successfully
been included in the protection computation.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the required operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, continue the
protection processing on the data in input_buffer and, if the
underlying mechanism defines this, put any resulting P-IDU/M-IDU data
in output_buffer. The application calls this routine over and over
again with new buffers of data until it has protected all the data
buffers of the IDU. It then calls IDUP_End_Protect() to complete the
protection processing.
Adams Document Expiration: 26 May 1997 29
2.3.5. IDUP_End_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o Services_to_Perform SET OF Prot_Service,
o final_midu_buffer OCTET STRING,
-- zero length if encapsulation_request was set to TRUE in
-- IDUP_Start_Protect(), in which case pidu is used
o final_pidu_buffer OCTET STRING,
-- zero length if encapsulation_request was set to FALSE in
-- IDUP_Start_Protect(), in which case token and midu are used
Return major_status codes:
o GSS_S_COMPLETE indicates that the protection computation has been
successfully completed and the resulting P-IDU is ready for
transfer. If defined by the underlying mechanism,
final_midu_buffer will contain any residual M-IDU data.
o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers
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 data.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, complete the
protection processing on the data and place the computed output in
final_pidu_buffer (or final_midu_buffer and the unencapsulated_token
parameter for each Prot_Service). If a service was requested from
one or more targets in Start_Protect() - and if this is supported by
the underlying mechanism - Service_Verification_Info will hold
whatever data is necessary for the mechanism to verify a service
returned by a target (unprotector) of the P-IDU. Successful
application of IDUP_End_Protect() does not guarantee that the
corresponding unprotection set of calls can necessarily be performed
successfully when the P-IDU arrives at the target (for example, it
may be damaged in transit).
Adams Document Expiration: 26 May 1997 30
2.3.6. IDUP_Start_Unprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o Mech_Specific_Info PARAMETER BUNDLE,
-- NULL selects the mechanism-defined default values
o single_data_buffer OCTET STRING,
-- non-zero length for this buffer means that IDUP_Unprotect() and
-- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU
-- (if encapsulation is used) or M-IDU (if encap. is not used)
-- is contained in this buffer)
o partial_pidu_buffer OCTET STRING,
-- may be an arbitrary-sized piece of the full pidu (if the
-- application's buffer isn't large enough to hold entire pidu).
-- Used if pidu_buffer will be input a buffer at a time (except
-- that the final buffer must be passed in final_pidu_buffer
-- rather than partial_pidu_buffer). Only one of
-- single_pidu_buffer and partial(final)_pidu_buffer can have
-- nonzero length.
o final_pidu_buffer OCTET STRING,
o Special_Conditions PARAMETER BUNDLE,
Adams Document Expiration: 26 May 1997 31
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o Services_to_Receive SET OF Unprot_Service,
o Prot_Information PARAMETER BUNDLE,
o single_idu_buffer OCTET STRING,
-- if this buffer has non-zero length, then service processing has
-- been completed on the data in single_pidu_buffer
o initial_idu_buffer OCTET STRING,
-- holds any data from partial(final)_pidu_buffer which has been
-- unprotected; remaining data will be returned by Unprotect and
-- End_Unprotect as they are called with successive buffers of
-- pidu
o Service_Verification_Info PARAMETER BUNDLE,
-- used only if target is on "service_to" list in Unprot_Service
o service_verification_info_id INTEGER,
-- used only if target is on "service_to" list in Unprot_Service
Return major_status codes:
o GSS_S_COMPLETE indicates that unprotection processing can begin
(or has completed, if single_idu_buffer has non-zero length).
o IDUP_S_INCOMPLETE 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. (This status code is used in
IDUP_Start_Unprotect only if single_idu_buffer has non-zero
length)
o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers
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 data.
o IDUP_S_MORE_PIDU_NEEDED indicates that not enough of the P-IDU
has been input yet for the completion of Start_Protect. The
application should call this routine again with another buffer
of P-IDU in partial_pidu_buffer.
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the received P-IDU failed, preventing further processing
from being performed.
o IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied
do not contain the information necessary for P-IDU unprotection.
Adams Document Expiration: 26 May 1997 32
o IDUP_S_MORE_DATA_NEEDED indicates whether unprotection is
completed by this call or by IDUP_End_Unprotect() (e.g., whether
more data buffers are required for unprotection)
o GSS_S_DEFECTIVE_VERIF indicates that consistency checks performed
on Service_Verification_Info failed, preventing further processing
from being performed with that parameter.
o IDUP_S_NO_MATCH indicates that Service_Verification_Info and
the P-IDU to be verified do not match.
o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism
does not support the service requested.
o IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service
requested (TTIME or UTIME) is not available in the environment.
o IDUP_S_SERV_VERIF_INFO_NEEDED 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.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
is not recognized or supported in the underlying mechanism.
o GSS_S_BAD_QOP indicates that the qop_algs value specified in P-IDU
for at least one of the services is unavailable in the local
mechanism, so processing cannot continue.
o GSS_S_BAD_SIG indicates that the received P-IDU contains an
incorrect integrity field (e.g., signature or MAC) for the data.
o IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU
data origin auth. / integ. has either expired or been revoked.
o IDUP_S_BAD_KE_KEY indicates that the key used to establish a key
for confidentiality purposes between originator and target has
either expired or been revoked.
o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU
cannot be completed because the encrypted IDU was invalid/defec-
tive (e.g., the final block was short or had incorrect padding).
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Adams Document Expiration: 26 May 1997 33
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of unprotecting a
P-IDU. The caller will be alerted as to which services were applied
to the P-IDU in the returned Services_to_Receive set of parameters.
If unprotection will be applied more than once to a given P-IDU, it
is the responsibility of the calling application to remember if a
service solicitation has been responded to previously (i.e., if the
requested service has already been generated / sent for that P-IDU)
and thus ignore subsequent solicitations on unprotect.
The time flags indicate whether to consult trusted, untrusted, or no
time (if both flags are FALSE) during the unprotection operation. If
the current time is not to be checked, then unprotection may be
successful even if the protector's key has expired since the P-IDU
was generated (that is, if the Validity period -- as specified in
the Quality parameter bundle -- has expired).
If the underlying mechanism supports it and if this information is
contained in the token, information regarding the originator (that
is, the entity which used the protection set of calls to generate
this token) is returned in the Prot_Information parameter bundle.
2.3.7. IDUP_Unprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o input_buffer OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_buffer OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that the input_buffer has successfully
been included in the unprotection computation.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, continue the
unprotection processing on the data in input_buffer, putting any
resulting IDU data in output_buffer (if required).
Adams Document Expiration: 26 May 1997 34
2.3.8. IDUP_End_Unprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o Prot_Information PARAMETER BUNDLE,
o Services_to_Receive SET OF Unprot_Service,
o final_idu_buffer OCTET STRING,
o Service_Verification_Info PARAMETER BUNDLE,
-- used only if target is on "service_to" list in Unprot_Service
o service_verification_info_id INTEGER,
-- used only if target is on "service_to" list in Unprot_Service
Return major_status codes:
o GSS_S_COMPLETE indicates that the unprotect computation was
successful. Any residual IDU data will be returned in
final_idu_buffer.
o IDUP_S_INCOMPLETE 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.
o GSS_S_CONTINUE_NEEDED indicates that at least one of the buffers
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 data.
o GSS_S_BAD_SIG indicates that the received P-IDU contains an
incorrect integrity field (e.g., signature or MAC) for the data.
o IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU
data origin auth. / integ. has either expired or been revoked.
o IDUP_S_BAD_KE_KEY indicates that the key used to establish a key
for confidentiality purposes between originator and target has
either expired or been revoked.
o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU
cannot be completed because the encrypted IDU was invalid/defec-
tive (e.g., the final block was short or had incorrect padding).
Adams Document Expiration: 26 May 1997 35
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, complete the
unprotection processing on the data and return the appropriate status
code. If there is any residual IDU data it will be returned in
final_idu_buffer.
If the IDUP_S_INCOMPLETE major status value is returned, all output
parameters are conditionally valid; the unprotection set of functions
will have to be called again (perhaps with a complete P-IDU, as
produced by IDUP_Form_Complete_PIDU) in order to get valid values for
all parameters. "Conditional validity" may arise, for example, if
all relevant certificates verify correctly, but it is not yet past
the time up to which the current policy allows the authorities
involved to repudiate their keys.
If the underlying mechanism supports it and if this information is
contained in the token, information regarding the originator (that
is, the entity which used the protection set of calls to generate
this token) is returned in the Prot_Information parameter bundle.
This information may or may not be omitted if it was returned by the
IDUP_Start_Unprotect() call.
Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the
concept of error tokens transferred between sender and recipient
since the protection and unprotection of an IDU may be separated by
an indefinite amount of time and may or may not be performed by the
same entity.
Adams Document Expiration: 26 May 1997 36
2.4. Special-Purpose Calls
2.4.1. Relationship to GSS-API
The special-purpose call described in this section has no analog
in GSS-API [RFC-1508]. This call is used to complete a P-IDU (that
is, to generate a P-IDU which can be unprotected successfully with
no additional data at any time during its validity period). This
call may not be supported by all underlying IDUP mechanisms or
implementations.
2.4.2. IDUP_Form_Complete_PIDU call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o single_pidu_buffer OCTET STRING,
o partial_pidu_buffer OCTET STRING,
-- an arbitrary-sized piece of the full pidu token. Used if pidu
-- will be input a buffer at a time (except that the final buffer
-- must be passed in final_pidu_buffer rather than
-- partial_pidu_buffer). Only one of single_pidu_buffer and
-- partial(final)_pidu_buffer can have nonzero length.
o final_pidu_buffer OCTET STRING,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o pidu_token_out OCTET STRING
o call_again_before INTEGER,
o call_again_after INTEGER,
Adams Document Expiration: 26 May 1997 37
Return major_status codes:
o GSS_S_COMPLETE indicates that the completion of P-IDU generation
was successful.
o GSS_S_CONTINUE_NEEDED indicates that the buffer supplied for
pidu_token_out 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 data.
o IDUP_S_INCOMPLETE indicates that the generation of the P-IDU
is not yet complete. The application should call this function
again before the time given in call_again_before (if not NULL),
or after the time given in call_again_after (if not NULL), or
both (if neither are NULL).
o IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism
does not support the service requested.
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the input P-IDU token failed, preventing further processing
from being performed with that token.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, complete the
generation of a P-IDU token and return the appropriate status value
along with the completed token (if available). Such a call may be
used, for example, for the purpose of batch evidence generation on an
"evidence server". A local machine may be able to use the protection
set of calls to fill out most of an evidence token and then send a
number of these to a batch processor which forms the complete
evidence tokens (perhaps by adding a certification path, or a
timestamp and signature from a timestamping authority). As another
example, on the receiving end an application may make such a call in
order to collect all the information necessary to unprotect a P-IDU
(such as all relevant certificates and Certificate Revocation Lists);
this will ensure that the calls to the unprotection set of operations
will be entirely local (i.e., can be performed off-line) and fast.
Note that the complete P-IDU generated will be formed using trusted
time if this is available in the environment referenced by env_handle
and will use untrusted time or no time otherwise (depending on what
is available).
Adams Document Expiration: 26 May 1997 38
2.5. Support calls
2.5.1. Relationship to GSS-API
Support calls in IDUP-GSS-API are to be understood and used as
described in GSS-API [RFC-1508]. The calls GSS_Display_status(),
GSS_Indicate_mechs(), GSS_Compare_name(), GSS_Display_name(),
GSS_Import_name(), GSS_Release_name(), GSS_Release_buffer(), and
GSS_Release_oid_set() are unchanged.
2.5.2. IDUP_Parse_token call
Inputs:
o input_token OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o mech_type OBJECT IDENTIFIER,
Return major_status codes:
o GSS_S_COMPLETE indicates that the input_token could be parsed for
all relevant fields.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o GSS_S_DEFECTIVE_TOKEN indicates that the mechanism type could be
parsed, but that either the other fields could not be determined
from the input_token, or their values did not correspond to valid
values for that mechanism.
o GSS_S_FAILURE indicates that the mechanism type could not be
parsed (for example, the token may be corrupted).
IDUP_Parse_Token() is used to return to an application the attributes
which correspond to a given input token. Since IDUP-GSS-API tokens
are meant to be opaque to the calling application, this function
allows the application to determine information about the token
without having to violate the opaqueness intention of IDUP. Of
primary importance is the mechanism type, which the application can
then use as input to the IDUP_Establish_Env() call in order to
establish the correct environment in which to have the token
processed. Other token attributes may be added as outputs of this
call in future versions of this specification, if required.
Adams Document Expiration: 26 May 1997 39
If all tokens are framed as suggested in RFC-1508, Appendix B
(mandated in the Kerberos V5 GSS mechanism [RFC 1964] and in the SPKM
GSS Mechanism [RFC 2025], then any mechanism implementation should be
able to return the mech_type parameter for any uncorrupted input
token. If the mechanism implementation whose IDUP_Parse_token()
function is being called does recognize the token, it can return
other token attributes, if specified.
2.5.3. IDUP_Get_policy_info call
Inputs:
o policy_id OBJECT IDENTIFIER
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o policy_version INTEGER,
o policy_effective_time INTEGER,
o policy_expiry_time INTEGER,
o supported_services SET OF Service_Descriptor,
o supported_mechanisms SET OF Mechanism_Descriptor
Return major_status codes:
o GSS_S_COMPLETE indicates that the policy_id was recognized and
all relevant fields have been returned.
o GSS_S_FAILURE indicates that the policy_id was not recognized.
This call (which need not be supported by all underlying mechanisms
or implementations) allows the application to retrieve information
pertaining to a given policy_id. Policies define the following:
- rules for the protection of IDUs, such as trusted third
parties which may be involved in P-IDU generation, the roles
in which they may be involved, and the duration for which the
generated P-IDU is valid;
Adams Document Expiration: 26 May 1997 40
- rules for the unprotection of P-IDUs, such as the interval
during which a trusted third party may legitimately declare its
key to have been compromised or revoked; and
- rules for adjudication, such as which authorities may be used
to adjudicate disputes.
The policy itself may be used by an adjudicator when resolving a
dispute. For example, the adjudicator might refer to the policy to
determine whether the rules for generation of the P-IDU have been
followed.
The following parameter bundles are associated with this call.
o Service_Descriptor PARAMETER BUNDLE,
o service_type OBJECT IDENTIFIER,
o service_validity_duration INTEGER,
o must_use_trusted_time BOOLEAN
o Mechanism_Descriptor PARAMETER BUNDLE,
o mechanism_type OBJECT IDENTIFIER,
o Authority_List PARAMETER BUNDLE,
o maximum_time_skew INTEGER
-- maximum permissible difference between P-IDU generation
-- time and the time of countersignature from a time
-- service (if required). This parameter is unused if
-- trusted time is not required.
o Authority_List PARAMETER BUNDLE,
o authority_name INTERNAL NAME,
o authority_role OCTET STRING,
o last_revocation_check_offset INTEGER
-- may be greater than 0 or less than 0. The value of
-- this parameter is added to P-IDU generation time to
-- get latest time at which the mechanism will check to
-- see if this authority's key has been revoked.
An example of the use of the last parameter in Authority_List is as
follows. If an authority has a defined last_revocation_check_offset
of negative one hour, then all revocations taking effect earlier than
one hour before the generation of a P-IDU will render that P-IDU
invalid; no revocation taking place later than one hour before the
generation of the P-IDU will affect the P-IDU's validity.
Note that both the maximum_time_skew and the
last_revocation_check_offset values are given in minutes.
Adams Document Expiration: 26 May 1997 41
3. Related Activities
In order to implement the IDUP-GSS-API atop existing, emerging, and
future security mechanisms, the following is necessary:
- object identifiers must be assigned to candidate IDUP-GSS-API
mechanisms and the name types which they support; and
- concrete data element (i.e., token and parameter bundle) formats
must be defined for candidate mechanisms.
Calling applications must implement formatting conventions which will
enable them to distinguish IDUP-GSS-API P-IDUs from other
IDUs in their environment.
Concrete language bindings are required for the programming
environments in which the IDUP-GSS-API is to be employed; such a
binding for the C language are available in the Internet Draft
[IDUP-C].
4. Acknowledgments
Many thanks are due to Tim Moses and Dhanya Thakkar of Nortel,
Denis Pinkas of Bull, and David Kurn of Tandem Computers for a number
of helpful comments.
5. Security Considerations
Security issues are discussed throughout this memo.
Adams Document Expiration: 26 May 1997 42
6. REFERENCES
[MSP]: U.S. National Security Agency, "Message Security
Protocol", Secure Data Network System SDN.701, March 1994.
[RFC-1421]: J. Linn, "Privacy Enhancement for Internet Electronic
Mail: Part I: Message Encryption and Authentication Procedures",
RFC 1421.
[RFC-1508]: J. Linn, "Generic Security Service Application Program
Interface", RFC 1508.
[GSSv2]: J. Linn, "Generic Security Service Application Program
Interface, Version 2", Internet Draft draft-ietf-cat-gssv2-0x.txt
(work in progress).
[RFC 1964]: J. Linn, "The Kerberos Version 5 GSS-API Mechanism",
RFC 1964.
[RFC 2025]: C. Adams, "The Simple Public-Key GSS-API Mechanism
(SPKM)", RFC 2025.
[IDUP-C]: D. Thakkar, D. Grebovich, "Independent Data Unit
Protection Generic Security Service Application Program Interface: C-
bindings", Internet Draft draft-ietf-cat-idup-cbind-0x.txt (work in
progress).
[ISO/IEC]: 2nd ISO/IEC CD 13888-1, "Information technology -
Security techniques - Non-repudiation - Part 1: General Model",
ISO/IEC JTC 1/SC 27, May 30, 1995
7. Author's Address
Carlisle Adams
Nortel Secure Networks
P.O.Box 3511, Station C
Ottawa, Ontario, CANADA K1Y 4H7
Phone: +1 613.763.9008
E-mail: cadams@entrust.com
Adams Document Expiration: 26 May 1997 43
APPENDIX A
MECHANISM-INDEPENDENT TOKEN FORMAT
This appendix specifies a mechanism-independent level of
encapsulating representation for IDUP-GSS-API tokens, incorporating
an identifier of the mechanism type to be used when processing those
tokens. Use of this format (with ASN.1-encoded data elements
represented in BER, constrained in the interests of parsing
simplicity to the Distinguished Encoding Rule (DER) BER subset
defined in X.509, clause 8.7) is recommended to the designers of
IDUP-GSS-API implementations based on various mechanisms, so that
tokens can be interpreted unambiguously at IDUP-GSS-API peers. There
is no requirement that the mechanism-specific token data element be
encoded in ASN.1 BER.
-- top-level token definition to frame different mechanisms
IDUP-GSS-API DEFINITIONS ::=
BEGIN
MechType ::= OBJECT IDENTIFIER
Token ::= [APPLICATION 0] IMPLICIT SEQUENCE {
thisMech MechType,
token ANY DEFINED BY thisMech
-- contents mechanism-specific
}
END
Adams Document Expiration: 26 May 1997 44
APPENDIX B
EXAMPLES OF IDUP USE
This appendix provides examples of the use of IDUP to do IDU protec-
tion and unprotection. It should not be regarded as constrictive to
implementations or as defining the only means through which
IDUP-GSS-API functions can be realized with particular underlying
technology, and does not demonstrate all IDUP-GSS-API features.
B.1. Simple Mechanism, Single Buffer
To illustrate the simplest possible case, consider an underlying IDUP
mechanism which does straightforward encryption/decryption and
signing/verification only; none of the other possible services, such
as creation of proof-of-origin evidence, requests for proof-of-
delivery evidence, or use of trusted time, are supported. PEM
[RFC-1421] is one example of a mechanism which fits this description.
Furthermore (again for simplicity), assume that encapsulation is
chosen by the calling application during IDU protection.
The following parameter bundle uses and defaults would therefore be
specified in the relevant IDUP mechanism document.
Mech_Specific_Info
- NOT USED (the only acceptable input, therefore, is NULL)
Idu_Sensitivity
- NOT USED (the only acceptable input, therefore, is NULL)
Service_Creation_Info
- NOT USED (the only acceptable input, therefore, is NULL)
Service_Verification_Info
- NOT USED (the only acceptable input, therefore, is NULL)
Quality
- the qop_algs parameter must be supported, with a suitable
DEFAULT value specified;
- suitable DEFAULT values for validity, policy_id, and
allow_policy_mapping must be specified (it may be an
implementation option as to whether these parameters are
explicitly modifiable by the calling application, or whether
NULLs are the only acceptable input)
Idu_Information
- the idu_type parameter must have a value representing a suitable
IDU type (for example, in PEM a value representing the string
"RFC822" or some other valid "Content-Domain" would be used),
with a suitable DEFAULT value specified;
- the idu_title parameter is NOT USED (the only acceptable input,
therefore, is NULL)
Adams Document Expiration: 26 May 1997 45
Prot_Information
- the originator_name and idu_type (in Idu_Information) parameters
are read from the encapsulating information and output by
IDUP_Start_Unprotect;
- all other parameters are NOT USED (and therefore NULL)
Special_Conditions
- NOT USED (the only acceptable input, therefore, is NULL)
Target_Info
- this bundle is used as described in IDUP; no DEFAULT values are
specified
General_Service_Data
- the unencapsulated_token parameter is used if
encapsulation_request is FALSE;
- the minor_status parameter is used to return minor status values
as specified by the mechanism document
Prot_Service
- the prot_service_type parameter may have a value of "1"
("perform unsolicited service") or NULL (which specifies the
DEFAULT value of "1");
- the service_id parameter must have a value representing
"PER_CONF" or "PER_DOA";
- the parameters Service_Creation_Info, service_to,
Service_Verification_Info, and service_verification_info_id are
NOT USED (and therefore NULL)
Unprot_Service
- the unprot_service_type parameter will always have a value of
"1" ("receive unsolicited service");
- the service_id parameter will have a value representing
"REC_CONF" or "REC_DOA";
- the parameters service_verification_info_id,
Service_Verification_Info, service_to, and
Service_Creation_Info, are NOT USED (and therefore NULL)
Assuming that the calling application has only a single buffer of
data to protect/unprotect, the following sequence of operations must
be performed by the sender and receivers (subsequent to environment
establishment).
SENDER (any parameters not listed below are given the value NULL):
Set
env_handle = environment handle in use;
encapsulation_request = TRUE;
single_idu_buffer = data buffer;
Target_Info.targ_names = receiver names;
P_Services.Prot_Service_1.service_id = PER_CONF;
P_Services.Prot_Service_2.service_id = PER_DOA;
Adams Document Expiration: 26 May 1997 46
Call
IDUP_Start_Protect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
Target_Info.bad_targ_names / Target_Info.bad_targ_status,
P_Services.Prot_Service_1.General_Service_Data.minor_status,
P_Services.Prot_Service_2.General_Service_Data.minor_status
(as required) for more detailed information.
Send
Output parameter pidu_buffer to receiver.
RECEIVER (any parameters not listed below are given the value NULL):
Set
env_handle = environment handle in use;
single_pidu_buffer = received data buffer;
Call
IDUP_Start_Unprotect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status,
R_Services.Unprot_Service_2.General_Service_Data.minor_status
(as required) for more detailed information
Utilize
R_Services.Unprot_Service_1/2.service_id,
(to determine which services were applied by the originator)
R_Services.Unprot_Service_1/2.Quality,
(to determine the corresponding qualities of the services)
Prot_Information.originator_name,
(to determine the name of the originator)
single_idu_buffer
(to retrieve the unprotected data).
Adams Document Expiration: 26 May 1997 47
B.2. Simple Mechanism, Multiple Buffers
To illustrate the next step up in complexity, consider the use of the
simple IDUP mechanism described above with multiple data buffers. In
particular, consider the case in which a large data file is to be
signed. For this example, assume that the calling application does
not wish to use encapsulation.
Note that the parameter bundle uses and defaults are as specified in
C.1. above.
SENDER (any parameters not listed below are given the value NULL):
Set
env_handle = environment handle in use;
encapsulation_request = FALSE;
P_Services.Prot_Service.service_id = PER_DOA;
Call
IDUP_Start_Protect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
P_Services.Prot_Service.General_Service_Data.minor_status
(as required) for more detailed information.
For each buffer of input data:
Set
input_buffer = buffer
Call
IDUP_Protect() with above input parameter
Check
major_status. If not GSS_S_COMPLETE, check
minor_status
Call
IDUP_End_Protect()
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
P_Services.Prot_Service.General_Service_Data.minor_status
(as required) for more detailed information.
Send
P_Services.Prot_Service.General_Service_Data.unencapsulated_token,
the file for which the signature was calculated (if required)
to receiver.
Adams Document Expiration: 26 May 1997 48
RECEIVER (any parameters not listed below are given the value NULL):
Set
env_handle = environment handle in use;
partial_pidu_buffer = received unencapsulated token;
Call
IDUP_Start_Unprotect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status,
(as required) for more detailed information
For each buffer of input data:
Set
input_buffer = buffer
Call
IDUP_Unprotect() with above input parameter
Check
major_status. If not GSS_S_COMPLETE, check
minor_status
Call
IDUP_End_Unprotect()
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status,
(as required) for more detailed information.
Utilize
R_Services.Unprot_Service_1.service_id,
(to determine which service was applied by the originator; note
that Unprot_Service_2 will have NULL in unprot_service_type
to indicate that it is not used)
R_Services.Unprot_Service_1.Quality,
(to determine the corresponding quality of the service)
Prot_Information.originator_name, (from IDUP_Start_Unprotect)
(to determine the name of the signer)
major_status (from IDUP_End_Unprotect)
(to determine pass/fail status of signature verification).
Adams Document Expiration: 26 May 1997 49
B.3. More Sophisticated Mechanism, Small Application Buffers
To illustrate a higher level of complexity, consider the use of a
more sophisticated IDUP mechanism and a calling application with
small data buffers. In particular, consider the case in which a very
small e-mail message is to be encrypted for a relatively large
receiver list (R), some subset of whom (r) will be asked to send
proofs of receipt of the message to some other subset (L) (which
includes the originator). So that the example is not unnecessarily
complicated, assume again that the originating application uses
encapsulation.
The uses and defaults for the various parameter bundles for this
mechanism would be specified in the relevant IDUP mechanism document
as follows.
Mech_Specific_Info
- NOT USED (the only acceptable input, therefore, is NULL)
Idu_Sensitivity
- NOT USED (the only acceptable input, therefore, is NULL)
Service_Creation_Info
- used to create "proof of delivery" evidence (but actual
structure is opaque to calling application)
Service_Verification_Info
- used to verify "proof of delivery" evidence (but actual
structure is opaque to calling application)
Quality
- the qop_algs parameter must be supported, with a suitable
DEFAULT value specified;
- suitable DEFAULT values for validity, policy_id, and
allow_policy_mapping must be specified (it may be an
implementation option as to whether these parameters are
explicitly modifiable by the calling application, or whether
NULLs are the only acceptable input)
Idu_Information
- the idu_type parameter must have a value representing a suitable
IDU type, with a suitable DEFAULT value specified;
- the idu_title parameter must have a value representing a
suitable IDU title, with a suitable DEFAULT value specified
Prot_Information
- the originator_name, protection_time, and idu_type / idu_title
(in Idu_Information) parameters are read from the contained
header information and output by IDUP_Start_Unprotect;
Special_Conditions
- the parameter prot_oper_id is NOT USED (the only acceptable
input, therefore, is NULL);
- trusted or untrusted time may be selected by the calling
application, with a suitable DEFAULT value specified
Adams Document Expiration: 26 May 1997 50
Target_Info
- this bundle is used as described in IDUP; no DEFAULT values are
specified
General_Service_Data
- the unencapsulated_token parameter is used if
encapsulation_request is FALSE;
- the minor_status parameter is used to return minor status values
as specified by the mechanism document
Prot_Service
- the prot_service_type parameter may have a value of "1"
("perform unsolicited service"), "2" ("perform solicited
service"), "3" (perform service solicitation), or NULL (which
specifies the DEFAULT value of "1");
- the service_id parameter must have a value representing
"PER_CONF", "PER_DOA", "PER_POO", or "PER_POD";
- the parameters Service_Creation_Info, service_to,
Service_Verification_Info, and service_verification_info_id are
used when required by the IDUP operation
Unprot_Service
- the unprot_service_type parameter may have a value of "1"
("receive unsolicited service"), "2" ("receive solicited
service"), or "3" (receive service solicitation);
- the service_id parameter will have a value representing
"REC_CONF", "REC_DOA", "REC_POO", or "REC_POD";
- the parameters service_verification_info_id,
Service_Verification_Info, service_to, and
Service_Creation_Info, are used when required by the IDUP
operation
SENDER (any parameters not listed below are given the value NULL):
Set
env_handle = environment handle in use;
Idu_Information.idu_type = value for "e-mail document";
Idu_Information.idu_title = "Contract 1234";
Special_Conditions.use_trusted_time = TRUE;
encapsulation_request = TRUE;
single_idu_buffer = very small e-mail message;
Target_Info.targ_names = receiver names (R);
Prot_Service_1.prot_service_type = "1";
Prot_Service_1.service_id = PER_CONF;
Prot_Service_2.prot_service_type = "3";
Prot_Service_2.service_id = PER_POD;
Prot_Service_2.General_Service_Data.Target_Info.targ_names
= "receipts from" list (r);
Prot_Service_2.service_to = "receipts to" list (L);
P_Services.Prot_Service_1 = Prot_Service_1;
P_Services.Prot_Service_2 = Prot_Service_2;
Adams Document Expiration: 26 May 1997 51
Call
IDUP_Start_Protect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE,
while major_status == GSS_S_CONTINUE_NEEDED
Save
pidu_buffer,
Call
IDUP_Start_Protect() (to get next portion of pidu_buffer)
Check
major_status,
minor_status,
Target_Info.bad_targ_names / Target_Info.bad_targ_status,
P_Services.Prot_Service_1.General_Service_Data.minor_status,
P_Services.Prot_Service_2.General_Service_Data.minor_status
(as required) for more detailed information.
Save
Prot_Service_2.Service_Verification_Info,
Prot_Service_2.service_verification_info_id
Send
All saved buffers of pidu_buffer to receiver list (R).
RECEIVER (ON RECEIVER LIST (R)):
(any parameters not listed below are given the value NULL)
Set
env_handle = environment handle in use;
partial_pidu_buffer = initial buffer of received p-idu;
Call
IDUP_Start_Unprotect() with above input parameters
While major_status == IDUP_S_MORE_PIDU_NEEDED,
Set
partial_pidu_buffer = next buffer of p-idu
Call
IDUP_Start_Unprotect()
Check
major_status,
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status,
R_Services.Unprot_Service_2.General_Service_Data.minor_status,
(as required) for more detailed information
Save
initial_idu_buffer (if non-empty)
Adams Document Expiration: 26 May 1997 52
Set
input_buffer = remaining p-idu buffer
Call
IDUP_Unprotect() with above input parameter
Check
major_status. If not GSS_S_COMPLETE, check
minor_status
Save
output_buffer
Call
IDUP_End_Unprotect()
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status,
R_Services.Unprot_Service_2.General_Service_Data.minor_status,
(as required) for more detailed information.
Utilize
R_Services.Unprot_Service_1/2.service_id,
(to determine which services were applied by the originator)
R_Services.Unprot_Service_1/2.Quality,
(to determine the corresponding qualities of the service)
Prot_Information.originator_name/protection_time and
Prot_Information.Idu_Information.idu_type/idu_title,
(from IDUP_Start_Unprotect) (to determine originator info.)
R_Services.Unprot_Service_2.General_Service_Data.Target_Info.
targ.names, (to determine if rec. is in "receipts from" (r))
Service_Verification_Info/service_verification_info_id
(to determine if receiver is in "receipts to" list (L))
If receiver is in "receipts from" list (r)
Save
R_Services.Unprot_Service_2.service_to,
R_Services.Unprot_Service_2.Service_Creation_Info
If receiver is in "receipts to" list (L)
Save
Service_Verification_Info,
service_verification_info_id
Adams Document Expiration: 26 May 1997 53
RECEIVER (ON "RECEIPTS FROM" LIST (r)):
(procedure to generate receipt)
Set
env_handle = environment handle in use;
Target_Info.targ_names = service_to
Prot_Service_1.prot_service_type = "2";
Prot_Service_1.service_id = "PER_POD";
Prot_Service_1.Service_Creation_Info = Service_Creation_Info;
P_Services.Prot_Service_1 = Prot_Service_1
Call
IDUP_Start_Protect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
P_Services.Prot_Service_1.General_Service_Data.minor_status
(as required) for more detailed information.
Send
pidu_buffer to "receipts to" list (L)
RECEIVER (ON "RECEIPTS TO" LIST (L)):
(procedure to process received receipt)
Set
env_handle = environment handle in use;
single_pidu_buffer = received p-idu buffer (if it fits in a single
buffer; otherwise use partial_pidu_buffer and make multiple
calls, as above)
Call
IDUP_Start_Unprotect() with above input parameters
If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED
Utilize
R_Services.Unprot_Service_1.service_verification_info.id
(to assist in locating necessary Service_Verification_Info)
Set
R_Services.Unprot_Service_1.Service_Verification_Info
= Service_Verification_Info
Call
IDUP_Start_Unprotect() with above input parameters
Check
major_status,
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status
(as required) for more detailed information.
Utilize
R_Services.Unprot_Service_1.service_id,
(to determine that this is a "proof of delivery" evidence)
R_Services.Unprot_Service_1.Quality,
Prot_Information.originator_name, (for evidence generator info.)
major_status (to determine pass/fail status of evi. verif.).
Adams Document Expiration: 26 May 1997 54
| PAFTECH AB 2003-2026 | 2026-04-23 06:11:13 |