--- /dev/null 2018-03-13 15:57:05.100000000 -0400 +++ new/src/java.base/share/classes/sun/security/util/math/IntegerFieldModuloP.java 2018-03-20 10:01:33.134636000 -0400 @@ -0,0 +1,115 @@ +/* + * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package sun.security.util.math; + +import java.math.BigInteger; + +/** + * An interface for the field of integers modulo a prime number. An + * implementation of this interface can be used to get properties of the + * field and to produce field elements of type ImmutableIntegerModuloP from + * other objects and representations of field elements. + */ + +public interface IntegerFieldModuloP { + + /** + * Get the size of the field as a BigInteger. This size is equal to the + * prime modulus used to construct the field. + * + * @return the size of the field. + */ + BigInteger getSize(); + + /** + * Get the additive identity element 0 + * + * @return the additive identity element + */ + ImmutableIntegerModuloP get0(); + + /** + * Get the multiplicative identity element 1 + * + * @return the multiplicative identity element + */ + ImmutableIntegerModuloP get1(); + + /** + * Get the field element equivalent to the supplied BigInteger value. The + * supplied value may be negative or larger than the modulus that defines + * the field. + * + * @param v a BigInteger value + * @return the field element corresponding to v + */ + ImmutableIntegerModuloP getElement(BigInteger v); + + /** + * Get a "small" value according to this implementation. This value may + * be used in optimized forms of some operations to avoid unnecessary + * calculations. For example, multiplication is much faster when it is + * known that one of the numbers fits within a single limb. + * + * The definition of "small", and the range of accepted values, is + * implementation-specific. + * + * @param v the small integer value + * @throws IllegalArgumentException when the value is not small + */ + SmallValue getSmallValue(int v); + + /** + * Get a field element from a little-endian unsigned integer stored in an + * array. The entire array will be used, and the supplied value may be + * larger than the modulus that defines the field. The array will not be + * modified. + * + * @param v an array containing a little-endian unsigned integer + * @return the field element corresponding to v + */ + default ImmutableIntegerModuloP getElement(byte[] v) { + return getElement(v, 0, v.length, (byte) 0); + } + + /** + * Get a field element from a little-endian unsigned integer stored at the + * specified position in an array. The supplied value may be + * larger than the modulus that defines the field. This method also takes + * a byte which is interpreted as an additional high-order byte of the + * number. The array will not be modified. + * + * @param v an array containing a little-endian unsigned integer + * @param offset the starting position of the integer + * @param length the number of bytes to read + * @param highByte the high-order byte of the number + * @return the field element corresponding to the bytes at the specified + * position + */ + ImmutableIntegerModuloP getElement(byte[] v, int offset, int length, + byte highByte); +} +