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 }