RFC 8353
Generic Security Service API Version 2: Java Bindings Update
7.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. A QOP is an integer value defined by an mechanism. 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.7.5.1. Constructors
public MessageProp(boolean privState) Constructor that 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 that 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.
7.5.2. getQOP
public int getQOP()
Retrieves the QOP value.
7.5.3. getPrivacy
public boolean getPrivacy()
Retrieves the privacy state.
7.5.4. getMinorStatus
public int getMinorStatus()
Retrieves the minor status that the underlying mechanism might have
set.
7.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.
7.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.
7.5.7. setPrivacy
public void setPrivacy(boolean privState) Sets the privacy state. Parameters: privState The privacy state to set.7.5.8. isDuplicateToken
public boolean isDuplicateToken() Returns "true" if this is a duplicate of an earlier token.7.5.9. isOldToken
public boolean isOldToken() Returns "true" if the token's validity period has expired.7.5.10. isUnseqToken
public boolean isUnseqToken() Returns "true" if a later token has already been processed.7.5.11. isGapToken
public boolean isGapToken() Returns "true" if an expected per-message token was not received.7.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; otherwise, "false".
old "true" if the token's validity period has
expired; otherwise, "false".
unseq "true" if a later token has already been
processed; otherwise, "false".
gap "true" if one or more predecessor tokens have not
yet been successfully processed; otherwise,
"false".
minorStatus The integer minor status code that the underlying
mechanism wants to set.
minorString The textual representation of the minorStatus
value.
7.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.
7.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 that the
application does not want to specify.
Parameters:
initAddr The address of the context initiator. The "null"
value can be supplied to indicate that the
application does not want to set this value.
acceptAddr The address of the context acceptor. The "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. The "null" value can be
supplied to indicate that the application does
not want to set this value.
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.
7.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.
7.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.
7.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.
7.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 with which to compare.7.7. public class Oid
This class represents Universal 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 [ISOIEC-8824] and ISOIEC-8825 [ISOIEC-8825]. For example, the OID representation of the 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.7.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 [ISOIEC-8824] and ISOIEC-8825 [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 [ISOIEC-8824] and ISOIEC-8825 [ISOIEC-8825]. This method is identical in functionality to its byte array counterpart. Parameters: derOid Byte array storing a DER-encoded OID.7.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").7.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 [JLS] 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 with which to compare.7.7.4. getDER
public byte[] getDER() Returns the full ASN.1 DER encoding for this Oid object, which includes the tag and length.
7.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.7.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 implementors 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. This exception MAY also include an output token that SHOULD be sent to the peer. For example, when an initSecContext call fails due to a fatal error, the mechanism MAY define an error token that SHOULD be sent to the peer for debugging or informational purposes. All Java GSS-API methods are declared throwing this exception. All implementations are encouraged to use the Java internationalization techniques to provide local translations of the message strings.7.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. The value of this constant is 1. public static final int BAD_MECH Unsupported mechanism requested error. The value of this constant is 2. public static final int BAD_NAME Invalid name provided error. The value of this constant is 3.
public static final int BAD_NAMETYPE Name of unsupported type provided error. The value of this constant is 4. public static final int BAD_STATUS Invalid status code error - this is the default status value. The value of this constant is 5. public static final int BAD_MIC Token had invalid integrity check error. The value of this constant is 6. public static final int CONTEXT_EXPIRED Specified security context expired error. The value of this constant is 7. public static final int CREDENTIALS_EXPIRED Expired credentials detected error. The value of this constant is 8. public static final int DEFECTIVE_CREDENTIAL Defective credential error. The value of this constant is 9. public static final int DEFECTIVE_TOKEN Defective token error. The value of this constant is 10. public static final int FAILURE General failure, unspecified at GSS-API level. The value of this constant is 11. public static final int NO_CONTEXT Invalid security context error. The value of this constant is 12. public static final int NO_CRED Invalid credentials error. The value of this constant is 13. public static final int BAD_QOP Unsupported QOP value error. The value of this constant is 14.
public static final int UNAUTHORIZED Operation unauthorized error. The value of this constant is 15. public static final int UNAVAILABLE Operation unavailable error. The value of this constant is 16. public static final int DUPLICATE_ELEMENT Duplicate credential element requested error. The value of this constant is 17. public static final int NAME_NOT_MN Name contains multi-mechanism elements error. The value of this constant is 18. public static final int DUPLICATE_TOKEN The token was a duplicate of an earlier token. This is contained in an exception only when detected during context establishment, in which case it is considered a fatal error. (Non-fatal supplementary codes are indicated via the MessageProp object.) The value of this constant is 19. public static final int OLD_TOKEN The token's validity period has expired. This is contained in an exception only when detected during context establishment, in which case it is considered a fatal error. (Non-fatal supplementary codes are indicated via the MessageProp object.) The value of this constant is 20. public static final int UNSEQ_TOKEN A later token has already been processed. This is contained in an exception only when detected during context establishment, in which case it is considered a fatal error. (Non-fatal supplementary codes are indicated via the MessageProp object.) The value of this constant is 21.
public static final int GAP_TOKEN An expected per-message token was not received. This is contained in an exception only when detected during context establishment, in which case it is considered a fatal error. (Non-fatal supplementary codes are indicated via the MessageProp object.) The value of this constant is 22.7.8.2. Constructors
public GSSException(int majorCode) Creates a GSSException object with a specified major code. Calling this constructor is equivalent to calling GSSException(majorCode, null, 0, null, null). 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. Calling this constructor is equivalent to calling GSSException(majorCode, null, minorCode, minorString, null). public GSSException(int majorCode, String majorString, int minorCode, String minorString, byte[] outputToken) Creates a GSSException object with the specified major code, major code textual explanation, minor code, minor code textual explanation, and an output token. This is a general-purpose constructor that can be used to create any type of GSSException. Parameters: majorCode The GSS error code causing this exception to be thrown. majorString The textual explanation of the GSS error code. If null is provided, a default explanation that matches the majorCode will be set. minorCode The mechanism error code causing this exception to be thrown. Can be 0 if no mechanism error code is available.
minorString The textual explanation of the mechanism error
code. Can be null if no textual explanation is
available.
outputToken The output token that SHOULD be sent to the peer.
Can be null if no such token is available. It
MUST NOT be an empty array. When provided, the
array will be cloned to protect against
subsequent modifications.
7.8.3. getMajor
public int getMajor()
Returns the major code representing the GSS error code that caused
this exception to be thrown.
7.8.4. getMinor
public int getMinor()
Returns the mechanism error code that caused this exception. The
minor code is set by the underlying mechanism. The value of 0
indicates that the mechanism error code is not set.
7.8.5. getMajorString
public String getMajorString()
Returns a string explaining the GSS major error code causing this
exception to be thrown.
7.8.6. getMinorString
public String getMinorString()
Returns a string explaining the mechanism-specific error code. "null"
will be returned when no string explaining the mechanism error code
has been set.
7.8.7. getOutputToken
public byte[] getOutputToken Returns the output token in a new byte array. If the method (for example, GSSContext#initSecContext) that throws this GSSException needs to generate an output token that SHOULD be sent to the peer, that token will be stored in this GSSException and can be retrieved with this method. The return value MUST be null if no such token is generated. It MUST NOT be an empty byte array.7.8.8. 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. Parameters: minorCode The mechanism-specific error code. message A textual explanation of the mechanism error code.7.8.9. toString
public String toString() Returns a textual representation of both the major and minor status codes.7.8.10. 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.
(next page on part 7)
