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, or null if no context is available. 154 */ 155 public SSLSessionContext getSessionContext(); 156 157 /** 158 * Returns the object bound to the specified name in this session's 159 * application layer data. 160 * 161 * @param name 162 * the name of the bound value. 163 * @return the value bound to the specified name, or {@code null} if the 164 * specified name does not exist or is not accessible in the current 165 * access control context. 166 * @throws IllegalArgumentException 167 * if {@code name} is {@code null}. 168 */ 169 public Object getValue(String name); 170 171 /** 172 * Returns the list of the object names bound to this session's application 173 * layer data.. 174 * <p> 175 * Depending on the current access control context, the list of object names 176 * may be different. 177 * 178 * @return the list of the object names bound to this session's application 179 * layer data. 180 */ 181 public String[] getValueNames(); 182 183 /** 184 * Invalidates this session. 185 * <p> 186 * No new connections can be created, but any existing connection remains 187 * valid until it is closed. 188 */ 189 public void invalidate(); 190 191 /** 192 * Returns whether this session is valid. 193 * 194 * @return {@code true} if this session is valid, otherwise {@code false}. 195 */ 196 public boolean isValid(); 197 198 /** 199 * Binds the specified object under the specified name in this session's 200 * application layer data. 201 * <p> 202 * For bindings (new or existing) implementing the 203 * {@code SSLSessionBindingListener} interface the object will be notified. 204 * 205 * @param name 206 * the name to bind the object to. 207 * @param value 208 * the object to bind. 209 * @throws IllegalArgumentException 210 * if either {@code name} or {@code value} is {@code null}. 211 */ 212 public void putValue(String name, Object value); 213 214 /** 215 * Removes the binding for the specified name in this session's application 216 * layer data. If the existing binding implements the 217 * {@code SSLSessionBindingListener} interface the object will be notified. 218 * 219 * @param name 220 * the binding to remove. 221 * @throws IllegalArgumentException 222 * if {@code name} is {@code null}. 223 */ 224 public void removeValue(String name); 225 } 226
