001 /* SSLSession.java -- an SSL session.
002 Copyright (C) 2004 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package javax.net.ssl;
040
041 import java.security.Principal;
042 import java.security.cert.Certificate;
043
044 import 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 */
050 public 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 }