Package: galois
Thegaloislibrary is a Python 3 package that extends NumPy arrays to operate over finite fields.Enjoying the library? Give us a :star: onGitHub!The user creates aFieldArraysubclass usingGF = galois.GF(p**m).GFis a subclass ofnp.ndarrayand its constructorx = GF(array_like)mimics the signature ofnp.array(). TheFieldArrayxis operated on like any other NumPy array except
all arithmetic is performed in $\mathrm{GF}(p^m)$, not $\mathbb{R}$.Internally, the finite field arithmetic is implemented by replacingNumPy ufuncs.
The new ufuncs are written in pure Python andjust-in-time compiledwithNumba. The ufuncs can be configured to use either lookup tables (for speed) or explicit calculation (for memory savings).WarningThe algorithms implemented in the NumPy ufuncs are not constant-time, but were instead designed for performance. As such, the library could be vulnerable to aside-channel timing attack. This library is not intended for production security, but instead for research & development, reverse engineering, cryptanalysis, experimentation, and general education.FeaturesSupports allGalois fields$\mathrm{GF}(p^m)$, even arbitrarily-large fields!Fasterthan native NumPy!GF(x) * GF(y)is faster than(x * y) % pfor $\mathrm{GF}(p)$.Seamless integration with NumPy -- normal NumPy functions work onFieldArrays.Linear algebra over finite fields using normalnp.linalgfunctions.Linear transforms over finite fields, such as the FFT withnp.fft.fft()and the NTT withntt().Functions to generateirreducible,primitive, andConwaypolynomials.Univariate polynomials over finite fields withPoly.Forward error correction codes withBCHandReedSolomon.Fibonacci and Galois linear-feedback shift registers over any finite field withFLFSRandGLFSR.Variousnumber theoretic functions.Integer factorizationand accompanying algorithms.Prime number generationandprimality testing.RoadmapElliptic curves over finite fieldsGalois ring arraysGPU supportDocumentationThe documentation forgaloisis located athttps://mhostetter.github.io/galois/latest/.Getting StartedTheGetting Startedguide is intended to assist the user with installing the
library, creating two example arrays, and performing basic array arithmetic. SeeBasic Usagefor more detailed discussions and examples.Install the packageThe latest version ofgaloiscan be installed fromPyPIusingpip.$python3-mpipinstallgaloisImport thegaloispackage in Python.In[1]:importgaloisIn[2]:galois.__version__Out[2]:'0.3.8'Create aFieldArraysubclassNext, create aFieldArraysubclass
for the specific finite field you'd like to work in. This is created using thegalois.GF()class factory. In this example, we are
working in $\mathrm{GF}(3^5)$.In[3]:GF=galois.GF(3**5)In[4]:print(GF.properties)GaloisField:name:GF(3^5)characteristic:3degree:5order:243irreducible_poly:x^5+2x+1is_primitive_poly:Trueprimitive_element:xTheFieldArraysubclassGFis a subclass ofnp.ndarraythat performs all arithmetic in the Galois field $\mathrm{GF}(3^5)$, not in $\mathbb{R}$.In[5]:issubclass(GF,galois.FieldArray)Out[5]:TrueIn[6]:issubclass(GF,np.ndarray)Out[6]:TrueSeeArray Classesfor more details.Create twoFieldArrayinstancesNext, create a newFieldArrayxby passing anArrayLikeobject toGF's constructor.In[7]:x=GF([236,87,38,112]);xOut[7]:GF([236,87,38,112],order=3^5)The arrayxis an instance ofFieldArrayand also
an instance ofnp.ndarray.In[8]:isinstance(x,galois.FieldArray)Out[8]:TrueIn[9]:isinstance(x,np.ndarray)Out[9]:TrueCreate a secondFieldArrayyby converting an existing
NumPy array (without copying it) by invoking.view(). When finished working in the finite field, view it back as a NumPy array
with.view(np.ndarray).# y represents an array created elsewhere in the codeIn[10]:y=np.array([109,17,108,224]);yOut[10]:array([109,17,108,224])In[11]:y=y.view(GF);yOut[11]:GF([109,17,108,224],order=3^5)SeeArray Creationfor more details.Change the element representationThe representation of finite field elements can be set to either the integer ("int"), polynomial ("poly"),
or power ("power") representation. The default representation is the integer representation since integers are natural when
working with integer NumPy arrays.Set the element representation by passing thereprkeyword argument togalois.GF()or by calling therepr()classmethod. Choose whichever element representation is most convenient.# The default is the integer representationIn[12]:xOut[12]:GF([236,87,38,112],order=3^5)In[13]:GF.repr("poly");xOut[13]:GF([2α^4+2α^3+2α^2+2,α^4+2α,α^3+α^2+2,α^4+α^3+α+1],order=3^5)In[14]:GF.repr("power");xOut[14]:GF([α^204,α^16,α^230,α^34],order=3^5)# Reset to the integer representationIn[15]:GF.repr("int");SeeElement Representationfor more details.Perform array arithmeticOnce you have two Galois field arrays, nearly any arithmetic operation can be performed using normal NumPy arithmetic.
The traditionalNumPy broadcasting rulesapply.Standard element-wise array arithmetic -- addition, subtraction, multiplication, and division -- are easily preformed.In[16]:x+yOut[16]:GF([18,95,146,0],order=3^5)In[17]:x-yOut[17]:GF([127,100,173,224],order=3^5)In[18]:x*yOut[18]:GF([21,241,179,82],order=3^5)In[19]:x/yOut[19]:GF([67,47,192,2],order=3^5)More complicated arithmetic, like square root and logarithm base $\alpha$, are also supported.In[20]:np.sqrt(x)Out[20]:GF([51,135,40,16],order=3^5)In[21]:np.log(x)Out[21]:array([204,16,230,34])SeeArray Arithmeticfor more details.AcknowledgementsThegaloislibrary is an extension of, and completely dependent on,NumPy. It also heavily
relies onNumbaand theLLVM just-in-time compilerfor optimizing performance
of the finite field arithmetic.Frank Luebeck's compilationof Conway polynomials andWolfram's compilationof primitive polynomials are used
for efficient polynomial lookup, when possible.The Cunningham Book's tablesof prime factorizations, $b^n \pm 1$
for $b \in {2, 3, 5, 6, 7, 10, 11, 12}$, are used to generate factorization lookup tables. These lookup tables speed-up the
creation of large finite fields by avoiding the need to factor large integers.Sageis used extensively for generating test vectors for finite field arithmetic and polynomial arithmetic.SymPyis used to generate some test vectors.Octaveis used to generate test vectors for forward error correction codes.This library would not be possible without all of the other libraries mentioned. Thank you to all their developers!CitationIf this library was useful to you in your research, please cite us. Following theGitHub citation standards, here is the recommended citation.BibTeX@software{Hostetter_Galois_2020,title={{Galois: A performant NumPy extension for Galois fields}},author={Hostetter, Matt},month={11},year={2020},url={https://github.com/mhostetter/galois},}APAHostetter, M. (2020). Galois: A performant NumPy extension for Galois fields [Computer software]. https://github.com/mhostetter/galois