AntelopeIO Cryptography Kits

AntelopeIO Cryptography Library is a header-only library designed for use in smart contracts. The library includes implementations of ECC primitives and ECDSA verification algorithms, as well as RSA PKCS v1.5 & RSASSA-PSS signature verification algorithms, SHA-384 and Keccak hash algorithms: SHA3-256, SHA3-384, SHA3-512, SHAKE-128, and SHAKE-256.

One of the key features of the library is its optimization of algorithm execution by minimizing heap allocations. The library achieves this by allocating most of the data on the stack and passing it around by pointers and references using std::span. Data structures are designed in a way that utilizes static polymorphism to minimize v-table emissions and runtime overhead. This design choice ensures that the library operates as efficiently as possible, making it well-suited for use in resource-constrained environments.

It should be noted that some parts of the underlying algorithm implementations, such as software modular exponentiation, are taken from other libraries and were not developed by the authors of this library.

Algorithms

ECC

The library implements core elliptic curve primitives, such as curve and point, and supports basic EC arithmetic operations (addition, subtraction, and multiplication) for curves over a prime finite field GF(p). Points can be represented in affine, homogeneous and Jacobi coordinates, providing flexibility for various use cases and applications. Furthermore, the library pre-defines two elliptic curves: secp256k1 and secp256r1.

In addition to the core EC primitives, the library also provides implementation for the ECDSA signature verification algorithm. This implementation follows the NIST FIPS 186-5 standard and has been cross-checked against the SECG SEC1 v2.0 standard and the BSI TR-03111 v2.10 standard.

Elliptic Curve Primitives

The ack/ec.hpp header file defines the following elliptic curve primitives:

ec_point_fp - represents a point in affine coordinates for a curve over GF(p)
ec_point_fp_proj - represents a point in homogeneous coordinates for a curve over GF(p)
ec_point_fp_jacobi - represents a point in Jacobi coordinates for a curve over GF(p)
ec_curve_fp - represents an elliptic curve over GF(p)
ec_mul_add_fast - function for fast multiplication and addition of 2 points with 2 scalars , i.e.: aP + bQ

Pre-defined Elliptic Curves

The ack/ec_curve.hpp header file contains definitions for pre-defined elliptic curves.

ECDSA Signature Verification Functions

The ack/ecdsa.hpp header file defines the following ECDSA signature verification functions:

ecdsa_verify - checks if an ECDSA signature is valid for the provided message.
assert_ecdsa - fails transaction if an ECDSA signature is not valid for the provided message.

RSA PKCS#1 v1.5 & RSASSA-PSS signature verification

The implementation of RSA PKCS#1 v1.5 and RSASSA-PSS signature verification algorithms is following the RFC 8017 https://www.rfc-editor.org/rfc/rfc8017. For RSASSA-PSS only MGF1 mask generation function is supported. The underlying implementation for modular exponentiation math was borrowed from U-Boot C implementation. This implementation uses Montgomery multiplication which speeds up the computation of modular exponentiation. See powm.h.

The ack/rsa.hpp header file defines the RSA PKCS v1.5 signature verification functions for SHA-1, SHA-256 and SHA-512:

verify_rsa_sha1 - checks if RSA signature is valid for the provided SHA-1 hash.
assert_rsa_sha1 - fails transaction if RSA signature is not valid for the provided SHA-1 hash.
verify_rsa_sha256 - checks if RSA signature is valid for the provided SHA-256 hash.
assert_rsa_sha256 - fails transaction if RSA signature is not valid for the provided SHA-256 hash.
verify_rsa_sha384 - checks if RSA signature is valid for the provided SHA-384 hash.
assert_rsa_sha384 - fails transaction if RSA signature is not valid for the provided SHA-384 hash.
verify_rsa_sha512 - checks if RSA signature is valid for the provided SHA-512 hash.
assert_rsa_sha512 - fails transaction if RSA signature is not valid for the provided SHA-512 hash.

the RSASSA-PSS signature verification functions for SHA-1, SHA-256 and SHA-512:

