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 34 /** 35 * Represents a cache response originally retrieved through secure 36 * means, such as TLS. 37 * 38 * @since 1.5 39 */ 40 public abstract class SecureCacheResponse extends CacheResponse { 41 /** 42 * Returns the cipher suite in use on the original connection that 43 * retrieved the network resource. 44 * 45 * @return a string representing the cipher suite 46 */ 47 public abstract String getCipherSuite(); 48 49 /** 50 * Returns the certificate chain that were sent to the server during 51 * handshaking of the original connection that retrieved the 52 * network resource. Note: This method is useful only 53 * when using certificate-based cipher suites. 54 * 55 * @return an immutable List of Certificate representing the 56 * certificate chain that was sent to the server. If no 57 * certificate chain was sent, null will be returned. 58 * @see #getLocalPrincipal() 59 */ 60 public abstract List<Certificate> getLocalCertificateChain(); 61 62 /** 63 * Returns the server's certificate chain, which was established as 64 * part of defining the session in the original connection that 65 * retrieved the network resource, from cache. Note: This method 66 * can be used only when using certificate-based cipher suites; 67 * using it with non-certificate-based cipher suites, such as 68 * Kerberos, will throw an SSLPeerUnverifiedException. 69 * 70 * @return an immutable List of Certificate representing the server's 71 * certificate chain. 72 * @throws SSLPeerUnverifiedException if the peer is not verified. 73 * @see #getPeerPrincipal() 74 */ 75 public abstract List<Certificate> getServerCertificateChain() 76 throws SSLPeerUnverifiedException; 77 78 /** 79 * Returns the server's principal which was established as part of 80 * defining the session during the original connection that 81 * retrieved the network resource. 82 * 83 * @return the server's principal. Returns an X500Principal of the 84 * end-entity certiticate for X509-based cipher suites, and 85 * KerberosPrincipal for Kerberos cipher suites. 86 * 87 * @throws SSLPeerUnverifiedException if the peer was not verified. 88 * 89 * @see #getServerCertificateChain() 90 * @see #getLocalPrincipal() 91 */ 92 public abstract Principal getPeerPrincipal() 93 throws SSLPeerUnverifiedException; 94 95 /** 96 * Returns the principal that was sent to the server during 97 * handshaking in the original connection that retrieved the 98 * network resource. 99 * 100 * @return the principal sent to the server. Returns an X500Principal 101 * of the end-entity certificate for X509-based cipher suites, and 102 * KerberosPrincipal for Kerberos cipher suites. If no principal was 103 * sent, then null is returned. 104 * 105 * @see #getLocalCertificateChain() 106 * @see #getPeerPrincipal() 107 */ 108 public abstract Principal getLocalPrincipal(); 109 110 /** 111 * Returns the {@code SSLSession} in use on the original connection that 112 * retrieved the network resource. 113 * 114 * @implSpec This method can be used to access security parameters on 115 * the original connection. For compatibility, the 116 * implementation in this class throws 117 * {@code UnsupportedOperationException}. Subclasses SHOULD 118 * override this method with appropriate implementation. 119 * 120 * @implNote As an application may have to use this operation for more 121 * security parameters, it is recommended to support this 122 * operation in all implementations. 123 * 124 * @return the {@code SSLSession} 125 * 126 * @throws UnsupportedOperationException if this method is not supported 127 * by the underlying implementation. 128 * 129 * @see SSLSession 130 * 131 * @since 12 132 */ 133 public SSLSession getSSLSession() { 134 throw new UnsupportedOperationException(); 135 } 136 }