View Javadoc
1   /*
2    * Copyright (c) 1998, 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.*;
29  import java.security.spec.*;
30  
31  import java.nio.ByteBuffer;
32  
33  /**
34   * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
35   * for the <code>Mac</code> class.
36   * All the abstract methods in this class must be implemented by each
37   * cryptographic service provider who wishes to supply the implementation
38   * of a particular MAC algorithm.
39   *
40   * <p> Implementations are free to implement the Cloneable interface.
41   *
42   * @author Jan Luehe
43   *
44   * @since 1.4
45   */
46  
47  public abstract class MacSpi {
48  
49      /**
50       * Returns the length of the MAC in bytes.
51       *
52       * @return the MAC length in bytes.
53       */
54      protected abstract int engineGetMacLength();
55  
56      /**
57       * Initializes the MAC with the given (secret) key and algorithm
58       * parameters.
59       *
60       * @param key the (secret) key.
61       * @param params the algorithm parameters.
62       *
63       * @exception InvalidKeyException if the given key is inappropriate for
64       * initializing this MAC.
65       * @exception InvalidAlgorithmParameterException if the given algorithm
66       * parameters are inappropriate for this MAC.
67       */
68      protected abstract void engineInit(Key key,
69                                         AlgorithmParameterSpec params)
70          throws InvalidKeyException, InvalidAlgorithmParameterException ;
71  
72      /**
73       * Processes the given byte.
74       *
75       * @param input the input byte to be processed.
76       */
77      protected abstract void engineUpdate(byte input);
78  
79      /**
80       * Processes the first <code>len</code> bytes in <code>input</code>,
81       * starting at <code>offset</code> inclusive.
82       *
83       * @param input the input buffer.
84       * @param offset the offset in <code>input</code> where the input starts.
85       * @param len the number of bytes to process.
86       */
87      protected abstract void engineUpdate(byte[] input, int offset, int len);
88  
89      /**
90       * Processes <code>input.remaining()</code> bytes in the ByteBuffer
91       * <code>input</code>, starting at <code>input.position()</code>.
92       * Upon return, the buffer's position will be equal to its limit;
93       * its limit will not have changed.
94       *
95       * <p>Subclasses should consider overriding this method if they can
96       * process ByteBuffers more efficiently than byte arrays.
97       *
98       * @param input the ByteBuffer
99       * @since 1.5
100      */
101     protected void engineUpdate(ByteBuffer input) {
102         if (input.hasRemaining() == false) {
103             return;
104         }
105         if (input.hasArray()) {
106             byte[] b = input.array();
107             int ofs = input.arrayOffset();
108             int pos = input.position();
109             int lim = input.limit();
110             engineUpdate(b, ofs + pos, lim - pos);
111             input.position(lim);
112         } else {
113             int len = input.remaining();
114             byte[] b = new byte[CipherSpi.getTempArraySize(len)];
115             while (len > 0) {
116                 int chunk = Math.min(len, b.length);
117                 input.get(b, 0, chunk);
118                 engineUpdate(b, 0, chunk);
119                 len -= chunk;
120             }
121         }
122     }
123 
124     /**
125      * Completes the MAC computation and resets the MAC for further use,
126      * maintaining the secret key that the MAC was initialized with.
127      *
128      * @return the MAC result.
129      */
130     protected abstract byte[] engineDoFinal();
131 
132     /**
133      * Resets the MAC for further use, maintaining the secret key that the
134      * MAC was initialized with.
135      */
136     protected abstract void engineReset();
137 
138     /**
139      * Returns a clone if the implementation is cloneable.
140      *
141      * @return a clone if the implementation is cloneable.
142      *
143      * @exception CloneNotSupportedException if this is called
144      * on an implementation that does not support <code>Cloneable</code>.
145      */
146     public Object clone() throws CloneNotSupportedException {
147         if (this instanceof Cloneable) {
148             return super.clone();
149         } else {
150             throw new CloneNotSupportedException();
151         }
152     }
153 }