-- operation (e.g., so that PIDU_Information or initial_idu_buffer
-- may be returned).
o IDUP_S_INCONSISTENT_PARAMS
o GSS_S_CREDENTIALS_EXPIRED
o IDUP_S_NO_ENV
o GSS_S_BAD_QOP
o GSS_S_FAILURE
If Target_Info is used as an input parameter (e.g., if an encryption
operation is being performed), the following major_status return code
is also defined:
o IDUP_S_BAD_TARG_INFO
Note for this return code that if one or more of the targets in
targ_names cannot be used as a valid recipient of the P-IDU, these
names will be returned in bad_targ_names (with associated status
codes in bad_targ_status). As long as at least one of the targets
can be used, however, this does not cause this call to fail (i.e.,
the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the
caller's choice to discontinue IDU protection if the target set which
can be used is unsuitable for the caller's purposes.
2.3.2.4. IDUP_SE_SingleBuffer_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o Protect_Options PARAMETER BUNDLE,
o Target_Info PARAMETER BUNDLE,
o idu_buffer OCTET STRING
o additional_protection BOOLEAN
-- TRUE if idu_buffer is the output of a previous protection
-- operation (i.e., if this is the second (or higher) in a
-- series of SE/EV protection calls)
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o pidu_buffer OCTET STRING,
o sig_token OCTET STRING
-- used if Protect_Options is clear_sign_only
Using the security environment referenced by env_handle, encrypt
and/or sign the supplied IDU. If "clear signing" is performed, the
signature will be returned in sig_token and pidu_buffer may be empty
(depends on underlying mechanism).
2.3.2.5. IDUP_SE_SingleBuffer_Unprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o pidu_buffer OCTET STRING,
-- may contain an IDU if sig_token is non-NULL (i.e., if
-- clear_sign_only protection was applied)
o sig_token OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o idu_buffer OCTET STRING,
-- may be empty if clear_sign_only protection was applied (depends
-- on underlying mechanism)
o PIDU_Information PARAMETER BUNDLE
o additional_unprotection BOOLEAN
-- TRUE if idu_buffer should be input to another unprotection
-- operation (i.e., if this should not be the last in a series
-- of SE/EV unprotection calls)
Using the security environment referenced by env_handle, decrypt
and/or verify the supplied PIDU and return the contained IDU along
with all available PIDU_Information.
2.3.2.6. IDUP_SE_MultiBuffer_StartProtect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o Protect_Options PARAMETER BUNDLE,
o Target_Info PARAMETER BUNDLE,
o additional_protection BOOLEAN, -- (see Section 2.3.2.4)
o idu_size INTEGER -- (see Section 2.3.4.2)
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o initial_pidu_buffer OCTET STRING
-- may be empty (depends on underlying mechanism)
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of signing and/or
encrypting the IDU (which will be supplied in multiple buffers to the
Process_Buffer call).
2.3.2.7. IDUP_SE_MultiBuffer_EndProtect call
Inputs:
o env_handle ENVIRONMENT HANDLE
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o final_pidu_buffer OCTET STRING,
o sig_token OCTET STRING
-- used if Protect_Options was clear_sign_only
Using the security environment referenced by env_handle, complete the
protection processing on the data and place the computed output in
final_pidu_buffer and/or sig_token. Successful application of
IDUP_SE_MultiBuffer_EndProtect() does not guarantee that unprotection
can necessarily be performed successfully when the P-IDU arrives at
the target (for example, it may be damaged in transit).
2.3.2.8. IDUP_SE_MultiBuffer_StartUnprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o initial_pidu_buffer OCTET STRING,
o sign_qop_alg_in UNSIGNED INTEGER,
-- used if Protect_Options was clear_sign_only (and calling
-- application has prior knowledge of signing alg. applied);
-- if NULL, then sig_token must be supplied
o sig_token OCTET STRING
-- used if Protect_Options was clear_sign_only;
-- if NULL, then sign_qop_alg_in must be supplied
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o PIDU_Information PARAMETER BUNDLE,
-- returns all available information
o initial_idu_buffer OCTET STRING
-- may be empty
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of decrypting
and/or verifying the PIDU (which will be supplied in multiple buffers
to the Process_Buffer call).
The parameters sign_qop_alg_in and sig_token should not both be
supplied (i.e., they should not both be non-NULL). If they are both
non-NULL, however, sig_token is taken to be authoritative since this
is the token created at protection time and therefore is guaranteed
to carry the information needed to unprotect.
2.3.2.9. IDUP_SE_MultiBuffer_EndUnprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o sig_token OCTET STRING OPTIONAL
-- used if Protect_Options was clear_sign_only and sig_token was
-- not available when StartUnprotect was called
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o PIDU_Information PARAMETER BUNDLE,
-- returns all available information
o final_idu_buffer OCTET STRING -- may be empty
o additional_unprotection BOOLEAN -- (see Section 2.3.2.5)
Using the security environment referenced by env_handle, complete the
decryption and/or verification processing on the data and place any
residual output in final_idu_buffer.
2.3.2.10. IDUP_SE_Process_Buffer call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o input_buffer OCTET STRING,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_buffer OCTET STRING
-- may be zero length (depends on underlying mechanism and
-- corresponding Start() call and Protect_Options value)
Using the security environment referenced by env_handle, continue the
processing on the data in input_buffer and, if it is available, put
any resulting output data in output_buffer. The application calls
this routine over and over again with new buffers of data until it
has processed all the data buffers of the IDU/PIDU. It then calls the
appropriate End() call to complete the processing.
2.3.3. The "EV" Calls
2.3.3.1. IDUP_EV Purpose
The "EV" group of calls provides a simple, high-level interface to
underlying IDUP mechanisms when application developers need to deal
only with evidence but not with encryption or integrity services. It
includes both the single-buffer and multiple-buffer IDU cases and can
be used for the generation and verification of evidence tokens
embodying several different types of evidences.
The following list of evidence types is supported. This list is by no
means exhaustive and it is anticipated that it may be extended in
future versions of this specification.
"Non-repudiation of Origin" prevents a message creator's false
denial of creating and sending a message.
"Non-repudiation of Creation" prevents a message creator's false
denial of creating a message.
"Non-repudiation of Sender" prevents a message creator's false
denial of sending a message (that was not necessarily created by
the sender).
"Non-repudiation of Delivery" prevents a message recipient's false
denial of having received and looked at the content of a message.
"Non-repudiation of Receipt" prevents a message recipient's false
denial of having received a message (whose content was not
necessarily looked at by the recipient).
"Non-repudiation of Approval" prevents a message recipient's false
denial of having approved the content of a received message.
An evidence is provided in the form of a evidence token. Two forms of
evidence tokens are supported:
o Tokens including the associated data,
o Tokens without included data (but with a unique reference to
the associated data).
Evidence tokens may be freely distributed. Any possessor of an
evidence token (and of the associated data, if not included in the
token) can verify the evidence if it has the appropriate credentials
which include the definition of security policies (i.e., keys alone
do not permit the verification of evidence tokens). Any holder of an
evidence token may store it (along with the associated data, if not
included in the token) for later verification.
Calls that are specific to the support of evidence include:
* Generate_token, which generates a non-repudiation token using the
current environment. The generated token may consist of:
1 - an evidence token
2 - a token containing a request for an evidence, which carries
information describing which evidence type should be generated
by the recipient(s) and sent back to some entities (that may
or may not include the sender).
3 - a token containing an evidence token which is an answer to an
evidence that has been previously requested.
4 - a token including both an evidence and a request for another
evidence to be provided.
* Verify_evidence, which verifies the evidence token using the
current environment. This operation returns a major_status code
which can be used to determine whether the evidence contained in a
token is complete (i.e., can be successfully verified (perhaps
years) later). If a token's evidence is not complete, the token can
be passed to form_complete_pidu to complete it.
Additional useful calls for evidence services include:
* IDUP_Get_token_details (see Section 2.5.3);
* IDUP_Form_Complete_PIDU (see Section 2.4.2).
2.3.3.2. IDUP_EV Parameters
The following parameter bundles are used in the "EV" protection and
unprotection sets of calls.
o Nr_Options PARAMETER BUNDLE
o evidence_type INTEGER {
no_evidence (0)
-- used when request-only token desired
proof_of_receipt (1),
proof_of_delivery (2),
proof_of_approval (3),
proof_of_creation (4),
proof_of_sender (5),
proof_of_origin (6)
} OPTIONAL,
o evidence_type_oid OBJECT IDENTIFIER OPTIONAL,
-- may be used in place of above parameter if OID is known
o evidence_validity_duration INTEGER,
-- duration_in_minutes
-- DURATION_HOUR = 60;
-- DURATION_DAY = 1440;
-- DURATION_WEEK = 10080;
-- DURATION_MONTH = 43200;// 30 days
-- DURATION_YEAR = 525600;//365 days
o mech_indep_encap_req BOOLEAN -- (see Appendix A)
o Originator_Information PARAMETER BUNDLE
o token_generator_name INTERNAL NAME,
-- obtained from the credentials of the originator
-- (e.g., from its public key certificate)
o token_generator_role Originator_Role OPTIONAL,
-- (see Section 2.3.4.1)
o protection_time INTEGER OPTIONAL
o Bad_Target_Name PARAMETER BUNDLE -- (see Section 2.3.2.2)
o bad_targ_name INTERNAL NAME,
o bad_targ_status INTEGER
-- a status flag giving the reason for rejection of the
-- name in bad_targ_name
o Target_Info PARAMETER BUNDLE -- same as in Section 2.3.2.2
o targ_names SET OF INTERNAL NAME,
o bad_targ_count INTEGER,
o bad_target_names SET OF Bad_Target_Name
o Request_Features PARAMETER BUNDLE
o requested_evidence_type INTEGER {
no_evidence (0), - used when no token desired
proof_of_receipt (1),
proof_of_delivery (2),
proof_of_approval (3), },
o nr_req_policy OBJECT IDENTIFIER,
o evidence_from Target_Info,
o evidence_to Target_Info,
o include_received_token_in_evidence BOOLEAN
The following data_type is used in the "EV" protection calls.
o Nr_Operation INTEGER {
evidence_and_or_evidence_request (1),
returned_evidence (2) }
2.3.3.3. IDUP_EV major_status codes
The following major_status return codes are defined for the "EV"
calls in this section:
o GSS_S_COMPLETE
-- indicates that the evidence is complete
o IDUP_S_INCOMPLETE
o IDUP_S_MORE_OUTBUFFER_NEEDED
-- returned (by any EV call) to indicate that there is more output
-- data than can fit into the supplied buffers. The application
-- should save the returned data and call again to retrieve the
-- remaining output.
o IDUP_S_INCONSISTENT_PARAMS
o GSS_S_CREDENTIALS_EXPIRED
o IDUP_S_NO_MATCH
o IDUP_S_NO_ENV
o GSS_S_FAILURE
If Target_Info is used as an input parameter (i.e., if an evidence is
being requested ), the following major_status return code is also
defined:
o IDUP_S_BAD_TARG_INFO
Note for this return code that if one or more of the targets in
targ_names cannot be used as a valid recipient of the P-IDU, these
names will be returned in bad_targ_names (with associated status
codes in bad_targ_status). As long as at least one of the targets
can be used, however, this does not cause this call to fail (i.e.,
the failure code IDUP_S_BAD_TARG_INFO is not returned); it is the
caller's choice to discontinue IDU protection if the target set which
can be used is unsuitable for the caller's purposes.
2.3.3.4. IDUP_EV_SingleBuffer_Generate call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o nr_operation Nr_Operation,
o Nr_Options PARAMETER BUNDLE,
o idu_buffer OCTET STRING,
o form_complete_pidu BOOLEAN,
-- if TRUE the implementation will attempt to form a complete PIDU
o include_data_in_token BOOLEAN,
-- if TRUE, data provided in idu_buffer will be included in the
-- generated token; if FALSE, the data will not be included
o Request_Features PARAMETER BUNDLE
-- the type of the evidence that is requested;
-- policy under which the returned evidence should be generated;
-- the recipients that are supposed to send back an evidence;
-- the recipients that should receive the requested evidence;
-- an indicator include_received_token_in_evidence:
-- if TRUE, the evidence token incorporating the request will be
-- included in the data for which recipients will generate
-- evidence; if FALSE, evidence will be generated using only
-- the data (and not the token incorporating the request).
o additional_protection BOOLEAN -- (see Section 2.3.2.4)
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o token OCTET STRING,
o evidence_check OCTET STRING,
-- present only if an evidence is requested. Consists of data to
-- be used to verify the requested token(s) (if any) when they are
-- received.
Description:
This operation generates a non-repudiation token associated with the
data passed in an input buffer. Two kinds of operations can be
performed (using the Nr_Operation parameter):
a) generating a token that includes either an evidence only, or
an evidence request only, or both an evidence and an evidence
request;
b) generating a response token for some recipients that includes an
evidence generated as a response to a request (in this case the
idu_buffer is used to enter the request token that was received).
It is possible to request the generation of complete evidence. This
may succeed or fail; if it fails, a subsequent call to
Form_Complete_PIDU can be made.
2.3.3.5. IDUP_EV_SingleBuffer_Verify call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o token OCTET STRING,
o external_idu_buffer OCTET STRING,
-- if not present within the token
o evidence_check OCTET STRING,
-- present only if the input token is a response to a previous
-- request for evidence (this parameter is used to validate that
-- evidence).
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o Nr_Options PARAMETER BUNDLE,
o Originator_Information PARAMETER BUNDLE,
o Request_Features PARAMETER BUNDLE,
o trusted_time_stamping_time INTEGER OPTIONAL,
-- present for informational purposes only
o complete_evidence_before INTEGER OPTIONAL,
-- if the major status code that is returned is
-- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called
-- with the same token before this time.
-- This may be required, for example, in order to insure that
-- the time skew between the evidence generation time and
-- the trusted time service's countersignature on the evidence
-- falls within the interval allowed by the current NR policy.
o complete_evidence_after INTEGER OPTIONAL,
-- if the major status code that is returned is
-- IDUP_S_INCOMPLETE, IDUP_Form_Complete_PIDU should be called
-- with the same token after this time.
-- This may be required, for example, to insure that all
-- authorities involved in generating the evidence have passed
-- the last time at which the current NR policy allows them to
-- repudiate their keys.
o encapsulated_idu_buffer OCTET STRING
-- if the IDU was present within the token
o additional_unprotection BOOLEAN -- (see Section 2.3.2.5)
Description:
Verifies the validity and discloses the content of a nr_token.
If the token containing the evidence to be verified was provided to
the calling application by a partner responding to the calling
application's request, then the calling application must pass the
evidence check it received when it generated the request as a
parameter along with the token it received from the partner.
Output indicators are provided which give guidance about the time or
times at which form_complete_pidu should be called; see the parameter
descriptions for explanations of these indicators and their use. Note
that the time specified by complete_evidence_before may be earlier
than that specified by complete_evidence_after; in this case it will
be necessary to call form_complete_pidu twice.
Because keys can be revoked or declared compromised, the return from
verify_evidence cannot in all cases be a definitive "valid" or
"invalid"; sometimes "conditionally valid" may be returned, depending
upon the policy in use. IDUP_S_INCOMPLETE will be returned, for
example, if:
- the interval during which the generator of the evidence may
permissibly declare his key invalid has not yet expired (and
therefore it is possible that the evidence may be declared invalid
in the future), or
- trusted time is required for verification, and the time obtained
from the token is not trusted.
2.3.3.6. IDUP_EV_MultiBuffer_StartGenerate call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o nr_operation Nr_Operation,
o Nr_Options PARAMETER BUNDLE,
o form_complete_pidu BOOLEAN,
o include_data_in_token BOOLEAN,
o idu_size INTEGER, -- (see Section 2.3.4.2)
o Request_Features PARAMETER BUNDLE
o additional_protection BOOLEAN -- (see Section 2.3.2.4)
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o initial_pidu_buffer OCTET STRING
-- may be empty (depends on underlying mechanism)
Description:
Using the security environment referenced by env_handle, initialize
the data structures required to begin the generation of a token. The
IDU will be supplied in multiple buffers to the
IDUP_EV_Process_Buffer call). Two kinds of operations can be
performed (using the Nr_Operation parameter) :
a) generating a token that includes either an evidence only, or
an evidence request only, or both an evidence and an evidence
request.
b) generating a return token for some recipients that includes an
evidence generated as a response to a request. In that case the
received token will be passed into the subsequent
IDUP_EV_Process_Buffer calls. The boolean include_data_in_token
is ignored as the output will always be contained in a single
token. The Request_Features are ignored in that case at this
time in order to keep things simple and to avoid the piggy-
backing that is theoretically possible.
It is possible to request the generation of complete evidence. This
may succeed or fail; if it fails, a subsequent call to
Form_Complete_PIDU can be made.
2.3.3.7. IDUP_EV_MultiBuffer_EndGenerate call
Inputs:
o env_handle ENVIRONMENT HANDLE
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o final_pidu OCTET STRING,
o token OCTET STRING,
o evidence_check OCTET STRING
-- present only if an evidence is requested.
Description:
Using the security environment referenced by env_handle, provide the
requested token or the final P-IDU. A token will be generated if
encapsulation was not requested; otherwise, the final P-IDU is
provided.
2.3.3.8. IDUP_EV_MultiBuffer_StartVerify call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o token OCTET STRING,
o evidence_check OCTET STRING,
-- present only if an evidence has been previously requested.
Outputs:
o major_status INTEGER,
o minor_status INTEGER
Description:
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of verifying the
token. The P-IDU will be supplied in multiple buffers to the
IDUP_EV_Process_Buffer call.
2.3.3.9. IDUP_EV_MultiBuffer_EndVerify call
Input:
o env_handle ENVIRONMENT HANDLE
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o Nr_Options PARAMETER BUNDLE,
o Originator_Information PARAMETER BUNDLE,
o Request_Features PARAMETER BUNDLE,
o trusted_time_stamping_time INTEGER OPTIONAL,
o complete_evidence_before INTEGER OPTIONAL,
o complete_evidence_after INTEGER OPTIONAL,
o idu_buffer OCTET STRING
-- if the IDU was present within the token
o additional_unprotection BOOLEAN -- (see Section 2.3.2.5)
Description:
Using the security environment referenced by env_handle, complete the
verification processing on the data and provide verified output
parameters to the caller when the major status code is either:
o GSS_S_COMPLETE or
o IDUP_S_INCOMPLETE
2.3.3.10. IDUP_EV_Process_Buffer call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o input_buffer OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_buffer OCTET STRING
-- may be zero length (depends on underlying mechanism and
-- corresponding Generate () call and options
-- (e.g., data_included_in_token)
Description:
Using the security environment referenced by env_handle, continue the
processing on the data in input_buffer and, if it is available, put
any resulting output data in output_buffer. The application calls
this routine over and over again with new buffers of data until it
has processed all the data buffers of the IDU/PIDU. It then calls the
appropriate End() call to complete the processing.
2.3.4. The "GP" Calls
The "GP" group of calls provides a powerful interface to flexible and
sophisticated combinations of protection and unprotection services.
This power and flexibility, however, necessitates a more complex
interface than either the SE or the EV calls. Furthermore, such
combinations of services are not needed in many of the security
mechanisms in common use today (although this is likely to change as
time goes on). The GP calls are therefore specified to be OPTIONAL
and need not be supported by IDUP-conformant implementations. Note,
however, that the structure of IDUP tokens should be such that the
SE/EV and GP calls may be used interchangably by the receiver.
2.3.4.1. Parameter Bundles
The concept of "parameter bundles" is used in the calls presented in
the following subsections in order to simplify their presentation and
clarify their intended purpose and use (note that specific language
bindings may or may not use parameter bundles for its actual calling
conventions). A parameter bundle is simply a set of closely-related
parameters of a call which are either all used by / available to the
calling application or all not used by / unavailable to the calling
application. These parameters may be all input parameters, all
output parameters, or any combination of the two.
An example use envisioned for parameter bundles in a language such as
C would be as a structure, where individual parameters in the bundle
are structure members. The calling application wishing to use a
particular bundle would then allocate the appropriate structure
variable, assign the desired input values to the appropriate members,
and pass the address of the structure as the bundle "parameter". On
output, the values of the appropriate output members may be read. An
application not wishing to use a particular bundle (or one which is
satisfied with default values for all input parameters of the bundle
and which doesn't care about output values), can pass NULL as the
bundle "parameter". From the mechanism implementor's perspective, if
a parameter bundle is not supported (for example, if it represents a
security service which is not supported by the implementation), then
any non-NULL value passed as the bundle parameter will generate an
error status return code.
[Note that the parameter bundles given below, except where explicitly
referenced by the SE and EV calls, are specific to the (optional) GP
calls. Thus, these bundles need not be supported by IDUP-conformant
implementations if the GP calls are not supported.]
The following parameter bundles are used in the subsequent protection
and unprotection sets of calls. A parameter preceded by "(I)" is an
input parameter; one preceded by "(O)" is an output parameter; one
preceded by neither is an input if the bundle itself is an input and
is an output if the bundle itself is an output; one preceded by "(X)"
is the opposite: an output if the bundle itself is an input and an
input if the bundle itself is an output.
o Mech_Specific_Info PARAMETER BUNDLE
-- actual parameters included in this bundle are defined by (and
-- specific to) the underlying mechanism
o Sensitivity PARAMETER BUNDLE,
-- actual parameters included in this bundle are defined by (and
-- specific to) the underlying mechanism, but may include
-- codified values for "Unclassified", "Secret", "Top Secret",
-- and so on
o Service_Creation_Info PARAMETER BUNDLE
-- actual parameters included in this bundle are defined by (and
-- specific to) the underlying mechanism, but it is mandatory
-- that they include at least service_id and Quality
o Service_Verification_Info PARAMETER BUNDLE
-- actual parameters included in this bundle are defined by (and
-- specific to) the underlying mechanism, but it is mandatory
-- that they include at least service_id and Quality
o Quality PARAMETER BUNDLE
o qop_algs UNSIGNED INTEGER,
o qop_algID AlgorithmIdentifier, --overrides qop_algs
o validity UNSIGNED INTEGER,
-- protection guaranteed to be valid until time specified
o policy_id OBJECT IDENTIFIER,
-- security policy under which protection is/was carried out
o allow_policy_mapping BOOLEAN,
-- determines whether mapping between policy IDs is allowed
o actual_policy_time INTEGER
-- time at which the above policy rules came into effect
o Idu_Information PARAMETER BUNDLE,
o idu_type_oid OBJECT IDENTIFIER,
o idu_type_string OCTET STRING,
o idu_title OCTET STRING,
o idu_sensitivity Sensitivity,
o pidu_type_oid OBJECT IDENTIFIER,
o pidu_type_string OCTET STRING,
o pidu_title OCTET STRING,
o pidu_sensitivity Sensitivity,
o Prot_Information PARAMETER BUNDLE,
o originator_name INTERNAL NAME,
o originator_role Originator_Role,
o idu_information Idu_Information,
o protection_time INTEGER,
o Originator_Role PARAMETER BUNDLE, -- role in organization
o domain_name INTERNAL NAME OPTIONAL,
o role PRINTABLE STRING,
o role_info_is_authenticated BOOLEAN
-- TRUE if info. is authenticated (e.g., inside a cert.)
o Special_Conditions PARAMETER BUNDLE,
o prot_oper_id INTEGER,
o form_complete_pidu BOOLEAN,
-- input to protection operations for evidence generation
o pidu_in_solic_service BOOLEAN,
-- in protection operations, used as input for service
-- solicitation to request that receiver include the
-- received PIDU when generating the response. In unprot.
-- operations, used as output to inform receiver that PIDU
-- should be included when generating the response.
o use_trusted_time BOOLEAN,
o use_untrusted_time BOOLEAN,
o mech_indep_encap_req BOOLEAN -- (see Appendix A)
o Bad_Target_Name PARAMETER BUNDLE,
o (O) bad_targ_name INTERNAL NAME,
o (O) bad_targ_status INTEGER,
-- a status flag giving the reason for rejection of
-- the name in bad_targ_name. Specified reasons include:
-- SYNTAX_INVALID (0)
-- the syntax of the name is invalid;
-- NAME_UNRECOGNIZED (1)
-- the name is not recognized;
-- NAME_AMBIGUOUS (2)
-- the name cannot be resolved;
-- ACCESS_DENIED (3)
-- access to this target is denied;
-- CERTIFICATE_NOT_FOUND (4)
-- the encryption certificate of the target could
-- not be found.
o Target_Info PARAMETER BUNDLE,
o targ_names SET OF INTERNAL NAME,
o (O) bad_targ_count INTEGER,
o (O) bad_target_names SET OF Bad_Target_Name,
o General_Service_Data PARAMETER BUNDLE,
o target_info Target_Info,
o (X) unencapsulated_token OCTET STRING,
-- zero length if encapsulation_request is TRUE
o (O) minor_status INTEGER,
Three types of protection services are defined in IDUP. These are:
1. perform unsolicited service (i.e., act on a locally-generated
service request),
2. perform solicited service (i.e., act on a remotely-generated
service request), and
3. perform service solicitation (i.e., send a service request to
the remote end).
As an originator, applying data confidentiality with data integrity,
or data origin authentication with data integrity, or proof of origin
evidence is an example of service type 1. As a target, creating a
proof of delivery (i.e., receipt) evidence token as the result of a
request received from the originator is an example of service type 2.
Finally, as an originator, submitting a request that one or more
targets return a receipt for the data sent is an example of service
type 3.
The first four parameters in the Prot_Service parameter bundle
pertain to all service types; the fifth parameter is used if and only
if service type 2 is desired; parameters 6-8 are used if and only if
service type 3 is desired.
o Prot_Service PARAMETER BUNDLE
o (I) prot_service_type INTEGER,
o (I) service_id OBJECT IDENTIFIER,
o (I) quality Quality, -- NULL specifies default Quality
o (I) general_service_data General_Service_Data,
o (I) service_creation_info Service_Creation_Info,
o (I) service_to SET OF INTERNAL NAME,
o (O) service_verification_info Service_Verification_Info,
o (O) service_verification_info_id INTEGER,
Also, three types of unprotection services are defined. These are:
1. receive unsolicited service (i.e., process unrequested
remotely-generated service),
2. receive solicited service (i.e., process remotely-generated
response to locally-generated request), and
3. receive service solicitation (i.e., process req. from rem. end)
As a target, unprotecting an encrypted message, or verifying the
originator's proof of origin is an example of service type 1. As an
originator, verifying a proof of delivery which you requested from a
target is an example of service type 2. Finally, as a target,
receiving a request from an originator for a proof of delivery is an
example of service type 3.
The first four parameters in the Unprot_Service parameter bundle
pertain to all service types; parameters 5-6 are used if and only if
service type 2 is required; parameters 7-8 are used only if service
type 3 is required.
o Unprot_Service PARAMETER BUNDLE
o (O) unprot_service_type INTEGER,
o (O) service_id OBJECT IDENTIFIER,
o (O) quality Quality,
-- actual Quality specified (never NULL)
o (O) general_service_data General_Service_Data,
o (O) service_verification_info_id INTEGER,
o (I) service_verification_info Service_Verification_Info,
o (O) service_to SET OF INTERNAL NAME,
o (O) service_creation_info Service_Creation_Info,
2.3.4.2. IDUP_Start_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o Mech_Specific_Info PARAMETER BUNDLE,
-- NULL selects the mechanism-defined default values
o Idu_Information PARAMETER BUNDLE,
o Special_Conditions PARAMETER BUNDLE,
o encapsulation_request BOOLEAN,
o single_idu_buffer OCTET STRING,
-- non-zero length for this buffer means that Protect/End_Protect
-- won't be called (i.e., entire IDU is contained in this buffer)
o idu_size INTEGER,
-- size (in bytes) of the IDU to be protected;
-- may be "-1" signifying "UNKNOWN" (note that some mechanisms
-- may not support encapsulation in such a case)
o Target_Info PARAMETER BUNDLE,
o Services_to_Perform SET OF Prot_Service,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o midu_buffer OCTET STRING,
-- zero length if encapsulation_request is TRUE;
-- may be zero length otherwise (depends on underlying mechanism)
o pidu_buffer OCTET STRING,
-- zero length if encapsulation_request is FALSE;
-- may be zero length otherwise (depends on underlying mechanism)
Return major_status codes:
o GSS_S_COMPLETE
-- the protection process can begin (or has completed, if
-- single_idu_buffer has non-zero length).
o IDUP_S_MORE_OUTBUFFER_NEEDED
o GSS_S_CREDENTIALS_EXPIRED
o IDUP_S_NO_ENV
o IDUP_S_ENCAPSULATION_UNAVAIL
o IDUP_S_SERVICE_UNAVAIL
o IDUP_S_REQ_TIME_SERVICE_UNAVAIL
o IDUP_S_UNKNOWN_OPER_ID
o GSS_S_BAD_QOP
o IDUP_S_BAD_TARG_INFO
o GSS_S_FAILURE
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of protecting the
IDU buffers. The caller requests specific protection services by
supplying the appropriate Prot_Service parameter bundles in
Services_to_Perform. Each service is able to return a minor status
code to the calling application, if necessary.
The calling application, knowing the size of the IDU it wishes to
protect and the buffer size which it has available to it, can choose
to input the entire IDU in a single buffer and omit the subsequent
IDUP_Protect() and IDUP_End_Protect() calls. Furthermore, the
application can request that the resulting M-IDU be encapsulated in
the token -- so that the token contains the entire P-IDU -- rather
than having it be returned separately in midu_buffer. Encapsulation,
however, may not be supported by all underlying mechanisms or
implementations; if this is the case, the
IDUP_S_ENCAPSULATION_UNAVAIL major status code will be returned and
M-IDU will be returned in midu_buffer.
For those mechanisms which allow or require multiple stages of
processing, each producing a different aspect of protection for the
IDU, the operation identifier prot_oper_id is used to specify which
stage is currently being requested by the application. An example
where this would be useful is a mechanism which implements the signed
Message Security Protocol [MSP]. As another example, a mechanism may
choose to do a digital signature in two stages: one for the hashing
of the message and another for the signature on the hash. The
calling application would therefore use the protection set of calls
on the IDU in stage 1 and then use the protection set of calls on the
token (from stage 1) in stage 2.
Note that prot_oper_id is simply an integer (1, 2, 3, ..., n, where
"n" is the number of stages as defined by the mechanism (typically 1
or 2)). The calling application uses this parameter to indicate to
the underlying mechanism whether it wishes to do stage 1 of
protection / unprotection processing, or stage 2, and so on. Portable
applications may pass "0" to let the mechanism choose the stage (note
that mechanism implementers may still iterate when prot_oper_id = 0
(e.g., use output as next input, et cetera).
If one or more of the targets in targ_names cannot be used as a valid
recipient of the P-IDU, these names will be returned in
bad_targ_names (with associated status codes in bad_targ_status). As
long as at least one of the targets can be used, this does not cause
this call to fail; it is the caller's choice to discontinue IDU
protection if the target set which can be used is unsuitable for the
caller's purposes. Note that each Prot_Service parameter bundle can
also input a list of targ_names; this is used if a separate list is
to be used for that service only (the general list of targets is to
be used for all services unless overridden in this way).
2.3.4.3. IDUP_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o input_buffer OCTET STRING,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_buffer OCTET STRING
-- may be zero length if encapsulation_request was set to TRUE in
-- IDUP_Start_Protect() (depends on underlying mechanism)
Return major_status codes:
o GSS_S_COMPLETE
o IDUP_S_NO_ENV
o GSS_S_FAILURE
Using the security environment referenced by env_handle, continue the
protection processing on the data in input_buffer and, if the
underlying mechanism defines this, put any resulting P-IDU/M-IDU data
in output_buffer. The application calls this routine over and over
again with new buffers of data until it has protected all the data
buffers of the IDU. It then calls IDUP_End_Protect() to complete the
protection processing.
2.3.4.4. IDUP_End_Protect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o Services_to_Perform SET OF Prot_Service,
o final_midu_buffer OCTET STRING,
-- zero length if encapsulation_request was set to TRUE in
-- IDUP_Start_Protect(), in which case pidu is used
o final_pidu_buffer OCTET STRING,
-- zero length if encapsulation_request was set to FALSE in
-- IDUP_Start_Protect(), in which case token and midu are used
Return major_status codes:
o GSS_S_COMPLETE
-- protection has successfully completed and the resulting P-IDU
-- is ready for transfer. If defined by the underlying mechanism,
-- final_midu_buffer will contain any residual M-IDU data.
o IDUP_S_MORE_OUTBUFFER_NEEDED
o IDUP_S_NO_ENV
o GSS_S_FAILURE
Using the security environment referenced by env_handle, complete the
protection processing on the data and place the computed output in
final_pidu_buffer (or final_midu_buffer and the unencapsulated_token
parameter for each Prot_Service). If a service was requested from
one or more targets in Start_Protect() - and if this is supported by
the underlying mechanism - Service_Verification_Info will hold
whatever data is necessary for the mechanism to verify a service
returned by a target (unprotector) of the P-IDU. Successful
application of IDUP_End_Protect() does not guarantee that the
corresponding unprotection set of calls can necessarily be performed
successfully when the P-IDU arrives at the target (for example, it
may be damaged in transit).
2.3.4.5. IDUP_Start_Unprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o Mech_Specific_Info PARAMETER BUNDLE,
-- NULL selects the mechanism-defined default values
o single_pidu_buffer OCTET STRING,
-- non-zero length for this buffer means that IDUP_Unprotect() and
-- IDUP_End_Unprotect() will not be called (i.e., the entire P-IDU
-- (if encapsulation is used) or M-IDU (if encap. is not used)
-- is contained in this buffer)
o partial_pidu_buffer OCTET STRING,
-- may be an arbitrary-sized piece of the full pidu (if the
-- application's buffer isn't large enough to hold entire pidu).
-- Used if pidu_buffer will be input a buffer at a time (except
-- that the final buffer must be passed in final_pidu_buffer
-- rather than partial_pidu_buffer). Only one of
-- single_pidu_buffer and partial(final)_pidu_buffer can have
-- nonzero length.
o final_pidu_buffer OCTET STRING,
o Special_Conditions PARAMETER BUNDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o Services_to_Receive SET OF Unprot_Service,
o Prot_Information PARAMETER BUNDLE,
o single_idu_buffer OCTET STRING,
-- if this buffer has non-zero length, then service processing has
-- been completed on the data in single_pidu_buffer
o initial_idu_buffer OCTET STRING,
-- holds any data from partial(final)_pidu_buffer which has been
-- unprotected; remaining data will be returned by Unprotect and
-- End_Unprotect as they are called with successive buffers of
-- pidu
o Service_Verification_Info PARAMETER BUNDLE,
-- used only if target is on "service_to" list in Unprot_Service
o service_verification_info_id INTEGER,
-- used only if target is on "service_to" list in Unprot_Service
Return major_status codes:
o GSS_S_COMPLETE
-- unprotection processing can begin (or has completed, if
-- single_idu_buffer has non-zero length).
o IDUP_S_INCOMPLETE
-- used only if single_idu_buffer has non-zero length.
o IDUP_S_MORE_OUTBUFFER_NEEDED
o IDUP_S_MORE_PIDU_NEEDED
o GSS_S_DEFECTIVE_TOKEN
o IDUP_S_INAPPROPRIATE_CRED
o IDUP_S_INCONSISTENT_PARAMS
o IDUP_S_DEFECTIVE_VERIF
o IDUP_S_NO_MATCH
o IDUP_S_SERVICE_UNAVAIL
o IDUP_S_REQ_TIME_SERVICE_UNAVAIL
o IDUP_S_SERV_VERIF_INFO_NEEDED
o GSS_S_CREDENTIALS_EXPIRED
o IDUP_S_NO_ENV
o IDUP_S_UNKNOWN_OPER_ID
o GSS_S_BAD_QOP
-- the qop_algs value specified in P-IDU for at least one of the
-- services is unavailable in the local mechanism, so processing
-- cannot continue.
o GSS_S_BAD_MIC
o IDUP_S_BAD_DOA_KEY
o IDUP_S_BAD_KE_KEY
o IDUP_S_BAD_ENC_IDU
o GSS_S_FAILURE
Using the security environment referenced by env_handle, initialize
the data structures required to begin the process of unprotecting a
P-IDU. The caller will be alerted as to which services were applied
to the P-IDU in the returned Services_to_Receive set of parameters.
If encapsulation was not used by the originator, it is the receiving
application's responsibility to separate the received P-IDU into a
M-IDU and one or more unencapsulated_token buffers (the latter being
input in separate Unprot_Service bundles in the Services_to_Receive
parameter). These unencapsulated_token buffers should be input
before the M-IDU (i.e., in IDUP_Start_Unprotect) or after the M-IDU
(i.e., in IDUP_End_Unprotect) as appropriate; this order may be
dictated, for example, by their placement in the in-coming message.
If unprotection will be applied more than once to a given P-IDU, it
is the responsibility of the calling application to remember if a
service solicitation has been responded to previously (i.e., if the
requested service has already been generated / sent for that P-IDU)
and thus ignore subsequent solicitations on unprotect.
The time flags indicate whether to consult trusted, untrusted, or no
time (if both flags are FALSE) during the unprotection operation. If
the current time is not to be checked, then unprotection may be
successful even if the protector's key has expired since the P-IDU
was generated (that is, if the Validity period -- as specified in the
Quality parameter bundle -- has expired).
If the underlying mechanism supports it and if this information is
contained in the P-IDU, information regarding the originator (that
is, the entity which used the protection set of calls to generate
this P-IDU) is returned in the Prot_Information parameter bundle.
2.3.4.6. IDUP_Unprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o input_buffer OCTET STRING
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o output_buffer OCTET STRING
Return major_status codes:
o GSS_S_COMPLETE
o IDUP_S_NO_ENV
o GSS_S_FAILURE
Using the security environment referenced by env_handle, continue the
unprotection processing on the data in input_buffer, putting any
resulting IDU data in output_buffer (if required).
2.3.4.7. IDUP_End_Unprotect call
Inputs:
o env_handle ENVIRONMENT HANDLE,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o Prot_Information PARAMETER BUNDLE,
o Services_to_Receive SET OF Unprot_Service,
o final_idu_buffer OCTET STRING,
o Service_Verification_Info PARAMETER BUNDLE,
-- used only if target is on "service_to" list in Unprot_Service
o service_verification_info_id INTEGER,
-- used only if target is on "service_to" list in Unprot_Service
Return major_status codes:
o GSS_S_COMPLETE
-- residual IDU data will be returned in final_idu_buffer.
o IDUP_S_INCOMPLETE
o IDUP_S_MORE_OUTBUFFER_NEEDED
o GSS_S_BAD_MIC
o IDUP_S_BAD_DOA_KEY
o IDUP_S_BAD_KE_KEY
o IDUP_S_BAD_ENC_IDU
o IDUP_S_NO_ENV
o GSS_S_FAILURE
Using the security environment referenced by env_handle, complete the
unprotection processing on the data and return the appropriate status
code. If there is any residual IDU data it will be returned in
final_idu_buffer.
If the IDUP_S_INCOMPLETE major status value is returned, all output
parameters are conditionally valid; the unprotection set of functions
will have to be called again (perhaps with a complete P-IDU, as
produced by IDUP_Form_Complete_PIDU) in order to get valid values for
all parameters. "Conditional validity" may arise, for example, if
all relevant certificates verify correctly, but it is not yet past
the time up to which the current policy allows the authorities
involved to repudiate their keys.
If the underlying mechanism supports it and if this information is
contained in the token, information regarding the originator (that
is, the entity which used the protection set of calls to generate
this token) is returned in the Prot_Information parameter bundle.
This information may or may not be omitted if it was returned by the
IDUP_Start_Unprotect() call.
Note that, unlike GSS-API, IDUP-GSS-API does not incorporate the
concept of error tokens transferred between sender and recipient
since the protection and unprotection of an IDU may be separated by
an indefinite amount of time and may or may not be performed by the
same entity.
2.4. Special-Purpose Calls
2.4.1. Relationship to GSS-API
The special-purpose call described in this section has no analog in
GSS-API [RFC-2078]. This call is used to complete a P-IDU (that is,
to generate a P-IDU which can be unprotected successfully with no
additional data at any time during its validity period). This call
may not be supported by all underlying IDUP mechanisms or
implementations.
2.4.2. IDUP_Form_Complete_PIDU call
Inputs:
o env_handle ENVIRONMENT HANDLE,
o single_pidu_buffer OCTET STRING,
o partial_pidu_buffer OCTET STRING,
-- an arbitrary-sized piece of the full pidu token. Used if pidu
-- will be input a buffer at a time (except that the final buffer
-- must be passed in final_pidu_buffer rather than
-- partial_pidu_buffer). Only one of single_pidu_buffer and
-- partial(final)_pidu_buffer can have nonzero length.
o final_pidu_buffer OCTET STRING,
Outputs:
o major_status INTEGER,
o minor_status INTEGER,
o pidu_token_out OCTET STRING -- the augmented PIDU; may be complete
o call_again_before INTEGER,
o call_again_after INTEGER,
o trusted_time_stamping_time INTEGER -- for information only
Return major_status codes:
o GSS_S_COMPLETE
o IDUP_S_MORE_OUTBUFFER_NEEDED
o IDUP_S_INCOMPLETE
-- generation of the P-IDU is not yet complete. The application
-- should call this function again before the time given in
-- call_again_before (if not NULL), or after the time given in
-- call_again_after (if not NULL), or both (if neither are NULL).
o IDUP_S_INCONSISTENT_PARAMS
o IDUP_S_SERVICE_UNAVAIL
o GSS_S_DEFECTIVE_TOKEN
o GSS_S_FAILURE
Form_Complete_PIDU is used primarily by the evidence services; in
particular, when the evidence token itself does not contain all the
data required for its verification and it is anticipated that some of
the data not stored in the token may become unavailable during the
interval between generation of the evidence token and verification
unless it is stored in the token. The Form_Complete_PIDU operation
gathers the missing information and includes it in the token so that
verification can be guaranteed to be possible at any future time.