1 /*
2 * Copyright (c) 1998, 2016, 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.util.*;
29
30 import java.security.*;
31 import java.security.Provider.Service;
32 import java.security.spec.AlgorithmParameterSpec;
33
34 import java.nio.ByteBuffer;
35
36 import sun.security.util.Debug;
37 import sun.security.jca.*;
38 import sun.security.jca.GetInstance.Instance;
39
40 /**
41 * This class provides the functionality of a "Message Authentication Code"
42 * (MAC) algorithm.
43 *
44 * <p> A MAC provides a way to check
45 * the integrity of information transmitted over or stored in an unreliable
46 * medium, based on a secret key. Typically, message
47 * authentication codes are used between two parties that share a secret
48 * key in order to validate information transmitted between these
49 * parties.
50 *
51 * <p> A MAC mechanism that is based on cryptographic hash functions is
52 * referred to as HMAC. HMAC can be used with any cryptographic hash function,
53 * e.g., MD5 or SHA-1, in combination with a secret shared key. HMAC is
54 * specified in RFC 2104.
55 *
56 * <p> Every implementation of the Java platform is required to support
57 * the following standard {@code Mac} algorithms:
58 * <ul>
59 * <li>{@code HmacMD5}</li>
60 * <li>{@code HmacSHA1}</li>
61 * <li>{@code HmacSHA256}</li>
62 * </ul>
63 * These algorithms are described in the
64 * <a href="{@docRoot}/../technotes/guides/security/StandardNames.html#Mac">
65 * Mac section</a> of the
66 * Java Cryptography Architecture Standard Algorithm Name Documentation.
67 * Consult the release documentation for your implementation to see if any
68 * other algorithms are supported.
69 *
70 * @author Jan Luehe
71 *
72 * @since 1.4
73 */
74
75 public class Mac implements Cloneable {
76
77 private static final Debug debug =
78 Debug.getInstance("jca", "Mac");
79
80 private static final Debug pdebug =
81 Debug.getInstance("provider", "Provider");
82 private static final boolean skipDebug =
83 Debug.isOn("engine=") && !Debug.isOn("mac");
84
85 // The provider
86 private Provider provider;
87
88 // The provider implementation (delegate)
89 private MacSpi spi;
90
91 // The name of the MAC algorithm.
92 private final String algorithm;
93
94 // Has this object been initialized?
95 private boolean initialized = false;
96
97 // next service to try in provider selection
98 // null once provider is selected
99 private Service firstService;
100
101 // remaining services to try in provider selection
102 // null once provider is selected
103 private Iterator<Service> serviceIterator;
104
105 private final Object lock;
106
107 /**
108 * Creates a MAC object.
109 *
110 * @param macSpi the delegate
111 * @param provider the provider
112 * @param algorithm the algorithm
113 */
114 protected Mac(MacSpi macSpi, Provider provider, String algorithm) {
115 this.spi = macSpi;
116 this.provider = provider;
117 this.algorithm = algorithm;
118 serviceIterator = null;
119 lock = null;
120 }
121
122 private Mac(Service s, Iterator<Service> t, String algorithm) {
123 firstService = s;
124 serviceIterator = t;
125 this.algorithm = algorithm;
126 lock = new Object();
127 }
128
129 /**
130 * Returns the algorithm name of this {@code Mac} object.
131 *
132 * <p>This is the same name that was specified in one of the
133 * {@code getInstance} calls that created this
134 * {@code Mac} object.
135 *
136 * @return the algorithm name of this {@code Mac} object.
137 */
138 public final String getAlgorithm() {
139 return this.algorithm;
140 }
141
142 /**
143 * Returns a {@code Mac} object that implements the
144 * specified MAC algorithm.
145 *
146 * <p> This method traverses the list of registered security Providers,
147 * starting with the most preferred Provider.
148 * A new Mac object encapsulating the
149 * MacSpi implementation from the first
150 * Provider that supports the specified algorithm is returned.
151 *
152 * <p> Note that the list of registered providers may be retrieved via
153 * the {@link Security#getProviders() Security.getProviders()} method.
154 *
155 * @implNote
156 * The JDK Reference Implementation additionally uses the
157 * {@code jdk.security.provider.preferred}
158 * {@link Security#getProperty(String) Security} property to determine
159 * the preferred provider order for the specified algorithm. This
160 * may be different than the order of providers returned by
161 * {@link Security#getProviders() Security.getProviders()}.
162 *
163 * @param algorithm the standard name of the requested MAC algorithm.
164 * See the Mac section in the <a href=
165 * "{@docRoot}/../technotes/guides/security/StandardNames.html#Mac">
166 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
167 * for information about standard algorithm names.
168 *
169 * @return the new {@code Mac} object
170 *
171 * @throws NoSuchAlgorithmException if no {@code Provider} supports a
172 * {@code MacSpi} implementation for the specified algorithm
173 *
174 * @throws NullPointerException if {@code algorithm} is {@code null}
175 *
176 * @see java.security.Provider
177 */
178 public static final Mac getInstance(String algorithm)
179 throws NoSuchAlgorithmException {
180 Objects.requireNonNull(algorithm, "null algorithm name");
181 List<Service> services = GetInstance.getServices("Mac", algorithm);
182 // make sure there is at least one service from a signed provider
183 Iterator<Service> t = services.iterator();
184 while (t.hasNext()) {
185 Service s = t.next();
186 if (JceSecurity.canUseProvider(s.getProvider()) == false) {
187 continue;
188 }
189 return new Mac(s, t, algorithm);
190 }
191 throw new NoSuchAlgorithmException
192 ("Algorithm " + algorithm + " not available");
193 }
194
195 /**
196 * Returns a {@code Mac} object that implements the
197 * specified MAC algorithm.
198 *
199 * <p> A new Mac object encapsulating the
200 * MacSpi implementation from the specified provider
201 * is returned. The specified provider must be registered
202 * in the security provider list.
203 *
204 * <p> Note that the list of registered providers may be retrieved via
205 * the {@link Security#getProviders() Security.getProviders()} method.
206 *
207 * @param algorithm the standard name of the requested MAC algorithm.
208 * See the Mac section in the <a href=
209 * "{@docRoot}/../technotes/guides/security/StandardNames.html#Mac">
210 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
211 * for information about standard algorithm names.
212 *
213 * @param provider the name of the provider.
214 *
215 * @return the new {@code Mac} object
216 *
217 * @throws IllegalArgumentException if the {@code provider}
218 * is {@code null} or empty
219 *
220 * @throws NoSuchAlgorithmException if a {@code MacSpi}
221 * implementation for the specified algorithm is not
222 * available from the specified provider
223 *
224 * @throws NoSuchProviderException if the specified provider is not
225 * registered in the security provider list
226 *
227 * @throws NullPointerException if {@code algorithm} is {@code null}
228 *
229 * @see java.security.Provider
230 */
231 public static final Mac getInstance(String algorithm, String provider)
232 throws NoSuchAlgorithmException, NoSuchProviderException {
233 Objects.requireNonNull(algorithm, "null algorithm name");
234 Instance instance = JceSecurity.getInstance
235 ("Mac", MacSpi.class, algorithm, provider);
236 return new Mac((MacSpi)instance.impl, instance.provider, algorithm);
237 }
238
239 /**
240 * Returns a {@code Mac} object that implements the
241 * specified MAC algorithm.
242 *
243 * <p> A new Mac object encapsulating the
244 * MacSpi implementation from the specified Provider
245 * object is returned. Note that the specified Provider object
246 * does not have to be registered in the provider list.
247 *
248 * @param algorithm the standard name of the requested MAC algorithm.
249 * See the Mac section in the <a href=
250 * "{@docRoot}/../technotes/guides/security/StandardNames.html#Mac">
251 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
252 * for information about standard algorithm names.
253 *
254 * @param provider the provider.
255 *
256 * @return the new {@code Mac} object
257 *
258 * @throws IllegalArgumentException if the {@code provider} is
259 * {@code null}
260 *
261 * @throws NoSuchAlgorithmException if a {@code MacSpi}
262 * implementation for the specified algorithm is not available
263 * from the specified {@code Provider} object
264 *
265 * @throws NullPointerException if {@code algorithm} is {@code null}
266 *
267 * @see java.security.Provider
268 */
269 public static final Mac getInstance(String algorithm, Provider provider)
270 throws NoSuchAlgorithmException {
271 Objects.requireNonNull(algorithm, "null algorithm name");
272 Instance instance = JceSecurity.getInstance
273 ("Mac", MacSpi.class, algorithm, provider);
274 return new Mac((MacSpi)instance.impl, instance.provider, algorithm);
275 }
276
277 // max number of debug warnings to print from chooseFirstProvider()
278 private static int warnCount = 10;
279
280 /**
281 * Choose the Spi from the first provider available. Used if
282 * delayed provider selection is not possible because init()
283 * is not the first method called.
284 */
285 void chooseFirstProvider() {
286 if ((spi != null) || (serviceIterator == null)) {
287 return;
288 }
289 synchronized (lock) {
290 if (spi != null) {
291 return;
292 }
293 if (debug != null) {
294 int w = --warnCount;
295 if (w >= 0) {
296 debug.println("Mac.init() not first method "
297 + "called, disabling delayed provider selection");
298 if (w == 0) {
299 debug.println("Further warnings of this type will "
300 + "be suppressed");
301 }
302 new Exception("Call trace").printStackTrace();
303 }
304 }
305 Exception lastException = null;
306 while ((firstService != null) || serviceIterator.hasNext()) {
307 Service s;
308 if (firstService != null) {
309 s = firstService;
310 firstService = null;
311 } else {
312 s = serviceIterator.next();
313 }
314 if (JceSecurity.canUseProvider(s.getProvider()) == false) {
315 continue;
316 }
317 try {
318 Object obj = s.newInstance(null);
319 if (obj instanceof MacSpi == false) {
320 continue;
321 }
322 spi = (MacSpi)obj;
323 provider = s.getProvider();
324 // not needed any more
325 firstService = null;
326 serviceIterator = null;
327 return;
328 } catch (NoSuchAlgorithmException e) {
329 lastException = e;
330 }
331 }
332 ProviderException e = new ProviderException
333 ("Could not construct MacSpi instance");
334 if (lastException != null) {
335 e.initCause(lastException);
336 }
337 throw e;
338 }
339 }
340
341 private void chooseProvider(Key key, AlgorithmParameterSpec params)
342 throws InvalidKeyException, InvalidAlgorithmParameterException {
343 synchronized (lock) {
344 if (spi != null) {
345 spi.engineInit(key, params);
346 return;
347 }
348 Exception lastException = null;
349 while ((firstService != null) || serviceIterator.hasNext()) {
350 Service s;
351 if (firstService != null) {
352 s = firstService;
353 firstService = null;
354 } else {
355 s = serviceIterator.next();
356 }
357 // if provider says it does not support this key, ignore it
358 if (s.supportsParameter(key) == false) {
359 continue;
360 }
361 if (JceSecurity.canUseProvider(s.getProvider()) == false) {
362 continue;
363 }
364 try {
365 MacSpi spi = (MacSpi)s.newInstance(null);
366 spi.engineInit(key, params);
367 provider = s.getProvider();
368 this.spi = spi;
369 firstService = null;
370 serviceIterator = null;
371 return;
372 } catch (Exception e) {
373 // NoSuchAlgorithmException from newInstance()
374 // InvalidKeyException from init()
375 // RuntimeException (ProviderException) from init()
376 if (lastException == null) {
377 lastException = e;
378 }
379 }
380 }
381 // no working provider found, fail
382 if (lastException instanceof InvalidKeyException) {
383 throw (InvalidKeyException)lastException;
384 }
385 if (lastException instanceof InvalidAlgorithmParameterException) {
386 throw (InvalidAlgorithmParameterException)lastException;
387 }
388 if (lastException instanceof RuntimeException) {
389 throw (RuntimeException)lastException;
390 }
391 String kName = (key != null) ? key.getClass().getName() : "(null)";
392 throw new InvalidKeyException
393 ("No installed provider supports this key: "
394 + kName, lastException);
395 }
396 }
397
398 /**
399 * Returns the provider of this {@code Mac} object.
400 *
401 * @return the provider of this {@code Mac} object.
402 */
403 public final Provider getProvider() {
404 chooseFirstProvider();
405 return this.provider;
406 }
407
408 /**
409 * Returns the length of the MAC in bytes.
410 *
411 * @return the MAC length in bytes.
412 */
413 public final int getMacLength() {
414 chooseFirstProvider();
415 return spi.engineGetMacLength();
416 }
417
418 /**
419 * Initializes this {@code Mac} object with the given key.
420 *
421 * @param key the key.
422 *
423 * @exception InvalidKeyException if the given key is inappropriate for
424 * initializing this MAC.
425 */
426 public final void init(Key key) throws InvalidKeyException {
427 try {
428 if (spi != null) {
429 spi.engineInit(key, null);
430 } else {
431 chooseProvider(key, null);
432 }
433 } catch (InvalidAlgorithmParameterException e) {
434 throw new InvalidKeyException("init() failed", e);
435 }
436 initialized = true;
437
438 if (!skipDebug && pdebug != null) {
439 pdebug.println("Mac." + algorithm + " algorithm from: " +
440 this.provider.getName());
441 }
442 }
443
444 /**
445 * Initializes this {@code Mac} object with the given key and
446 * algorithm parameters.
447 *
448 * @param key the key.
449 * @param params the algorithm parameters.
450 *
451 * @exception InvalidKeyException if the given key is inappropriate for
452 * initializing this MAC.
453 * @exception InvalidAlgorithmParameterException if the given algorithm
454 * parameters are inappropriate for this MAC.
455 */
456 public final void init(Key key, AlgorithmParameterSpec params)
457 throws InvalidKeyException, InvalidAlgorithmParameterException {
458 if (spi != null) {
459 spi.engineInit(key, params);
460 } else {
461 chooseProvider(key, params);
462 }
463 initialized = true;
464
465 if (!skipDebug && pdebug != null) {
466 pdebug.println("Mac." + algorithm + " algorithm from: " +
467 this.provider.getName());
468 }
469 }
470
471 /**
472 * Processes the given byte.
473 *
474 * @param input the input byte to be processed.
475 *
476 * @exception IllegalStateException if this {@code Mac} has not been
477 * initialized.
478 */
479 public final void update(byte input) throws IllegalStateException {
480 chooseFirstProvider();
481 if (initialized == false) {
482 throw new IllegalStateException("MAC not initialized");
483 }
484 spi.engineUpdate(input);
485 }
486
487 /**
488 * Processes the given array of bytes.
489 *
490 * @param input the array of bytes to be processed.
491 *
492 * @exception IllegalStateException if this {@code Mac} has not been
493 * initialized.
494 */
495 public final void update(byte[] input) throws IllegalStateException {
496 chooseFirstProvider();
497 if (initialized == false) {
498 throw new IllegalStateException("MAC not initialized");
499 }
500 if (input != null) {
501 spi.engineUpdate(input, 0, input.length);
502 }
503 }
504
505 /**
506 * Processes the first {@code len} bytes in {@code input},
507 * starting at {@code offset} inclusive.
508 *
509 * @param input the input buffer.
510 * @param offset the offset in {@code input} where the input starts.
511 * @param len the number of bytes to process.
512 *
513 * @exception IllegalStateException if this {@code Mac} has not been
514 * initialized.
515 */
516 public final void update(byte[] input, int offset, int len)
517 throws IllegalStateException {
518 chooseFirstProvider();
519 if (initialized == false) {
520 throw new IllegalStateException("MAC not initialized");
521 }
522
523 if (input != null) {
524 if ((offset < 0) || (len > (input.length - offset)) || (len < 0))
525 throw new IllegalArgumentException("Bad arguments");
526 spi.engineUpdate(input, offset, len);
527 }
528 }
529
530 /**
531 * Processes {@code input.remaining()} bytes in the ByteBuffer
532 * {@code input}, starting at {@code input.position()}.
533 * Upon return, the buffer's position will be equal to its limit;
534 * its limit will not have changed.
535 *
536 * @param input the ByteBuffer
537 *
538 * @exception IllegalStateException if this {@code Mac} has not been
539 * initialized.
540 * @since 1.5
541 */
542 public final void update(ByteBuffer input) {
543 chooseFirstProvider();
544 if (initialized == false) {
545 throw new IllegalStateException("MAC not initialized");
546 }
547 if (input == null) {
548 throw new IllegalArgumentException("Buffer must not be null");
549 }
550 spi.engineUpdate(input);
551 }
552
553 /**
554 * Finishes the MAC operation.
555 *
556 * <p>A call to this method resets this {@code Mac} object to the
557 * state it was in when previously initialized via a call to
558 * {@code init(Key)} or
559 * {@code init(Key, AlgorithmParameterSpec)}.
560 * That is, the object is reset and available to generate another MAC from
561 * the same key, if desired, via new calls to {@code update} and
562 * {@code doFinal}.
563 * (In order to reuse this {@code Mac} object with a different key,
564 * it must be reinitialized via a call to {@code init(Key)} or
565 * {@code init(Key, AlgorithmParameterSpec)}.
566 *
567 * @return the MAC result.
568 *
569 * @exception IllegalStateException if this {@code Mac} has not been
570 * initialized.
571 */
572 public final byte[] doFinal() throws IllegalStateException {
573 chooseFirstProvider();
574 if (initialized == false) {
575 throw new IllegalStateException("MAC not initialized");
576 }
577 byte[] mac = spi.engineDoFinal();
578 spi.engineReset();
579 return mac;
580 }
581
582 /**
583 * Finishes the MAC operation.
584 *
585 * <p>A call to this method resets this {@code Mac} object to the
586 * state it was in when previously initialized via a call to
587 * {@code init(Key)} or
588 * {@code init(Key, AlgorithmParameterSpec)}.
589 * That is, the object is reset and available to generate another MAC from
590 * the same key, if desired, via new calls to {@code update} and
591 * {@code doFinal}.
592 * (In order to reuse this {@code Mac} object with a different key,
593 * it must be reinitialized via a call to {@code init(Key)} or
594 * {@code init(Key, AlgorithmParameterSpec)}.
595 *
596 * <p>The MAC result is stored in {@code output}, starting at
597 * {@code outOffset} inclusive.
598 *
599 * @param output the buffer where the MAC result is stored
600 * @param outOffset the offset in {@code output} where the MAC is
601 * stored
602 *
603 * @exception ShortBufferException if the given output buffer is too small
604 * to hold the result
605 * @exception IllegalStateException if this {@code Mac} has not been
606 * initialized.
607 */
608 public final void doFinal(byte[] output, int outOffset)
609 throws ShortBufferException, IllegalStateException
610 {
611 chooseFirstProvider();
612 if (initialized == false) {
613 throw new IllegalStateException("MAC not initialized");
614 }
615 int macLen = getMacLength();
616 if (output == null || output.length-outOffset < macLen) {
617 throw new ShortBufferException
618 ("Cannot store MAC in output buffer");
619 }
620 byte[] mac = doFinal();
621 System.arraycopy(mac, 0, output, outOffset, macLen);
622 return;
623 }
624
625 /**
626 * Processes the given array of bytes and finishes the MAC operation.
627 *
628 * <p>A call to this method resets this {@code Mac} object to the
629 * state it was in when previously initialized via a call to
630 * {@code init(Key)} or
631 * {@code init(Key, AlgorithmParameterSpec)}.
632 * That is, the object is reset and available to generate another MAC from
633 * the same key, if desired, via new calls to {@code update} and
634 * {@code doFinal}.
635 * (In order to reuse this {@code Mac} object with a different key,
636 * it must be reinitialized via a call to {@code init(Key)} or
637 * {@code init(Key, AlgorithmParameterSpec)}.
638 *
639 * @param input data in bytes
640 * @return the MAC result.
641 *
642 * @exception IllegalStateException if this {@code Mac} has not been
643 * initialized.
644 */
645 public final byte[] doFinal(byte[] input) throws IllegalStateException
646 {
647 chooseFirstProvider();
648 if (initialized == false) {
649 throw new IllegalStateException("MAC not initialized");
650 }
651 update(input);
652 return doFinal();
653 }
654
655 /**
656 * Resets this {@code Mac} object.
657 *
658 * <p>A call to this method resets this {@code Mac} object to the
659 * state it was in when previously initialized via a call to
660 * {@code init(Key)} or
661 * {@code init(Key, AlgorithmParameterSpec)}.
662 * That is, the object is reset and available to generate another MAC from
663 * the same key, if desired, via new calls to {@code update} and
664 * {@code doFinal}.
665 * (In order to reuse this {@code Mac} object with a different key,
666 * it must be reinitialized via a call to {@code init(Key)} or
667 * {@code init(Key, AlgorithmParameterSpec)}.
668 */
669 public final void reset() {
670 chooseFirstProvider();
671 spi.engineReset();
672 }
673
674 /**
675 * Returns a clone if the provider implementation is cloneable.
676 *
677 * @return a clone if the provider implementation is cloneable.
678 *
679 * @exception CloneNotSupportedException if this is called on a
680 * delegate that does not support {@code Cloneable}.
681 */
682 public final Object clone() throws CloneNotSupportedException {
683 chooseFirstProvider();
684 Mac that = (Mac)super.clone();
685 that.spi = (MacSpi)this.spi.clone();
686 return that;
687 }
688 }