18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.net.ssl;
27
28 import java.security.Principal;
29
30 /**
31 * In SSL, sessions are used to describe an ongoing relationship between
32 * two entities. Each SSL connection involves one session at a time, but
33 * that session may be used on many connections between those entities,
34 * simultaneously or sequentially. The session used on a connection may
35 * also be replaced by a different session. Sessions are created, or
36 * rejoined, as part of the SSL handshaking protocol. Sessions may be
37 * invalidated due to policies affecting security or resource usage,
38 * or by an application explicitly calling <code>invalidate</code>.
39 * Session management policies are typically used to tune performance.
40 *
41 * <P> In addition to the standard session attributes, SSL sessions expose
42 * these read-only attributes: <UL>
43 *
44 * <LI> <em>Peer Identity.</em> Sessions are between a particular
45 * client and a particular server. The identity of the peer may
46 * have been established as part of session setup. Peers are
47 * generally identified by X.509 certificate chains.
48 *
49 * <LI> <em>Cipher Suite Name.</em> Cipher suites describe the
50 * kind of cryptographic protection that's used by connections
51 * in a particular session.
52 *
53 * <LI> <em>Peer Host.</em> All connections in a session are
54 * between the same two hosts. The address of the host on the other
55 * side of the connection is available.
56 *
57 * </UL>
58 *
65 public interface SSLSession {
66
67 /**
68 * Returns the identifier assigned to this Session.
69 *
70 * @return the Session identifier
71 */
72 public byte[] getId();
73
74
75 /**
76 * Returns the context in which this session is bound.
77 * <P>
78 * This context may be unavailable in some environments,
79 * in which case this method returns null.
80 * <P>
81 * If the context is available and there is a
82 * security manager installed, the caller may require
83 * permission to access it or a security exception may be thrown.
84 * In a Java environment, the security manager's
85 * <code>checkPermission</code> method is called with a
86 * <code>SSLPermission("getSSLSessionContext")</code> permission.
87 *
88 * @throws SecurityException if the calling thread does not have
89 * permission to get SSL session context.
90 * @return the session context used for this session, or null
91 * if the context is unavailable.
92 */
93 public SSLSessionContext getSessionContext();
94
95
96 /**
97 * Returns the time at which this Session representation was created,
98 * in milliseconds since midnight, January 1, 1970 UTC.
99 *
100 * @return the time this Session was created
101 */
102 public long getCreationTime();
103
104
105 /**
106 * Returns the last time this Session representation was accessed by the
131 *
132 * @see #isValid()
133 */
134 public void invalidate();
135
136
137 /**
138 * Returns whether this session is valid and available for resuming or
139 * joining.
140 *
141 * @return true if this session may be rejoined.
142 * @see #invalidate()
143 *
144 * @since 1.5
145 */
146 public boolean isValid();
147
148
149 /**
150 *
151 * Binds the specified <code>value</code> object into the
152 * session's application layer data
153 * with the given <code>name</code>.
154 * <P>
155 * Any existing binding using the same <code>name</code> is
156 * replaced. If the new (or existing) <code>value</code> implements the
157 * <code>SSLSessionBindingListener</code> interface, the object
158 * represented by <code>value</code> is notified appropriately.
159 * <p>
160 * For security reasons, the same named values may not be
161 * visible across different access control contexts.
162 *
163 * @param name the name to which the data object will be bound.
164 * This may not be null.
165 * @param value the data object to be bound. This may not be null.
166 * @throws IllegalArgumentException if either argument is null.
167 */
168 public void putValue(String name, Object value);
169
170
171 /**
172 * Returns the object bound to the given name in the session's
173 * application layer data. Returns null if there is no such binding.
174 * <p>
175 * For security reasons, the same named values may not be
176 * visible across different access control contexts.
177 *
178 * @param name the name of the binding to find.
179 * @return the value bound to that name, or null if the binding does
180 * not exist.
181 * @throws IllegalArgumentException if the argument is null.
182 */
183 public Object getValue(String name);
184
185
186 /**
187 * Removes the object bound to the given name in the session's
188 * application layer data. Does nothing if there is no object
189 * bound to the given name. If the bound existing object
190 * implements the <code>SessionBindingListener</code> interface,
191 * it is notified appropriately.
192 * <p>
193 * For security reasons, the same named values may not be
194 * visible across different access control contexts.
195 *
196 * @param name the name of the object to remove visible
197 * across different access control contexts
198 * @throws IllegalArgumentException if the argument is null.
199 */
200 public void removeValue(String name);
201
202
203 /**
204 * Returns an array of the names of all the application layer
205 * data objects bound into the Session.
206 * <p>
207 * For security reasons, the same named values may not be
208 * visible across different access control contexts.
209 *
210 * @return a non-null (possibly empty) array of names of the objects
332 *
333 * <P> This defines the protocol used in the connection.
334 *
335 * @return the standard name of the protocol used for all
336 * connections in the session.
337 */
338 public String getProtocol();
339
340 /**
341 * Returns the host name of the peer in this session.
342 * <P>
343 * For the server, this is the client's host; and for
344 * the client, it is the server's host. The name may not be
345 * a fully qualified host name or even a host name at all as
346 * it may represent a string encoding of the peer's network address.
347 * If such a name is desired, it might
348 * be resolved through a name service based on the value returned
349 * by this method.
350 * <P>
351 * This value is not authenticated and should not be relied upon.
352 * It is mainly used as a hint for <code>SSLSession</code> caching
353 * strategies.
354 *
355 * @return the host name of the peer host, or null if no information
356 * is available.
357 */
358 public String getPeerHost();
359
360 /**
361 * Returns the port number of the peer in this session.
362 * <P>
363 * For the server, this is the client's port number; and for
364 * the client, it is the server's port number.
365 * <P>
366 * This value is not authenticated and should not be relied upon.
367 * It is mainly used as a hint for <code>SSLSession</code> caching
368 * strategies.
369 *
370 * @return the port number of the peer host, or -1 if no information
371 * is available.
372 *
373 * @since 1.5
374 */
375 public int getPeerPort();
376
377 /**
378 * Gets the current size of the largest SSL/TLS packet that is expected
379 * when using this session.
380 * <P>
381 * A <code>SSLEngine</code> using this session may generate SSL/TLS
382 * packets of any size up to and including the value returned by this
383 * method. All <code>SSLEngine</code> network buffers should be sized
384 * at least this large to avoid insufficient space problems when
385 * performing <code>wrap</code> and <code>unwrap</code> calls.
386 *
387 * @return the current maximum expected network packet size
388 *
389 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
390 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
391 *
392 * @since 1.5
393 */
394 public int getPacketBufferSize();
395
396
397 /**
398 * Gets the current size of the largest application data that is
399 * expected when using this session.
400 * <P>
401 * <code>SSLEngine</code> application data buffers must be large
402 * enough to hold the application data from any inbound network
403 * application data packet received. Typically, outbound
404 * application data buffers can be of any size.
405 *
406 * @return the current maximum expected application packet size
407 *
408 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
409 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
410 *
411 * @since 1.5
412 */
413 public int getApplicationBufferSize();
414 }
|
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.net.ssl;
27
28 import java.security.Principal;
29
30 /**
31 * In SSL, sessions are used to describe an ongoing relationship between
32 * two entities. Each SSL connection involves one session at a time, but
33 * that session may be used on many connections between those entities,
34 * simultaneously or sequentially. The session used on a connection may
35 * also be replaced by a different session. Sessions are created, or
36 * rejoined, as part of the SSL handshaking protocol. Sessions may be
37 * invalidated due to policies affecting security or resource usage,
38 * or by an application explicitly calling {@code invalidate}.
39 * Session management policies are typically used to tune performance.
40 *
41 * <P> In addition to the standard session attributes, SSL sessions expose
42 * these read-only attributes: <UL>
43 *
44 * <LI> <em>Peer Identity.</em> Sessions are between a particular
45 * client and a particular server. The identity of the peer may
46 * have been established as part of session setup. Peers are
47 * generally identified by X.509 certificate chains.
48 *
49 * <LI> <em>Cipher Suite Name.</em> Cipher suites describe the
50 * kind of cryptographic protection that's used by connections
51 * in a particular session.
52 *
53 * <LI> <em>Peer Host.</em> All connections in a session are
54 * between the same two hosts. The address of the host on the other
55 * side of the connection is available.
56 *
57 * </UL>
58 *
65 public interface SSLSession {
66
67 /**
68 * Returns the identifier assigned to this Session.
69 *
70 * @return the Session identifier
71 */
72 public byte[] getId();
73
74
75 /**
76 * Returns the context in which this session is bound.
77 * <P>
78 * This context may be unavailable in some environments,
79 * in which case this method returns null.
80 * <P>
81 * If the context is available and there is a
82 * security manager installed, the caller may require
83 * permission to access it or a security exception may be thrown.
84 * In a Java environment, the security manager's
85 * {@code checkPermission} method is called with a
86 * {@code SSLPermission("getSSLSessionContext")} permission.
87 *
88 * @throws SecurityException if the calling thread does not have
89 * permission to get SSL session context.
90 * @return the session context used for this session, or null
91 * if the context is unavailable.
92 */
93 public SSLSessionContext getSessionContext();
94
95
96 /**
97 * Returns the time at which this Session representation was created,
98 * in milliseconds since midnight, January 1, 1970 UTC.
99 *
100 * @return the time this Session was created
101 */
102 public long getCreationTime();
103
104
105 /**
106 * Returns the last time this Session representation was accessed by the
131 *
132 * @see #isValid()
133 */
134 public void invalidate();
135
136
137 /**
138 * Returns whether this session is valid and available for resuming or
139 * joining.
140 *
141 * @return true if this session may be rejoined.
142 * @see #invalidate()
143 *
144 * @since 1.5
145 */
146 public boolean isValid();
147
148
149 /**
150 *
151 * Binds the specified {@code value} object into the
152 * session's application layer data
153 * with the given {@code name}.
154 * <P>
155 * Any existing binding using the same {@code name} is
156 * replaced. If the new (or existing) {@code value} implements the
157 * {@code SSLSessionBindingListener} interface, the object
158 * represented by {@code value} is notified appropriately.
159 * <p>
160 * For security reasons, the same named values may not be
161 * visible across different access control contexts.
162 *
163 * @param name the name to which the data object will be bound.
164 * This may not be null.
165 * @param value the data object to be bound. This may not be null.
166 * @throws IllegalArgumentException if either argument is null.
167 */
168 public void putValue(String name, Object value);
169
170
171 /**
172 * Returns the object bound to the given name in the session's
173 * application layer data. Returns null if there is no such binding.
174 * <p>
175 * For security reasons, the same named values may not be
176 * visible across different access control contexts.
177 *
178 * @param name the name of the binding to find.
179 * @return the value bound to that name, or null if the binding does
180 * not exist.
181 * @throws IllegalArgumentException if the argument is null.
182 */
183 public Object getValue(String name);
184
185
186 /**
187 * Removes the object bound to the given name in the session's
188 * application layer data. Does nothing if there is no object
189 * bound to the given name. If the bound existing object
190 * implements the {@code SessionBindingListener} interface,
191 * it is notified appropriately.
192 * <p>
193 * For security reasons, the same named values may not be
194 * visible across different access control contexts.
195 *
196 * @param name the name of the object to remove visible
197 * across different access control contexts
198 * @throws IllegalArgumentException if the argument is null.
199 */
200 public void removeValue(String name);
201
202
203 /**
204 * Returns an array of the names of all the application layer
205 * data objects bound into the Session.
206 * <p>
207 * For security reasons, the same named values may not be
208 * visible across different access control contexts.
209 *
210 * @return a non-null (possibly empty) array of names of the objects
332 *
333 * <P> This defines the protocol used in the connection.
334 *
335 * @return the standard name of the protocol used for all
336 * connections in the session.
337 */
338 public String getProtocol();
339
340 /**
341 * Returns the host name of the peer in this session.
342 * <P>
343 * For the server, this is the client's host; and for
344 * the client, it is the server's host. The name may not be
345 * a fully qualified host name or even a host name at all as
346 * it may represent a string encoding of the peer's network address.
347 * If such a name is desired, it might
348 * be resolved through a name service based on the value returned
349 * by this method.
350 * <P>
351 * This value is not authenticated and should not be relied upon.
352 * It is mainly used as a hint for {@code SSLSession} caching
353 * strategies.
354 *
355 * @return the host name of the peer host, or null if no information
356 * is available.
357 */
358 public String getPeerHost();
359
360 /**
361 * Returns the port number of the peer in this session.
362 * <P>
363 * For the server, this is the client's port number; and for
364 * the client, it is the server's port number.
365 * <P>
366 * This value is not authenticated and should not be relied upon.
367 * It is mainly used as a hint for {@code SSLSession} caching
368 * strategies.
369 *
370 * @return the port number of the peer host, or -1 if no information
371 * is available.
372 *
373 * @since 1.5
374 */
375 public int getPeerPort();
376
377 /**
378 * Gets the current size of the largest SSL/TLS/DTLS packet that is
379 * expected when using this session.
380 * <P>
381 * An {@code SSLEngine} using this session may generate SSL/TLS/DTLS
382 * packets of any size up to and including the value returned by this
383 * method. All {@code SSLEngine} network buffers should be sized
384 * at least this large to avoid insufficient space problems when
385 * performing {@code wrap} and {@code unwrap} calls.
386 *
387 * @return the current maximum expected network packet size
388 *
389 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
390 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
391 *
392 * @since 1.5
393 */
394 public int getPacketBufferSize();
395
396
397 /**
398 * Gets the current size of the largest application data that is
399 * expected when using this session.
400 * <P>
401 * {@code SSLEngine} application data buffers must be large
402 * enough to hold the application data from any inbound network
403 * application data packet received. Typically, outbound
404 * application data buffers can be of any size.
405 *
406 * @return the current maximum expected application packet size
407 *
408 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
409 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
410 *
411 * @since 1.5
412 */
413 public int getApplicationBufferSize();
414 }
|