1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package javax.net.ssl;
19
20import java.net.Socket;
21import java.security.Principal;
22import java.security.PrivateKey;
23import java.security.cert.X509Certificate;
24
25/**
26 * A Key Manager for X509 certificate-based key pairs.
27 */
28public interface X509KeyManager extends KeyManager {
29
30    /**
31     * Chooses an alias for the client side of an SSL connection to authenticate
32     * it with the specified public key type and certificate issuers.
33     *
34     * @param keyType
35     *            the list of public key algorithm names.
36     * @param issuers
37     *            the list of certificate issuers, or {@code null} if any issuer
38     *            will do.
39     * @param socket
40     *            the socket for the connection, or {@code null} if
41     *            the alias selected does not depend on a specific socket.
42     * @return the alias name of a matching key or {@code null} if there are no
43     *         matches.
44     */
45    public String chooseClientAlias(String[] keyType, Principal[] issuers,
46            Socket socket);
47
48    /**
49     * Chooses an alias for the server side of an SSL connection to authenticate
50     * it with the specified public key type and certificate issuers.
51     *
52     * @param keyType
53     *            the list of public key algorithm type names.
54     * @param issuers
55     *            the list of certificate issuers, or {@code null} if any issuer
56     *            will do.
57     * @param socket
58     *            the socket for the connection, or {@code null} if
59     *            the alias selected does not depend on a specific socket.
60     * @return the alias name of a matching key or {@code null} if there are no
61     *         matches.
62     */
63    public String chooseServerAlias(String keyType, Principal[] issuers,
64            Socket socket);
65
66    /**
67     * Returns the certificate chain for the specified alias.
68     *
69     * @param alias
70     *            the alias to get the certificate chain for.
71     * @return the certificate chain for the specified alias, or {@code null} if
72     *         the alias cannot be found.
73     */
74    public X509Certificate[] getCertificateChain(String alias);
75
76    /**
77     * Returns the client aliases for the specified public key type and list of
78     * certificate issuers.
79     *
80     * @param keyType
81     *            the public key algorithm type name.
82     * @param issuers
83     *            the list of certificate issuers, or {@code null} if any issuer
84     *            will do.
85     * @return the client aliases for the specified public key type, or
86     *         {@code null} if there are no matching aliases.
87     */
88    public String[] getClientAliases(String keyType, Principal[] issuers);
89
90    /**
91     * Returns the server aliases for the specified public key type and list of
92     * certificate issuers.
93     *
94     * @param keyType
95     *            the public key algorithm type name.
96     * @param issuers
97     *            the list of certificate issuers, or {@code null} if any issuer
98     *            will do.
99     * @return the client aliases for the specified public key type, or
100     *         {@code null} if there are no matching aliases.
101     */
102    public String[] getServerAliases(String keyType, Principal[] issuers);
103
104    /**
105     * Returns the private key for the specified alias.
106     *
107     * @param alias
108     *            the alias to get the private key for.
109     * @return the private key for the specified alias, or {@code null} if the
110     *         alias cannot be found.
111     */
112    public PrivateKey getPrivateKey(String alias);
113}
114