001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: KeyProvider.java,v 1.5 2009/07/02 21:53:26 madan_ranganath Exp $
026 *
027 */
028
029/*
030 * Portions Copyrighted 2013-2016 ForgeRock AS.
031 */
032
033package com.sun.identity.saml.xmlsig;
034
035import java.security.KeyStore;
036import java.security.PrivateKey;
037import java.security.cert.Certificate;
038
039import javax.crypto.SecretKey;
040
041/**
042 * The class <code>KeyProvider</code> is an interface
043 * that is implemented to retrieve X509Certificates and Private Keys from
044 * user data store.  
045 * <p>
046 *
047 * @supported.all.api
048 */
049
050public interface KeyProvider {
051
052    /**
053     * Set the key to access key store database. This method will only need to 
054     * be called once if the key could not be obtained by other means. 
055     * @param storepass  password for the key store
056     * @param keypass password for the certificate
057     */
058    public void setKey(String storepass, String keypass); 
059
060    /**
061     * Return <code>java.security.cert.X509Certificate</code> for the specified
062     * <code>certAlias</code>.
063     * @param certAlias Certificate alias name 
064     * @return <code>X509Certificate</code> which matches the
065     *         <code>certAlias</code>, return null if the certificate could not
066     *         be found.
067     */
068    public java.security.cert.X509Certificate getX509Certificate (
069           String certAlias); 
070
071    /**
072     * Returns <code>java.security.PublicKey</code> for the specified
073     * <code>keyAlias</code>
074     *
075     * @param keyAlias Key alias name
076     * @return <code>PublicKey</code> which matches the <code>keyAlias</code>,
077     *         return null if the <code>PublicKey</code> could not be found.
078     */
079    public java.security.PublicKey getPublicKey (String keyAlias);
080
081    /**
082     * Returns <code>java.security.PrivateKey</code> for the specified
083     * <code>certAlias</code>.
084     *
085     * @param certAlias Certificate alias name  
086     * @return <code>PrivateKey</code> which matches the <code>certAlias</code>,
087     *         return null if the private key could not be found.
088     */
089    public java.security.PrivateKey getPrivateKey (String certAlias);
090
091    /**
092     * Retrieves the secret key for the given certificate alias.
093     *
094     * @param certAlias
095     *         the certificate alieas
096     *
097     * @return the secret key or returns {@literal null} if the key does
098     * not exist or this key provider does not support secret keys
099     */
100    SecretKey getSecretKey(String certAlias);
101
102    /**
103     * Return the {@link java.security.PrivateKey} for the specified certAlias and encrypted private key password.
104     * @param certAlias Certificate alias name
105     * @param encryptedKeyPass The encrypted keypass to use when getting the private certificate
106     * @return PrivateKey which matches the certAlias, return null if
107    the private key could not be found.
108     */
109    public PrivateKey getPrivateKey (String certAlias, String encryptedKeyPass);
110
111     /**
112     * Get the alias name of the first keystore entry whose certificate matches 
113     * the given certificate. 
114     * @param cert Certificate 
115     * @return the (alias) name of the first entry with matching certificate,
116     *       or null if no such entry exists in this keystore. If the keystore 
117     *       has not been loaded properly, return null as well. 
118     */
119    public String getCertificateAlias(Certificate cert); 
120
121    /**
122     * Returns <code>java.security.PrivateKey</code> for the given
123     * <code>X509Certificate</code>.
124     *
125     * @param cert <code>X509Certificate</code>
126     * @return <code>PrivateKey</code> which matches the certificate,
127     *         return null if the private key could not be found.
128     */
129    /* public java.security.PrivateKey getPrivateKey (
130           java.security.cert.X509Certificate cert); */
131
132    /**
133     * Returns certificate corresponding to the specified
134     * <code>PublicKey</code>.
135     *
136     * @param publicKey Certificate public key
137     * @return Certificate which matches the <code>PublicKey</code>, return
138     *         null if the Certificate could not be found.
139     */
140    public Certificate getCertificate (
141            java.security.PublicKey publicKey);
142
143    /**
144     * Returns the keystore instance.
145     * @return the keystore instance.
146     */
147    public KeyStore getKeyStore();
148
149    /**
150     * Whether the key alias exists in the keystore.
151     *
152     * @param alias
153     *         the key alias
154     *
155     * @return whether the key alias exists
156     */
157    boolean containsKey(String alias);
158
159}