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