One document matched: draft-ietf-cat-idup-cbind-00.txt
Internet Draft D. Grebovich
draft-ietf-cat-idup-cbind-00.txt Bell-Northern Research
Expires: September 30, 1995 March 24, 1995
Independent Data Unit Protection Generic Security Service
Application Program Interface: C-bindings
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 Independent Data Unit Protection Generic Security Service
Application Program Interface (IDUP-GSS-API) extends the GSS-API [RFC-
1508] for applications requiring protection of a generic data unit
(such as a file or message) in a way which is independent of the
protection of any other data unit and independent of any concurrent
contact with designated "receivers" of the data unit. Thus, it is
suitable for applications such as secure electronic mail where data
needs to be protected without any on-line connection with the intended
recipient(s) of that data. Subsequent to being protected, the
independent data unit can be transferred to the recipient(s) - or to
an archive - perhaps to be processed only days or years later.
This document is a companion document to the IDUP-GSS-API and
specifies its C language bindings. It extends the generic GSS-API: C-
bindings [RFC-1509].
TABLE OF CONTENTS
1. INTRODUCTION ................................................ 3
2. IDUP-GSS-API ROUTINES ....................................... 4
2.1. Data Types and Calling Conventions ........................ 5
2.1.1. Structured data types ................................... 5
2.1.2. Integer types ........................................... 5
2.1.3. String and similar data ................................. 6
2.1.3.1. Opaque data types ..................................... 6
2.1.3.2. Character strings ..................................... 6
2.1.4. Data Unit Identifiers ................................... 6
2.1.5. Data Unit Identifier Sets ............................... 7
2.1.6. Credentials ............................................. 7
2.1.7. Environments ............................................ 8
2.1.8. Authentication tokens ................................... 8
2.1.9. Status values ........................................... 8
2.1.9.1. IDUP-GSS status codes ................................. 8
2.1.9.2. Mechanism-specific status codes ....................... 11
2.1.10. Names .................................................. 11
2.1.11. Optional parameters .................................... 12
2.1.11.1. gss_buffer_t types ................................... 12
2.1.11.2. Integer types (input) ................................ 12
2.1.11.3. Integer types (output) ............................... 12
2.1.11.4. Pointer types ........................................ 12
2.1.11.5. Data Unit IDs ........................................ 12
2.1.11.6. Data Unit ID Sets .................................... 12
2.1.11.7. Credentials .......................................... 12
3. IDUP-GSS-API ROUTINE DESCRIPTIONS .......................... 13
3.1. Credential management calls .............................. 13
3.2. Environment-level calls .................................. 13
3.2.1. IDUP_Establish_env ..................................... 13
3.2.2. IDUP_Abolish_env ....................................... 16
3.2.3 IDUP_Inquire_env ....................................... 17
3.3. Per-IDU calls ............................................ 18
3.3.1. IDUP_Start_Protect ...................................... 19
3.3.2. IDUP_Protect ............................................ 22
3.3.3. IDUP_End_Protect ........................................ 23
3.3.4. IDUP_Start_Unprotect .................................... 24
3.3.5. IDUP_Unprotect .......................................... 26
3.3.6. IDUP_End_Unprotect ...................................... 27
3.3.7 IDUP_Process_Receipt .................................... 28
3.4. Support calls ............................................ 30
3.4.1 IDUP_Parse_token ........................................ 30
4. ACKNOWLEDGMENTS ............................................ 31
5. SECURITY CONSIDERATIONS .................................... 31
6. REFERENCES ........................................... 31
7. AUTHOR'S ADDRESS ........................................... 31
APPENDIX - IDUP-GSS-API Example ................................ 32
Grebovich 2 Expires: September 30, 1995 1.
INTRODUCTION
The Independent Data Unit Protection Generic Security Service
Application Program Interface (IDUP-GSS-API) [IDUP] provides security
services to calling applications in a local environment. It allows
an application to protect an independent data unit for future use,
to unprotect a protected independent data unit and to apply
security services such as confidentiality, integrity and support for
non-repudiation on a per-data-unit basis.
There are four stages to using the IDUP-GSS-API:
(a) The application acquires a set of credentials with which it may
bind its identity to a data unit. The application's credentials
vouch for its global identity, which may or may not be related to
the local username under which it is running.
(b) The application establishes a security environment using its
credentials. The security environment is an IDUP-GSS-API data
structure that contains information, which is required in order
that per-data-unit security services may be provided.
To establish the information that is used to protect an IDU,
certain IDUP-GSS-API calls will return a token data structure.
The caller of the data protection IDUP-GSS-API routine is
responsible for attaching the token to the data unit. This token
is used, by a corresponding IDUP-GSS-API routine which will
process the protected IDU, to verify the integrity, data origin
authenticity and/or extract the data unit information.
(c) Per-data-unit services are invoked to apply any combination of
the following:
(i) integrity,
(ii) data origin authentication,
(iii) confidentiality,
The application wishing to protect an IDU will call the protect
IDUP-GSS-API routines, specifying the appropriate security
environment. The recipient will pass the protected IDU to the
unprotecting routines to remove the protection and validate the
data.
(d) At the completion of a security environment (which may extend
across several protection and unprotection operations), the
application calls an IDUP-GSS-API routine to abolish the security
environment.
Grebovich 3 Expires: September 30, 1995 2.
IDUP-GSS-API ROUTINES
This section lists the functions performed by each of the IDUP-GSS-
API calls and discusses their major parameters, describing how
they are to be passed to the routines. The calls are listed in
Figure 1 (an asterisk marks the calls which are identical to the GSS-
API specification).
Figure 1 - 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 establish IDUP environment (to protect
or unprotect IDUs)
IDUP_Abolish_env abolish env. when no longer needed
IDUP_Inquire_env obtain environment parameters
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 1 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
Grebovich 4 Expires: September 30, 1995
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 normalized 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
Individual IDUP-GSS-API implementations may augment these routines by
providing additional mechanism-specific routines if required
functionality is not available from the generic forms. Applications
are encouraged to use the generic routines wherever possible on
portability grounds.
2.1. Data Types and Calling Conventions
The following conventions are used by the IDUP-GSS-API:
2.1.1. Structured data types
Wherever these IDUP-GSS-API C-bindings describe structured data, only
fields that must be provided by all IDUP-GSS-API implementation are
documented. Individual implementations may provide additional
fields, either for internal use within IDUP-GSS-API routines, or for
use by non-portable applications.
2.1.2. Integer types
IDUP-GSS-API defines the following integer data type:
OM_uint32 32-bit unsigned integer
Where guaranteed minimum bit-count is important, this portable data
type is used by the IDUP-GSS-API routine definitions. Individual
IDUP-GSS-API implementations will include appropriate typedef
definitions to map this type onto a built-in data type.
Grebovich 5 Expires: September 30, 1995 2.1.3.
String and similar data
Many of the IDUP-GSS-API routines take arguments and return values
that describe contiguous multiple-byte data. All such data is passed
between the IDUP-GSS-API and the caller using the gss_buffer_t data
type.
This data type is a pointer to a buffer descriptor, which consists of
a length field that contains the total number of bytes in the datum,
and a value field which contains a pointer to the actual datum:
typedef struct gss_buffer_desc_struct {
size_t length;
void *value;
} _gss_buffer_desc, *gss_buffer_t;
Storage for data passed to the application by a IDUP-GSS-API routine
using the gss_buffer_t conventions is allocated by the IDUP-GSS-API
routine. The application may free this storage by invoking the
GSS_Release_buffer routine. Allocation of the gss_buffer_desc data
unit is always the responsibility of the application; unused
gss_buffer_desc data units may be initialized to the value
GSS_C_EMPTY_BUFFER.
2.1.3.1. Opaque data types
Certain multiple-word data items are considered opaque data types at
the IDUP-GSS-API, because their internal structure has no
significance either to the IDUP-GSS-API or to the caller. Example of
such opaque data types is the input_buffer parameter to IDUP_Protect
(which is opaque to the IDUP-GSS-API). Opaque data is passed between
the IDUP-GSS-API and the application using the gss_buffer_t datatype.
2.1.3.2. Character strings
Certain multiple-word data items may be regarded as simple ISO Latin-
1 character strings. An example of this is the input_name_buffer
parameter to GSS_Import_name. Some IDUP-GSS-API routines also return
character strings. Character strings are passed between the
application and the IDUP-GSS-API using the gss_buffer_t datatype,
defined earlier.
2.1.4. Object Identifiers
Certain IDUP-GSS-API procedures take parameters of the type gss_OID,
or Object identifier. This is a type containing ISO-defined tree-
structured values, and is used by the IDUP-GSS-API caller to select
an underlying security mechanism. A value of type gss_OID has the
following structure:
typedef struct gss_OID_desc_struct {
OM_uint32 length;
void *elements;
} gss_OID_desc, *gss_OID;
Grebovich 6 Expires: September 30, 1995 The
elements field of this structure points to the first byte of an
octet string containing the ASN.1 BER encoding of the value of the
gss_OID. The length field contains the number of bytes in this
value. For example, the gss_OID value corresponding to {iso(1)
identified- oganization(3) icd-ecma(12) member-company(2) dec(1011)
cryptoAlgorithms(7) SPX(5)} meaning SPX (Digital's X.509
authentication mechanism) has a length field of 7 and an elements
field pointing to seven octets containing the following octal values:
53,14,2,207,163,7,5. IDUP-GSS-API implementations should provide
constant gss_OID values to allow callers to request any supported
mechanism, although applications are encouraged on portability
grounds to accept the default mechanism. gss_OID values should also
be provided to allow applications to specify particular name types
(see section 2.1.10). Applications should treat gss_OID_desc values
returned by IDUP-GSS-API routines as read-only. In particular, the
application should not attempt to deallocate them. The gss_OID_desc
datatype is equivalent to the X/Open OM_object_identifier datatype
[OSI].
2.1.5. Object Identifier Sets
Certain IDUP-GSS-API procedures take parameters of the type
gss_OID_set. This type represents one or more object identifiers
(section 2.1.4). A gss_OID_set object has the following structure:
typedef struct gss_OID_set_desc_struct {
int count;
gss_OID elements;
} gss_OID_set_desc, *gss_OID_set;
The count field contains the number of OIDs within the set. The
elements field is a pointer to an array of gss_OID_desc objects, each
of which describes a single OID. gss_OID_set values are used to name
the available mechanisms supported by the API-GSS-API, to request the
use of specific mechanisms, and to indicate which mechanisms a given
credential supports. Storage associated with gss_OID_set values
returned to the application by the IDUP-GSS-API may be deallocated by
the GSS_Release_oid_set routine.
2.1.6. Credentials
A credential handle is a caller-opaque atomic datum that identifies a
IDUP-GSS-API credential data structure. It is represented by the
caller-opaque type gss_cred_id_t, which may be implemented as either
an arithmetic or a pointer type. Credentials describe a principal,
and they give their holder the ability to act as that principal. The
IDUP-GSS-API does not make the actual credentials available to
applications; instead the credential handle is used to identify a
particular credential, held internally by IDUP-GSS-API or underlying
mechanism. Thus the credential handle contains no security-relavent
information, and requires no special protection by the application.
Depending on the implementation, a given credential handle may refer
to different credentials when presented to the IDUP-GSS-API by
different callers. Individual IDUP-GSS-API implementations should
define both the scope of a credential handle and the scope of a
credential itself (which must be at least as wide as that of a
Grebovich 7 Expires: September 30, 1995
handle). Possibilities for credential handle scope include the
process that acquired the handle, the acquiring process and its
children, or all processes sharing some local identification
information (e.g., UID). If no handles exist by which a given
credential may be reached, the IDUP-GSS-API may abolish the
credential.
Certain routines allow credential handle parameters to be omitted to
indicate the use of a default credential. The mechanism by which a
default credential is established and its scope should be defined by
the individual IDUP-GSS-API implementation.
2.1.7. Environments
The idup_env_id_t data type contains a caller-opaque atomic value
that identifies one end of a IDUP-GSS-API security environment. It
may be implemented as either an arithmetic or a pointer type.
Depending on the implementation, a given idup_env_id_t value may
refer to different IDUP-GSS-API security environments when presented
to the IDUP-GSS-API by different callers. The security environment
holds state information about the security association, including
cryptographic state information. Individual IDUP-GSS-API
implementations should define the scope of a environment. Since no
way is provided by which a new idup_env_id_t value may be obtained
for an existing environment, the scope of a environment should be the
same as the scope of a idup_env_id_t.
2.1.8. Authentication tokens
A token is a caller-opaque type that IDUP-GSS-API uses to store
protection information regarding an IDU. The token is a bit-string,
generated by the underlying mechanism at protection of a IDUP-GSS-API
security environment for use by the security mechanism at
unprotection. A token is passed between the IDUP-GSS-API and the
application using the gss_buffer_t conventions.
2.1.9. Status values
One or more status codes are returned by each IDUP-GSS-API routine.
Two distinct sorts of status codes are returned. These are termed
GSS status codes and Mechanism status codes.
2.1.9.1. IDUP-GSS status codes
IDUP-GSS-API routines return IDUP-GSS status codes as their OM_uint32
function value. These codes indicate errors that are independent of
the underlying mechanism used to provide the security service. The
errors that can be indicated via a IDUP-GSS status code are either
generic API routine errors (errors that are defined in the IDUP-GSS-
API specification) or calling errors (errors that are specific to
these bindings).
Grebovich 8 Expires: September 30, 1995 An
IDUP-GSS status code can indicate a single fatal generic API error
from the routine and a single calling error. In addition,
supplementary status information may be indicated via the setting of
bits in the supplementary info field of a IDUP-GSS status code.
These errors are encoded into the 32-bit GSS status code as follows:
MSB LSB
|------------------------------------------------------------|
| Calling Error | Routine Error | Supplementary Info |
|------------------------------------------------------------|
Bit 31 24 23 16 15 0
Hence if a IDUP-GSS-API routine returns a IDUP-GSS status code whose
upper 16 bits contain a non-zero value, the call failed. If the
calling error field is non-zero, the invoking application's call of
the routine was erroneous. Calling errors are defined in Table 1.
If the routine error field is non-zero, the routine failed for one of
the routine-specific reasons listed below in Table 2. Whether or not
the upper 16 bits indicate a failure or a success, the routine may
indicate additional information by setting bits in the supplementary
info field of the status code. The meaning of individual bits is
listed below in Table 3.
Table 1 - Calling Errors
Name Value in Meaning
Field
GSS_S_CALL_INACCESSIBLE_READ 1 A required input parameter
could not be read
GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output
parameter could not be
written.
GSS_S_CALL_BAD_STRUCTURE 3 A parameter was malformed.
Table 2 - Routine Errors
Name Value in Meaning
Field
GSS_S_BAD_BINDINGS 1 NOT APPLICABLE TO IDUP
GSS_S_BAD_MECH 2 unsupported mechanism requested
GSS_S_BAD_NAME 3 invalid name provided
GSS_S_BAD_NAMETYPE 4 name of unsupported type provided
GSS_S_BAD_STATUS 5 invalid input status selector
GSS_S_BAD_SIG 6 token had invalid signature
GSS_S_CONTEXT_EXPIRED 7 specified security context expired
GSS_S_CREDENTIALS_EXPIRED 8 expired credentials detected
GSS_S_DEFECTIVE_CREDENTIAL 9 defective credential detected
GSS_S_DEFECTIVE_TOKEN 10 defective token detected
GSS_S_FAILURE 11 failure, unspecified at GSS-API
level
GSS_S_NO_CONTEXT 12 NOT APPLICABLE TO IDUP
GSS_S_NO_CRED 13 no valid credentials provided
Grebovich 9 Expires: September 30, 1995
GSS_S_BAD_QOP 14 unsupported QOP value
IDUP_S_BAD_TARG_INFO 15 Target information is invalid
or unsuitable for IDU
protection.
IDUP_S_BAD_DIGEST_ALG 16 Requested digest algorithm
unsupported.
IDUP_S_BAD_CONF_ALG 17 Requested conf.
algorithm unsupported.
IDUP_S_BAD_ENC_IDU 18 Encrypted IDU is
defective/invalid algorithm
unsupported.
IDUP_S_NO_ENV 19 No environment recognized for
env_handle
IDUP_S_UNKNOWN_OPER_ID 20 Requested operation id.
unsupported
Table 3 - Supplementary Status Bits
Name Bit Number Meaning
GSS_S_COMPLETE 0 (LSB) Normal completion
GSS_S_CONTINUE_NEEDED 1 Continuation call to routine
required
GSS_S_DUPLICATE_TOKEN 2 NOT APPLICABLE TO IDU-P
GSS_S_OLD_TOKEN 3 NOT APPLICABLE TO IDU-P
GSS_S_UNSEQ_TOKEN 4 NOT APPLICABLE TO IDU-P
GSS_S_GAP_TOKEN 5 NOT APPLICABLE TO IDU-P
IDUP_S_RECEIPTS_UNAVAIL 6 Mechanism does not support
receipts
The routine documentation also uses the name GSS_S_COMPLETE, which is
a zero value, to indicate an absence of any API errors or
supplementary information bits.
All GSS_S_xxx and IDUP_S_xxx symbols equate to complete OM_uint32
status codes, rather than to bitfield values. For example, the
actual value of the symbol GSS_S_BAD_NAMETYPE (value 3 in the routine
error field) is 3 << 16.
The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and
GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a IDUP-GSS
status code and removes all but the relevant field. For example, the
value obtained by applying GSS_ROUTINE_ERROR to a status code removes
the calling errors and supplementary info fields, leaving only the
routine errors field. The values delivered by these macros may be
directly compared with a GSS_S_xxx symbol of the appropriate type.
The macro GSS_ERROR() is also provided, which when applied to a IDUP-
GSS status code returns a non-zero value if the status code indicated
a calling or routine error, and a zero value otherwise.
An IDUP-GSS-API implementation may choose to signal calling errors in
a platform-specific manner instead of, or in addition to the routine
value; routine errors and supplementary info should be returned via
routine status values only.
Grebovich 10 Expires: September 30, 1995
2.1.9.2. Mechanism-specific status codes
IDUP-GSS-API routines return a minor_status parameter, which is used
to indicate specialized errors from the underlying security
mechanism. This parameter may contain a single mechanism-specific
error, indicated by a OM_uint32 value.
The minor_status parameter will always be set by a IDUP-GSS-API
routine, even if it returns a calling error or one of the generic API
errors indicated above as fatal, although other output parameters may
remain unset in such cases. However, output parameters that are
expected to return pointers to storage allocated by a routine must
always set set by the routine, even in the event of an error,
although in such cases the IDUP-GSS-API routine may elect to set the
returned parameter value to NULL to indicate that no storage was
actually allocated. Any length field associated with such pointers
(as in a gss_buffer_desc structure) should also be set to zero in
such cases.
The GSS status code GSS_S_FAILURE is used to indicate that the
underlying mechanism detected an error for which no specific IDUP-GSS
status code is defined. The mechanism status code will provide more
details about the error.
2.1.10. Names
A name is used to identify a person or entity. IDUP-GSS-API
authenticates the relationship between a name and the entity claiming
the name.
Two distinct representations are defined for names:
(a) A printable form, for presentation to a user
(b) An internal form, for presentation at the API
The syntax of a printable name is defined by the IDUP-GSS-API
implementation, and may be dependent on local system configuration,
or on individual user preference. The internal form provides a
canonical representation of the name that is independent of
configuration.
A given IDUP-GSS-API implementation may support names drawn from
multiple namespaces. In such an implementation, the internal form of
the name must include fields that identify the namespace from which
the name is drawn. The namespace from which a printable name is
drawn is specified by an accompanying object identifier.
Routines (GSS_Import_name and GSS_Display_name) are provided to
convert names between their printable representations and the
gss_name_t type. GSS_Import_name may support multiple syntaxes for
each supported namespace, allowing users the freedom to choose a
preferred name representation. GSS_Display_name should use an
implementation-chosen preferred syntax for each supported name-type.
Grebovich 11 Expires: September 30, 1995 Comparison
of internal-form names is accomplished via the
GSS_Compare_names routine. This removes the need for the application
program to understand the syntaxes of the various printable names
that a given IDUP-GSS-API implementation may support.
Storage is allocated by routines that return gss_name_t values. A
procedure, GSS_Release_name, is provided to free storage associated
with a name.
2.1.11. Optional parameters
Various parameters are described as optional. This means that they
follow a convention whereby a default value may be requested. The
following conventions are used for omitted parameters. These
conventions apply only to those parameters that are explicitly
documented as optional.
2.1.11.1. gss_buffer_t types
Specify GSS_C_NO_BUFFER as a value. For an input parameter this
signifies that default behavior is requested, while for an output
parameter it indicates that the information that would be returned
via the parameter is not required by the application.
2.1.11.2. Integer types (input)
Individual parameter documentation lists values to be used to
indicate default actions.
2.1.11.3. Integer types (output)
Specify NULL as the value for the pointer.
2.1.11.4. Pointer types
Specify NULL as the value.
2.1.11.5. Object IDs
Specify GSS_C_NULL_OID as the value.
2.1.11.6. Object ID Sets
Specify GSS_C_NULL_OID_SET as the value.
2.1.11.7. Credentials
Specify GSS_C_NO_CREDENTIAL to use the default credential handle.
Grebovich 12 Expires: September 30, 1995 3.
IDUP-GSS-API routine descriptions
3.1 Credential Management Calls
Credential management in IDUP-GSS-API is to be understood and used as
described in GSS-API [RFC-1508 and RFC-1509]. The calls
GSS_Acquire_cred(), GSS_Release_cred() and GSS_Inquire_cred() are
unchanged.
3.2 Environment-level Calls
The set of calls described in this section replaces the calls
gss_init_sec_environment(), gss_accept_sec_environment(),
gss_delete_sec_environment(), gss_process_Environment_token() and
gss_environment_time() which are specified in [RFC-1508 and RFC-
1509].
3.2.1. IDUP_Establish_env
OM_uint32 IDUP_Establish_env (
gss_cred_id_t claimant_cred_handle,
gss_OID req_mech_type,
int time_req,
int req_flag,
OM_uint32 * minor_status,
idup_env_id_t * env_handle,
gss_OID * actual_mech_type,
int * time_rec,
int * ret_flags)
Purpose:
Initiates the establishment of a security environment by the
application.
The values returned via the ret_flags parameters are not defined
unless the routine returns GSS_S_COMPLETE.
Parameters:
claimant_cred_handle gss_cred_id_t, read, optional
handle for credentials claimed. Supply
GSS_C_NO_CRED to use default credentials.
req_mech_type OID, read, optional
Object ID of desired mechanism. Supply
GSS_C_NULL_OID to obtain an implementation
specific default
time_req integer, read, optional
Indicates lifetime requested for
environment.
Grebovich 13 Expires: September 30, 1995
req_flags integer, read
Contains three flags which request that the
environment support specific service
options:
GSS_C_CONF_FLAG
True - Confidentiality service requested
by calling protect routine
False - No confidentiality service (via
protect) requested. Protect will
provide data-origin authentication
and/or integrity services only.
GSS_C_INTEG_FLAG
True - Integrity service requested by
calling protect routine.
False - IDU integrity service not
requested.
IDUP_C_RECEIPT_REQ_FLAG
True - Receipts requested, i.e. initiator
wishes to obtain a proof of receipt
(of an IDU which it protected in
the established environment) from
one or more of the intended
recipients of that P-IDU
False - Receipts not requested
minor_status integer, modify
Mechanism specific status code.
env_handle idup_env_id_t, modify
environment handle for new environment.
actual_mech_type OID, modify
Actual mechanism used.
Always indicated, never NULL.
time_rec integer, modify, optional
Indicates actual lifetime for environment.
ret_flags bit-mask, modify
Contains three independent flags, each of
which indicates that the environment
supports a specific service option.
Symbolic names are provided for each flag,
and the symbolic names corresponding to the
required flags should be logically-ANDed
with the ret_flags value to test whether a
given option is supported by the
environment. The flags are:
Grebovich 14 Expires: September 30, 1995
GSS_C_CONF_FLAG
True - Confidentiality service may be
invoked by calling protect routine
False - No confidentiality service (via
protect) available. Protect will
provide data-origin authentication
and/or integrity services only.
GSS_C_INTEG_FLAG
True - Integrity service may be invoked by
calling protect routine.
False - IDU integrity service unavailable.
IDUP_C_RECEIPT_AVAIL_FLAG
True - Receipts available, i.e. initiator
may be able to obtain a proof of
receipt (of an IDU which it
protected in the established
environment) from one or more of
the intended recipients of that P-
IDU
False - Receipts not available
Function value:
GSS status code:
GSS_S_COMPLETE indicates that environment-level information was
successfully initialized, and that data unit
processing can begin on the newly-established
environment.
GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks
performed on the credential structure referenced
by claimant_cred_handle failed, preventing
further processing from being performed using
that credential structure.
GSS_S_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.
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.
GSS_S_BAD_NAMETYPE indicates that the provided targ_names are of a
type uninterpretable or unsupported by the
supporting IDUP-GSS-API implementation, so
environment establishment cannot be completed.
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.
Grebovich 15 Expires: September 30, 1995
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.
Failure. See minor_status for more information
3.2.2 IDUP_Abolish_env
OM_uint32 IDUP_Abolish_env (
idup_env_id_t * env_handle,
OM_uint32 * minor_status)
Purpose:
Abolish a security environment. IDUP_Abolish_env will abolish the
local data structures associated with the specified security
environment. No further security services may be obtained using the
environment specified by environment_handle.
Parameters:
env_handle idup_env_id_t, read
environment handle identifying environment
to abolish
minor_status integer, modify
Mechanism specific status code.
Function value:
GSS status code:
GSS_S_COMPLETE indicates that the environment was recognized
and that relevant environment-specific
information was flushed.
IDUP_S_NO_ENV indicates that no valid environment was
recognized for the environment_handle
provided, so no deletion was performed.
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.
Failure, see minor_status for more
information
Grebovich 16 Expires: September 30, 1995 3.2.3
IDUP_Inquire_env
OM_uint32 IDUP_Inquire_env (
idup_env_id_t env_handle,
OM_uint32 * minor_status,
int * lifetime_rec,
gss_OID * mech_type,
int * ret_flags)
Purpose:
This call is used to extract information describing characteristics
of a security context.
Parameters:
env_handle idup_env_id_t, read, optional
environment handle identifying environment
used.
minor_status integer, modify
mechanism specific status code.
lifetime_rec integer, modify
in seconds, or reserved value for
INDEFINITE
mech_type OID, modify, optional
the mechanism supporting this security
environment
ret_flags bit-mask, modify
Contains three independent flags, each of
which indicates that the environment
supports a specific service option.
Symbolic names are provided for each flag,
and the symbolic names corresponding to
the required flags should be logically-
ANDed with the ret_flags value to test
whether a given option is supported by the
environment. The flags are:
GSS_C_CONF_FLAG
True - Confidentiality service may be
invoked by calling protect
routine
False - No confidentiality service (via
protect) available. Protect will
provide data-origin
authentication and/or integrity
services only.
GSS_C_INTEG_FLAG
True - Integrity service may be invoked
by calling protect routine.
False - IDU integrity service
unavailable.
Grebovich 17 Expires: September 30, 1995
IDUP_C_RECEIPT_AVAIL_FLAG
True - Receipts available, i.e.
initiator may be able to obtain a
proof of receipt (of an IDU which
it protected in the established
environment) from one or more of
the intended recipients of that
P-IDU
False - Receipts not available
Function value:
GSS status code:
GSS_S_COMPLETE indicates that the referenced environment is
valid and that src_name, lifetime_rec,
mech_type, and ret_flags return values
describe the corresponding characteristics
of the environment.
GSS_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.
GSS_S_NO_ENV indicates that no valid environment was
recognized for the input env_handle
provided. Return values other than
major_status and minor_status are undefined.
GSS_S_FAILURE indicates that the requested operation
failed for reasons unspecified at the GSS-
API level. Return values other than
major_status and minor_status are undefined.
3.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 a data unit'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.
Grebovich 18 Expires: September 30, 1995 3.3.1.
IDUP_Start_Protect
OM_uint32 IDUP_Start_Protect (
idup_env_id_t env_handle,
int digest_req_flag,
int conf_req_flag,
int qop_req,
idup_name_t_set targ_names,
int receipt_req_flag,
idup_name_t_set receipts_from,
idup_name_t_set receipts_to,
int prot_oper_id,
OM_uint32 * minor_status,
int * digest_state,
int * conf_state,
idup_name_t_set bad_targ_names)
Purpose:
Using the security environment referenced by env_handle, establish
the data structures required to begin the process of
protecting the IDU buffers.
Parameters:
env_handle idup_env_id_t, read
identifies the environment in which the
data unit will be protected
digest_req_flag boolean, read
True - the caller requests the data
origin authentication and/or
data integrity services be
applied to the data unit buffers
False - data origin authentication and
integrity services not requested
conf_req_flag boolean, read
True - the caller requests the data
confidentiality service be
applied to the data unit buffers
False - data confidentiality service is
not requested
qop_req integer, read
Specifies requested quality of
protection. Callers are encouraged, on
portability grounds, to accept the
default quality of protection offered by
the chosen mechanism, which may be
requested by specifying GSS_C_QOP_DEFAULT
for this parameter. If an unsupported
protection strength is requested,
IDUP_Start_Protect will return a
major_status of GSS_S_FAILURE.
Grebovich 19 Expires: September 30, 1995
Zero specifies default QOP (which is
defined to specify the integrity service
only)..
NOTE: Choice of the QOP value determines
whether non-repudiation services should
be supported for a data unit.
targ_names idup_name_t_set, read
Indicates a list of names which will be
recipients to the P-IDU.
receipt_req_flag boolean, modify
Indicates a request to receive receipts.
receipts_from idup_name_t_set, read
Indicates a list of names that receipts
are expected from.
receipts_to idup_name_t_set, read
Indicates a list of names that receipts
are to be delivered to
prot_oper_id integer, read
For those mechanisms which allow or
require multiple stages of processing,
each producing a different aspect of
protection for the data data unit, this
parameter is used to specify which stage
is currently being requested by the
application, e.g., as in a mechanism
which implements the signed Message
Security Protocol [MSP].
minor_status integer, modify
Implementation specific status code
digest_state boolean, modify
True - data origin authentication
and/or data integrity services
are applied to the data unit
buffers
False - data origin authentication
and/or data integrity services
are not applied to the data unit
buffers
conf_state boolean, modify
True - confidentiality is applied to
the data unit buffers
False - confidentiality is not applied
to the data unit buffers
bad_targ_names idup_name_t_set, modify
Indicates a list of names that cannot be
used as recipients.
Grebovich 20 Expires: September 30, 1995 i
Function value:
GSS status code:
GSS_S_COMPLETE indicates that the protection process can
begin.
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.
IDUP_S_ENV_EXPIRED indicated 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.
IDUP_S_NO_ENV indicates that no valid environment was
recognized for the env_handle provided.
IDUP_S_BAD_DIGEST_ALG indicates that the digest algorithm
specified is unavailable in the requested
mechanism, so processing cannot continue.
IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value
is not recognized or supported in the
underlying mechanism.
GSS_S_BAD_QOP indicates that the provided QOP value is
not recognized or supported for the
environment.
IDUP_S_BAD_CONF_ALG indicates that the confidentiality
algorithm specified is unavailable in the
requested mechanism, so processing cannot
continue.
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.
IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism
does not support the generation of receipts
by the unprotection set of calls.
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.
Grebovich 21 Expires: September 30, 1995 3.3.2.
IDUP_Protect
OM_uint32 IDUP_Protect (
idup_env_id_t env_handle,
gss_buffer_t input buffer,
OM_uint32 * minor status,
gss_buffer_t output_buffer)
Purpose:
Using the security environment referenced by environment_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.
Parameters:
env_handle idup_env_id_t, read
Environment handle identifying environment
used
input_buffer octet string, read
IDU buffer
minor_status integer, modify
Implementation specific status code
output_buffer buffer, opaque, modify
Protected data unit buffer
Function value:
GSS status codes:
GSS_S_COMPLETE indicates that the input_buffer has
successfully been included in the
protection computation.
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.
IDUP_S_NO_ENV indicates that no valid environment was
recognized for the env_handle provided.
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.
Grebovich 22 Expires: September 30, 1995 3.3.3.
IDUP_End_Protect
OM_uint32 IDUP_End_Protect (
idup_env_id_t env_handle,
OM_uint32 * minor status,
gss_buffer_t output_buffer,
gss_buffer_t prot_token)
Purpose:
Using the security environment referenced by environment_handle,
complete the protection processing on the data and place the result
in prot_token.
Successful application of IDUP_End_Protect() does not guarantee that
the corresponding unprotection set of functions can necessarily be
performed successfully when the protected data unit arrives at the
target.
Parameters:
env_handle idup_env_id_t, read
Environment handle identifying
environment used
minor_status integer, modify
Implementation specific status code
output_buffer buffer, opaque, modify
Protected data unit buffer
prot_token buffer, opaque, modify
Protect token
Function value:
GSS status codes:
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.
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.
IDUP_S_NO_ENV indicates that no valid environment was
recognized for the env_handle provided.
Grebovich 23 Expires: September 30, 1995
IDUP_S_BAD_TARG_INFO indicates that the information regarding
the target(s) is invalid or is
insufficient for the protection of a data
unit, so prot_token cannot be created.
IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying mechanism
does support the generation of
receipts by the unprotection set of
calls.
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.
3.3.4. IDUP_Start_Unprotect
OM_uint32 IDUP_Start_Unprotect (
idup_env_id_t env_handle,
gss_buffer_t prot_token,
int prot_oper_id,
OM_uint32 * minor_status,
int conf_state,
int digest_state,
int qop_state,
gss_buffer_t originator_info)
Purpose:
Using the security environment referenced by environment_handle,
initialize the data structures required to begin the process of
unprotecting the P-IDU.
Parameters:
env_handle idup_env_id_t, read
Environment handle identifying
environment used.
prot_token buffer, opaque, read
Protect token.
prot_oper_id integer, read
For those mechanisms which allow or
require multiple stages of processing,
each producing a different aspect of
protection for the data unit, this
parameter is used to specify which stage
is currently being requested by the
application, e.g., as in a mechanism
which implements the signed Message
Security Protocol [MSP].
Grebovich 24 Expires: September 30, 1995
minor_status integer, modify
Implementation specific status code
conf_state boolean, modify
True - confidentiality is applied to
the data unit buffers
False - confidentiality is not applied
to the data unit buffers
digest_state boolean, modify
True - data origin authentication
and/or data integrity services
are applied to the data unit
buffers
False - data origin authentication
and/or data integrity services
are not applied to the data
unit buffers
NOTE: 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, has been applied to the
data unit.
qop_state integer, modify
Specifies quality of
protection which was applied to the P-
IDU.
If an unsupported protection strength
was applied, IDUP_Start_Unprotect will
return a major_status of GSS_S_FAILURE.
originator_info buffer, modify
if underlying mechanism supports it,
contains return information regarding
the originator
Function value:
GSS status codes:
GSS_S_COMPLETE indicates that unprotection processing
can begin.
GSS_S_DEFECTIVE_TOKEN indicates that consistency checks
performed on the received prot_token
failed, preventing further processing
from being performed with that token.
Grebovich 25 Expires: September 30, 1995
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.
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.
GSS_S_NO_ENV indicates that no valid environment
was recognized for the env_handle
provided.
IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id
value is not recognized or supported
in the underlying mechanism.
IDUP_S_BAD_DIGEST_ALG indicates that the digest algorithm
specified in prot_token is unavailable
in the local mechanism, so processing
cannot continue.
IDUP_S_BAD_CONF_ALG indicates that the confidentiality
algorithm specified in prot_token is
unavailable in the local mechanism, so
processing cannot continue.
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.
3.3.5. IDUP_Unprotect
OM_uint32 IDUP_Unprotect (
idup_env_id_t environment_handle,
gss_buffer_t input buffer,
OM_uint32 * minor status,
gss_buffer_t output_buffer)
Purpose:
Using the security environment referenced by environment_handle,
continue the unprotect processing on the data in input_buffer. If
confidentiality was applied to the data unit, put the decrypted data
in output_buffer.
Grebovich 26 Expires: September 30, 1995
Parameters:
environment_handle idup_env_id_t, rea
Environment handle identifying
environment used.
input_buffer octet string, opaque, read
Protected data unit buffer.
minor_status integer, modify
Implementation specific status code
output_buffer buffer, modify
Unprotected data unit buffer.
Function values:
GSS status codes:
GSS_S_COMPLETE indicates that the input_buffer has
successfully been included in the
unprotection computation.
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.
GSS_S_NO_ENV indicates that no valid environment was
recognized for the env_handle provided.
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.
3.3.6. IDUP_End_Unprotect
OM_uint32 IDUP_End_Unprotect (
idup_env_id_t env_handle,
OM_uint32 * minor status,
gss_buffer_t output_buffer,
gss_buffer_t receipt_token)
Purpose:
Using the security environment referenced by environment_handle,
complete the unprotect processing on the data and return the
appropriate status code.
Grebovich 27 Expires: September 30, 1995
Parameters:
env_handle idup_env_id_t, read
Environment handle identifying
environment used
minor_status integer, modify
Implementation specific status code
output_buffer buffer, modify
Unprotected data unit buffer.
receipt_token buffer, opaque, modify
Receipt token in a form suitable for
immediate transfer back to the sender
of the protected data unit.
Function value:
GSS status codes:
GSS_S_COMPLETE indicates that the unprotect computation was
successful. If confidentiality was applied
to the data unit, output_buffer will contain
any residual plaintext.
GSS_S_BAD_SIG indicates that the received prot_token
contains an incorrect digest for the data.
IDUP_S_BAD_ENC_IDU indicates that decryption of the received IDU
cannot be completed because the encrypted IDU
was invalid/defective (e.g., the final block
was short or had incorrect padding).
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.
GSS_S_NO_ENV indicates that no valid environment was
recognized for the env_handle provided.
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.
3.3.7 IDUP_Process_Receipt
OM_uint32 IDUP_Process_Receipt (
idup_env_id_t env_handle,
gss_buffer_t receipt_token,
OM_uint32 * minor status,
gss_buffer_t originator_info)
Grebovich 28 Expires: September 30, 1995 Purpose:
Using the security environment referenced by environment_handle,
initialize the data structures required to process the received
receipt_token and return the appropriate status value.
Parameters:
env_handle idup_env_id_t, read
Environment handle identifying
environment used
receipt_token gss_buffer_t, read
Received receipt_token.
minor_status integer, modify
Implementation specific status code
originator_info gss_buffer_t, modify
Information regarding the creator of
the receipt_token may be returned in
originator_info, if the underlying
mechanism supports it.
Function value:
GSS status codes:
GSS_S_COMPLETE indicates that receipt processing was
successful.
GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed
on the received receipt_token failed,
preventing further processing from being
performed with that token.
IDUP_S_ENV_EXPIRED indicates that the provided env_handle is
recognized, but that the referenced
environment has expired. Return values other
than major_status and minor_status are
undefined.
IDUP_S_RECEIPTS_UNAVAIL indicates that the underlying
mechanism does not support the
generation of receipts by the unprotection
set of calls.
IDUP_S_NO_ENV indicates that no valid environment was
recognized for the env_handle provided.
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.
Grebovich 29 Expires: September 30, 1995 3.4 Support
calls
Support calls in IDUP-GSS-API are to be understood and used as
described in GSS-API [RFC-1508 and RFC-1509]. 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() are unchanged.
3.4.1 IDUP_Parse_token
OMuint IDUP_Parse_token (
gss_buffer_t input_token,
OM_uint32 * minor status,
gss_OID * mech_type,
int token_type)
Purpose:
IDUP_Parse_token is used to return to an application the mechanism
type and token type which correspond to a given input token.
Parameters:
input_token gss_buffer_t, read
Input token from the protect call.
minor_status OM_uint32, modify
Implementation specific status code.
mech_type gss_OID, modify
The mechanism that was used to create the
input_token.
token_type int, modify
Type of the input_token.
Function value:
GSS status code:
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.
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.
GSS_S_FAILURE indicates that the mechanism type could not be
parsed (e.g., the token may be corrupted).
Grebovich 30 Expires: September 30, 1995
4. ACKNOWLEDGMENTS
I would like to thank Carlisle Adams of Bell Northern Research for
many helpful comments.
Section 1 and many parts of section 2 of this document are either
strongly influenced by or identical to John Wray's GSS-API:C-
bindings.
5. SECURITY CONSIDERATIONS
Security issues are discussed throughout this memo.
6. REFERENCES
[IDUP] Independent Data Unit Protection Generic Security Service
Application Program Interface, Internet Draft, C. Adams,
March 1995.
[MSP]: U.S. National Security Agency, "Message Security Protocol",
Secure Data Network System SDN.701, March 1994.
[OSI] "OSI Object Management API Specification, Version 2.0 t",
X.400 API Association & X/Open Company Limited, August 1990.
Specification of datatypes and routines for manipulating
information objects.
[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.
[RFC-1509]: J. Wray, "Generic Security Service API: C-bindings", RFC1509.
7. AUTHOR'S ADDRESS
Dragan Grebovich
Bell-Northern Research, Ltd.
P.O.Box 3511, Station C
Ottawa, Ontario, CANADA K1Y 4H7
Phone: +1 (613) 765-3524
E-mail: dragan@bnr.ca
Grebovich 31 Expires: September 30, 1995
APPENDIX
IDUP-GSS-API Example
#ifndef IDUP-GSS-API_H_
#define IDUP-GSS-API_H_
/*
* First, define the platform-dependent types.
*/
typedef <platform-specific> OM_uint32;
typedef <platform-specific> idup_env_id_t;
typedef <platform-specific> gss_cred_id_t;
typedef <platform-specific> gss_name_t;
typedef <platform-specific> idup_name_t;
/*
* Note that a platform supporting the xom.h X/Open header file
* may make use of that header for the definitions of OM_uint32
* and the structure to which gss_OID_desc equates.
*/
typedef struct gss_OID_desc_struct {
OM_uint32 length;
void *elements;
} gss_OID_desc, *gss_OID;
typedef struct gss_OID_set_desc_struct {
int count;
gss_OID elements;
} gss_OID_set_desc, *gss_OID_set;
typedef struct gss_buffer_desc_struct {
size_t length;
void *value;
} gss_buffer_desc, *gss_buffer_t;
typedef struct idup_name_t_set_desc_struct {
int count;
gss_name_t elements;
} idup_name_t_set_desc, *idup_name_t_set;
/*
* Seven independent flags each of which indicates that a environment
* supports a specific service option.
*/
#define GSS_C_DELEG_FLAG 1
#define GSS_C_MUTUAL_FLAG 2
#define GSS_C_REPLAY_FLAG 4
#define GSS_C_SEQUENCE_FLAG 8
#define GSS_C_CONF_FLAG 16
#define GSS_C_INTEG_FLAG 32
#define IDUP_C_RECEIPT_REQ_FLAG 64
Grebovich 32 Expires: September 30, 1995 /*
* Credential usage options
*/
#define GSS_C_BOTH 0
#define IDUP_C_PROTECT 1
#define IDUP_C_UNPROTECT 2
/*
* Status code types for GSS_Display_status
*/
#define GSS_C_GSS_CODE 1
#define GSS_C_MECH_CODE 2
#define IDUP_C_CODE 3
/*
#define GSS_C_AF_NULLADDR 255;
#define GSS_C_NO_BUFFER ((gss_buffer_t) 0)
#define GSS_C_NULL_OID ((gss_OID) 0)
#define GSS_C_NULL_OID_SET ((gss_OID_set) 0)
#define GSS_C_NO_CONTEXT ((idup_env_id_t) 0)
#define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0)
#define GSS_C_EMPTY_BUFFER {0, NULL}
#define IDUP_C_NO_ENV ((idup_env_id_t) 0)
/*
* Define the default Quality of Protection for per-data-unit
* services. Note that an implementation that offers multiple
* levels of QOP may either reserve a value (for example zero,
* as assumed here) to mean "default protection", or alternatively
* may simply equate GSS_C_QOP_DEFAULT to a specific explicit QOP
* value.
*/
#define GSS_C_QOP_DEFAULT 0
/*
* Expiration time of 2^32-1 seconds means infinite lifetime for a
* credential or security environment
*/
#define GSS_C_INDEFINITE 0xfffffffful
/* Major status codes */
#define GSS_S_COMPLETE 0
/*
* Some "helper" definitions to make the status code macros obvious.
*/
#define GSS_C_CALLING_ERROR_OFFSET 24
#define GSS_C_ROUTINE_ERROR_OFFSET 16
#define GSS_C_SUPPLEMENTARY_OFFSET 0
#define GSS_C_CALLING_ERROR_MASK 0377ul
#define GSS_C_ROUTINE_ERROR_MASK 0377ul
#define GSS_C_SUPPLEMENTARY_MASK 0177777ul
Grebovich 33 Expires: September 30, 1995 /*
* The macros that test status codes for error conditions
*/
#define GSS_CALLING_ERROR(x) \
(x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET))
#define GSS_ROUTINE_ERROR(x) \
(x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))
#define GSS_SUPPLEMENTARY_INFO(x) \
(x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET))
#define GSS_ERROR(x) \
((GSS_CALLING_ERROR(x) != 0) || (GSS_ROUTINE_ERROR(x) != 0))
/*
* Now the actual status code definitions
*/
/*
* Calling errors:
*/
#define GSS_S_CALL_INACCESSIBLE_READ \
(1ul << GSS_C_CALLING_ERROR_OFFSET)
#define GSS_S_CALL_INACCESSIBLE_WRITE \
(2ul << GSS_C_CALLING_ERROR_OFFSET)
#define GSS_S_CALL_BAD_STRUCTURE \
(3ul << GSS_C_CALLING_ERROR_OFFSET)
/*
* Routine errors:
*/
#define GSS_S_BAD_BINDINGS (1ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_BAD_MECH (2ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_BAD_NAME (3ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_BAD_NAMETYPE (4ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_BAD_STATUS (5ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_BAD_SIG (6ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_CONTEXT_EXPIRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_CREDENTIALS_EXPIRED (8ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_DEFECTIVE_CREDENTIAL (9ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_DEFECTIVE_TOKEN (10ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_FAILURE (11ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_NO_CONTEXT (12ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_NO_CRED (13ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define GSS_S_BAD_QOP (14ul << GSS_C_ROUTINE_ERROR_OFFSET)
#define IDUP_S_BAD_TARG_INFO (15ul << IDUP_C_ROUTINE_ERROR_OFFSET)
#define IDUP_S_BAD_DIGEST_ALG (16ul << IDUP_C_ROUTINE_ERROR_OFFSET)
#define IDUP_S_BAD_CONF_ALG (17ul << IDUP_C_ROUTINE_ERROR_OFFSET)
#define IDUP_S_BAD_ENC_IDU (18ul << IDUP_C_ROUTINE_ERROR_OFFSET)
#define IDUP_S_NO_ENV (19ul << IDUP_C_ROUTINE_ERROR_OFFSET)
#define IDUP_S_UNKNOWN_OPER_ID (20ul << IDUP_C_ROUTINE_ERROR_OFFSET)
Grebovich 34 Expires: September 30, 1995 /*
* Supplementary info bits:
*/
#define GSS_S_CONTINUE_NEEDED (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0))
#define GSS_S_DUPLICATE_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1))
#define GSS_S_OLD_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2))
#define GSS_S_UNSEQ_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3))
#define GSS_S_GAP_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4))
#define IDUP_S_RECEIPTS_UNAVAIL \
(1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 5))
/*
* Finally, function prototypes for the IDUP-GSS-API routines.
*/
OM_uint32 IDUP_Establish_env
(gss_cred_id_t /* claimant_cred_handle */
gss_OID /* mech_type */
int /* time_req */
int /* req_flag */
OM_uint32 * /* minor_status */
idup_env_id_t * /* env_handle */
gss_OID * /* mech_type */
int * /* time_rec */
int * /* ret_flags */
)
OM_uint32 IDUP_Abolish_env
(idup_env_id_t * /* env_handle */
OM_uint32 * /* minor_status */
)
OM_uint32 IDUP_Inquire_env
(idup_env_id_t /* env_handle */
OM_uint32 * /* minor_status */
int * /* lifetime_rec */
gss_OID * /* mech_type */
int * /* ret_flags */
)
OM_uint32 IDUP_Start_Protect (
(idup_env_id_t /* env_handle */
int /* digest_req_flag */
int /* conf_req_flag */
int /* qop_req */
idup_name_t_set /* targ_names */
int /* receipt_req_flag */
idup_name_t_set /* receipts_from */
idup_name_t_set /* receipts_to */
int /* prot_oper_id */
OM_uint32 * /* minor_status */
int * /* digest_state */
int * /* conf_state */
idup_name_t_set /* bad_targ_names */
)
Grebovich 35 Expires: September 30, 1995 OM_uint32
IDUP_Protect
(idup_env_id_t /* env_handle */
gss_buffer_t /* input buffer */
OM_uint32 * /* minor status */
gss_buffer_t /* output_buffer */
)
OM_uint32 IDUP_End_Protect
(idup_env_id_t /* env_handle */
OM_uint32 * /* minor status */
gss_buffer_t /* output_buffer */
gss_buffer_t /* prot_token */
)
OM_uint32 IDUP_Start_Unprotect
(idup_env_id_t /* env_handle */
gss_buffer_t /* prot_token */
int /* prot_oper_id */
OM_uint32 * /* minor_status */
int /* conf_state */
int /* digest_state */
int /* qop_state */
gss_buffer_t /* originator_info */
)
OM_uint32 IDUP_Unprotect
(idup_env_id_t /* environment_handle */
gss_buffer_t /* input buffer */
OM_uint32 * /* minor status */
gss_buffer_t /* output_buffer */
OM_uint32 IDUP_End_Unprotect
(idup_env_id_t /* env_handle */
OM_uint32 * /* minor status */
gss_buffer_t /* output_buffer */
gss_buffer_t /* receipt_token */
);
OM_uint32 IDUP_Process_Receipt
(idup_env_id_t /* env_handle */
gss_buffer_t /* receipt_token */
OM_uint32 * /* minor status */
gss_buffer_t /* originator_info */
);
OM_uint32 GSS_Display_status
(OM_uint32*, /* minor_status */
OM_uint32, /* status_value */
int, /* status_type */
gss_OID, /* mech_type */
int*, /* message_environment */
gss_buffer_t /* status_string */
);
Grebovich 36 Expires: September 30, 1995 OM_uint32
GSS_Indicate_mechs
(OM_uint32*, /* minor_status */
gss_OID_set* /* mech_set */
);
OM_uint32 GSS_Compare_name
(OM_uint32*, /* minor_status */
gss_name_t, /* name1 */
gss_name_t, /* name2 */
int* /* name_equal */
);
OM_uint32 GSS_Display_name,
(OM_uint32*, /* minor_status */
gss_name_t, /* input_name */
gss_buffer_t, /* output_name_buffer */
gss_OID* /* output_name_type */
);
OM_uint32 GSS_Import_name
(OM_uint32*, /* minor_status */
gss_buffer_t, /* input_name_buffer */
gss_OID, /* input_name_type */
gss_name_t* /* output_name */
);
OM_uint32 GSS_Release_name
(OM_uint32*, /* minor_status */
gss_name_t* /* input_name */
);
OM_uint32 GSS_Release_buffer
(OM_uint32*, /* minor_status */
gss_buffer_t /* buffer */
);
OM_uint32 GSS_Release_oid_set
(OM_uint32*, /* minor_status */
gss_OID_set* /* set */
);
OMuint IDUP_Parse_token
(gss_buffer_t /* input_token */
OM_uint32 * /* minor status */
gss_OID * /* mech_type */
int /* token_type */
)
/*
* IDUP Token Types
*/
#define IDUP_PROT_TOKEN 1
#define IDUP_RECEIPT_TOKEN 2
#endif /* IDUP-GSS-API_H_ *
Grebovich 37 Expires: September 30, 1995
| PAFTECH AB 2003-2026 | 2026-04-23 06:11:14 |