libcore/luni/src/main/java/javax/crypto/SecretKeyFactory.java

   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
  18 package javax.crypto;
  19
  20 import java.security.InvalidKeyException;
  21 import java.security.NoSuchAlgorithmException;
  22 import java.security.NoSuchProviderException;
  23 import java.security.Provider;
  24 import java.security.Security;
  25 import java.security.spec.InvalidKeySpecException;
  26 import java.security.spec.KeySpec;
  27 import org.apache.harmony.security.fortress.Engine;
  28
  29
  30 /**
  31  * The public API for {@code SecretKeyFactory} implementations.
  32  * <p>
  33  * Secret key factories provide the following functionality:
  34  * <ul>
  35  * <li>convert {@link SecretKey} objects to and from {@link KeySpec} objects</li>
  36  * <li>translate {@link SecretKey} objects from one provider implementation to
  37  * another</li>
  38  * </ul>
  39  * Which key specifications are supported by the {@link #generateSecret} and
  40  * {@link #getKeySpec} is provider dependent.
  41  */
  42 public class SecretKeyFactory {
  43
  44     // Used to access common engine functionality
  45     private static final Engine engine = new Engine("SecretKeyFactory");
  46
  47     // Store used provider
  48     private final Provider provider;
  49
  50     // Store used spi implementation
  51     private final SecretKeyFactorySpi spiImpl;
  52
  53     // Store used algorithm name
  54     private final String algorithm;
  55
  56     /**
  57      * Creates a new {@code SecretKeyFactory}
  58      *
  59      * @param keyFacSpi
  60      *            the SPI delegate.
  61      * @param provider
  62      *            the provider providing this key factory.
  63      * @param algorithm
  64      *            the algorithm name for the secret key.
  65      */
  66     protected SecretKeyFactory(SecretKeyFactorySpi keyFacSpi,
  67             Provider provider, String algorithm) {
  68         this.provider = provider;
  69         this.algorithm = algorithm;
  70         this.spiImpl = keyFacSpi;
  71     }
  72
  73     /**
  74      * Returns the name of the secret key algorithm.
  75      *
  76      * @return the name of the secret key algorithm.
  77      */
  78     public final String getAlgorithm() {
  79         return algorithm;
  80     }
  81
  82     /**
  83      * Returns the provider for this {@code SecretKeyFactory} instance.
  84      *
  85      * @return the provider for this {@code SecretKeyFactory} instance.
  86      */
  87     public final Provider getProvider() {
  88         return provider;
  89     }
  90
  91     /**
  92      * Creates a new {@code SecretKeyFactory} instance for the specified key
  93      * algorithm.
  94      *
  95      * @param algorithm
  96      *            the name of the key algorithm.
  97      * @return a secret key factory for the specified key algorithm.
  98      * @throws NoSuchAlgorithmException
  99      *             if no installed provider can provide the requested algorithm.
 100      * @throws NullPointerException
 101      *             if the specified algorithm is {@code null}.
 102      */
 103     public static final SecretKeyFactory getInstance(String algorithm)
 104             throws NoSuchAlgorithmException {
 105         if (algorithm == null) {
 106             throw new NullPointerException();
 107         }
 108         synchronized (engine) {
 109             engine.getInstance(algorithm, null);
 110             return new SecretKeyFactory((SecretKeyFactorySpi) engine.spi,
 111                     engine.provider, algorithm);
 112         }
 113     }
 114
 115     /**
 116      * Creates a new {@code SecretKeyFactory} instance for the specified key
 117      * algorithm from the specified {@code provider}.
 118      *
 119      * @param algorithm
 120      *            the name of the key algorithm.
 121      * @param provider
 122      *            the name of the provider that provides the requested
 123      *            algorithm.
 124      * @return a secret key factory for the specified key algorithm from the
 125      *         specified provider.
 126      * @throws NoSuchAlgorithmException
 127      *             if the specified provider cannot provide the requested
 128      *             algorithm.
 129      * @throws NoSuchProviderException
 130      *             if the specified provider does not exist.
 131      * @throws IllegalArgumentException
 132      *             if the specified provider name is {@code null} or empty.
 133      */
 134     public static final SecretKeyFactory getInstance(String algorithm,
 135             String provider) throws NoSuchAlgorithmException,
 136             NoSuchProviderException {
 137         if (provider == null || provider.isEmpty()) {
 138             throw new IllegalArgumentException("Provider is null or empty");
 139         }
 140         Provider impProvider = Security.getProvider(provider);
 141         if (impProvider == null) {
 142             throw new NoSuchProviderException(provider);
 143         }
 144         return getInstance(algorithm, impProvider);
 145     }
 146
 147     /**
 148      * Creates a new {@code SecretKeyFactory} instance for the specified key
 149      * algorithm from the specified provider.
 150      *
 151      * @param algorithm
 152      *            the name of the key algorithm.
 153      * @param provider
 154      *            the provider that provides the requested algorithm.
 155      * @return a secret key factory for the specified key algorithm from the
 156      *         specified provider.
 157      * @throws NoSuchAlgorithmException
 158      *             if the specified provider cannot provider the requested
 159      *             algorithm.
 160      * @throws IllegalArgumentException
 161      *             if the specified provider is {@code null}.
 162      * @throws NullPointerException
 163      *             is the specified algorithm name is {@code null}.
 164      */
 165     public static final SecretKeyFactory getInstance(String algorithm,
 166             Provider provider) throws NoSuchAlgorithmException {
 167         if (provider == null) {
 168             throw new IllegalArgumentException("provider == null");
 169         }
 170         if (algorithm == null) {
 171             throw new NullPointerException();
 172         }
 173         synchronized (engine) {
 174             engine.getInstance(algorithm, provider, null);
 175             return new SecretKeyFactory((SecretKeyFactorySpi) engine.spi, provider,
 176                     algorithm);
 177         }
 178     }
 179
 180     /**
 181      * Generate a secret key from the specified key specification.
 182      *
 183      * @param keySpec
 184      *            the key specification.
 185      * @return a secret key.
 186      * @throws InvalidKeySpecException
 187      *             if the specified key specification cannot be used to generate
 188      *             a secret key.
 189      */
 190     public final SecretKey generateSecret(KeySpec keySpec)
 191             throws InvalidKeySpecException {
 192         return spiImpl.engineGenerateSecret(keySpec);
 193     }
 194
 195     /**
 196      * Returns the key specification of the specified secret key.
 197      *
 198      * @param key
 199      *            the secret key to get the specification from.
 200      * @param keySpec
 201      *            the target key specification class.
 202      * @return an instance of the specified key specification class.
 203      * @throws InvalidKeySpecException
 204      *             if the specified secret key cannot be transformed into the
 205      *             requested key specification.
 206      */
 207     @SuppressWarnings("unchecked")
 208     public final KeySpec getKeySpec(SecretKey key, Class keySpec)
 209             throws InvalidKeySpecException {
 210         return spiImpl.engineGetKeySpec(key, keySpec);
 211     }
 212
 213     /**
 214      * Translates the specified secret key into an instance of the corresponding
 215      * key from the provider of this key factory.
 216      *
 217      * @param key
 218      *            the secret key to translate.
 219      * @return the corresponding translated key.
 220      * @throws InvalidKeyException
 221      *             if the specified key cannot be translated using this key
 222      *             factory.
 223      */
 224     public final SecretKey translateKey(SecretKey key)
 225             throws InvalidKeyException {
 226         return spiImpl.engineTranslateKey(key);
 227
 228     }
 229 }