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.crypto;
19
20import java.security.InvalidAlgorithmParameterException;
21import java.security.InvalidKeyException;
22import java.security.Key;
23import java.security.NoSuchAlgorithmException;
24import java.security.SecureRandom;
25import java.security.spec.AlgorithmParameterSpec;
26
27/**
28 * The <i>Service Provider Interface</i> (<b>SPI</b>) definition for the
29 * {@code KeyAgreement} class.
30 */
31public 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}