java/security/MessageDigestSpi.java

	MessageDigestSpi.java revision 2362
3544N/A/*
3544N/A * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
3544N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3544N/A *
3544N/A * This code is free software; you can redistribute it and/or modify it
3544N/A * under the terms of the GNU General Public License version 2 only, as
3544N/A * published by the Free Software Foundation.  Oracle designates this
3544N/A * particular file as subject to the "Classpath" exception as provided
3544N/A * by Oracle in the LICENSE file that accompanied this code.
3544N/A *
3544N/A * This code is distributed in the hope that it will be useful, but WITHOUT
3544N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
3544N/A * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
3544N/A * version 2 for more details (a copy is included in the LICENSE file that
3544N/A * accompanied this code).
3544N/A *
3544N/A * You should have received a copy of the GNU General Public License version
3544N/A * 2 along with this work; if not, write to the Free Software Foundation,
3544N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
3544N/A *
3544N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
3544N/A * or visit www.oracle.com if you need additional information or have any
4586N/A * questions.
5185N/A */
5185N/A
5185N/Apackage java.security;
3544N/A
3544N/Aimport java.nio.ByteBuffer;
3544N/A
3952N/Aimport sun.security.jca.JCAUtil;
5185N/A
3544N/A/**
3544N/A * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
3544N/A * for the <code>MessageDigest</code> class, which provides the functionality
3544N/A * of a message digest algorithm, such as MD5 or SHA. Message digests are
3544N/A * secure one-way hash functions that take arbitrary-sized data and output a
3544N/A * fixed-length hash value.
3544N/A *
3544N/A * <p> All the abstract methods in this class must be implemented by a
3544N/A * cryptographic service provider who wishes to supply the implementation
3544N/A * of a particular message digest algorithm.
3544N/A *
3544N/A * <p> Implementations are free to implement the Cloneable interface.
3544N/A *
3544N/A * @author Benjamin Renaud
3544N/A *
3544N/A *
3544N/A * @see MessageDigest
3544N/A */
5185N/A
5185N/Apublic abstract class MessageDigestSpi {
5185N/A
5185N/A    // for re-use in engineUpdate(ByteBuffer input)
5185N/A    private byte[] tempArray;
5185N/A
5185N/A    /**
3580N/A     * Returns the digest length in bytes.
5185N/A     *
5185N/A     * <p>This concrete method has been added to this previously-defined
5185N/A     * abstract class. (For backwards compatibility, it cannot be abstract.)
3544N/A     *
5185N/A     * <p>The default behavior is to return 0.
5185N/A     *
5185N/A     * <p>This method may be overridden by a provider to return the digest
5185N/A     * length.
5185N/A     *
3580N/A     * @return the digest length in bytes.
3544N/A     *
4305N/A     * @since 1.2
3544N/A     */
3544N/A    protected int engineGetDigestLength() {
3544N/A        return 0;
3544N/A    }
3544N/A
3544N/A    /**
4305N/A     * Updates the digest using the specified byte.
3544N/A     *
4305N/A     * @param input the byte to use for the update.
3544N/A     */
3544N/A    protected abstract void engineUpdate(byte input);
5185N/A
3544N/A    /**
3544N/A     * Updates the digest using the specified array of bytes,
5185N/A     * starting at the specified offset.
5185N/A     *
5185N/A     * @param input the array of bytes to use for the update.
5185N/A     *
5185N/A     * @param offset the offset to start from in the array of bytes.
5185N/A     *
5185N/A     * @param len the number of bytes to use, starting at
5185N/A     * <code>offset</code>.
5185N/A     */
5185N/A    protected abstract void engineUpdate(byte[] input, int offset, int len);
5185N/A
5185N/A    /**
5185N/A     * Update the digest using the specified ByteBuffer. The digest is
5185N/A     * updated using the <code>input.remaining()</code> bytes starting
3544N/A     * at <code>input.position()</code>.
3952N/A     * Upon return, the buffer's position will be equal to its limit;
3544N/A     * its limit will not have changed.
5185N/A     *
4305N/A     * @param input the ByteBuffer
4305N/A     * @since 1.5
4305N/A     */
3544N/A    protected void engineUpdate(ByteBuffer input) {
5185N/A        if (input.hasRemaining() == false) {
3544N/A            return;
3544N/A        }
4305N/A        if (input.hasArray()) {
3544N/A            byte[] b = input.array();
3544N/A            int ofs = input.arrayOffset();
3544N/A            int pos = input.position();
3544N/A            int lim = input.limit();
4305N/A            engineUpdate(b, ofs + pos, lim - pos);
5185N/A            input.position(lim);
3544N/A        } else {
3544N/A            int len = input.remaining();
3544N/A            int n = JCAUtil.getTempArraySize(len);
3544N/A            if ((tempArray == null) || (n > tempArray.length)) {
3544N/A                tempArray = new byte[n];
3544N/A            }
4305N/A            while (len > 0) {
5185N/A                int chunk = Math.min(len, tempArray.length);
5185N/A                input.get(tempArray, 0, chunk);
5185N/A                engineUpdate(tempArray, 0, chunk);
5185N/A                len -= chunk;
5185N/A            }
5185N/A        }
5185N/A    }
5185N/A
5185N/A    /**
5185N/A     * Completes the hash computation by performing final
5185N/A     * operations such as padding. Once <code>engineDigest</code> has
5185N/A     * been called, the engine should be reset (see
5185N/A     * {@link #engineReset() engineReset}).
5185N/A     * Resetting is the responsibility of the
5185N/A     * engine implementor.
5185N/A     *
5185N/A     * @return the array of bytes for the resulting hash value.
5185N/A     */
5185N/A    protected abstract byte[] engineDigest();
5185N/A
5185N/A    /**
5185N/A     * Completes the hash computation by performing final
5185N/A     * operations such as padding. Once <code>engineDigest</code> has
5185N/A     * been called, the engine should be reset (see
5185N/A     * {@link #engineReset() engineReset}).
5185N/A     * Resetting is the responsibility of the
5185N/A     * engine implementor.
5185N/A     *
5185N/A     * This method should be abstract, but we leave it concrete for
5185N/A     * binary compatibility.  Knowledgeable providers should override this
5185N/A     * method.
5185N/A     *
5185N/A     * @param buf the output buffer in which to store the digest
5185N/A     *
5185N/A     * @param offset offset to start from in the output buffer
5185N/A     *
5185N/A     * @param len number of bytes within buf allotted for the digest.
5185N/A     * Both this default implementation and the SUN provider do not
5185N/A     * return partial digests.  The presence of this parameter is solely
5185N/A     * for consistency in our API's.  If the value of this parameter is less
5185N/A     * than the actual digest length, the method will throw a DigestException.
5185N/A     * This parameter is ignored if its value is greater than or equal to
5185N/A     * the actual digest length.
5185N/A     *
5185N/A     * @return the length of the digest stored in the output buffer.
5185N/A     *
5185N/A     * @exception DigestException if an error occurs.
5185N/A     *
5185N/A     * @since 1.2
5185N/A     */
5185N/A    protected int engineDigest(byte[] buf, int offset, int len)
5185N/A                                                throws DigestException {
5185N/A
5185N/A        byte[] digest = engineDigest();
5185N/A        if (len < digest.length)
5185N/A                throw new DigestException("partial digests not returned");
5185N/A        if (buf.length - offset < digest.length)
5185N/A                throw new DigestException("insufficient space in the output "
5185N/A                                          + "buffer to store the digest");
5185N/A        System.arraycopy(digest, 0, buf, offset, digest.length);
        return digest.length;
    }

    /**
     * Resets the digest for further use.
     */
    protected abstract void engineReset();

    /**
     * Returns a clone if the implementation is cloneable.
     *
     * @return a clone if the implementation is cloneable.
     *
     * @exception CloneNotSupportedException if this is called on an
     * implementation that does not support <code>Cloneable</code>.
     */
    public Object clone() throws CloneNotSupportedException {
        if (this instanceof Cloneable) {
            return super.clone();
        } else {
            throw new CloneNotSupportedException();
        }
    }
}