1/* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements.  See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License.  You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16package java.net;
17
18import java.security.Principal;
19import java.security.cert.Certificate;
20import java.util.List;
21import javax.net.ssl.SSLPeerUnverifiedException;
22
23/**
24 * A secure cache response represents data which is originally retrieved over a
25 * secure connection. Such a connection can be secured by using a cryptographic
26 * protocol like TLS or SSL.
27 *
28 * @see ResponseCache
29 */
30public abstract class SecureCacheResponse extends CacheResponse {
31
32    /**
33     * Creates a new instance of this class.
34     */
35    public SecureCacheResponse() {
36    }
37
38    /**
39     * Gets the cipher suite string on the connection which is originally used
40     * to retrieve the network resource.
41     *
42     * @return the cipher suite string.
43     */
44    public abstract String getCipherSuite();
45
46    /**
47     * Gets the local certificate chain. When the original connection retrieved
48     * the resource data, this certificate chain was sent to the server during
49     * handshaking process. This method only takes effect when certificate-based
50     * cipher suite is enabled.
51     *
52     * @return the certificate chain that was sent to the server. If no
53     *         certificate chain was sent, the method returns {@code null}.
54     */
55    public abstract List<Certificate> getLocalCertificateChain();
56
57    /**
58     * Gets the cached server's certificate chain. As part of defining the
59     * session, the certificate chain was established when the original
60     * connection retrieved network resource. This method can only be invoked
61     * when certificated-based cipher suite is enabled. Otherwise, it throws an
62     * {@code SSLPeerUnverifiedException}.
63     *
64     * @return the server's certificate chain.
65     * @throws SSLPeerUnverifiedException
66     *             if the peer is unverified.
67     */
68    public abstract List<Certificate> getServerCertificateChain()
69            throws SSLPeerUnverifiedException;
70
71    /**
72     * Gets the server's principle. When the original connection retrieved
73     * network resource, the principle was established when defining the
74     * session.
75     *
76     * @return a principal object representing the server's principal.
77     * @throws SSLPeerUnverifiedException
78     *             if the peer is unverified.
79     */
80    public abstract Principal getPeerPrincipal()
81            throws SSLPeerUnverifiedException;
82
83    /**
84     * Gets the local principle that the original connection sent to the server.
85     * When the original connection fetched the network resource, the principle
86     * was sent to the server during handshaking process.
87     *
88     * @return the local principal object being sent to the server. Returns an
89     *         {@code X500Principal} object for X509-based cipher suites. If no
90     *         principal was sent, it returns {@code null}.
91     */
92    public abstract Principal getLocalPrincipal();
93}
94