1 /*

     2  * Copyright (c) 1999, 2007, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package javax.crypto;

    27 

    28 import java.security.Key;

    29 import java.security.AlgorithmParameters;

    30 import java.security.InvalidKeyException;

    31 import java.security.InvalidAlgorithmParameterException;

    32 import java.security.spec.AlgorithmParameterSpec;

    33 

    34 /**

    35  * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)

    36  * for the <code>ExemptionMechanism</code> class.

    37  * All the abstract methods in this class must be implemented by each

    38  * cryptographic service provider who wishes to supply the implementation

    39  * of a particular exemption mechanism.

    40  *

    41  * @author Sharon Liu

    42  *

    43  * @since 1.4

    44  */

    45 

    46 public abstract class ExemptionMechanismSpi {

    47 

    48     /**

    49      * Returns the length in bytes that an output buffer would need to be in

    50      * order to hold the result of the next

    51      * {@link #engineGenExemptionBlob(byte[], int) engineGenExemptionBlob}

    52      * operation, given the input length <code>inputLen</code> (in bytes).

    53      *

    54      * <p>The actual output length of the next

    55      * {@link #engineGenExemptionBlob(byte[], int) engineGenExemptionBlob}

    56      * call may be smaller than the length returned by this method.

    57      *

    58      * @param inputLen the input length (in bytes)

    59      *

    60      * @return the required output buffer size (in bytes)

    61      */

    62     protected abstract int engineGetOutputSize(int inputLen);

    63 

    64     /**

    65      * Initializes this exemption mechanism with a key.

    66      *

    67      * <p>If this exemption mechanism requires any algorithm parameters

    68      * that cannot be derived from the given <code>key</code>, the underlying

    69      * exemption mechanism implementation is supposed to generate the required

    70      * parameters itself (using provider-specific default values); in the case

    71      * that algorithm parameters must be specified by the caller, an

    72      * <code>InvalidKeyException</code> is raised.

    73      *

    74      * @param key the key for this exemption mechanism

    75      *

    76      * @exception InvalidKeyException if the given key is inappropriate for

    77      * this exemption mechanism.

    78      * @exception ExemptionMechanismException if problem(s) encountered in the

    79      * process of initializing.

    80      */

    81     protected abstract void engineInit(Key key)

    82     throws InvalidKeyException, ExemptionMechanismException;

    83 

    84     /**

    85      * Initializes this exemption mechanism with a key and a set of algorithm

    86      * parameters.

    87      *

    88      * <p>If this exemption mechanism requires any algorithm parameters and

    89      * <code>params</code> is null, the underlying exemption mechanism

    90      * implementation is supposed to generate the required parameters

    91      * itself (using provider-specific default values); in the case that

    92      * algorithm parameters must be specified by the caller, an

    93      * <code>InvalidAlgorithmParameterException</code> is raised.

    94      *

    95      * @param key the key for this exemption mechanism

    96      * @param params the algorithm parameters

    97      *

    98      * @exception InvalidKeyException if the given key is inappropriate for

    99      * this exemption mechanism.

   100      * @exception InvalidAlgorithmParameterException if the given algorithm

   101      * parameters are inappropriate for this exemption mechanism.

   102      * @exception ExemptionMechanismException if problem(s) encountered in the

   103      * process of initializing.

   104      */

   105     protected abstract void engineInit(Key key, AlgorithmParameterSpec params)

   106     throws InvalidKeyException, InvalidAlgorithmParameterException,

   107     ExemptionMechanismException;

   108 

   109     /**

   110      * Initializes this exemption mechanism with a key and a set of algorithm

   111      * parameters.

   112      *

   113      * <p>If this exemption mechanism requires any algorithm parameters

   114      * and <code>params</code> is null, the underlying exemption mechanism

   115      * implementation is supposed to generate the required parameters

   116      * itself (using provider-specific default values); in the case that

   117      * algorithm parameters must be specified by the caller, an

   118      * <code>InvalidAlgorithmParameterException</code> is raised.

   119      *

   120      * @param key the key for this exemption mechanism

   121      * @param params the algorithm parameters

   122      *

   123      * @exception InvalidKeyException if the given key is inappropriate for

   124      * this exemption mechanism.

   125      * @exception InvalidAlgorithmParameterException if the given algorithm

   126      * parameters are inappropriate for this exemption mechanism.

   127      * @exception ExemptionMechanismException if problem(s) encountered in the

   128      * process of initializing.

   129      */

   130     protected abstract void engineInit(Key key, AlgorithmParameters params)

   131     throws InvalidKeyException, InvalidAlgorithmParameterException,

   132     ExemptionMechanismException;

   133 

   134     /**

   135      * Generates the exemption mechanism key blob.

   136      *

   137      * @return the new buffer with the result key blob.

   138      *

   139      * @exception ExemptionMechanismException if problem(s) encountered in the

   140      * process of generating.

   141      */

   142     protected abstract byte[] engineGenExemptionBlob()

   143         throws ExemptionMechanismException;

   144 

   145     /**

   146      * Generates the exemption mechanism key blob, and stores the result in

   147      * the <code>output</code> buffer, starting at <code>outputOffset</code>

   148      * inclusive.

   149      *

   150      * <p>If the <code>output</code> buffer is too small to hold the result,

   151      * a <code>ShortBufferException</code> is thrown. In this case, repeat this

   152      * call with a larger output buffer. Use

   153      * {@link #engineGetOutputSize(int) engineGetOutputSize} to determine

   154      * how big the output buffer should be.

   155      *

   156      * @param output the buffer for the result

   157      * @param outputOffset the offset in <code>output</code> where the result

   158      * is stored

   159      *

   160      * @return the number of bytes stored in <code>output</code>

   161      *

   162      * @exception ShortBufferException if the given output buffer is too small

   163      * to hold the result.

   164      * @exception ExemptionMechanismException if problem(s) encountered in the

   165      * process of generating.

   166      */

   167     protected abstract int engineGenExemptionBlob

   168     (byte[] output, int outputOffset)

   169         throws ShortBufferException, ExemptionMechanismException;

   170 }