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      */
KeyAgreementSpi()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      */
engineDoPhase(Key key, boolean lastPhase)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      */
engineGenerateSecret()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      */
engineGenerateSecret(byte[] sharedSecret, int offset)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      */
engineGenerateSecret(String algorithm)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      */
engineInit(Key key, SecureRandom random)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      */
engineInit(Key key, AlgorithmParameterSpec params, SecureRandom random)138     protected abstract void engineInit(Key key, AlgorithmParameterSpec params,
139             SecureRandom random) throws InvalidKeyException,
140             InvalidAlgorithmParameterException;
141 }