1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package javax.net.ssl; 19 20 import java.security.Principal; 21 import java.security.cert.Certificate; 22 import javax.security.cert.X509Certificate; 23 24 /** 25 * The interface representing an SSL session. 26 */ 27 public interface SSLSession { 28 29 /** 30 * Returns the maximum size that an application buffer can be for this 31 * session. 32 * 33 * @return the maximum application buffer size. 34 */ 35 public int getApplicationBufferSize(); 36 37 /** 38 * Returns the name of the cipher suite used in this session. 39 * 40 * @return the name of the cipher suite used in this session. 41 */ 42 public String getCipherSuite(); 43 44 /** 45 * Returns the time this session was created, in milliseconds since midnight 46 * January 1st 1970 UTC. 47 * 48 * @return the time the session was created. 49 */ 50 public long getCreationTime(); 51 52 /** 53 * Returns this sessions identifier. 54 * 55 * @return this sessions identifier. 56 */ 57 public byte[] getId(); 58 59 /** 60 * Returns the time this session was last accessed, in milliseconds since 61 * midnight January 1st 1970 UTC. 62 * 63 * @return the time this session was last accessed. 64 */ 65 public long getLastAccessedTime(); 66 67 /** 68 * Returns the list of certificates that were used to identify the local 69 * side to the peer during the handshake. 70 * 71 * @return the list of certificates, ordered from local certificate to 72 * CA's certificates. 73 */ 74 public Certificate[] getLocalCertificates(); 75 76 /** 77 * Returns the principal used to identify the local side to the peer during 78 * the handshake. 79 * 80 * @return the principal used to identify the local side. 81 */ 82 public Principal getLocalPrincipal(); 83 84 /** 85 * Returns the maximum size that a network buffer can be for this session. 86 * 87 * @return the maximum network buffer size. 88 */ 89 public int getPacketBufferSize(); 90 91 /** 92 * Returns the list of certificates the peer used to identify itself during 93 * the handshake. 94 * <p> 95 * Note: this method exists for compatility reasons, use 96 * {@link #getPeerCertificates()} instead. 97 * 98 * @return the list of certificates, ordered from the identity certificate to 99 * the CA's certificates 100 * @throws SSLPeerUnverifiedException 101 * if the identity of the peer is not verified. 102 */ 103 public X509Certificate[] getPeerCertificateChain() throws SSLPeerUnverifiedException; 104 105 /** 106 * Returns the list of certificates the peer used to identify itself during 107 * the handshake. 108 * 109 * @return the list of certificates, ordered from the identity certificate to 110 * the CA's certificates. 111 * @throws SSLPeerUnverifiedException 112 * if the identity of the peer is not verified. 113 */ 114 public Certificate[] getPeerCertificates() throws SSLPeerUnverifiedException; 115 116 /** 117 * Returns the host name of the peer of this session. The host name is not 118 * authenticated. 119 * 120 * @return the host name of the peer of this session, or {@code null} if no 121 * host name is available. 122 */ 123 public String getPeerHost(); 124 125 /** 126 * Returns the port number of the peer of this session. The port number is 127 * not authenticated. 128 * 129 * @return the port number of the peer, of {@code -1} is no port number is 130 * available. 131 */ 132 public int getPeerPort(); 133 134 /** 135 * Returns the principal identifying the peer during the handshake. 136 * 137 * @return the principal identifying the peer. 138 * @throws SSLPeerUnverifiedException 139 * if the identity of the peer has not been verified. 140 */ 141 public Principal getPeerPrincipal() throws SSLPeerUnverifiedException; 142 143 /** 144 * Returns the protocol name that is used for all connections in this 145 * session. 146 * 147 * @return the protocol name that is used for all connections in this 148 * session. 149 */ 150 public String getProtocol(); 151 152 /** 153 * Returns the context of this session. If a context is available and a 154 * security manager is installed, the 155 * {@code SSLPermission("getSSLSessionContext"} is checked with the security 156 * manager. 157 * 158 * @return the context of this session or {@code null} if no context is 159 * available. 160 */ 161 public SSLSessionContext getSessionContext(); 162 163 /** 164 * Returns the object bound to the specified name in this session's 165 * application layer data. 166 * 167 * @param name 168 * the name of the bound value. 169 * @return the value bound to the specified name, or {@code null} if the 170 * specified name does not exist or is not accessible in the current 171 * access control context. 172 * @throws IllegalArgumentException 173 * if {@code name} is {@code null}. 174 */ 175 public Object getValue(String name); 176 177 /** 178 * Returns the list of the object names bound to this session's application 179 * layer data.. 180 * <p> 181 * Depending on the current access control context, the list of object names 182 * may be different. 183 * 184 * @return the list of the object names bound to this session's application 185 * layer data. 186 */ 187 public String[] getValueNames(); 188 189 /** 190 * Invalidates this session. 191 * <p> 192 * No new connections can be created, but any existing connection remains 193 * valid until it is closed. 194 */ 195 public void invalidate(); 196 197 /** 198 * Returns whether this session is valid. 199 * 200 * @return {@code true} if this session is valid, otherwise {@code false}. 201 */ 202 public boolean isValid(); 203 204 /** 205 * Binds the specified object under the specified name in this session's 206 * application layer data. 207 * <p> 208 * For bindings (new or existing) implementing the 209 * {@code SSLSessionBindingListener} interface the object will be notified. 210 * 211 * @param name 212 * the name to bind the object to. 213 * @param value 214 * the object to bind. 215 * @throws IllegalArgumentException 216 * if either {@code name} or {@code value} is {@code null}. 217 */ 218 public void putValue(String name, Object value); 219 220 /** 221 * Removes the binding for the specified name in this session's application 222 * layer data. If the existing binding implements the 223 * {@code SSLSessionBindingListener} interface the object will be notified. 224 * 225 * @param name 226 * the binding to remove. 227 * @throws IllegalArgumentException 228 * if {@code name} is {@code null}. 229 */ 230 public void removeValue(String name); 231 } 232
