neptune-triton

neptune-triton is a Futhark implementation of the Poseidon hash function, targeting OpenCL for execution on GPU.

neputne-triton has undergone a security audit performed by Troels Henriksen and been deemed free of critical or major security issues. Incidentally, the linked report contains a detailed analysis of the security guarantees (and their limits) provided by the Futhark programming language itself — many of which flow from its status as a purely functional programming language.

This repository contains two packages: neptune-triton-generator and neptune-triton. The former is a code generator, and the latter is the resulting Rust library.

The generated neptune-triton library is implemented over the Bls12-381 curve. neptune-triton's security levels (partial round numbers) are hard coded to match those provided by neptune, but the actual round constants used must be provided at runtime. When neptune-triton is used by neptune to provide support for batched hashes (arities 2, 8, and 11).

Code generation is performed by genfut. First OpenCL code is generated by invoking the Futhark compiler, then Rust bindings are generated using bindgen. Finally, a Rust library wrapping the generated bindings is created. The resulting Rust library is neptune-triton.

Generating Rust code

In general, users should not need to generate code. This already been performed by the library maintainer, and the resulting generated code is consumed as-is by downstream dependencies. However, for development purposes, or to verify the provenance of the generated Rust code, neptune-triton can be generated by running neptune-triton-generator's default codegen binary.

NOTE: the following will also generate OpenCL code using Futhark, so you will need to have installed the Futhark compiler first. Instructions for installing the correct version of Futhark can be found below.

From repository root:

% cd library
% cargo run

This will generate Futhark artifacts for an OpenCL implemented in library/neptune-triton/lib/, Rust bindings, and a Rust library wrapping OpenCL code in …/neptune-triton/.

You can verify that the existing neptune-triton library indeed represents the result of invoking genfut by observing that regenerating the code does not result in a diff to the repository version. For more detail, see the next section and the procedure described there.

Verify Code Generation

Because Futhark output is deterministic by design, you can easily verify that the OpenCL artifacts are indeed those generated by compiling poseidon.fut with Futhark. Because Futhark does not provide facilities for I/O and only emits purely functional and (with small exceptions for profiling and deubgging) side-effect free programs. From the preceding link:

Calling an entry point, or interacting with Futhark values through the functions listed above, has no system-wide side effects, such as writing to the file system, launching processes, or performing network connections. Defects in the program or Futhark compiler itself can with high probability result only in the consumption of CPU or GPU resources, or a process crash.

To verify that OpenCL artifacts are those generated by Futhark, first check the Futhark version which was used by inspecting the contents of library/neptune-triton/futhark-version.txt. Next, install the reported Futhark version. Note that if a specific Git commit hash is reported, then this commit must be used when building and installing Futhark if you wish to verify the correctness of the generated code.

For example, if futhark-version.txt contains the folowing, then neptune-triton was compiled using commit 965e8eb of Futhark:

Futhark 0.16.2
git: HEAD @ 2cd88bd (Wed Jul 15 13:40:14 2020 +0200)
Copyright (C) DIKU, University of Copenhagen, released under the ISC license.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

If a specific commit is not reported, then neptune-triton was built with a released version of Futhark. Binary release can be downloaded here.

Once Futhark is installed installed, verify the installation by comparing the version information from your Futhark version and that in futhark-version.txt.

% futhark --version

The text should be identical.

Assuming your Futhark version text exactly matches that included in the neptune-triton source you wish to verify, you can regenerate lib/a.c, lib/a.h as follows:

From repository root:

% cd library
% futhark opencl --library -o neptune-triton/lib/a poseidon.fut

If you have recompiled poseidon.fut from a checkout of the project's Git repository, you should observe:

• The timestamps of neptune-triton/lib/a.c, neptune-triton/lib/a.h, and neptune-triton/lib/a.fut have been udpated to reflect this recompilation.
• The content of the files is unchanged, and git status shows that your branch is up do date, if it was before:

On branch master
Your branch is up to date with 'origin/master.

nothing to commit, working tree clean

If this is not the case, first ensure you do have a clean checkout as above, then try again. Compiling with the correct Futhark version should produce new output (observable by timestamp) but no change of content ('nothing to commit, working treen clean').

Futhark Version

Although binary Futhark releases do not print the associated commit in response to the version command, the commit from whose content they are built is well-documented. It can be found in the commit_id file of the unpacked binary release.

The current version of neptune_triton was generated using Futhark v0.16.2, which was itself built from commit 2cd88bd1b64c1e7d3aebcfa41c3473be845277b7. Users who wish to verify the accuracy of the claimed Futhark commit may check that commit out of the Futhark repo and build from source. Regenerating code with the source-built Futhark should still show no changes from the repository version — except that the commit will have been added to futhark-version.txt as in the example above.

Verify Generated Code is Safe

From the second paragraph of 4.8 General Guarantees (also linked above):

Using the #[unsafe] attribute with in-place updates can result in writes to arbitrary memory locations. A malicious program can likely exploit this to obtain arbitrary code execution, just as with any insecure C program. If you must run untrusted code, consider using the --safe command line option to instruct the compiler to disable #[unsafe].

You may inspect (or grep) poseidon.fut to verify that #[unsafe] is not used. To observe this differently, you can compile with the --safe option and witness that the output still remains unchanged (as above).

From repository root:

% cd library
% futhark opencl --safe --library -o neptune-triton/lib/a poseidon.fut

Code Verification in Continuous Integration

The procedure described above is automatically [performed] as part of neptune-triton's continuous integration test suite. If CI is passing, this check has succeeded.

Verify Futhark Packages

poseidon.fut depends on several Futhark packages, the contents of which are committed to the repository. To verify that the provided sources correspond to those specified in library/futhark.pkg, you can manually sync.

From repository root:

% cd library
% futhark pkg sync

Assuming you have a network connection, there should be no output, and no files in the repository should have been modified. The Futhark packages will (still) be installed in library/lib.

License

The Filecoin Project is dual-licensed under Apache 2.0 and MIT terms:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)