1 /* 2 * Copyright (c) 1999, 2013, 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 javax.net.ssl; 27 28 import java.security.PrivateKey; 29 import java.security.Principal; 30 import java.security.cert.X509Certificate; 31 import java.net.Socket; 32 33 /** 34 * Instances of this interface manage which X509 certificate-based 35 * key pairs are used to authenticate the local side of a secure 36 * socket. 37 * <P> 38 * During secure socket negotiations, implentations 39 * call methods in this interface to: 40 * <UL> 41 * <LI> determine the set of aliases that are available for negotiations 42 * based on the criteria presented, 43 * <LI> select the <i> best alias</i> based on 44 * the criteria presented, and 45 * <LI> obtain the corresponding key material for given aliases. 46 * </UL> 47 * <P> 48 * Note: the X509ExtendedKeyManager should be used in favor of this 49 * class. 50 * 51 * @since 1.4 52 */ 53 public interface X509KeyManager extends KeyManager { 54 /** 55 * Get the matching aliases for authenticating the client side of a secure 56 * socket given the public key type and the list of 57 * certificate issuer authorities recognized by the peer (if any). 58 * 59 * @param keyType the key algorithm type name 60 * @param issuers the list of acceptable CA issuer subject names, 61 * or null if it does not matter which issuers are used. 62 * @return an array of the matching alias names, or null if there 63 * were no matches. 64 */ 65 public String[] getClientAliases(String keyType, Principal[] issuers); 66 67 /** 68 * Choose an alias to authenticate the client side of a secure 69 * socket given the public key type and the list of 70 * certificate issuer authorities recognized by the peer (if any). 71 * 72 * @param keyType the key algorithm type name(s), ordered 73 * with the most-preferred key type first. 74 * @param issuers the list of acceptable CA issuer subject names 75 * or null if it does not matter which issuers are used. 76 * @param socket the socket to be used for this connection. This 77 * parameter can be null, which indicates that 78 * implementations are free to select an alias applicable 79 * to any socket. 80 * @return the alias name for the desired key, or null if there 81 * are no matches. 82 */ 83 public String chooseClientAlias(String[] keyType, Principal[] issuers, 84 Socket socket); 85 86 /** 87 * Get the matching aliases for authenticating the server side of a secure 88 * socket given the public key type and the list of 89 * certificate issuer authorities recognized by the peer (if any). 90 * 91 * @param keyType the key algorithm type name 92 * @param issuers the list of acceptable CA issuer subject names 93 * or null if it does not matter which issuers are used. 94 * @return an array of the matching alias names, or null 95 * if there were no matches. 96 */ 97 public String[] getServerAliases(String keyType, Principal[] issuers); 98 99 /** 100 * Choose an alias to authenticate the server side of a secure 101 * socket given the public key type and the list of 102 * certificate issuer authorities recognized by the peer (if any). 103 * 104 * @param keyType the key algorithm type name. 105 * @param issuers the list of acceptable CA issuer subject names 106 * or null if it does not matter which issuers are used. 107 * @param socket the socket to be used for this connection. This 108 * parameter can be null, which indicates that 109 * implementations are free to select an alias applicable 110 * to any socket. 111 * @return the alias name for the desired key, or null if there 112 * are no matches. 113 */ 114 public String chooseServerAlias(String keyType, Principal[] issuers, 115 Socket socket); 116 117 /** 118 * Returns the certificate chain associated with the given alias. 119 * 120 * @param alias the alias name 121 * @return the certificate chain (ordered with the user's certificate first 122 * and the root certificate authority last), or null 123 * if the alias can't be found. 124 */ 125 public X509Certificate[] getCertificateChain(String alias); 126 127 /** 128 * Returns the key associated with the given alias. 129 * 130 * @param alias the alias name 131 * @return the requested key, or null if the alias can't be found. 132 */ 133 public PrivateKey getPrivateKey(String alias); 134 } 135
