1 /* SSLSession.java -- an SSL session. 2 Copyright (C) 2004 Free Software Foundation, Inc. 3 4 This file is part of GNU Classpath. 5 6 GNU Classpath is free software; you can redistribute it and/or modify 7 it under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2, or (at your option) 9 any later version. 10 11 GNU Classpath is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with GNU Classpath; see the file COPYING. If not, write to the 18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA. 20 21 Linking this library statically or dynamically with other modules is 22 making a combined work based on this library. Thus, the terms and 23 conditions of the GNU General Public License cover the whole 24 combination. 25 26 As a special exception, the copyright holders of this library give you 27 permission to link this library with independent modules to produce an 28 executable, regardless of the license terms of these independent 29 modules, and to copy and distribute the resulting executable under 30 terms of your choice, provided that you also meet, for each linked 31 independent module, the terms and conditions of the license of that 32 module. An independent module is a module which is not derived from 33 or based on this library. If you modify this library, you may extend 34 this exception to your version of the library, but you are not 35 obligated to do so. If you do not wish to do so, delete this 36 exception statement from your version. */ 37 38 39 package javax.net.ssl; 40 41 import java.security.Principal; 42 import java.security.cert.Certificate; 43 44 import javax.security.cert.X509Certificate; 45 46 /** 47 * An SSL session is a mechanism through which connections can be established 48 * by re-using previously negotiated handshakes. 49 */ 50 public interface SSLSession 51 { 52 53 /** 54 * Returns the size of the largest application data buffer that can 55 * occur in this session. 56 * 57 * <p>Buffers passed to handle the incoming data for the 58 * <code>unwrap</code> method of SSLEngine must be at least this 59 * large. 60 * 61 * @return The size of application buffers. 62 * @since 1.5 63 */ getApplicationBufferSize()64 int getApplicationBufferSize (); 65 66 /** 67 * Returns this session's cihper suite. 68 * 69 * @return The cipher suite. 70 */ getCipherSuite()71 String getCipherSuite(); 72 73 /** 74 * Returns the time in milliseconds since midnight GMT, 1 January 1970, that 75 * this session was created. 76 * 77 * @return The creation time. 78 */ getCreationTime()79 long getCreationTime(); 80 81 /** 82 * Returns this session's unique identifier, a arbitrary byte array of up 83 * to 32 bytes. 84 * 85 * @return The session identifier. 86 */ getId()87 byte[] getId(); 88 89 /** 90 * Returns the last time this session was accessed. 91 * 92 * @return The lest time this session was accessed. 93 */ getLastAccessedTime()94 long getLastAccessedTime(); 95 96 /** 97 * Returns the chain of certificates that the local side used in the 98 * handshake, or null if none were used. 99 * 100 * @return The local certificate chain. 101 */ getLocalCertificates()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 */ getLocalPrincipal()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 */ getPacketBufferSize()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 */ getPeerCertificates()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 */ getPeerCertificateChain()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 */ getPeerHost()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 */ getPeerPort()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 */ getPeerPrincipal()173 Principal getPeerPrincipal () throws SSLPeerUnverifiedException; 174 175 /** 176 * Returns the protocol this session uses. 177 * 178 * @return The protocol. 179 */ getProtocol()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 */ getSessionContext()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 */ getValueNames()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 */ getValue(String name)204 Object getValue(String name); 205 206 /** 207 * Invalidates this session, ensuring that it will not be continued by 208 * another socket. 209 */ invalidate()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 */ isValid()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 */ putValue(String name, Object value)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 */ removeValue(String name)234 void removeValue(String name); 235 } 236