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}