Internet Draft C. Adams, Bell-Northern Research
draft-ietf-cat-idup-gss-01.txt March 31, 1995
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 (previously known as IOP-GSS-API) extends the
GSS-API [RFC-1508] for applications requiring protection of a generic
data unit (such as a file or message) in a way which is independent
of the protection of any other data unit and independent of any
concurrent contact with designated "receivers" of the data unit.
Thus, it is suitable for applications such as secure electronic mail
where data needs to be protected without any on-line connection with
the intended recipient(s) of that data. Subsequent to being
protected, the data unit can be transferred to the recipient(s) - or
to an archive - perhaps to be processed 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: 30 Sept. 1995 1
As with RFC-1508, this IDUP-GSS-API definition provides security
services to callers in a generic fashion, supportable with a range of
underlying mechanisms and technologies and hence allowing source-
level portability of applications to different environments. This
specification defines IDUP-GSS-API services and primitives at a level
independent of underlying mechanism and programming language environ-
ment, and is to be complemented by other, related specifications:
- documents defining specific parameter bindings for particular
language environments;
- documents defining token formats, protocols, and procedures to
be implemented in order to realize IDUP-GSS-API services atop
particular security mechanisms.
TABLE OF CONTENTS
1. IDUP-GSS-API Characteristics and Concepts ................... 3
1.1. IDUP-GSS-API Constructs ................................... 4
1.1.1. Credentials ............................................ 4
1.1.2. Tokens ................................................. 4
1.1.3. Security Environment ................................... 5
1.1.4. Mechanism Types ........................................ 5
1.1.5. Naming ................................................. 5
1.1.6. Channel Bindings ....................................... 5
1.2. IDUP-GSS-API Features and Issues ......................... 5
1.2.1. Status Reporting ....................................... 5
1.2.2. Per-IDU Security Service Availability .................. 6
1.2.3. Per-IDU Replay Detection and Sequencing ................ 6
1.2.4. Quality of Protection .................................. 6
2. Interface Descriptions ...................................... 7
2.1. Credential management calls .............................. 8
2.1.1. Relationship to GSS-API ................................ 8
2.2. Environment-level calls .................................. 8
2.2.1. Relationship to GSS-API ................................ 8
2.2.2. IDUP_Establish_Env call ................................ 9
2.2.3. IDUP_Abolish_Env call .................................. 11
2.2.4. IDUP_Inquire_Env call .................................. 11
2.3. Per-IDU calls ............................................ 12
2.3.1. Relationship to GSS-API ................................ 12
2.3.2. IDUP_Start_Protect ..................................... 13
2.3.3. IDUP_Protect ........................................... 15
2.3.4. IDUP_End_Protect ....................................... 15
2.3.5. IDUP_Start_Unprotect ................................... 16
2.3.6. IDUP_Unprotect ......................................... 18
2.3.7. IDUP_End_Unprotect ..................................... 18
2.3.8. IDUP_Process_Receipt ................................... 19
2.4. Support calls ............................................ 20
2.4.1. Relationship to GSS-API ................................ 20
2.4.2. IDUP_Parse_token call .................................. 20
3. Mechanism-Specific Example Scenarios ........................ 22
3.1. PEM-compliant file protection ............................ 22
3.2. Signed-MSP-compliant file protection ..................... 23
4. Related Activities .......................................... 23
5. Acknowledgments ............................................. 24
6. Security Considerations ..................................... 24
7. References ............................................ 24
8. Author's Address ............................................ 24
Appendix A, B .................................................. 25
Adams Document Expiration: 30 Sept. 1995 2
1. IDUP-GSS-API Characteristics and Concepts
The operational paradigm in which IDUP-GSS-API operates is as
follows. An IDUP-GSS-API caller is any application which works with
IDUs, calling on IDUP-GSS-API in order to protect its IDUs with
origin authentication, integrity, confidentiality, and/or (support
for) non-repudiation security services. An IDUP-GSS-API caller
accepts tokens provided to it by its local IDUP-GSS-API
implementation, logically concatenates the token(s) and the IDU to
create a protected IDU (P-IDU), and transfers the P-IDU to a peer or
to any storage medium. When the P-IDU is to be "unprotected", the
token(s) and the IDU must be passed to an IDUP-GSS-API implementation
for processing. The security services available through IDUP-GSS-API
in this fashion are implementable over a range of underlying
mechanisms based on secret-key and public-key cryptographic
technologies. Note that the protecting application may choose
whatever method it wishes to concatenate or combine the token(s) and
the IDU into a P-IDU, but the unprotecting application must know how
to de-couple the P-IDU back into its component parts prior to calling
the IDUP unprotection set of functions.
The IDUP-GSS-API separates the operation of initializing a security
environment (the IDUP_Establish_Env() call) from the operations of
providing per-IDU protection, for IDUs subsequently protected in
conjunction with that environment. Per-IDU protection and
unprotection calls provide the data origin authentication / data
integrity services, or confidentiality services, or both, as a caller
option. Additional calls provide supportive functions to the
IDUP-GSS-API's users.
The following paragraphs provide an example illustrating the
dataflows involved in use of the IDUP-GSS-API by the sender and
receiver of a P-IDU in a mechanism-independent fashion. The example
assumes that credential acquisition has already been completed by
both sides.
The sender first calls IDUP_Establish_Env() to establish a
security environment. Then, for the IDU to be protected the
sender calls IDUP_Start_Protect(), IDUP_Protect() for each buffer
of data, and IDUP_End_Protect() to complete the IDU protection.
The prot_token output by IDUP_End_Protect() and the IDU (which had
confidentiality applied if this was requested in
IDUP_Start_Protect()) are logically concatenated to form the
P-IDU, which is now ready to be sent to the target. The sender
then calls IDUP_Abolish_Env() to flush all environment-specific
information.
The receiver first calls IDUP_Establish_Env() to establish a
security environment for unprotecting P-IDUs. Then, for the
received P-IDU the receiver calls IDUP_Start_Unprotect(),
IDUP_Unprotect() for each buffer of data, and IDUP_End_Unprotect()
to complete the P-IDU unprotection. The receiver then calls
IDUP_Abolish_Env() to flush all environment-specific information.
Adams Document Expiration: 30 Sept. 1995 3
It is important to note that absolutely no synchronization is implied
or expected between the data buffer size used by the sender as input
to the protection calls, the data buffer size used by the receiver as
input to the unprotection calls, and the block sizes required by the
underlying protection algorithms (integrity and confidentiality).
All these sizes are meant to be independent; furthermore, the data
buffer sizes used for the protection and unprotection calls are
purely a function of the local environment where the calls are made.
The IDUP-GSS-API design assumes and addresses several basic goals,
including the following.
Mechanism independence: The IDUP-GSS-API defines an interface to
cryptographically implemented security services at a generic level
which is independent of particular underlying mechanisms. For
example, IDUP-GSS-API-provided services can be implemented by
secret-key technologies or public-key approaches.
Protocol environment independence: The IDUP-GSS-API is independent
of the communications protocol suites which may be used to
transfer P-IDUs, permitting use in a broad range of protocol
environments.
Protocol association independence: The IDUP-GSS-API's security
environment construct is independent of communications protocol
association constructs, so that IDUP-GSS-API services can be
invoked by applications, wholly independent of protocol
associations.
Suitability for a range of implementation placements: IDUP-GSS-API
clients are not constrained to reside within any Trusted Computing
Base (TCB) perimeter defined on a system where the IDUP-GSS-API is
implemented; security services are specified in a manner suitable
for both intra-TCB and extra-TCB callers.
1.1. IDUP-GSS-API Constructs
This section describes the basic elements comprising the
IDUP-GSS-API.
1.1.1. Credentials
Credentials in IDUP-GSS-API are to be understood and used as
described in GSS-API [RFC-1508].
1.1.2. Tokens
Tokens in IDUP-GSS-API are to be understood and used as described in
GSS-API [RFC-1508] with the exception that there are no context-level
tokens generated by IDUP-GSS-API. Only two tokens, prot_token and
receipt_token, are defined by IDUP-GSS-API. The first is meant to
be logically concatenated with an IDU prior to transfer to a target;
the latter can be sent independently of any other data transfer.
Adams Document Expiration: 30 Sept. 1995 4
1.1.3. Security Environment
The "security environment" in IDUP-GSS-API is entirely different from
the concept of security contexts used in GSS-API [RFC-1508]. Here, a
security environment exists within a calling application (that is, it
is purely local to the caller) for the purpose of protecting or
unprotecting one or more IDUs using a particular caller credential.
In GSS-API, on the other hand, a security context exists between
peers (the initiator and the target) for the purpose of protecting,
in real time, the data that is exchanged between them. Although they
are different concepts, the IDUP_handle in IDUP-GSS-API is similar to
the context_handle in GSS-API in that it is a convenient way of tying
together the entire process of protecting or unprotecting one or more
IDUs. As with the GSS-API security contexts, a caller can initiate
and maintain multiple environments using the same or different
credentials.
1.1.4. Mechanism Types
Mechanism types in IDUP-GSS-API are to be understood and used as
described in GSS-API [RFC-1508].
1.1.5. Naming
Naming in IDUP-GSS-API is to be understood and used as described in
GSS-API [RFC-1508].
1.1.6. Channel Bindings
The concept of channel bindings discussed in GSS-API [RFC-1508] is
not relevant to the IDUP-GSS-API.
1.2. IDUP-GSS-API Features and Issues
This section describes aspects of IDUP-GSS-API operations and of the
security services which the IDUP-GSS-API provides. It also provides
commentary on design issues.
1.2.1. Status Reporting
Status reporting in IDUP-GSS-API is to be understood and used as
described in GSS-API [RFC-1508], with the addition of the following
IDUP-GSS-API major status codes:
Adams Document Expiration: 30 Sept. 1995 5
Table 1: IDUP-GSS-API Major Status Codes
FATAL ERROR CODES
IDUP_S_BAD_TARG_INFO target information is invalid or
unsuitable for IDU protection.
IDUP_S_BAD_DIGEST_ALG requested digest algorithm unsupported
IDUP_S_BAD_CONF_ALG requested conf. algorithm unsupported
IDUP_S_BAD_ENC_IDU encrypted IDU is defective/invalid
IDUP_S_NO_ENV no environment recognized for env_handle
IDUP_S_UNKNOWN_OPER_ID requested operation id. is unsupported
INFORMATORY STATUS CODES
IDUP_S_RECEIPTS_UNAVAIL mechanism does not support receipts
1.2.2. Per-IDU Security Service Availability
Per-IDU security service availability in IDUP-GSS-API is to be
understood and used as described in GSS-API [RFC-1508], with the
exception that integrity or confidentiality or both can be applied to
any IDU.
1.2.3. Per-IDU Replay Detection and Sequencing
The concept of per-IDU replay detection and sequencing discussed
in GSS-API [RFC-1508] is not relevant to the IDUP-GSS-API.
1.2.4. Quality of Protection
The concept of QOP control in IDUP-GSS-API is to be understood
essentially as described in GSS-API [RFC-1508]. However, the actual
description and use of the QOP parameter follows that given in the
Internet Draft "draft-ietf-cat-spkmgss-02.txt". This QOP description
allows either mechanism-independent labels or particular algorithm
labels to be specified by calling applications for both
confidentiality and integrity.
Adams Document Expiration: 30 Sept. 1995 6
2. Interface Descriptions
This section describes the IDUP-GSS-API's service interface, dividing
the set of calls offered into four 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. Support calls provide ancillary functions
useful to IDUP-GSS-API callers. Table 2 groups and summarizes the
calls in tabular fashion (an asterisk marks the calls which are
identical to the GSS-API specification).
Table 2: IDUP-GSS-API Calls
CREDENTIAL MANAGEMENT
* GSS_Acquire_cred acquire credentials for use
* GSS_Release_cred release credentials after use
* GSS_Inquire_cred display information about credentials
ENVIRONMENT-LEVEL CALLS
IDUP_Establish_Env estbablish IDUP environment (to protect
and unprotect IDUs)
IDUP_Abolish_Env abolish env. when no longer needed
IDUP_Inquire_Env indicate characteristics of env.
PER-IDU CALLS
IDUP_Start_Protect begin the protection process
IDUP_Protect protect IDU (perhaps 1 buffer at a time)
IDUP_End_Protect end the protection process; create a
"protect token" which contains info.
necessary for the legitimate receiver(s)
of the P-IDU to unprotect it
IDUP_Start_Unprotect begin the unprotect process
IDUP_Unprotect use the "protect token" to unprotect the
P-IDU (possibly one buffer at a time)
IDUP_End_Unprotect end the unprotect process; create a
receipt token if this was requested
and if underlying mechanism supports it
IDUP_Process_Receipt process the receipt_token
Adams Document Expiration: 30 Sept. 1995 7
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 object
* GSS_Import_name_object import name from object
* GSS_Export_name_object export name to object
IDUP_Parse_Token examine the input token to determine
mech_type and token_type
2.1. Credential management calls
2.1.1. Relationship to GSS-API
Credential management in IDUP-GSS-API is to be understood and used as
described in GSS-API [RFC-1508]. The calls GSS_Acquire_cred(),
GSS_Release_cred(), and GSS_Inquire_cred() are unchanged.
2.2. Environment-level calls
This group of calls is devoted to the establishment and management of
an environment for the purpose of IDU protection and unprotection.
Before protecting or unprotecting any IDU, an application must call
IDUP_Establish_Env() to initialize environment information and select
the underlying IDUP-GSS mechanism to be used. A series of protection
or unprotection calls are made to process each IDU, resulting in a
"prot_token" or a "receipt_token" (if supported) for each. Finally,
IDUP_Abolish_Env() is called to flush all environment information.
2.2.1. Relationship to GSS-API
The set of calls described in this section replaces the calls
GSS_Init_sec_context(), GSS_Accept_sec_context(),
GSS_Delete_sec_context(), GSS_Process_context_token(), and
GSS_Context_time() which are specified in [RFC-1508].
Adams Document Expiration: 30 Sept. 1995 8
2.2.2. IDUP_Establish_Env call
Inputs:
o claimant_cred_handle CREDENTIAL HANDLE, -NULL specifies "use
default"
o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use
default"
o time_req INTEGER,
o req_flags INTEGER,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o env_handle ENVIRONMENT HANDLE,
o mech_type OBJECT IDENTIFIER, -actual mechanism always
indicated, never NULL
o time_rec INTEGER,
o ret_flags INTEGER,
Return major_status codes:
o GSS_S_COMPLETE indicates that environment-level information was
successfully initialized, and that IDU processing can begin on
the newly-established environment.
o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
performed on the credential structure referenced by
claimant_cred_handle failed, preventing further processing from
being performed using that credential structure.
o GSS_S_NO_CRED indicates that no environment was established,
either because the input cred_handle was invalid or because the
caller lacks authorization to access the referenced credentials.
o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided
through the input claimant_cred_handle argument are no longer
valid, so environment establishment cannot be completed.
o GSS_S_BAD_MECH indicates that a mech_type unsupported by the
IDUP_GSS-API implementation type was requested, causing the
environment establishment operation to fail.
o GSS_S_FAILURE indicates that environment setup could not be
accomplished for reasons unspecified at the IDUP-GSS-API level,
and that no interface-defined recovery action is available.
Adams Document Expiration: 30 Sept. 1995 9
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 an IDU. The
claimant_cred_handle 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_flags parameter may be used by the calling application to
request that integrity, confidentiality, and/or receipt processing be
available in the established environment. Requesting receipt
processing indicates that the calling application may wish to obtain
a proof of receipt (of an IDU which it will protect in the
established environment) from one or more of the intended recipients
of that P-IDU.
Not all features will be available in all underlying mech_types; the
returned value of ret_flags (receipts_avail, conf_avail,
integ_avail) indicates, as a function of mech_type processing
capabilities and the initiator-provided input flags, the set of
features which will be available in the environment. These state
indicators' values are undefined unless the routine's major_status
indicates COMPLETE. Failure to provide the precise set of features
desired by the caller does not cause environment establishment to
fail; it is the caller's prerogative to abolish the environment if
the feature set provided is unsuitable for the caller's use. The
returned mech_type value indicates the specific mechanism employed in
the environment, and will never indicate the value for "default".
The conf_avail return value (in the ret_flags paramter) indicates
whether the environment supports confidentiality services, and so
informs the caller whether or not a request for encryption through
the conf_req_flag input to IDUP_Protect() can be honored. In similar
fashion, the integ_avail return value indicates whether integrity
services are available in the established environment, and the
receipts_avail return value indicates whether receipt generation and
processing services are available.
Adams Document Expiration: 30 Sept. 1995 10
2.2.3. IDUP_Abolish_Env call
Input:
o env_handle ENVIRONMENT HANDLE
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
Return major_status codes:
o GSS_S_COMPLETE indicates that the environment was recognized and
that relevant environment-specific information was flushed.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided, so no deletion was performed.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
This call is made to flush environment-specific information. (Once an
environment is established, cached credential and environment-related
information is expected to be retained until an IDUP_Abolish_Env()
call is made or until the environment lifetime expires.) Attempts to
perform IDU processing on a deleted or expired environment will
result in error returns.
2.2.4: IDUP_Inquire_Env call
Input:
o env_handle ENVIRONMENT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this env.
o ret_flags INTEGER,
o time_rec INTEGER -- in seconds
Return major_status codes:
o GSS_S_COMPLETE indicates that the referenced environment is valid
and that mech_type, ret_flags, and time_rec return values describe
the corresponding characteristics of the environment.
Adams Document Expiration: 30 Sept. 1995 11
o IDUP_S_ENV_EXPIRED indicates that the provided input env_handle
is recognized, but that the referenced environment has expired.
Return values other than major_status and minor_status are
undefined.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided, so no return values can be provided.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
This call is used to extract information describing characteristics
of the security environment.
2.3. Per-IDU calls
This group of calls is used to perform IDU protection processing
on an established IDUP environment. Some of these calls may block
pending network interactions (depending on the underlying mechanism
in use). These calls may be invoked by an IDU's protector or by the
P-IDU's recipient. The two sets of members of this group form a
pair; the output from the protection set is properly input to the
unprotection set.
The per-IDU calls support caller-requested confidentiality in
addition to data origin authentication / data integrity / non-
repudiation services. IDUP_End_Protect() outputs a token which
encapsulates all the information required to unprotect the IDU. The
token from IDUP_End_Protect() is passed to the target along with the
IDU and is processed by the unprotection calls at that system.
Unprotection performs decipherment or validation of P-IDUs (or both),
as required.
Note that each of the two main operations (protection and
unprotection) is separated into three parts: "Start_Operation";
"Operation", called once for each buffer of input data; and
"End_Operation". This separation is done for convenience since the
parts require different parameters. "Start_Operation" allows the
caller to specify or retrieve the algorithms (through the QOP value)
used during the processing. "Operation" is concerned with the
processing itself, receiving a buffer of input data and, if
confidentiality is involved, returning a buffer of output data.
Finally, "End_Operation" performs any required clean-up and creates
the appropriate token or states whether the input token and IDU were
valid.
2.3.1. Relationship to GSS-API
The set of calls described in this section replaces 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].
Adams Document Expiration: 30 Sept. 1995 12
2.3.2. IDUP_Start_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o digest_req_flag BOOLEAN,
o conf_req_flag BOOLEAN,
o qop_req INTEGER, -0 specifies default QOP
o targ_names SEQUENCE OF INTERNAL NAME,
o receipt_req_flag BOOLEAN,
o receipts_from SEQUENCE OF INTERNAL NAME,
-must be a subset of targ_names
o receipts_to SEQUENCE OF INTERNAL NAME,
o prot_oper_id INTEGER
-stage of protection operation to be performed
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o digest_state BOOLEAN,
o conf_state BOOLEAN,
o bad_targ_names SEQUENCE OF INTERNAL NAME,
Return major_status codes:
o GSS_S_COMPLETE indicates that the protection process can begin.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_ENV_EXPIRED indicates that the provided input env_handle
is recognized, but that the referenced environment has expired.
Return values other than major_status and minor_status are
undefined.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o IDUP_S_BAD_DIGEST_ALG indicates that the digest algorithm
specified is unavailable in the requested mechanism, so processing
cannot continue.
Adams Document Expiration: 30 Sept. 1995 13
o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
is not recognized or supported in the underlying mechanism.
o GSS_S_BAD_QOP indicates that the provided QOP value is not
recognized or supported for the environment.
o IDUP_S_BAD_CONF_ALG indicates that the confidentiality algorithm
specified is unavailable in the requested mechanism, so processing
cannot continue.
o IDUP_S_BAD_TARG_INFO indicates that the information regarding the
target(s) is invalid or is insufficient for the protection of an
IDU, so prot_token cannot be created.
o IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism
does not support the generation of receipts by the unprotection
set of calls.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of protecting the
IDU buffers. If the digest_req_flag is TRUE, the caller requests
that data origin authentication and/or data integrity services be
applied to the IDU buffers. If the conf_req_flag is TRUE, the
caller requests that confidentiality be applied to the IDU
buffers. Confidentiality and authentication/integrity may not be
supported in all mech_types or by all implementations; the returned
conf_state and digest_state flags indicate whether confidentiality or
authentication/integrity, or both, can be provided for the IDU.
The qop_req parameter allows quality-of-protection control. Choice
of the digest algorithm determines whether non-repudiation services
can be supported for an IDU.
For those mechanisms which allow or require multiple stages of
processing, each producing a different aspect of protection for the
IDU, the operation identifier prot_oper_id is used to specify
which stage is currently being requested by the application. An
example where this would be useful is a mechanism which implements
the signed Message Security Protocol [MSP] -- see Section 3.2 for
details.
If one or more of the targets in targ_names cannot be used as a valid
recipient of the P-IDU, these names will be returned in
bad_targ_names. As long as at least one of the targets can be used,
this does not cause environment establishment to fail; it is the
caller's prerogative to abolish the environment if the target set
which can be used is unsuitable for the caller's purposes.
Adams Document Expiration: 30 Sept. 1995 14
2.3.3. 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
Return major_status codes:
o GSS_S_COMPLETE indicates that the input_buffer has successfully
been included in the protection computation.
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 GSS_S_FAILURE indicates that the environment is recognized, but
that the required operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, continue the
protection processing on the data in input_buffer and, if
confidentially was requested in IDUP_Start_Protect(), put the result
in output_buffer.
2.3.4. IDUP_End_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_buffer OCTET STRING
o prot_token OCTET STRING
Adams Document Expiration: 30 Sept. 1995 15
Return major_status codes:
o GSS_S_COMPLETE indicates that the protection computation has been
successfully completed and the result has been placed in
prot_token. If confidentiality was requested in
IDUP_Start_Protect(), output_buffer will contain any residual
ciphertext.
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 GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, complete the
protection processing on the data and place the computed protection
token in prot_token.
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.
2.3.5. IDUP_Start_Unprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o prot_token OCTET STRING
o prot_oper_id INTEGER
-stage of unprotection operation to be performed
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o conf_state BOOLEAN -TRUE implies that conf. was applied
o digest_state BOOLEAN -TRUE implies that integrity was applied
o qop_state INTEGER,
o originator_info OCTET STRING
Adams Document Expiration: 30 Sept. 1995 16
Return major_status codes:
o GSS_S_COMPLETE indicates that unprotection processing can begin.
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the received prot_token failed, preventing further processing
from being performed with that token.
o GSS_S_CREDENTIALS_EXPIRED indicates that the environment is
recognized, but that its associated credentials have expired, so
that the requested operation cannot be performed.
o IDUP_S_ENV_EXPIRED indicates that the provided input env_handle
is recognized, but that the referenced environment has expired.
Return values other than major_status and minor_status are
undefined.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
is not recognized or supported in the underlying mechanism.
o IDUP_S_BAD_DIGEST_ALG indicates that the digest algorithm
specified in prot_token is unavailable in the local mechanism, so
processing cannot continue.
o IDUP_S_BAD_CONF_ALG indicates that the confidentiality algorithm
specified in prot_token is unavailable in the local mechanism, so
processing cannot continue.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of unprotecting a
P-IDU. If the returned conf_state value is TRUE, then
confidentiality was applied to the IDU and the confidentiality
portion of qop_state specifies the algorithm which was used.
Similarly, if the returned digest_state value is TRUE, then data
integrity / data origin authentication services were applied to the
IDU and the integrity portion of qop_state specifies the algorithm
which was used.
If underlying mechanism supports it and if this information is
contained in prot_token, return information regarding the originator
(that is, the entity which used the protection set of calls to
protect this IDU) in originator_info.
Adams Document Expiration: 30 Sept. 1995 17
2.3.6. 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 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 GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, continue the
unprotect processing on the data in input_buffer. If confidentiality
was applied to the IDU, put the decrypted data in output_buffer.
2.3.7. IDUP_End_Unprotect call
Inputs:
o env_handle ENVIRONMNENT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_buffer OCTET STRING
o receipt_token OCTET STRING
Adams Document Expiration: 30 Sept. 1995 18
Return major_status codes:
o GSS_S_COMPLETE indicates that the unprotect computation was
successful. If confidentiality was applied to the IDU,
output_buffer will contain any residual plaintext.
o GSS_S_BAD_SIG indicates that the received prot_token contains an
incorrect digest for the data.
o IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU
cannot be completed because the encrypted IDU was
invalid/defective (for example the final block was short or had
incorrect padding).
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 GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, complete the
unprotect processing on the data and return the appropriate status
code. If a receipt was requested by the sender of the P-IDU (and the
underlying mechanism supports this), receipt_token will contain this
receipt in a form suitable for transfer back to the sender.
Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the
concept of error tokens since the protection and unprotection of an
IDU may be separated by an indefinite amount of time and may or may
not be performed by the same entity.
2.3.8. IDUP_Process_Receipt call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o receipt_token OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o originator_info OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE indicates that receipt processing was successful.
Adams Document Expiration: 30 Sept. 1995 19
o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the received receipt_token failed, preventing further
processing from being performed with that token.
o IDUP_S_ENV_EXPIRED indicates that the provided input env_handle
is recognized, but that the referenced environment has expired.
Return values other than major_status and minor_status are
undefined.
o IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism
does not support the generation or processing of receipts.
o IDUP_S_NO_ENV indicates that no valid environment was recognized
for the env_handle provided.
o GSS_S_FAILURE indicates that the environment is recognized, but
that the requested operation could not be performed for reasons
unspecified at the IDUP-GSS-API level.
Using the security environment referenced by env_handle, initialize
the data structures required to process the received receipt_token
and return the appropriate status value. Information regarding the
creator of the receipt_token may be returned in originator_info, if
the underlying mechanism supports it.
2.4. Support calls
2.4.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(),
GSS_Release_oid_set(), GSS_Import_name_object(), and
GSS_Export_name_object() are unchanged.
2.4.2. IDUP_Parse_token call
Inputs:
o input_token OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o mech_type OBJECT IDENTIFIER,
o token_type INTEGER,
Adams Document Expiration: 30 Sept. 1995 20
Return major_status codes:
o GSS_S_COMPLETE indicates that the input_token could be parsed for
both fields. The resulting values are stored in mech_type and
token_type.
o GSS_S_DEFECTIVE_TOKEN indicates that the mechanism type could be
parsed, but that either the token type could not be determined
from the input token, or the value determined did not correspond
to any valid token_type.
o GSS_S_FAILURE indicates that the mechanism type could not be
parsed (for example, the token may be corrupted).
IDUP_Parse_Token() is used to return to an application the mechanism
type and token type which correspond to a given input token. Since
IDUP-GSS-API tokens are meant to be opaque to the calling
application, this function allows the application to determine
information about the token without having to violate the opaqueness
intention of IDUP. Of primary importance is the mechanism type,
which the application can then use as input to the
IDUP_Establish_Env() call in order to establish the correct
environment in which to have the token processed. The token_type may
be used to allow the application to determine whether to pass the
token to the IDUP_Start_Unprotect() call or the
IDUP_Process_Receipt() call.
If all tokens are framed as suggested in RFC-1508, Appendix B
(specified in the Kerberos V5 GSS mechanism [KRB5], in the SPKM GSS
Mechanism [SPKM], and in this document), then any mechanism
implementation should be able to return at least the mech_type
parameter (the token_type parameter being NULL) for any uncorrupted
input token. If the mechanism implementation whose
IDUP_Parse_token() function is being called does recognize the token,
it can return token_type so that the application can subsequently
call IDUP_Start_Unprotect() or IDUP_Process_Receipt().
Note that no minor status return codes have been defined for this
function at this time.
2.4.2.1. The token_type Output Parameter
The following token types are defined:
IDUP_PROT_TOKEN = 1
IDUP_RECEIPT_TOKEN = 2
Every mechanism must be able to perform the mapping from an input
token to one of the above token types (for any token generated by
that mechanism).
Adams Document Expiration: 30 Sept. 1995 21
3. Mechanism-Specific Example Scenarios
This section provides an illustrative overview of the use of a
candidate mechanism type to support the IDUP-GSS-API. This discussion
is intended primarily for readers familiar with the specific security
technology, demonstrating how IDUP-GSS-API functions can be used and
implemented by a candidate underlying mechanism. 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 a
particular underlying technology, and does not demonstrate all
IDUP-GSS-API features.
3.1. PEM-compliant file protection
A PEM-compliant IDUP-GSS-API mechanism would have as its prot_token
a PEM-compliant header for a protected (encrypted and/or signed) file
[RFC-1421]. A calling application wishing to encrypt and sign a data
file would initiate an environment using IDUP_Establish_Env(),
passing in the appropriate mech_type and a FALSE receipt_req.
IDUP_Start_Protect() is called next to specify that both encryption
and authentication/integrity are desired, and a QOP value is input
specifying either particular algorithms to be used (if the
application is aware of algorithms supported by the underlying
mechanism) or "generic" values. As well, the targ_names (possibly a
set of Distinguished Names) are specified at this time to be used in
the construction of prot_token. Any targets which cannot be used as
valid recipients (for example, because they do not have public-key
certificates which can be accessed by the mechanism) are returned in
bad_targ_names.
The file is then encrypted and signed one buffer at a time using
IDUP_Protect(). As each IDUP_Protect() call returns, the application
writes output_buffer (which contains ciphertext) to the end of an
output file. After the last input_buffer has been protected, the
application calls IDUP_End_Protect(). Any residual ciphertext is
returned in output_buffer, which is then written to the end of the
output file. As well, the returned prot_token is prepended to the
beginning of the output file. The output file is the "P-IDU" which
can be transferred by any means to the intended recipient(s).
Assuming that this is the only IDU to be protected at this time,
the application abolishes the environment by calling
IDUP_Abolish_Env().
The recipient of the P-IDU begins by calling IDUP_Parse_Token()
to determine the mech_type of the received token (the token_type
is redundant information for a PEM-compliant IDUP-GSS-API mechanism,
since receipts are not defined for such a mechanism).
IDUP_Establish_Env() is then called to initialize the environment.
The recipient then calls IDUP_Start_Unprotect(), passing it the
prot_token, IDUP_Unprotect() (once for each buffer of data),
and IDUP_End_Unprotect(). Output buffers are written to an output
file; after IDUP_End_Unprotect() has been called this file is the
original IDU which the sender protected.
The recipient then abolishes the env. by calling IDUP_Abolish_Env().
Adams Document Expiration: 30 Sept. 1995 22
3.2. Signed-MSP-compliant file protection
An MSP-compliant IDUP-GSS-API mechanism would be virtually identical
to the PEM-compliant mechanism described above (for details regarding
MSP see [MSP]). A Signed-MSP-compliant mechanism, however, requires
a signature on the MSP IDU itself -- that is, on the MSP header and
the encapsulated (possibly encrypted) content. This can be achieved
using the prot_oper_id parameter of the IDUP_Start_Protect() call.
For example, if prot_oper_id = 1 then the protection set of calls
would produce a prot_token which is the MSP header and which is then
concatenated with the (possibly encrypted) IDU to create an MSP IDU.
If the protection set were then called again on MSP IDU with
prot_oper_id = 2, prot_token would be the signature on MSP IDU, which
would be appended to MSP IDU to create the Signed-MSP IDU (i.e., the
final P-IDU).
MSP recognizes at least two kinds of recipients, intermediate Message
Transfer Agents (MTAs) and end User Agents (UAs). An MTA may be able
to validate that a Signed-MSP IDU is valid, but only end UAs should
be able to retrieve MSP-protected data. Thus, the MTA would call the
unprotection set of calls with prot_oper_id = 2 to verify the
signature on the MSP IDU, but would be unable to successfully call
the unprotection set with prot_oper_id = 1 since it would lack the
proper credentials. A valid end UA (one of the specified targets of
the P-IDU), on the other hand, would be able to unprotect the Signed-
MSP IDU with either value of prot_oper_id.
Note that a receipt generated by an MSP-compliant mechanism will be
sent to the IDU protector as a receipt_token and will be processed
using the IDUP_Process_Receipt() call.
4. Related Activities
In order to implement the IDUP-GSS-API atop existing, emerging, and
future security mechanisms,
object identifiers must be assigned to candidate IDUP-GSS-API
mechanisms and the name types which they support, and
concrete data element 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
bindings for the C language are available in an associated draft.
Adams Document Expiration: 30 Sept. 1995 23
5. Acknowledgments
Many thanks are due to Warwick Ford and Paul Van Oorschot of
Bell-Northern Research for a number of helpful comments.
6. Security Considerations
Security issues are discussed throughout this memo.
7. REFERENCES
[MSP]: U.S. National Security Agency, "Message Security
Protocol", Secure Data Network System SDN.701, March 1994.
[RFC-1421]: J. Linn, "Privacy Enhancement for Internet Electronic
Mail: Part I: Message Encryption and Authentication Procedures",
RFC 1421.
[RFC-1508]: J. Linn, "Generic Security Service Application Program
Interface", RFC 1508.
8. Author's Address
Carlisle Adams
Bell-Northern Research
P.O.Box 3511, Station C
Ottawa, Ontario, CANADA K1Y 4H7
Phone: +1 613.763.9008
E-mail: cadams@bnr.ca
Adams Document Expiration: 30 Sept. 1995 24
APPENDIX A
MECHANISM-INDEPENDENT TOKEN FORMAT
This appendix specifies a mechanism-independent level of
encapsulating representation for IDUP-GSS-API tokens, incorporating
an identifier of the mechanism type to be used when processing those
tokens. Use of this format (with ASN.1-encoded data elements
represented in BER, constrained in the interests of parsing
simplicity to the Distinguished Encoding Rule (DER) BER subset
defined in X.509, clause 8.7) is recommended to the designers of
IDUP-GSS-API implementations based on various mechanisms, so that
tokens can be interpreted unambiguously at IDUP-GSS-API peers. There
is no requirement that the mechanism-specific protToken data element
be encoded in ASN.1 BER.
-- top-level token definition to frame different mechanisms
IDUP-GSS-API DEFINITIONS ::=
BEGIN
MechType ::= OBJECT IDENTIFIER
ProtToken ::=
-- option indication done within mechanism-specific token
[APPLICATION 0] IMPLICIT SEQUENCE {
thisMech MechType,
protToken ANY DEFINED BY thisMech
-- contents mechanism-specific
}
ReceiptToken ::=
[APPLICATION 0] IMPLICIT SEQUENCE {
thisMech MechType,
receiptToken ANY DEFINED BY thisMech
-- contents mechanism-specific
}
END
APPENDIX B
MECHANISM DESIGN CONSTRAINTS
The following constraints on IDUP-GSS-API mechanism designs are
adopted in response to observed caller protocol requirements, and
adherence thereto is anticipated in subsequent descriptions of
IDUP-GSS-API mechanisms to be documented in standards-track Internet
specifications.
Use of the approach defined in Appendix A of this specification,
applying a mechanism type tag to the ProtToken and the ReceiptToken
(if defined), is required.
Adams Document Expiration: 30 Sept. 1995 25