1 /* 2 * Copyright (c) 2003, 2018, 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 * Returns the cipher suite in use on the original connection that 44 * retrieved the network resource. 45 * 46 * @return a string representing the cipher suite 47 */ 48 public abstract String getCipherSuite(); 49 50 /** 51 * Returns the certificate chain that were sent to the server during 52 * handshaking of the original connection that retrieved the 53 * network resource. Note: This method is useful only 54 * when using certificate-based cipher suites. 55 * 56 * @return an immutable List of Certificate representing the 57 * certificate chain that was sent to the server. If no 58 * certificate chain was sent, null will be returned. 59 * @see #getLocalPrincipal() 60 */ 61 public abstract List<Certificate> getLocalCertificateChain(); 62 63 /** 64 * Returns the server's certificate chain, which was established as 65 * part of defining the session in the original connection that 66 * retrieved the network resource, from cache. Note: This method 67 * can be used only when using certificate-based cipher suites; 68 * using it with non-certificate-based cipher suites, such as 69 * Kerberos, will throw an SSLPeerUnverifiedException. 70 * 71 * @return an immutable List of Certificate representing the server's 72 * certificate chain. 73 * @throws SSLPeerUnverifiedException if the peer is not verified. 74 * @see #getPeerPrincipal() 75 */ 76 public abstract List<Certificate> getServerCertificateChain() 77 throws SSLPeerUnverifiedException; 78 79 /** 80 * Returns the server's principal which was established as part of 81 * defining the session during the original connection that 82 * retrieved the network resource. 83 * 84 * @return the server's principal. Returns an X500Principal of the 85 * end-entity certiticate for X509-based cipher suites, and 86 * KerberosPrincipal for Kerberos cipher suites. 87 * 88 * @throws SSLPeerUnverifiedException if the peer was not verified. 89 * 90 * @see #getServerCertificateChain() 91 * @see #getLocalPrincipal() 92 */ 93 public abstract Principal getPeerPrincipal() 94 throws SSLPeerUnverifiedException; 95 96 /** 97 * Returns the principal that was sent to the server during 98 * handshaking in the original connection that retrieved the 99 * network resource. 100 * 101 * @return the principal sent to the server. Returns an X500Principal 102 * of the end-entity certificate for X509-based cipher suites, and 103 * KerberosPrincipal for Kerberos cipher suites. If no principal was 104 * sent, then null is returned. 105 * 106 * @see #getLocalCertificateChain() 107 * @see #getPeerPrincipal() 108 */ 109 public abstract Principal getLocalPrincipal(); 110 111 /** 112 * Returns an {@link Optional} containing the {@code SSLSession} in 113 * use on the original connection that retrieved the network resource. 114 * Returns an empty {@code Optional} if the underlying implementation 115 * does not support this method. 116 * 117 * @implSpec For compatibility, the default implementation of this 118 * method returns an empty {@code Optional}. Subclasses 119 * should override this method with an appropriate 120 * implementation since an application may need to access 121 * additional parameters associated with the SSL session. 122 * 123 * @return an {@link Optional} containing the {@code SSLSession} in 124 * use on the original connection 125 * 126 * @see SSLSession 127 * 128 * @since 12 129 */ 130 public Optional<SSLSession> getSSLSession() { 131 return Optional.empty(); 132 } 133 }