1 /* 2 * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.net; 27 28 import java.security.cert.Certificate; 29 import javax.net.ssl.SSLSession; 30 import javax.net.ssl.SSLPeerUnverifiedException; 31 import java.security.Principal; 32 import java.util.List; 33 import java.util.Optional; 34 35 /** 36 * Represents a cache response originally retrieved through secure 37 * means, such as TLS. 38 * 39 * @since 1.5 40 */ 41 public abstract class SecureCacheResponse extends CacheResponse { 42 /** 43 * Constructor for subclasses to call. 44 */ 45 public SecureCacheResponse() {} 46 47 /** 48 * Returns the cipher suite in use on the original connection that 49 * retrieved the network resource. 50 * 51 * @return a string representing the cipher suite 52 */ 53 public abstract String getCipherSuite(); 54 55 /** 56 * Returns the certificate chain that were sent to the server during 57 * handshaking of the original connection that retrieved the 58 * network resource. Note: This method is useful only 59 * when using certificate-based cipher suites. 60 * 61 * @return an immutable List of Certificate representing the 62 * certificate chain that was sent to the server. If no 63 * certificate chain was sent, null will be returned. 64 * @see #getLocalPrincipal() 65 */ 66 public abstract List<Certificate> getLocalCertificateChain(); 67 68 /** 69 * Returns the server's certificate chain, which was established as 70 * part of defining the session in the original connection that 71 * retrieved the network resource, from cache. Note: This method 72 * can be used only when using certificate-based cipher suites; 73 * using it with non-certificate-based cipher suites, such as 74 * Kerberos, will throw an SSLPeerUnverifiedException. 75 * 76 * @return an immutable List of Certificate representing the server's 77 * certificate chain. 78 * @throws SSLPeerUnverifiedException if the peer is not verified. 79 * @see #getPeerPrincipal() 80 */ 81 public abstract List<Certificate> getServerCertificateChain() 82 throws SSLPeerUnverifiedException; 83 84 /** 85 * Returns the server's principal which was established as part of 86 * defining the session during the original connection that 87 * retrieved the network resource. 88 * 89 * @return the server's principal. Returns an X500Principal of the 90 * end-entity certificate for X509-based cipher suites, and 91 * KerberosPrincipal for Kerberos cipher suites. 92 * 93 * @throws SSLPeerUnverifiedException if the peer was not verified. 94 * 95 * @see #getServerCertificateChain() 96 * @see #getLocalPrincipal() 97 */ 98 public abstract Principal getPeerPrincipal() 99 throws SSLPeerUnverifiedException; 100 101 /** 102 * Returns the principal that was sent to the server during 103 * handshaking in the original connection that retrieved the 104 * network resource. 105 * 106 * @return the principal sent to the server. Returns an X500Principal 107 * of the end-entity certificate for X509-based cipher suites, and 108 * KerberosPrincipal for Kerberos cipher suites. If no principal was 109 * sent, then null is returned. 110 * 111 * @see #getLocalCertificateChain() 112 * @see #getPeerPrincipal() 113 */ 114 public abstract Principal getLocalPrincipal(); 115 116 /** 117 * Returns an {@link Optional} containing the {@code SSLSession} in 118 * use on the original connection that retrieved the network resource. 119 * Returns an empty {@code Optional} if the underlying implementation 120 * does not support this method. 121 * 122 * @implSpec For compatibility, the default implementation of this 123 * method returns an empty {@code Optional}. Subclasses 124 * should override this method with an appropriate 125 * implementation since an application may need to access 126 * additional parameters associated with the SSL session. 127 * 128 * @return an {@link Optional} containing the {@code SSLSession} in 129 * use on the original connection 130 * 131 * @see SSLSession 132 * 133 * @since 12 134 */ 135 public Optional<SSLSession> getSSLSession() { 136 return Optional.empty(); 137 } 138 }