SSLSession.java revision 6b811c5daec1b28e6f63b57f98a032236f2c3cf7 
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
18package javax.net.ssl;
19
20import java.security.Principal;
21import java.security.cert.Certificate;
22import javax.security.cert.X509Certificate;
23
24/**
25 * The interface representing an SSL session.
26 */
27public 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