< prev index next >
src/java.security.jgss/share/classes/org/ietf/jgss/GSSContext.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
--- 1,7 ----
/*
! * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
*** 102,112 ****
* The example code presented below demonstrates the usage of the
* <code>GSSContext</code> interface for the initiating peer. Different
* operations on the <code>GSSContext</code> 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.<p>
*
* <pre>
* // Create a context using default credentials
* // and the implementation specific default mechanism
* GSSManager manager ...
--- 102,112 ----
* The example code presented below demonstrates the usage of the
* <code>GSSContext</code> interface for the initiating peer. Different
* operations on the <code>GSSContext</code> 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.
*
* <pre>
* // Create a context using default credentials
* // and the implementation specific default mechanism
* GSSManager manager ...
*** 207,217 ****
* established.<p>
*
* Some mechanism providers might require that the caller be granted
* permission to initiate a security context. A failed permission check
* might cause a {@link java.lang.SecurityException SecurityException}
! * to be thrown from this method.<p>
*
* @return a byte[] containing the token to be sent to the
* peer. <code>null</code> indicates that no token is generated.
* @param inputBuf token generated by the peer. This parameter is ignored
* on the first call since no token has been received from the peer.
--- 207,217 ----
* established.<p>
*
* Some mechanism providers might require that the caller be granted
* permission to initiate a security context. A failed permission check
* might cause a {@link java.lang.SecurityException SecurityException}
! * to be thrown from this method.
*
* @return a byte[] containing the token to be sent to the
* peer. <code>null</code> indicates that no token is generated.
* @param inputBuf token generated by the peer. This parameter is ignored
* on the first call since no token has been received from the peer.
*** 274,284 ****
* permission to initiate a security context. A failed permission check
* might cause a {@link java.lang.SecurityException SecurityException}
* to be thrown from this method.<p>
*
* The following example code demonstrates how this method might be
! * used:<p>
* <pre>
* InputStream is ...
* OutputStream os ...
* GSSContext context ...
*
--- 274,284 ----
* permission to initiate a security context. A failed permission check
* might cause a {@link java.lang.SecurityException SecurityException}
* to be thrown from this method.<p>
*
* The following example code demonstrates how this method might be
! * used:
* <pre>
* InputStream is ...
* OutputStream os ...
* GSSContext context ...
*
*** 344,354 ****
* permission to accept a security context. A failed permission check
* might cause a {@link java.lang.SecurityException SecurityException}
* to be thrown from this method.<p>
*
* The following example code demonstrates how this method might be
! * used:<p>
* <pre>
* byte[] inToken;
* byte[] outToken;
* GSSContext context ...
*
--- 344,354 ----
* permission to accept a security context. A failed permission check
* might cause a {@link java.lang.SecurityException SecurityException}
* to be thrown from this method.<p>
*
* The following example code demonstrates how this method might be
! * used:
* <pre>
* byte[] inToken;
* byte[] outToken;
* GSSContext context ...
*
*** 421,431 ****
* permission to accept a security context. A failed permission check
* might cause a {@link java.lang.SecurityException SecurityException}
* to be thrown from this method.<p>
*
* The following example code demonstrates how this method might be
! * used:<p>
* <pre>
* InputStream is ...
* OutputStream os ...
* GSSContext context ...
*
--- 421,431 ----
* permission to accept a security context. A failed permission check
* might cause a {@link java.lang.SecurityException SecurityException}
* to be thrown from this method.<p>
*
* The following example code demonstrates how this method might be
! * used:
* <pre>
* InputStream is ...
* OutputStream os ...
* GSSContext context ...
*
*** 508,518 ****
* application to fragment messages prior to applying protection.<p>
*
* GSS-API implementations are recommended but not required to detect
* invalid QOP values when <code>getWrapSizeLimit</code> is called.
* This routine guarantees only a maximum message size, not the
! * availability of specific QOP values for message protection.<p>
*
* @param qop the level of protection wrap will be asked to provide.
* @param confReq <code>true</code> if wrap will be asked to provide
* privacy, <code>false</code> otherwise.
* @param maxTokenSize the desired maximum size of the token emitted by
--- 508,518 ----
* application to fragment messages prior to applying protection.<p>
*
* GSS-API implementations are recommended but not required to detect
* invalid QOP values when <code>getWrapSizeLimit</code> is called.
* This routine guarantees only a maximum message size, not the
! * availability of specific QOP values for message protection.
*
* @param qop the level of protection wrap will be asked to provide.
* @param confReq <code>true</code> if wrap will be asked to provide
* privacy, <code>false</code> otherwise.
* @param maxTokenSize the desired maximum size of the token emitted by
*** 593,603 ****
* query upon return. If the mechanism is not able to provide the
* requested QOP, it throws a GSSException with the BAD_QOP code.<p>
*
* 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.<p>
*
* @param inStream an InputStream containing the application data to be
* protected. All of the data that is available in
* inStream is used.
* @param outStream an OutputStream to write the protected message
--- 593,603 ----
* query upon return. If the mechanism is not able to provide the
* requested QOP, it throws a GSSException with the BAD_QOP code.<p>
*
* 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.
*
* @param inStream an InputStream containing the application data to be
* protected. All of the data that is available in
* inStream is used.
* @param outStream an OutputStream to write the protected message
*** 628,638 ****
* such as the QOP, whether confidentiality was applied to the message,
* and other supplementary message state information.<p>
*
* 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.<p>
*
* @param inBuf a byte array containing the wrap token received from
* peer.
* @param offset the offset where the token begins.
* @param len the length of the token
--- 628,638 ----
* such as the QOP, whether confidentiality was applied to the message,
* and other supplementary message state information.<p>
*
* 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.
*
* @param inBuf a byte array containing the wrap token received from
* peer.
* @param offset the offset where the token begins.
* @param len the length of the token
*** 677,687 ****
* are not definitive then the method will attempt to treat all
* available bytes as part of the token.<p>
*
* Other than the possible blocking behavior described above, this
* method is equivalent to the byte array based {@link #unwrap(byte[],
! * int, int, MessageProp) unwrap} method.<p>
*
* @param inStream an InputStream that contains the wrap token generated
* by the peer.
* @param outStream an OutputStream to write the application message
* to.
--- 677,687 ----
* are not definitive then the method will attempt to treat all
* available bytes as part of the token.<p>
*
* Other than the possible blocking behavior described above, this
* method is equivalent to the byte array based {@link #unwrap(byte[],
! * int, int, MessageProp) unwrap} method.
*
* @param inStream an InputStream that contains the wrap token generated
* by the peer.
* @param outStream an OutputStream to write the application message
* to.
*** 825,835 ****
* are not definitive then the method will attempt to treat all
* available bytes as part of the token.<p>
*
* Other than the possible blocking behavior described above, this
* method is equivalent to the byte array based {@link #verifyMIC(byte[],
! * int, int, byte[], int, int, MessageProp) verifyMIC} method.<p>
*
* @param tokStream an InputStream containing the token generated by the
* peer's getMIC method.
* @param msgStream an InputStream containing the application message to
* verify the cryptographic MIC over. All of the data
--- 825,835 ----
* are not definitive then the method will attempt to treat all
* available bytes as part of the token.<p>
*
* Other than the possible blocking behavior described above, this
* method is equivalent to the byte array based {@link #verifyMIC(byte[],
! * int, int, byte[], int, int, MessageProp) verifyMIC} method.
*
* @param tokStream an InputStream containing the token generated by the
* peer's getMIC method.
* @param msgStream an InputStream containing the application message to
* verify the cryptographic MIC over. All of the data
*** 911,921 ****
*
* Not all mechanisms support mutual authentication and some mechanisms
* might require mutual authentication even if the application
* doesn't. Therefore, the application should check to see if the
* request was honored with the {@link #getMutualAuthState()
! * getMutualAuthState} method.<p>
*
* @param state a boolean value indicating whether mutual
* authentication should be used or not.
* @see #getMutualAuthState()
*
--- 911,921 ----
*
* Not all mechanisms support mutual authentication and some mechanisms
* might require mutual authentication even if the application
* doesn't. Therefore, the application should check to see if the
* request was honored with the {@link #getMutualAuthState()
! * getMutualAuthState} method.
*
* @param state a boolean value indicating whether mutual
* authentication should be used or not.
* @see #getMutualAuthState()
*
*** 941,951 ****
* getReplayDetState} method. If replay detection is enabled then the
* {@link MessageProp#isDuplicateToken() MessageProp.isDuplicateToken} and {@link
* MessageProp#isOldToken() MessageProp.isOldToken} methods will return
* valid results for the <code>MessageProp</code> object that is passed
* in to the <code>unwrap</code> method or the <code>verifyMIC</code>
! * method.<p>
*
* @param state a boolean value indicating whether replay detection
* should be enabled over the established context or not.
* @see #getReplayDetState()
*
--- 941,951 ----
* getReplayDetState} method. If replay detection is enabled then the
* {@link MessageProp#isDuplicateToken() MessageProp.isDuplicateToken} and {@link
* MessageProp#isOldToken() MessageProp.isOldToken} methods will return
* valid results for the <code>MessageProp</code> object that is passed
* in to the <code>unwrap</code> method or the <code>verifyMIC</code>
! * method.
*
* @param state a boolean value indicating whether replay detection
* should be enabled over the established context or not.
* @see #getReplayDetState()
*
*** 973,983 ****
* {@link MessageProp#isOldToken() MessageProp.isOldToken},
* {@link MessageProp#isUnseqToken() MessageProp.isUnseqToken}, and
* {@link MessageProp#isGapToken() MessageProp.isGapToken} methods will return
* valid results for the <code>MessageProp</code> object that is passed
* in to the <code>unwrap</code> method or the <code>verifyMIC</code>
! * method.<p>
*
* @param state a boolean value indicating whether sequence checking
* should be enabled over the established context or not.
* @see #getSequenceDetState()
*
--- 973,983 ----
* {@link MessageProp#isOldToken() MessageProp.isOldToken},
* {@link MessageProp#isUnseqToken() MessageProp.isUnseqToken}, and
* {@link MessageProp#isGapToken() MessageProp.isGapToken} methods will return
* valid results for the <code>MessageProp</code> object that is passed
* in to the <code>unwrap</code> method or the <code>verifyMIC</code>
! * method.
*
* @param state a boolean value indicating whether sequence checking
* should be enabled over the established context or not.
* @see #getSequenceDetState()
*
*** 999,1009 ****
* request was honored with the {@link #getCredDelegState()
* getCredDelegState} method. If the application indicates that
* delegation must not be used, then the mechanism will honor the
* request and delegation will not occur. This is an exception
* to the general rule that a mechanism may enable a service even if it
! * is not requested.<p>
*
* @param state a boolean value indicating whether the credentials
* should be delegated or not.
* @see #getCredDelegState()
*
--- 999,1009 ----
* request was honored with the {@link #getCredDelegState()
* getCredDelegState} method. If the application indicates that
* delegation must not be used, then the mechanism will honor the
* request and delegation will not occur. This is an exception
* to the general rule that a mechanism may enable a service even if it
! * is not requested.
*
* @param state a boolean value indicating whether the credentials
* should be delegated or not.
* @see #getCredDelegState()
*
*** 1019,1029 ****
* context initiator's side and it has to be done prior to the first
* call to <code>initSecContext</code>.
*
* Not all mechanisms support anonymity for the initiator. Therefore, the
* application should check to see if the request was honored with the
! * {@link #getAnonymityState() getAnonymityState} method.<p>
*
* @param state a boolean value indicating if the initiator should
* be authenticated to the acceptor as an anonymous principal.
* @see #getAnonymityState
*
--- 1019,1029 ----
* context initiator's side and it has to be done prior to the first
* call to <code>initSecContext</code>.
*
* Not all mechanisms support anonymity for the initiator. Therefore, the
* application should check to see if the request was honored with the
! * {@link #getAnonymityState() getAnonymityState} method.
*
* @param state a boolean value indicating if the initiator should
* be authenticated to the acceptor as an anonymous principal.
* @see #getAnonymityState
*
*** 1046,1056 ****
* is enabled, only then will the mechanism honor a request for privacy
* in the {@link MessageProp#MessageProp(int, boolean) MessageProp}
* object that is passed in to the <code>wrap</code> method.<p>
*
* Enabling confidentiality will also automatically enable
! * integrity.<p>
*
* @param state a boolean value indicating whether confidentiality
* should be enabled or not.
* @see #getConfState()
* @see #getIntegState()
--- 1046,1056 ----
* is enabled, only then will the mechanism honor a request for privacy
* in the {@link MessageProp#MessageProp(int, boolean) MessageProp}
* object that is passed in to the <code>wrap</code> method.<p>
*
* Enabling confidentiality will also automatically enable
! * integrity.
*
* @param state a boolean value indicating whether confidentiality
* should be enabled or not.
* @see #getConfState()
* @see #getIntegState()
*** 1073,1083 ****
* might enable it even if the application doesn't request
* it. The application may check to see if the request was honored with
* the {@link #getIntegState() getIntegState} method.<p>
*
* Disabling integrity will also automatically disable
! * confidentiality.<p>
*
* @param state a boolean value indicating whether integrity
* should be enabled or not.
* @see #getIntegState()
*
--- 1073,1083 ----
* might enable it even if the application doesn't request
* it. The application may check to see if the request was honored with
* the {@link #getIntegState() getIntegState} method.<p>
*
* Disabling integrity will also automatically disable
! * confidentiality.
*
* @param state a boolean value indicating whether integrity
* should be enabled or not.
* @see #getIntegState()
*
*** 1093,1103 ****
* side and it has to be done prior to the first call to
* <code>initSecContext</code>.<p>
*
* The actual lifetime of the context will depend on the capabilities of
* the underlying mechanism and the application should call the {@link
! * #getLifetime() getLifetime} method to determine this.<p>
*
* @param lifetime the desired context lifetime in seconds. Use
* <code>INDEFINITE_LIFETIME</code> to request an indefinite lifetime
* and <code>DEFAULT_LIFETIME</code> to request a default lifetime.
* @see #getLifetime()
--- 1093,1103 ----
* side and it has to be done prior to the first call to
* <code>initSecContext</code>.<p>
*
* The actual lifetime of the context will depend on the capabilities of
* the underlying mechanism and the application should call the {@link
! * #getLifetime() getLifetime} method to determine this.
*
* @param lifetime the desired context lifetime in seconds. Use
* <code>INDEFINITE_LIFETIME</code> to request an indefinite lifetime
* and <code>DEFAULT_LIFETIME</code> to request a default lifetime.
* @see #getLifetime()
*** 1131,1141 ****
* context acceptor. For a definitive answer this method must be
* called only after context establishment is complete. Note that if an
* initiator requests that delegation not be allowed the {@link
* #requestCredDeleg(boolean) requestCredDeleg} method will honor that
* request and this method will return <code>false</code> on the
! * initiator's side from that point onwards. <p>
*
* @return true if delegation is enabled, false otherwise.
* @see #requestCredDeleg(boolean)
*/
public boolean getCredDelegState();
--- 1131,1141 ----
* context acceptor. For a definitive answer this method must be
* called only after context establishment is complete. Note that if an
* initiator requests that delegation not be allowed the {@link
* #requestCredDeleg(boolean) requestCredDeleg} method will honor that
* request and this method will return <code>false</code> on the
! * initiator's side from that point onwards.
*
* @return true if delegation is enabled, false otherwise.
* @see #requestCredDeleg(boolean)
*/
public boolean getCredDelegState();
*** 1145,1155 ****
* this context. It can be called by both the context initiator and the
* context acceptor. For a definitive answer this method must be
* called only after context establishment is complete. An initiator
* that requests mutual authentication can call this method after
* context completion and dispose the context if its request was not
! * honored.<p>
*
* @return true if mutual authentication is enabled, false otherwise.
* @see #requestMutualAuth(boolean)
*/
public boolean getMutualAuthState();
--- 1145,1155 ----
* this context. It can be called by both the context initiator and the
* context acceptor. For a definitive answer this method must be
* called only after context establishment is complete. An initiator
* that requests mutual authentication can call this method after
* context completion and dispose the context if its request was not
! * honored.
*
* @return true if mutual authentication is enabled, false otherwise.
* @see #requestMutualAuth(boolean)
*/
public boolean getMutualAuthState();
*** 1159,1169 ****
* per-message security services from this context. It can be called by
* both the context initiator and the context acceptor. For a
* definitive answer this method must be called only after context
* establishment is complete. An initiator that requests replay
* detection can call this method after context completion and
! * dispose the context if its request was not honored.<p>
*
* @return true if replay detection is enabled, false otherwise.
* @see #requestReplayDet(boolean)
*/
public boolean getReplayDetState();
--- 1159,1169 ----
* per-message security services from this context. It can be called by
* both the context initiator and the context acceptor. For a
* definitive answer this method must be called only after context
* establishment is complete. An initiator that requests replay
* detection can call this method after context completion and
! * dispose the context if its request was not honored.
*
* @return true if replay detection is enabled, false otherwise.
* @see #requestReplayDet(boolean)
*/
public boolean getReplayDetState();
*** 1173,1183 ****
* per-message security services from this context. It can be called by
* both the context initiator and the context acceptor. For a
* definitive answer this method must be called only after context
* establishment is complete. An initiator that requests sequence
* checking can call this method after context completion and
! * dispose the context if its request was not honored.<p>
*
* @return true if sequence checking is enabled, false otherwise.
* @see #requestSequenceDet(boolean)
*/
public boolean getSequenceDetState();
--- 1173,1183 ----
* per-message security services from this context. It can be called by
* both the context initiator and the context acceptor. For a
* definitive answer this method must be called only after context
* establishment is complete. An initiator that requests sequence
* checking can call this method after context completion and
! * dispose the context if its request was not honored.
*
* @return true if sequence checking is enabled, false otherwise.
* @see #requestSequenceDet(boolean)
*/
public boolean getSequenceDetState();
*** 1193,1203 ****
* authenticated anonymously should call this method after each call to
* <code>initSecContext</code> to determine if the generated token
* should be sent to the peer or the context aborted.</strong> On the
* acceptor side, a call to this method determines if any of the tokens
* processed by <code>acceptSecContext</code> thus far have divulged
! * the identity of the initiator.<p>
*
* @return true if the context initiator is still anonymous, false
* otherwise.
* @see #requestAnonymity(boolean)
*/
--- 1193,1203 ----
* authenticated anonymously should call this method after each call to
* <code>initSecContext</code> to determine if the generated token
* should be sent to the peer or the context aborted.</strong> On the
* acceptor side, a call to this method determines if any of the tokens
* processed by <code>acceptSecContext</code> thus far have divulged
! * the identity of the initiator.
*
* @return true if the context initiator is still anonymous, false
* otherwise.
* @see #requestAnonymity(boolean)
*/
*** 1233,1243 ****
* over the context. This method can be called by both the context
* initiator and the context acceptor, but only after one of {@link
* #isProtReady() isProtReady} or {@link #isEstablished()
* isEstablished} return <code>true</code>. If this method returns
* <code>true</code>, so will {@link #getIntegState()
! * getIntegState}<p>
*
* @return true if confidentiality services are available, false
* otherwise.
* @see #requestConf(boolean)
*/
--- 1233,1243 ----
* over the context. This method can be called by both the context
* initiator and the context acceptor, but only after one of {@link
* #isProtReady() isProtReady} or {@link #isEstablished()
* isEstablished} return <code>true</code>. If this method returns
* <code>true</code>, so will {@link #getIntegState()
! * getIntegState}
*
* @return true if confidentiality services are available, false
* otherwise.
* @see #requestConf(boolean)
*/
*** 1248,1258 ****
* over the context. This method can be called by both the context
* initiator and the context acceptor, but only after one of {@link
* #isProtReady() isProtReady} or {@link #isEstablished()
* isEstablished} return <code>true</code>. This method will always
* return <code>true</code> if {@link #getConfState() getConfState}
! * returns true.<p>
*
* @return true if integrity services are available, false otherwise.
* @see #requestInteg(boolean)
*/
public boolean getIntegState();
--- 1248,1258 ----
* over the context. This method can be called by both the context
* initiator and the context acceptor, but only after one of {@link
* #isProtReady() isProtReady} or {@link #isEstablished()
* isEstablished} return <code>true</code>. This method will always
* return <code>true</code> if {@link #getConfState() getConfState}
! * returns true.
*
* @return true if integrity services are available, false otherwise.
* @see #requestInteg(boolean)
*/
public boolean getIntegState();
*** 1260,1270 ****
/**
* Determines what the remaining lifetime for this
* context is. It can be called by both the context initiator and the
* context acceptor, but for a definitive answer it should be called
* only after {@link #isEstablished() isEstablished} returns
! * true.<p>
*
* @return the remaining lifetime in seconds
* @see #requestLifetime(int)
*/
public int getLifetime();
--- 1260,1270 ----
/**
* Determines what the remaining lifetime for this
* context is. It can be called by both the context initiator and the
* context acceptor, but for a definitive answer it should be called
* only after {@link #isEstablished() isEstablished} returns
! * true.
*
* @return the remaining lifetime in seconds
* @see #requestLifetime(int)
*/
public int getLifetime();
< prev index next >