verify_rsa_pss_sha1 - checks if RSASSA-PSS MGF1 signature is valid for the provided SHA-1 hash.
assert_rsa_pss_sha1 - fails transaction if RSASSA-PSS MGF1 signature is not valid for the provided SHA-1 hash.
verify_rsa_pss_sha256 - checks if RSASSA-PSS MGF1 signature is valid for the provided SHA-256 hash.
assert_rsa_pss_sha256 - fails transaction if RSASSA-PSS MGF1 signature is not valid for the provided SHA-256 hash.
verify_rsa_pss_sha384 - checks if RSASSA-PSS MGF1 signature is valid for the provided SHA-384 hash.
assert_rsa_pss_sha384 - fails transaction if RSASSA-PSS MGF1 signature is not valid for the provided SHA-384 hash.
verify_rsa_pss_sha512 - checks if RSASSA-PSS MGF1 signature is valid for the provided SHA-512 hash.
assert_rsa_pss_sha512 - fails transaction if RSASSA-PSS MGF1 signature is not valid for the provided SHA-512 hash.

and modular exponentiation function:

powm - computes modular exponentiation for base and exponent over modulus.
By default eosio::mod_exp intrinsic is used if macro ACK_NO_INTRINSICS=1 is not defined.

Keccak hash algorithms

Library implements 5 Keccak hashing algorithms: SHA3-256, SHA3-384, SHA3-512, SHAKE-128 and SHAKE-256. The underlying base implementation was copied from the original authors. The code is hosted at https://github.com/XKCP/XKCP

The ack/keccak.hpp header file defines those 4 hash algorithms:

sha3_256 - computes SHA3-256 hash
sha3_384 - computes SHA3-384 hash
sha3_512 - computes SHA3-512 hash
shake128_fixed - computes fixed size SHAKE-128 hash
shake128 - computes var-long SHAKE-128 hash
shake256_fixed - computes fixed size SHAKE-256 hash
shake256 - computes var-long SHAKE-256 hash

SHA-2

The ack/sha.hpp header file defines SHA-2 algorithm:

sha384 - computes SHA-384 hash

Algorithm testing

The validity of algorithms was tested with FIPS 180-4, FIPS 186-3 & 186-4 and FIPS 202 test vectors from the US National Institute of Standards and Technology - NIST. In addition, the RSA and ECDSA signature verification algorithms were tested using test vectors from Google's Wycheproof project. Tests can be found in the tests folder. To compile the tests, configure cmake with -DACK_BUILD_TESTS=ON (enabled by default).

Test vectors:
FIPS 180-4: https://csrc.nist.gov/Projects/Cryptographic-Algorithm-Validation-Program/Secure-Hashing#shavs <br>FIPS 186-4: https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/digital-signatures <br>FIPS 202: https://csrc.nist.gov/Projects/Cryptographic-Algorithm-Validation-Program/Secure-Hashing#sha3vsha3vss <br>Project Wycheproof: https://github.com/google/wycheproof

Use in project

To use antelope.ck library in your project, it is recommended to use CMake and configure your project to use the external ack project. E.g.: using FetchContent or copy the library folder to your project and point cmake to it with add_subdirectory. If only pure WASM implementation is desired configure your CMake project with ACK_NO_INTRINSICS=ON option before including ack library. This will exclude specialized intrinsics such as eosio::mod_exp from being used by the library, and instead, a software implementation will be used.

If configured correctly, you should be able to add the ack library to your CMake project using command add_library(<your_project> ack) and include it in your code using the header file: #include <ack/ack.hpp>.

Example:

  #include <ack/ack.hpp>

  // Calculate sum of 2 EC points on secp256k1 curve using affine coordinates
  const auto p1 = ack::ec_curve::secp256k1.make_point( p1_x, p1_y );
  const auto p2 = ack::ec_curve::secp256k1.generate_point( "85d0c2e48955214783ecf50a4f041" );
  const auto p3 = p1 + p2;

  // Triple the p3 point
  const auto p4 = p3 * 3;

  // Multiply the inverse of p4 by integer 0x73c5f6a67456ae48209b5a32d1b8
  const auto p5 = -p4 * "73c5f6a67456ae48209b5a32d1b8";
  
  // Generate 2 EC points on secp256r1 curve using Jacobi coordinates representation
  using secp256r1_t     = decltype( ack::ec_curve::

Ack

Install / Use

README