Package: oblivious
Python library that serves as an API for common cryptographic primitives used to implement OPRF, OT, and PSI protocols.PurposeThis library provides pure-Python implementations, Python wrappers forlibsodiumandmcl, and additional utility methods for cryptographic primitives that are often used to implementoblivious pseudorandom function (OPRF),oblivious transfer (OT), andprivate set intersection (PSI)protocols.Installation and UsageThis library is available as apackage on PyPI:python-mpipinstallobliviousIt is possible to install the library together with packages that bundle dynamic/shared libraries, such asrbcland/ormclbn256(note that in some environments, the brackets and/or commas may need to be escaped):python-mpipinstalloblivious[rbcl]python-mpipinstalloblivious[mclbn256]python-mpipinstalloblivious[rbcl,mclbn256]The library can be imported in the usual ways:importobliviousfromobliviousimportristrettofromobliviousimportbn254ExamplesThis library supports concise construction of elliptic curve points and scalars. The examples below use theristrettomodule that provides data structures for working with theRistrettogroup:>>>fromoblivious.ristrettoimportpoint,scalar>>>p=point.hash('abc'.encode())# Point derived from a hash of a string.>>>s=scalar()# Random scalar.>>>t=scalar.from_int(0)# Scalar corresponding to the zero residue.Built-in Python operators are overloaded to support point operations (such as addition, subtraction, negation, and equality) and scalar operations (such as multiplication by a scalar and inversion of scalars):>>>q=s*p>>>p==(~s)*qTrue>>>p==((~s)*s)*pTrue>>>p+q==q+pTrue>>>t*p==p-pTrueThepointandscalarclasses have common conversion methods that correspond to those supported bybytesobjects (and in some cases, these classes are themselves derived frombytes):>>>hex='35c141f1c2c43543de9d188805a210abca3cd39a1e986304991ceded42b11709'>>>s=scalar.from_hex(hex)>>>s.hex()'35c141f1c2c43543de9d188805a210abca3cd39a1e986304991ceded42b11709'In addition, Base64 conversion methods are included to support concise encoding and decoding ofpointandscalarobjects:>>>s.to_base64()'NcFB8cLENUPenRiIBaIQq8o805oemGMEmRzt7UKxFwk='>>>s==scalar.from_base64('NcFB8cLENUPenRiIBaIQq8o805oemGMEmRzt7UKxFwk=')TrueFor more information and background about the underlying mathematical structures and primitives found in theristrettomodule, consult materials aboutCurve25519, theRistrettogroup, and the relatedEd25519system.Using Pure Python or a Shared/Dynamic LibraryEach module within this library can export two variants of its primitives and data structures: one corresponding to pure-Python implementations and another corresponding to shared/dynamic library wrappers.For example, theristrettomodule exports two container classes/namespaces:pythonandsodium. These encapsulate pure-Python implementations and shared/dynamic library (i.e., libsodium) wrappers, respectively, of all operations and classes available in theristrettomodule. This makes it possible to explicitly choose whether an operation requires only Python or also requires the presence of a compiled copy of libsodium on the host system.The example below uses pure-Python implementations of the scalar multiplication operation (relying on thege25519library):>>>fromoblivious.ristrettoimportpython>>>p=python.point.hash('abc'.encode())>>>s=python.scalar.hash('123'.encode())>>>(s*p).to_base64()'SrC7vA9sSR5f4E27ALxk14MPotTYR6B33B4ZN+mQXFA='To check whether an instance of the libsodium shared/dynamic library has been loaded successfully, the check below can be performed:>>>fromoblivious.ristrettoimportsodium>>>sodiumisnotNone# Was the dynamic/shared library loaded?TrueIn the example below, the scalar multiplication operation invokes a binding for thecrypto_scalarmult_ristretto255functionexported by libsodium:>>>p=sodium.point.hash('abc'.encode())>>>s=sodium.scalar.hash('123'.encode())>>>(s*p).to_base64()'SrC7vA9sSR5f4E27ALxk14MPotTYR6B33B4ZN+mQXFA='The class methods exported by theristrettomodule directly (e.g., the method__add__within the classpointthat is imported via the statementfrom oblivious.ristretto import point) correspond either (A) to libsodium wrappers if an instance of libsodium is found and loaded or (B) to pure-Python implementations if all attempts to load a working instances of libsodium fail. The ordered list below summarizes what definitions are exported under various conditions and the ordered sequence of attempts to locate and load an instance of libsodium.Under all conditions, the wrapper classpythonis defined and encapsulates a pure-Python variant of every low-level operation and class available in theristrettomodule.As a starting default, all classes exported directly by theristrettomodule correspond to the pure-Python implementations.If a shared/dynamic library instance of libsodium is found on the system and successfully loaded during one of the attempts below, then the wrapper classsodiumis defined:the built-inctypes.util.find_libraryfunction is able to locate'sodium'or'libsodium'and it is loaded successfully;a filelibsodium.soorlibsodium.dllunder the paths specified by thePATHandLD_LIBRARY_PATHenvironment variables is found and loaded successfully; orthe optionalrbclpackage is installed and the compiled subset of libsodium included in that package is loaded successfully.IfsodiumisnotNone, then thesodiumclass encapsulates libsodium wrappers for low-level operations and for every class exported by theristrettomodule. Furthermore,those classes exported directly by the library are redefinedto use the bindings available in the loaded instance of libsodium. Thepythonclass is still exported, as well, and all operations and class methods encapsulated withinpythonremain as-is (i.e., pure-Python implementations).The classes within thebn254module (both those that are pure-Python implementations and those that are wrappers for functions in themcllibrary) are organized in a similar manner. More information is available in the documentation for thebn254module.DevelopmentAll installation and development dependencies are fully specified inpyproject.toml. Theproject.optional-dependenciesobject is used tospecify optional requirementsfor various development tasks. This makes it possible to specify additional options (such asdocs,lint, and so on) when performing installation usingpip:python-mpipinstall.[docs,lint]DocumentationThe documentation can be generated automatically from the source files usingSphinx:python-mpipinstall.[docs]cddocssphinx-apidoc-f-e-E--templatedir=_templates-o_source..&&makehtmlTesting and ConventionsAll unit tests are executed and their coverage is measured when usingpytest(see thepyproject.tomlfile for configuration details, and note that unit tests that requirerbcland/ormclbn256are skipped if the corresponding optional package is not installed):python-mpipinstall.[test]python-mpytestConcise unit tests are implemented with the help offountains; new reference specifications for the tests in a given testing module can be generated by running that testing module directly:pythontest/test_ristretto.pypythontest/test_bn254.pyStyle conventions are enforced usingPylint:python-mpipinstall.[lint]python-mpylintsrc/oblivioustest/test_ristretto.pytest/test_bn254.pyContributionsIn order to contribute to the source code, open an issue or submit a pull request on theGitHub pagefor this library.VersioningBeginning with version 0.1.0, the version number format for this library and the changes to the library associated with version number increments conform withSemantic Versioning 2.0.0.PublishingThis library can be published as apackage on PyPIby a package maintainer. First, install the dependencies required for packaging and publishing:python-mpipinstall.[publish]Ensure that the correct version number appears inpyproject.toml, and that any links in this README document to the Read the Docs documentation of this package (or its dependencies) have appropriate version numbers. Also ensure that the Read the Docs project for this library has anautomation rulethat activates and sets as the default all tagged versions. Create and push a tag for this version (replacing?.?.?with the version number):gittag?.?.?gitpushorigin?.?.?Remove any old build/distribution files. Then, package the source into a distribution archive:rm-rfbuilddistsrc/*.egg-infopython-mbuild--sdist--wheel.Finally, upload the package distribution archive toPyPI:python-mtwineuploaddist/*