This call generates a PIDU which can be unprotected successfully with
no additional data at any time during its validity period. [For
background information on the notion of "complete" evidence, see
"CORBA Security Service v1.2 Draft D02", 18 June 1997.]
Using the security environment referenced by env_handle, complete the
generation of a P-IDU token and return the appropriate status value
along with the completed token (if available). Such a call may be
used, for example, for the purpose of batch evidence generation on an
"evidence server". A local machine may be able to use the protection
set of calls to fill out most of an evidence token and then send a
number of these to a batch processor which forms the complete
evidence tokens (perhaps by adding a certification path, or a
timestamp and signature from a timestamping authority). As another
example, on the receiving end an application may make such a call in
order to collect all the information necessary to unprotect a P-IDU
(such as all relevant certificates and Certificate Revocation Lists);
this will ensure that the calls to the unprotection set of operations
will be entirely local (i.e., can be performed off-line) and fast.
Note that the complete P-IDU generated will be formed using trusted
time if this is available in the environment referenced by env_handle
and will use untrusted time or no time otherwise (depending on what
is available).
2.5. Support calls
2.5.1. Relationship to GSS-API
Support calls in IDUP-GSS-API are to be understood and used as
described in GSS-API [RFC-2078]. The calls described in Section 2.4
of GSS-API (including all associated parameters) are unchanged. The
following additional calls are specified for IDUP-GSS-API.
2.5.2: IDUP_Acquire_cred_with_auth call
Inputs:
o desired_name INTERNAL NAME,
-- NULL requests locally-determined default
o authenticator OCTET STRING
-- string which authenticates the caller claiming to be
-- desired_name
o lifetime_req INTEGER,
-- in seconds; 0 requests default
o desired_mechs SET OF OBJECT IDENTIFIER,
-- empty set requests system-selected default
o cred_usage BIT STRING
-- actual values which can be used currently correspond to those
-- given in Section 2.1.1 (i.e.,
-- ENCRYPT_ONLY 8
-- DECRYPT_ONLY 16
-- SIGN_ONLY 32
-- VERIFY_ONLY 64
-- with the values logically OR'ed together in any desired
-- combination to restrict credential usage; OR'ing all values
-- results in NO_RESTRICTION).
-- Future possible values for this parameter are for further
-- study (note that the type of this parameter is BIT STRING
-- (rather than INTEGER as in GSS_Acquire_cred) to facilitate
-- such future expansion).
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_cred_handle CREDENTIAL HANDLE,
o actual_mechs SET OF OBJECT IDENTIFIER,
o actual_cred_usage BIT STRING,
o lifetime_rec INTEGER
-- in seconds, or reserved value for INDEFINITE
This call (which need not be supported by all underlying mechanisms
or implementations) is identical to the GSS_Acquire_cred call, with
the exception of the added input parameter "authenticator" and the
added output parameter "actual_cred_usage". The authenticator
(typically a password, pass-phrase, or PIN) is used to authenticate
the caller claiming to be desired_name to the underlying GSS (or
mechanism) code. The actual_cred_usage specifies the actual uses
available for these credentials; it is up to the caller to determine
if this is sufficient for its purposes.
Implementations that are able to authenticate the caller in some
other way are encouraged to use the GSS_Acquire_cred call; those
having no other means available to them, or wishing to explicitly
authenticate the caller at the time of credential acquisition, should
use the IDUP_Acquire_cred_with_auth call (if supported).
Note that the return major status codes for this call are identical
to those given for the GSS_Acquire_cred call. If the authentication
fails (e.g., the wrong authenticator is supplied for the given
desired_name), the major status GSS_S_FAILURE is returned (along with
an appropriate minor status code).
2.5.3. IDUP_Get_token_details call
Inputs:
o token OCTET STRING,
-- all the data to be returned shall be within the first 4 KB of
-- the token; hence, a single call is needed. It is not necessary
-- to provide the entire token when the token includes the IDU.
o mech_type SET OF OBJECT IDENTIFIER
-- input if known (typically SET will contain a single member)
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o actual_mech_type OBJECT IDENTIFIER,
o data_included_in_token BOOLEAN,
-- true if the data is encapsulated
o idu_size INTEGER,
o has_SE_protection BOOLEAN,
o has_EV_protection BOOLEAN,
o PIDU_Information PARAMETER BUNDLE,
o nr_policy OBJECT IDENTIFIER,
-- this and subsequent parameters pertain only to evidence tokens
o Nr_Options PARAMETER BUNDLE,
o Originator_Information PARAMETER BUNDLE,
o time_stamping_time INTEGER OPTIONAL
o Request_Features PARAMETER BUNDLE,
-- describes the included request, if any.
o requested_evidence_back BOOLEAN,
-- true if this is an evidence generated in response to a
-- previously-sent request
o evidence_check OCTET STRING,
-- meaningful if the boolean above is true
Return major_status codes:
o GSS_S_COMPLETE
-- input_token could be parsed for all relevant fields.
o GSS_S_CREDENTIALS_EXPIRED
o GSS_S_DEFECTIVE_TOKEN
-- the mechanism type could be parsed, but either the other fields
-- could not be determined from the input_token, or their values
-- did not correspond to valid values for that mechanism.
o GSS_S_FAILURE
-- the mechanism type was missing or corrupted.
IDUP_Get_token_details() is used to return to an application the
attributes that 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.
If all tokens are framed as suggested in Section 3.1 of [RFC-2078]
(mandated in the Kerberos V5 GSS mechanism [RFC1964] and in the SPKM
GSS Mechanism [RFC2025]), then any mechanism implementation should
be able to return the mech_type parameter for any uncorrupted input
token. If the mechanism implementation whose IDUP_Get_token_details()
function is being called does recognize the token, it can return any
further relevant information in the other token attributes, as
specified. In particular, this function can set has_SE_protection if
the SE calls may be used to unprotect it, or has_EV_protection if the
EV calls may be used to unprotect it, or both if both kinds of
protection have been applied (so that SE or EV calls may be used in
any order for unprotection) [note that GP calls, when supported,
should be usable for unprotection of any IDUP token].
IDUP_Get_token_details (which need not be supported by all underlying
mechanisms or implementations) gives only a hint about the content of
the token, there is no integrity check of any kind performed.
Regardless of the token type, it is possible to check that this
information is correct only by doing a proper unprotection of the
token. It is recommended that IDUP callers supply a token buffer at
least 4 KB in length in order to ensure that the desired data can
easily flow across this interface.
The OID of the mechanism and whether the token contains the
associated data is returned. In addition the size of the associated
data, whether inside or outside the token, is included if known.
[Note: data size will typically be unknown if the data was protected
using multibuffer calls. A value of "-1" may be used to indicate
"UNKNOWN".]
When the input token contains only an evidence generated
spontaneously, the following is returned:
- the evidence type;
- the Non-Repudiation policy under which the evidence was generated;
- the name of the generator of the evidence;
- the date and time when the evidence was generated (if available);
- the date and time when it was time stamped (if available).
When the input token contains only an evidence generated in response
to a request from another entity, the following additional
information is returned:
- an indicator to state that this evidence relates to a request;
- a string significant for the requester that will allow him to
check whether the answer corresponds to the requested evidence.
When the input token only contains a request, the following is
returned:
- the name of the requestor of the evidence,
- the date and time when the request was made,
- the evidence type to send back,
- the non-repudiation policy under which the evidence to send back
should be generated,
- the names of the recipients which should generate and distribute
the requested evidence,
- the names of the recipients to whom the requested evidence should
be sent after it has been generated.
When the input token contains both evidence and a request, an
indicator is returned describing whether the new evidence should be
generated using only the data in the input token, or using both the
data and the evidence in the input token.
When the input token contains only CONF and DOA services, the
PIDU_Information bundle is returned. Other relevant parameters (such
as idu_size and time_stamping_time) may also be returned if this data
is available.
2.5.4. IDUP_Get_policy_info call
Inputs:
o policy_id OBJECT IDENTIFIER
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o policy_version INTEGER,
o policy_effective_time INTEGER,
o policy_expiry_time INTEGER,
o supported_services SET OF Service_Descriptor,
-- services supported by this particular policy_id (equal to the
-- intersection of the services supported by the mechanisms
-- listed in supported_mechanisms)
o supported_mechanisms SET OF Mechanism_Descriptor
-- mechanisms supported by this particular policy_id
Return major_status codes:
o GSS_S_COMPLETE
-- policy_id recognized; all relevant fields have been returned.
o GSS_S_FAILURE
-- the policy_id was not recognized.
This call (which need not be supported by all underlying mechanisms
or implementations) allows the application to retrieve information
pertaining to a given policy_id. Policies define the following:
- rules for the protection of IDUs, such as trusted third
parties which may be involved in P-IDU generation, the roles in
which they may be involved, and the duration for which the
generated P-IDU is valid;
- rules for the unprotection of P-IDUs, such as the interval
during which a trusted third party may legitimately declare its
key to have been compromised or revoked; and
- rules for adjudication, such as which authorities may be used
to adjudicate disputes.
The policy itself may be used by an adjudicator when resolving a
dispute. For example, the adjudicator might refer to the policy to
determine whether the rules for generation of the P-IDU have been
followed.
The following parameter bundles are associated with this call.
o Service_Descriptor PARAMETER BUNDLE,
o service_type OBJECT IDENTIFIER,
o service_validity_duration INTEGER,
o must_use_trusted_time BOOLEAN
o Mechanism_Descriptor PARAMETER BUNDLE,
o mechanism_type OBJECT IDENTIFIER,
o Authority_List PARAMETER BUNDLE,
o maximum_time_skew INTEGER
-- maximum permissible difference between P-IDU generation
-- time and the time of countersignature from a time
-- service (if required). This parameter is unused if
-- trusted time is not required.
o Authority_List PARAMETER BUNDLE,
o authority_name INTERNAL NAME,
o authority_role OCTET STRING,
o last_revocation_check_offset INTEGER
-- may be 0, greater than 0, or less than 0. The value of
-- this parameter is added to P-IDU generation time to
-- get latest time at which the mechanism will check to
-- see if this authority's key has been revoked.
An example of the use of the last parameter in Authority_List is as
follows. If an authority has a defined last_revocation_check_offset
of negative one hour, then all revocations taking effect earlier than
one hour before the generation of a P-IDU will render that P-IDU
invalid; no revocation taking place later than one hour before the
generation of the P-IDU will affect the P-IDU's validity.
Note that both the maximum_time_skew and the
last_revocation_check_offset values are given in minutes.
2.5.5. IDUP_Cancel_multibuffer_op call
Inputs:
o env_handle ENVIRONMENT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
Return major_status codes:
o GSS_S_COMPLETE
-- operation cancelled; state purged.
o GSS_S_FAILURE
-- unable to cancel operation; state retained.
This call (which need not be supported by all underlying mechanisms
or implementations) allows the application to cancel a multibuffer
operation prior to normal completion (e.g., subsequent to calling
Start_operation and zero or more Process_operation, but prior to
calling End_operation). When successful, this call purges any
internal state information which would have been used to continue
processing for the full set of multibuffer calls.
3. Related Activities
In order to implement the IDUP-GSS-API atop existing, emerging, and
future security mechanisms, the following is necessary:
- object identifiers must be assigned to candidate IDUP-GSS-API
mechanisms and the name types which they support; and
- concrete data element (i.e., token and parameter bundle) formats
must be defined for candidate mechanisms.
Calling applications must implement formatting conventions which will
enable them to distinguish IDUP-GSS-API P-IDUs from other IDUs in
their environment.
Concrete language bindings are required for the programming
environments in which the IDUP-GSS-API is to be employed.
4. Acknowledgments
Many thanks are due to Tim Moses and Dhanya Thakkar of Entrust
Technologies, Denis Pinkas of Bull, and David Kurn of Tandem
Computers for a number of helpful comments and contributions.
5. Security Considerations
Security issues are discussed throughout this memo.
6. REFERENCES
[MSP] U.S. National Security Agency, "Message Security
Protocol", Secure Data Network System SDN.701, March
1994.
[RFC-1421] Linn, J., "Privacy Enhancement for Internet Electronic
Mail: Part I: Message Encryption and Authentication
Procedures", RFC1421, February 1993.
[RFC-2078] Linn, J., "Generic Security Service Application Program
Interface, Version 2", RFC2078, January 1997..
[RFC1964] Linn, J, "The Kerberos Version 5 GSS-API Mechanism", RFC
1964, June 1996.
[RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism
(SPKM)", RFC2025, October 1996.
[ISO/IEC] 2nd ISO/IEC CD 13888-1, "Information technology -
Security techniques - Non-repudiation - Part 1: General
Model", ISO/IEC JTC 1/SC 27, May 30, 1995
7. Author's Address
Carlisle Adams
Entrust Technologies
750 Heron Road, Suite E08,
Ottawa, Ontario, CANADA K1V 1A7
Phone: +1 613.247.3180
EMail: cadams@entrust.com
APPENDIX A: MECHANISM-INDEPENDENT TOKEN FORMAT
This appendix specifies the use, for IDUP-GSS-API tokens, of the
mechanism-independent level of encapsulating representation for
tokens given in Section 3.1 of GSS-API [RFC-2078]. The
representation given there incorporates an identifier of the
mechanism type to be used when processing the associated tokens. Use
of that octet format 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. It is recognized,
however, that for interoperability purposes with peers not using IDUP
for specific IDU protection/unprotection protocols, the encapsulating
representation may need to be omitted. (In such a case it is
necessary that the underlying mechanism provides some sort of
internal or external identification that allows it to recognize its
own tokens.) When the mechanism-independent level of encapsulating
representation is not desired, callers SHOULD set
mech_indep_encap_req to FALSE (note that some underlying mechanisms
may default this parameter to FALSE).
For purely descriptive purposes, the following simple ASN.1 structure
is used to illustrate the structural relationships among token and
tag objects. For interoperability purposes, token and tag encoding
shall be performed using the concrete encoding procedures described
in Section 3.1 of GSS-API [RFC-2078].
-- top-level token definition to frame different mechanisms
IDUP-GSS-API DEFINITIONS ::=
BEGIN
MechType ::= OBJECT IDENTIFIER
Token ::= [APPLICATION 0] IMPLICIT SEQUENCE {
thisMech MechType,
token ANY DEFINED BY thisMech
-- contents mechanism-specific
}
END
APPENDIX B: EXAMPLES OF IDUP USE
This appendix provides examples of the use of IDUP to do IDU
protection and unprotection. It should not be regarded as
constrictive to implementations or as defining the only means through
which IDUP-GSS-API functions can be realized with particular
underlying technology, and does not demonstrate all IDUP-GSS-API
features.
Most of the examples below only illustrate the use of CONF/DOA
protection services. Note that when both CONF/DOA and Evidence
services are required, calling applications may use a series of SE
and EV calls, or may use the GP calls (when these are supported).
Using the former approach implies multiple calls (e.g., the SE calls
are used to protect some data and the resulting token is then input
to the EV calls to add evidence information), but some callers may
find this to be more attractive than coding to the GP calls because
of the simpler SE/EV interface. Depending upon the underlying
mechanism, the series of SE/EV calls may result in a single token
that can be unprotected using the SE and EV calls in any order (for
example, because it is a single ASN.1 SEQUENCE that incorporates all
the specified protection services at one level), or the series may
result in a token that can only be unprotected in the reverse order
of protection (for example, because each SE/EV output token was
effectively embedded in the token of the subsequent call). The
IDUP_Get_token_details call can assist callers in determining how to
unprotect any received token.
B.1. Simple Mechanism, Single Buffer
To illustrate the simplest possible case, consider an underlying IDUP
mechanism which does straightforward encryption/decryption and
signing/verification only using public-key techniques; none of the
other possible services, such as creation of proof-of-origin
evidence, requests for proof-of-delivery evidence, or use of trusted
time, are supported. PEM[RFC-1421] is one example of a mechanism
which fits this description. Furthermore (again for simplicity),
assume that encapsulation is chosen by the calling application during
IDU protection.
Such a mechanism would likely use the "SE" set of IDUP-GSS-API calls.
The following parameter bundle uses and defaults would therefore be
specified in the relevant IDUP mechanism document.
SENDER:
Set
env_handle = environment handle in use;
idu_buffer = data buffer;
Target_Info.targ_names = receiver names;
Protect_Options = as necessary;
Call
IDUP_SE_SingleBuffer_Protect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
Target_Info.Bad_Targ_Name,
(as required) for more detailed information.
Send
Output parameter pidu_buffer to receiver.
RECEIVER (any parameters not listed below are given the value NULL):
Set
env_handle = environment handle in use;
pidu_buffer = received data buffer;
Call
IDUP_SE_SingleBuffer_Unprotect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
(as required) for more detailed information
Utilize
PIDU_Information.Protect_Options.Protect_Operation,
(to determine which services were applied by the originator)
PIDU_Information.Protect_Options.sign_qop_alg / enc_qop_alg,
(to determine the corresponding qualities of the services)
Prot_Information.originator_name,
(to determine the name of the originator)
Prot_Information.protection_time,
(to determine when the IDU was protected)
idu_buffer
(to retrieve the unprotected data).
B.2. Simple Mechanism, Single Buffer (Again)
To illustrate a slight variation on the simplest possible case,
assume that everything is as in the previous scenario except that the
"GP" calls are used.
The following parameter bundle uses and defaults would therefore be
specified in the relevant IDUP mechanism document.
Mech_Specific_Info
- NOT USED (the only acceptable input, therefore, is NULL)
Idu_Sensitivity
- NOT USED (the only acceptable input, therefore, is NULL)
Service_Creation_Info
- NOT USED (the only acceptable input, therefore, is NULL)
Service_Verification_Info
- NOT USED (the only acceptable input, therefore, is NULL)
Quality
- the qop_algs parameter must be supported, with a suitable
DEFAULT value specified;
- suitable DEFAULT values for validity, policy_id, and
allow_policy_mapping must be specified (it may be an
implementation option as to whether these parameters are
explicitly modifiable by the calling application, or whether
NULLs are the only acceptable input)
Idu_Information
- the idu_type parameter must have a value representing a suitable
IDU type (for example, in PEM a value representing the string
"RFC822" or some other valid "Content-Domain" would be used),
with a suitable DEFAULT value specified;
- the idu_title parameter is NOT USED (the only acceptable input,
therefore, is NULL)
Prot_Information
- the originator_name and idu_type (in Idu_Information) parameters
are read from the encapsulating information and output by
IDUP_Start_Unprotect;
- all other parameters are NOT USED (and therefore NULL)
Special_Conditions
- NOT USED (the only acceptable input, therefore, is NULL)
Target_Info
- this bundle is used as described in IDUP; no DEFAULT values are
specified
General_Service_Data
- the unencapsulated_token parameter is used if
encapsulation_request is FALSE;
- the minor_status parameter is used to return minor status values
as specified by the mechanism document
Prot_Service
- the prot_service_type parameter may have a value of "1"
("perform unsolicited service") or NULL (which specifies the
DEFAULT value of "1");
- the service_id parameter must have a value representing
"PER_CONF" or "PER_DOA";
- the parameters Service_Creation_Info, service_to,
Service_Verification_Info, and service_verification_info_id are
NOT USED (and therefore NULL)
Unprot_Service
- the unprot_service_type parameter will always have a value of
"1" ("receive unsolicited service");
- the service_id parameter will have a value representing
"REC_CONF" or "REC_DOA";
- the parameters service_verification_info_id,
Service_Verification_Info, service_to, and
Service_Creation_Info, are NOT USED (and therefore NULL)
Assuming that the calling application has only a single buffer of
data to protect/unprotect, the following sequence of operations must
be performed by the sender and receivers (subsequent to environment
establishment).
SENDER (any parameters not listed below are given the value NULL):
Set
env_handle = environment handle in use;
encapsulation_request = TRUE;
single_idu_buffer = data buffer;
Target_Info.targ_names = receiver names;
P_Services.Prot_Service_1.service_id = PER_CONF;
P_Services.Prot_Service_2.service_id = PER_DOA;
Call
IDUP_Start_Protect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
Target_Info.bad_targ_names / Target_Info.bad_targ_status,
P_Services.Prot_Service_1.General_Service_Data.minor_status,
P_Services.Prot_Service_2.General_Service_Data.minor_status
(as required) for more detailed information.
Send
Output parameter pidu_buffer to receiver.
RECEIVER (any parameters not listed below are given the value NULL):
Set
env_handle = environment handle in use;
single_pidu_buffer = received data buffer;
Call
IDUP_Start_Unprotect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status,
R_Services.Unprot_Service_2.General_Service_Data.minor_status
(as required) for more detailed information
Utilize
R_Services.Unprot_Service_1/2.service_id,
(to determine which services were applied by the originator)
R_Services.Unprot_Service_1/2.Quality,
(to determine the corresponding qualities of the services)
Prot_Information.originator_name,
(to determine the name of the originator)
single_idu_buffer
(to retrieve the unprotected data).
B.3. Simple Mechanism, Multiple Buffers
To illustrate the next step up in complexity, consider the use of the
simple IDUP mechanism described in B.2 above with multiple data
buffers. In particular, consider the case in which a large data file
is to be signed. For this example, assume that the calling
application does not wish to use encapsulation.
Note that the parameter bundle uses and defaults are as specified in
B.2. above.
SENDER (any parameters not listed below are given the value NULL):
Set
env_handle = environment handle in use;
encapsulation_request = FALSE;
P_Services.Prot_Service.service_id = PER_DOA;
Call
IDUP_Start_Protect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
P_Services.Prot_Service.General_Service_Data.minor_status
(as required) for more detailed information.
For each buffer of input data:
Set
input_buffer = buffer
Call
IDUP_Protect() with above input parameter
Check
major_status. If not GSS_S_COMPLETE, check
minor_status
Call
IDUP_End_Protect()
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
P_Services.Prot_Service.General_Service_Data.minor_status
(as required) for more detailed information.
Send
P_Services.Prot_Service.General_Service_Data.unencapsulated_token,
and the file for which the signature was calculated (if required),
to receiver.
RECEIVER (any parameters not listed below are given the value NULL):
Set
env_handle = environment handle in use;
R_Services.Unprot_Service_1.General_Service_Data.
unencapsulated_token = received unencapsulated token;
Call
IDUP_Start_Unprotect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status,
(as required) for more detailed information
For each buffer of input data:
Set
input_buffer = buffer
Call
IDUP_Unprotect() with above input parameter
Check
major_status. If not GSS_S_COMPLETE, check
minor_status
Call
IDUP_End_Unprotect()
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status,
(as required) for more detailed information.
Utilize
R_Services.Unprot_Service_1.service_id,
(to determine which service was applied by the originator; note
that Unprot_Service_2 will have NULL in unprot_service_type
to indicate that it is not used)
R_Services.Unprot_Service_1.Quality,
(to determine the corresponding quality of the service)
Prot_Information.originator_name, (from IDUP_Start_Unprotect)
(to determine the name of the signer)
major_status (from IDUP_End_Unprotect)
(to determine pass/fail status of signature verification).
B.4. More Sophisticated Mechanism, Small Application Buffers
To illustrate a higher level of complexity, consider the use of a
more sophisticated IDUP mechanism and a calling application with
small data buffers. In particular, consider the case in which a very
small e-mail message is to be encrypted for a relatively large
receiver list (R), some subset of whom (r) will be asked to send
proofs of receipt of the message to some other subset (L) (which
includes the originator). So that the example is not unnecessarily
complicated, assume again that the originating application uses
encapsulation.
The uses and defaults for the various parameter bundles for this
mechanism would be specified in the relevant IDUP mechanism document
as follows.
Mech_Specific_Info
- NOT USED (the only acceptable input, therefore, is NULL)
Idu_Sensitivity
- NOT USED (the only acceptable input, therefore, is NULL)
Service_Creation_Info
- used to create "proof of delivery" evidence (but actual
structure is opaque to calling application)
Service_Verification_Info
- used to verify "proof of delivery" evidence (but actual
structure is opaque to calling application)
Quality
- the qop_algs parameter must be supported, with a suitable
DEFAULT value specified;
- suitable DEFAULT values for validity, policy_id, and
allow_policy_mapping must be specified (it may be an
implementation option as to whether these parameters are
explicitly modifiable by the calling application, or whether
NULLs are the only acceptable input)
Idu_Information
- the idu_type parameter must have a value representing a suitable
IDU type, with a suitable DEFAULT value specified;
- the idu_title parameter must have a value representing a
suitable IDU title, with a suitable DEFAULT value specified
Prot_Information
- the originator_name, protection_time, and idu_type / idu_title
(in Idu_Information) parameters are read from the contained
header information and output by IDUP_Start_Unprotect;
Special_Conditions
- the parameter prot_oper_id is NOT USED (the only acceptable
input, therefore, is NULL);
- trusted or untrusted time may be selected by the calling
application, with a suitable DEFAULT value specified
Target_Info
- this bundle is used as described in IDUP; no DEFAULT values are
specified
General_Service_Data
- the unencapsulated_token parameter is used if
encapsulation_request is FALSE;
- the minor_status parameter is used to return minor status values
as specified by the mechanism document
Prot_Service
- the prot_service_type parameter may have a value of "1"
("perform unsolicited service"), "2" ("perform solicited
service"), "3" (perform service solicitation), or NULL (which
specifies the DEFAULT value of "1");
- the service_id parameter must have a value representing
"PER_CONF", "PER_DOA", "PER_POO", or "PER_POD";
- the parameters Service_Creation_Info, service_to,
Service_Verification_Info, and service_verification_info_id are
used when required by the IDUP operation
Unprot_Service
- the unprot_service_type parameter may have a value of "1"
("receive unsolicited service"), "2" ("receive solicited
service"), or "3" (receive service solicitation);
- the service_id parameter will have a value representing
"REC_CONF", "REC_DOA", "REC_POO", or "REC_POD";
- the parameters service_verification_info_id,
Service_Verification_Info, service_to, and
Service_Creation_Info, are used when required by the IDUP
operation
SENDER (any parameters not listed below are given the value NULL):
Set
env_handle = environment handle in use;
Idu_Information.idu_type = value for "e-mail document";
Idu_Information.idu_title = "Contract 1234";
Special_Conditions.use_trusted_time = TRUE;
encapsulation_request = TRUE;
single_idu_buffer = very small e-mail message;
Target_Info.targ_names = receiver names (R);
Prot_Service_1.prot_service_type = "1";
Prot_Service_1.service_id = PER_CONF;
Prot_Service_2.prot_service_type = "3";
Prot_Service_2.service_id = PER_POD;
Prot_Service_2.General_Service_Data.Target_Info.targ_names
= "receipts from" list (r);
Prot_Service_2.service_to = "receipts to" list (L);
P_Services.Prot_Service_1 = Prot_Service_1;
P_Services.Prot_Service_2 = Prot_Service_2;
Call
IDUP_Start_Protect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE,
while major_status == IDUP_S_MORE_OUTBUFFER_NEEDED
Save
pidu_buffer,
Call
IDUP_Start_Protect() (to get next portion of pidu_buffer)
Check
major_status,
minor_status,
Target_Info.bad_targ_names / Target_Info.bad_targ_status,
P_Services.Prot_Service_1.General_Service_Data.minor_status,
P_Services.Prot_Service_2.General_Service_Data.minor_status
(as required) for more detailed information.
Save
Prot_Service_2.Service_Verification_Info,
Prot_Service_2.service_verification_info_id
Send
All saved buffers of pidu_buffer to receiver list (R).
RECEIVER (ON RECEIVER LIST (R)):
(any parameters not listed below are given the value NULL)
Set
env_handle = environment handle in use;
partial_pidu_buffer = initial buffer of received p-idu;
Call
IDUP_Start_Unprotect() with above input parameters
While major_status == IDUP_S_MORE_PIDU_NEEDED,
Set
partial_pidu_buffer = next buffer of p-idu
Call
IDUP_Start_Unprotect()
Check
major_status,
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status,
R_Services.Unprot_Service_2.General_Service_Data.minor_status,
(as required) for more detailed information
Save
initial_idu_buffer (if non-empty)
Set
input_buffer = remaining p-idu buffer
Call
IDUP_Unprotect() with above input parameter
Check
major_status. If not GSS_S_COMPLETE, check
minor_status
Save
output_buffer
Call
IDUP_End_Unprotect()
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status,
R_Services.Unprot_Service_2.General_Service_Data.minor_status,
(as required) for more detailed information.
Utilize
R_Services.Unprot_Service_1/2.service_id,
(to determine which services were applied by the originator)
R_Services.Unprot_Service_1/2.Quality,
(to determine the corresponding qualities of the service)
Prot_Information.originator_name/protection_time and
Prot_Information.Idu_Information.idu_type/idu_title,
(from IDUP_Start_Unprotect) (to determine originator info.)
R_Services.Unprot_Service_2.General_Service_Data.Target_Info.
targ.names, (to determine if rec. is in "receipts from" (r))
Service_Verification_Info/service_verification_info_id
(to determine if receiver is in "receipts to" list (L))
If receiver is in "receipts from" list (r)
Save
R_Services.Unprot_Service_2.service_to,
R_Services.Unprot_Service_2.Service_Creation_Info
If receiver is in "receipts to" list (L)
Save
Service_Verification_Info,
service_verification_info_id
RECEIVER (ON "RECEIPTS FROM" LIST (r)):
(procedure to generate receipt)
Set
env_handle = environment handle in use;
Target_Info.targ_names = service_to
Prot_Service_1.prot_service_type = "2";
Prot_Service_1.service_id = "PER_POD";
Prot_Service_1.Service_Creation_Info = Service_Creation_Info;
P_Services.Prot_Service_1 = Prot_Service_1
Call
IDUP_Start_Protect() with above input parameters
Check
major_status. If not GSS_S_COMPLETE, check
minor_status,
P_Services.Prot_Service_1.General_Service_Data.minor_status
(as required) for more detailed information.
Send
pidu_buffer to "receipts to" list (L)
RECEIVER (ON "RECEIPTS TO" LIST (L)):
(procedure to process received receipt)
Set
env_handle = environment handle in use;
single_pidu_buffer = received p-idu buffer (if it fits in a single
buffer; otherwise use partial_pidu_buffer and make multiple
calls, as above)
Call
IDUP_Start_Unprotect() with above input parameters
If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED
Utilize
R_Services.Unprot_Service_1.service_verification_info.id
(to assist in locating necessary Service_Verification_Info)
Set
R_Services.Unprot_Service_1.Service_Verification_Info
= Service_Verification_Info
Call
IDUP_Start_Unprotect() with above input parameters
Check
major_status,
minor_status,
R_Services.Unprot_Service_1.General_Service_Data.minor_status
(as required) for more detailed information.
Utilize
R_Services.Unprot_Service_1.service_id,
(to determine that this is a "proof of delivery" evidence)
R_Services.Unprot_Service_1.Quality,
Prot_Information.originator_name, (for evidence generator info.)
major_status (to determine pass/fail status of evi. verif.).
Full Copyright Statement
Copyright (C) The Internet Society (1998). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.