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.AlgorithmParameters;
21import java.security.InvalidAlgorithmParameterException;
22import java.security.InvalidKeyException;
23import java.security.Key;
24import java.security.spec.AlgorithmParameterSpec;
25
26/**
27 * The <i>Service Provider Interface</i> (<b>SPI</b>) definition for the {@code
28 * ExemptionMechanism} class.
29 */
30public abstract class ExemptionMechanismSpi {
31
32    /**
33     * Creates a new {@code ExemptionMechanismSpi} instance.
34     */
35    public ExemptionMechanismSpi() {
36    }
37
38    /**
39     * Generates the result key blob for this exemption mechanism.
40     *
41     * @return the result key blob for this exemption mechanism.
42     * @throws ExemptionMechanismException
43     *             if error(s) occur during generation.
44     */
45    protected abstract byte[] engineGenExemptionBlob()
46            throws ExemptionMechanismException;
47
48    /**
49     * Generates the result key blob for this exemption mechanism and stores it
50     * into the {@code output} buffer at offset {@code outputOffset}.
51     *
52     * @param output
53     *            the output buffer for the result key blob.
54     * @param outputOffset
55     *            the offset in the output buffer to start.
56     * @return the number of bytes written to the {@code output} buffer.
57     * @throws ShortBufferException
58     *             if the provided buffer is too small for the result key blob.
59     * @throws ExemptionMechanismException
60     *             if error(s) occur during generation.
61     */
62    protected abstract int engineGenExemptionBlob(byte[] output,
63            int outputOffset) throws ShortBufferException,
64            ExemptionMechanismException;
65
66    /**
67     * Returns the size in bytes for the output buffer needed to hold the output
68     * of the next {@link #engineGenExemptionBlob} call, given the specified
69     * {@code inputLen} (in bytes).
70     *
71     * @param inputLen
72     *            the specified input length (in bytes).
73     * @return the size in bytes for the output buffer.
74     */
75    protected abstract int engineGetOutputSize(int inputLen);
76
77    /**
78     * Initializes this {@code ExemptionMechanism} instance with the specified
79     * key.
80     *
81     * @param key
82     *            the key to initialize this instance with.
83     * @throws InvalidKeyException
84     *             if the key cannot be used to initialize this mechanism.
85     * @throws ExemptionMechanismException
86     *             if error(s) occur during initialization.
87     */
88    protected abstract void engineInit(Key key) throws InvalidKeyException,
89            ExemptionMechanismException;
90
91    /**
92     * Initializes this {@code ExemptionMechanism} instance with the specified
93     * key and algorithm parameters.
94     *
95     * @param key
96     *            the key to initialize this instance with.
97     * @param params
98     *            the parameters for this exemption mechanism algorithm.
99     * @throws InvalidKeyException
100     *             if the key cannot be used to initialize this mechanism.
101     * @throws InvalidAlgorithmParameterException
102     *             if the parameters cannot be used to initialize this
103     *             mechanism.
104     * @throws ExemptionMechanismException
105     *             if error(s) occur during initialization.
106     */
107    protected abstract void engineInit(Key key, AlgorithmParameters params)
108            throws InvalidKeyException, InvalidAlgorithmParameterException,
109            ExemptionMechanismException;
110
111    /**
112     * Initializes this {@code ExemptionMechanism} instance with the specified
113     * key and algorithm parameters.
114     *
115     * @param key
116     *            the key to initialize this instance with.
117     * @param params
118     *            the parameters for this exemption mechanism algorithm.
119     * @throws InvalidKeyException
120     *             if the key cannot be used to initialize this mechanism.
121     * @throws InvalidAlgorithmParameterException
122     *             the the parameters cannot be used to initialize this
123     *             mechanism.
124     * @throws ExemptionMechanismException
125     *             if error(s) occur during initialization.
126     */
127    protected abstract void engineInit(Key key, AlgorithmParameterSpec params)
128            throws InvalidKeyException, InvalidAlgorithmParameterException,
129            ExemptionMechanismException;
130}