001/* SSLSession.java -- an SSL session.
002   Copyright (C) 2004 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.net.ssl;
040
041import java.security.Principal;
042import java.security.cert.Certificate;
043
044import javax.security.cert.X509Certificate;
045
046/**
047 * An SSL session is a mechanism through which connections can be established
048 * by re-using previously negotiated handshakes.
049 */
050public interface SSLSession
051{
052
053  /**
054   * Returns the size of the largest application data buffer that can
055   * occur in this session.
056   *
057   * <p>Buffers passed to handle the incoming data for the
058   * <code>unwrap</code> method of SSLEngine must be at least this
059   * large.
060   *
061   * @return The size of application buffers.
062   * @since 1.5
063   */
064  int getApplicationBufferSize ();
065
066  /**
067   * Returns this session's cihper suite.
068   *
069   * @return The cipher suite.
070   */
071  String getCipherSuite();
072
073  /**
074   * Returns the time in milliseconds since midnight GMT, 1 January 1970, that
075   * this session was created.
076   *
077   * @return The creation time.
078   */
079  long getCreationTime();
080
081  /**
082   * Returns this session's unique identifier, a arbitrary byte array of up
083   * to 32 bytes.
084   *
085   * @return The session identifier.
086   */
087  byte[] getId();
088
089  /**
090   * Returns the last time this session was accessed.
091   *
092   * @return The lest time this session was accessed.
093   */
094  long getLastAccessedTime();
095
096  /**
097   * Returns the chain of certificates that the local side used in the
098   * handshake, or null if none were used.
099   *
100   * @return The local certificate chain.
101   */
102  Certificate[] getLocalCertificates();
103
104  /**
105   * Returns the {@link Principal} representing the local identity
106   * used in this session, or <code>null</code> if there is no local
107   * identity.
108   *
109   * @return The local principal.
110   */
111  Principal getLocalPrincipal ();
112
113  /**
114   * Returns the size of the largest SSL message that will be
115   * generated by this session.
116   *
117   * <p>Callers of <code>wrap</code> and <code>unwrap</code> should
118   * use this value to determine the size of buffers for data coming
119   * into, or going out over, the network.
120   *
121   * @returns The maximum network packet size.
122   * @since 1.5
123   */
124  int getPacketBufferSize ();
125
126  /**
127   * Returns the chain of certificates that the remote side used in
128   * the handshake, or null if none were used.
129   *
130   * @return The peer's certificate chain.
131   * @throws SSLPeerUnverifiedException If the identity of the peer has
132   *   not been verified.
133   */
134  Certificate[] getPeerCertificates() throws SSLPeerUnverifiedException;
135
136  /**
137   * Returns the chain of certificates that the remote side used in
138   * the handshake, or null if none were used.
139   *
140   * @return The peer's certificate chain.
141   * @throws SSLPeerUnverifiedException If the identity of the peer has
142   *   not been verified.
143   */
144  X509Certificate[] getPeerCertificateChain()
145    throws SSLPeerUnverifiedException;
146
147  /**
148   * Returns the remote host's name.
149   *
150   * @return The name of the remote host.
151   */
152  String getPeerHost();
153
154  /**
155   * Returns the port number the remote peer is using for this
156   * session.
157   *
158   * @return The peer's port number.
159   * @since 1.5
160   */
161  int getPeerPort ();
162
163  /**
164   * Returns the {@link Principal} representing the identity of the
165   * remote peer, or <code>null</code> if the remote peer has no known
166   * identity.
167   *
168   * @return The remote peer's principal.
169   * @throws SSLPeerUnverifiedException If the remote peer's identity
170   * could not be verified.
171   * @since 1.5
172   */
173  Principal getPeerPrincipal () throws SSLPeerUnverifiedException;
174
175  /**
176   * Returns the protocol this session uses.
177   *
178   * @return The protocol.
179   */
180  String getProtocol();
181
182  /**
183   * Returns this session's session context object.
184   *
185   * @return The session context.
186   * @throws SecurityException If the caller does not have the
187   *   {@link SSLPermission} "getSessionContext".
188   */
189  SSLSessionContext getSessionContext();
190
191  /**
192   * Returns the names of all values bound to this session.
193   *
194   * @return The list of bound names.
195   */
196  String[] getValueNames();
197
198  /**
199   * Returns the object bound to the given name.
200   *
201   * @param name The name of the value to get.
202   * @return The object bound by that name, or null.
203   */
204  Object getValue(String name);
205
206  /**
207   * Invalidates this session, ensuring that it will not be continued by
208   * another socket.
209   */
210  void invalidate();
211
212  /**
213   * Tells if this session is currently valid, and may be resumed.
214   *
215   * @return True if this session is valid.
216   * @since 1.5
217   * @see #invalidate()
218   */
219  boolean isValid ();
220
221  /**
222   * Binds a value to this session, with the given name.
223   *
224   * @param name The name to bind the object with.
225   * @param value The value to bind.
226   */
227  void putValue(String name, Object value);
228
229  /**
230   * Un-binds a value.
231   *
232   * @param name The name of the value to un-bind.
233   */
234  void removeValue(String name);
235}