Home | History | Annotate | Download | only in crypto 
      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.InvalidAlgorithmParameterException;
     21 import java.security.InvalidKeyException;
     22 import java.security.Key;
     23 import java.security.NoSuchAlgorithmException;
     24 import java.security.SecureRandom;
     25 import java.security.spec.AlgorithmParameterSpec;
     26 
     27 /**
     28  * The <i>Service Provider Interface</i> (<b>SPI</b>) definition for the
     29  * {@code KeyAgreement} class.
     30  */
     31 public abstract class KeyAgreementSpi {
     32 
     33     /**
     34      * Creates a new {@code KeyAgreementSpi} instance.
     35      */
     36     public KeyAgreementSpi() {
     37     }
     38 
     39     /**
     40      * Does the next (or the last) phase of the key agreement, using the
     41      * specified key.
     42      *
     43      * @param key
     44      *            the key received from the other party for this phase.
     45      * @param lastPhase
     46      *            set to {@code true} if this is the last phase of this key
     47      *            agreement.
     48      * @return the intermediate key from this phase or null if there is no
     49      *         intermediate key for this phase.
     50      * @throws InvalidKeyException
     51      *             if the specified key cannot be used in this key agreement or
     52      *             this phase,
     53      * @throws IllegalStateException
     54      *             if this instance has not been initialized.
     55      */
     56     protected abstract Key engineDoPhase(Key key, boolean lastPhase)
     57             throws InvalidKeyException, IllegalStateException;
     58 
     59     /**
     60      * Generates the shared secret.
     61      *
     62      * @return the generated shared secret.
     63      * @throws IllegalStateException
     64      *             if this key agreement is not complete.
     65      */
     66     protected abstract byte[] engineGenerateSecret()
     67             throws IllegalStateException;
     68 
     69     /**
     70      * Generates the shared secret and stores it into the buffer {@code
     71      * sharedSecred} at {@code offset}.
     72      *
     73      * @param sharedSecret
     74      *            the buffer to store the shared secret.
     75      * @param offset
     76      *            the offset in the buffer.
     77      * @return the number of bytes stored in the buffer.
     78      * @throws IllegalStateException
     79      *             if this key agreement is not complete.
     80      * @throws ShortBufferException
     81      *             if the specified buffer is too small for the shared secret.
     82      */
     83     protected abstract int engineGenerateSecret(byte[] sharedSecret, int offset)
     84             throws IllegalStateException, ShortBufferException;
     85 
     86     /**
     87      * Generates the shared secret.
     88      *
     89      * @param algorithm
     90      *            the algorithm to for the {@code SecretKey}
     91      * @return the shared secret as a {@code SecretKey} of the specified
     92      *         algorithm.
     93      * @throws IllegalStateException
     94      *             if this key agreement is not complete.
     95      * @throws NoSuchAlgorithmException
     96      *             if the specified algorithm for the secret key does not
     97      *             exists.
     98      * @throws InvalidKeyException
     99      *             if a {@code SecretKey} with the specified algorithm cannot be
    100      *             created using the generated shared secret.
    101      */
    102     protected abstract SecretKey engineGenerateSecret(String algorithm)
    103             throws IllegalStateException, NoSuchAlgorithmException,
    104             InvalidKeyException;
    105 
    106     /**
    107      * Initializes this {@code KeyAgreementSpi} with the specified key and the
    108      * specified randomness source.
    109      *
    110      * @param key
    111      *            the key to initialize this key agreement.
    112      * @param random
    113      *            the source for any randomness needed.
    114      * @throws InvalidKeyException
    115      *             if the specified key cannot be used to initialize this key
    116      *             agreement.
    117      */
    118     protected abstract void engineInit(Key key, SecureRandom random)
    119             throws InvalidKeyException;
    120 
    121     /**
    122      * Initializes this {@code KeyAgreementSpi} with the specified key,
    123      * algorithm parameters and randomness source.
    124      *
    125      * @param key
    126      *            the key to initialize this key agreement.
    127      * @param params
    128      *            the parameters for this key agreement algorithm.
    129      * @param random
    130      *            the source for any randomness needed.
    131      * @throws InvalidKeyException
    132      *             if the specified key cannot be used to initialize this key
    133      *             agreement.
    134      * @throws InvalidAlgorithmParameterException
    135      *             if the specified parameters are invalid for this key
    136      *             agreement algorithm.
    137      */
    138     protected abstract void engineInit(Key key, AlgorithmParameterSpec params,
    139             SecureRandom random) throws InvalidKeyException,
    140             InvalidAlgorithmParameterException;
    141 }