SSLSession


1   /*
2    * @(#)SSLSession.java  1.14 04/02/16
3    *
4    * Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL.  Use is subject to license terms.
6    */
7     
8   /*
9    * NOTE:
10   * Because of various external restrictions (i.e. US export
11   * regulations, etc.), the actual source code can not be provided
12   * at this time. This file represents the skeleton of the source
13   * file, so that javadocs of the API can be created.
14   */
15  
16  package javax.net.ssl;
17  
18  import java.net.InetAddress;
19  import java.security.Principal;
20  
21  /** 
22   * In SSL, sessions are used to describe an ongoing relationship between
23   * two entities.  Each SSL connection involves one session at a time, but
24   * that session may be used on many connections between those entities,
25   * simultaneously or sequentially.  The session used on a connection may
26   * also be replaced by a different session.  Sessions are created, or
27   * rejoined, as part of the SSL handshaking protocol. Sessions may be
28   * invalidated due to policies affecting security or resource usage,
29   * or by an application explicitly calling <code>invalidate</code>.
30   * Session management policies are typically used to tune performance.
31   *
32   * <P> In addition to the standard session attributes, SSL sessions expose
33   * these read-only attributes:  <UL>
34   *
35   *  <LI> <em>Peer Identity.</em>  Sessions are between a particular
36   *  client and a particular server.  The identity of the peer may
37   *  have been established as part of session setup.  Peers are
38   *  generally identified by X.509 certificate chains.
39   *
40   *  <LI> <em>Cipher Suite Name.</em>  Cipher suites describe the
41   *  kind of cryptographic protection that's used by connections
42   *  in a particular session.
43   *
44   *  <LI> <em>Peer Host.</em>  All connections in a session are
45   *  between the same two hosts.  The address of the host on the other
46   *  side of the connection is available.
47   *
48   *  </UL>
49   *
50   * <P> Sessions may be explicitly invalidated.  Invalidation may also
51   * be done implicitly, when faced with certain kinds of errors.
52   *
53   * @since 1.4
54   * @version 1.31
55   * @author David Brownell
56   */
57  public interface SSLSession
58  {
59  
60      /** 
61       * Returns the identifier assigned to this Session.
62       *
63       * @return the Session identifier
64       */
65      public byte[] getId();
66  
67      /** 
68       * Returns the context in which this session is bound.
69       * <P>
70       * This context may be unavailable in some environments,
71       * in which case this method returns null.
72       * <P>
73       * If the context is available and there is a
74       * security manager installed, the caller may require
75       * permission to access it or a security exception may be thrown.
76       * In a Java 2 environment, the security manager's
77       * <code>checkPermission</code> method is called with a
78       * <code>SSLPermission("getSSLSessionContext")</code> permission.
79       *
80       * @return the session context used for this session, or null
81       * if the context is unavailable.
82       */
83      public SSLSessionContext getSessionContext();
84  
85      /** 
86       * Returns the time at which this Session representation was created,
87       * in milliseconds since midnight, January 1, 1970 UTC.
88       *
89       * @return the time this Session was created
90       */
91      public long getCreationTime();
92  
93      /** 
94       * Returns the last time this Session representation was accessed by the
95       * session level infrastructure, in milliseconds since
96       * midnight, January 1, 1970 UTC.
97       * <P>
98       * Access indicates a new connection being established using session data.
99       * Application level operations, such as getting or setting a value
100      * associated with the session, are not reflected in this access time.
101      *
102      * <P> This information is particularly useful in session management
103      * policies.  For example, a session manager thread could leave all
104      * sessions in a given context which haven't been used in a long time;
105      * or, the sessions might be sorted according to age to optimize some task.
106      *
107      * @return the last time this Session was accessed
108      */
109     public long getLastAccessedTime();
110 
111     /** 
112      * Invalidates the session.
113      * <P>
114      * Future connections will not be able to
115      * resume or join this session.  However, any existing connection
116      * using this session can continue to use the session until the
117      * connection is closed.
118      *
119      * @see #isValid()
120      */
121     public void invalidate();
122 
123     /** 
124      * Returns whether this session is valid and available for resuming or
125      * joining.
126      *
127      * @return true if this session may be rejoined.
128      * @see #invalidate()
129      *
130      * @since 1.5
131      */
132     public boolean isValid();
133 
134     /** 
135      * Binds the specified <code>value</code> object into the
136      * session's application layer data
137      * with the given <code>name</code>.
138      * <P>
139      * Any existing binding using the same <code>name</code> is
140      * replaced.  If the new (or existing) <code>value</code> implements the
141      * <code>SSLSessionBindingListener</code> interface, the object
142      * represented by <code>value</code> is notified appropriately.
143      * <p>
144      * For security reasons, the same named values may not be
145      * visible across different access control contexts.
146      *
147      * @param name the name to which the data object will be bound.
148      *      This may not be null.
149      * @param value the data object to be bound. This may not be null.
150      * @throws IllegalArgumentException if either argument is null.
151      */
152     public void putValue(String name, Object value);
153 
154     /** 
155      * Returns the object bound to the given name in the session's
156      * application layer data.  Returns null if there is no such binding.
157      * <p>
158      * For security reasons, the same named values may not be
159      * visible across different access control contexts.
160      *
161      * @param name the name of the binding to find.
162      * @return the value bound to that name, or null if the binding does
163      *      not exist.
164      * @throws IllegalArgumentException if the argument is null.
165      */
166     public Object getValue(String name);
167 
168     /** 
169      * Removes the object bound to the given name in the session's
170      * application layer data.  Does nothing if there is no object
171      * bound to the given name.  If the bound existing object
172      * implements the <code>SessionBindingListener</code> interface,
173      * it is notified appropriately.
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 object to remove visible
179      *      across different access control contexts
180      * @throws IllegalArgumentException if the argument is null.
181      */
182     public void removeValue(String name);
183 
184     /** 
185      * Returns an array of the names of all the application layer
186      * data objects bound into the Session.
187      * <p>
188      * For security reasons, the same named values may not be
189      * visible across different access control contexts.
190      *
191      * @return a non-null (possibly empty) array of names of the objects
192      *  bound to this Session.
193      */
194     public String[] getValueNames();
195 
196     /** 
197      * Returns the identity of the peer which was established as part
198      * of defining the session.
199      * <P>
200      * Note: This method can be used only when using certificate-based
201      * cipher suites; using it with non-certificate-based cipher suites,
202      * such as Kerberos, will throw an SSLPeerUnverifiedException.
203      *
204      * @return an ordered array of peer certificates,
205      *      with the peer's own certificate first followed by any
206      *      certificate authorities.
207      * @exception SSLPeerUnverifiedException if the peer's identity has not
208      *      been verified
209      * @see #getPeerPrincipal()
210      */
211     public java.security.cert.Certificate[] getPeerCertificates()
212         throws SSLPeerUnverifiedException;
213 
214     /** 
215      * Returns the certificate(s) that were sent to the peer during
216      * handshaking.
217      * <P>
218      * Note: This method is useful only when using certificate-based
219      * cipher suites.
220      * <P>
221      * When multiple certificates are available for use in a
222      * handshake, the implementation chooses what it considers the
223      * "best" certificate chain available, and transmits that to
224      * the other side.  This method allows the caller to know
225      * which certificate chain was actually used.
226      *
227      * @return an ordered array of certificates,
228      * with the local certificate first followed by any
229      * certificate authorities.  If no certificates were sent,
230      * then null is returned.
231      *
232      * @see #getLocalPrincipal()
233      */
234     public java.security.cert.Certificate[] getLocalCertificates();
235 
236     /** 
237      * Returns the identity of the peer which was identified as part
238      * of defining the session.
239      * <P>
240      * Note: This method can be used only when using certificate-based
241      * cipher suites; using it with non-certificate-based cipher suites,
242      * such as Kerberos, will throw an SSLPeerUnverifiedException.
243      *
244      * <p><em>Note: this method exists for compatibility with previous
245      * releases. New applications should use
246      * {@link #getPeerCertificates} instead.</em></p>
247      *
248      * @return an ordered array of peer X.509 certificates,
249      *      with the peer's own certificate first followed by any
250      *      certificate authorities.  (The certificates are in
251      *      the original JSSE certificate
252      *      {@link javax.security.cert.X509Certificate} format.)
253      * @exception SSLPeerUnverifiedException if the peer's identity
254      *      has not been verified
255      * @see #getPeerPrincipal()
256      */
257     public javax.security.cert.X509Certificate[] getPeerCertificateChain()
258         throws SSLPeerUnverifiedException;
259 
260     /** 
261      * Returns the identity of the peer which was established as part of
262      * defining the session.
263      *
264      * @return the peer's principal. Returns an X500Principal of the
265      * end-entity certiticate for X509-based cipher suites, and
266      * KerberosPrincipal for Kerberos cipher suites.
267      *
268      * @throws SSLPeerUnverifiedException if the peer's identity has not
269      *      been verified
270      *
271      * @see #getPeerCertificates()
272      * @see #getLocalPrincipal()
273      *
274      * @since 1.5
275      */
276     public Principal getPeerPrincipal() throws SSLPeerUnverifiedException;
277 
278     /** 
279      * Returns the principal that was sent to the peer during handshaking.
280      *
281      * @return the principal sent to the peer. Returns an X500Principal
282      * of the end-entity certificate for X509-based cipher suites, and
283      * KerberosPrincipal for Kerberos cipher suites. If no principal was
284      * sent, then null is returned.
285      *
286      * @see #getLocalCertificates()
287      * @see #getPeerPrincipal()
288      *
289      * @since 1.5
290      */
291     public Principal getLocalPrincipal();
292 
293     /** 
294      * Returns the name of the SSL cipher suite which is used for all
295      * connections in the session.
296      *
297      * <P> This defines the level of protection
298      * provided to the data sent on the connection, including the kind
299      * of encryption used and most aspects of how authentication is done.
300      *
301      * @return the name of the session's cipher suite
302      */
303     public String getCipherSuite();
304 
305     /** 
306      * Returns the standard name of the protocol used for all
307      * connections in the session.
308      *
309      * <P> This defines the protocol used in the connection.
310      *
311      * @return the standard name of the protocol used for all
312      * connections in the session.
313      */
314     public String getProtocol();
315 
316     /** 
317      * Returns the host name of the peer in this session.
318      * <P>
319      * For the server, this is the client's host;  and for
320      * the client, it is the server's host. The name may not be
321      * a fully qualified host name or even a host name at all as
322      * it may represent a string encoding of the peer's network address.
323      * If such a name is desired, it might
324      * be resolved through a name service based on the value returned
325      * by this method.
326      * <P>
327      * This value is not authenticated and should not be relied upon.
328      * It is mainly used as a hint for <code>SSLSession</code> caching
329      * strategies.
330      *
331      * @return  the host name of the peer host, or null if no information
332      *      is available.
333      */
334     public String getPeerHost();
335 
336     /** 
337      * Returns the port number of the peer in this session.
338      * <P>
339      * For the server, this is the client's port number;  and for
340      * the client, it is the server's port number.
341      * <P>
342      * This value is not authenticated and should not be relied upon.
343      * It is mainly used as a hint for <code>SSLSession</code> caching
344      * strategies.
345      *
346      * @return  the port number of the peer host, or -1 if no information
347      *      is available.
348      *
349      * @since 1.5
350      */
351     public int getPeerPort();
352 
353     /** 
354      * Gets the size of the largest SSL/TLS packet that may occur
355      * when using this session.
356      * <P>
357      * A <code>SSLEngine</code> using this session may generate SSL/TLS
358      * packets of any size up to and including the value returned by this
359      * method.  All <code>SSLEngine</code> network buffers should be sized
360      * at least this large to avoid insufficient space problems when
361      * performing <code>wrap</code> and <code>unwrap</code calls.
362      *
363      * @return  the maximum network packet size
364      *
365      * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
366      * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
367      *
368      * @since 1.5
369      */
370     public int getPacketBufferSize();
371 
372     /** 
373      * Gets the size of the largest application buffer
374      * that may occur when using this session.
375      * <P>
376      * <code>SSLEngine</code> application data buffers must be large
377      * enough to hold the application data from any inbound network
378      * application data packet received.  Typically, outbound
379      * application data buffers can be of any size.
380      *
381      * @return  the maximum application packet size
382      *
383      * @see SSLEngine#wrap(ByteBuffer, ByteBuffer)
384      * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer)
385      *
386      * @since 1.5
387      */
388     public int getApplicationBufferSize();
389 }
390
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags