1 /* 2 * Copyright (c) 2018, 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 sun.security.util.math; 27 28 import java.math.BigInteger; 29 30 /** 31 * An interface for the field of integers modulo a prime number. An 32 * implementation of this interface can be used to get properties of the 33 * field and to produce field elements of type ImmutableIntegerModuloP from 34 * other objects and representations of field elements. 35 */ 36 37 public interface IntegerFieldModuloP { 38 39 /** 40 * Get the size of the field as a BigInteger. This size is equal to the 41 * prime modulus used to construct the field. 42 * 43 * @return the size of the field. 44 */ 45 BigInteger getSize(); 46 47 /** 48 * Get the additive identity element 0 49 * 50 * @return the additive identity element 51 */ 52 ImmutableIntegerModuloP get0(); 53 54 /** 55 * Get the multiplicative identity element 1 56 * 57 * @return the multiplicative identity element 58 */ 59 ImmutableIntegerModuloP get1(); 60 61 /** 62 * Get the field element equivalent to the supplied BigInteger value. The 63 * supplied value may be negative or larger than the modulus that defines 64 * the field. 65 * 66 * @param v a BigInteger value 67 * @return the field element corresponding to v 68 */ 69 ImmutableIntegerModuloP getElement(BigInteger v); 70 71 /** 72 * Get a "small" value according to this implementation. This value may 73 * be used in optimized forms of some operations to avoid unnecessary 74 * calculations. For example, multiplication is much faster when it is 75 * known that one of the numbers fits within a single limb. 76 * 77 * The definition of "small", and the range of accepted values, is 78 * implementation-specific. 79 * 80 * @param v the small integer value 81 * @throws IllegalArgumentException when the value is not small 82 */ 83 SmallValue getSmallValue(int v); 84 85 /** 86 * Get a field element from a little-endian unsigned integer stored in an 87 * array. The entire array will be used, and the supplied value may be 88 * larger than the modulus that defines the field. The array will not be 89 * modified. 90 * 91 * @param v an array containing a little-endian unsigned integer 92 * @return the field element corresponding to v 93 */ 94 default ImmutableIntegerModuloP getElement(byte[] v) { 95 return getElement(v, 0, v.length, (byte) 0); 96 } 97 98 /** 99 * Get a field element from a little-endian unsigned integer stored at the 100 * specified position in an array. The supplied value may be 101 * larger than the modulus that defines the field. This method also takes 102 * a byte which is interpreted as an additional high-order byte of the 103 * number. The array will not be modified. 104 * 105 * @param v an array containing a little-endian unsigned integer 106 * @param offset the starting position of the integer 107 * @param length the number of bytes to read 108 * @param highByte the high-order byte of the number 109 * @return the field element corresponding to the bytes at the specified 110 * position 111 */ 112 ImmutableIntegerModuloP getElement(byte[] v, int offset, int length, 113 byte highByte); 114 } 115