From 4effcdad0499d4c8279b25c2b996b0802bc7fe23 Mon Sep 17 00:00:00 2001 From: Simon Josefsson Date: Wed, 30 Apr 2003 22:40:21 +0000 Subject: [PATCH] Add. --- doc/specifications/rfc1961.txt | 507 ++++ doc/specifications/rfc2025.txt | 2523 +++++++++++++++++++ doc/specifications/rfc2478.txt | 1011 ++++++++ doc/specifications/rfc2479.txt | 3923 +++++++++++++++++++++++++++++ doc/specifications/rfc2853.txt | 5379 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 13343 insertions(+) create mode 100644 doc/specifications/rfc1961.txt create mode 100644 doc/specifications/rfc2025.txt create mode 100644 doc/specifications/rfc2478.txt create mode 100644 doc/specifications/rfc2479.txt create mode 100644 doc/specifications/rfc2853.txt diff --git a/doc/specifications/rfc1961.txt b/doc/specifications/rfc1961.txt new file mode 100644 index 00000000..5d354cf7 --- /dev/null +++ b/doc/specifications/rfc1961.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group P. McMahon +Request for Comments: 1961 ICL +Category: Standards Track June 1996 + + + GSS-API Authentication Method for SOCKS Version 5 + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Table of Contents + + 1. Purpose ............................................ 1 + 2. Introduction ....................................... 1 + 3. GSS-API Security Context Establishment ............. 2 + 4. GSS-API Protection-level Options ................... 5 + 5. GSS-API Per-message Protection ..................... 7 + 6. GSS-API Security Context Termination ............... 8 + 7. References ......................................... 8 + 8. Acknowledgments .................................... 8 + 9. Security Considerations ............................ 8 + 10. Author's Address .................................. 9 + +1. Purpose + + The protocol specification for SOCKS Version 5 specifies a + generalized framework for the use of arbitrary authentication + protocols in the initial SOCKS connection setup. This document + provides the specification for the SOCKS V5 GSS-API authentication + protocol, and defines a GSS-API-based encapsulation for provision of + integrity, authentication and optional confidentiality. + +2. Introduction + + GSS-API provides an abstract interface which provides security + services for use in distributed applications, but isolates callers + from specific security mechanisms and implementations. + + GSS-API peers achieve interoperability by establishing a common + security mechanism for security context establishment - either + through administrative action, or through negotiation. GSS-API is + specified in [RFC 1508], and [RFC 1509]. This specification is + intended for use with implementations of GSS-API, and the emerging + + + +McMahon Standards Track [Page 1] + +RFC 1961 GSS-API Authentication for SOCKS V5 June 1996 + + + GSS-API V2 specification. + + The approach for use of GSS-API in SOCKS V5 is to authenticate the + client and server by successfully establishing a GSS-API security + context - such that the GSS-API encapsulates any negotiation protocol + for mechanism selection, and the agreement of security service + options. + + The GSS-API enables the context initiator to know what security + services the target supports for the chosen mechanism. The required + level of protection is then agreed by negotiation. + + The GSS-API per-message protection calls are subsequently used to + encapsulate any further TCP and UDP traffic between client and + server. + +3. GSS-API Security Context Establishment + +3.1 Preparation + + Prior to use of GSS-API primitives, the client and server should be + locally authenticated, and have established default GSS-API + credentials. + + The client should call gss_import_name to obtain an internal + representation of the server name. For maximal portability the + default name_type GSS_C_NULL_OID should be used to specify the + default name space, and the input name_string should treated by the + client's code as an opaque name-space specific input. + + For example, when using Kerberos V5 naming, the imported name may be + of the form "SERVICE:socks@socks_server_hostname" where + "socks_server_hostname" is the fully qualified host name of the + server with all letters in lower case. Other mechanisms may, however, + have different name forms, so the client should not make assumptions + about the name syntax. + +3.2 Client Context Establishment + + The client should then call gss_init_sec_context, typically passing: + + GSS_C_NO_CREDENTIAL into cred_handle to specify the default + credential (for initiator usage), + + GSS_C_NULL_OID into mech_type to specify the default + mechanism, + + + + + +McMahon Standards Track [Page 2] + +RFC 1961 GSS-API Authentication for SOCKS V5 June 1996 + + + GSS_C_NO_CONTEXT into context_handle to specify a NULL + context (initially), and, + + the previously imported server name into target_name. + + The client must also specify its requirements for replay protection, + delegation, and sequence protection via the gss_init_sec_context + req_flags parameter. It is required by this specification that the + client always requests these service options (i.e. passes + GSS_C_MUTUAL_FLAG | GSS_C_REPLAY_FLAG | GSS_C_DELEG_FLAG | + GSS_C_SEQUENCE_FLAG into req_flags). + + However, GSS_C_SEQUENCE_FLAG should only be passed in for TCP-based + clients, not for UDP-based clients. + +3.3 Client Context Establishment Major Status codes + + The gss_init_sec_context returned status code can take two different + success values: + + - If gss_init_sec_context returns GSS_S_CONTINUE_NEEDED, then the + client should expect the server to issue a token in the + subsequent subnegotiation response. The client must pass the + token to another call to gss_init_sec_context, and repeat this + procedure until "continue" operations are complete. + + - If gss_init_sec_context returns GSS_S_COMPLETE, then the client + should respond to the server with any resulting output_token. + + If there is no output_token, the client should proceed to send + the protected request details, including any required message + protection subnegotiation as specified in sections 4 and 5 + below. + +3.4 Client initial token + + The client's GSS-API implementation then typically responds with the + resulting output_token which the client sends in a message to the + server. + + +------+------+------+.......................+ + + ver | mtyp | len | token | + +------+------+------+.......................+ + + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets | + +------+------+------+.......................+ + + + + + + +McMahon Standards Track [Page 3] + +RFC 1961 GSS-API Authentication for SOCKS V5 June 1996 + + + Where: + + - "ver" is the protocol version number, here 1 to represent the + first version of the SOCKS/GSS-API protocol + + - "mtyp" is the message type, here 1 to represent an + authentication message + + - "len" is the length of the "token" field in octets + + - "token" is the opaque authentication token emitted by GSS-API + +3.5 Client GSS-API Initialisation Failure + + If, however, the client's GSS-API implementation failed during + gss_init_sec_context, the client must close its connection to the + server. + +3.6 Server Context Establishment + + For the case where a client successfully sends a token emitted by + gss_init_sec_context() to the server, the server must pass the + client-supplied token to gss_accept_sec_context as input_token. + + When calling gss_accept_sec_context() for the first time, the + context_handle argument is initially set to GSS_C_NO_CONTEXT. + + For portability, verifier_cred_handle is set to GSS_C_NO_CREDENTIAL + to specify default credentials (for acceptor usage). + + If gss_accept_sec_context returns GSS_CONTINUE_NEEDED, the server + should return the generated output_token to the client, and + subsequently pass the resulting client supplied token to another call + to gss_accept_sec_context. + + If gss_accept_sec_context returns GSS_S_COMPLETE, then, if an + output_token is returned, the server should return it to the client. + + If no token is returned, a zero length token should be sent by the + server to signal to the client that it is ready to receive the + client's request. + + + + + + + + + + +McMahon Standards Track [Page 4] + +RFC 1961 GSS-API Authentication for SOCKS V5 June 1996 + + +3.7 Server Reply + + In all continue/confirmation cases, the server uses the same message + type as for the client -> server interaction. + + +------+------+------+.......................+ + + ver | mtyp | len | token | + +------+------+------+.......................+ + + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets | + +------+------+------+.......................+ + +3.8 Security Context Failure + + If the server refuses the client's connection for any reason (GSS-API + authentication failure or otherwise), it will return: + + +------+------+ + + ver | mtyp | + +------+------+ + + 0x01 | 0xff | + +------+------+ + + Where: + + - "ver" is the protocol version number, here 1 to represent the + first version of the SOCKS/GSS-API protocol + + - "mtyp" is the message type, here 0xff to represent an abort + message + +4. GSS-API Protection-level Options + +4.1 Message protection + + Establishment of a GSS-API security context enables comunicating + peers to determine which per-message protection services are + available to them through the gss_init_sec_context() and + gss_accept_sec_context() ret_flags GSS_C_INTEG_FLAG and + GSS_C_CONF_FLAG which respectively indicate message integrity and + confidentiality services. + + It is necessary to ensure that the message protection applied to the + traffic is appropriate to the sensitivity of the data, and the + severity of the threats. + + + + + + + +McMahon Standards Track [Page 5] + +RFC 1961 GSS-API Authentication for SOCKS V5 June 1996 + + +4.2 Message Protection Subnegotiation + + For TCP and UDP clients and servers, different levels of protection + are possible in the SOCKS V5 protocol, so an additional + subnegotiation stage is needed to agree the message protection level. + After successful completion of this subnegotiation, TCP and UDP + clients and servers use GSS-API encapsulation as defined in section + 5.1. + + After successful establishment of a GSS-API security context, the + client's GSS-API implementation sends its required security context + protection level to the server. The server then returns the security + context protection level which it agrees to - which may or may not + take the the client's request into account. + + The security context protection level sent by client and server must + be one of the following values: + + 1 required per-message integrity + 2 required per-message integrity and confidentiality + 3 selective per-message integrity or confidentiality based on + local client and server configurations + + It is anticipated that most implementations will agree on level 1 or + 2 due to the practical difficulties in applying selective controls to + messages passed through a socks library. + +4.3 Message Protection Subnegotiation Message Format + + The security context protection level is sent from client to server + and vice versa using the following protected message format: + + +------+------+------+.......................+ + + ver | mtyp | len | token | + +------+------+------+.......................+ + + 0x01 | 0x02 | 0x02 | up to 2^16 - 1 octets | + +------+------+------+.......................+ + + Where: + + - "ver" is the protocol version number, here 1 to represent the + first version of the SOCKS/GSS-API protocol + + - "mtyp" is the message type, here 2 to represent a protection + -level negotiation message + + - "len" is the length of the "token" field in octets + + + + +McMahon Standards Track [Page 6] + +RFC 1961 GSS-API Authentication for SOCKS V5 June 1996 + + + - "token" is the GSS-API encapsulated protection level + +4.4 Message Protection Subnegotiation Message Generation + + The token is produced by encapsulating an octet containing the + required protection level using gss_seal()/gss_wrap() with conf_req + set to FALSE. The token is verified using gss_unseal()/ + gss_unwrap(). + + If the server's choice of protection level is unacceptable to the + client, then the client must close its connection to the server + +5. GSS-API Per-message Protection + + For TCP and UDP clients and servers, the GSS-API functions for + encapsulation and de-encapsulation shall be used by implementations - + i.e. gss_seal()/gss_wrap(), and gss_unseal()/ gss_unwrap(). + + The default value of quality of protection shall be specified, and + the use of conf_req_flag shall be as determined by the previous + subnegotiation step. If protection level 1 is agreed then + conf_req_flag MUST always be FALSE; if protection level 2 is agreed + then conf_req_flag MUST always be TRUE; and if protection level 3 is + agreed then conf_req is determined on a per-message basis by client + and server using local configuration. + + All encapsulated messages are prefixed by the following framing: + + +------+------+------+.......................+ + + ver | mtyp | len | token | + +------+------+------+.......................+ + + 0x01 | 0x03 | 0x02 | up to 2^16 - 1 octets | + +------+------+------+.......................+ + + Where: + + - "ver" is the protocol version number, here 1 to represent the + first version of the SOCKS/GSS-API protocol + + - "mtyp" is the message type, here 3 to represent encapulated user + data + + - "len" is the length of the "token" field in octets + + - "token" is the user data encapsulated by GSS-API + + + + + + +McMahon Standards Track [Page 7] + +RFC 1961 GSS-API Authentication for SOCKS V5 June 1996 + + +6. GSS-API Security Context Termination + + The GSS-API context termination message (emitted by + gss_delete_sec_context) is not used by this protocol. + + When the connection is closed, each peer invokes + gss_delete_sec_context() passing GSS_C_NO_BUFFER into the + output_token argument. + +7. References + + [RFC 1508] Linn, J., "Generic Security Service API", + September 1993. + + [RFC 1509] Wray, J., "Generic Security Service API : C-bindings", + September 1993. + + [SOCKS V5] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., + and L. Jones, "SOCKS Protocol V5", RFC 1928, April + 1996. + +8. Acknowledgment + + This document builds from a previous memo produced by Marcus Leech + (BNR) - whose comments are gratefully acknowleged. It also reflects + input from the AFT WG, and comments arising from implementation + experience by Xavier Gosselin (IUT Lyons). + +9. Security Considerations + + The security services provided through the GSS-API are entirely + dependent on the effectiveness of the underlying security mechanisms, + and the correctness of the implementation of the underlying + algorithms and protocols. + + The user of a GSS-API service must ensure that the quality of + protection provided by the mechanism implementation is consistent + with their security policy. + + In addition, where negotiation is supported under the GSS-API, + constraints on acceptable mechanisms may be imposed to ensure + suitability for application to authenticated firewall traversal. + + + + + + + + + +McMahon Standards Track [Page 8] + +RFC 1961 GSS-API Authentication for SOCKS V5 June 1996 + + +10. Author's Address + + P. V. McMahon + ICL Enterprises + Kings House + 33 Kings Road + Reading, RG1 3PX + UK + + EMail: p.v.mcmahon@rea0803.wins.icl.co.uk + Phone: +44 1734 634882 + Fax: +44 1734 855106 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +McMahon Standards Track [Page 9] + diff --git a/doc/specifications/rfc2025.txt b/doc/specifications/rfc2025.txt new file mode 100644 index 00000000..f4c3c61c --- /dev/null +++ b/doc/specifications/rfc2025.txt @@ -0,0 +1,2523 @@ + + + + + + +Network Working Group C. Adams +Request for Comments: 2025 Bell-Northern Research +Category: Standards Track October 1996 + + + The Simple Public-Key GSS-API Mechanism (SPKM) + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + This specification defines protocols, procedures, and conventions to + be employed by peers implementing the Generic Security Service + Application Program Interface (as specified in RFCs 1508 and 1509) + when using the Simple Public-Key Mechanism. + +Background + + Although the Kerberos Version 5 GSS-API mechanism [KRB5] is becoming + well-established in many environments, it is important in some + applications to have a GSS-API mechanism which is based on a public- + key, rather than a symmetric-key, infrastructure. The mechanism + described in this document has been proposed to meet this need and to + provide the following features. + + 1) The SPKM allows both unilateral and mutual authentication + to be accomplished without the use of secure timestamps. This + enables environments which do not have access to secure time + to nevertheless have access to secure authentication. + + 2) The SPKM uses Algorithm Identifiers to specify various + algorithms to be used by the communicating peers. This allows + maximum flexibility for a variety of environments, for future + enhancements, and for alternative algorithms. + + 3) The SPKM allows the option of a true, asymmetric algorithm- + based, digital signature in the gss_sign() and gss_seal() + operations (now called gss_getMIC() and gss_wrap() in + [GSSv2]), rather than an integrity checksum based on a MAC + computed with a symmetric algorithm (e.g., DES). For some + environments, the availability of true digital signatures + supporting non-repudiation is a necessity. + + + +Adams Standards Track [Page 1] + +RFC 2025 SPKM October 1996 + + + 4) SPKM data formats and procedures are designed to be as similar + to those of the Kerberos mechanism as is practical. This is + done for ease of implementation in those environments where + Kerberos has already been implemented. + + For the above reasons, it is felt that the SPKM will offer + flexibility and functionality, without undue complexity or overhead. + +Key Management + + The key management employed in SPKM is intended to be as compatible + as possible with both X.509 [X.509] and PEM [RFC-1422], since these + represent large communities of interest and show relative maturity in + standards. + +Acknowledgments + + Much of the material in this document is based on the Kerberos + Version 5 GSS-API mechanism [KRB5], and is intended to be as + compatible with it as possible. This document also owes a great debt + to Warwick Ford and Paul Van Oorschot of Bell-Northern Research for + many fruitful discussions, to Kelvin Desplanque for implementation- + related clarifications, to John Linn of OpenVision Technologies for + helpful comments, and to Bancroft Scott of OSS for ASN.1 assistance. + +1. Overview + + The goal of the Generic Security Service Application Program + Interface (GSS-API) is stated in the abstract of [RFC-1508] as + follows: + + "This Generic Security Service Application Program Interface (GSS- + API) definition provides security services to callers in a generic + fashion, supportable with a range of underlying mechanisms and + technologies and hence allowing source-level portability of + applications to different environments. This specification defines + GSS-API services and primitives at a level independent of + underlying mechanism and programming language environment, and is + to be complemented by other, related specifications: + + - documents defining specific parameter bindings for particular + language environments; + + - documents defining token formats, protocols, and procedures to + be implemented in order to realize GSS-API services atop + particular security mechanisms." + + + + + +Adams Standards Track [Page 2] + +RFC 2025 SPKM October 1996 + + + The SPKM is an instance of the latter type of document and is + therefore termed a "GSS-API Mechanism". This mechanism provides + authentication, key establishment, data integrity, and data + confidentiality in an on-line distributed application environment + using a public-key infrastructure. Because it conforms to the + interface defined by [RFC-1508], SPKM can be used as a drop-in + replacement by any application which makes use of security services + through GSS-API calls (for example, any application which already + uses the Kerberos GSS-API for security). The use of a public-key + infrastructure allows digital signatures supporting non-repudiation + to be employed for message exchanges, and provides other benefits + such as scalability to large user populations. + + The tokens defined in SPKM are intended to be used by application + programs according to the GSS API "operational paradigm" (see [RFC- + 1508] for further details): + + The operational paradigm in which GSS-API operates is as follows. + A typical GSS-API caller is itself a communications protocol [or is + an application program which uses a communications protocol], + calling on GSS-API in order to protect its communications with + authentication, integrity, and/or confidentiality security + services. A GSS-API caller accepts tokens provided to it by its + local GSS-API implementation [i.e., its GSS-API mechanism] and + transfers the tokens to a peer on a remote system; that peer passes + the received tokens to its local GSS-API implementation for + processing. + + This document defines two separate GSS-API mechanisms, SPKM-1 and + SPKM-2, whose primary difference is that SPKM-2 requires the + presence of secure timestamps for the purpose of replay detection + during context establishment and SPKM-1 does not. This allows + greater flexibility for applications since secure timestamps cannot + always be guaranteed to be available in a given environment. + + + + + + + + + + + + + + + + + +Adams Standards Track [Page 3] + +RFC 2025 SPKM October 1996 + + +2. Algorithms + + A number of algorithm types are employed in SPKM. Each type, along + with its purpose and a set of specific examples, is described in this + section. In order to ensure at least a minimum level of + interoperability among various implementations of SPKM, one of the + integrity algorithms is specified as MANDATORY; all remaining + examples (and any other algorithms) may optionally be supported by a + given SPKM implementation (note that a GSS-conformant mechanism need + not support confidentiality). Making a confidentiality algorithm + mandatory may preclude exportability of the mechanism implementation; + this document therefore specifies certain algorithms as RECOMMENDED + (that is, interoperability will be enhanced if these algorithms are + included in all SPKM implementations for which exportability is not a + concern). + +2.1 Integrity Algorithm (I-ALG): + + Purpose: + + This algorithm is used to ensure that a message has not been + altered in any way after being constructed by the legitimate + sender. Depending on the algorithm used, the application of + this algorithm may also provide authenticity and support non- + repudiation for the message. + + Examples: + + md5WithRSAEncryption OBJECT IDENTIFIER ::= { + iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) + pkcs-1(1) 4 -- imported from [PKCS1] + } + + This algorithm (MANDATORY) provides data integrity and + authenticity and supports non-repudiation by computing an + RSA signature on the MD5 hash of that data. This is + essentially equivalent to md5WithRSA {1 3 14 3 2 3}, + which is defined by OIW (the Open Systems Environment + Implementors' Workshop). + + Note that since this is the only integrity/authenticity + algorithm specified to be mandatory at this time, for + interoperability reasons it is also stipulated that + md5WithRSA be the algorithm used to sign all context + establishment tokens which are signed rather than MACed -- + see Section 3.1.1 for details. In future versions of this + document, alternate or additional algorithms may be + specified to be mandatory and so this stipulation on the + + + +Adams Standards Track [Page 4] + +RFC 2025 SPKM October 1996 + + + context establishment tokens may be removed. + + DES-MAC OBJECT IDENTIFIER ::= { + iso(1) identified-organization(3) oiw(14) secsig(3) + algorithm(2) 10 -- carries length in bits of the MAC as + } -- an INTEGER parameter, constrained to + -- multiples of eight from 16 to 64 + + This algorithm (RECOMMENDED) provides integrity by computing + a DES MAC (as specified by [FIPS-113]) on that data. + + + md5-DES-CBC OBJECT IDENTIFIER ::= { + iso(1) identified-organization(3) dod(6) internet(1) + security(5) integrity(3) md5-DES-CBC(1) + } + + This algorithm provides data integrity by encrypting, using + DES CBC, the "confounded" MD5 hash of that data (see Section + 3.2.2.1 for the definition and purpose of confounding). + This will typically be faster in practice than computing a + DES MAC unless the input data is extremely short (e.g., a + few bytes). Note that without the confounder the strength + of this integrity mechanism is (at most) equal to the + strength of DES under a known-plaintext attack. + + + sum64-DES-CBC OBJECT IDENTIFIER ::= { + iso(1) identified-organization(3) dod(6) internet(1) + security(5) integrity(3) sum64-DES-CBC(2) + } + + This algorithm provides data integrity by encrypting, using + DES CBC, the concatenation of the confounded data and the + sum of all the input data blocks (the sum computed using + addition modulo 2**64 - 1). Thus, in this algorithm, + encryption is a requirement for the integrity to be secure. + + For comments regarding the security of this integrity + algorithm, see [Juen84, Davi89]. + + + + + + + + + + + +Adams Standards Track [Page 5] + +RFC 2025 SPKM October 1996 + + +2.2 Confidentiality Algorithm (C-ALG): + + Purpose: + + This symmetric algorithm is used to generate the encrypted + data for gss_seal() / gss_wrap(). + + Example: + + DES-CBC OBJECT IDENTIFIER ::= { + iso(1) identified-organization(3) oiw(14) secsig(3) + algorithm(2) 7 -- carries IV (OCTET STRING) as a parameter; + } -- this (optional) parameter is unused in + -- SPKM due to the use of confounding + + This algorithm is RECOMMENDED. + +2.3 Key Establishment Algorithm (K-ALG): + + Purpose: + + This algorithm is used to establish a symmetric key for use + by both the initiator and the target over the established + context. The keys used for C-ALG and any keyed I-ALGs (for + example, DES-MAC) are derived from this context key. As will + be seen in Section 3.1, key establishment is done within the + X.509 authentication exchange and so the resulting shared + symmetric key is authenticated. + + Examples: + + RSAEncryption OBJECT IDENTIFIER ::= { + iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) + pkcs-1(1) 1 -- imported from [PKCS1] and [RFC-1423] + } + + In this algorithm (MANDATORY), the context key is generated + by the initiator, encrypted with the RSA public key of the + target, and sent to the target. The target need not respond + to the initiator for the key to be established. + + id-rsa-key-transport OBJECT IDENTIFIER ::= { + iso(1) identified-organization(3) oiw(14) secsig(3) + algorithm(2) 22 -- imported from [X9.44] + } + + Similar to RSAEncryption, but source authenticating info. + is also encrypted with the target's RSA public key. + + + +Adams Standards Track [Page 6] + +RFC 2025 SPKM October 1996 + + + dhKeyAgreement OBJECT IDENTIFIER ::= { + iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) + pkcs-3(3) 1 + } + + In this algorithm, the context key is generated jointly by + the initiator and the target using the Diffie-Hellman key + establishment algorithm. The target must therefore respond + to the initiator for the key to be established (so this + K-ALG cannot be used with unilateral authentication in + SPKM-2 (see Section 3.1)). + +2.4 One-Way Function (O-ALG) for Subkey Derivation Algorithm: + + Purpose: + + Having established a context key using the negotiated K-ALG, + both initiator and target must be able to derive a set of + subkeys for the various C-ALGs and keyed I-ALGs supported over + the context. Let the (ordered) list of agreed C-ALGs be + numbered consecutively, so that the first algorithm (the + "default") is numbered "0", the next is numbered "1", and so + on. Let the numbering for the (ordered) list of agreed I-ALGs + be identical. Finally, let the context key be a binary string + of arbitrary length "M", subject to the following constraint: + L <= M <= U (where the lower limit "L" is the bit length of + the longest key needed by any agreed C-ALG or keyed I-ALG, and + the upper limit "U" is the largest bit size which will fit + within the K-ALG parameters). + + For example, if DES and two-key-triple-DES are the negotiated + confidentiality algorithms and DES-MAC is the negotiated keyed + integrity algorithm (note that digital signatures do not use a + context key), then the context key must be at least 112 bits + long. If 512-bit RSAEncryption is the K-ALG in use then the + originator can randomly generate a context key of any greater + length up to 424 bits (the longest allowable RSA input + specified in [PKCS-1]) -- the target can determine the length + which was chosen by removing the padding bytes during the RSA + decryption operation. On the other hand, if dhKeyAgreement is + the K-ALG in use then the context key is the result of the + Diffie-Hellman computation (with the exception of the high- + order byte, which is discarded for security reasons), so that + its length is that of the Diffie-Hellman modulus, p, minus 8 + bits. + + + + + + +Adams Standards Track [Page 7] + +RFC 2025 SPKM October 1996 + + + The derivation algorithm for a k-bit subkey is specified as + follows: + + rightmost_k_bits (OWF(context_key || x || n || s || context_key)) + + where + + - "x" is the ASCII character "C" (0x43) if the subkey is + for a confidentiality algorithm or the ASCII character "I" + (0x49) if the subkey is for a keyed integrity algorithm; + - "n" is the number of the algorithm in the appropriate agreed + list for the context (the ASCII character "0" (0x30), "1" + (0x31), and so on); + - "s" is the "stage" of processing -- always the ASCII + character "0" (0x30), unless "k" is greater than the output + size of OWF, in which case the OWF is computed repeatedly + with increasing ASCII values of "stage" (each OWF output + being concatenated to the end of previous OWF outputs), + until "k" bits have been generated; + - "||" is the concatenation operation; and + - "OWF" is any appropriate One-Way Function. + + Examples: + + MD5 OBJECT IDENTIFIER ::= { + iso(1) member-body(2) US(840) rsadsi(113549) + digestAlgorithm(2) 5 + } + + This algorithm is MANDATORY. + + SHA OBJECT IDENTIFIER ::= { + iso(1) identified-organization(3) oiw(14) secsig(3) + algorithm(2) 18 + } + + It is recognized that existing hash functions may not satisfy + all required properties of OWFs. This is the reason for + allowing negotiation of the O-ALG OWF during the context + establishment process (see Section 2.5), since in this way + future improvements in OWF design can easily be accommodated. + For example, in some environments a preferred OWF technique + might be an encryption algorithm which encrypts the input + specified above using the context_key as the encryption key. + + + + + + + +Adams Standards Track [Page 8] + +RFC 2025 SPKM October 1996 + + +2.5 Negotiation: + + During context establishment in SPKM, the initiator offers a set of + possible confidentiality algorithms and a set of possible integrity + algorithms to the target (note that the term "integrity algorithms" + includes digital signature algorithms). The confidentiality + algorithms selected by the target become ones that may be used for + C-ALG over the established context, and the integrity algorithms + selected by the target become ones that may be used for I-ALG over + the established context (the target "selects" algorithms by + returning, in the same relative order, the subset of each offered + list that it supports). Note that any C-ALG and I-ALG may be used + for any message over the context and that the first confidentiality + algorithm and the first integrity algorithm in the agreed sets become + the default algorithms for that context. + + The agreed confidentiality and integrity algorithms for a specific + context define the valid values of the Quality of Protection (QOP) + parameter used in the gss_getMIC() and gss_wrap() calls -- see + Section 5.2 for further details. If no response is expected from the + target (unilateral authentication in SPKM-2) then the algorithms + offered by the initiator are the ones that may be used over the + context (if this is unacceptable to the target then a delete token + must be sent to the initiator so that the context is never + established). + + Furthermore, in the first context establishment token the initiator + offers a set of possible K-ALGs, along with the key (or key half) + corresponding to the first algorithm in the set (its preferred + algorithm). If this K-ALG is unacceptable to the target then the + target must choose one of the other K-ALGs in the set and send this + choice along with the key (or key half) corresponding to this choice + in its response (otherwise a delete token must be sent so that the + context is never established). If necessary (that is, if the target + chooses a 2-pass K-ALG such as dhKeyAgreement), the initiator will + send its key half in a response to the target. + + Finally, in the first context establishment token the initiator + offers a set of possible O-ALGs (only a single O-ALG if no response + is expected). The (single) O-ALG chosen by the target becomes the + subkey derivation algorithm OWF to be used over the context. + + In future versions of SPKM, other algorithms may be specified for any + or all of I-ALG, C-ALG, K-ALG, and O-ALG. + + + + + + + +Adams Standards Track [Page 9] + +RFC 2025 SPKM October 1996 + + +3. Token Formats + + This section discusses protocol-visible characteristics of the SPKM; + it defines elements of protocol for interoperability and is + independent of language bindings per [RFC-1509]. + + The SPKM GSS-API mechanism will be identified by an Object Identifier + representing "SPKM-1" or "SPKM-2", having the value {spkm spkm-1(1)} + or {spkm spkm-2(2)}, where spkm has the value {iso(1) identified- + organization(3) dod(6) internet(1) security(5) mechanisms(5) + spkm(1)}. SPKM-1 uses random numbers for replay detection during + context establishment and SPKM-2 uses timestamps (note that for both + mechanisms, sequence numbers are used to provide replay and out-of- + sequence detection during the context, if this has been requested by + the application). + + Tokens transferred between GSS-API peers (for security context + management and per-message protection purposes) are defined. + +3.1. Context Establishment Tokens + + Three classes of tokens are defined in this section: "Initiator" + tokens, emitted by calls to gss_init_sec_context() and consumed by + calls to gss_accept_sec_context(); "Target" tokens, emitted by calls + to gss_accept_sec_context() and consumed by calls to + gss_init_sec_context(); and "Error" tokens, potentially emitted by + calls to gss_init_sec_context() or gss_accept_sec_context(), and + potentially consumed by calls to gss_init_sec_context() or + gss_accept_sec_context(). + + Per RFC-1508, Appendix B, the initial context establishment token + will be enclosed within framing as follows: + + InitialContextToken ::= [APPLICATION 0] IMPLICIT SEQUENCE { + thisMech MechType, + -- MechType is OBJECT IDENTIFIER + -- representing "SPKM-1" or "SPKM-2" + innerContextToken ANY DEFINED BY thisMech + } -- contents mechanism-specific + + + + + + + + + + + + +Adams Standards Track [Page 10] + +RFC 2025 SPKM October 1996 + + + When thisMech is SPKM-1 or SPKM-2, innerContextToken is defined as + follows: + + SPKMInnerContextToken ::= CHOICE { + req [0] SPKM-REQ, + rep-ti [1] SPKM-REP-TI, + rep-it [2] SPKM-REP-IT, + error [3] SPKM-ERROR, + mic [4] SPKM-MIC, + wrap [5] SPKM-WRAP, + del [6] SPKM-DEL + } + + The above GSS-API framing shall be applied to all tokens emitted by + the SPKM GSS-API mechanism, including SPKM-REP-TI (the response from + the Target to the Initiator), SPKM-REP-IT (the response from the + Initiator to the Target), SPKM-ERROR, context-deletion, and per- + message tokens, not just to the initial token in a context + establishment exchange. While not required by RFC-1508, this enables + implementations to perform enhanced error-checking. The tag values + provided in SPKMInnerContextToken ("[0]" through "[6]") specify a + token-id for each token; similar information is contained in each + token's tok-id field. While seemingly redundant, the tag value and + tok-id actually perform different tasks: the tag ensures that + InitialContextToken can be properly decoded; tok-id ensures, among + other things, that data associated with the per-message tokens is + cryptographically linked to the intended token type. Every + innerContextToken also includes a context-id field; see Section 6 for + a discussion of both token-id and context-id information and their + use in an SPKM support function). + + The innerContextToken field of context establishment tokens for the + SPKM GSS-API mechanism will contain one of the following messages: + SPKM-REQ; SPKM-REP-TI; SPKM-REP-IT; and SPKM-ERROR. Furthermore, all + innerContextTokens are encoded using ASN.1 BER (constrained, in the + interests of parsing simplicity, to the DER subset defined in + [X.509], clause 8.7). + + The SPKM context establishment tokens are defined according to + [X.509] Section 10 and are compatible with [9798]. SPKM-1 (random + numbers) uses Section 10.3, "Two-way Authentication", when performing + unilateral authentication of the target to the initiator and uses + Section 10.4, "Three-way Authentication", when mutual authentication + is requested by the initiator. SPKM-2 (timestamps) uses Section + 10.2, "One-way Authentication", when performing unilateral + authentication of the initiator to the target and uses Section 10.3, + "Two-way Authentication", when mutual authentication is requested by + the initiator. + + + +Adams Standards Track [Page 11] + +RFC 2025 SPKM October 1996 + + + The implication of the previous paragraph is that for SPKM-2 + unilateral authentication no negotiation of K-ALG can be done (the + target either accepts the K-ALG and context key given by the + initiator or disallows the context). For SPKM-2 mutual or SPKM-1 + unilateral authentication some negotiation is possible, but the + target can only choose among the one-pass K-ALGs offered by the + initiator (or disallow the context). Alternatively, the initiator + can request that the target generate and transmit the context key. + For SPKM-1 mutual authentication the target can choose any one- or + two-pass K-ALG offered by the initiator and, again, can be requested + to generate and transmit the context key. + + It is envisioned that typical use of SPKM-1 or SPKM-2 will involve + mutual authentication. Although unilateral authentication is + available for both mechanisms, its use is not generally recommended. + +3.1.1. Context Establishment Tokens - Initiator (first token) + + In order to accomplish context establishment, it may be necessary + that both the initiator and the target have access to the other + partys public-key certificate(s). In some environments the initiator + may choose to acquire all certificates and send the relevant ones to + the target in the first token. In other environments the initiator + may request that the target send certificate data in its response + token, or each side may individually obtain the certificate data it + needs. In any case, however, the SPKM implementation must have the + ability to obtain certificates which correspond to a supplied Name. + The actual mechanism to be used to achieve this is a local + implementation matter and is therefore outside the scope of this + specification. + + + Relevant SPKM-REQ syntax is as follows (note that imports from other + documents are given in Appendix A): + + SPKM-REQ ::= SEQUENCE { + requestToken REQ-TOKEN, + certif-data [0] CertificationData OPTIONAL, + auth-data [1] AuthorizationData OPTIONAL + -- see [RFC-1510] for a discussion of auth-data + } + + CertificationData ::= SEQUENCE { + certificationPath [0] CertificationPath OPTIONAL, + certificateRevocationList [1] CertificateList OPTIONAL + } -- at least one of the above shall be present + + + + + +Adams Standards Track [Page 12] + +RFC 2025 SPKM October 1996 + + + CertificationPath ::= SEQUENCE { + userKeyId [0] OCTET STRING OPTIONAL, + -- identifier for user's public key + userCertif [1] Certificate OPTIONAL, + -- certificate containing user's public key + verifKeyId [2] OCTET STRING OPTIONAL, + -- identifier for user's public verification key + userVerifCertif [3] Certificate OPTIONAL, + -- certificate containing user's public verification key + theCACertificates [4] SEQUENCE OF CertificatePair OPTIONAL + } -- certification path from target to source + + Having separate verification fields allows different key pairs + (possibly corresponding to different algorithms) to be used for + encryption/decryption and signing/verification. Presence of [0] or + [1] and absence of [2] and [3] implies that the same key pair is to + be used for enc/dec and verif/signing (note that this practice is not + typically recommended). Presence of [2] or [3] implies that a + separate key pair is to be used for verif/signing, and so [0] or [1] + must also be present. Presence of [4] implies that at least one of + [0], [1], [2], and [3] must also be present. + + REQ-TOKEN ::= SEQUENCE { + req-contents Req-contents, + algId AlgorithmIdentifier, + req-integrity Integrity -- "token" is Req-contents + } + + Integrity ::= BIT STRING + -- If corresponding algId specifies a signing algorithm, + -- "Integrity" holds the result of applying the signing procedure + -- specified in algId to the BER-encoded octet string which results + -- from applying the hashing procedure (also specified in algId) to + -- the DER-encoded octets of "token". + -- Alternatively, if corresponding algId specifies a MACing + -- algorithm, "Integrity" holds the result of applying the MACing + -- procedure specified in algId to the DER-encoded octets of + -- "token" (note that for MAC, algId must be one of the integrity + -- algorithms offered by the initiator with the appropriate subkey + -- derived from the context key (see Section 2.4) used as the key + -- input) + + It is envisioned that typical use of the Integrity field for each of + REQ-TOKEN, REP-TI-TOKEN, and REP-IT-TOKEN will be a true digital + signature, providing unilateral or mutual authentication along with + replay protection, as required. However, there are situations in + which the MAC choice will be appropriate. One example is the case in + which the initiator wishes to remain anonymous (so that the first, or + + + +Adams Standards Track [Page 13] + +RFC 2025 SPKM October 1996 + + + first and third, token(s) will be MACed and the second token will be + signed). Another example is the case in which a previously + authenticated, established, and cached context is being re- + established at some later time (here all exchanged tokens will be + MACed). + + The primary advantage of the MAC choice is that it reduces processing + overhead for cases in which either authentication is not required + (e.g., anonymity) or authentication is established by some other + means (e.g., ability to form the correct MAC on a "fresh" token in + context re-establishment). + + Req-contents ::= SEQUENCE { + tok-id INTEGER (256), -- shall contain 0100(hex) + context-id Random-Integer, -- see Section 6.3 + pvno BIT STRING, -- protocol version number + timestamp UTCTime OPTIONAL, -- mandatory for SPKM-2 + randSrc Random-Integer, + targ-name Name, + src-name [0] Name OPTIONAL, + -- must be supplied unless originator is "anonymous" + req-data Context-Data, + validity [1] Validity OPTIONAL, + -- validity interval for key (may be used in the + -- computation of security context lifetime) + key-estb-set Key-Estb-Algs, + -- specifies set of key establishment algorithms + key-estb-req BIT STRING OPTIONAL, + -- key estb. parameter corresponding to first K-ALG in set + -- (not used if initiator is unable or unwilling to + -- generate and securely transmit key material to target). + -- Established key must satisfy the key length constraints + -- specified in Section 2.4. + key-src-bind OCTET STRING OPTIONAL + -- Used to bind the source name to the symmetric key. + -- This field must be present for the case of SPKM-2 + -- unilateral authen. if the K-ALG in use does not provide + -- such a binding (but is optional for all other cases). + -- The octet string holds the result of applying the + -- mandatory hashing procedure MD5 (in MANDATORY I-ALG; + -- see Section 2.1) as follows: MD5(src || context_key), + -- where "src" is the DER-encoded octets of src-name, + -- "context-key" is the symmetric key (i.e., the + -- unprotected version of what is transmitted in + -- key-estb-req), and "||" is the concatenation operation. + } + + + + + +Adams Standards Track [Page 14] + +RFC 2025 SPKM October 1996 + + + -- The protocol version number (pvno) parameter is a BIT STRING which + -- uses as many bits as necessary to specify all the SPKM protocol + -- versions supported by the initiator (one bit per protocol + -- version). The protocol specified by this document is version 0. + -- Bit 0 of pvno is therefore set if this version is supported; + -- similarly, bit 1 is set if version 1 (if defined in the future) is + -- supported, and so on. Note that for unilateral authentication + -- using SPKM-2, no response token is expected during context + -- establishment, so no protocol negotiation can take place; in this + -- case, the initiator must set exactly one bit of pvno. The version + -- of REQ-TOKEN must correspond to the highest bit set in pvno. + -- The "validity" parameter above is the only way within SPKM for + -- the initiator to transmit desired context lifetime to the target. + -- Since it cannot be guaranteed that the initiator and target have + -- synchronized time, the span of time specified by "validity" is to + -- be taken as definitive (rather than the actual times given in this + -- parameter). + + Random-Integer ::= BIT STRING + + -- Each SPKM implementation is responsible for generating a "fresh" + -- random number for the purpose of context establishment; that is, + -- one which (with high probability) has not been used previously. + -- There are no cryptographic requirements on this random number + -- (i.e., it need not be unpredictable, it simply needs to be fresh). + + Context-Data ::= SEQUENCE { + channelId ChannelId OPTIONAL, -- channel bindings + seq-number INTEGER OPTIONAL, -- sequence number + options Options, + conf-alg Conf-Algs, -- confidentiality. algs. + intg-alg Intg-Algs, -- integrity algorithm + owf-alg OWF-Algs -- for subkey derivation + } + + ChannelId ::= OCTET STRING + + Options ::= BIT STRING { + delegation-state (0), + mutual-state (1), + replay-det-state (2), -- used for replay det. during context + sequence-state (3), -- used for sequencing during context + conf-avail (4), + integ-avail (5), + target-certif-data-required (6) + -- used to request targ's certif. data + } + + + + +Adams Standards Track [Page 15] + +RFC 2025 SPKM October 1996 + + + Conf-Algs ::= CHOICE { + algs [0] SEQUENCE OF AlgorithmIdentifier, + null [1] NULL + -- used when conf. is not available over context + } -- for C-ALG (see Section 5.2 for discussion of QOP) + + Intg-Algs ::= SEQUENCE OF AlgorithmIdentifier + -- for I-ALG (see Section 5.2 for discussion of QOP) + + OWF-Algs ::= SEQUENCE OF AlgorithmIdentifier + -- Contains exactly one algorithm in REQ-TOKEN for SPKM-2 + -- unilateral, and contains at least one algorithm otherwise. + -- Always contains exactly one algorithm in REP-TOKEN. + + Key-Estb-Algs ::= SEQUENCE OF AlgorithmIdentifier + -- to allow negotiation of K-ALG + + A context establishment sequence based on the SPKM will perform + unilateral authentication if the mutual-req bit is not set in the + application's call to gss_init_sec_context(). SPKM-2 accomplishes + this using only SPKM-REQ (thereby authenticating the initiator to the + target), while SPKM-1 accomplishes this using both SPKM-REQ and + SPKM-REP-TI (thereby authenticating the target to the initiator). + + Applications requiring authentication of both peers (initiator as + well as target) must request mutual authentication, resulting in + "mutual-state" being set within SPKM-REQ Options. In response to + such a request, the context target will reply to the initiator with + an SPKM-REP-TI token. If mechanism SPKM-2 has been chosen, this + completes the (timestamp-based) mutual authentication context + establishment exchange. If mechanism SPKM-1 has been chosen and + SPKM-REP-TI is sent, the initiator will then reply to the target with + an SPKM-REP-IT token, completing the (random-number-based) mutual + authentication context establishment exchange. + + Other bits in the Options field of Context-Data are explained in + RFC-1508, with the exception of target-certif-data-required, which + the initiator sets to TRUE to request that the target return its + certification data in the SPKM-REP-TI token. For unilateral + authentication in SPKM-2 (in which no SPKM-REP-TI token is + constructed), this option bit is ignored by both initiator and + target. + + + + + + + + + +Adams Standards Track [Page 16] + +RFC 2025 SPKM October 1996 + + +3.1.2. Context Establishment Tokens - Target + + SPKM-REP-TI ::= SEQUENCE { + responseToken REP-TI-TOKEN, + certif-data CertificationData OPTIONAL + -- included if target-certif-data-required option was + -- set to TRUE in SPKM-REQ + } + + + REP-TI-TOKEN ::= SEQUENCE { + rep-ti-contents Rep-ti-contents, + algId AlgorithmIdentifier, + rep-ti-integ Integrity -- "token" is Rep-ti-contents + } + + Rep-ti-contents ::= SEQUENCE { + tok-id INTEGER (512), -- shall contain 0200 (hex) + context-id Random-Integer, -- see Section 6.3 + pvno [0] BIT STRING OPTIONAL, -- prot. version number + timestamp UTCTime OPTIONAL, -- mandatory for SPKM-2 + randTarg Random-Integer, + src-name [1] Name OPTIONAL, + -- must contain whatever value was supplied in REQ-TOKEN + targ-name Name, + randSrc Random-Integer, + rep-data Context-Data, + validity [2] Validity OPTIONAL, + -- validity interval for key (used if the target can only + -- support a shorter context lifetime than was offered in + -- REQ-TOKEN) + key-estb-id AlgorithmIdentifier OPTIONAL, + -- used if target is changing key estb. algorithm (must be + -- a member of initiators key-estb-set) + key-estb-str BIT STRING OPTIONAL + -- contains (1) the response to the initiators + -- key-estb-req (if init. used a 2-pass K-ALG), or (2) the + -- key-estb-req corresponding to the K-ALG supplied in + -- above key-estb-id, or (3) the key-estb-req corresponding + -- to the first K-ALG supplied in initiator's key-estb-id, + -- if initiator's (OPTIONAL) key-estb-req was not used + -- (target's key-estb-str must be present in this case). + -- Established key must satisfy the key length constraints + -- specified in Section 2.4. + } + + + + + + +Adams Standards Track [Page 17] + +RFC 2025 SPKM October 1996 + + + The protocol version number (pvno) parameter is a BIT STRING which + uses as many bits as necessary to specify a single SPKM protocol + version offered by the initiator which is supported by the target + (one bit per protocol version); that is, the target sets exactly one + bit of pvno. If none of the versions offered by the initiator are + supported by the target, a delete token must be returned so that the + context is never established. If the initiator's pvno has only one + bit set and the target happens to support this protocol version, then + this version is used over the context and the pvno parameter of REP- + TOKEN can be omitted. Finally, if the initiator and target do have + one or more versions in common but the version of the REQ-TOKEN + received is not supported by the target, a REP-TOKEN must be sent + with a desired version bit set in pvno (and dummy values used for all + subsequent token fields). The initiator can then respond with a new + REQ-TOKEN of the proper version (essentially starting context + establishment anew). + +3.1.3. Context Establishment Tokens - Initiator (second token) + + Relevant SPKM-REP-IT syntax is as follows: + + SPKM-REP-IT ::= SEQUENCE { + responseToken REP-IT-TOKEN, + algId AlgorithmIdentifier, + rep-it-integ Integrity -- "token" is REP-IT-TOKEN + } + + REP-IT-TOKEN ::= SEQUENCE { + tok-id INTEGER (768), -- shall contain 0300 (hex) + context-id Random-Integer, + randSrc Random-Integer, + randTarg Random-Integer, + targ-name Name, -- the targ-name specified in REP-TI + src-name Name OPTIONAL, + -- must contain whatever value was supplied in REQ-TOKEN + key-estb-rep BIT STRING OPTIONAL + -- contains the response to targets key-estb-str + -- (if target selected a 2-pass K-ALG) + } + +3.1.4. Error Token + + The syntax of SPKM-ERROR is as follows: + + SPKM-ERROR ::= SEQUENCE { + error-token ERROR-TOKEN, + algId AlgorithmIdentifier, + integrity Integrity -- "token" is ERROR-TOKEN + + + +Adams Standards Track [Page 18] + +RFC 2025 SPKM October 1996 + + + } + + ERROR-TOKRN ::= SEQUENCE { + tok-id INTEGER (1024), -- shall contain 0400 (hex) + context-id Random-Integer + } + + The SPKM-ERROR token is used only during the context establishment + process. If an SPKM-REQ or SPKM-REP-TI token is received in error, + the receiving function (either gss_init_sec_context() or + gss_accept_sec_context()) will generate an SPKM-ERROR token to be + sent to the peer (if the peer is still in the context establishment + process) and will return GSS_S_CONTINUE_NEEDED. If, on the other + hand, no context establishment response is expected from the peer + (i.e., the peer has completed context establishment), the function + will return the appropriate major status code (e.g., GSS_S_BAD_SIG) + along with a minor status of GSS_SPKM_S_SG_CONTEXT_ESTB_ABORT and all + context-relevant information will be deleted. The output token will + not be an SPKM-ERROR token but will instead be an SPKM-DEL token + which will be processed by the peer's gss_process_context_token(). + + If gss_init_sec_context() receives an error token (whether valid or + invalid), it will regenerate SPKM-REQ as its output token and return + a major status code of GSS_S_CONTINUE_NEEDED. (Note that if the + peer's gss_accept_sec_context() receives SPKM-REQ token when it is + expecting a SPKM-REP-IT token, it will ignore SPKM-REQ and return a + zero-length output token with a major status of + GSS_S_CONTINUE_NEEDED.) + + Similarly, if gss_accept_sec_context() receives an error token + (whether valid or invalid), it will regenerate SPKM-REP-TI as its + output token and return a major status code of GSS_S_CONTINUE_NEEDED. + + md5WithRsa is currently stipulated for the signing of context + establishment tokens. Discrepancies involving modulus bitlength can + be resolved through judicious use of the SPKM-ERROR token. The + context initiator signs REQ-TOKEN using the strongest RSA it supports + (e.g., 1024 bits). If the target is unable to verify signatures of + this length, it sends SPKM-ERROR signed with the strongest RSA that + it supports (e.g. 512). + + At the completion of this exchange, both sides know what RSA + bitlength the other supports, since the size of the signature is + equal to the size of the modulus. Further exchanges can be made + (using successively smaller supported bitlengths) until either an + agreement is reached or context establishment is aborted because no + agreement is possible. + + + + +Adams Standards Track [Page 19] + +RFC 2025 SPKM October 1996 + + +3.2. Per-Message and Context Deletion Tokens + + Three classes of tokens are defined in this section: "MIC" tokens, + emitted by calls to gss_getMIC() and consumed by calls to + gss_verifyMIC(); "Wrap" tokens, emitted by calls to gss_wrap() and + consumed by calls to gss_unwrap(); and context deletion tokens, + emitted by calls to gss_init_sec_context(), gss_accept_sec_context(), + or gss_delete_sec_context() and consumed by calls to + gss_process_context_token(). + +3.2.1. Per-message Tokens - Sign / MIC + + Use of the gss_sign() / gss_getMIC() call yields a token, separate + from the user data being protected, which can be used to verify the + integrity of that data as received. The token and the data may be + sent separately by the sending application and it is the receiving + application's responsibility to associate the received data with the + received token. + + The SPKM-MIC token has the following format: + + SPKM-MIC ::= SEQUENCE { + mic-header Mic-Header, + int-cksum BIT STRING + -- Checksum over header and data, + -- calculated according to algorithm + -- specified in int-alg field. + } + + Mic-Header ::= SEQUENCE { + tok-id INTEGER (257), + -- shall contain 0101 (hex) + context-id Random-Integer, + int-alg [0] AlgorithmIdentifier OPTIONAL, + -- Integrity algorithm indicator (must + -- be one of the agreed integrity + -- algorithms for this context). + -- field not present = default id. + snd-seq [1] SeqNum OPTIONAL -- sequence number field. + } + + SeqNum ::= SEQUENCE { + num INTEGER, -- the sequence number itself + dir-ind BOOLEAN -- a direction indicator + } + + + + + + +Adams Standards Track [Page 20] + +RFC 2025 SPKM October 1996 + + +3.2.1.1. Checksum + + Checksum calculation procedure (common to all algorithms -- note that + for SPKM the term "checksum" includes digital signatures as well as + hashes and MACs): Checksums are calculated over the data field, + logically prepended by the bytes of the plaintext token header (mic- + header). The result binds the data to the entire plaintext header, + so as to minimize the possibility of malicious splicing. + + For example, if the int-alg specifies the md5WithRSA algorithm, then + the checksum is formed by computing an MD5 [RFC-1321] hash over the + plaintext data (prepended by the header), and then computing an RSA + signature [PKCS1] on the 16-byte MD5 result. The signature is + computed using the RSA private key retrieved from the credentials + structure and the result (whose length is implied by the "modulus" + parameter in the private key) is stored in the int-cksum field. + + If the int-alg specifies a keyed hashing algorithm (for example, + DES-MAC or md5-DES-CBC), then the key to be used is the appropriate + subkey derived from the context key (see Section 2.4). Again, the + result (whose length is implied by int-alg) is stored in the int- + cksum field. + +3.2.1.2. Sequence Number + + It is assumed that the underlying transport layers (of whatever + protocol stack is being used by the application) will provide + adequate communications reliability (that is, non-malicious loss, + re-ordering, etc., of data packets will be handled correctly). + Therefore, sequence numbers are used in SPKM purely for security, as + opposed to reliability, reasons (that is, to avoid malicious loss, + replay, or re-ordering of SPKM tokens) -- it is therefore recommended + that applications request sequencing and replay detection over all + contexts. Note that sequence numbers are used so that there is no + requirement for secure timestamps in the message tokens. The + initiator's initial sequence number for the current context may be + explicitly given in the Context-Data field of SPKM-REQ and the + target's initial sequence number may be explicitly given in the + Context-Data field of SPKM-REP-TI; if either of these is not given + then the default value of 00 is to be used. + + Sequence number field: The sequence number field is formed from the + sender's four-byte sequence number and a Boolean direction-indicator + (FALSE - sender is the context initiator, TRUE - sender is the + context acceptor). After constructing a gss_sign/getMIC() or + gss_seal/wrap() token, the sender's seq. number is incremented by 1. + + + + + +Adams Standards Track [Page 21] + +RFC 2025 SPKM October 1996 + + +3.2.1.3. Sequence Number Processing + + The receiver of the token will verify the sequence number field by + comparing the sequence number with the expected sequence number and + the direction indicator with the expected direction indicator. If + the sequence number in the token is higher than the expected number, + then the expected sequence number is adjusted and GSS_S_GAP_TOKEN is + returned. If the token sequence number is lower than the expected + number, then the expected sequence number is not adjusted and + GSS_S_DUPLICATE_TOKEN, GSS_S_UNSEQ_TOKEN, or GSS_S_OLD_TOKEN is + returned, whichever is appropriate. If the direction indicator is + wrong, then the expected sequence number is not adjusted and + GSS_S_UNSEQ_TOKEN is returned. + + Since the sequence number is used as part of the input to the + integrity checksum, sequence numbers need not be encrypted, and + attempts to splice a checksum and sequence number from different + messages will be detected. The direction indicator will detect + tokens which have been maliciously reflected. + +3.2.2. Per-message Tokens - Seal / Wrap + + Use of the gss_seal() / gss_wrap() call yields a token which + encapsulates the input user data (optionally encrypted) along with + associated integrity check quantities. The token emitted by + gss_seal() / gss_wrap() consists of an integrity header followed by a + body portion that contains either the plaintext data (if conf-alg = + NULL) or encrypted data (using the appropriate subkey specified in + Section 2.4 for one of the agreed C-ALGs for this context). + + The SPKM-WRAP token has the following format: + + SPKM-WRAP ::= SEQUENCE { + wrap-header Wrap-Header, + wrap-body Wrap-Body + } + + Wrap-Header ::= SEQUENCE { + tok-id INTEGER (513), + -- shall contain 0201 (hex) + context-id Random-Integer, + int-alg [0] AlgorithmIdentifier OPTIONAL, + -- Integrity algorithm indicator (must + -- be one of the agreed integrity + -- algorithms for this context). + -- field not present = default id. + + + + + +Adams Standards Track [Page 22] + +RFC 2025 SPKM October 1996 + + + conf-alg [1] Conf-Alg OPTIONAL, + -- Confidentiality algorithm indicator + -- (must be NULL or one of the agreed + -- confidentiality algorithms for this + -- context). + -- field not present = default id. + -- NULL = none (no conf. applied). + snd-seq [2] SeqNum OPTIONAL + -- sequence number field. + } + + + + Wrap-Body ::= SEQUENCE { + int-cksum BIT STRING, + -- Checksum of header and data, + -- calculated according to algorithm + -- specified in int-alg field. + data BIT STRING + -- encrypted or plaintext data. + } + + Conf-Alg ::= CHOICE { + algId [0] AlgorithmIdentifier, + null [1] NULL + } + + +3.2.2.1: Confounding + + As in [KRB5], an 8-byte random confounder is prepended to the data to + compensate for the fact that an IV of zero is used for encryption. + The result is referred to as the "confounded" data field. + +3.2.2.2. Checksum + + Checksum calculation procedure (common to all algorithms): Checksums + are calculated over the plaintext data field, logically prepended by + the bytes of the plaintext token header (wrap-header). As with + gss_sign() / gss_getMIC(), the result binds the data to the entire + plaintext header, so as to minimize the possibility of malicious + splicing. + + The examples for md5WithRSA and DES-MAC are exactly as specified in + 3.2.1.1. + + If int-alg specifies md5-DES-CBC and conf-alg specifies anything + other than DES-CBC, then the checksum is computed according to + + + +Adams Standards Track [Page 23] + +RFC 2025 SPKM October 1996 + + + 3.2.1.1 and the result is stored in int-cksum. However, if conf-alg + specifies DES-CBC then the encryption and the integrity are done as + follows. An MD5 [RFC-1321] hash is computed over the plaintext data + (prepended by the header). This 16-byte value is appended to the + concatenation of the "confounded" data and 1-8 padding bytes (the + padding is as specified in [KRB5] for DES-CBC). The result is then + CBC encrypted using the DES-CBC subkey (see Section 2.4) and placed + in the "data" field of Wrap-Body. The final two blocks of ciphertext + (i.e., the encrypted MD5 hash) are also placed in the int-cksum field + of Wrap-Body as the integrity checksum. + + If int-alg specifies sum64-DES-CBC then conf-alg must specify DES-CBC + (i.e., confidentiality must be requested by the calling application + or SPKM will return an error). Encryption and integrity are done in + a single pass using the DES-CBC subkey as follows. The sum (modulo + 2**64 - 1) of all plaintext data blocks (prepended by the header) is + computed. This 8-byte value is appended to the concatenation of the + "confounded" data and 1-8 padding bytes (the padding is as specified + in [KRB5] for DES-CBC). As above, the result is then CBC encrypted + and placed in the "data" field of Wrap-Body. The final block of + ciphertext (i.e., the encrypted sum) is also placed in the int-cksum + field of Wrap-Body as the integrity checksum. + +3.2.2.3 Sequence Number + + Sequence numbers are computed and processed for gss_wrap() exactly as + specified in 3.2.1.2 and 3.2.1.3. + +3.2.2.4: Data Encryption + + The following procedure is followed unless (a) conf-alg is NULL (no + encryption), or (b) conf-alg is DES-CBC and int-alg is md5-DES-CBC + (encryption as specified in 3.2.2.2), or (c) int-alg is sum64-DES-CBC + (encryption as specified in 3.2.2.2): + + The "confounded" data is padded and encrypted according to the + algorithm specified in the conf-alg field. The data is encrypted + using CBC with an IV of zero. The key used is the appropriate subkey + derived from the established context key using the subkey derivation + algorithm described in Section 2.4 (this ensures that the subkey used + for encryption and the subkey used for a separate, keyed integrity + algorithm -- for example DES-MAC, but not sum64-DES-CBC -- are + different). + +3.2.3. Context deletion token + + The token emitted by gss_delete_sec_context() is based on the format + for tokens emitted by gss_sign() / gss_getMIC(). + + + +Adams Standards Track [Page 24] + +RFC 2025 SPKM October 1996 + + + The SPKM-DEL token has the following format: + + SPKM-DEL ::= SEQUENCE { + del-header Del-Header, + int-cksum BIT STRING + -- Checksum of header, calculated + -- according to algorithm specified + -- in int-alg field. + } + + Del-Header ::= SEQUENCE { + tok-id INTEGER (769), + -- shall contain 0301 (hex) + context-id Random-Integer, + int-alg [0] AlgorithmIdentifier OPTIONAL, + -- Integrity algorithm indicator (must + -- be one of the agreed integrity + -- algorithms for this context). + -- field not present = default id. + snd-seq [1] SeqNum OPTIONAL + -- sequence number field. + } + + The field snd-seq will be calculated as for tokens emitted by + gss_sign() / gss_getMIC(). The field int-cksum will be calculated as + for tokens emitted by gss_sign() / gss_getMIC(), except that the + user-data component of the checksum data will be a zero-length + string. + + If a valid delete token is received, then the SPKM implementation + will delete the context and gss_process_context_token() will return a + major status of GSS_S_COMPLETE and a minor status of + GSS_SPKM_S_SG_CONTEXT_DELETED. If, on the other hand, the delete + token is invalid, the context will not be deleted and + gss_process_context_token() will return the appropriate major status + (GSS_S_BAD_SIG, for example) and a minor status of + GSS_SPKM_S_SG_BAD_DELETE_TOKEN_RECD. The application may wish to + take some action at this point to check the context status (such as + sending a sealed/wrapped test message to its peer and waiting for a + sealed/wrapped response). + +4. Name Types and Object Identifiers + + No mandatory name forms have yet been defined for SPKM. This section + is for further study. + + + + + + +Adams Standards Track [Page 25] + +RFC 2025 SPKM October 1996 + + +4.1. Optional Name Forms + + This section discusses name forms which may optionally be supported + by implementations of the SPKM GSS-API mechanism. It is recognized + that OS-specific functions outside GSS-API are likely to exist in + order to perform translations among these forms, and that GSS-API + implementations supporting these forms may themselves be layered atop + such OS-specific functions. Inclusion of this support within GSS-API + implementations is intended as a convenience to applications. + +4.1.1. User Name Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) user_name(1)}. The recommended symbolic name for this + type is "GSS_SPKM_NT_USER_NAME". + + This name type is used to indicate a named user on a local system. + Its interpretation is OS-specific. This name form is constructed as: + + username + +4.1.2. Machine UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) machine_uid_name(2)}. The recommended symbolic name for + this type is "GSS_SPKM_NT_MACHINE_UID_NAME". + + This name type is used to indicate a numeric user identifier + corresponding to a user on a local system. Its interpretation is + OS-specific. The gss_buffer_desc representing a name of this type + should contain a locally-significant uid_t, represented in host byte + order. The gss_import_name() operation resolves this uid into a + username, which is then treated as the User Name Form. + +4.1.3. String UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) string_uid_name(3)}. The recommended symbolic name for + this type is "GSS_SPKM_NT_STRING_UID_NAME". + + This name type is used to indicate a string of digits representing + the numeric user identifier of a user on a local system. Its + interpretation is OS-specific. This name type is similar to the + Machine UID Form, except that the buffer contains a string + representing the uid_t. + + + +Adams Standards Track [Page 26] + +RFC 2025 SPKM October 1996 + + +5. Parameter Definitions + + This section defines parameter values used by the SPKM GSS-API + mechanism. It defines interface elements in support of portability. + +5.1. Minor Status Codes + + This section recommends common symbolic names for minor_status values + to be returned by the SPKM GSS-API mechanism. Use of these + definitions will enable independent implementors to enhance + application portability across different implementations of the + mechanism defined in this specification. (In all cases, + implementations of gss_display_status() will enable callers to + convert minor_status indicators to text representations.) Each + implementation must make available, through include files or other + means, a facility to translate these symbolic names into the concrete + values which a particular GSS-API implementation uses to represent + the minor_status values specified in this section. It is recognized + that this list may grow over time, and that the need for additional + minor_status codes specific to particular implementations may arise. + +5.1.1. Non-SPKM-specific codes (Minor Status Code MSB, bit 31, SET) + +5.1.1.1. GSS-Related codes (Minor Status Code bit 30 SET) + + GSS_S_G_VALIDATE_FAILED + /* "Validation error" */ + GSS_S_G_BUFFER_ALLOC + /* "Couldn't allocate gss_buffer_t data" */ + GSS_S_G_BAD_MSG_CTX + /* "Message context invalid" */ + GSS_S_G_WRONG_SIZE + /* "Buffer is the wrong size" */ + GSS_S_G_BAD_USAGE + /* "Credential usage type is unknown" */ + GSS_S_G_UNAVAIL_QOP + /* "Unavailable quality of protection specified" */ + +5.1.1.2. Implementation-Related codes (Minor Status Code bit 30 OFF) + + GSS_S_G_MEMORY_ALLOC + /* "Couldn't perform requested memory allocation" */ + +5.1.2. SPKM-specific-codes (Minor Status Code MSB, bit 31, OFF) + + GSS_SPKM_S_SG_CONTEXT_ESTABLISHED + /* "Context is already fully established" */ + GSS_SPKM_S_SG_BAD_INT_ALG_TYPE + + + +Adams Standards Track [Page 27] + +RFC 2025 SPKM October 1996 + + + /* "Unknown integrity algorithm type in token" */ + GSS_SPKM_S_SG_BAD_CONF_ALG_TYPE + /* "Unknown confidentiality algorithm type in token" */ + GSS_SPKM_S_SG_BAD_KEY_ESTB_ALG_TYPE + /* "Unknown key establishment algorithm type in token" */ + GSS_SPKM_S_SG_CTX_INCOMPLETE + /* "Attempt to use incomplete security context" */ + GSS_SPKM_S_SG_BAD_INT_ALG_SET + /* "No integrity algorithm in common from offered set" */ + GSS_SPKM_S_SG_BAD_CONF_ALG_SET + /* "No confidentiality algorithm in common from offered set" */ + GSS_SPKM_S_SG_BAD_KEY_ESTB_ALG_SET + /* "No key establishment algorithm in common from offered set" */ + GSS_SPKM_S_SG_NO_PVNO_IN_COMMON + /* "No protocol version number in common from offered set" */ + GSS_SPKM_S_SG_INVALID_TOKEN_DATA + /* "Data is improperly formatted: cannot encode into token" */ + GSS_SPKM_S_SG_INVALID_TOKEN_FORMAT + /* "Received token is improperly formatted: cannot decode" */ + GSS_SPKM_S_SG_CONTEXT_DELETED + /* "Context deleted at peer's request" */ + GSS_SPKM_S_SG_BAD_DELETE_TOKEN_RECD + /* "Invalid delete token received -- context not deleted" */ + GSS_SPKM_S_SG_CONTEXT_ESTB_ABORT + /* "Unrecoverable context establishment error. Context deleted" */ + +5.2. Quality of Protection Values + + The Quality of Protection (QOP) parameter is used in the SPKM GSS-API + mechanism as input to gss_sign() and gss_seal() (gss_getMIC() and + gss_wrap()) to select among alternate confidentiality and integrity- + checking algorithms. Once these sets of algorithms have been agreed + upon by the context initiator and target, the QOP parameter simply + selects from these ordered sets. + + More specifically, the SPKM-REQ token sends an ordered sequence of + Alg. IDs specifying integrity-checking algorithms supported by the + initiator and an ordered sequence of Alg. IDs specifying + confidentiality algorithms supported by the initiator. The target + returns the subset of the offered integrity-checking Alg. IDs which + it supports and the subset of the offered confidentiality Alg. IDs + which it supports in the SPKM-REP-TI token (in the same relative + orders as those given by the initiator). Thus, the initiator and + target each know the algorithms which they themselves support and the + algorithms which both sides support (the latter are defined to be + those supported over the established context). The QOP parameter has + meaning and validity with reference to this knowledge. For example, + an application may request integrity algorithm number 3 as defined by + + + +Adams Standards Track [Page 28] + +RFC 2025 SPKM October 1996 + + + the mechanism specification. If this algorithm is supported over + this context then it is used; otherwise, GSS_S_FAILURE and an + appropriate minor status code are returned. + + If the SPKM-REP-TI token is not used (unilateral authentication using + SPKM-2), then the "agreed" sets of Alg. IDs are simply taken to be + the initiator's sets (if this is unacceptable to the target then it + must return an error token so that the context is never established). + Note that, in the interest of interoperability, the initiator is not + required to offer every algorithm it supports; rather, it may offer + only the mandated/recommended SPKM algorithms since these are likely + to be supported by the target. + + The QOP parameter for SPKM is defined to be a 32-bit unsigned integer + (an OM_uint32) with the following bit-field assignments: + + Confidentiality Integrity + 31 (MSB) 16 15 (LSB) 0 +------------------------------------|----------------------------------- +| TS (5) | U(3) | IA (4) | MA (4) | TS (5) | U(3) | IA (4) | MA(4) | +------------------------------------|----------------------------------- + + where + + TS is a 5-bit Type Specifier (a semantic qualifier whose value + specifies the type of algorithm which may be used to protect the + corresponding token -- see below for details); + + U is a 3-bit Unspecified field (available for future + use/expansion); + + IA is a 4-bit field enumerating Implementation-specific + Algorithms; and + + MA is a 4-bit field enumerating Mechanism-defined Algorithms. + + The interpretation of the QOP parameter is as follows (note that the + same procedure is used for both the confidentiality and the integrity + halves of the parameter). The MA field is examined first. If it is + non-zero then the algorithm used to protect the token is the + mechanism-specified algorithm corresponding to that integer value. + + If MA is zero then IA is examined. If this field value is non-zero + then the algorithm used to protect the token is the implementation- + specified algorithm corresponding to that integer value (if this + algorithm is available over the established context). Note that use + of this field may hinder portability since a particular value may + specify one algorithm in one implementation of the mechanism and may + + + +Adams Standards Track [Page 29] + +RFC 2025 SPKM October 1996 + + + not be supported or may specify a completely different algorithm in + another implementation of the mechanism. + + Finally, if both MA and IA are zero then TS is examined. A value of + zero for TS specifies the default algorithm for the established + context, which is defined to be the first algorithm on the + initiator's list of offered algorithms (confidentiality or integrity, + depending on which half of QOP is being examined) which is supported + over the context. A non-zero value for TS corresponds to a + particular algorithm qualifier and selects the first algorithm + supported over the context which satisfies that qualifier. + + The following TS values (i.e., algorithm qualifiers) are specified; + other values may be added in the future. + + For the Confidentiality TS field: + + 00001 (1) = SPKM_SYM_ALG_STRENGTH_STRONG + 00010 (2) = SPKM_SYM_ALG_STRENGTH_MEDIUM + 00011 (3) = SPKM_SYM_ALG_STRENGTH_WEAK + + For the Integrity TS field: + + 00001 (1) = SPKM_INT_ALG_NON_REP_SUPPORT + 00010 (2) = SPKM_INT_ALG_REPUDIABLE + + Clearly, qualifiers such as strong, medium, and weak are debatable + and likely to change with time, but for the purposes of this version + of the specification we define these terms as follows. A + confidentiality algorithm is "weak" if the effective key length of + the cipher is 40 bits or less; it is "medium-strength" if the + effective key length is strictly between 40 and 80 bits; and it is + "strong" if the effective key length is 80 bits or greater. (Note + that "effective key length" describes the computational effort + required to break a cipher using the best-known cryptanalytic attack + against that cipher.) + + A five-bit TS field allows up to 31 qualifiers for each of + confidentiality and integrity (since "0" is reserved for "default"). + This document specifies three for confidentiality and two for + integrity, leaving a lot of room for future specification. + Suggestions of qualifiers such as "fast", "medium-speed", and "slow" + have been made, but such terms are difficult to quantify (and in any + case are platform- and processor-dependent), and so have been left + out of this initial specification. The intention is that the TS + terms be quantitative, environment-independent qualifiers of + algorithms, as much as this is possible. + + + + +Adams Standards Track [Page 30] + +RFC 2025 SPKM October 1996 + + + Use of the QOP structure as defined above is ultimately meant to be + as follows. + + - TS values are specified at the GSS-API level and are therefore + portable across mechanisms. Applications which know nothing about + algorithms are still able to choose "quality" of protection for + their message tokens. + + - MA values are specified at the mechanism level and are therefore + portable across implementations of a mechanism. For example, all + implementations of the Kerberos V5 GSS mechanism must support + + GSS_KRB5_INTEG_C_QOP_MD5 (value: 1) + GSS_KRB5_INTEG_C_QOP_DES_MD5 (value: 2) + GSS_KRB5_INTEG_C_QOP_DES_MAC (value: 3). + + (Note that these Kerberos-specified integrity QOP values do not + conflict with the QOP structure defined above.) + + - IA values are specified at the implementation level (in user + documentation, for example) and are therefore typically non- + portable. An application which is aware of its own mechanism + implementation and the mechanism implementation of its peer, + however, is free to use these values since they will be perfectly + valid and meaningful over that context and between those peers. + + The receiver of a token must pass back to its calling application a + QOP parameter with all relevant fields set. For example, if triple- + DES has been specified by a mechanism as algorithm 8, then a receiver + of a triple-DES-protected token must pass to its application (QOP + Confidentiality TS=1, IA=0, MA=8). In this way, the application is + free to read whatever part of the QOP it understands (TS or IA/MA). + + To aid in implementation and interoperability, the following + stipulation is made. The set of integrity Alg. IDs sent by the + initiator must contain at least one specifying an algorithm which + computes a digital signature supporting non-repudiation, and must + contain at least one specifying any other (repudiable) integrity + algorithm. The subset of integrity Alg. IDs returned by the target + must also contain at least one specifying an algorithm which computes + a digital signature supporting non-repudiation, and at least one + specifying a repudiable integrity algorithm. + + The reason for this stipulation is to ensure that every SPKM + implementation will provide an integrity service which supports non- + repudiation and one which does not support non-repudiation. An + application with no knowledge of underlying algorithms can choose one + or the other by passing (QOP Integrity TS=1, IA=MA=0) or (QOP + + + +Adams Standards Track [Page 31] + +RFC 2025 SPKM October 1996 + + + Integrity TS=2, IA=MA=0). Although an initiator who wishes to remain + anonymous will never actually use the non-repudiable digital + signature, this integrity service must be available over the context + so that the target can use it if desired. + + Finally, in accordance with the MANDATORY and RECOMMENDED algorithms + given in Section 2, the following QOP values are specified for SPKM. + + For the Confidentiality MA field: + + 0001 (1) = DES-CBC + + For the Integrity MA field: + + 0001 (1) = md5WithRSA + 0010 (2) = DES-MAC + +6. Support Functions + + This section describes a mandatory support function for SPKM- + conformant implementations which may, in fact, be of value in all + GSS-API mechanisms. It makes use of the token-id and context-id + information which is included in SPKM context-establishment, error, + context-deletion, and per-message tokens. The function is defined in + the following section. + +6.1. SPKM_Parse_token call + + Inputs: + + o input_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o mech_type OBJECT IDENTIFIER, + + o token_type INTEGER, + + o context_handle CONTEXT HANDLE, + + + + + + + + +Adams Standards Track [Page 32] + +RFC 2025 SPKM October 1996 + + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the input_token could be parsed for + all relevant fields. The resulting values are stored in + mech_type, token_type and context_handle, respectively (with NULLs + in any parameters which are not relevant). + + o GSS_S_DEFECTIVE_TOKEN indicates that either the token-id or the + context-id (if it was expected) information could not be parsed. + A non-NULL return value in token_type indicates that the latter + situation occurred. + + o GSS_S_NO_TYPE indicates that the token-id information could be + parsed, but it did not correspond to any valid token_type. + + (Note that this major status code has not been defined for GSS in + RFC-1508. Until such a definition is made (if ever), SPKM + implementations should instead return GSS_S_DEFECTIVE_TOKEN with + both token_type and context_handle set to NULL. This essentially + implies that unrecognized token-id information is considered to be + equivalent to token-id information which could not be parsed.) + + o GSS_S_NO_CONTEXT indicates that the context-id could be parsed, + but it did not correspond to any valid context_handle. + + o GSS_S_FAILURE indicates that the mechanism type could not be + parsed (for example, the token may be corrupted). + + SPKM_Parse_token() is used to return to an application the mechanism + type, token type, and context handle which correspond to a given + input token. Since 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 GSS. Of primary importance is the token + type, which the application can then use to decide which GSS function + to call in order to have the token processed. + + If all tokens are framed as suggested in RFC-1508, Appendix B + (specified both in the Kerberos V5 GSS mechanism [KRB5] and in this + document), then any mechanism implementation should be able to return + at least the mech_type parameter (the other parameters being NULL) + for any uncorrupted input token. If the mechanism implementation + whose SPKM_Parse_token() function is being called does recognize the + token, it can return token_type so that the application can + subsequently call the correct GSS function. Finally, if the + mechanism provides a context-id field in its tokens (as SPKM does), + then an implementation can map the context-id to a context_handle and + return this to the application. This is necessary for the situation + + + +Adams Standards Track [Page 33] + +RFC 2025 SPKM October 1996 + + + where an application has multiple contexts open simultaneously, all + using the same mechanism. When an incoming token arrives, the + application can use this function to determine not only which GSS + function to call, but also which context_handle to use for the call. + Note that this function does no cryptographic processing to determine + the validity of tokens; it simply attempts to parse the mech_type, + token_type, and context-id fields of any token it is given. Thus, it + is conceivable, for example, that an arbitrary buffer of data might + start with random values which look like a valid mech_type and that + SPKM_Parse_token() would return incorrect information if given this + buffer. While conceivable, however, such a situation is unlikely. + + The SPKM_Parse_token() function is mandatory for SPKM-conformant + implementations, but it is optional for applications. That is, if an + application has only one context open and can guess which GSS + function to call (or is willing to put up with some error codes), + then it need never call SPKM_Parse_token(). Furthermore, if this + function ever migrates up to the GSS-API level, then + SPKM_Parse_token() will be deprecated at that time in favour of + GSS_Parse_token(), or whatever the new name and function + specification might be. Note finally that no minor status return + codes have been defined for this function at this time. + +6.2. The token_type Output Parameter + + The following token types are defined: + + GSS_INIT_TOKEN = 1 + GSS_ACCEPT_TOKEN = 2 + GSS_ERROR_TOKEN = 3 + GSS_SIGN_TOKEN = GSS_GETMIC_TOKEN = 4 + GSS_SEAL_TOKEN = GSS_WRAP_TOKEN = 5 + GSS_DELETE_TOKEN = 6 + + All SPKM mechanisms shall be able to perform the mapping from the + token-id information which is included in every token (through the + tag values in SPKMInnerContextToken or through the tok-id field) to + one of the above token types. Applications should be able to decide, + on the basis of token_type, which GSS function to call (for example, + if the token is a GSS_INIT_TOKEN then the application will call + gss_accept_sec_context(), and if the token is a GSS_WRAP_TOKEN then + the application will call gss_unwrap()). + +6.3. The context_handle Output Parameter + + The SPKM mechanism implementation is responsible for maintaining a + mapping between the context-id value which is included in every token + and a context_handle, thus associating an individual token with its + + + +Adams Standards Track [Page 34] + +RFC 2025 SPKM October 1996 + + + proper context. Clearly the value of context_handle may be locally + determined and may, in fact, be associated with memory containing + sensitive data on the local system, and so having the context-id + actually be set equal to a computed context_handle will not work in + general. Conversely, having the context_handle actually be set equal + to a computed context-id will not work in general either, because + context_handle must be returned to the application by the first call + to gss_init_sec_context() or gss_accept_sec_context(), whereas + uniqueness of the context-id (over all contexts at both ends) may + require that both initiator and target be involved in the + computation. Consequently, context_handle and context-id must be + computed separately and the mechanism implementation must be able to + map from one to the other by the completion of context establishment + at the latest. + + Computation of context-id during context establishment is + accomplished as follows. Each SPKM implementation is responsible for + generating a "fresh" random number; that is, one which (with high + probability) has not been used previously. Note that there are no + cryptographic requirements on this random number (i.e., it need not + be unpredictable, it simply needs to be fresh). The initiator passes + its random number to the target in the context-id field of the SPKM- + REQ token. If no further context establishment tokens are expected + (as for unilateral authentication in SPKM-2), then this value is + taken to be the context-id (if this is unacceptable to the target + then an error token must be generated). Otherwise, the target + generates its random number and concatenates it to the end of the + initiator's random number. This concatenated value is then taken to + be the context-id and is used in SPKM-REP-TI and in all subsequent + tokens over that context. + + Having both peers contribute to the context-id assures each peer of + freshness and therefore precludes replay attacks between contexts + (where a token from an old context between two peers is maliciously + injected into a new context between the same or different peers). + Such assurance is not available to the target in the case of + unilateral authentication using SPKM-2, simply because it has not + contributed to the freshness of the computed context-id (instead, it + must trust the freshness of the initiator's random number, or reject + the context). The key-src-bind field in SPKM-REQ is required to be + present for the case of SPKM-2 unilateral authentication precisely to + assist the target in trusting the freshness of this token (and its + proposed context key). + +7. Security Considerations + + Security issues are discussed throughout this memo. + + + + +Adams Standards Track [Page 35] + +RFC 2025 SPKM October 1996 + + +8. References + + [Davi89]: D. W. Davies and W. L. Price, "Security for Computer + Networks", Second Edition, John Wiley and Sons, New York, 1989. + + [FIPS-113]: National Bureau of Standards, Federal Information + Processing Standard 113, "Computer Data Authentication", May 1985. + + [GSSv2]: Linn, J., "Generic Security Service Application Program + Interface Version 2", Work in Progress. + + [Juen84]: R. R. Jueneman, C. H. Meyer and S. M. Matyas, Message + Authentication with Manipulation Detection Codes, in Proceedings of + the 1983 IEEE Symposium on Security and Privacy, IEEE Computer + Society Press, 1984, pp.33-54. + + [KRB5]: Linn, J., "The Kerberos Version 5 GSS-API Mechanism", + RFC 1964, June 1996. + + [PKCS1]: RSA Encryption Standard, Version 1.5, RSA Data Security, + Inc., Nov. 1993. + + [PKCS3]: Diffie-Hellman Key-Agreement Standard, Version 1.4, RSA + Data Security, Inc., Nov. 1993. + + [RFC-1321]: Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321. + + [RFC-1422]: Kent, S., "Privacy Enhancement for Internet Electronic + Mail: Part II: Certificate-Based Key Management", RFC 1422. + + [RFC-1423]: Balenson, D., "Privacy Enhancement for Internet + Elecronic Mail: Part III: Algorithms, Modes, and Identifiers", + RFC 1423. + + [RFC-1508]: Linn, J., "Generic Security Service Application Program + Interface", RFC 1508. + + [RFC-1509]: Wray, J., "Generic Security Service Application Program + Interface: C-bindings", RFC 1509. + + [RFC-1510]: Kohl J., and C. Neuman, "The Kerberos Network + Authentication Service (V5)", RFC 1510. + + [9798]: ISO/IEC 9798-3, "Information technology - Security + Techniques - Entity authentication mechanisms - Part 3: Entitiy + authentication using a public key algorithm", ISO/IEC, 1993. + + + + + +Adams Standards Track [Page 36] + +RFC 2025 SPKM October 1996 + + + [X.501]: ISO/IEC 9594-2, "Information Technology - Open Systems + Interconnection - The Directory: Models", CCITT/ITU Recommendation + X.501, 1993. + + [X.509]: ISO/IEC 9594-8, "Information Technology - Open Systems + Interconnection - The Directory: Authentication Framework", + CCITT/ITU Recommendation X.509, 1993. + + [X9.44]: ANSI, "Public Key Cryptography Using Reversible + Algorithms for the Financial Services Industry: Transport of + Symmetric Algorithm Keys Using RSA", X9.44-1993. + +9. Author's Address + + Carlisle Adams + Bell-Northern Research + P.O.Box 3511, Station C + Ottawa, Ontario, CANADA K1Y 4H7 + + Phone: +1 613.763.9008 + EMail: cadams@bnr.ca + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Adams Standards Track [Page 37] + +RFC 2025 SPKM October 1996 + + +Appendix A: ASN.1 Module Definition + +SpkmGssTokens {iso(1) identified-organization(3) dod(6) internet(1) + security(5) mechanisms(5) spkm(1) spkmGssTokens(10)} + + +DEFINITIONS IMPLICIT TAGS ::= +BEGIN + + +-- EXPORTS ALL -- + + +IMPORTS + + Name + FROM InformationFramework {joint-iso-ccitt(2) ds(5) module(1) + informationFramework(1) 2} + + Certificate, CertificateList, CertificatePair, AlgorithmIdentifier, + Validity + FROM AuthenticationFramework {joint-iso-ccitt(2) ds(5) module(1) + authenticationFramework(7) 2} ; + + + +-- types -- + + SPKM-REQ ::= SEQUENCE { + requestToken REQ-TOKEN, + certif-data [0] CertificationData OPTIONAL, + auth-data [1] AuthorizationData OPTIONAL + } + + + CertificationData ::= SEQUENCE { + certificationPath [0] CertificationPath OPTIONAL, + certificateRevocationList [1] CertificateList OPTIONAL + } -- at least one of the above shall be present + + + CertificationPath ::= SEQUENCE { + userKeyId [0] OCTET STRING OPTIONAL, + userCertif [1] Certificate OPTIONAL, + verifKeyId [2] OCTET STRING OPTIONAL, + userVerifCertif [3] Certificate OPTIONAL, + theCACertificates [4] SEQUENCE OF CertificatePair OPTIONAL + } -- Presence of [2] or [3] implies that [0] or [1] must also be + + + +Adams Standards Track [Page 38] + +RFC 2025 SPKM October 1996 + + + -- present. Presence of [4] implies that at least one of [0], [1], + -- [2], and [3] must also be present. + + REQ-TOKEN ::= SEQUENCE { + req-contents Req-contents, + algId AlgorithmIdentifier, + req-integrity Integrity -- "token" is Req-contents + } + + Integrity ::= BIT STRING + -- If corresponding algId specifies a signing algorithm, + -- "Integrity" holds the result of applying the signing procedure + -- specified in algId to the BER-encoded octet string which results + -- from applying the hashing procedure (also specified in algId) to + -- the DER-encoded octets of "token". + -- Alternatively, if corresponding algId specifies a MACing + -- algorithm, "Integrity" holds the result of applying the MACing + -- procedure specified in algId to the DER-encoded octets of + -- "token" + + Req-contents ::= SEQUENCE { + tok-id INTEGER (256), -- shall contain 0100 (hex) + context-id Random-Integer, + pvno BIT STRING, + timestamp UTCTime OPTIONAL, -- mandatory for SPKM-2 + randSrc Random-Integer, + targ-name Name, + src-name [0] Name OPTIONAL, + req-data Context-Data, + validity [1] Validity OPTIONAL, + key-estb-set Key-Estb-Algs, + key-estb-req BIT STRING OPTIONAL, + key-src-bind OCTET STRING OPTIONAL + -- This field must be present for the case of SPKM-2 + -- unilateral authen. if the K-ALG in use does not provide + -- such a binding (but is optional for all other cases). + -- The octet string holds the result of applying the + -- mandatory hashing procedure (in MANDATORY I-ALG; + -- see Section 2.1) as follows: MD5(src || context_key), + -- where "src" is the DER-encoded octets of src-name, + -- "context-key" is the symmetric key (i.e., the + -- unprotected version of what is transmitted in + -- key-estb-req), and "||" is the concatenation operation. + } + + Random-Integer ::= BIT STRING + + + + + +Adams Standards Track [Page 39] + +RFC 2025 SPKM October 1996 + + + Context-Data ::= SEQUENCE { + channelId ChannelId OPTIONAL, + seq-number INTEGER OPTIONAL, + options Options, + conf-alg Conf-Algs, + intg-alg Intg-Algs, + owf-alg OWF-Algs + } + + ChannelId ::= OCTET STRING + + Options ::= BIT STRING { + delegation-state (0), + mutual-state (1), + replay-det-state (2), + sequence-state (3), + conf-avail (4), + integ-avail (5), + target-certif-data-required (6) + } + + Conf-Algs ::= CHOICE { + algs [0] SEQUENCE OF AlgorithmIdentifier, + null [1] NULL + } + + Intg-Algs ::= SEQUENCE OF AlgorithmIdentifier + + OWF-Algs ::= SEQUENCE OF AlgorithmIdentifier + + Key-Estb-Algs ::= SEQUENCE OF AlgorithmIdentifier + + + SPKM-REP-TI ::= SEQUENCE { + responseToken REP-TI-TOKEN, + certif-data CertificationData OPTIONAL + -- present if target-certif-data-required option was + } -- set to TRUE in SPKM-REQ + + REP-TI-TOKEN ::= SEQUENCE { + rep-ti-contents Rep-ti-contents, + algId AlgorithmIdentifier, + rep-ti-integ Integrity -- "token" is Rep-ti-contents + } + + Rep-ti-contents ::= SEQUENCE { + tok-id INTEGER (512), -- shall contain 0200 (hex) + context-id Random-Integer, + + + +Adams Standards Track [Page 40] + +RFC 2025 SPKM October 1996 + + + pvno [0] BIT STRING OPTIONAL, + timestamp UTCTime OPTIONAL, -- mandatory for SPKM-2 + randTarg Random-Integer, + src-name [1] Name OPTIONAL, + targ-name Name, + randSrc Random-Integer, + rep-data Context-Data, + validity [2] Validity OPTIONAL, + key-estb-id AlgorithmIdentifier OPTIONAL, + key-estb-str BIT STRING OPTIONAL + } + + + SPKM-REP-IT ::= SEQUENCE { + responseToken REP-IT-TOKEN, + algId AlgorithmIdentifier, + rep-it-integ Integrity -- "token" is REP-IT-TOKEN + } + + REP-IT-TOKEN ::= SEQUENCE { + tok-id INTEGER (768), -- shall contain 0300 (hex) + context-id Random-Integer, + randSrc Random-Integer, + randTarg Random-Integer, + targ-name Name, + src-name Name OPTIONAL, + key-estb-rep BIT STRING OPTIONAL + } + + SPKM-ERROR ::= SEQUENCE { + errorToken ERROR-TOKEN, + algId AlgorithmIdentifier, + integrity Integrity -- "token" is ERROR-TOKEN + } + + ERROR-TOKEN ::= SEQUENCE { + tok-id INTEGER (1024), -- shall contain 0400 (hex) + context-id Random-Integer + } + + SPKM-MIC ::= SEQUENCE { + mic-header Mic-Header, + int-cksum BIT STRING + } + + Mic-Header ::= SEQUENCE { + tok-id INTEGER (257), -- shall contain 0101 (hex) + context-id Random-Integer, + + + +Adams Standards Track [Page 41] + +RFC 2025 SPKM October 1996 + + + int-alg [0] AlgorithmIdentifier OPTIONAL, + snd-seq [1] SeqNum OPTIONAL + } + + SeqNum ::= SEQUENCE { + num INTEGER, + dir-ind BOOLEAN + } + + SPKM-WRAP ::= SEQUENCE { + wrap-header Wrap-Header, + wrap-body Wrap-Body + } + + Wrap-Header ::= SEQUENCE { + tok-id INTEGER (513), -- shall contain 0201 (hex) + context-id Random-Integer, + int-alg [0] AlgorithmIdentifier OPTIONAL, + conf-alg [1] Conf-Alg OPTIONAL, + snd-seq [2] SeqNum OPTIONAL + } + + Wrap-Body ::= SEQUENCE { + int-cksum BIT STRING, + data BIT STRING + } + + Conf-Alg ::= CHOICE { + algId [0] AlgorithmIdentifier, + null [1] NULL + } + + + SPKM-DEL ::= SEQUENCE { + del-header Del-Header, + int-cksum BIT STRING + } + + Del-Header ::= SEQUENCE { + tok-id INTEGER (769), -- shall contain 0301 (hex) + context-id Random-Integer, + int-alg [0] AlgorithmIdentifier OPTIONAL, + snd-seq [1] SeqNum OPTIONAL + } + + +-- other types -- + + + + +Adams Standards Track [Page 42] + +RFC 2025 SPKM October 1996 + + + -- from [RFC-1508] -- + + MechType ::= OBJECT IDENTIFIER + + InitialContextToken ::= [APPLICATION 0] IMPLICIT SEQUENCE { + thisMech MechType, + innerContextToken SPKMInnerContextToken + } -- when thisMech is SPKM-1 or SPKM-2 + + SPKMInnerContextToken ::= CHOICE { + req [0] SPKM-REQ, + rep-ti [1] SPKM-REP-TI, + rep-it [2] SPKM-REP-IT, + error [3] SPKM-ERROR, + mic [4] SPKM-MIC, + wrap [5] SPKM-WRAP, + del [6] SPKM-DEL + } + + + -- from [RFC-1510] -- + + AuthorizationData ::= SEQUENCE OF SEQUENCE { + ad-type INTEGER, + ad-data OCTET STRING + } + + +-- object identifier assignments -- + + md5-DES-CBC OBJECT IDENTIFIER ::= + {iso(1) identified-organization(3) dod(6) internet(1) security(5) + integrity(3) md5-DES-CBC(1)} + + sum64-DES-CBC OBJECT IDENTIFIER ::= + {iso(1) identified-organization(3) dod(6) internet(1) security(5) + integrity(3) sum64-DES-CBC(2)} + + spkm-1 OBJECT IDENTIFIER ::= + {iso(1) identified-organization(3) dod(6) internet(1) security(5) + mechanisms(5) spkm(1) spkm-1(1)} + + spkm-2 OBJECT IDENTIFIER ::= + {iso(1) identified-organization(3) dod(6) internet(1) security(5) + mechanisms(5) spkm(1) spkm-2(2)} + + +END + + + +Adams Standards Track [Page 43] + +RFC 2025 SPKM October 1996 + + +Appendix B: Imported Types + + This appendix contains, for completeness, the relevant ASN.1 types + imported from InformationFramework (1993), AuthenticationFramework + (1993), and [PKCS3]. + + AttributeType ::= OBJECT IDENTIFIER + AttributeValue ::= ANY + AttributeValueAssertion ::= SEQUENCE {AttributeType,AttributeValue} + RelativeDistinguishedName ::= SET OF AttributeValueAssertion + -- note that the 1993 InformationFramework module uses + -- different syntax for the above constructs + RDNSequence ::= SEQUENCE OF RelativeDistinguishedName + DistinguishedName ::= RDNSequence + Name ::= CHOICE { -- only one for now + rdnSequence RDNSequence + } + + Certificate ::= SEQUENCE { + certContents CertContents, + algID AlgorithmIdentifier, + sig BIT STRING + } -- sig holds the result of applying the signing procedure + -- specified in algId to the BER-encoded octet string which + -- results from applying the hashing procedure (also specified in + -- algId) to the DER-encoded octets of CertContents + + CertContents ::= SEQUENCE { + version [0] Version DEFAULT v1, + serialNumber CertificateSerialNumber, + signature AlgorithmIdentifier, + issuer Name, + validity Validity, + subject Name, + subjectPublicKeyInfo SubjectPublicKeyInfo, + issuerUID [1] IMPLICIT UID OPTIONAL, -- used in v2 only + subjectUID [2] IMPLICIT UID OPTIONAL -- used in v2 only + } + + Version ::= INTEGER {v1(0), v2(1)} + CertificateSerialNumber ::= INTEGER + UID ::= BIT STRING + + Validity ::= SEQUENCE { + notBefore UTCTime, + notAfter UTCTime + } + + + + +Adams Standards Track [Page 44] + +RFC 2025 SPKM October 1996 + + + SubjectPublicKeyInfo ::= SEQUENCE { + algorithm AlgorithmIdentifier, + subjectPublicKey BIT STRING + } + + CertificatePair ::= SEQUENCE { + forward [0] Certificate OPTIONAL, + reverse [1] Certificate OPTIONAL + } -- at least one of the pair shall be present + + CertificateList ::= SEQUENCE { + certListContents CertListContents, + algId AlgorithmIdentifier, + sig BIT STRING + } -- sig holds the result of applying the signing procedure + -- specified in algId to the BER-encoded octet string which + -- results from applying the hashing procedure (also specified in + -- algId) to the DER-encoded octets of CertListContents + + CertListContents ::= SEQUENCE { + signature AlgorithmIdentifier, + issuer Name, + thisUpdate UTCTime, + nextUpdate UTCTime OPTIONAL, + revokedCertificates SEQUENCE OF SEQUENCE { + userCertificate CertificateSerialNumber, + revocationDate UTCTime } OPTIONAL + } + + AlgorithmIdentifier ::= SEQUENCE { + algorithm OBJECT IDENTIFIER, + parameter ANY DEFINED BY algorithm OPTIONAL + } -- note that the 1993 AuthenticationFramework module uses + -- different syntax for this construct + + + + --from [PKCS3] (the parameter to be used with dhKeyAgreement) -- + + DHParameter ::= SEQUENCE { + prime INTEGER, -- p + base INTEGER, -- g + privateValueLength INTEGER OPTIONAL + } + + + + + + + +Adams Standards Track [Page 45] + diff --git a/doc/specifications/rfc2478.txt b/doc/specifications/rfc2478.txt new file mode 100644 index 00000000..83395577 --- /dev/null +++ b/doc/specifications/rfc2478.txt @@ -0,0 +1,1011 @@ + + + + + + +Network Working Group E. Baize +Request for Comments: 2478 D. Pinkas +Category: Standards Track Bull + December 1998 + + + The Simple and Protected GSS-API Negotiation Mechanism + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +1. ABSTRACT + + This document specifies a Security Negotiation Mechanism for the + Generic Security Service Application Program Interface (GSS-API) + which is described in [1]. + + The GSS-API provides a generic interface which can be layered atop + different security mechanisms such that if communicating peers + acquire GSS-API credentials for the same security mechanism, then a + security context may be established between them (subject to policy). + However, GSS-API doesn't prescribe the method by which GSS-API peers + can establish whether they have a common security mechanism. + + The Simple and Protected GSS-API Negotiation Mechanism defined here + is a pseudo-security mechanism, represented by the object identifier + iso.org.dod.internet.security.mechanism.snego (1.3.6.1.5.5.2) which + enables GSS-API peers to determine in-band whether their credentials + share common GSS-API security mechanism(s), and if so, to invoke + normal security context establishment for a selected common security + mechanism. This is most useful for applications that are based on + GSS-API implementations which support multiple security mechanisms. + + This allows to negotiate different security mechanisms, different + options within a given security mechanism or different options from + several security mechanisms. + + + + + + +Baize & Pinkas Standards Track [Page 1] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + + Once the common security mechanism is identified, the security + mechanism may also negotiate mechanism-specific options during its + context establishment. This will be inside the mechanism tokens, and + invisible to the SPNEGO protocol. + + The simple and protected GSS-API mechanism negotiation is based on + the following negotiation model : the initiator proposes one security + mechanism or an ordered list of security mechanisms, the target + either accepts the proposed security mechanism, or chooses one from + an offered set, or rejects the proposed value(s). The target then + informs the initiator of its choice. + + In its basic form this protocol requires an extra-round trip. Network + connection setup is a critical performance characteristic of any + network infrastructure and extra round trips over WAN links, packet + radio networks, etc. really make a difference. In order to avoid such + an extra round trip the initial security token of the preferred + mechanism for the initiator may be embedded in the initial token. If + the target preferred mechanism matches the initiator's preferred + mechanism, no additional round trips are incurred by using the + negotiation protocol. + + The simple and protected GSS-API mechanism negotiation provides a + technique to protect the negotiation that must be used when the + underlying mechanism selected by the target is capable of integrity + protection. + + When all the mechanisms proposed by the initiator support integrity + protection or when the selected mechanism supports integrity + protection, then the negotiation mechanism becomes protected since + this guarantees that the appropriate mechanism supported by both + peers has been selected. + + The Simple and Protected GSS-API Negotiation Mechanism uses the + concepts developed in the GSS-API specification [1]. The negotiation + data is encapsulated in context-level tokens. Therefore, callers of + the GSS-API do not need to be aware of the existence of the + negotiation tokens but only of the new pseudo-security mechanism. A + failure in the negotiation phase causes a major status code to be + returned: GSS_S_BAD_MECH. + + + + + + + + + + + +Baize & Pinkas Standards Track [Page 2] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + +2. NEGOTIATION MODEL + +2.1. Negotiation description + + The model for security mechanism negotiation reuses a subset of the + concepts specified in [2]. + + Each OID represents one GSS-API mechanism or one variant of it. + + - When one security mechanism is proposed by the initiator, it + represents the only security mechanism supported or selected + (when the additional APIs defined in the Annex A are used) by the + initiator. + + - When several security mechanisms are proposed by the initiator, + they represent a set of security mechanisms supported or selected + (when the additional APIs defined in the Annex A are used) by the + initiator. + + The first negotiation token sent by the initiator contains an ordered + list of mechanisms, a set of options (e.g. deleg, replay, conf flags) + that should be supported by the selected mechanism and optionally the + initial security token for the desired mechanism of the initiator + (i.e. the first of the list). + + The first negotiation token sent by the target contains the result of + the negotiation (accept_completed, accept_incomplete or reject) and, + in case of accept, the agreed security mechanism. It may also include + the response to the initial security token from the initiator, when + the first proposed mechanism of the initiator has been selected. When + the first mechanism is acceptable to the target,it should respond to + the initial security token for the desired mechanism of the initiator + when it is present. However, if this is not possible, the target can + simply ignore it and omit the responseToken from the first reply. + + Implementations that can piggyback the initial token will be rewarded + by faster connection setup. + + In case of a successful negotiation, the security mechanism + represents the value suitable for the target, and picked up from the + list offered by the initiator. The policy by which the target + chooses a mechanism is an implementation-specific local matter. In + the absence of other policy, the target should chose the first + mechanism in the list for which valid credentials are available. + + Once a mechanism has been selected, the tokens specific to the + selected mechanism are carried within the negotiation tokens (in the + mechToken for the initiator and in the responseToken for the target). + + + +Baize & Pinkas Standards Track [Page 3] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + +2.2. Negotiation procedure + + The negotiation procedure is summarised as follows: + + (a) the GSS-API initiator invokes GSS_Init_sec_context as normal, but + requests (either explicitly, with the negotiation mechanism, or + through accepting a default, when the default is the negotiation + mechanism) that the Simple and Protected GSS-API Negotiation + Mechanism be used; + + (b) the initiator GSS-API implementation emits a negotiation token + containing a list of supported security mechanisms for the + credentials used for this context establishment, and optionally + an initial security token for the first mechanism from that list + (i.e. the preferred mechanism), and indicates + GSS_S_CONTINUE_NEEDED status; + + (c) The GSS-API initiator sends the token to the target application; + + (d) The GSS-API target deposits the token through invoking + GSS_Accept_sec_context. The target GSS-API implementation emits a + negotiation token containing which if any of the proposed + mechanisms it supports (or has selected). + + If the mechanism selected by the target matches the preferred + mechanism identified by the initiator and the initiator provides a + mechToken, the negotiation token response may contain also an initial + security token from that mechanism. + + If the preferred mechanism is accepted, GSS_Accept_sec_context() + indicates GSS_S_COMPLETE when unilateral or mutual authentication has + been performed and involves a single token in either direction. + + If a proposed mechanism is accepted, and it was not the preferred + mechanism, or if the first negotiation token sent by the initiator + did not included a mechToken, then the negotiation token response + sent by the target may contain also a response token from that + mechanism which transmits mechanism-specific information (e.g. to + transmit a certificate). The initiator may ignore such an initial + token if it is not prepared to process it. + + If a proposed mechanism other than the preferred mechanism is + accepted, or the preferred mechanism is accepted but involves + multiple exchanges (e.g. challenge-response authentication), then + GSS_Accept_sec_context() indicates GSS_S_CONTINUE_NEEDED status. + + + + + + +Baize & Pinkas Standards Track [Page 4] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + + If the proposed mechanism(s) are rejected, GSS_Accept_sec_context() + indicates GSS_S_BAD_MECH status. The security context initialisation + has failed. + + (e) The GSS-API target returns the token to the initiator + application; + + (f) The GSS-API initiator deposits the token through invoking + GSS_Init_sec_context. + + GSS_Init_sec_context() may then indicate GSS_S_CONTINUE_NEEDED, + GSS_S_COMPLETE or GSS_S_BAD_MECH status. + + The GSS_S_BAD_MECH status is returned when the negotiation token + carries a reject result or when the negotiation token carries an + accept result and the mechanism selected by the target is not + included in the initial list sent by the initiator. + + The GSS_S_BAD_MIC status is returned when the selected mechanism + supports a MIC token but the MIC computed over the list of + mechanisms sent by the initiator is missing or incorrect. + + If the negotiation token carries a reject result, the context + establishment is impossible. For example, a rejection will occur + if the target doesn't support the initiator's proposed mechanism + type(s). Upon failure of the mechanism negotiation procedure, the + mech_type output parameter value is the negotiation mechanism + type. + + The GSS_S_CONTINUE_NEEDED status is returned when the negotiation + token carries an accept result and further tokens must be + transferred in order to complete context establishment for the + selected mechanism. In that case GSS_Init_sec_context() returns an + initial context token as output_token (with the selected + mechanism's context token encapsulated within that output_token). + + The initiator then sends the output_token to the target. The + security context initialisation is then continued according to the + standard GSS-API conventions for the selected mechanism, where the + tokens of the selected mechanism are encapsulated until the + GSS_S_COMPLETE is returned for both the initiator and the target. + When GSS_S_CONTINUE_NEEDED is returned, the mech_type output + parameter is not yet valid. + + When GSS_S_COMPLETE is returned, the mech_type output parameter + indicates the selected mechanism. When the final negotiation token + does not contain a MIC, the initiator GSS-API implementation must + check the returned/selected mechanism is on the originally + + + +Baize & Pinkas Standards Track [Page 5] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + + submitted list of mechanisms and also verify that the selected + mechanism is not able to support a MIC. When the final negotiation + token contains a MIC over the initial mechanisms list sent by the + initiator, the MIC must be verified. + + Note that the *_req_flag input parameters for context establishment + are relative to the selected mechanism, as are the *_state output + parameters. i.e., these parameters are not applicable to the + negotiation process per se. + + The initiator GSS-API calling application may need to know when the + negotiation exchanges were protected or not. For this, when + GSS_S_COMPLETE is returned, it can simply test the integ_avail flag. + When this flag is set it indicates that the negotiation was + protected. + + On receipt of a negotiation token on the target side, a GSS-API + implementation that does not support negotiation would indicate the + GSS_S_BAD_MECH status as if a particular basic security mechanism had + been requested but was not supported. + + When GSS_Acquire_cred is invoked with the negotiation mechanism as + desired_mechs, an implementation-specific default credential is used + to carry on the negotiation. A set of mechanisms as specified locally + by the system administrator is then available for negotiation. If + there is a desire for the caller to make its own choice, then an + additional API has to be used (see Appendix A). + +3. DATA ELEMENTS + +3.1. Mechanism Type + + MechType::= OBJECT IDENTIFIER + + mechType + Each security mechanism is as defined in [1]. + +3.2. Negotiation Tokens + + The syntax of the negotiation tokens follows the InitialContextToken + syntax defined in [1]. The security mechanism of the initial + negotiation token is identified by the Object Identifier + iso.org.dod.internet.security.mechanism.snego (1.3.6.1.5.5.2). + + + + + + + + +Baize & Pinkas Standards Track [Page 6] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + +3.2.1. Syntax + + This section specifies the syntax of the corresponding + "innerContextToken" field for the first token and subsequent + negotiation tokens. During the mechanism negociation, the + "innerContextToken" field contains the ASN.1 structure + "NegociationToken" given below, encoded using the DER encoding + conventions. + +NegotiationToken ::= CHOICE { + negTokenInit [0] NegTokenInit, + negTokenTarg [1] NegTokenTarg } + +MechTypeList ::= SEQUENCE OF MechType + +NegTokenInit ::= SEQUENCE { + mechTypes [0] MechTypeList OPTIONAL, + reqFlags [1] ContextFlags OPTIONAL, + mechToken [2] OCTET STRING OPTIONAL, + mechListMIC [3] OCTET STRING OPTIONAL + } + +ContextFlags ::= BIT STRING { + delegFlag (0), + mutualFlag (1), + replayFlag (2), + sequenceFlag (3), + anonFlag (4), + confFlag (5), + integFlag (6) +} + +negTokenInit + Negotiation token sent by the initiator to the target, which + contains, for the first token sent, one or more security mechanisms + supported by the initiator (as indicated in the field mechTypes) + and the service options (reqFlags) that are requested to establish + the context. The context flags should be filled in from the + req_flags parameter of init_sec_context(). + + The mechToken field is optional for the first token sent that all + target implementations would not have to support. However for those + targets that do support piggybacking the initial mechToken, an + optimistic negotiation response is possible. Otherwise the + mechToken is used to carry the tokens specific to the mechanism + selected. + + + + + +Baize & Pinkas Standards Track [Page 7] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + + The mechListMIC is an optional field. In the case that the chosen + mechanism supports integrity, the initiator may optionally include + a mechListMIC which is the result of a GetMIC of the MechTypes in + the initial NegTokenInit and return GSS_S_COMPLETE. + + When the chosen mechanism uses an odd number of messages, the final + mechanism token will be sent from the initiator to the acceptor. In + this case, there is a tradeoff between using the optimal number of + messages, or using an additional message from the acceptor to the + initiator in order to give the initiator assurance that no + modification of the initiator's mechanism list occurred. The + implementation can choose which tradeoff to make (see section 4.2.2 + for further details for the processing of that field). + +NegTokenTarg ::= SEQUENCE { + negResult [0] ENUMERATED { + accept_completed (0), + accept_incomplete (1), + reject (2) } OPTIONAL, + supportedMech [1] MechType OPTIONAL, + responseToken [2] OCTET STRING OPTIONAL, + mechListMIC [3] OCTET STRING OPTIONAL +} + +negTokenTarg + Negotiation token returned by the target to the initiator which + contains, for the first token returned, a global negotiation result + and the security mechanism selected (if any). + +negResult + The result accept_completed indicates that a context has been + successfully established, while the result accept_incomplete + indicates that additional token exchanges are needed. + + Note: For the case where (a) a single-token context setup is + used and (b) the preferred mechanism does not support the + integrity facility which would cause a mechListMIC to be + generated and enclosed, this feature allows to make a + difference between a mechToken sent by the initiator but not + processed by the target (accept_incomplete) and a mechToken + sent by the initiator and processed by the target + (accept_completed). + + For those targets that support piggybacking the initial mechToken, + an optimistic negotiation response is possible and includes in that + case a responseToken which may continue the authentication exchange + (e.g. when mutual authentication has been requested or when + unilateral authentication requires several round trips). Otherwise + + + +Baize & Pinkas Standards Track [Page 8] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + + the responseToken is used to carry the tokens specific to the + mechanism selected. For subsequent tokens (if any) returned by the + target, negResult, and supportedMech are not present. + + For the last token returned by the target, the mechListMIC, when + present, is a MIC computed over the MechTypes using the selected + mechanism. + +negResult + Result of the negotiation exchange, specified by the target. + + This can be either : + + accept_completed + The target accepts the preferred security mechanism, + and the context is established for the target or, + + accept_incomplete + The target accepts one of the proposed security + mechanisms and further exchanges are necessary, or, + + reject + The target rejects all the proposed security + mechanisms. + +supportedMech + This field has to be present when negResult is "accept_completed" + or "accept_incomplete". It is a choice from the mechanisms offered + by the initiator. + +responseToken + This field may be used either to transmit the response to the + mechToken when sent by the initiator and when the first mechanism + from the list has been selected by the target or to carry the + tokens specific to the selected security mechanism. + +mechListMIC + If the selected mechanism is capable of integrity protection, this + field must be present in the last message of the negotiation, + (i.e., when the underlying mechanism returns a non-empty token and + a major status of GSS_S_COMPLETE); it contains the result of a + GetMIC of the MechTypes field in the initial NegTokenInit. It + allows to verify that the list initially sent by the initiator has + been received unmodified by the target. + + + + + + + +Baize & Pinkas Standards Track [Page 9] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + +3.2.2. Processing of mechListMIC. + + If the mechanism selected by the negotiation does not support + integrity, then no mechListMIC is included, otherwise a mechListMIC + must be used and validated as indicated below. + + If the mechanism supports integrity and uses an even number of + messages, then the target must compute a MIC as described above, and + send this in the final NegTokenTarg along with the final mechToken. + The initiator when receiving the last token must require that the + mechListMIC field be present and valid. In the absence of a valid + mechListMIC, the negotiation must fail as if the last context + establishment token was invalid. + + In the case that the chosen mechanism supports integrity and uses an + odd number of messages, the final mechanism token will be sent from + the initiator to the target. In this case, there is a tradeoff + between using the optimal number of messages, or using an additional + message from the target to the initiator in order to give the + initiator assurance that no modification of the initiator's mechanism + list occurred. The implementation can choose which tradeoff to make. + + When generating the final NegTokenInit message, the NegTokenInit may + optionally include a mechListMIC which is the result of a GetMIC of + the MechTypes in the initial NegTokenInit and return GSS_S_COMPLETE. + The target must check the presence of the MIC computed over the + mechList sent in the initial NegTokenInit. Three cases may then be + considered: + + 1) If the mechListMIC is present and correct, then + GSS_S_COMPLETE is returned to the target with no token; the + context is established by the target. + + 2) If the mechListMIC is present but invalid, then the context + establishment must fail. An error major status code is + returned to the target. + + 3) If the mechListMIC is not included in the final NegTokenInit, + then GSS_S_COMPLETE must be returned to the target with a + token. This token must be a NegTokenTarg, with a MIC included + as described above, and no responseToken. The application will + then send this token back to the initiator, which must verify + that the mechListMIC field is present and valid. + + + + + + + + +Baize & Pinkas Standards Track [Page 10] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + + Note: If the MIC was originally sent by the initiator, but + thenafter deleted by an attacker, the target will send + back a token according to the description above, but the + initiator will be unable to process that returned token + and the context establishment must then fail. + +4. EXAMPLES : SECURITY MECHANISM NEGOTIATION + + Here are some examples of security mechanism negotiation between an + initiator (I) and a target (T). + +4.1. Initial steps + + (I) supports two security mechanism types (GSS-MECH1 and GSS-MECH2). + + (I) invokes GSS_Init_sec_context() with : + + Input + mech_type = OID for negotiation mechanism or NULL, if the + negotiation mechanism is the default mechanism. + + Output + major_status = GSS_S_CONTINUE_NEEDED + output_token = negTokenInit + + The negotiation token (negTokenInit) contains two security mechanisms + with : + mechType = GSS-MECH1 or + mechType = GSS-MECH2 + + (I) sends to (T) the negotiation token. + +4.2 Successful negotiation steps + + (T) supports GSS-MECH2 + (T) receives the negotiation token (negTokenInit) from (I) + (T) invokes GSS_Accept_sec_context() with : + + Input + input_token = negTokenInit + + Output + major_status = GSS_S_CONTINUE_NEEDED + output_token = negTokenTarg + + The negotiation token (negTokenTarg) contains : + negResult = accept (the negotiation result) + supportedMech : mechType = GSS-MECH2 + + + +Baize & Pinkas Standards Track [Page 11] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + + (T) returns the negotiation token (negTokenTarg) to (I) + (I) invokes GSS_Init_sec_context() with : + + Input + input_token = negTokenTarg + + Output + major_status = GSS_S_COMPLETE + output_token = initialContextToken (initial context token + for GSS-MECH2) + mech_type = GSS-MECH2 + + The subsequent steps are security mechanism specific, and work as + specified in [1]. The output tokens from the security mechanism are + encapsulated in a NegTokenTarg message (with the supportedMech field + omitted, and the mechListMIC included with the last token). + +4.3. Failed negotiation steps + + (T) supports GSS-MECH3. + (T) receives the negotiation token (negTokenInit) from (I) + (T) invokes GSS_Accept_sec_context() with : + + Input + input_token = negTokenInit + + Output + major_status = GSS_S_BAD_MECH + output_token = negTokenTarg + + The negotiation token (negTokenTarg) contains : + + negResult = reject (the negotiation result) + + (T) returns the negotiation token (negTokenTarg) to (I) + (I) invokes GSS_Init_sec_context() with : + + Input + input_token = negTokenTarg + + Output + major_status = GSS_S_BAD_MECH + + The security context establishment has failed. + + + + + + + +Baize & Pinkas Standards Track [Page 12] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + +4.4 Successful Negotiation with preferred mechanism info + + (I) supports two security mechanism types (GSS-MECH1 and GSS-MECH2). + + (I) invokes GSS_Init_sec_context() with : + + Input + mech_type = OID for negotiation mechanism or NULL, if the + negotiation mechanism is the default mechanism. + + Output + major_status = GSS_S_CONTINUE_NEEDED + output_token = negTokenInit + + The negotiation token (negTokenInit) contains two security mechanisms + with : + mechType = GSS-MECH1 or + mechType = GSS-MECH2 + + mechToken = output_token from GSS_Init_sec_context + ( first mechType) as described in [1] + + (I) sends to (T) the negotiation token. + + (T) supports GSS-MECH1. + (T) receives the negotiation token (negTokenInit) from (I) + (T) invokes GSS_Accept_sec_context() with : + + Input + input_token = negTokenInit + + Output + major_status = GSS_S_CONTINUE_NEEDED + output_token = negTokenTarg + + The negotiation token (negTokenTarg) contains : + negResult = accept (the negotiation result) + supportedMech : mechType = GSS-MECH1 + + mechToken = output_token from + GSS_Accept_sec_context(mechToken ) + + (T) returns the negotiation token (negTokenTarg) to (I) + (I) invokes GSS_Init_sec_context() with : + + Input + input_token = negTokenTarg + + + + +Baize & Pinkas Standards Track [Page 13] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + + Output + major_status = GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED as needed + output_token = ContextToken (initial or subsequent context token + for GSS-MECH1) + mech_type = GSS-MECH1 + + Specific implementations of the protocol can support the optimistic + negotiation by completing the security context establishment using the + agreed upon mechanism as described in [1]. As described above in + section 5.2, the output tokens from the security mechanisms are + encapsulated in a NegTokenTarg message (with the negResult and + supportedMech fields omitted, and the mechListMIC included with the + last token). + +5. SECURITY CONSIDERATIONS + + When the mechanism selected by the target from the list supplied by + the initiator supports integrity protection, then the negotiation is + protected. + + When one of the mechanisms proposed by the initiator does not support + integrity protection, then the negotiation is exposed to all threats + a non secured service is exposed. In particular, an active attacker + can force to use a security mechanism which is not the common + preferred one (when multiple security mechanisms are shared between + peers) but which is acceptable anyway to the target. + + In any case, the communicating peers may be exposed to the denial of + service threat. + +6. ACKNOWLEDGMENTS + + Acknowledgments are due to Stephen Farrell of SSE, Marc Horowitz of + Stonecast, John Linn of RSA Laboratories, Piers McMahon of Platinum + Technology, Tom Parker of ICL and Doug Rosenthal of EINet, for + reviewing earlier versions of this document and for providing useful + inputs. Acknowledgments are also due to Peter Brundrett of Microsoft + for his proposal for an optimistic negotiation, and for Bill + Sommerfeld of Epilogue Technology for his proposal for protecting the + negotiation. + + + + + + + + + + + +Baize & Pinkas Standards Track [Page 14] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + +APPENDIX A + + + GSS-API NEGOTIATION SUPPORT API + + In order to provide to a GSS-API caller (either the initiator or the + target or both) the ability to choose among the set of supported + mechanisms a reduced set of mechanisms for negotiation, two + additional APIs are defined: + + GSS_Get_neg_mechs() indicates the set of security mechanisms + available on the local system to the caller for negotiation. + + GSS_Set_neg_mechs() specifies the set of security mechanisms to be + used on the local system by the caller for negotiation. + +A.1. GSS_Set_neg_mechs call + + Input: + cred_handle CREDENTIAL HANDLE + - NULL specifies default credentials + mech_set SET OF OBJECT IDENTIFIER + + Outputs: + major_status INTEGER, + minor_status INTEGER, + + Return major_status codes : + GSS_S_COMPLETE indicates that the set of security mechanisms + available for negotiation has been set to mech_set. GSS_S_FAILURE + indicates that the requested operation could not be performed for + reasons unspecified at the GSS-API level. + + Allows callers to specify the set of security mechanisms that may be + negotiated with the credential identified by cred_handle. This call + is intended for support of specialised callers who need to restrict + the set of negotiable security mechanisms from the set of all + security mechanisms available to the caller (based on available + credentials). Note that if more than one mechanism is specified in + mech_set, the order in which those mechanisms are specified implies a + relative mechanism preference for the target. + + + + + + + + + + +Baize & Pinkas Standards Track [Page 15] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + +A.2. GSS_Get_neg_mechs call + + Input: + cred_handle CREDENTIAL HANDLE + - NULL specifies default credentials + + Outputs: + major_status INTEGER, + minor_status INTEGER, + mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes : + GSS_S_COMPLETE indicates that the set of security mechanisms + available for negotiation has been returned in + mech_option_set. + GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to determine the set of security mechanisms available + for negotiation with the credential identified by cred_handle. This + call is intended for support of specialised callers who need to + reduce the set of negotiable security mechanisms from the set of + supported security mechanisms available to the caller (based on + available credentials). + + Note: The GSS_Indicate_mechs() function indicates the full set of + mechanism types available on the local system. Since this call has no + input parameter, the returned set is not necessarily available for + all credentials. + +REFERENCES + + [1] Linn, J., "Generic Security Service Application Program + Interface", RFC 2078, January 1997. + + [2] Standard ECMA-206, "Association Context Management including + Security Context Management", December 1993. Available on + http://www.ecma.ch + + + + + + + + + + + + + +Baize & Pinkas Standards Track [Page 16] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + +AUTHORS' ADDRESSES + + Eric Baize + Bull - 300 Concord Road + Billerica, MA 01821 - USA + + Phone: +1 978 294 61 37 + Fax: +1 978 294 61 09 + EMail: Eric.Baize@bull.com + + + Denis Pinkas + Bull + Rue Jean-Jaures + BP 68 + 78340 Les Clayes-sous-Bois - FRANCE + + Phone: +33 1 30 80 34 87 + Fax: +33 1 30 80 33 21 + EMail: Denis.Pinkas@bull.net + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Baize & Pinkas Standards Track [Page 17] + +RFC 2478 GSS-API Negotiation Mechanism December 1998 + + +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. + + + + + + + + + + + + + + + + + + + + + + + + +Baize & Pinkas Standards Track [Page 18] + diff --git a/doc/specifications/rfc2479.txt b/doc/specifications/rfc2479.txt new file mode 100644 index 00000000..8413bcae --- /dev/null +++ b/doc/specifications/rfc2479.txt @@ -0,0 +1,3923 @@ + + + + + + +Network Working Group C. Adams +Request for Comments: 2479 Entrust Technologies +Category: Informational December 1998 + + + Independent Data Unit Protection Generic Security Service + Application Program Interface (IDUP-GSS-API) + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +ABSTRACT + + The IDUP-GSS-API extends the GSS-API [RFC-2078] for applications + requiring protection of a generic data unit (such as a file or + message) in a way which is independent of the protection of any other + data unit and independent of any concurrent contact with designated + "receivers" of the data unit. Thus, it is suitable for applications + such as secure electronic mail where data needs to be protected + without any on-line connection with the intended recipient(s) of that + data. The protection offered by IDUP includes services such as data + origin authentication with data integrity, data confidentiality with + data integrity, and support for non-repudiation services. Subsequent + to being protected, the data unit can be transferred to the + recipient(s) - or to an archive - perhaps to be processed + ("unprotected") only days or years later. + + Throughout the remainder of this document, the "unit" of data + described in the above paragraph will be referred to as an IDU + (Independent Data Unit). The IDU can be of any size (the application + may, if it wishes, split the IDU into pieces and have the protection + computed a piece at a time, but the resulting protection token + applies to the entire IDU). However, the primary characteristic of + an IDU is that it represents a stand-alone unit of data whose + protection is entirely independent of any other unit of data. If an + application protects several IDUs and sends them all to a single + receiver, the IDUs may be unprotected by that receiver in any order + over any time span; no logical connection of any kind is implied by + the protection process itself. + + + + + +Adams Informational [Page 1] + +RFC 2479 IDUP-GSS-API December 1998 + + + As with RFC-2078, this IDUP-GSS-API definition provides security + services to callers in a generic fashion, supportable with a range of + underlying mechanisms and technologies and hence allowing source- + level portability of applications to different environments. This + specification defines IDUP-GSS-API services and primitives at a level + independent of underlying mechanism and programming language + environment, and is to be complemented by other, related + specifications: + + - documents defining specific parameter bindings for particular + language environments; + - documents defining token formats, protocols, and procedures to + be implemented in order to realize IDUP-GSS-API services atop + particular security mechanisms. + +TABLE OF CONTENTS + + 1. IDUP-GSS-API Characteristics and Concepts .................. 3 + 1.1. IDUP-GSS-API Constructs .................................. 5 + 1.1.1. Credentials ............................................ 5 + 1.1.2. Tokens ................................................. 5 + 1.1.3. Security Environment ................................... 6 + 1.1.4. Mechanism Types ........................................ 6 + 1.1.5. Naming ................................................. 6 + 1.1.6. Channel Bindings ....................................... 6 + 1.2. IDUP-GSS-API Features and Issues ......................... 6 + 1.2.1. Status Reporting ....................................... 6 + 1.2.2. Per-IDU Security Service Availability .................. 9 + 1.2.3. Per-IDU Replay Detection and Sequencing ................ 9 + 1.2.4. Quality of Protection .................................. 9 + 1.2.5. The Provision of Time .................................. 12 + 2. Interface Descriptions ..................................... 13 + 2.1. Credential management calls .............................. 14 + 2.1.1. Relationship to GSS-API ................................ 14 + 2.2. Environment-level calls .................................. 15 + 2.2.1. Relationship to GSS-API ................................ 15 + 2.2.2. IDUP_Establish_Env call ................................ 15 + 2.2.3. IDUP_Abolish_Env call .................................. 19 + 2.2.4. IDUP_Inquire_Env call .................................. 19 + 2.3. Per-IDU protection/unprotection calls .................... 20 + 2.3.1. Relationship to GSS-API ................................ 20 + 2.3.2. The "SE" Calls ......................................... 21 + 2.3.3. The "EV" Calls ......................................... 27 + 2.3.4. The "GP" Calls ......................................... 36 + 2.4. Special-Purpose calls .................................... 47 + 2.4.1. Relationship to GSS-API ................................ 47 + 2.4.2. IDUP_Form_Complete_PIDU ................................ 48 + 2.5. Support calls ............................................ 49 + + + +Adams Informational [Page 2] + +RFC 2479 IDUP-GSS-API December 1998 + + + 2.5.1. Relationship to GSS-API ................................ 49 + 2.5.2. IDUP_Acquire_Cred_With_Auth ............................ 49 + 2.5.3. IDUP_Get_Token_Details ................................. 50 + 2.5.4. IDUP_Get_Policy_Info ................................... 53 + 2.5.5. IDUP_Cancel_Multibuffer_Op ............................. 55 + 3. Related Activities ......................................... 55 + 4. Acknowledgments ............................................ 56 + 5. Security Considerations .................................... 56 + 6. References ........................................... 56 + 7. Author's Address ........................................... 56 + Appendix A Mechanism-Independent Token Format ................. 57 + Appendix B Examples of IDUP Use ............................... 58 + Full Copyright Statement ....................................... 70 + +1. IDUP-GSS-API Characteristics and Concepts + + The paradigm within which IDUP-GSS-API operates is as follows. An + IDUP-GSS-API caller is any application that works with IDUs, calling + on IDUP-GSS-API in order to protect its IDUs with services such as + data origin authentication with integrity (DOA), confidentiality with + integrity (CONF), and/or support for non-repudiation (e.g., evidence + generation, where "evidence" is information that either by itself, or + when used in conjunction with other information, is used to establish + proof about an event or action (note: the evidence itself does not + necessarily prove truth or existence of something, but contributes to + establish proof) -- see [ISO/IEC] for fuller discussion regarding + evidence and its role in various types of non-repudiation). An + IDUP-GSS-API caller passes an IDU to, and accepts a token from, its + local IDUP-GSS-API implementation, transferring the resulting + protected IDU (P-IDU) to a peer or to any storage medium. When a P- + IDU is to be "unprotected", it is passed to an IDUP-GSS-API + implementation for processing. The security services available + through IDUP-GSS-API in this fashion are implementable over a range + of underlying mechanisms based on secret-key and/or public-key + cryptographic technologies. + + During the protection operation, the input IDU buffers may be + modified (for example, the data may be encrypted or encoded in some + way) or may remain unchanged. In any case, the result is termed a + "M-IDU" (Modified IDU) in order to distinguish it from the original + IDU. Depending on the desire of the calling application and the + capabilities of the underlying IDUP mechanism, the output produced by + the protection processing may or may not encapsulate the M-IDU. Thus, + the P-IDU may be the contents of a single output parameter (if + encapsulation is done) or may be the logical concatenation of an + unencapsulated token parameter and a M-IDU parameter (if + encapsulation is not done). In the latter case, the protecting + application may choose whatever method it wishes to concatenate or + + + +Adams Informational [Page 3] + +RFC 2479 IDUP-GSS-API December 1998 + + + combine the unencapsulated token and the M-IDU into a P-IDU, provided + the unprotecting application knows how to de-couple the P-IDU back + into its component parts prior to calling the IDUP unprotection set + of functions. + + It is expected that any output buffer returned by IDUP (i.e., P-IDU + or portion thereof) is ready for immediate transmission to the + intended receiver(s) by the calling application, if this is desired. + In other words, an application wishing to transmit data buffers as + they appear from IDUP should not be unduly restricted from doing so + by the underlying mechanism. + + The IDUP-GSS-API separates the operation of initializing a security + environment (the IDUP_Establish_Env() call) from the operations of + providing per-IDU protection, for IDUs subsequently protected in + conjunction with that environment. Per-IDU protection and + unprotection calls provide DOA, CONF, evidence, and other services, + as requested by the calling application and as supported by the + underlying mechanism. + + The following paragraphs provide an example illustrating the + dataflows involved in the use of the IDUP-GSS-API by the sender and + receiver of a P-IDU in a mechanism-independent fashion. The example + assumes that credential acquisition has already been completed by + both sides. Furthermore, the example does not cover all possible + options available in the protection/unprotection calls. + + The sender first calls IDUP_Establish_Env() to establish a + security environment. Then, for the IDU to be protected the + sender calls the appropriate protection calls (SE, EV, or GP) to + perform the IDU protection. The resulting P-IDU, which may + (depending on whether or not encapsulation was chosen/available) + be either the token itself or the logical concatenation of the + token and the M-IDU, is now ready to be sent to the target. The + sender then calls IDUP_Abolish_Env() to flush all environment- + specific information. + + The receiver first calls IDUP_Establish_Env() to establish a + security environment in order to unprotect the P-IDU. Then, for + the received P-IDU the receiver calls the appropriate unprotection + calls (SE, EV, or GP (known a priori, or possibly determined + through the use of the IDUP_Get_token_details call)) to perform + the P-IDU unprotection. The receiver then calls + IDUP_Abolish_Env() to flush all environment-specific information. + + It is important to note that absolutely no synchronization is implied + or expected between the data buffer size used by the sender as input + to the protection calls, the data buffer size used by the receiver as + + + +Adams Informational [Page 4] + +RFC 2479 IDUP-GSS-API December 1998 + + + input to the unprotection calls, and the block sizes required by the + underlying protection algorithms (integrity and confidentiality). All + these sizes are meant to be independent; furthermore, the data buffer + sizes used for the protection and unprotection calls are purely a + function of the local environment where the calls are made. + + The IDUP-GSS-API design assumes and addresses several basic goals, + including the following. + + Mechanism independence: The IDUP-GSS-API defines an interface to + cryptographically implemented security services at a generic level + which is independent of particular underlying mechanisms. For + example, IDUP-GSS-API-provided services can be implemented by + secret-key technologies or public-key approaches. + + Protocol environment independence: The IDUP-GSS-API is independent + of the communications protocol suites which may be used to + transfer P-IDUs, permitting use in a broad range of protocol + environments. + + Protocol association independence: The IDUP-GSS-API's security + environment construct has nothing whatever to do with + communications protocol association constructs, so that IDUP-GSS- + API services can be invoked by applications, wholly independent of + protocol associations. + + Suitability for a range of implementation placements: IDUP-GSS-API + clients are not constrained to reside within any Trusted Computing + Base (TCB) perimeter defined on a system where the IDUP-GSS-API is + implemented; security services are specified in a manner suitable + for both intra-TCB and extra-TCB callers. + +1.1. IDUP-GSS-API Constructs + + This section describes the basic elements comprising the IDUP-GSS- + API. + +1.1.1. Credentials + + Credentials in IDUP-GSS-API are to be understood and used as + described in GSS-API [RFC-2078]. + +1.1.2. Tokens + + Tokens in IDUP-GSS-API are to be understood and used as described in + GSS-API [RFC-2078] with the exception that there are no context-level + tokens generated by IDUP-GSS-API. The IDUP-GSS-API token may + (depending on the underlying mechanism) encapsulate the M-IDU or may + + + +Adams Informational [Page 5] + +RFC 2479 IDUP-GSS-API December 1998 + + + be logically concatenated with the M-IDU prior to transfer to a + target; furthermore, for some evidence services the token may be sent + independently of any other data transfer. + +1.1.3. Security Environment + + The "security environment" in IDUP-GSS-API is entirely different from + the concept of security contexts used in GSS-API [RFC-2078]. Here, a + security environment exists within a calling application (that is, it + is purely local to the caller) for the purpose of protecting or + unprotecting one or more IDUs using a particular caller credential or + set of credentials. In GSS-API, on the other hand, a security + context exists between peers (the initiator and the target) for the + purpose of protecting, in real time, the data that is exchanged + between them. Although they are different concepts, the env_handle + in IDUP-GSS-API is similar to the context_handle in GSS-API in that + it is a convenient way of tying together the entire process of + protecting or unprotecting one or more IDUs using a particular + underlying mechanism. As with the GSS-API security contexts, a + caller can initiate and maintain multiple environments using the same + or different credentials. + +1.1.4. Mechanism Types + + Mechanism types in IDUP-GSS-API are to be understood and used as + described in GSS-API [RFC-2078]. + +1.1.5. Naming + + Naming in IDUP-GSS-API is to be understood and used as described in + GSS-API [RFC-2078]. + +1.1.6. Channel Bindings + + The concept of channel bindings discussed in GSS-API [RFC-2078] is + not relevant to the IDUP-GSS-API. + +1.2. IDUP-GSS-API Features and Issues + + This section describes aspects of IDUP-GSS-API operations and of the + security services which the IDUP-GSS-API provides. It also provides + commentary on design issues. + +1.2.1. Status Reporting + + Status reporting in IDUP-GSS-API is to be understood and used as + described in GSS-API [RFC-2078], with the addition of a number of + IDUP-specific status codes. Descriptions of the major_status codes + + + +Adams Informational [Page 6] + +RFC 2479 IDUP-GSS-API December 1998 + + + used in IDUP are provided in Table 1. Codes that are informatory + (i.e., that do not cause the requested operation to fail) are + indicated with the symbol "(I)". + + As with GSS-API, minor_status codes, which provide more detailed + status information than major_status codes, and which may include + status codes specific to the underlying security mechanism, are not + specified in this document. + + Table 1: IDUP-GSS-API Major Status Codes + + GSS_S_BAD_MECH indicates that a mech_type unsupported by the + IDUP_GSS-API implementation was requested, causing the environment + establishment operation to fail. + + GSS_S_BAD_QOP indicates that the provided qop_alg value is not + recognized or supported for the environment. + + GSS_S_BAD_MIC indicates that the received P-IDU contains an + incorrect integrity field (e.g., signature or MAC) for the data. + + GSS_S_COMPLETE indicates that the requested operation was + successful. + + GSS_S_CREDENTIALS_EXPIRED indicates that the credentials + associated with this operation have expired, so that the requested + operation cannot be performed. + + 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_DEFECTIVE_TOKEN indicates that consistency checks performed + on the received P-IDU failed, preventing further processing from + being performed. + + GSS_S_FAILURE indicates that the requested operation could not be + accomplished for reasons unspecified at the IDUP-GSS-API level, + and that no interface-defined recovery action is available. + + 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. + + IDUP_S_BAD_DOA_KEY indicates that the key used to provide IDU data + origin auth. / integ. has either expired or been revoked. + + + + +Adams Informational [Page 7] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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). + + IDUP_S_BAD_KE_KEY indicates that the key used to establish a key + for confidentiality purposes between originator and target has + either expired or been revoked. + + IDUP_S_BAD_TARG_INFO indicates that the full set of supplied + information regarding the target(s) is invalid or is insufficient + for the protection of an IDU, so P-IDU cannot be created. + + IDUP_S_DEFECTIVE_VERIF indicates that consistency checks performed + on Service_Verification_Info failed, preventing further processing + from being performed with that parameter. + + IDUP_S_ENCAPSULATION_UNAVAIL (I) indicates that the underlying + mechanism does not support encapsulation of the M-IDU into the + token. + + IDUP_S_INAPPROPRIATE_CRED indicates that the credentials supplied + do not contain the information necessary for P-IDU unprotection. + + IDUP_S_INCOMPLETE (I) indicates that the unprotection of the P-IDU + is not yet complete (i.e., a determination cannot yet be made on + the validity of the P-IDU). The application should call + IDUP_Form_Complete_PIDU and then should call this function again + with the complete P-IDU. + + IDUP_S_INCONSISTENT_PARAMS indicates that the supplied parameters + are inconsistent (e.g., only one or the other of two parameters + may be supplied, but both have been input). + + IDUP_S_MORE_OUTBUFFER_NEEDED (I) indicates that the output buffer + supplied is too small to hold the generated data. The application + should continue calling this routine (until GSS_S_COMPLETE is + returned) in order to get all remaining output data. + + IDUP_S_MORE_PIDU_NEEDED (I) indicates that not enough of the P-IDU + has been input yet for the completion of StartUnprotect. The + application should call this routine again with another buffer of + P-IDU in partial(initial)_pidu_buffer. + + IDUP_S_NO_ENV indicates that no valid environment was recognized + for the env_handle provided. + + + + + +Adams Informational [Page 8] + +RFC 2479 IDUP-GSS-API December 1998 + + + IDUP_S_NO_MATCH indicates that Service_Verification_Info (or + evidence_check) and the P-IDU to be verified do not match. + + IDUP_S_REQ_TIME_SERVICE_UNAVAIL indicates that the time service + requested (TTIME or UTIME) is not available in the environment. + + IDUP_S_SERVICE_UNAVAIL indicates that the underlying mechanism + does not support the service requested. + + IDUP_S_SERV_VERIF_INFO_NEEDED (I) indicates that the + Service_Verification_Info parameter bundle must be input in order + for service verification to proceed. The output parameter + service_verification_info_id contains an identifier which may be + used by the calling application to locate the necessary + information. + + IDUP_S_UNKNOWN_OPER_ID indicates that the input prot_oper_id value + is not recognized or supported in the underlying mechanism. + +1.2.2. Per-IDU Security Service Availability + + Per-IDU security service availability in IDUP-GSS-API is to be + understood and used as described in GSS-API [RFC-2078], with the + exception that combinations of services requested by the calling + application and supported by the underlying mechanism may be applied + simultaneously to any IDU (true for both the SE and the EV calls, but + true in the fullest sense for the GP calls). + + GSS-API callers desiring per-message security services should check + the relevant service OBJECT IDs at environment establishment time to + ensure that what is available in the established environment is + suitable for their security needs. + +1.2.3. Per-IDU Replay Detection and Sequencing + + The concept of per-IDU replay detection and sequencing discussed in + GSS-API [RFC-2078] is not relevant to the IDUP-GSS-API. + +1.2.4. Quality of Protection + + The concept of QOP control in IDUP-GSS-API is to be understood + essentially as described in GSS-API [RFC-2078]. However, the actual + description and use of the QOP parameter is given as follows. + + The qop_algs parameter for IDUP is defined to be a 32-bit unsigned + integer with the following bit-field assignments: + + + + + +Adams Informational [Page 9] + +RFC 2479 IDUP-GSS-API December 1998 + + + 31 (MSB) (LSB) 0 + ---------------------------------------------- + | U(19) | TS(5) | IA(4) | MA(4) | + ---------------------------------------------- + + where + + U is a 19-bit Unspecified field (available for future + use/expansion) -- must be set to zero; + + TS is a 5-bit Type Specifier (a semantic qualifier whose value + specifies the type of algorithm which may be used to protect the + corresponding IDU -- see below for details); + + IA is a 4-bit field enumerating Implementation-specific + Algorithms; and + + MA is a 4-bit field enumerating Mechanism-defined Algorithms. + + The interpretation of the qop_algs parameter is as follows. The MA + field is examined first. If it is non-zero then the algorithm used + to protect the IDU is the mechanism-specified algorithm corresponding + to that integer value. + + If MA is zero then IA is examined. If this field value is non-zero + then the algorithm used to protect the IDU is the implementation- + specified algorithm corresponding to that integer value. Note that + use of this field may hinder portability since a particular value may + specify one algorithm in one implementation of the mechanism and may + not be supported or may specify a completely different algorithm in + another implementation of the mechanism. + + Finally, if both MA and IA are zero then TS is examined. A value of + zero for TS specifies the default algorithm for the established + mechanism. A non-zero value for TS corresponds to a particular + algorithm qualifier and selects any algorithm from the mechanism + specification which satisfies that qualifier (which actual algorithm + is selected is an implementation choice; the calling application need + not be aware of the choice made). + + The following TS values (i.e., algorithm qualifiers) are specified; + other values may be added in the future. + + + + + + + + + +Adams Informational [Page 10] + +RFC 2479 IDUP-GSS-API December 1998 + + + When qop_algs is used to select a confidentiality algorithm: + + 00000 (0) = default confidentiality algorithm + 00001 (1) = IDUP_SYM_ALG_STRENGTH_STRONG + 00010 (2) = IDUP_SYM_ALG_STRENGTH_MEDIUM + 00011 (3) = IDUP_SYM_ALG_STRENGTH_WEAK + 11111 (31) = IDUP_NO_CONFIDENTIALITY + + When qop_algs is used to select a DOA/integrity algorithm: + + 00000 (0) = default integrity algorithm + 00001 (1) = IDUP_INT_ALG_DIG_SIGNATURE + (integrity provided through a digital signature) + 00010 (2) = IDUP_INT_ALG_NON_DIG_SIGNATURE + (integrity without a dig. sig. (e.g., with a MAC)) + 11111 (31) = IDUP_NO_INTEGRITY + + Clearly, qualifiers such as strong, medium, and weak are debatable + and likely to change with time, but for the purposes of this version + of the specification we define these terms as follows. A + confidentiality algorithm is "weak" if the effective key length of + the cipher is 40 bits or less; it is "medium-strength" if the + effective key length is strictly between 40 and 80 bits; and it is + "strong" if the effective key length is 80 bits or greater. + ("Effective key length" describes the computational effort required + to break a cipher using the best-known cryptanalytic attack against + that cipher.) + + A five-bit TS field allows up to 30 qualifiers for each of + confidentiality and integrity (since "0" is reserved for "default" + and "31" is reserved for "none", as shown above). This document + specifies three for confidentiality and two for integrity, leaving a + lot of room for future specification. Suggestions of qualifiers such + as "fast", "medium-speed", and "slow" have been made, but such terms + are difficult to quantify (and in any case are platform- and + processor-dependent), and so have been left out of this initial + specification. The intention is that the TS terms be quantitative, + environment-independent qualifiers of algorithms, as much as this is + possible. + + Use of the qop_algs parameter as defined above is ultimately meant to + be as follows. + + - TS values are specified at the IDUP-GSS-API level and are + therefore portable across mechanisms. Applications which know + nothing about algorithms are still able to choose "quality" of + protection for their message tokens. + + + + +Adams Informational [Page 11] + +RFC 2479 IDUP-GSS-API December 1998 + + + - MA values are specified at the mechanism level and are therefore + portable across implementations of a mechanism. + + - IA values are specified at the implementation level (in user + documentation, for example) and are therefore typically non- + portable. An application which is aware of its own mechanism + implementation and the mechanism implementation of its intended + P-IDU recipient, however, is free to use these values since they + will be perfectly valid and meaningful for protecting IDUs between + those entities. + + The receiver of a P-IDU must pass back to its calling application (in + IDUP_Start_Unprotect()) a qop_algs parameter with all relevant fields + set. For example, if triple-DES has been specified by a mechanism as + algorithm 8, then a receiver of a triple-DES-protected P-IDU must + pass to its application (TS=1, IA=0, MA=8). In this way, the + application is free to read whatever part of the qop_algs parameter + it understands (TS or IA/MA). + +1.2.5. The Provision of Time + + IDUP mechanisms should make provision in their protocols for the + carrying of time information from originator to target(s). That is, + a target (a legitimate recipient) should get some indication during + unprotection regarding the time at which the protection operation + took place. This is particularly important if the mechanism offers + non-repudiation services because in some cases evidence verification + may only be achievable if the time at which the evidence was + generated is known. + + Depending upon the platform and resources available to the + implementation, an IDUP environment may have access to a source of + trusted (secure) time, untrusted (local) time, both kinds of time, or + no time. OBJECT IDs indicating such availability are returned by the + IDUP_Establish_Env() call. When starting a protection operation, an + application may specify which time services it wishes to have applied + to the IDU. Similarly, for unprotection, an application may specify + which kind of time (if any) to consult when the validity of the P-IDU + is to be established. Specifying both kinds of time is interpreted + to mean that the calling application does not care which kind of time + is used. + + The IDUP calls which use a time parameter specify the type of that + parameter to be INTEGER. This INTEGER is defined in all cases to be + the number of seconds which have elapsed since midnight, January 1, + 1970, coordinated universal time. + + + + + +Adams Informational [Page 12] + +RFC 2479 IDUP-GSS-API December 1998 + + +2. Interface Descriptions + + This section describes the IDUP-GSS-API's operational interface, + dividing the set of calls offered into five groups. Credential + management calls are related to the acquisition and release of + credentials by API callers. Environment-level calls are related to + the management of the security environment by an API caller. Per-IDU + calls are related to the protection or unprotection of individual + IDUs in established security environments. Special-purpose calls + deal with unusual or auxiliary evidence generation/verification + requirements. Support calls provide extra functions useful to IDUP- + GSS-API callers. Table 2 groups and summarizes the calls in tabular + fashion. + + Table 2: IDUP-GSS-API Calls + + CREDENTIAL MANAGEMENT + (see the calls given in Section 2.1 of GSS-API [RFC-2078]) + + ENVIRONMENT-LEVEL CALLS + IDUP_Establish_Env + IDUP_Abolish_Env + IDUP_Inquire_Env + + PER-IDU CALLS + SE (SIGN,ENCRYPT) CALLS + IDUP_SE_SingleBuffer_Protect + IDUP_SE_SingleBuffer_Unprotect + IDUP_SE_MultiBuffer_StartProtect + IDUP_SE_MultiBuffer_EndProtect + IDUP_SE_MultiBuffer_StartUnprotect + IDUP_SE_MultiBuffer_EndUnprotect + IDUP_SE_Process_Buffer + EV (EVIDENCE) CALLS + IDUP_EV_SingleBuffer_Generate + IDUP_EV_SingleBuffer_Verify + IDUP_EV_MultiBuffer_StartGenerate + IDUP_EV_MultiBuffer_EndGenerate + IDUP_EV_MultiBuffer_StartVerify + IDUP_EV_MultiBuffer_EndVerify + IDUP_EV_Process_Buffer + GP (GENERAL PROTECTION) CALLS + IDUP_Start_Protect + IDUP_Protect + IDUP_End_Protect + IDUP_Start_Unprotect + IDUP_Unprotect + IDUP_End_Unprotect + + + +Adams Informational [Page 13] + +RFC 2479 IDUP-GSS-API December 1998 + + + SPECIAL-PURPOSE CALLS (might not be supported by all mechanisms) + IDUP_Form_Complete_PIDU + + SUPPORT CALLS + IDUP_Acquire_cred_with_auth + IDUP_Get_Token_Details + IDUP_Get_Policy_Info + IDUP_Cancel_Multibuffer_Op + (see also the calls given in Section 2.4 of GSS-API [RFC-2078]) + + In terms of conformance to this specification, IDUP-GSS-API + implementations must support the credential management calls, the + environment-level calls, some subset of the per-IDU calls, and the + support calls (except where explicitly stated otherwise in Section + 2.5). The subset of per-IDU calls supported will depend upon the + underlying mechanisms supported and will typically be the SE calls, + or the EV calls, or both. As stated in Section 2.3.2.1, + implementations are encouraged to support the more powerful GP calls + to anticipate the future needs of applications developers, but this + is not required for conformance. + +2.1. Credential management calls + +2.1.1. Relationship to GSS-API + + Credential management in IDUP-GSS-API is to be understood and used as + described in GSS-API [RFC-2078]. The calls given in Section 2.1 of + GSS-API (including all associated parameters) are unchanged, although + the interpretation of the cred_usage parameter in the GSS-API calls + for IDUP purposes is as follows. + + ENCRYPT_ONLY 8 + DECRYPT_ONLY 16 + SIGN_ONLY 32 + VERIFY_ONLY 64 + + The values above may be logically OR'ed together in any desired + combination to restrict credential usage (where OR'ing all values + results in NO_RESTRICTION). Future possible values for this + parameter are for further study. + + The call IDUP_Acquire_cred_with_auth has been added as a support call + in this specification to permit authenticated credential acquirement; + see Section 2.5.2 for details. + + + + + + + +Adams Informational [Page 14] + +RFC 2479 IDUP-GSS-API December 1998 + + +2.2. Environment-level calls + + This group of calls is devoted to the establishment and management of + an environment for the purpose of IDU protection and unprotection. + Before protecting or unprotecting any IDU, an application must call + IDUP_Establish_Env() to initialize environment information and select + the underlying IDUP-GSS mechanism to be used. A series of protection + or unprotection calls is made to process each IDU, the protection + calls resulting in a P-IDU for each. Finally, IDUP_Abolish_Env() is + called to flush all environment information. + + Semantically, acquiring credentials and establishing an environment + is (in many cases) analogous to logging in to a system -- it + authenticates a local user to the system and gives that user access + to a set of operations which can be performed. + +2.2.1. Relationship to GSS-API + + The set of calls described in this section is used in place of the + calls described in Section 2.2 of GSS-API [RFC-2078], since those + calls are specific to a session-oriented environment. + +2.2.2. IDUP_Establish_Env call + + Inputs: o claimant_cred_handle CREDENTIAL HANDLE, + -- NULL parameter specifies "use default" + + o req_mech_type OBJECT IDENTIFIER, + -- NULL parameter specifies "use default" + o req_environmentPolicies EnvironmentPolicies, + -- NULL parameter specifies "use default" + o req_services SET OF OBJECT IDENTIFIER, + -- GSS_C_NO_OID_SET requests full set of services available + -- for req_mech_type + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o env_handle ENVIRONMENT HANDLE, + o actual_mech_type OBJECT IDENTIFIER, + -- actual mechanism always indicated, never NULL + o actual_environmentPolicies EnvironmentPolicies, + -- actual values always indicated, never NULL + o ret_services SET OF OBJECT IDENTIFIER, + + Return major_status codes: + o GSS_S_COMPLETE + -- environment-level information was successfully initialized, + + + +Adams Informational [Page 15] + +RFC 2479 IDUP-GSS-API December 1998 + + + -- and IDU / P-IDU processing can begin. + o GSS_S_DEFECTIVE_CREDENTIAL + o GSS_S_NO_CRED + o GSS_S_CREDENTIALS_EXPIRED + -- the credentials provided through claimant_cred_handle are + -- no longer valid, so environment cannot be established. + o GSS_S_BAD_MECH + o GSS_S_FAILURE + + The following structures are defined to facilitate environment policy + input and output: + + EnvironmentPolicies ::= SEQUENCE { + confPolicy [0] PolicyAndTime OPTIONAL, + -- NULL parameter (on input) specifies "use default" + integPolicy [1] PolicyAndTime OPTIONAL, + -- NULL parameter (on input) specifies "use default" + evidencePolicy [2] PolicyAndTime OPTIONAL } + -- NULL parameter (on input) specifies "use default" + + PolicyAndTime ::= SEQUENCE { + policy OBJECT IDENTIFIER, + -- this environment-level policy identifier is separate from + -- the policy provisions connected with credentials, if they exist + time INTEGER + -- on input: the policy rules available at the specified time + -- on output: the time at which the policy rules came into effect + -- (defined to be the number of seconds elapsed since midnight, + -- January 1, 1970, coordinated universal time) + endTime INTEGER OPTIONAL } + -- on input: unused + -- on output: the expiration time of the given policy rules + + This routine is used by an application which protects or unprotects + IDUs. Using information in the credentials structure referenced by + claimant_cred_handle, IDUP_Establish_Env() initializes the data + structures required to protect or unprotect IDUs. The + claimant_cred_handle, if non-NULL, must correspond to a valid + credentials structure. + + This routine returns an env_handle for all future references to this + environment; when protection, unprotection, or IDUP_Abolish_Env() + calls are made, this handle value will be used as the input + env_handle argument. It is the caller's responsibility to establish + a communications path to the intended recipients of the P-IDU, and to + transmit the P-IDU to those recipients over that path. This may + occur subsequent to the IDUP_Abolish_Env() call. + + + + +Adams Informational [Page 16] + +RFC 2479 IDUP-GSS-API December 1998 + + + The req_services parameter may be used by the calling application to + request that data origin authentication with integrity, + confidentiality with integrity, evidence generation, and/or evidence + verification services be available in the established environment. + Requests can also be made for "trusted" or "untrusted" time services. + Requesting evidence generation or verification indicates that the + calling application may wish to generate or verify evidence + information for non-repudiation purposes (note: an IDU protector may + request that a flag be inserted into a P-IDU asking a recipient to + provide an evidence of the type "non-repudiation of delivery"; + however, the IDUP-GSS-API cannot by itself guarantee that the + evidence will be sent because there is no way to force a target to + send an evidence_token back to the IDU protector). + + Not all features will be available in all underlying mech_types; the + returned value of ret_services indicates, as a function of mech_type + processing capabilities and the initiator-provided input OBJECT IDs, + the set of features which will be available in the environment. The + value of this parameter is undefined unless the routine's + major_status indicates COMPLETE. Failure to provide the precise set + of services desired by the caller does not cause environment + establishment to fail; it is the caller's choice to abolish the + environment if the service set provided is unsuitable for the + caller's use. The returned mech_type value indicates the specific + mechanism employed in the environment and will never indicate the + value for "default". + + The following OBJECT IDs are defined for protection and unprotection + services (the OBJECT ID iso.org.dod.internet.security.services, + 1.3.6.1.5.7, has been assigned by IANA, and some of the security + services under that node are assigned as shown below). It is + recognized that this list may grow over time. + + PER_CONF = { 1.3.6.1.5.7.1.1 } + -- perform data confidentiality (i.e., encrypt data) + PER_CONF_FULL = { 1.3.6.1.5.7.1.3 } + -- perform full confidentiality (i.e., encrypt data and sig) + -- (may be used only when PER_DOA is requested simultaneously) + PER_DOA = { 1.3.6.1.5.7.3.1 } + -- perform data origin authentication with data integrity + PER_DOA_CIPH = { 1.3.6.1.5.7.3.3 } + -- perform DOA with DI over ciphertext (rather than plaintext) + -- (may be used only when PER_CONF is requested simultaneously) + PER_POO = { 1.3.6.1.5.7.4.1 } + -- perform (i.e., create) non-repudiable "proof of origin" + PER_POD = { 1.3.6.1.5.7.4.3 } + -- perform (i.e., create) non-repudiable "proof of delivery" + + + + +Adams Informational [Page 17] + +RFC 2479 IDUP-GSS-API December 1998 + + + REC_CONF = { 1.3.6.1.5.7.1.2 } + -- receive data confidentiality (i.e., decrypt data) + REC_CONF_FULL = { 1.3.6.1.5.7.1.4 } + -- receive full confidentiality (i.e., decrypt data and sig) + -- (may be used only when REC_DOA is received simultaneously) + REC_DOA = { 1.3.6.1.5.7.3.2 } + -- receive / verify DOA with data integrity + REC_DOA_CIPH = { 1.3.6.1.5.7.3.4 } + -- verify DOA with DI over ciphertext (rather than plaintext) + -- (may be used only when PER_CONF is received simultaneously) + REC_POO = { 1.3.6.1.5.7.4.2 } + -- receive / verify "proof of origin" + REC_POD = { 1.3.6.1.5.7.4.4 } + -- receive / verify "proof of delivery" + TTIME = { 1.3.6.1.5.7.7.1 } + -- trusted time availability + UTIME = { 1.3.6.1.5.7.7.2 } + -- untrusted time availability + + The PER_CONF return value (in the ret_services paramater) indicates + whether the environment supports confidentiality services, and so + informs the caller whether or not a request for encryption can be + honored. In similar fashion, the PER_DOA return value indicates + whether DOA services are available in the established environment, + and the PER_POO and PER_POD return values indicate whether evidence + generation services are available. The TTIME and UTIME values + indicate whether trusted time and untrusted time are available for + protection / unprotection services. + + Note that, unlike a GSS "context", an IDUP environment does not have + an explicit lifetime associated with it. Instead, it relies on the + lifetime of the calling entity's credential (set by the caller in the + GSS_Acquire_cred() call). When the credential expires (or is + explicitly deleted in any other way), no new operations are allowed + in the IDUP environment (although operations which have begun, such + as the Protection set of calls, can be taken to completion). + + + + + + + + + + + + + + + +Adams Informational [Page 18] + +RFC 2479 IDUP-GSS-API December 1998 + + +2.2.3. IDUP_Abolish_Env call + + Input: + o env_handle ENVIRONMENT HANDLE + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + + Return major_status codes: + o GSS_S_COMPLETE + -- the relevant environment-specific information was flushed. + o IDUP_S_NO_ENV + o GSS_S_FAILURE + + This call is made to flush environment-specific information. (Once an + environment is established, cached credential and environment-related + info. is expected to be retained until an IDUP_Abolish_Env() call is + made or until the cred. lifetime expires.) Attempts to perform IDU + processing on a deleted environment will result in error returns. + +2.2.4. IDUP_Inquire_Env call + + Input: + o env_handle ENVIRONMENT HANDLE, + + Outputs: + o major_status INTEGER, + o minor_status INTEGER, + o mech_type OBJECT IDENTIFIER, + -- the mechanism supporting this environment + o environmentPolicies EnvironmentPolicies, + -- the environment policies in effect + o ret_services SET OF OBJECT IDENTIFIER, + + Return major_status codes: + o GSS_S_COMPLETE + -- referenced environment is valid and mech_type and other return + -- values describe the characteristics of the environment. + o GSS_S_CREDENTIALS_EXPIRED + o IDUP_S_NO_ENV + o GSS_S_FAILURE + + This routine provides environment-related information to the caller. + + + + + + + +Adams Informational [Page 19] + +RFC 2479 IDUP-GSS-API December 1998 + + +2.3. Per-IDU calls + + This group of calls is used to perform IDU protection and + unprotection processing on an established IDUP environment. Some of + these calls may block pending network interactions (depending on the + underlying mechanism in use). These calls may be invoked by an IDU's + protector or by the P-IDU's recipient. Members of this group form + pairs; the output from the protection types of calls is typically + meant to be input to the unprotection types of calls. + + The per-IDU calls can support caller-requested data origin + authentication with data integrity, confidentiality with data + integrity, evidence, and evidence-requested-from-target services. + + The protection operations output a token which encapsulates all the + information required to unprotect the IDU. The token is passed to + the target (possibly separate from the M-IDU) and is processed by the + unprotection calls at that system. Unprotection performs + decipherment, DOA verification, evidence verification, or + notification of evidence requested, as required. + + Each of the two main operations (protection and unprotection) may be + separated into three parts: "Start_Operation"; "Operation" (which + may be called once for each buffer of input data); and + "End_Operation". This separation is available for the case where the + IDU or P-IDU is to be processed one buffer at a time. + "Start_Operation" allows the caller to specify or retrieve the + appropriate "Quality" used during the processing. "Operation" is + concerned with the processing itself, receiving a buffer of input + data and potentially returning a buffer of output data. + "End_Operation" performs any required clean-up and creates the + appropriate token or states whether the input token was verified. + + If the IDU or P-IDU is wholly contained in a single buffer, the + three-part protection/unprotection processing need not be done. + Instead, protection or unprotection can be accomplished using only a + single call, simplifying application code. + +2.3.1. Relationship to GSS-API + + The set of calls described in this section is used in place of the + calls GSS_GetMIC(), GSS_VerifyMIC, GSS_Wrap(), and GSS_Unwrap() which + are specified in [RFC-2078], since those calls are specific to a + session-oriented environment. + + + + + + + +Adams Informational [Page 20] + +RFC 2479 IDUP-GSS-API December 1998 + + +2.3.2. The "SE" Calls + +2.3.2.1. IDUP_SE Purpose + + The "SE" group of calls provides a very simple, high-level interface + to underlying IDUP mechanisms when application developers need access + only to signature and encryption protection/unprotection services. + It includes both the single-buffer and multiple-buffer IDU cases and + can be used for signing only, encrypting only, signing and encrypting + (in either order, and with or without visibility of the resulting + signature), and "clear signing" (where the data is not modified in + any way and the signature itself is returned as a separate item). + [Note that encapsulation occurs in all cases except for clear + signing, so that these calls provide functionality similar to the + GSS_Wrap call.] + + Note that the term "signing" is used in its most generic sense, not + necessarily implying the use of public-key techniques. This concept + has also been called "sealing" in other contexts (e.g., in other + standardization efforts). + + The SE calls may be viewed by mechanism implementors as an "API" to + the more powerful GP calls defined later and so may be implemented as + simple mapping functions to those calls (when those optional calls + are supported). Application callers, on the other hand, may find + that the SE calls are all they currently need for many environments. + At some time in the future when they have need of non-repudiation or + "directed receipts" types of services, they may consider using the EV + calls (or the GP calls -- when these are supported -- if complex and + sophisticated combinations of services are required). To assist in + this migration path, mechanism implementors are encouraged to support + the full set of IDUP calls (i.e., the SE, EV, and GP calls) even + though some calling applications will only use the SE calls in the + short term. + +2.3.2.2. IDUP_SE Parameter Bundles + + The concept of "parameter bundles" is used in the calls presented in + the following subsections in order to simplify their presentation and + clarify their intended purpose and use. See Section 2.3.4.1 for a + more complete description of parameter bundles. + + The following parameter bundles are used in the "SE" protection and + unprotection sets of calls. + + + + + + + +Adams Informational [Page 21] + +RFC 2479 IDUP-GSS-API December 1998 + + + o Protect_Options PARAMETER BUNDLE + o protect_operation INTEGER { + sign_only (0), + encrypt_only (1), + sign_and_encrypt (2), + -- let mechanism choose order (and readability of signature) + sign_then_encrypt_data (3), + -- sign, then encrypt plaintext (leaving signature in clear) + sign_then_encrypt_full (4), + -- sign, then encrypt everything (including signature) + encrypt_then_sign (5), + -- encrypt, then sign the ciphertext + clear_sign_only (6) + } OPTIONAL, + o protect_oper_oid OBJECT IDENTIFIER OPTIONAL, + -- may be used in place of above parameter if OID is known + o sign_qop_alg UNSIGNED INTEGER, + o sign_qop_algID AlgorithmIdentifier, --overrides sign_qop_alg + o enc_qop_alg UNSIGNED INTEGER, + o enc_qop_algID AlgorithmIdentifier, --overrides enc_qop_alg + o idu_type_string OCTET STRING, + -- type of the IDU ("data", "e-mail doc", MIME type, etc.) + o pidu_type_string OCTET STRING, + o mech_indep_encap_req BOOLEAN -- (see Appendix A) + + o PIDU_Information PARAMETER BUNDLE + o protect_options Protect_Options, + o originator_name INTERNAL NAME, + o originator_role Originator_Role, -- (see Section 2.3.4.1) + o protection_time INTEGER, + o Bad_Target_Name PARAMETER BUNDLE, -- same as in Section 2.3.3.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. 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, -- same as in Section 2.3.3.2 + o targ_names SET OF INTERNAL NAME, + o bad_targ_count INTEGER, + o bad_target_names SET OF Bad_Target_Name, + + + + + +Adams Informational [Page 22] + +RFC 2479 IDUP-GSS-API December 1998 + + +2.3.2.3. IDUP_SE major_status codes + + The following major_status return codes are defined for the "SE" + calls in this section: + + o GSS_S_COMPLETE + o IDUP_S_MORE_OUTBUFFER_NEEDED + -- returned (by any SE 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_MORE_PIDU_NEEDED + -- indicates that more PIDU data is needed for the StartUnprotect + -- 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) + + + + +Adams Informational [Page 23] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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) + + + + + + +Adams Informational [Page 24] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + +Adams Informational [Page 25] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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) + + + + + +Adams Informational [Page 26] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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, + + + + + +Adams Informational [Page 27] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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), + + + +Adams Informational [Page 28] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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. + + + + +Adams Informational [Page 29] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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, + + + +Adams Informational [Page 30] + +RFC 2479 IDUP-GSS-API December 1998 + + + -- 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 + + + +Adams Informational [Page 31] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + +Adams Informational [Page 32] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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. + + + + + + +Adams Informational [Page 33] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + + + + + +Adams Informational [Page 34] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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) + + + + +Adams Informational [Page 35] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + +Adams Informational [Page 36] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + + + +Adams Informational [Page 37] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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) + + + +Adams Informational [Page 38] + +RFC 2479 IDUP-GSS-API December 1998 + + + -- 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, + + + +Adams Informational [Page 39] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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, + + + +Adams Informational [Page 40] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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. + + + + + + +Adams Informational [Page 41] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + +Adams Informational [Page 42] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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). + + + + +Adams Informational [Page 43] + +RFC 2479 IDUP-GSS-API December 1998 + + +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 + + + + + + + + + + + + +Adams Informational [Page 44] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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. + + + +Adams Informational [Page 45] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + + +Adams Informational [Page 46] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + +Adams Informational [Page 47] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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. + + 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 + + + +Adams Informational [Page 48] + +RFC 2479 IDUP-GSS-API December 1998 + + + "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 + + + +Adams Informational [Page 49] + +RFC 2479 IDUP-GSS-API December 1998 + + + -- 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. + + + +Adams Informational [Page 50] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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. + + + + + +Adams Informational [Page 51] + +RFC 2479 IDUP-GSS-API December 1998 + + + If all tokens are framed as suggested in Section 3.1 of [RFC-2078] + (mandated in the Kerberos V5 GSS mechanism [RFC 1964] and in the SPKM + GSS Mechanism [RFC 2025]), then any mechanism implementation should + be able to return the mech_type parameter for any uncorrupted input + token. If the mechanism implementation whose IDUP_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, + + + +Adams Informational [Page 52] + +RFC 2479 IDUP-GSS-API December 1998 + + + - 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 + + + +Adams Informational [Page 53] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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. + + + + + +Adams Informational [Page 54] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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. + + + + + + + + +Adams Informational [Page 55] + +RFC 2479 IDUP-GSS-API December 1998 + + +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", RFC 1421, February 1993. + + [RFC-2078] Linn, J., "Generic Security Service Application Program + Interface, Version 2", RFC 2078, January 1997.. + + [RFC 1964] Linn, J, "The Kerberos Version 5 GSS-API Mechanism", RFC + 1964, June 1996. + + [RFC 2025] Adams, C., "The Simple Public-Key GSS-API Mechanism + (SPKM)", RFC 2025, 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 + + + + + + + + + +Adams Informational [Page 56] + +RFC 2479 IDUP-GSS-API December 1998 + + +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 + + + + + + + + + + + + + +Adams Informational [Page 57] + +RFC 2479 IDUP-GSS-API December 1998 + + +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. + + + + + + + + +Adams Informational [Page 58] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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). + + + + + + + +Adams Informational [Page 59] + +RFC 2479 IDUP-GSS-API December 1998 + + +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) + + + + + +Adams Informational [Page 60] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + + + +Adams Informational [Page 61] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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. + + + + +Adams Informational [Page 62] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + +Adams Informational [Page 63] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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. + + + +Adams Informational [Page 64] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + +Adams Informational [Page 65] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + + +Adams Informational [Page 66] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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) + + + + + +Adams Informational [Page 67] + +RFC 2479 IDUP-GSS-API December 1998 + + + 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 + + + +Adams Informational [Page 68] + +RFC 2479 IDUP-GSS-API December 1998 + + + Prot_Service_1.prot_service_type = "2"; + Prot_Service_1.service_id = "PER_POD"; + Prot_Service_1.Service_Creation_Info = Service_Creation_Info; + P_Services.Prot_Service_1 = Prot_Service_1 + + Call + IDUP_Start_Protect() with above input parameters + Check + major_status. If not GSS_S_COMPLETE, check + minor_status, + P_Services.Prot_Service_1.General_Service_Data.minor_status + (as required) for more detailed information. + + Send + pidu_buffer to "receipts to" list (L) + + RECEIVER (ON "RECEIPTS TO" LIST (L)): + (procedure to process received receipt) + + Set + env_handle = environment handle in use; + single_pidu_buffer = received p-idu buffer (if it fits in a single + buffer; otherwise use partial_pidu_buffer and make multiple + calls, as above) + + Call + IDUP_Start_Unprotect() with above input parameters + If major_status == IDUP_S_SERV_VERIF_INFO_NEEDED + Utilize + R_Services.Unprot_Service_1.service_verification_info.id + (to assist in locating necessary Service_Verification_Info) + Set + R_Services.Unprot_Service_1.Service_Verification_Info + = Service_Verification_Info + Call + IDUP_Start_Unprotect() with above input parameters + Check + major_status, + minor_status, + R_Services.Unprot_Service_1.General_Service_Data.minor_status + (as required) for more detailed information. + + Utilize + R_Services.Unprot_Service_1.service_id, + (to determine that this is a "proof of delivery" evidence) + R_Services.Unprot_Service_1.Quality, + Prot_Information.originator_name, (for evidence generator info.) + major_status (to determine pass/fail status of evi. verif.). + + + +Adams Informational [Page 69] + +RFC 2479 IDUP-GSS-API December 1998 + + +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. + + + + + + + + + + + + + + + + + + + + + + + + +Adams Informational [Page 70] + diff --git a/doc/specifications/rfc2853.txt b/doc/specifications/rfc2853.txt new file mode 100644 index 00000000..66767ddb --- /dev/null +++ b/doc/specifications/rfc2853.txt @@ -0,0 +1,5379 @@ + + + + + + +Network Working Group J. Kabat +Request for Comments: 2853 ValiCert, Inc. +Category: Standards Track M. Upadhyay + Sun Microsystems, Inc. + June 2000 + + + Generic Security Service API Version 2 : Java Bindings + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2000). All Rights Reserved. + +Abstract + + The Generic Security Services Application Program Interface (GSS-API) + offers application programmers uniform access to security services + atop a variety of underlying cryptographic mechanisms. This document + specifies the Java bindings for GSS-API which is described at a + language independent conceptual level in RFC 2743 [GSSAPIv2-UPDATE]. + + The GSS-API allows a caller application to authenticate a principal + identity, to delegate rights to a peer, and to apply security + services such as confidentiality and integrity on a per-message + basis. Examples of security mechanisms defined for GSS-API are The + Simple Public-Key GSS-API Mechanism [SPKM] and The Kerberos Version 5 + GSS-API Mechanism [KERBV5]. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 5 + 2. GSS-API Operational Paradigm . . . . . . . . . . . . . . . 6 + 3. Additional Controls . . . . . . . . . . . . . . . . . . . 8 + 3.1. Delegation . . . . . . . . . . . . . . . . . . . . . . . 9 + 3.2. Mutual Authentication . . . . . . . . . . . . . . . . . 10 + 3.3. Replay and Out-of-Sequence Detection . . . . . . . . . . 10 + 3.4. Anonymous Authentication . . . . . . . . . . . . . . . . 11 + 3.5. Confidentiality . . . . . . . . . . . . . . . . . . . . 12 + 3.6. Inter-process Context Transfer . . . . . . . . . . . . . 12 + 3.7. The Use of Incomplete Contexts . . . . . . . . . . . . . 13 + + + +Kabat & Upadhyay Standards Track [Page 1] + +RFC 2853 GSS-API Java Bindings June 2000 + + + 4. Calling Conventions . . . . . . . . . . . . . . . . . . . 13 + 4.1. Package Name . . . . . . . . . . . . . . . . . . . . . . 13 + 4.2. Provider Framework . . . . . . . . . . . . . . . . . . . 13 + 4.3. Integer types . . . . . . . . . . . . . . . . . . . . . 14 + 4.4. Opaque Data types . . . . . . . . . . . . . . . . . . . 14 + 4.5. Strings . . . . . . . . . . . . . . . . . . . . . . . . 15 + 4.6. Object Identifiers . . . . . . . . . . . . . . . . . . . 15 + 4.7. Object Identifier Sets . . . . . . . . . . . . . . . . . 15 + 4.8. Credentials . . . . . . . . . . . . . . . . . . . . . . 16 + 4.9. Contexts . . . . . . . . . . . . . . . . . . . . . . . . 18 + 4.10. Authentication tokens . . . . . . . . . . . . . . . . . 18 + 4.11. Interprocess tokens . . . . . . . . . . . . . . . . . . 18 + 4.12. Error Reporting . . . . . . . . . . . . . . . . . . . . 19 + 4.12.1. GSS status codes . . . . . . . . . . . . . . . . . . 19 + 4.12.2. Mechanism-specific status codes . . . . . . . . . . . 21 + 4.12.3. Supplementary status codes . . . . . . . . . . . . . 21 + 4.13. Names . . . . . . . . . . . . . . . . . . . . . . . . . 22 + 4.14. Channel Bindings . . . . . . . . . . . . . . . . . . . 25 + 4.15. Stream Objects . . . . . . . . . . . . . . . . . . . . 26 + 4.16. Optional Parameters . . . . . . . . . . . . . . . . . . 26 + 5. Introduction to GSS-API Classes and Interfaces . . . . . . 26 + 5.1. GSSManager class . . . . . . . . . . . . . . . . . . . . 26 + 5.2. GSSName interface . . . . . . . . . . . . . . . . . . . 27 + 5.3. GSSCredential interface . . . . . . . . . . . . . . . . 28 + 5.4. GSSContext interface . . . . . . . . . . . . . . . . . . 28 + 5.5. MessageProp class . . . . . . . . . . . . . . . . . . . 30 + 5.6. GSSException class . . . . . . . . . . . . . . . . . . . 30 + 5.7. Oid class . . . . . . . . . . . . . . . . . . . . . . . 30 + 5.8. ChannelBinding class . . . . . . . . . . . . . . . . . . 31 + 6. Detailed GSS-API Class Description . . . . . . . . . . . . 31 + 6.1. public abstract class GSSManager . . . . . . . . . . . . 31 + 6.1.1. Example Code . . . . . . . . . . . . . . . . . . . . . 32 + 6.1.2. getInstance . . . . . . . . . . . . . . . . . . . . . 33 + 6.1.3. getMechs . . . . . . . . . . . . . . . . . . . . . . . 33 + 6.1.4. getNamesForMech . . . . . . . . . . . . . . . . . . . 33 + 6.1.5. getMechsForName . . . . . . . . . . . . . . . . . . . 33 + 6.1.6. createName . . . . . . . . . . . . . . . . . . . . . . 33 + 6.1.7. createName . . . . . . . . . . . . . . . . . . . . . . 34 + 6.1.8. createName . . . . . . . . . . . . . . . . . . . . . . 35 + 6.1.9. createName . . . . . . . . . . . . . . . . . . . . . . 35 + 6.1.10. createCredential . . . . . . . . . . . . . . . . . . 36 + 6.1.11. createCredential . . . . . . . . . . . . . . . . . . 36 + 6.1.12. createCredential . . . . . . . . . . . . . . . . . . 37 + 6.1.13. createContext . . . . . . . . . . . . . . . . . . . . 37 + 6.1.14. createContext . . . . . . . . . . . . . . . . . . . . 38 + 6.1.15. createContext . . . . . . . . . . . . . . . . . . . . 38 + 6.1.16. addProviderAtFront . . . . . . . . . . . . . . . . . 38 + 6.1.16.1. Example Code . . . . . . . . . . . . . . . . . . . 39 + + + +Kabat & Upadhyay Standards Track [Page 2] + +RFC 2853 GSS-API Java Bindings June 2000 + + + 6.1.17. addProviderAtEnd . . . . . . . . . . . . . . . . . . 40 + 6.1.17.1. Example Code . . . . . . . . . . . . . . . . . . . 41 + 6.2. public interface GSSName . . . . . . . . . . . . . . . . 42 + 6.2.1. Example Code . . . . . . . . . . . . . . . . . . . . . 42 + 6.2.2. Static Constants . . . . . . . . . . . . . . . . . . . 43 + 6.2.3. equals . . . . . . . . . . . . . . . . . . . . . . . . 44 + 6.2.4. equals . . . . . . . . . . . . . . . . . . . . . . . . 44 + 6.2.5. canonicalize . . . . . . . . . . . . . . . . . . . . . 44 + 6.2.6. export . . . . . . . . . . . . . . . . . . . . . . . . 45 + 6.2.7. toString . . . . . . . . . . . . . . . . . . . . . . . 45 + 6.2.8. getStringNameType . . . . . . . . . . . . . . . . . . 45 + 6.2.9. isAnonymous . . . . . . . . . . . . . . . . . . . . . 45 + 6.2.10. isMN . . . . . . . . . . . . . . . . . . . . . . . . 45 + 6.3. public interface GSSCredential implements Cloneable . . 45 + 6.3.1. Example Code . . . . . . . . . . . . . . . . . . . . . 46 + 6.3.2. Static Constants . . . . . . . . . . . . . . . . . . . 47 + 6.3.3. dispose . . . . . . . . . . . . . . . . . . . . . . . 48 + 6.3.4. getName . . . . . . . . . . . . . . . . . . . . . . . 48 + 6.3.5. getName . . . . . . . . . . . . . . . . . . . . . . . 48 + 6.3.6. getRemainingLifetime . . . . . . . . . . . . . . . . . 48 + 6.3.7. getRemainingInitLifetime . . . . . . . . . . . . . . . 49 + 6.3.8. getRemainingAcceptLifetime . . . . . . . . . . . . . . 49 + 6.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . . 49 + 6.3.10. getUsage . . . . . . . . . . . . . . . . . . . . . . 49 + 6.3.11. getMechs . . . . . . . . . . . . . . . . . . . . . . 50 + 6.3.12. add . . . . . . . . . . . . . . . . . . . . . . . . . 50 + 6.3.13. equals . . . . . . . . . . . . . . . . . . . . . . . 51 + 6.4. public interface GSSContext . . . . . . . . . . . . . . 51 + 6.4.1. Example Code . . . . . . . . . . . . . . . . . . . . . 52 + 6.4.2. Static Constants . . . . . . . . . . . . . . . . . . . 54 + 6.4.3. initSecContext . . . . . . . . . . . . . . . . . . . . 54 + 6.4.3.1. Example Code . . . . . . . . . . . . . . . . . . . . 55 + 6.4.4. initSecContext . . . . . . . . . . . . . . . . . . . . 56 + 6.4.4.1. Example Code . . . . . . . . . . . . . . . . . . . . 56 + 6.4.5. acceptSecContext . . . . . . . . . . . . . . . . . . . 57 + 6.4.5.1. Example Code . . . . . . . . . . . . . . . . . . . . 58 + 6.4.6. acceptSecContext . . . . . . . . . . . . . . . . . . . 59 + 6.4.6.1. Example Code . . . . . . . . . . . . . . . . . . . . 59 + 6.4.7. isEstablished . . . . . . . . . . . . . . . . . . . . 60 + 6.4.8. dispose . . . . . . . . . . . . . . . . . . . . . . . 60 + 6.4.9. getWrapSizeLimit . . . . . . . . . . . . . . . . . . . 61 + 6.4.10. wrap . . . . . . . . . . . . . . . . . . . . . . . . 61 + 6.4.11. wrap . . . . . . . . . . . . . . . . . . . . . . . . 62 + 6.4.12. unwrap . . . . . . . . . . . . . . . . . . . . . . . 63 + 6.4.13. unwrap . . . . . . . . . . . . . . . . . . . . . . . 64 + 6.4.14. getMIC . . . . . . . . . . . . . . . . . . . . . . . 65 + 6.4.15. getMIC . . . . . . . . . . . . . . . . . . . . . . . 65 + 6.4.16. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 66 + + + +Kabat & Upadhyay Standards Track [Page 3] + +RFC 2853 GSS-API Java Bindings June 2000 + + + 6.4.17. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 67 + 6.4.18. export . . . . . . . . . . . . . . . . . . . . . . . 68 + 6.4.19. requestMutualAuth . . . . . . . . . . . . . . . . . . 68 + 6.4.20. requestReplayDet . . . . . . . . . . . . . . . . . . 69 + 6.4.21. requestSequenceDet . . . . . . . . . . . . . . . . . 69 + 6.4.22. requestCredDeleg . . . . . . . . . . . . . . . . . . 69 + 6.4.23. requestAnonymity . . . . . . . . . . . . . . . . . . 69 + 6.4.24. requestConf . . . . . . . . . . . . . . . . . . . . . 70 + 6.4.25. requestInteg . . . . . . . . . . . . . . . . . . . . 70 + 6.4.26. requestLifetime . . . . . . . . . . . . . . . . . . . 70 + 6.4.27. setChannelBinding . . . . . . . . . . . . . . . . . . 71 + 6.4.28. getCredDelegState . . . . . . . . . . . . . . . . . . 71 + 6.4.29. getMutualAuthState . . . . . . . . . . . . . . . . . 71 + 6.4.30. getReplayDetState . . . . . . . . . . . . . . . . . . 71 + 6.4.31. getSequenceDetState . . . . . . . . . . . . . . . . . 71 + 6.4.32. getAnonymityState . . . . . . . . . . . . . . . . . . 72 + 6.4.33. isTransferable . . . . . . . . . . . . . . . . . . . 72 + 6.4.34. isProtReady . . . . . . . . . . . . . . . . . . . . . 72 + 6.4.35. getConfState . . . . . . . . . . . . . . . . . . . . 72 + 6.4.36. getIntegState . . . . . . . . . . . . . . . . . . . . 72 + 6.4.37. getLifetime . . . . . . . . . . . . . . . . . . . . . 73 + 6.4.38. getSrcName . . . . . . . . . . . . . . . . . . . . . 73 + 6.4.39. getTargName . . . . . . . . . . . . . . . . . . . . . 73 + 6.4.40. getMech . . . . . . . . . . . . . . . . . . . . . . . 73 + 6.4.41. getDelegCred . . . . . . . . . . . . . . . . . . . . 73 + 6.4.42. isInitiator . . . . . . . . . . . . . . . . . . . . . 73 + 6.5. public class MessageProp . . . . . . . . . . . . . . . . 74 + 6.5.1. Constructors . . . . . . . . . . . . . . . . . . . . . 74 + 6.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . . 75 + 6.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . . 75 + 6.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . . 75 + 6.5.5. getMinorString . . . . . . . . . . . . . . . . . . . . 75 + 6.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . . 75 + 6.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . . 75 + 6.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . . 76 + 6.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . . 76 + 6.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . 76 + 6.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . 76 + 6.5.12. setSupplementaryStates . . . . . . . . . . . . . . . 76 + 6.6. public class ChannelBinding . . . . . . . . . . . . . . 77 + 6.6.1. Constructors . . . . . . . . . . . . . . . . . . . . . 77 + 6.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 78 + 6.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . . 78 + 6.6.4. getApplicationData . . . . . . . . . . . . . . . . . . 78 + 6.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . . 78 + 6.7. public class Oid . . . . . . . . . . . . . . . . . . . . 79 + 6.7.1. Constructors . . . . . . . . . . . . . . . . . . . . . 79 + 6.7.2. toString . . . . . . . . . . . . . . . . . . . . . . . 80 + + + +Kabat & Upadhyay Standards Track [Page 4] + +RFC 2853 GSS-API Java Bindings June 2000 + + + 6.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . . 80 + 6.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . . 80 + 6.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 80 + 6.8. public class GSSException extends Exception . . . . . . 80 + 6.8.1. Static Constants . . . . . . . . . . . . . . . . . . . 81 + 6.8.2. Constructors . . . . . . . . . . . . . . . . . . . . . 83 + 6.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . . 84 + 6.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . . 84 + 6.8.5. getMajorString . . . . . . . . . . . . . . . . . . . . 84 + 6.8.6. getMinorString . . . . . . . . . . . . . . . . . . . . 84 + 6.8.7. setMinor . . . . . . . . . . . . . . . . . . . . . . . 84 + 6.8.8. toString . . . . . . . . . . . . . . . . . . . . . . . 85 + 6.8.9. getMessage . . . . . . . . . . . . . . . . . . . . . . 85 + 7. Sample Applications . . . . . . . . . . . . . . . . . . . 85 + 7.1. Simple GSS Context Initiator . . . . . . . . . . . . . . 85 + 7.2. Simple GSS Context Acceptor . . . . . . . . . . . . . . 89 + 8. Security Considerations . . . . . . . . . . . . . . . . . 93 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 94 + 10. Bibliography . . . . . . . . . . . . . . . . . . . . . . 94 + 11. Authors' Addresses . . . . . . . . . . . . . . . . . . . 95 + 12. Full Copyright Statement. . . . . . . . . . . . . . . . . 96 + +1. Introduction + + This document specifies Java language bindings for the Generic + Security Services Application Programming Interface Version 2 (GSS- + API). GSS-API Version 2 is described in a language independent + format in RFC 2743 [GSSAPIv2-UPDATE]. The GSS-API allows a caller + application to authenticate a principal identity, to delegate rights + to a peer, and to apply security services such as confidentiality and + integrity on a per-message basis. + + This document leverages the work performed by the WG in the area of + RFC 2743 [GSSAPIv2-UPDATE] and the C-bindings RFC 2744 [GSSAPI-C]. + Whenever appropriate, text has been used from the C-bindings RFC 2744 + to explain generic concepts and provide direction to the + implementors. + + The design goals of this API have been to satisfy all the + functionality defined in RFC 2743 and to provide these services in an + object oriented method. The specification also aims to satisfy the + needs of both types of Java application developers, those who would + like access to a "system-wide" GSS-API implementation, as well as + those who would want to provide their own "custom" implementation. + + + + + + + +Kabat & Upadhyay Standards Track [Page 5] + +RFC 2853 GSS-API Java Bindings June 2000 + + + A "system-wide" implementation is one that is available to all + applications in the form of a library package. It may be a standard + package in the Java runtime environment (JRE) being used or it may be + additionally installed and accessible to any application via the + CLASSPATH. + + A "custom" implementation of the GSS-API, on the other hand, is one + that would, in most cases, be bundled with the application during + distribution. It is expected that such an implementation would be + meant to provide for some particular need of the application, such as + support for some specific mechanism. + + The design of this API also aims to provide a flexible framework to + add and manage GSS-API mechanisms. GSS-API leverages the Java + Cryptography Architecture (JCA) provider model to support the + plugability of mechanisms. Mechanisms can be added on a "system- + wide" basis, where all users of the framework will have them + available. The specification also allows for the addition of + mechanisms per-instance of the GSS-API. + + Lastly, this specification presents an API that will naturally fit + within the operation environment of the Java platform. Readers are + assumed to be familiar with both the GSS-API and the Java platform. + +2. GSS-API Operational Paradigm + + The Generic Security Service Application Programming Interface + Version 2 [GSSAPIv2-UPDATE] defines a generic security API to calling + applications. It allows a communicating application to authenticate + the user associated with another application, to delegate rights to + another application, and to apply security services such as + confidentiality and integrity on a per-message basis. + + There are four stages to using GSS-API: + + 1) The application acquires a set of credentials with which it may + prove its identity to other processes. The application's + credentials vouch for its global identity, which may or may not + be related to any local username under which it may be running. + + 2) A pair of communicating applications establish a joint security + context using their credentials. The security context + encapsulates shared state information, which is required in + order that per-message security services may be provided. + Examples of state information that might be shared between + applications as part of a security context are cryptographic + keys, and message sequence numbers. As part of the + establishment of a security context, the context initiator is + + + +Kabat & Upadhyay Standards Track [Page 6] + +RFC 2853 GSS-API Java Bindings June 2000 + + + authenticated to the responder, and may require that the + responder is authenticated back to the initiator. The + initiator may optionally give the responder the right to + initiate further security contexts, acting as an agent or + delegate of the initiator. This transfer of rights is termed + "delegation", and is achieved by creating a set of credentials, + similar to those used by the initiating application, but which + may be used by the responder. + + A GSSContext object is used to establish and maintain the + shared information that makes up the security context. Certain + GSSContext methods will generate a token, which applications + treat as cryptographically protected, opaque data. The caller + of such GSSContext method is responsible for transferring the + token to the peer application, encapsulated if necessary in an + application-to-application protocol. On receipt of such a + token, the peer application should pass it to a corresponding + GSSContext method which will decode the token and extract the + information, updating the security context state information + accordingly. + + 3) Per-message services are invoked on a GSSContext object to + apply either: + + integrity and data origin authentication, or + + confidentiality, integrity and data origin authentication + + to application data, which are treated by GSS-API as arbitrary + octet-strings. An application transmitting a message that it + wishes to protect will call the appropriate GSSContext method + (getMIC or wrap) to apply protection, and send the resulting + token to the receiving application. The receiver will pass the + received token (and, in the case of data protected by getMIC, + the accompanying message-data) to the corresponding decoding + method of the GSSContext interface (verifyMIC or unwrap) to + remove the protection and validate the data. + + 4) At the completion of a communications session (which may extend + across several transport connections), each application uses a + GSSContext method to invalidate the security context and + release any system or cryptographic resources held. Multiple + contexts may also be used (either successively or + simultaneously) within a single communications association, at + the discretion of the applications. + + + + + + +Kabat & Upadhyay Standards Track [Page 7] + +RFC 2853 GSS-API Java Bindings June 2000 + + +3. Additional Controls + + This section discusses the optional services that a context initiator + may request of the GSS-API before the context establishment. Each of + these services is requested by calling the appropriate mutator method + in the GSSContext object before the first call to init is performed. + Only the context initiator can request context flags. + + The optional services defined are: + + Delegation + The (usually temporary) transfer of rights from initiator to + acceptor, enabling the acceptor to authenticate itself as an + agent of the initiator. + + Mutual Authentication + In addition to the initiator authenticating its identity to the + context acceptor, the context acceptor should also authenticate + itself to the initiator. + + Replay Detection + In addition to providing message integrity services, GSSContext + per-message operations of getMIC and wrap should include + message numbering information to enable verifyMIC and unwrap + to detect if a message has been duplicated. + + Out-of-Sequence Detection + In addition to providing message integrity services, GSSContext + per-message operations (getMIC and wrap) should include + message sequencing information to enable verifyMIC and unwrap + to detect if a message has been received out of sequence. + + Anonymous Authentication + The establishment of the security context should not reveal the + initiator's identity to the context acceptor. + + Some mechanisms may not support all optional services, and some + mechanisms may only support some services in conjunction with others. + The GSSContext interface offers query methods to allow the + verification by the calling application of which services will be + available from the context when the establishment phase is complete. + In general, if the security mechanism is capable of providing a + requested service, it should do so even if additional services must + be enabled in order to provide the requested service. If the + mechanism is incapable of providing a requested service, it should + proceed without the service leaving the application to abort the + context establishment process if it considers the requested service + to be mandatory. + + + +Kabat & Upadhyay Standards Track [Page 8] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Some mechanisms may specify that support for some services is + optional, and that implementors of the mechanism need not provide it. + This is most commonly true of the confidentiality service, often + because of legal restrictions on the use of data-encryption, but may + apply to any of the services. Such mechanisms are required to send + at least one token from acceptor to initiator during context + establishment when the initiator indicates a desire to use such a + service, so that the initiating GSS-API can correctly indicate + whether the service is supported by the acceptor's GSS-API. + +3.1. Delegation + + The GSS-API allows delegation to be controlled by the initiating + application via the requestCredDeleg method before the first call to + init has been issued. Some mechanisms do not support delegation, and + for such mechanisms attempts by an application to enable delegation + are ignored. + + The acceptor of a security context, for which the initiator enabled + delegation, can check if delegation was enabled by using the + getCredDelegState method of the GSSContext interface. In cases when + it is, the delegated credential object can be obtained by calling the + getDelegCred method. The obtained GSSCredential object may then be + used to initiate subsequent GSS-API security contexts as an agent or + delegate of the initiator. If the original initiator's identity is + "A" and the delegate's identity is "B", then, depending on the + underlying mechanism, the identity embodied by the delegated + credential may be either "A" or "B acting for A". + + For many mechanisms that support delegation, a simple boolean does + not provide enough control. Examples of additional aspects of + delegation control that a mechanism might provide to an application + are duration of delegation, network addresses from which delegation + is valid, and constraints on the tasks that may be performed by a + delegate. Such controls are presently outside the scope of the GSS- + API. GSS-API implementations supporting mechanisms offering + additional controls should provide extension routines that allow + these controls to be exercised (perhaps by modifying the initiator's + GSS-API credential object prior to its use in establishing a + context). However, the simple delegation control provided by GSS-API + should always be able to over-ride other mechanism-specific + delegation controls. If the application instructs the GSSContext + object that delegation is not desired, then the implementation must + not permit delegation to occur. This is an exception to the general + rule that a mechanism may enable services even if they are not + requested - delegation may only be provided at the explicit request + of the application. + + + + +Kabat & Upadhyay Standards Track [Page 9] + +RFC 2853 GSS-API Java Bindings June 2000 + + +3.2. Mutual Authentication + + Usually, a context acceptor will require that a context initiator + authenticate itself so that the acceptor may make an access-control + decision prior to performing a service for the initiator. In some + cases, the initiator may also request that the acceptor authenticate + itself. GSS-API allows the initiating application to request this + mutual authentication service by calling the requestMutualAuth method + of the GSSContext interface with a "true" parameter before making the + first call to init. The initiating application is informed as to + whether or not the context acceptor has authenticated itself. Note + that some mechanisms may not support mutual authentication, and other + mechanisms may always perform mutual authentication, whether or not + the initiating application requests it. In particular, mutual + authentication may be required by some mechanisms in order to support + replay or out-of-sequence message detection, and for such mechanisms + a request for either of these services will automatically enable + mutual authentication. + +3.3. Replay and Out-of-Sequence Detection + + The GSS-API may provide detection of mis-ordered messages once a + security context has been established. Protection may be applied to + messages by either application, by calling either getMIC or wrap + methods of the GSSContext interface, and verified by the peer + application by calling verifyMIC or unwrap for the peer's GSSContext + object. + + The getMIC method calculates a cryptographic checksum of an + application message, and returns that checksum in a token. The + application should pass both the token and the message to the peer + application, which presents them to the verifyMIC method of the + peer's GSSContext object. + + The wrap method calculates a cryptographic checksum of an application + message, and places both the checksum and the message inside a single + token. The application should pass the token to the peer + application, which presents it to the unwrap method of the peer's + GSSContext object to extract the message and verify the checksum. + + Either pair of routines may be capable of detecting out-of-sequence + message delivery, or duplication of messages. Details of such mis- + ordered messages are indicated through supplementary query methods of + the MessageProp object that is filled in by each of these routines. + + A mechanism need not maintain a list of all tokens that have been + processed in order to support these status codes. A typical + mechanism might retain information about only the most recent "N" + + + +Kabat & Upadhyay Standards Track [Page 10] + +RFC 2853 GSS-API Java Bindings June 2000 + + + tokens processed, allowing it to distinguish duplicates and missing + tokens within the most recent "N" messages; the receipt of a token + older than the most recent "N" would result in the isOldToken method + of the instance of MessageProp to return "true". + +3.4. Anonymous Authentication + + In certain situations, an application may wish to initiate the + authentication process to authenticate a peer, without revealing its + own identity. As an example, consider an application providing + access to a database containing medical information, and offering + unrestricted access to the service. A client of such a service might + wish to authenticate the service (in order to establish trust in any + information retrieved from it), but might not wish the service to be + able to obtain the client's identity (perhaps due to privacy concerns + about the specific inquiries, or perhaps simply to avoid being placed + on mailing-lists). + + In normal use of the GSS-API, the initiator's identity is made + available to the acceptor as a result of the context establishment + process. However, context initiators may request that their identity + not be revealed to the context acceptor. Many mechanisms do not + support anonymous authentication, and for such mechanisms the request + will not be honored. An authentication token will still be + generated, but the application is always informed if a requested + service is unavailable, and has the option to abort context + establishment if anonymity is valued above the other security + services that would require a context to be established. + + In addition to informing the application that a context is + established anonymously (via the isAnonymous method of the GSSContext + class), the getSrcName method of the acceptor's GSSContext object + will, for such contexts, return a reserved internal-form name, + defined by the implementation. + + The toString method for a GSSName object representing an anonymous + entity will return a printable name. The returned value will be + syntactically distinguishable from any valid principal name supported + by the implementation. The associated name-type object identifier + will be an oid representing the value of NT_ANONYMOUS. This name- + type oid will be defined as a public, static Oid object of the + GSSName class. The printable form of an anonymous name should be + chosen such that it implies anonymity, since this name may appear in, + for example, audit logs. For example, the string "" might + be a good choice, if no valid printable names supported by the + implementation can begin with "<" and end with ">". + + + + + +Kabat & Upadhyay Standards Track [Page 11] + +RFC 2853 GSS-API Java Bindings June 2000 + + + When using the equal method of the GSSName interface, and one of the + operands is a GSSName instance representing an anonymous entity, the + method must return "false". + +3.5. Confidentiality + + If a GSSContext supports the confidentiality service, wrap method may + be used to encrypt application messages. Messages are selectively + encrypted, under the control of the setPrivacy method of the + MessageProp object used in the wrap method. + +3.6. Inter-process Context Transfer + + GSS-API V2 provides functionality which allows a security context to + be transferred between processes on a single machine. These are + implemented using the export method of GSSContext and a byte array + constructor of the same class. The most common use for such a + feature is a client-server design where the server is implemented as + a single process that accepts incoming security contexts, which then + launches child processes to deal with the data on these contexts. In + such a design, the child processes must have access to the security + context object created within the parent so that they can use per- + message protection services and delete the security context when the + communication session ends. + + Since the security context data structure is expected to contain + sequencing information, it is impractical in general to share a + context between processes. Thus GSSContext interface provides an + export method that the process, which currently owns the context, can + call to declare that it has no intention to use the context + subsequently, and to create an inter-process token containing + information needed by the adopting process to successfully re-create + the context. After successful completion of export, the original + security context is made inaccessible to the calling process by GSS- + API and any further usage of this object will result in failures. + The originating process transfers the inter-process token to the + adopting process, which creates a new GSSContext object using the + byte array constructor. The properties of the context are equivalent + to that of the original context. + + The inter-process token may contain sensitive data from the original + security context (including cryptographic keys). Applications using + inter-process tokens to transfer security contexts must take + appropriate steps to protect these tokens in transit. + + + + + + + +Kabat & Upadhyay Standards Track [Page 12] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Implementations are not required to support the inter-process + transfer of security contexts. Calling the isTransferable method of + the GSSContext interface will indicate if the context object is + transferable. + +3.7. The Use of Incomplete Contexts + + Some mechanisms may allow the per-message services to be used before + the context establishment process is complete. For example, a + mechanism may include sufficient information in its initial context- + level tokens for the context acceptor to immediately decode messages + protected with wrap or getMIC. For such a mechanism, the initiating + application need not wait until subsequent context-level tokens have + been sent and received before invoking the per-message protection + services. + + An application can invoke the isProtReady method of the GSSContext + class to determine if the per-message services are available in + advance of complete context establishment. Applications wishing to + use per-message protection services on partially-established contexts + should query this method before attempting to invoke wrap or getMIC. + +4. Calling Conventions + + Java provides the implementors with not just a syntax for the + language, but also an operational environment. For example, memory + is automatically managed and does not require application + intervention. These language features have allowed for a simpler API + and have led to the elimination of certain GSS-API functions. + + Moreover, the JCA defines a provider model which allows for + implementation independent access to security services. Using this + model, applications can seamlessly switch between different + implementations and dynamically add new services. The GSS-API + specification leverages these concepts by the usage of providers for + the mechanism implementations. + +4.1. Package Name + + The classes and interfaces defined in this document reside in the + package called "org.ietf.jgss". Applications that wish to make use + of this API should import this package name as shown in section 7. + +4.2. Provider Framework + + The Java security API's use a provider architecture that allows + applications to be implementation independent and security API + implementations to be modular and extensible. The + + + +Kabat & Upadhyay Standards Track [Page 13] + +RFC 2853 GSS-API Java Bindings June 2000 + + + java.security.Provider class is an abstract class that a vendor + extends. This class maps various properties that represent different + security services that are available to the names of the actual + vendor classes that implement those services. When requesting a + service, an application simply specifies the desired provider and the + API delegates the request to service classes available from that + provider. + + Using the Java security provider model insulates applications from + implementation details of the services they wish to use. + Applications can switch between providers easily and new providers + can be added as needed, even at runtime. + + The GSS-API may use providers to find components for specific + underlying security mechanisms. For instance, a particular provider + might contain components that will allow the GSS-API to support the + Kerberos v5 mechanism and another might contain components to support + the SPKM mechanism. By delegating mechanism specific functionality + to the components obtained from providers the GSS-API can be extended + to support an arbitrary list of mechanism. + + How the GSS-API locates and queries these providers is beyond the + scope of this document and is being deferred to a Service Provider + Interface (SPI) specification. The availability of such a SPI + specification is not mandatory for the adoption of this API + specification nor is it mandatory to use providers in the + implementation of a GSS-API framework. However, by using the provider + framework together with an SPI specification one can create an + extensible and implementation independent GSS-API framework. + +4.3. Integer types + + All numeric values are declared as "int" primitive Java type. The + Java specification guarantees that this will be a 32 bit two's + complement signed number. + + Throughout this API, the "boolean" primitive Java type is used + wherever a boolean value is required or returned. + +4.4. Opaque Data types + + Java byte arrays are used to represent opaque data types which are + consumed and produced by the GSS-API in the forms of tokens. Java + arrays contain a length field which enables the users to easily + determine their size. The language has automatic garbage collection + which alleviates the need by developers to release memory and + simplifies buffer ownership issues. + + + + +Kabat & Upadhyay Standards Track [Page 14] + +RFC 2853 GSS-API Java Bindings June 2000 + + +4.5. Strings + + The String object will be used to represent all textual data. The + Java String object, transparently treats all characters as two-byte + Unicode characters which allows support for many locals. All + routines returning or accepting textual data will use the String + object. + +4.6. Object Identifiers + + An Oid object will be used to represent Universal Object Identifiers + (Oids). Oids are ISO-defined, hierarchically globally-interpretable + identifiers used within the GSS-API framework to identify security + mechanisms and name formats. The Oid object can be created from a + string representation of its dot notation (e.g. "1.3.6.1.5.6.2") as + well as from its ASN.1 DER encoding. Methods are also provided to + test equality and provide the DER representation for the object. + + An important feature of the Oid class is that its instances are + immutable - i.e. there are no methods defined that allow one to + change the contents of an Oid. This property allows one to treat + these objects as "statics" without the need to perform copies. + + Certain routines allow the usage of a default oid. A "null" value + can be used in those cases. + +4.7. Object Identifier Sets + + The Java bindings represents object identifiers sets as arrays of Oid + objects. All Java arrays contain a length field which allows for + easy manipulation and reference. + + In order to support the full functionality of RFC 2743, the Oid class + includes a method which checks for existence of an Oid object within + a specified array. This is equivalent in functionality to + gss_test_oid_set_member. The use of Java arrays and Java's automatic + garbage collection has eliminated the need for the following + routines: gss_create_empty_oid_set, gss_release_oid_set, and + gss_add_oid_set_member. Java GSS-API implementations will not + contain them. Java's automatic garbage collection and the immutable + property of the Oid object eliminates the complicated memory + management issues of the C counterpart. + + When ever a default value for an Object Identifier Set is required, a + "null" value can be used. Please consult the detailed method + description for details. + + + + + +Kabat & Upadhyay Standards Track [Page 15] + +RFC 2853 GSS-API Java Bindings June 2000 + + +4.8. Credentials + + GSS-API credentials are represented by the GSSCredential interface. + The interface contains several constructs to allow for the creation + of most common credential objects for the initiator and the acceptor. + Comparisons are performed using the interface's "equals" method. The + following general description of GSS-API credentials is included from + the C-bindings specification: + + GSS-API credentials can contain mechanism-specific principal + authentication data for multiple mechanisms. A GSS-API credential is + composed of a set of credential-elements, each of which is applicable + to a single mechanism. A credential may contain at most one + credential-element for each supported mechanism. A credential- + element identifies the data needed by a single mechanism to + authenticate a single principal, and conceptually contains two + credential-references that describe the actual mechanism-specific + authentication data, one to be used by GSS-API for initiating + contexts, and one to be used for accepting contexts. For mechanisms + that do not distinguish between acceptor and initiator credentials, + both references would point to the same underlying mechanism-specific + authentication data. + + Credentials describe a set of mechanism-specific principals, and give + their holder the ability to act as any of those principals. All + principal identities asserted by a single GSS-API credential should + belong to the same entity, although enforcement of this property is + an implementation-specific matter. A single GSSCredential object + represents all the credential elements that have been acquired. + + The creation's of an GSSContext object allows the value of "null" to + be specified as the GSSCredential input parameter. This will + indicate a desire by the application to act as a default principal. + While individual GSS-API implementations are free to determine such + default behavior as appropriate to the mechanism, the following + default behavior by these routines is recommended for portability: + + For the initiator side of the context: + + 1) If there is only a single principal capable of initiating + security contexts for the chosen mechanism that the application + is authorized to act on behalf of, then that principal shall be + used, otherwise + + + + + + + + +Kabat & Upadhyay Standards Track [Page 16] + +RFC 2853 GSS-API Java Bindings June 2000 + + + 2) If the platform maintains a concept of a default network- + identity for the chosen mechanism, and if the application is + authorized to act on behalf of that identity for the purpose of + initiating security contexts, then the principal corresponding + to that identity shall be used, otherwise + + 3) If the platform maintains a concept of a default local + identity, and provides a means to map local identities into + network-identities for the chosen mechanism, and if the + application is authorized to act on behalf of the network- + identity image of the default local identity for the purpose of + initiating security contexts using the chosen mechanism, then + the principal corresponding to that identity shall be used, + otherwise + + 4) A user-configurable default identity should be used. + + and for the acceptor side of the context + + 1) If there is only a single authorized principal identity capable + of accepting security contexts for the chosen mechanism, then + that principal shall be used, otherwise + + 2) If the mechanism can determine the identity of the target + principal by examining the context-establishment token + processed during the accept method, and if the accepting + application is authorized to act as that principal for the + purpose of accepting security contexts using the chosen + mechanism, then that principal identity shall be used, + otherwise + + 3) If the mechanism supports context acceptance by any principal, + and if mutual authentication was not requested, any principal + that the application is authorized to accept security contexts + under using the chosen mechanism may be used, otherwise + + 4) A user-configurable default identity shall be used. + + The purpose of the above rules is to allow security contexts to be + established by both initiator and acceptor using the default behavior + whenever possible. Applications requesting default behavior are + likely to be more portable across mechanisms and implementations than + ones that instantiate an GSSCredential object representing a specific + identity. + + + + + + + +Kabat & Upadhyay Standards Track [Page 17] + +RFC 2853 GSS-API Java Bindings June 2000 + + +4.9. Contexts + + The GSSContext interface is used to represent one end of a GSS-API + security context, storing state information appropriate to that end + of the peer communication, including cryptographic state information. + The instantiation of the context object is done differently by the + initiator and the acceptor. After the context has been instantiated, + the initiator may choose to set various context options which will + determine the characteristics of the desired security context. When + all the application desired characteristics have been set, the + initiator will call the initSecContext method which will produce a + token for consumption by the peer's acceptSecContext method. It is + the responsibility of the application to deliver the authentication + token(s) between the peer applications for processing. Upon + completion of the context establishment phase, context attributes can + be retrieved, by both the initiator and acceptor, using the accessor + methods. These will reflect the actual attributes of the established + context. At this point the context can be used by the application to + apply cryptographic services to its data. + +4.10. Authentication tokens + + A token is a caller-opaque type that GSS-API uses to maintain + synchronization between each end of the GSS-API security context. + The token is a cryptographically protected octet-string, generated by + the underlying mechanism at one end of a GSS-API security context for + use by the peer mechanism at the other end. Encapsulation (if + required) within the application protocol and transfer of the token + are the responsibility of the peer applications. + + Java GSS-API uses byte arrays to represent authentication tokens. + Overloaded methods exist which allow the caller to supply input and + output streams which will be used for the reading and writing of the + token data. + +4.11. Interprocess tokens + + Certain GSS-API routines are intended to transfer data between + processes in multi-process programs. These routines use a caller- + opaque octet-string, generated by the GSS-API in one process for use + by the GSS-API in another process. The calling application is + responsible for transferring such tokens between processes. Note + that, while GSS-API implementors are encouraged to avoid placing + sensitive information within interprocess tokens, or to + cryptographically protect them, many implementations will be unable + to avoid placing key material or other sensitive data within them. + It is the application's responsibility to ensure that interprocess + tokens are protected in transit, and transferred only to processes + + + +Kabat & Upadhyay Standards Track [Page 18] + +RFC 2853 GSS-API Java Bindings June 2000 + + + that are trustworthy. An interprocess token is represented using a + byte array emitted from the export method of the GSSContext + interface. The receiver of the interprocess token would initialize + an GSSContext object with this token to create a new context. Once a + context has been exported, the GSSContext object is invalidated and + is no longer available. + +4.12. Error Reporting + + RFC 2743 defined the usage of major and minor status values for + signaling of GSS-API errors. The major code, also called GSS status + code, is used to signal errors at the GSS-API level independent of + the underlying mechanism(s). The minor status value or Mechanism + status code, is a mechanism defined error value indicating a + mechanism specific error code. + + Java GSS-API uses exceptions implemented by the GSSException class to + signal both minor and major error values. Both mechanism specific + errors and GSS-API level errors are signaled through instances of + this class. The usage of exceptions replaces the need for major and + minor codes to be used within the API calls. GSSException class also + contains methods to obtain textual representations for both the major + and minor values, which is equivalent to the functionality of + gss_display_status. + +4.12.1. GSS status codes + + GSS status codes indicate errors that are independent of the + underlying mechanism(s) used to provide the security service. The + errors that can be indicated via a GSS status code are generic API + routine errors (errors that are defined in the GSS-API + specification). These bindings take advantage of the Java exceptions + mechanism, thus eliminating the need for calling errors. + + A GSS status code indicates a single fatal generic API error from the + routine that has thrown the GSSException. Using exceptions announces + that a fatal error has occurred during the execution of the method. + The GSS-API operational model also allows for the signaling of + supplementary status information from the per-message calls. These + need to be handled as return values since using exceptions is not + appropriate for informatory or warning-like information. The methods + that are capable of producing supplementary information are the two + per-message methods GSSContext.verifyMIC() and GSSContext.unwrap(). + These methods fill the supplementary status codes in the MessageProp + object that was passed in. + + + + + + +Kabat & Upadhyay Standards Track [Page 19] + +RFC 2853 GSS-API Java Bindings June 2000 + + + GSSException object, along with providing the functionality for + setting of the various error codes and translating them into textual + representation, also contains the definitions of all the numeric + error values. The following table lists the definitions of error + codes: + + Table: GSS Status Codes + + Name Value Meaning + + BAD_MECH 1 An unsupported mechanism + was requested. + + BAD_NAME 2 An invalid name was supplied. + + BAD_NAMETYPE 3 A supplied name was of an + unsupported type. + + BAD_BINDINGS 4 Incorrect channel bindings were + supplied. + + BAD_STATUS 5 An invalid status code was + supplied. + + BAD_MIC 6 A token had an invalid MIC. + + NO_CRED 7 No credentials were supplied, or + the credentials were unavailable + or inaccessible. + + NO_CONTEXT 8 Invalid context has been + supplied. + + DEFECTIVE_TOKEN 9 A supplied token was invalid. + + DEFECTIVE_CREDENTIAL 10 A supplied credential was + invalid. + + CREDENTIALS_EXPIRED 11 The referenced credentials + have expired. + + CONTEXT_EXPIRED 12 The context has expired. + + FAILURE 13 Miscellaneous failure, + unspecified at the GSS-API level. + + BAD_QOP 14 The quality-of-protection + requested could not be provided. + + + +Kabat & Upadhyay Standards Track [Page 20] + +RFC 2853 GSS-API Java Bindings June 2000 + + + UNAUTHORIZED 15 The operation is forbidden by + local security policy. + + UNAVAILABLE 16 The operation or option is + unavailable. + + DUPLICATE_ELEMENT 17 The requested credential + element already exists. + + NAME_NOT_MN 18 The provided name was not a + mechanism name. + + OLD_TOKEN 19 The token's validity period has + expired. + + DUPLICATE_TOKEN 20 The token was a duplicate of an + earlier version. + + The GSS major status code of FAILURE is used to indicate that the + underlying mechanism detected an error for which no specific GSS + status code is defined. The mechanism-specific status code can + provide more details about the error. + + The different major status codes that can be contained in the + GSSException object thrown by the methods in this specification are + the same as the major status codes returned by the corresponding + calls in RFC 2743 [GSSAPIv2-UPDATE]. + +4.12.2. Mechanism-specific status codes + + Mechanism-specific status codes are communicated in two ways, they + are part of any GSSException thrown from the mechanism specific layer + to signal a fatal error, or they are part of the MessageProp object + that the per-message calls use to signal non-fatal errors. + + A default value of 0 in either the GSSException object or the + MessageProp object will be used to represent the absence of any + mechanism specific status code. + +4.12.3. Supplementary status codes + + Supplementary status codes are confined to the per-message methods of + the GSSContext interface. Because of the informative nature of these + errors it is not appropriate to use exceptions to signal them. + Instead, the per-message operations of the GSSContext interface + return these values in a MessageProp object. + + + + + +Kabat & Upadhyay Standards Track [Page 21] + +RFC 2853 GSS-API Java Bindings June 2000 + + + The MessageProp class defines query methods which return boolean + values indicating the following supplementary states: + + Table: Supplementary Status Methods + + Method Name Meaning when "true" is returned + + isDuplicateToken The token was a duplicate of an + earlier token. + + isOldToken The token's validity period has + expired. + + isUnseqToken A later token has already been + processed. + + isGapToken An expected per-message token was + not received. + + "true" return value for any of the above methods indicates that the + token exhibited the specified property. The application must + determine the appropriate course of action for these supplementary + values. They are not treated as errors by the GSS-API. + +4.13. Names + + A name is used to identify a person or entity. GSS-API authenticates + the relationship between a name and the entity claiming the name. + + Since different authentication mechanisms may employ different + namespaces for identifying their principals, GSS-API's naming support + is necessarily complex in multi-mechanism environments (or even in + some single-mechanism environments where the underlying mechanism + supports multiple namespaces). + + Two distinct conceptual representations are defined for names: + + 1) A GSS-API form represented by implementations of the GSSName + interface: A single GSSName object may contain multiple names from + different namespaces, but all names should refer to the same + entity. An example of such an internal name would be the name + returned from a call to the getName method of the GSSCredential + interface, when applied to a credential containing credential + elements for multiple authentication mechanisms employing + different namespaces. This GSSName object will contain a distinct + name for the entity for each authentication mechanism. + + + + + +Kabat & Upadhyay Standards Track [Page 22] + +RFC 2853 GSS-API Java Bindings June 2000 + + + For GSS-API implementations supporting multiple namespaces, + GSSName implementations must contain sufficient information to + determine the namespace to which each primitive name belongs. + + 2) Mechanism-specific contiguous byte array and string forms: + Different GSSName initialization methods are provided to handle + both byte array and string formats and to accommodate various + calling applications and name types. These formats are capable of + containing only a single name (from a single namespace). + Contiguous string names are always accompanied by an object + identifier specifying the namespace to which the name belongs, and + their format is dependent on the authentication mechanism that + employs that name. The string name forms are assumed to be + printable, and may therefore be used by GSS-API applications for + communication with their users. The byte array name formats are + assumed to be in non-printable formats (e.g. the byte array + returned from the export method of the GSSName interface). + + A GSSName object can be converted to a contiguous representation by + using the toString method. This will guarantee that the name will be + converted to a printable format. Different initialization methods in + the GSSName interface are defined allowing support for multiple + syntaxes for each supported namespace, and allowing users the freedom + to choose a preferred name representation. The toString method + should use an implementation-chosen printable syntax for each + supported name-type. To obtain the printable name type, + getStringNameType method can be used. + + There is no guarantee that calling the toString method on the GSSName + interface will produce the same string form as the original imported + string name. Furthermore, it is possible that the name was not even + constructed from a string representation. The same applies to name- + space identifiers which may not necessarily survive unchanged after a + journey through the internal name-form. An example of this might be + a mechanism that authenticates X.500 names, but provides an + algorithmic mapping of Internet DNS names into X.500. That + mechanism's implementation of GSSName might, when presented with a + DNS name, generate an internal name that contained both the original + DNS name and the equivalent X.500 name. Alternatively, it might only + store the X.500 name. In the latter case, the toString method of + GSSName would most likely generate a printable X.500 name, rather + than the original DNS name. + + The context acceptor can obtain a GSSName object representing the + entity performing the context initiation (through the usage of + getSrcName method). Since this name has been authenticated by a + single mechanism, it contains only a single name (even if the + internal name presented by the context initiator to the GSSContext + + + +Kabat & Upadhyay Standards Track [Page 23] + +RFC 2853 GSS-API Java Bindings June 2000 + + + object had multiple components). Such names are termed internal + mechanism names, or "MN"s and the names emitted by GSSContext + interface in the getSrcName and getTargName are always of this type. + Since some applications may require MNs without wanting to incur the + overhead of an authentication operation, creation methods are + provided that take not only the name buffer and name type, but also + the mechanism oid for which this name should be created. When + dealing with an existing GSSName object, the canonicalize method may + be invoked to convert a general internal name into an MN. + + GSSName objects can be compared using their equal method, which + returns "true" if the two names being compared refer to the same + entity. This is the preferred way to perform name comparisons + instead of using the printable names that a given GSS-API + implementation may support. Since GSS-API assumes that all primitive + names contained within a given internal name refer to the same + entity, equal can return "true" if the two names have at least one + primitive name in common. If the implementation embodies knowledge + of equivalence relationships between names taken from different + namespaces, this knowledge may also allow successful comparisons of + internal names containing no overlapping primitive elements. + + When used in large access control lists, the overhead of creating an + GSSName object on each name and invoking the equal method on each + name from the ACL may be prohibitive. As an alternative way of + supporting this case, GSS-API defines a special form of the + contiguous byte array name which may be compared directly (byte by + byte). Contiguous names suitable for comparison are generated by the + export method. Exported names may be re-imported by using the byte + array constructor and specifying the NT_EXPORT_NAME as the name type + object identifier. The resulting GSSName name will also be a MN. + The GSSName interface defines public static Oid objects representing + the standard name types. Structurally, an exported name object + consists of a header containing an OID identifying the mechanism that + authenticated the name, and a trailer containing the name itself, + where the syntax of the trailer is defined by the individual + mechanism specification. Detailed description of the format is + specified in the language-independent GSS-API specification + [GSSAPIv2-UPDATE]. + + Note that the results obtained by using the equals method will in + general be different from those obtained by invoking canonicalize and + export, and then comparing the byte array output. The first series + of operation determines whether two (unauthenticated) names identify + the same principal; the second whether a particular mechanism would + authenticate them as the same principal. These two operations will + in general give the same results only for MNs. + + + + +Kabat & Upadhyay Standards Track [Page 24] + +RFC 2853 GSS-API Java Bindings June 2000 + + + It is important to note that the above are guidelines as how GSSName + implementations should behave, and are not intended to be specific + requirements of how names objects must be implemented. The mechanism + designers are free to decide on the details of their implementations + of the GSSName interface as long as the behavior satisfies the above + guidelines. + +4.14. Channel Bindings + + GSS-API supports the use of user-specified tags to identify a given + context to the peer application. These tags are intended to be used + to identify the particular communications channel that carries the + context. Channel bindings are communicated to the GSS-API using the + ChannelBinding object. The application may use byte arrays to + specify the application data to be used in the channel binding as + well as using instances of the InetAddress. The InetAddress for the + initiator and/or acceptor can be used within an instance of a + ChannelBinding. ChannelBinding can be set for the GSSContext object + using the setChannelBinding method before the first call to init or + accept has been performed. Unless the setChannelBinding method has + been used to set the ChannelBinding for a GSSContext object, "null" + ChannelBinding will be assumed. InetAddress is currently the only + address type defined within the Java platform and as such, it is the + only one supported within the ChannelBinding class. Applications + that use other types of addresses can include them as part of the + application specific data. + + Conceptually, the GSS-API concatenates the initiator and acceptor + address information, and the application supplied byte array to form + an octet string. The mechanism calculates a MIC over this octet + string and binds the MIC to the context establishment token emitted + by init method of the GSSContext interface. The same bindings are + set by the context acceptor for its GSSContext object and during + processing of the accept method a MIC is calculated in the same way. + The calculated MIC is compared with that found in the token, and if + the MICs differ, accept will throw a GSSException with the major + code set to BAD_BINDINGS, and the context will not be established. + Some mechanisms may include the actual channel binding data in the + token (rather than just a MIC); applications should therefore not use + confidential data as channel-binding components. + + Individual mechanisms may impose additional constraints on addresses + that may appear in channel bindings. For example, a mechanism may + verify that the initiator address field of the channel binding + contains the correct network address of the host system. Portable + applications should therefore ensure that they either provide correct + information for the address fields, or omit setting of the addressing + information. + + + +Kabat & Upadhyay Standards Track [Page 25] + +RFC 2853 GSS-API Java Bindings June 2000 + + +4.15. Stream Objects + + The context object provides overloaded methods which use input and + output streams as the means to convey authentication and per-message + GSS-API tokens. It is important to note that the streams are + expected to contain the usual GSS-API tokens which would otherwise be + handled through the usage of byte arrays. The tokens are expected to + have a definite start and an end. The callers are responsible for + ensuring that the supplied streams will not block, or expect to block + until a full token is processed by the GSS-API method. Only a single + GSS-API token will be processed per invocation of the stream based + method. + + The usage of streams allows the callers to have control and + management of the supplied buffers. Because streams are non- + primitive objects, the callers can make the streams as complicated or + as simple as desired simply by using the streams defined in the + java.io package or creating their own through the use of inheritance. + This will allow for the application's greatest flexibility. + +4.16. Optional Parameters + + Whenever the application wishes to omit an optional parameter the + "null" value shall be used. The detailed method descriptions + indicate which parameters are optional. Methods overloading has also + been used as a technique to indicate default parameters. + +5. Introduction to GSS-API Classes and Interfaces + + This section presents a brief description of the classes and + interfaces that constitute the GSS-API. The implementations of these + are obtained from the CLASSPATH defined by the application. If Java + GSS becomes part of the standard Java API's then these classes will + be available by default on all systems as part of the JRE's system + classes. + + This section also shows the corresponding RFC 2743 functionality + implemented by each of the classes. Detailed description of these + classes and their methods is presented in section 6. + +5.1. GSSManager class + + This abstract class serves as a factory to instantiate + implementations of the GSS-API interfaces and also provides methods + to make queries about underlying security mechanisms. + + + + + + +Kabat & Upadhyay Standards Track [Page 26] + +RFC 2853 GSS-API Java Bindings June 2000 + + + A default implementation can be obtained using the static method + getInstance(). Applications that desire to provide their own + implementation of the GSSManager class can simply extend the abstract + class themselves. + + This class contains equivalents of the following RFC 2743 routines: + + gss_import_name Create an internal name from 6.1.9- + the supplied information. 6.1.12 + + gss_acquire_cred Acquire credential 6.1.13- + for use. 6.1.15 + + gss_import_sec_context Create a previously exported 6.1.18 + context. + + gss_indicate_mechs List the mechanisms 6.1.6 + supported by this GSS-API + implementation. + + gss_inquire_mechs_for_name List the mechanisms 6.1.8 + supporting the + specified name type. + + gss_inquire_names_for_mech List the name types 6.1.7 + supported by the + specified mechanism. + +5.2. GSSName interface + + GSS-API names are represented in the Java bindings through the + GSSName interface. Different name formats and their definitions are + identified with universal Object Identifiers (oids). The format of + the names can be derived based on the unique oid of each name type. + The following GSS-API routines are provided by the GSSName interface: + + RFC 2743 Routine Function Section(s) + + + gss_display_name Covert internal name 6.2.7 + representation to text format. + + gss_compare_name Compare two internal names. 6.2.3, 6.2.4 + + gss_release_name Release resources associated N/A + with the internal name. + + + + + +Kabat & Upadhyay Standards Track [Page 27] + +RFC 2853 GSS-API Java Bindings June 2000 + + + gss_canonicalize_name Convert an internal name to a 6.1.11, + mechanism name. + + gss_export_name Convert a mechanism name to 6.2.6 + export format. + + gss_duplicate_name Create a copy of the internal N/A + name. + + The gss_release_name call is not provided as Java does its own + garbage collection. The gss_duplicate_name call is also redundant; + the GSSName interface has no mutator methods that can change the + state of the object so it is safe for sharing. + +5.3. GSSCredential interface + + The GSSCredential interface is responsible for the encapsulation of + GSS-API credentials. Credentials identify a single entity and + provide the necessary cryptographic information to enable the + creation of a context on behalf of that entity. A single credential + may contain multiple mechanism specific credentials, each referred to + as a credential element. The GSSCredential interface provides the + functionality of the following GSS-API routines: + + RFC 2743 Routine Function Section(s) + + gss_add_cred Constructs credentials 6.3.12 + incrementally. + + gss_inquire_cred Obtain information about 6.3.4,6.3.5 + credential. + + gss_inquire_cred_by_mech Obtain per-mechanism 6.3.5-6.3.10 + information about + a credential. + + gss_release_cred Disposes of credentials 6.3.3 + after use. + +5.4. GSSContext interface + + This interface encapsulates the functionality of context-level calls + required for security context establishment and management between + peers as well as the per-message services offered to applications. A + context is established between a pair of peers and allows the usage + of security services on a per-message basis on application data. It + + + + + +Kabat & Upadhyay Standards Track [Page 28] + +RFC 2853 GSS-API Java Bindings June 2000 + + + is created over a single security mechanism. The GSSContext + interface provides the functionality of the following GSS-API + routines: + + RFC 2743 Routine Function Section(s) + + gss_init_sec_context Initiate the creation of a 6.4.3, + security context with a peer. 6.4.4 + + gss_accept_sec_context Accept a security context 6.4.5, + initiated by a peer. 6.4.6 + + gss_delete_sec_context Destroy a security context. 6.4.8 + + gss_context_time Obtain remaining context 6.4.37 + time. + + gss_inquire_context Obtain context 6.4.29 to + characteristics. 6.3.42 + + gss_wrap_size_limit Determine token-size limit 6.4.9 + for gss_wrap. + + gss_export_sec_context Transfer security context 6.4.18 + to another process. + + + gss_get_mic Calculate a cryptographic 6.4.14, + Message Integrity Code (MIC) 6.4.15 + for a message. + + gss_verify_mic Verify integrity on a received 6.4.16, + message. 6.4.17 + + gss_wrap Attach a MIC to a message and 6.4.10, + optionally encrypt the message 6.4.11 + content. + + gss_unwrap Obtain a previously wrapped 6.4.12, + application message verifying 6.4.13 + its integrity and optionally + decrypting it. + + The functionality offered by the gss_process_context_token routine + has not been included in the Java bindings specification. The + corresponding functionality of gss_delete_sec_context has also been + modified to not return any peer tokens. This has been proposed in + + + + +Kabat & Upadhyay Standards Track [Page 29] + +RFC 2853 GSS-API Java Bindings June 2000 + + + accordance to the recommendations stated in RFC 2743. GSSContext + does offer the functionality of destroying the locally-stored context + information. + +5.5. MessageProp class + + This helper class is used in the per-message operations on the + context. An instance of this class is created by the application and + then passed into the per-message calls. In some cases, the + application conveys information to the GSS-API implementation through + this object and in other cases the GSS-API returns information to the + application by setting it in this object. See the description of the + per-message operations wrap, unwrap, getMIC, and verifyMIC in the + GSSContext interfaces for details. + +5.6. GSSException class + + Exceptions are used in the Java bindings to signal fatal errors to + the calling applications. This replaces the major and minor codes + used in the C-bindings specification as a method of signaling + failures. The GSSException class handles both minor and major codes, + as well as their translation into textual representation. All GSS- + API methods are declared as throwing this exception. + + RFC 2743 Routine Function Section + + gss_display_status Retrieve textual 6.8.5, 6.8.6, + representation of error 6.8.8, 6.8.9 + codes. + +5.7. Oid class + + This utility class is used to represent Universal Object Identifiers + and their associated operations. GSS-API uses object identifiers to + distinguish between security mechanisms and name types. This class, + aside from being used whenever an object identifier is needed, + implements the following GSS-API functionality: + + RFC 2743 Routine Function Section + + gss_test_oid_set_member Determine if the specified oid 6.7.5 + is part of a set of oids. + + + + + + + + + +Kabat & Upadhyay Standards Track [Page 30] + +RFC 2853 GSS-API Java Bindings June 2000 + + +5.8. ChannelBinding class + + An instance of this class is used to specify channel binding + information to the GSSContext object before the start of a security + context establishment. The application may use a byte array to + specify application data to be used in the channel binding as well as + use instances of the InetAddress. InetAddress is currently the only + address type defined within the Java platform and as such, it is the + only one supported within the ChannelBinding class. Applications that + use other types of addresses can include them as part of the + application data. + +6. Detailed GSS-API Class Description + + This section lists a detailed description of all the public methods + that each of the GSS-API classes and interfaces must provide. + +6.1. public abstract class GSSManager + + The GSSManager class is an abstract class that serves as a factory + for three GSS interfaces: GSSName, GSSCredential, and GSSContext. It + also provides methods for applications to determine what mechanisms + are available from the GSS implementation and what nametypes these + mechanisms support. An instance of the default GSSManager subclass + may be obtained through the static method getInstance(), but + applications are free to instantiate other subclasses of GSSManager. + + All but one method in this class are declared abstract. This means + that subclasses have to provide the complete implementation for those + methods. The only exception to this is the static method + getInstance() which will have platform specific code to return an + instance of the default subclass. + + Platform providers of GSS are required not to add any constructors to + this class, private, public, or protected. This will ensure that all + subclasses invoke only the default constructor provided to the base + class by the compiler. + + A subclass extending the GSSManager abstract class may be implemented + as a modular provider based layer that utilizes some well known + service provider specification. The GSSManager API provides the + application with methods to set provider preferences on such an + implementation. These methods also allow the implementation to throw + a well-defined exception in case provider based configuration is not + supported. Applications that expect to be portable should be aware of + this and recover cleanly by catching the exception. + + + + + +Kabat & Upadhyay Standards Track [Page 31] + +RFC 2853 GSS-API Java Bindings June 2000 + + + It is envisioned that there will be three most common ways in which + providers will be used: + + 1) The application does not care about what provider is used (the + default case). + + 2) The application wants a particular provider to be used + preferentially, either for a particular mechanism or all the + time, irrespective of mechanism. + + 3) The application wants to use the locally configured providers + as far as possible but if support is missing for one or more + mechanisms then it wants to fall back on its own provider. + + The GSSManager class has two methods that enable these modes of + usage: addProviderAtFront() and addProviderAtEnd(). These methods + have the effect of creating an ordered list of pairs + where each pair indicates a preference of provider for a given oid. + + The use of these methods does not require any knowledge of whatever + service provider specification the GSSManager subclass follows. It is + hoped that these methods will serve the needs of most applications. + Additional methods may be added to an extended GSSManager that could + be part of a service provider specification that is standardized + later. + +6.1.1. Example Code + + GSSManager mgr = GSSManager.getInstance(); + + // What mechs are available to us? + Oid[] supportedMechs = mgr.getMechs(); + + // Set a preference for the provider to be used when support is needed + // for the mechanisms "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1". + + Oid krb = new Oid("1.2.840.113554.1.2.2"); + Oid spkm1 = new Oid("1.3.6.1.5.5.1.1"); + + Provider p = (Provider) (new com.foo.security.Provider()); + + mgr.addProviderAtFront(p, krb); + mgr.addProviderAtFront(p, spkm1); + + // What name types does this spkm implementation support? + Oid[] nameTypes = mgr.getNamesForMech(spkm1); + + + + + +Kabat & Upadhyay Standards Track [Page 32] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.1.2. getInstance + + public static GSSManager getInstance() + + Returns the default GSSManager implementation. + +6.1.3. getMechs + + public abstract Oid[] getMechs() + + Returns an array of Oid objects indicating mechanisms available to + GSS-API callers. A "null" value is returned when no mechanism are + available (an example of this would be when mechanism are dynamically + configured, and currently no mechanisms are installed). + +6.1.4. getNamesForMech + + public abstract Oid[] getNamesForMech(Oid mech) + throws GSSException + + Returns name type Oid's supported by the specified mechanism. + + Parameters: + + mech The Oid object for the mechanism to query. + +6.1.5. getMechsForName + + public abstract Oid[] getMechsForName(Oid nameType) + + Returns an array of Oid objects corresponding to the mechanisms that + support the specific name type. "null" is returned when no + mechanisms are found to support the specified name type. + + Parameters: + + nameType The Oid object for the name type. + +6.1.6. createName + + public abstract GSSName createName(String nameStr, Oid nameType) + throws GSSException + + Factory method to convert a contiguous string name from the specified + namespace to a GSSName object. In general, the GSSName object + created will not be an MN; two examples that are exceptions to this + are when the namespace type parameter indicates NT_EXPORT_NAME or + when the GSS-API implementation is not multi-mechanism. + + + +Kabat & Upadhyay Standards Track [Page 33] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Parameters: + + nameStr The string representing a printable form of the name + to create. + + nameType The Oid specifying the namespace of the printable name + supplied. Note that nameType serves to describe and + qualify the interpretation of the input nameStr, it + does not necessarily imply a type for the output + GSSName implementation. "null" value can be used to + specify that a mechanism specific default printable + syntax should be assumed by each mechanism that + examines nameStr. + +6.1.7. createName + + public abstract GSSName createName(byte name[], Oid nameType) + throws GSSException + + Factory method to convert a contiguous byte array containing a name + from the specified namespace to a GSSName object. In general, the + GSSName object created will not be an MN; two examples that are + exceptions to this are when the namespace type parameter indicates + NT_EXPORT_NAME or when the GSS-API implementation is not multi- + mechanism. + + Parameters: + + name The byte array containing the name to create. + + nameType The Oid specifying the namespace of the name supplied + in the byte array. Note that nameType serves to + describe and qualify the interpretation of the input + name byte array, it does not necessarily imply a type + for the output GSSName implementation. "null" value + can be used to specify that a mechanism specific + default syntax should be assumed by each mechanism + that examines the byte array. + + + + + + + + + + + + + +Kabat & Upadhyay Standards Track [Page 34] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.1.8. createName + + public abstract GSSName createName(String nameStr, Oid nameType, + Oid mech) throws GSSException + + Factory method to convert a contiguous string name from the specified + namespace to an GSSName object that is a mechanism name (MN). In + other words, this method is a utility that does the equivalent of two + steps: the createName described in 6.1.7 and then also the + GSSName.canonicalize() described in 6.2.5. + + Parameters: + + nameStr The string representing a printable form of the name + to create. + + nameType The Oid specifying the namespace of the printable name + supplied. Note that nameType serves to describe and + qualify the interpretation of the input nameStr, it + does not necessarily imply a type for the output + GSSName implementation. "null" value can be used to + specify that a mechanism specific default printable + syntax should be assumed when the mechanism examines + nameStr. + + mech Oid specifying the mechanism for which this name + should be created. + +6.1.9. createName + + public abstract createName(byte name[], Oid nameType, Oid mech) + throws GSSException + + Factory method to convert a contiguous byte array containing a name + from the specified namespace to a GSSName object that is an MN. In + other words, this method is a utility that does the equivalent of two + steps: the createName described in 6.1.8 and then also the + GSSName.canonicalize() described in 6.2.5. + + Parameters: + + name The byte array representing the name to create. + + nameType The Oid specifying the namespace of the name supplied + in the byte array. Note that nameType serves to + describe and qualify the interpretation of the input + name byte array, it does not necessarily imply a type + for the output GSSName implementation. "null" value + + + +Kabat & Upadhyay Standards Track [Page 35] + +RFC 2853 GSS-API Java Bindings June 2000 + + + can be used to specify that a mechanism specific + default syntax should be assumed by each mechanism + that examines the byte array. + + mech Oid specifying the mechanism for which this name + should be created. + +6.1.10. createCredential + + public abstract GSSCredential createCredential (int usage) + throws GSSException + + Factory method for acquiring default credentials. This will cause + the GSS-API to use system specific defaults for the set of + mechanisms, name, and a DEFAULT lifetime. + + Parameters: + + usage The intended usage for this credential object. The + value of this parameter must be one of: + GSSCredential.ACCEPT_AND_INITIATE, + GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY + +6.1.11. createCredential + + public abstract GSSCredential createCredential (GSSName aName, + int lifetime, Oid mech, int usage) + throws GSSException + + Factory method for acquiring a single mechanism credential. + + Parameters: + + aName Name of the principal for whom this credential is to + be acquired. Use "null" to specify the default + principal. + + lifetime The number of seconds that credentials should remain + valid. Use GSSCredential.INDEFINITE_LIFETIME to + request that the credentials have the maximum + permitted lifetime. Use + GSSCredential.DEFAULT_LIFETIME to request default + credential lifetime. + + mech The oid of the desired mechanism. Use "(Oid) null" to + request the default mechanism(s). + + + + + +Kabat & Upadhyay Standards Track [Page 36] + +RFC 2853 GSS-API Java Bindings June 2000 + + + usage The intended usage for this credential object. The + value of this parameter must be one of: + GSSCredential.ACCEPT_AND_INITIATE, + GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY + +6.1.12. createCredential + + public abstract GSSCredential createCredential(GSSName aName, + int lifetime, Oid mechs[], int usage) + throws GSSException + + Factory method for acquiring credentials over a set of mechanisms. + Acquires credentials for each of the mechanisms specified in the + array called mechs. To determine the list of mechanisms' for which + the acquisition of credentials succeeded, the caller should use the + GSSCredential.getMechs() method. + + Parameters: + + aName Name of the principal for whom this credential is to + be acquired. Use "null" to specify the default + principal. + + lifetime The number of seconds that credentials should remain + valid. Use GSSCredential.INDEFINITE_LIFETIME to + request that the credentials have the maximum + permitted lifetime. Use + GSSCredential.DEFAULT_LIFETIME to request default + credential lifetime. + + mechs The array of mechanisms over which the credential is + to be acquired. Use "(Oid[]) null" for requesting a + system specific default set of mechanisms. + + usage The intended usage for this credential object. The + value of this parameter must be one of: + GSSCredential.ACCEPT_AND_INITIATE, + GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY + +6.1.13. createContext + + public abstract GSSContext createContext(GSSName peer, Oid mech, + GSSCredential myCred, int lifetime) + throws GSSException + + Factory method for creating a context on the initiator's side. + Context flags may be modified through the mutator methods prior to + calling GSSContext.initSecContext(). + + + +Kabat & Upadhyay Standards Track [Page 37] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Parameters: + + peer Name of the target peer. + + mech Oid of the desired mechanism. Use "(Oid) null" to + request default mechanism. + + myCred Credentials of the initiator. Use "null" to act as a + default initiator principal. + + lifetime The request lifetime, in seconds, for the context. + Use GSSContext.INDEFINITE_LIFETIME and + GSSContext.DEFAULT_LIFETIME to request indefinite or + default context lifetime. + +6.1.14. createContext + + public abstract GSSContext createContext(GSSCredential myCred) + throws GSSException + + Factory method for creating a context on the acceptor' side. The + context's properties will be determined from the input token supplied + to the accept method. + + Parameters: + + myCred Credentials for the acceptor. Use "null" to act as a + default acceptor principal. + +6.1.15. createContext + + public abstract GSSContext createContext(byte [] interProcessToken) + throws GSSException + + Factory method for creating a previously exported context. The + context properties will be determined from the input token and can't + be modified through the set methods. + + Parameters: + + interProcessToken + The token previously emitted from the export method. + +6.1.16. addProviderAtFront + + public abstract void addProviderAtFront(Provider p, Oid mech) + throws GSSException + + + + +Kabat & Upadhyay Standards Track [Page 38] + +RFC 2853 GSS-API Java Bindings June 2000 + + + This method is used to indicate to the GSSManager that the + application would like a particular provider to be used ahead of all + others when support is desired for the given mechanism. When a value + of null is used instead of an Oid for the mechanism, the GSSManager + must use the indicated provider ahead of all others no matter what + the mechanism is. Only when the indicated provider does not support + the needed mechanism should the GSSManager move on to a different + provider. + + Calling this method repeatedly preserves the older settings but + lowers them in preference thus forming an ordered list of provider + and Oid pairs that grows at the top. + + Calling addProviderAtFront with a null Oid will remove all previous + preferences that were set for this provider in the GSSManager + instance. Calling addProviderAtFront with a non-null Oid will remove + any previous preference that was set using this mechanism and this + provider together. + + If the GSSManager implementation does not support an SPI with a + pluggable provider architecture it should throw a GSSException with + the status code GSSException.UNAVAILABLE to indicate that the + operation is unavailable. + + Parameters: + + p The provider instance that should be used whenever + support is needed for mech. + + mech The mechanism for which the provider is being set + +6.1.16.1. Example Code + + Suppose an application desired that the provider A always be checked + first when any mechanism is needed, it would call: + + GSSManager mgr = GSSManager.getInstance(); + // mgr may at this point have its own pre-configured list + // of provider preferences. The following will prepend to + // any such list: + + mgr.addProviderAtFront(A, null); + + Now if it also desired that the mechanism of Oid m1 always be + obtained from the provider B before the previously set A was checked, + it would call: + + mgr.addProviderAtFront(B, m1); + + + +Kabat & Upadhyay Standards Track [Page 39] + +RFC 2853 GSS-API Java Bindings June 2000 + + + The GSSManager would then first check with B if m1 was needed. In + case B did not provide support for m1, the GSSManager would continue + on to check with A. If any mechanism m2 is needed where m2 is + different from m1 then the GSSManager would skip B and check with A + directly. + + Suppose at a later time the following call is made to the same + GSSManager instance: + + mgr.addProviderAtFront(B, null) + + then the previous setting with the pair (B, m1) is subsumed by this + and should be removed. Effectively the list of preferences now + becomes {(B, null), (A, null), + ... //followed by the pre-configured list. + + Please note, however, that the following call: + + mgr.addProviderAtFront(A, m3) + + does not subsume the previous setting of (A, null) and the list will + effectively become {(A, m3), (B, null), (A, null), ...} + +6.1.17. addProviderAtEnd + + public abstract addProviderAtEnd(Provider p, Oid mech) + throws GSSException + + This method is used to indicate to the GSSManager that the + application would like a particular provider to be used if no other + provider can be found that supports the given mechanism. When a value + of null is used instead of an Oid for the mechanism, the GSSManager + must use the indicated provider for any mechanism. + + Calling this method repeatedly preserves the older settings but + raises them above newer ones in preference thus forming an ordered + list of providers and Oid pairs that grows at the bottom. Thus the + older provider settings will be utilized first before this one is. + + If there are any previously existing preferences that conflict with + the preference being set here, then the GSSManager should ignore this + request. + + If the GSSManager implementation does not support an SPI with a + pluggable provider architecture it should throw a GSSException with + the status code GSSException.UNAVAILABLE to indicate that the + operation is unavailable. + + + + +Kabat & Upadhyay Standards Track [Page 40] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Parameters: + + p The provider instance that should be used whenever + support is needed for mech. + + mech The mechanism for which the provider is being set + +6.1.17.1. Example Code + + Suppose an application desired that when a mechanism of Oid m1 is + needed the system default providers always be checked first, and only + when they do not support m1 should a provider A be checked. It would + then make the call: + + GSSManager mgr = GSSManager.getInstance(); + + mgr.addProviderAtEnd(A, m1); + + Now, if it also desired that for all mechanisms the provider B be + checked after all configured providers have been checked, it would + then call: + + mgr.addProviderAtEnd(B, null); + + Effectively the list of preferences now becomes {..., (A, m1), (B, + null)}. + + Suppose at a later time the following call is made to the same + GSSManager instance: + + mgr.addProviderAtEnd(B, m2) + + then the previous setting with the pair (B, null) subsumes this and + therefore this request should be ignored. The same would happen if a + request is made for the already existing pairs of (A, m1) or (B, + null). + + Please note, however, that the following call: + + mgr.addProviderAtEnd(A, null) + + is not subsumed by the previous setting of (A, m1) and the list will + effectively become {..., (A, m1), (B, null), (A, null)} + + + + + + + + +Kabat & Upadhyay Standards Track [Page 41] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.2. public interface GSSName + + This interface encapsulates a single GSS-API principal entity. + Different name formats and their definitions are identified with + universal Object Identifiers (Oids). The format of the names can be + derived based on the unique oid of its namespace type. + +6.2.1. Example Code + + Included below are code examples utilizing the GSSName interface. + The code below creates a GSSName, converts it to a mechanism name + (MN), performs a comparison, obtains a printable representation of + the name, exports it and then re-imports to obtain a new GSSName. + + GSSManager mgr = GSSManager.getInstance(); + + // create a host based service name + GSSName name = mgr.createName("service@host", + GSSName.NT_HOSTBASED_SERVICE); + + Oid krb5 = new Oid("1.2.840.113554.1.2.2"); + + GSSName mechName = name.canonicalize(krb5); + + // the above two steps are equivalent to the following + GSSName mechName = mgr.createName("service@host", + GSSName.NT_HOSTBASED_SERVICE, krb5); + + // perform name comparison + if (name.equals(mechName)) + print("Names are equals."); + + // obtain textual representation of name and its printable + // name type + print(mechName.toString() + + mechName.getStringNameType().toString()); + + // export and re-import the name + byte [] exportName = mechName.export(); + + // create a new name object from the exported buffer + GSSName newName = mgr.createName(exportName, + GSSName.NT_EXPORT_NAME); + + + + + + + + +Kabat & Upadhyay Standards Track [Page 42] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.2.2. Static Constants + + public static final Oid NT_HOSTBASED_SERVICE + + Oid indicating a host-based service name form. It is used to + represent services associated with host computers. This name form is + constructed using two elements, "service" and "hostname", as follows: + + service@hostname + + Values for the "service" element are registered with the IANA. It + represents the following value: { 1(iso), 3(org), 6(dod), + 1(internet), 5(security), 6(nametypes), 2(gss-host-based-services) } + + public static final Oid NT_USER_NAME + + Name type to indicate a named user on a local system. It represents + the following value: { iso(1) member-body(2) United States(840) + mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) } + + public static final Oid NT_MACHINE_UID_NAME + + Name type to indicate a numeric user identifier corresponding to a + user on a local system. (e.g. Uid). It represents the following + value: { iso(1) member-body(2) United States(840) mit(113554) + infosys(1) gssapi(2) generic(1) machine_uid_name(2) } + + public static final Oid NT_STRING_UID_NAME + + Name type to indicate a string of digits representing the numeric + user identifier of a user on a local system. It represents the + following value: { iso(1) member-body(2) United States(840) + mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) } + + public static final Oid NT_ANONYMOUS + + Name type for representing an anonymous entity. It represents the + following value: { 1(iso), 3(org), 6(dod), 1(internet), 5(security), + 6(nametypes), 3(gss-anonymous-name) } + + public static final Oid NT_EXPORT_NAME + + Name type used to indicate an exported name produced by the export + method. It represents the following value: { 1(iso), 3(org), 6(dod), + 1(internet), 5(security), 6(nametypes), 4(gss-api-exported-name) } + + + + + + +Kabat & Upadhyay Standards Track [Page 43] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.2.3. equals + + public boolean equals(GSSName another) throws GSSException + + Compares two GSSName objects to determine whether they refer to the + same entity. This method may throw a GSSException when the names + cannot be compared. If either of the names represents an anonymous + entity, the method will return "false". + + Parameters: + + another GSSName object to compare with. + +6.2.4. equals + + public boolean equals(Object another) + + A variation of the equals method described in 6.2.3 that is provided + to override the Object.equals() method that the implementing class + will inherit. The behavior is exactly the same as that in 6.2.3 + except that no GSSException is thrown; instead, false will be + returned in the situation where an error occurs. (Note that the Java + language specification requires that two objects that are equal + according to the equals(Object) method must return the same integer + result when the hashCode() method is called on them.) + + Parameters: + + another GSSName object to compare with. + +6.2.5. canonicalize + + public GSSName canonicalize(Oid mech) throws GSSException + + Creates a mechanism name (MN) from an arbitrary internal name. This + is equivalent to using the factory methods described in 6.1.9 or + 6.1.10 that take the mechanism name as one of their parameters. + + Parameters: + + mech The oid for the mechanism for which the canonical form + of the name is requested. + + + + + + + + + +Kabat & Upadhyay Standards Track [Page 44] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.2.6. export + + public byte[] export() throws GSSException + + Returns a canonical contiguous byte representation of a mechanism + name (MN), suitable for direct, byte by byte comparison by + authorization functions. If the name is not an MN, implementations + may throw a GSSException with the NAME_NOT_MN status code. If an + implementation chooses not to throw an exception, it should use some + system specific default mechanism to canonicalize the name and then + export it. The format of the header of the output buffer is + specified in RFC 2743. + +6.2.7. toString + + public String toString() + + Returns a textual representation of the GSSName object. To retrieve + the printed name format, which determines the syntax of the returned + string, the getStringNameType method can be used. + +6.2.8. getStringNameType + + public Oid getStringNameType() throws GSSException + + Returns the oid representing the type of name returned through the + toString method. Using this oid, the syntax of the printable name + can be determined. + +6.2.9. isAnonymous + + public boolean isAnonymous() + + Tests if this name object represents an anonymous entity. Returns + "true" if this is an anonymous name. + +6.2.10. isMN + + public boolean isMN() + + Tests if this name object contains only one mechanism element and is + thus a mechanism name as defined by RFC 2743. + +6.3. public interface GSSCredential implements Cloneable + + This interface encapsulates the GSS-API credentials for an entity. A + credential contains all the necessary cryptographic information to + enable the creation of a context on behalf of the entity that it + + + +Kabat & Upadhyay Standards Track [Page 45] + +RFC 2853 GSS-API Java Bindings June 2000 + + + represents. It may contain multiple, distinct, mechanism specific + credential elements, each containing information for a specific + security mechanism, but all referring to the same entity. + + A credential may be used to perform context initiation, acceptance, + or both. + + GSS-API implementations must impose a local access-control policy on + callers to prevent unauthorized callers from acquiring credentials to + which they are not entitled. GSS-API credential creation is not + intended to provide a "login to the network" function, as such a + function would involve the creation of new credentials rather than + merely acquiring a handle to existing credentials. Such functions, + if required, should be defined in implementation-specific extensions + to the API. + + If credential acquisition is time-consuming for a mechanism, the + mechanism may choose to delay the actual acquisition until the + credential is required (e.g. by GSSContext). Such mechanism- + specific implementation decisions should be invisible to the calling + application; thus the query methods immediately following the + creation of a credential object must return valid credential data, + and may therefore incur the overhead of a deferred credential + acquisition. + + Applications will create a credential object passing the desired + parameters. The application can then use the query methods to obtain + specific information about the instantiated credential object + (equivalent to the gss_inquire routines). When the credential is no + longer needed, the application should call the dispose (equivalent to + gss_release_cred) method to release any resources held by the + credential object and to destroy any cryptographically sensitive + information. + + Classes implementing this interface also implement the Cloneable + interface. This indicates the the class will support the clone() + method that will allow the creation of duplicate credentials. This + is useful when called just before the add() call to retain a copy of + the original credential. + +6.3.1. Example Code + + This example code demonstrates the creation of a GSSCredential + implementation for a specific entity, querying of its fields, and its + release when it is no longer needed. + + + + + + +Kabat & Upadhyay Standards Track [Page 46] + +RFC 2853 GSS-API Java Bindings June 2000 + + + GSSManager mgr = GSSManager.getInstance(); + + // start by creating a name object for the entity + GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME); + + // now acquire credentials for the entity + GSSCredential cred = mgr.createCredential(name, + GSSCredential.ACCEPT_ONLY); + + // display credential information - name, remaining lifetime, + // and the mechanisms it has been acquired over + print(cred.getName().toString()); + print(cred.getRemainingLifetime()); + + Oid [] mechs = cred.getMechs(); + if (mechs != null) { + for (int i = 0; i < mechs.length; i++) + print(mechs[i].toString()); + } + + // release system resources held by the credential + cred.dispose(); + +6.3.2. Static Constants + + public static final int INITIATE_AND_ACCEPT + + Credential usage flag requesting that it be able to be used for both + context initiation and acceptance. + + public static final int INITIATE_ONLY + + Credential usage flag requesting that it be able to be used for + context initiation only. + + public static final int ACCEPT_ONLY + + Credential usage flag requesting that it be able to be used for + context acceptance only. + + public static final int DEFAULT_LIFETIME + + A lifetime constant representing the default credential lifetime. + + This value must be set to 0. + + public static final int INDEFINITE_LIFETIME + + + + +Kabat & Upadhyay Standards Track [Page 47] + +RFC 2853 GSS-API Java Bindings June 2000 + + + A lifetime constant representing indefinite credential lifetime. + This value must be set to the maximum integer value in Java - + Integer.MAX_VALUE. + +6.3.3. dispose + + public void dispose() throws GSSException + + Releases any sensitive information that the GSSCredential object may + be containing. Applications should call this method as soon as the + credential is no longer needed to minimize the time any sensitive + information is maintained. + +6.3.4. getName + + public GSSName getName() throws GSSException + + Retrieves the name of the entity that the credential asserts. + +6.3.5. getName + + public GSSName getName(Oid mechOID) throws GSSException + + Retrieves a mechanism name of the entity that the credential asserts. + Equivalent to calling canonicalize() on the name returned by 7.3.3. + + Parameters: + + mechOID The mechanism for which information should be + returned. + +6.3.6. getRemainingLifetime + + public int getRemainingLifetime() throws GSSException + + Returns the remaining lifetime in seconds for a credential. The + remaining lifetime is the minimum lifetime for any of the underlying + credential mechanisms. A return value of + GSSCredential.INDEFINITE_LIFETIME indicates that the credential does + not expire. A return value of 0 indicates that the credential is + already expired. + + + + + + + + + + +Kabat & Upadhyay Standards Track [Page 48] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.3.7. getRemainingInitLifetime + + public int getRemainingInitLifetime(Oid mech) throws GSSException + + Returns the remaining lifetime is seconds for the credential to + remain capable of initiating security contexts under the specified + mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME + indicates that the credential does not expire for context initiation. + A return value of 0 indicates that the credential is already expired. + + Parameters: + + mechOID The mechanism for which information should be + returned. + +6.3.8. getRemainingAcceptLifetime + + public int getRemainingAcceptLifetime(Oid mech) throws GSSException + + Returns the remaining lifetime is seconds for the credential to + remain capable of accepting security contexts under the specified + mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME + indicates that the credential does not expire for context acceptance. + A return value of 0 indicates that the credential is already expired. + + Parameters: + + mechOID The mechanism for which information should be + returned. + +6.3.9. getUsage + + public int getUsage() throws GSSException + + Returns the credential usage flag. The return value will be one of + GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or + GSSCredential.INITIATE_AND_ACCEPT. + +6.3.10. getUsage + + public int getUsage(Oid mechOID) throws GSSException + + Returns the credential usage flag for the specified credential + mechanism. The return value will be one of + GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or + GSSCredential.INITIATE_AND_ACCEPT. + + + + + +Kabat & Upadhyay Standards Track [Page 49] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Parameters: + + mechOID The mechanism for which information should be + returned. + +6.3.11. getMechs + + public Oid[] getMechs() throws GSSException + + Returns an array of mechanisms supported by this credential. + +6.3.12. add + + public void add(GSSName aName, int initLifetime, int acceptLifetime, + Oid mech, int usage) throws GSSException + + Adds a mechanism specific credential-element to an existing + credential. This method allows the construction of credentials one + mechanism at a time. + + This routine is envisioned to be used mainly by context acceptors + during the creation of acceptance credentials which are to be used + with a variety of clients using different security mechanisms. + + This routine adds the new credential element "in-place". To add the + element in a new credential, first call clone() to obtain a copy of + this credential, then call its add() method. + + Parameters: + + aName Name of the principal for whom this credential is to + be acquired. Use "null" to specify the default + principal. + + initLifetime + The number of seconds that credentials should remain + valid for initiating of security contexts. Use + GSSCredential.INDEFINITE_LIFETIME to request that the + credentials have the maximum permitted lifetime. Use + GSSCredential.DEFAULT_LIFETIME to request default + credential lifetime. + + acceptLifetime + The number of seconds that credentials should remain + valid for accepting of security contexts. Use + GSSCredential.INDEFINITE_LIFETIME to request that the + + + + + +Kabat & Upadhyay Standards Track [Page 50] + +RFC 2853 GSS-API Java Bindings June 2000 + + + credentials have the maximum permitted lifetime. Use + GSSCredential.DEFAULT_LIFETIME to request default + credential lifetime. + + mech The mechanisms over which the credential is to be + acquired. + + usage The intended usage for this credential object. The + value of this parameter must be one of: + GSSCredential.ACCEPT_AND_INITIATE, + GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY + +6.3.13. equals + + public boolean equals(Object another) + + Tests if this GSSCredential refers to the same entity as the supplied + object. The two credentials must be acquired over the same + mechanisms and must refer to the same principal. Returns "true" if + the two GSSCredentials refer to the same entity; "false" otherwise. + (Note that the Java language specification requires that two objects + that are equal according to the equals(Object) method must return the + same integer result when the hashCode() method is called on them.) + + Parameters: + + another Another GSSCredential object for comparison. + +6.4. public interface GSSContext + + This interface encapsulates the GSS-API security context and provides + the security services (wrap, unwrap, getMIC, verifyMIC) that are + available over the context. Security contexts are established + between peers using locally acquired credentials. Multiple contexts + may exist simultaneously between a pair of peers, using the same or + different set of credentials. GSS-API functions in a manner + independent of the underlying transport protocol and depends on its + calling application to transport its tokens between peers. + + Before the context establishment phase is initiated, the context + initiator may request specific characteristics desired of the + established context. These can be set using the set methods. After + the context is established, the caller can check the actual + characteristic and services offered by the context using the query + methods. + + + + + + +Kabat & Upadhyay Standards Track [Page 51] + +RFC 2853 GSS-API Java Bindings June 2000 + + + The context establishment phase begins with the first call to the + init method by the context initiator. During this phase the + initSecContext and acceptSecContext methods will produce GSS-API + authentication tokens which the calling application needs to send to + its peer. If an error occurs at any point, an exception will get + thrown and the code will start executing in a catch block. If not, + the normal flow of code continues and the application can make a call + to the isEstablished() method. If this method returns false it + indicates that a token is needed from its peer in order to continue + the context establishment phase. A return value of true signals that + the local end of the context is established. This may still require + that a token be sent to the peer, if one is produced by GSS-API. + During the context establishment phase, the isProtReady() method may + be called to determine if the context can be used for the per-message + operations. This allows applications to use per-message operations + on contexts which aren't fully established. + + After the context has been established or the isProtReady() method + returns "true", the query routines can be invoked to determine the + actual characteristics and services of the established context. The + application can also start using the per-message methods of wrap and + getMIC to obtain cryptographic operations on application supplied + data. + + When the context is no longer needed, the application should call + dispose to release any system resources the context may be using. + +6.4.1. Example Code + + The example code presented below demonstrates the usage of the + GSSContext interface for the initiating peer. Different operations + on the GSSContext object are presented, including: object + instantiation, setting of desired flags, context establishment, query + of actual context flags, per-message operations on application data, + and finally context deletion. + + GSSManager mgr = GSSManager.getInstance(); + + // start by creating the name for a service entity + GSSName targetName = mgr.createName("service@host", + GSSName.NT_HOSTBASED_SERVICE); + + // create a context using default credentials for the above entity + // and the implementation specific default mechanism + GSSContext context = mgr.createContext(targetName, + null, /* default mechanism */ + null, /* default credentials */ + GSSContext.INDEFINITE_LIFETIME); + + + +Kabat & Upadhyay Standards Track [Page 52] + +RFC 2853 GSS-API Java Bindings June 2000 + + + // set desired context options - all others are false by default + context.requestConf(true); + context.requestMutualAuth(true); + context.requestReplayDet(true); + context.requestSequenceDet(true); + + // establish a context between peers - using byte arrays + byte []inTok = new byte[0]; + + try { + do { + byte[] outTok = context.initSecContext(inTok, 0, + inTok.length); + + // send the token if present + if (outTok != null) + sendToken(outTok); + + // check if we should expect more tokens + if (context.isEstablished()) + break; + + // another token expected from peer + inTok = readToken(); + + } while (true); + + } catch (GSSException e) { + print("GSSAPI error: " + e.getMessage()); + } + + + // display context information + print("Remaining lifetime in seconds = " + context.getLifetime()); + print("Context mechanism = " + context.getMech().toString()); + print("Initiator = " + context.getSrcName().toString()); + print("Acceptor = " + context.getTargName().toString()); + + if (context.getConfState()) + print("Confidentiality security service available"); + + if (context.getIntegState()) + print("Integrity security service available"); + + // perform wrap on an application supplied message, appMsg, + // using QOP = 0, and requesting privacy service + byte [] appMsg ... + + + + +Kabat & Upadhyay Standards Track [Page 53] + +RFC 2853 GSS-API Java Bindings June 2000 + + + MessageProp mProp = new MessageProp(0, true); + + byte []tok = context.wrap(appMsg, 0, appMsg.length, mProp); + + if (mProp.getPrivacy()) + print("Message protected with privacy."); + + sendToken(tok); + + + // release the local-end of the context + context.dispose(); + +6.4.2. Static Constants + + public static final int DEFAULT_LIFETIME + + A lifetime constant representing the default context lifetime. This + value must be set to 0. + + public static final int INDEFINITE_LIFETIME + + A lifetime constant representing indefinite context lifetime. This + value must be set to the maximum integer value in Java - + Integer.MAX_VALUE. + +6.4.3. initSecContext + + public byte[] initSecContext(byte inputBuf[], int offset, int len) + throws GSSException + + Called by the context initiator to start the context creation + process. This is equivalent to the stream based method except that + the token buffers are handled as byte arrays instead of using stream + objects. This method may return an output token which the + application will need to send to the peer for processing by the + accept call. Typically, the application would do so by calling the + flush() method on an OutputStream that encapsulates the connection + between the two peers. The application can call isEstablished() to + determine if the context establishment phase is complete for this + peer. A return value of "false" from isEstablished() indicates that + more tokens are expected to be supplied to the initSecContext() + method. Note that it is possible that the initSecContext() method + return a token for the peer, and isEstablished() return "true" also. + This indicates that the token needs to be sent to the peer, but the + local end of the context is now fully established. + + + + + +Kabat & Upadhyay Standards Track [Page 54] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Upon completion of the context establishment, the available context + options may be queried through the get methods. + + Parameters: + + inputBuf Token generated by the peer. This parameter is ignored + on the first call. + + offset The offset within the inputBuf where the token begins. + + len The length of the token within the inputBuf (starting + at the offset). + +6.4.3.1. Example Code + + // Create a new GSSContext implementation object. + // GSSContext wrapper implements interface GSSContext. + GSSContext context = mgr.createContext(...); + + + byte []inTok = new byte[0]; + + try { + + do { + byte[] outTok = context.initSecContext(inTok, 0, + inTok.length); + + // send the token if present + if (outTok != null) + sendToken(outTok); + + + // check if we should expect more tokens + if (context.isEstablished()) + break; + + // another token expected from peer + inTok = readToken(); + } while (true); + + } catch (GSSException e) { + print("GSSAPI error: " + e.getMessage()); + } + + + + + + + +Kabat & Upadhyay Standards Track [Page 55] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.4.4. initSecContext + + public int initSecContext(InputStream inStream, + OutputStream outStream) throws GSSException + + Called by the context initiator to start the context creation + process. This is equivalent to the byte array based method. This + method may write an output token to the outStream, which the + application will need to send to the peer for processing by the + accept call. Typically, the application would do so by calling the + flush() method on an OutputStream that encapsulates the connection + between the two peers. The application can call isEstablished() to + determine if the context establishment phase is complete for this + peer. A return value of "false" from isEstablished indicates that + more tokens are expected to be supplied to the initSecContext method. + Note that it is possible that the initSecContext() method return a + token for the peer, and isEstablished() return "true" also. This + indicates that the token needs to be sent to the peer, but the local + end of the context is now fully established. + + The GSS-API authentication tokens contain a definitive start and end. + This method will attempt to read one of these tokens per invocation, + and may block on the stream if only part of the token is available. + + Upon completion of the context establishment, the available context + options may be queried through the get methods. + + Parameters: + + inStream Contains the token generated by the peer. This + parameter is ignored on the first call. + + outStream Output stream where the output token will be written. + During the final stage of context establishment, there + may be no bytes written. + +6.4.4.1. Example Code + + This sample code merely demonstrates the token exchange during the + context establishment phase. It is expected that most Java + applications will use custom implementations of the Input and Output + streams that encapsulate the communication routines. For instance, a + simple read on the application InputStream, when called by the + Context, might cause a token to be read from the peer, and a simple + flush() on the application OutputStream might cause a previously + written token to be transmitted to the peer. + + // Create a new GSSContext implementation object. + + + +Kabat & Upadhyay Standards Track [Page 56] + +RFC 2853 GSS-API Java Bindings June 2000 + + + // GSSContext wrapper implements interface GSSContext. + GSSContext context = mgr.createContext(...); + + // use standard java.io stream objects + ByteArrayOutputStream os = new ByteArrayOutputStream(); + ByteArrayInputStream is = null; + + + try { + + do { + context.initSecContext(is, os); + + // send token if present + if (os.size() > 0) + sendToken(os); + + // check if we should expect more tokens + if (context.isEstablished()) + break; + + // another token expected from peer + is = recvToken(); + + } while (true); + + } catch (GSSException e) { + print("GSSAPI error: " + e.getMessage()); + } + +6.4.5. acceptSecContext + + public byte[] acceptSecContext(byte inTok[], int offset, int len) + throws GSSException + + Called by the context acceptor upon receiving a token from the peer. + This call is equivalent to the stream based method except that the + token buffers are handled as byte arrays instead of using stream + objects. + + This method may return an output token which the application will + need to send to the peer for further processing by the init call. + + "null" return value indicates that no token needs to be sent to the + peer. The application can call isEstablished() to determine if the + context establishment phase is complete for this peer. A return + value of "false" from isEstablished() indicates that more tokens are + expected to be supplied to this method. + + + +Kabat & Upadhyay Standards Track [Page 57] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Note that it is possible that acceptSecContext() return a token for + the peer, and isEstablished() return "true" also. This indicates + that the token needs to be sent to the peer, but the local end of the + context is now fully established. + + Upon completion of the context establishment, the available context + options may be queried through the get methods. + + Parameters: + + inTok Token generated by the peer. + + offset The offset within the inTok where the token begins. + + len The length of the token within the inTok (starting at + the offset). + +6.4.5.1. Example Code + + // acquire server credentials + GSSCredential server = mgr.createCredential(...); + + // create acceptor GSS-API context from the default provider + GSSContext context = mgr.createContext(server, null); + + try { + do { + byte [] inTok = readToken(); + + byte []outTok = context.acceptSecContext(inTok, 0, + inTok.length); + + // possibly send token to peer + if (outTok != null) + sendToken(outTok); + + // check if local context establishment is complete + if (context.isEstablished()) + break; + } while (true); + + } catch (GSSException e) { + print("GSS-API error: " + e.getMessage()); + } + + + + + + + +Kabat & Upadhyay Standards Track [Page 58] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.4.6. acceptSecContext + + public void acceptSecContext(InputStream inStream, + OutputStream outStream) throws GSSException + + Called by the context acceptor upon receiving a token from the peer. + This call is equivalent to the byte array method. It may write an + output token to the outStream, which the application will need to + send to the peer for processing by its initSecContext method. + Typically, the application would do so by calling the flush() method + on an OutputStream that encapsulates the connection between the two + peers. The application can call isEstablished() to determine if the + context establishment phase is complete for this peer. A return + value of "false" from isEstablished() indicates that more tokens are + expected to be supplied to this method. + + Note that it is possible that acceptSecContext() return a token for + the peer, and isEstablished() return "true" also. This indicates + that the token needs to be sent to the peer, but the local end of the + context is now fully established. + + The GSS-API authentication tokens contain a definitive start and end. + This method will attempt to read one of these tokens per invocation, + and may block on the stream if only part of the token is available. + + Upon completion of the context establishment, the available context + options may be queried through the get methods. + + Parameters: + + inStream Contains the token generated by the peer. + + outStream Output stream where the output token will be written. + During the final stage of context establishment, there + may be no bytes written. + +6.4.6.1. Example Code + + This sample code merely demonstrates the token exchange during the + context establishment phase. It is expected that most Java + applications will use custom implementations of the Input and Output + streams that encapsulate the communication routines. For instance, a + simple read on the application InputStream, when called by the + Context, might cause a token to be read from the peer, and a simple + flush() on the application OutputStream might cause a previously + written token to be transmitted to the peer. + + // acquire server credentials + + + +Kabat & Upadhyay Standards Track [Page 59] + +RFC 2853 GSS-API Java Bindings June 2000 + + + GSSCredential server = mgr.createCredential(...); + + // create acceptor GSS-API context from the default provider + GSSContext context = mgr.createContext(server, null); + + // use standard java.io stream objects + ByteArrayOutputStream os = new ByteArrayOutputStream(); + ByteArrayInputStream is = null; + + try { + do { + + is = recvToken(); + + context.acceptSecContext(is, os); + + // possibly send token to peer + if (os.size() > 0) + sendToken(os); + + // check if local context establishment is complete + if (context.isEstablished()) + break; + } while (true); + + } catch (GSSException e) { + print("GSS-API error: " + e.getMessage()); + } + +6.4.7. isEstablished + + public boolean isEstablished() + + Used during context establishment to determine the state of the + context. Returns "true" if this is a fully established context on + the caller's side and no more tokens are needed from the peer. + Should be called after a call to initSecContext() or + acceptSecContext() when no GSSException is thrown. + +6.4.8. dispose + + public void dispose() throws GSSException + + Releases any system resources and cryptographic information stored in + the context object. This will invalidate the context. + + + + + + +Kabat & Upadhyay Standards Track [Page 60] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.4.9. getWrapSizeLimit + + public int getWrapSizeLimit(int qop, boolean confReq, + int maxTokenSize) throws GSSException + + Returns the maximum message size that, if presented to the wrap + method with the same confReq and qop parameters, will result in an + output token containing no more than the maxTokenSize bytes. + + This call is intended for use by applications that communicate over + protocols that impose a maximum message size. It enables the + application to fragment messages prior to applying protection. + + GSS-API implementations are recommended but not required to detect + invalid QOP values when getWrapSizeLimit is called. This routine + guarantees only a maximum message size, not the availability of + specific QOP values for message protection. + + Successful completion of this call does not guarantee that wrap will + be able to protect a message of the computed length, since this + ability may depend on the availability of system resources at the + time that wrap is called. However, if the implementation itself + imposes an upper limit on the length of messages that may be + processed by wrap, the implementation should not return a value that + is greater than this length. + + Parameters: + + qop Indicates the level of protection wrap will be asked + to provide. + + confReq Indicates if wrap will be asked to provide privacy + service. + + maxTokenSize + The desired maximum size of the token emitted by wrap. + +6.4.10. wrap + + public byte[] wrap(byte inBuf[], int offset, int len, + MessageProp msgProp) throws GSSException + + Applies per-message security services over the established security + context. The method will return a token with a cryptographic MIC and + may optionally encrypt the specified inBuf. This method is + equivalent in functionality to its stream counterpart. The returned + byte array will contain both the MIC and the message. + + + + +Kabat & Upadhyay Standards Track [Page 61] + +RFC 2853 GSS-API Java Bindings June 2000 + + + The MessageProp object is instantiated by the application and used to + specify a QOP value which selects cryptographic algorithms, and a + privacy service to optionally encrypt the message. The underlying + mechanism that is used in the call may not be able to provide the + privacy service. It sets the actual privacy service that it does + provide in this MessageProp object which the caller should then query + upon return. If the mechanism is not able to provide the requested + QOP, it throws a GSSException with the BAD_QOP code. + + Since some application-level protocols may wish to use tokens emitted + by wrap to provide "secure framing", implementations should support + the wrapping of zero-length messages. + + The application will be responsible for sending the token to the + peer. + + Parameters: + + inBuf Application data to be protected. + + offset The offset within the inBuf where the data begins. + + len The length of the data within the inBuf (starting at + the offset). + + msgProp Instance of MessageProp that is used by the + application to set the desired QOP and privacy state. + Set the desired QOP to 0 to request the default QOP. + Upon return from this method, this object will contain + the the actual privacy state that was applied to the + message by the underlying mechanism. + +6.4.11. wrap + + public void wrap(InputStream inStream, OutputStream outStream, + MessageProp msgProp) throws GSSException + + Allows to apply per-message security services over the established + security context. The method will produce a token with a + cryptographic MIC and may optionally encrypt the message in inStream. + The outStream will contain both the MIC and the message. + + The MessageProp object is instantiated by the application and used to + specify a QOP value which selects cryptographic algorithms, and a + privacy service to optionally encrypt the message. The underlying + mechanism that is used in the call may not be able to provide the + privacy service. It sets the actual privacy service that it does + + + + +Kabat & Upadhyay Standards Track [Page 62] + +RFC 2853 GSS-API Java Bindings June 2000 + + + provide in this MessageProp object which the caller should then query + upon return. If the mechanism is not able to provide the requested + QOP, it throws a GSSException with the BAD_QOP code. + + Since some application-level protocols may wish to use tokens emitted + by wrap to provide "secure framing", implementations should support + the wrapping of zero-length messages. + + The application will be responsible for sending the token to the + peer. + + Parameters: + + inStream Input stream containing the application data to be + protected. + + outStream The output stream to write the protected message to. + The application is responsible for sending this to the + other peer for processing in its unwrap method. + + msgProp Instance of MessageProp that is used by the + application to set the desired QOP and privacy state. + Set the desired QOP to 0 to request the default QOP. + Upon return from this method, this object will contain + the the actual privacy state that was applied to the + message by the underlying mechanism. + +6.4.12. unwrap + + public byte [] unwrap(byte[] inBuf, int offset, int len, + MessageProp msgProp) throws GSSException + + Used by the peer application to process tokens generated with the + wrap call. This call is equal in functionality to its stream + counterpart. The method will return the message supplied in the peer + application to the wrap call, verifying the embedded MIC. + + The MessageProp object is instantiated by the application and is used + by the underlying mechanism to return information to the caller such + as the QOP, whether confidentiality was applied to the message, and + other supplementary message state information. + + Since some application-level protocols may wish to use tokens emitted + by wrap to provide "secure framing", implementations should support + the wrapping and unwrapping of zero-length messages. + + + + + + +Kabat & Upadhyay Standards Track [Page 63] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Parameters: + + inBuf GSS-API wrap token received from peer. + + offset The offset within the inBuf where the token begins. + + len The length of the token within the inBuf (starting at + the offset). + + msgProp Upon return from the method, this object will contain + the applied QOP, the privacy state of the message, and + supplementary information described in 4.12.3 stating + whether the token was a duplicate, old, out of + sequence or arriving after a gap. + +6.4.13. unwrap + + public void unwrap(InputStream inStream, OutputStream outStream, + MessageProp msgProp) throws GSSException + + Used by the peer application to process tokens generated with the + wrap call. This call is equal in functionality to its byte array + counterpart. It will produce the message supplied in the peer + application to the wrap call, verifying the embedded MIC. + + The MessageProp object is instantiated by the application and is used + by the underlying mechanism to return information to the caller such + as the QOP, whether confidentiality was applied to the message, and + other supplementary message state information. + + Since some application-level protocols may wish to use tokens emitted + by wrap to provide "secure framing", implementations should support + the wrapping and unwrapping of zero-length messages. + + Parameters: + + inStream Input stream containing the GSS-API wrap token + received from the peer. + + outStream The output stream to write the application message to. + + msgProp Upon return from the method, this object will contain + the applied QOP, the privacy state of the message, and + supplementary information described in 4.12.3 stating + whether the token was a duplicate, old, out of + sequence or arriving after a gap. + + + + + +Kabat & Upadhyay Standards Track [Page 64] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.4.14. getMIC + + public byte[] getMIC(byte []inMsg, int offset, int len, + MessageProp msgProp) throws GSSException + + Returns a token containing a cryptographic MIC for the supplied + message, for transfer to the peer application. Unlike wrap, which + encapsulates the user message in the returned token, only the message + MIC is returned in the output token. This method is identical in + functionality to its stream counterpart. + + Note that privacy can only be applied through the wrap call. + + Since some application-level protocols may wish to use tokens emitted + by getMIC to provide "secure framing", implementations should support + derivation of MICs from zero-length messages. + + Parameters: + + inMsg Message to generate MIC over. + + offset The offset within the inMsg where the token begins. + + len The length of the token within the inMsg (starting at + the offset). + + msgProp Instance of MessageProp that is used by the + application to set the desired QOP. Set the desired + QOP to 0 in msgProp to request the default QOP. + Alternatively pass in "null" for msgProp to request + default QOP. + +6.4.15. getMIC + + public void getMIC(InputStream inStream, OutputStream outStream, + MessageProp msgProp) throws GSSException + + Produces a token containing a cryptographic MIC for the supplied + message, for transfer to the peer application. Unlike wrap, which + encapsulates the user message in the returned token, only the message + MIC is produced in the output token. This method is identical in + functionality to its byte array counterpart. + + Note that privacy can only be applied through the wrap call. + + Since some application-level protocols may wish to use tokens emitted + by getMIC to provide "secure framing", implementations should support + derivation of MICs from zero-length messages. + + + +Kabat & Upadhyay Standards Track [Page 65] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Parameters: + + inStream inStream Input stream containing the message to + generate MIC over. + + outStream outStream Output stream to write the GSS-API output + token to. + + msgProp Instance of MessageProp that is used by the + application to set the desired QOP. Set the desired + QOP to 0 in msgProp to request the default QOP. + Alternatively pass in "null" for msgProp to request + default QOP. + +6.4.16. verifyMIC + + public void verifyMIC(byte []inTok, int tokOffset, int tokLen, + byte[] inMsg, int msgOffset, int msgLen, + MessageProp msgProp) throws GSSException + + Verifies the cryptographic MIC, contained in the token parameter, + over the supplied message. This method is equivalent in + functionality to its stream counterpart. + + The MessageProp object is instantiated by the application and is used + by the underlying mechanism to return information to the caller such + as the QOP indicating the strength of protection that was applied to + the message and other supplementary message state information. + + Since some application-level protocols may wish to use tokens emitted + by getMIC to provide "secure framing", implementations should support + the calculation and verification of MICs over zero-length messages. + + Parameters: + + inTok Token generated by peer's getMIC method. + + tokOffset The offset within the inTok where the token begins. + + tokLen The length of the token within the inTok (starting at + the offset). + + inMsg Application message to verify the cryptographic MIC + over. + + msgOffset The offset within the inMsg where the message begins. + + + + + +Kabat & Upadhyay Standards Track [Page 66] + +RFC 2853 GSS-API Java Bindings June 2000 + + + msgLen The length of the message within the inMsg (starting + at the offset). + + msgProp Upon return from the method, this object will contain + the applied QOP and supplementary information + described in 4.12.3 stating whether the token was a + duplicate, old, out of sequence or arriving after a + gap. The confidentiality state will be set to + "false". + +6.4.17. verifyMIC + + public void verifyMIC(InputStream tokStream, InputStream msgStream, + MessageProp msgProp) throws GSSException + + Verifies the cryptographic MIC, contained in the token parameter, + over the supplied message. This method is equivalent in + functionality to its byte array counterpart. + + The MessageProp object is instantiated by the application and is used + by the underlying mechanism to return information to the caller such + as the QOP indicating the strength of protection that was applied to + the message and other supplementary message state information. + + Since some application-level protocols may wish to use tokens emitted + by getMIC to provide "secure framing", implementations should support + the calculation and verification of MICs over zero-length messages. + + Parameters: + + tokStream Input stream containing the token generated by peer's + getMIC method. + + msgStream Input stream containing the application message to + verify the cryptographic MIC over. + + msgProp Upon return from the method, this object will contain + the applied QOP and supplementary information + described in 4.12.3 stating whether the token was a + duplicate, old, out of sequence or arriving after a + gap. The confidentiality state will be set to + "false". + + + + + + + + + +Kabat & Upadhyay Standards Track [Page 67] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.4.18. export + + public byte [] export() throws GSSException + + Provided to support the sharing of work between multiple processes. + This routine will typically be used by the context-acceptor, in an + application where a single process receives incoming connection + requests and accepts security contexts over them, then passes the + established context to one or more other processes for message + exchange. + + This method deactivates the security context and creates an + interprocess token which, when passed to the byte array constructor + of the GSSContext interface in another process, will re-activate the + context in the second process. Only a single instantiation of a + given context may be active at any one time; a subsequent attempt by + a context exporter to access the exported security context will fail. + + The implementation may constrain the set of processes by which the + interprocess token may be imported, either as a function of local + security policy, or as a result of implementation decisions. For + example, some implementations may constrain contexts to be passed + only between processes that run under the same account, or which are + part of the same process group. + + The interprocess token may contain security-sensitive information + (for example cryptographic keys). While mechanisms are encouraged to + either avoid placing such sensitive information within interprocess + tokens, or to encrypt the token before returning it to the + application, in a typical GSS-API implementation this may not be + possible. Thus the application must take care to protect the + interprocess token, and ensure that any process to which the token is + transferred is trustworthy. + +6.4.19. requestMutualAuth + + public void requestMutualAuth(boolean state) throws GSSException + + Sets the request state of the mutual authentication flag for the + context. This method is only valid before the context creation + process begins and only for the initiator. + + Parameters: + + state Boolean representing if mutual authentication should + be requested during context establishment. + + + + + +Kabat & Upadhyay Standards Track [Page 68] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.4.20. requestReplayDet + + public void requestReplayDet(boolean state) throws GSSException + + Sets the request state of the replay detection service for the + context. This method is only valid before the context creation + process begins and only for the initiator. + + Parameters: + + state Boolean representing if replay detection is desired + over the established context. + +6.4.21. requestSequenceDet + + public void requestSequenceDet(boolean state) throws GSSException + + Sets the request state for the sequence checking service of the + context. This method is only valid before the context creation + process begins and only for the initiator. + + Parameters: + + state Boolean representing if sequence detection is desired + over the established context. + +6.4.22. requestCredDeleg + + public void requestCredDeleg(boolean state) throws GSSException + + Sets the request state for the credential delegation flag for the + context. This method is only valid before the context creation + process begins and only for the initiator. + + Parameters: + + state Boolean representing if credential delegation is + desired. + +6.4.23. requestAnonymity + + public void requestAnonymity(boolean state) throws GSSException + + Requests anonymous support over the context. This method is only + valid before the context creation process begins and only for the + initiator. + + + + + +Kabat & Upadhyay Standards Track [Page 69] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Parameters: + + state Boolean representing if anonymity support is + requested. + +6.4.24. requestConf + + public void requestConf(boolean state) throws GSSException + + Requests that confidentiality service be available over the context. + This method is only valid before the context creation process begins + and only for the initiator. + + Parameters: + + state Boolean indicating if confidentiality services are to + be requested for the context. + +6.4.25. requestInteg + + public void requestInteg(boolean state) throws GSSException + + Requests that integrity services be available over the context. This + method is only valid before the context creation process begins and + only for the initiator. + + Parameters: + + state Boolean indicating if integrity services are to be + requested for the context. + +6.4.26. requestLifetime + + public void requestLifetime(int lifetime) throws GSSException + + Sets the desired lifetime for the context in seconds. This method is + only valid before the context creation process begins and only for + the initiator. Use GSSContext.INDEFINITE_LIFETIME and + GSSContext.DEFAULT_LIFETIME to request indefinite or default context + lifetime. + + Parameters: + + lifetime The desired context lifetime in seconds. + + + + + + + +Kabat & Upadhyay Standards Track [Page 70] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.4.27. setChannelBinding + + public void setChannelBinding(ChannelBinding cb) throws GSSException + + Sets the channel bindings to be used during context establishment. + This method is only valid before the context creation process begins. + + Parameters: + + cb Channel bindings to be used. + +6.4.28. getCredDelegState + + public boolean getCredDelegState() + + Returns the state of the delegated credentials for the context. When + issued before context establishment is completed or when the + isProtReady method returns "false", it returns the desired state, + otherwise it will indicate the actual state over the established + context. + +6.4.29. getMutualAuthState + + public boolean getMutualAuthState() + + Returns the state of the mutual authentication option for the + context. When issued before context establishment completes or when + the isProtReady method returns "false", it returns the desired state, + otherwise it will indicate the actual state over the established + context. + +6.4.30. getReplayDetState + + public boolean getReplayDetState() + + Returns the state of the replay detection option for the context. + When issued before context establishment completes or when the + isProtReady method returns "false", it returns the desired state, + otherwise it will indicate the actual state over the established + context. + +6.4.31. getSequenceDetState + + public boolean getSequenceDetState() + + Returns the state of the sequence detection option for the context. + When issued before context establishment completes or when the + isProtReady method returns "false", it returns the desired state, + + + +Kabat & Upadhyay Standards Track [Page 71] + +RFC 2853 GSS-API Java Bindings June 2000 + + + otherwise it will indicate the actual state over the established + context. + +6.4.32. getAnonymityState + + public boolean getAnonymityState() + + Returns "true" if this is an anonymous context. When issued before + context establishment completes or when the isProtReady method + returns "false", it returns the desired state, otherwise it will + indicate the actual state over the established context. + +6.4.33. isTransferable + + public boolean isTransferable() throws GSSException + + Returns "true" if the context is transferable to other processes + through the use of the export method. This call is only valid on + fully established contexts. + +6.4.34. isProtReady + + public boolean isProtReady() + + Returns "true" if the per message operations can be applied over the + context. Some mechanisms may allow the usage of per-message + operations before the context is fully established. This will also + indicate that the get methods will return actual context state + characteristics instead of the desired ones. + +6.4.35. getConfState + + public boolean getConfState() + + Returns the confidentiality service state over the context. When + issued before context establishment completes or when the isProtReady + method returns "false", it returns the desired state, otherwise it + will indicate the actual state over the established context. + +6.4.36. getIntegState + + public boolean getIntegState() + + Returns the integrity service state over the context. When issued + before context establishment completes or when the isProtReady method + returns "false", it returns the desired state, otherwise it will + indicate the actual state over the established context. + + + + +Kabat & Upadhyay Standards Track [Page 72] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.4.37. getLifetime + + public int getLifetime() + + Returns the context lifetime in seconds. When issued before context + establishment completes or when the isProtReady method returns + "false", it returns the desired lifetime, otherwise it will indicate + the remaining lifetime for the context. + +6.4.38. getSrcName + + public GSSName getSrcName() throws GSSException + + Returns the name of the context initiator. This call is valid only + after the context is fully established or the isProtReady method + returns "true". It is guaranteed to return an MN. + +6.4.39. getTargName + + public GSSName getTargName() throws GSSException + + Returns the name of the context target (acceptor). This call is + valid only after the context is fully established or the isProtReady + method returns "true". It is guaranteed to return an MN. + +6.4.40. getMech + + public Oid getMech() throws GSSException + + Returns the mechanism oid for this context. This method may be called + before the context is fully established, but the mechanism returned + may change on successive calls in negotiated mechanism case. + +6.4.41. getDelegCred + + public GSSCredential getDelegCred() throws GSSException + + Returns the delegated credential object on the acceptor's side. To + check for availability of delegated credentials call + getDelegCredState. This call is only valid on fully established + contexts. + +6.4.42. isInitiator + + public boolean isInitiator() throws GSSException + + Returns "true" if this is the initiator of the context. This call is + only valid after the context creation process has started. + + + +Kabat & Upadhyay Standards Track [Page 73] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.5. public class MessageProp + + This is a utility class used within the per-message GSSContext + methods to convey per-message properties. + + When used with the GSSContext interface's wrap and getMIC methods, an + instance of this class is used to indicate the desired QOP and to + request if confidentiality services are to be applied to caller + supplied data (wrap only). To request default QOP, the value of 0 + should be used for QOP. + + When used with the unwrap and verifyMIC methods of the GSSContext + interface, an instance of this class will be used to indicate the + applied QOP and confidentiality services over the supplied message. + In the case of verifyMIC, the confidentiality state will always be + "false". Upon return from these methods, this object will also + contain any supplementary status values applicable to the processed + token. The supplementary status values can indicate old tokens, out + of sequence tokens, gap tokens or duplicate tokens. + +6.5.1. Constructors + + public MessageProp(boolean privState) + + Constructor which sets QOP to 0 indicating that the default QOP is + requested. + + Parameters: + + privState The desired privacy state. "true" for privacy and + "false" for integrity only. + + + public MessageProp(int qop, boolean privState) + + Constructor which sets the values for the qop and privacy state. + + Parameters: + + qop The desired QOP. Use 0 to request a default QOP. + + privState The desired privacy state. "true" for privacy and + "false" for integrity only. + + + + + + + + +Kabat & Upadhyay Standards Track [Page 74] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.5.2. getQOP + + public int getQOP() + + Retrieves the QOP value. + +6.5.3. getPrivacy + + public boolean getPrivacy() + + Retrieves the privacy state. + +6.5.4. getMinorStatus + + public int getMinorStatus() + + Retrieves the minor status that the underlying mechanism might have + set. + +6.5.5. getMinorString + + public String getMinorString() + + Returns a string explaining the mechanism specific error code. null + will be returned when no mechanism error code has been set. + +6.5.6. setQOP + + public void setQOP(int qopVal) + + Sets the QOP value. + + Parameters: + + qopVal The QOP value to be set. Use 0 to request a default + QOP value. + +6.5.7. setPrivacy + + public void setPrivacy(boolean privState) + + Sets the privacy state. + + Parameters: + + privState The privacy state to set. + + + + + +Kabat & Upadhyay Standards Track [Page 75] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.5.8. isDuplicateToken + + public boolean isDuplicateToken() + + Returns "true" if this is a duplicate of an earlier token. + +6.5.9. isOldToken + + public boolean isOldToken() + + Returns "true" if the token's validity period has expired. + +6.5.10. isUnseqToken + + public boolean isUnseqToken() + + Returns "true" if a later token has already been processed. + +6.5.11. isGapToken + + public boolean isGapToken() + + Returns "true" if an expected per-message token was not received. + +6.5.12. setSupplementaryStates + + public void setSupplementaryStates(boolean duplicate, + boolean old, boolean unseq, boolean gap, + int minorStatus, String minorString) + + This method sets the state for the supplementary information flags + and the minor status in MessageProp. It is not used by the + application but by the GSS implementation to return this information + to the caller of a per-message context method. + + Parameters: + + duplicate true if the token was a duplicate of an earlier token, + false otherwise + + old true if the token's validity period has expired, false + otherwise + + unseq true if a later token has already been processed, + false otherwise + + gap true if one or more predecessor tokens have not yet + been successfully processed, false otherwise + + + +Kabat & Upadhyay Standards Track [Page 76] + +RFC 2853 GSS-API Java Bindings June 2000 + + + minorStatus the integer minor status code that the underlying + mechanism wants to set + + minorString the textual representation of the minorStatus + value + +6.6. public class ChannelBinding + + The GSS-API accommodates the concept of caller-provided channel + binding information. Channel bindings are used to strengthen the + quality with which peer entity authentication is provided during + context establishment. They enable the GSS-API callers to bind the + establishment of the security context to relevant characteristics + like addresses or to application specific data. + + The caller initiating the security context must determine the + appropriate channel binding values to set in the GSSContext object. + The acceptor must provide an identical binding in order to validate + that received tokens possess correct channel-related characteristics. + + Use of channel bindings is optional in GSS-API. Since channel- + binding information may be transmitted in context establishment + tokens, applications should therefore not use confidential data as + channel-binding components. + +6.6.1. Constructors + + public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, + byte[] appData) + + Create a ChannelBinding object with user supplied address information + and data. "null" values can be used for any fields which the + application does not want to specify. + + Parameters: + + initAddr The address of the context initiator. "null" value + can be supplied to indicate that the application does + not want to set this value. + + acceptAddrThe address of the context acceptor. "null" value can + be supplied to indicate that the application does not + want to set this value. + + appData Application supplied data to be used as part of the + channel bindings. "null" value can be supplied to + indicate that the application does not want to set + this value. + + + +Kabat & Upadhyay Standards Track [Page 77] + +RFC 2853 GSS-API Java Bindings June 2000 + + + public ChannelBinding(byte[] appData) + + Creates a ChannelBinding object without any addressing information. + + Parameters: + + appData Application supplied data to be used as part of the + channel bindings. + +6.6.2. getInitiatorAddress + + public InetAddress getInitiatorAddress() + + Returns the initiator's address for this channel binding. "null" is + returned if the address has not been set. + +6.6.3. getAcceptorAddress + + public InetAddress getAcceptorAddress() + + Returns the acceptor's address for this channel binding. "null" is + returned if the address has not been set. + +6.6.4. getApplicationData + + public byte[] getApplicationData() + + Returns application data being used as part of the ChannelBinding. + "null" is returned if no application data has been specified for the + channel binding. + +6.6.5. equals + + public boolean equals(Object obj) + + Returns "true" if two channel bindings match. (Note that the Java + language specification requires that two objects that are equal + according to the equals(Object) method must return the same integer + result when the hashCode() method is called on them.) + + Parameters: + + obj Another channel binding to compare with. + + + + + + + + +Kabat & Upadhyay Standards Track [Page 78] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.7. public class Oid + + This class represents Universal Object Identifiers (Oids) and their + associated operations. + + Oids are hierarchically globally-interpretable identifiers used + within the GSS-API framework to identify mechanisms and name formats. + + The structure and encoding of Oids is defined in ISOIEC-8824 and + ISOIEC-8825. For example the Oid representation of Kerberos V5 + mechanism is "1.2.840.113554.1.2.2" + + The GSSName name class contains public static Oid objects + representing the standard name types defined in GSS-API. + +6.7.1. Constructors + + public Oid(String strOid) throws GSSException + + Creates an Oid object from a string representation of its integer + components (e.g. "1.2.840.113554.1.2.2"). + + Parameters: + + strOid The string representation for the oid. + + public Oid(InputStream derOid) throws GSSException + + Creates an Oid object from its DER encoding. This refers to the full + encoding including tag and length. The structure and encoding of + Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is + identical in functionality to its byte array counterpart. + + Parameters: + + derOid Stream containing the DER encoded oid. + + public Oid(byte[] DEROid) throws GSSException + + Creates an Oid object from its DER encoding. This refers to the full + encoding including tag and length. The structure and encoding of + Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is + identical in functionality to its byte array counterpart. + + Parameters: + + derOid Byte array storing a DER encoded oid. + + + + +Kabat & Upadhyay Standards Track [Page 79] + +RFC 2853 GSS-API Java Bindings June 2000 + + +6.7.2. toString + + public String toString() + + Returns a string representation of the oid's integer components in + dot separated notation (e.g. "1.2.840.113554.1.2.2"). + +6.7.3. equals + + public boolean equals(Object Obj) + + Returns "true" if the two Oid objects represent the same oid value. + (Note that the Java language specification requires that two objects + that are equal according to the equals(Object) method must return the + same integer result when the hashCode() method is called on them.) + + Parameters: + + obj Another Oid object to compare with. + +6.7.4. getDER + + public byte[] getDER() + + Returns the full ASN.1 DER encoding for this oid object, which + includes the tag and length. + +6.7.5. containedIn + + public boolean containedIn(Oid[] oids) + + A utility method to test if an Oid object is contained within the + supplied Oid object array. + + Parameters: + + oids An array of oids to search. + +6.8. public class GSSException extends Exception + + This exception is thrown whenever a fatal GSS-API error occurs + including mechanism specific errors. It may contain both, the major + and minor, GSS-API status codes. The mechanism implementers are + responsible for setting appropriate minor status codes when throwing + this exception. Aside from delivering the numeric error code(s) to + the caller, this class performs the mapping from their numeric values + to textual representations. All Java GSS-API methods are declared + throwing this exception. + + + +Kabat & Upadhyay Standards Track [Page 80] + +RFC 2853 GSS-API Java Bindings June 2000 + + + All implementations are encouraged to use the Java + internationalization techniques to provide local translations of the + message strings. + +6.8.1. Static Constants + + All valid major GSS-API error code values are declared as constants + in this class. + + public static final int BAD_BINDINGS + + Channel bindings mismatch error. + + + public static final int BAD_MECH + + Unsupported mechanism requested error. + + + public static final int BAD_NAME + + Invalid name provided error. + + + public static final int BAD_NAMETYPE + + Name of unsupported type provided error. + + + public static final int BAD_STATUS + + Invalid status code error - this is the default status value. + + + public static final int BAD_MIC + + Token had invalid integrity check error. + + + public static final int CONTEXT_EXPIRED + + Specified security context expired error. + + + public static final int CREDENTIALS_EXPIRED + + Expired credentials detected error. + + + + +Kabat & Upadhyay Standards Track [Page 81] + +RFC 2853 GSS-API Java Bindings June 2000 + + + public static final int DEFECTIVE_CREDENTIAL + + Defective credential error. + + + public static final int DEFECTIVE_TOKEN + + Defective token error. + + + public static final int FAILURE + + General failure, unspecified at GSS-API level. + + + public static final int NO_CONTEXT + + Invalid security context error. + + + public static final int NO_CRED + + Invalid credentials error. + + + public static final int BAD_QOP + + Unsupported QOP value error. + + + public static final int UNAUTHORIZED + + Operation unauthorized error. + + + public static final int UNAVAILABLE + + Operation unavailable error. + + + public static final int DUPLICATE_ELEMENT + + Duplicate credential element requested error. + + + public static final int NAME_NOT_MN + + Name contains multi-mechanism elements error. + + + +Kabat & Upadhyay Standards Track [Page 82] + +RFC 2853 GSS-API Java Bindings June 2000 + + + public static final int DUPLICATE_TOKEN + + The token was a duplicate of an earlier token. This is a fatal error + code that may occur during context establishment. It is not used to + indicate supplementary status values. The MessageProp object is used + for that purpose. + + public static final int OLD_TOKEN + + The token's validity period has expired. This is a fatal error code + that may occur during context establishment. It is not used to + indicate supplementary status values. The MessageProp object is used + for that purpose. + + public static final int UNSEQ_TOKEN + + A later token has already been processed. This is a fatal error code + that may occur during context establishment. It is not used to + indicate supplementary status values. The MessageProp object is used + for that purpose. + + public static final int GAP_TOKEN + + An expected per-message token was not received. This is a fatal + error code that may occur during context establishment. It is not + used to indicate supplementary status values. The MessageProp object + is used for that purpose. + +6.8.2. Constructors + + public GSSException(int majorCode) + + Creates a GSSException object with a specified major code. + + Parameters: + + majorCode The GSS error code causing this exception to be + thrown. + + public GSSException(int majorCode, int minorCode, String minorString) + + Creates a GSSException object with the specified major code, minor + code, and minor code textual explanation. This constructor is to be + used when the exception is originating from the security mechanism. + It allows to specify the GSS code and the mechanism code. + + + + + + +Kabat & Upadhyay Standards Track [Page 83] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Parameters: + + majorCode The GSS error code causing this exception to be + thrown. + + minorCode The mechanism error code causing this exception + to be thrown. + + minorString The textual explanation of the mechanism error + code. + +6.8.3. getMajor + + public int getMajor() + + Returns the major code representing the GSS error code that caused + this exception to be thrown. + +6.8.4. getMinor + + public int getMinor() + + Returns the mechanism error code that caused this exception. The + minor code is set by the underlying mechanism. Value of 0 indicates + that mechanism error code is not set. + +6.8.5. getMajorString + + public String getMajorString() + + Returns a string explaining the GSS major error code causing this + exception to be thrown. + +6.8.6. getMinorString + + public String getMinorString() + + Returns a string explaining the mechanism specific error code. null + will be returned when no mechanism error code has been set. + +6.8.7. setMinor + + public void setMinor(int minorCode, String message) + + Used internally by the GSS-API implementation and the underlying + mechanisms to set the minor code and its textual representation. + + + + + +Kabat & Upadhyay Standards Track [Page 84] + +RFC 2853 GSS-API Java Bindings June 2000 + + + Parameters: + + minorCode The mechanism specific error code. + + message A textual explanation of the mechanism error code. + +6.8.8. toString + + public String toString() + + Returns a textual representation of both the major and minor status + codes. + +6.8.9. getMessage + + public String getMessage() + + Returns a detailed message of this exception. Overrides + Throwable.getMessage. It is customary in Java to use this method to + obtain exception information. + +7. Sample Applications + +7.1. Simple GSS Context Initiator + + import org.ietf.jgss.*; + + /** + * This is a partial sketch for a simple client program that acts + * as a GSS context initiator. It illustrates how to use the Java + * bindings for the GSS-API specified in + * Generic Security Service API Version 2 : Java bindings + * + * + * This code sketch assumes the existence of a GSS-API + * implementation that supports the mechanism that it will need and + * is present as a library package (org.ietf.jgss) either as part of + * the standard JRE or in the CLASSPATH the application specifies. + */ + + public class SimpleClient { + + private String serviceName; // name of peer (ie. server) + private GSSCredential clientCred = null; + private GSSContext context = null; + private Oid mech; // underlying mechanism to use + + private GSSManager mgr = GSSManager.getInstance(); + + + +Kabat & Upadhyay Standards Track [Page 85] + +RFC 2853 GSS-API Java Bindings June 2000 + + + ... + ... + + private void clientActions() { + initializeGSS(); + establishContext(); + doCommunication(); + } + + /** + * Acquire credentials for the client. + */ + private void initializeGSS() { + + try { + + clientCred = mgr.createCredential(null /*default princ*/, + GSSCredential.INDEFINITE_LIFETIME /* max lifetime */, + mech /* mechanism to use */, + GSSCredential.INITIATE_ONLY /* init context */); + + print("GSSCredential created for " + + cred.getName().toString()); + print("Credential lifetime (sec)=" + + cred.getRemainingLifetime()); + } catch (GSSException e) { + print("GSS-API error in credential acquisition: " + + e.getMessage()); + ... + ... + } + + ... + ... + } + + /** + * Does the security context establishment with the + * server. + */ + private void establishContext() { + + byte[] inToken = new byte[0]; + byte[] outToken = null; + + try { + + GSSName peer = mgr.createName(serviceName, + + + +Kabat & Upadhyay Standards Track [Page 86] + +RFC 2853 GSS-API Java Bindings June 2000 + + + GSSName.NT_HOSTBASED_SERVICE); + + context = mgr.createContext(peer, mech, gssCred, + GSSContext.INDEFINITE_LIFETIME/*lifetime*/); + + // Will need to support confidentiality + context.requestConf(true); + + while (!context.isEstablished()) { + + outToken = context.initSecContext(inToken, 0, + inToken.length); + + if (outToken != null) + writeGSSToken(outToken); + + if (!context.isEstablished()) + inToken = readGSSToken(); + } + + GSSName peer = context.getSrcName(); + print("Security context established with " + peer + + " using underlying mechanism " + mech.toString()); + } catch (GSSException e) { + print("GSS-API error during context establishment: " + + e.getMessage()); + ... + ... + } + + ... + ... + } + + /** + * Sends some data to the server and reads back the + * response. + */ + private void doCommunication() { + byte[] inToken = null; + byte[] outToken = null; + byte[] buffer; + + // Container for multiple input-output arguments to and + // from the per-message routines (e.g., wrap/unwrap). + MessageProp messgInfo = new MessageProp(); + + try { + + + +Kabat & Upadhyay Standards Track [Page 87] + +RFC 2853 GSS-API Java Bindings June 2000 + + + /* + * Now send some bytes to the server to be + * processed. They will be integrity protected but + * not encrypted for privacy. + */ + + buffer = readFromFile(); + + // Set privacy to false and use the default QOP + messgInfo.setPrivacy(false); + + outToken = context.wrap(buffer, 0, buffer.length, + messgInfo); + + writeGSSToken(outToken); + + /* + * Now read the response from the server. + */ + + inToken = readGSSToken(); + buffer = context.unwrap(inToken, 0, inToken.length, + messgInfo); + // All ok if no exception was thrown! + + GSSName peer = context.getSrcName(); + + print("Message from " + peer.toString() + + " arrived."); + print("Was it encrypted? " + + messgInfo.getPrivacy()); + print("Duplicate Token? " + + messgInfo.isDuplicateToken()); + print("Old Token? " + + messgInfo.isOldToken()); + print("Unsequenced Token? " + + messgInfo.isUnseqToken()); + print("Gap Token? " + + messgInfo.isGapToken()); + + ... + ... + + } catch (GSSException e) { + print("GSS-API error in per-message calls: " + + e.getMessage()); + ... + ... + + + +Kabat & Upadhyay Standards Track [Page 88] + +RFC 2853 GSS-API Java Bindings June 2000 + + + } + + ... + + ... + + } // end of doCommunication method + + ... + ... + + } // end of class SimpleClient + +7.2. Simple GSS Context Acceptor + + import org.ietf.jgss.*; + + /** + * This is a partial sketch for a simple server program that acts + * as a GSS context acceptor. It illustrates how to use the Java + * bindings for the GSS-API specified in + * Generic Security Service API Version 2 : Java bindings + * + * This code sketch assumes the existence of a GSS-API + * implementation that supports the mechanisms that it will need and + * is present as a library package (org.ietf.jgss) either as part of + * the standard JRE or in the CLASSPATH the application specifies. + */ + + import org.ietf.jgss.*; + + public class SimpleServer { + + private String serviceName; + private GSSName name; + private GSSCredential cred; + + private GSSManager mgr; + + ... + ... + + /** + * Wait for client connections, establish security contexts and + * provide service. + */ + private void loop() { + + + + +Kabat & Upadhyay Standards Track [Page 89] + +RFC 2853 GSS-API Java Bindings June 2000 + + + ... + ... + + mgr = GSSManager.getInstance(); + + name = mgr.createName(serviceName, + GSSName.NT_HOSTBASED_SERVICE); + + cred = mgr.createCredential(name, + GSSCredential.INDEFINITE_LIFETIME, + null, + GSSCredential.ACCEPT_ONLY); + + + // Loop infinitely + while (true) { + + Socket s = serverSock.accept(); + + // Start a new thread to serve this connection + Thread serverThread = new ServerThread(s); + serverThread.start(); + + } + } + + /** + * Inner class ServerThread whose run() method provides the + * secure service to a connection. + */ + + private class ServerThread extends Thread { + + ... + ... + + /** + * Deals with the connection from one client. It also + * handles all GSSException's thrown while talking to + * this client. + */ + public void run() { + + byte[] inToken = null; + byte[] outToken = null; + byte[] buffer; + + GSSName peer; + + + +Kabat & Upadhyay Standards Track [Page 90] + +RFC 2853 GSS-API Java Bindings June 2000 + + + // Container for multiple input-output arguments to and + // from the per-message routines (ie. wrap/unwrap). + MessageProp supplInfo = new MessageProp(); + + GSSContext secContext = null; + + try { + + + // Now do the context establishment loop + + GSSContext context = mgr.createContext(cred); + + while (!context.isEstablished()) { + + inToken = readGSSToken(); + + outToken = context.acceptSecContext(inToken, 0, + inToken.length); + + if (outToken != null) + writeGSSToken(outToken); + + } + + + // SimpleServer wants confidentiality to be + // available. Check for it. + if (!context.getConfState()){ + ... + ... + } + + GSSName peer = context.getSrcName(); + Oid mech = context.getMech(); + print("Security context established with " + + peer.toString() + + " using underlying mechanism " + + mech.toString() + + " from Provider " + + context.getProvider().getName()); + + + // Now read the bytes sent by the client to be + // processed. + inToken = readGSSToken(); + + // Unwrap the message + + + +Kabat & Upadhyay Standards Track [Page 91] + +RFC 2853 GSS-API Java Bindings June 2000 + + + buffer = context.unwrap(inToken, 0, inToken.length, + supplInfo); + // All ok if no exception was thrown! + + // Print other supplementary per-message status + // information + + print("Message from " + + peer.toString() + " arrived."); + print("Was it encrypted? " + + supplInfo.getPrivacy()); + print("Duplicate Token? " + + supplInfo.isDuplicateToken()); + print("Old Token? " + supplInfo.isOldToken()); + print("Unsequenced Token? " + + supplInfo.isUnseqToken()); + print("Gap Token? " + supplInfo.isGapToken()); + + /* + * Now process the bytes and send back an encrypted + * response. + */ + + buffer = serverProcess(buffer); + + // Encipher it and send it across + + supplInfo.setPrivacy(true); // privacy requested + supplInfo.setQOP(0); // default QOP + outToken = context.wrap(buffer, 0, buffer.length, + supplInfo); + writeGSSToken(outToken); + + } catch (GSSException e) { + print("GSS-API Error: " + e.getMessage()); + // Alternatively, could call e.getMajorMessage() + // and e.getMinorMessage() + print("Abandoning security context."); + + ... + ... + + } + + ... + ... + + } // end of run method in ServerThread + + + +Kabat & Upadhyay Standards Track [Page 92] + +RFC 2853 GSS-API Java Bindings June 2000 + + + } // end of inner class ServerThread + + ... + ... + + } // end of class SimpleServer + +8. Security Considerations + + The Java language security model allows platform providers to have + policy based fine-grained access control over any resource that an + application wants. When using a Java security manager (such as, but + not limited to, the case of applets running in browsers) the + application code is in a sandbox by default. + + Administrators of the platform JRE determine what permissions, if + any, are to be given to source from different codebases. Thus the + administrator has to be aware of any special requirements that the + GSS provider might have for system resources. For instance, a + Kerberos provider might wish to make a network connection to the KDC + to obtain initial credentials. This would not be allowed under the + sandbox unless the administrator had granted permissions for this. + Also note that this granting and checking of permissions happens + transparently to the application and is outside the scope of this + document. + + The Java language allows administrators to pre-configure a list of + security service providers in the /lib/security/java.security + file. At runtime, the system approaches these providers in order of + preference when looking for security related services. Applications + have a means to modify this list through methods in the "Security" + class in the "java.security" package. However, since these + modifications would be visible in the entire JVM and thus affect all + code executing in it, this operation is not available in the sandbox + and requires special permissions to perform. Thus when a GSS + application has special needs that are met by a particular security + provider, it has two choices: + + 1) To install the provider on a JVM wide basis using the + java.security.Security class and then depend on the system to + find the right provider automatically when the need arises. + (This would require the application to be granted a + "insertProvider SecurityPermission".) + + 2) To pass an instance of the provider to the local instance of + GSSManager so that only factory calls going through that + GSSManager use the desired provider. (This would not require + any permissions.) + + + +Kabat & Upadhyay Standards Track [Page 93] + +RFC 2853 GSS-API Java Bindings June 2000 + + +9. Acknowledgments + + This proposed API leverages earlier work performed by the IETF's CAT + WG as outlined in both RFC 2743 and RFC 2744. Many conceptual + definitions, implementation directions, and explanations have been + included from these documents. + + We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael + Saltz and other members of Sun's development team for their helpful + input, comments and suggestions. + + We would also like to thank Joe Salowey, and Michael Smith for many + insightful ideas and suggestions that have contributed to this + document. + +10. Bibliography + + [GSSAPIv2] Linn, J., "Generic Security Service Application + Program Interface, Version 2", RFC 2078, January + 1997. + + [GSSAPIv2-UPDATE] Linn, J., "Generic Security Service Application + Program Interface, Version 2, Update 1", RFC 2743, + January 2000. + + [GSSAPI-Cbind] Wray, J., "Generic Security Service API Version 2 : + C-bindings", RFC 2744, January 2000. + + [KERBV5] Linn, J., "The Kerberos Version 5 GSS-API + Mechanism", RFC 1964, June 1996. + + [SPKM] Adams, C., "The Simple Public-Key GSS-API + Mechanism", RFC 2025, October 1996. + + + + + + + + + + + + + + + + + + +Kabat & Upadhyay Standards Track [Page 94] + +RFC 2853 GSS-API Java Bindings June 2000 + + +11. Authors' Addresses + + Address comments related to this memorandum to: + + + + Jack Kabat + ValiCert, Inc. + 339 N. Bernardo Avenue + Mountain View, CA + 94043, USA + + Phone: +1-650-567-5496 + EMail: jackk@valicert.com + + + Mayank Upadhyay + Sun Microsystems, Inc. + 901 San Antonio Road, MS CUP02-102 + Palo Alto, CA 94303 + + Phone: +1-408-517-5956 + EMail: mdu@eng.sun.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Kabat & Upadhyay Standards Track [Page 95] + +RFC 2853 GSS-API Java Bindings June 2000 + + +12. Full Copyright Statement + + Copyright (C) The Internet Society (2000). 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. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Kabat & Upadhyay Standards Track [Page 96] + -- 2.11.4.GIT