Header only cryptography library for AntelopeIO smart contracts. Library currently implements RSA PKCS v1.5 & RSASSA-PSS signature verification algorithms and Keccak hash algorithms: SHA3-256, SHA3-512, SHAKE-128 and SHAKE-256.
Library tries to optimize the execution of algorithms by minimizing the heap allocations to bare minimum. This is achieved by allocating most of the data on the stack and pass it around by pointers and references using std::span. Note that some parts of the underlying algorithm implementations are taken from other libraries and was not built by the authors of this library.
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_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_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 defaulteosio::mod_expintrinsic is used if macroACK_NO_INTRINSICS=1is not defined.
Library implements 4 Keccak hashing algorithms: SHA3-256, 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 hashsha3_512- computes SHA3-512 hashshake128_fixed- computes fixed size SHAKE-128 hashshake128- computes var-long SHAKE-128 hashshake256_fixed- computes fixed size SHAKE-256 hashshake256- computes var-long SHAKE-256 hash
The validity of algorithms was tested with some of FIPS 186-3 and FIPS 202 test vectors from the US National Institute of Standards and Technology - NIST. Additionally, validity of RSA signature verification algorithms was tested with testvectors from Google's project Wycheproof.
The tests can be found in tests/rsa_test.hpp and tests/keccak_test.hpp for Keccak algorithms. Tests can be compiled by configuring cmake with -DACK_BUILD_TESTS=ON (on by default).
RSA FIPS 186-3: https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/digital-signatures
Project Wycheproof: https://github.com/google/wycheproof
Keccak SHA-3 FIPS 202: https://csrc.nist.gov/Projects/Cryptographic-Algorithm-Validation-Program/Secure-Hashing#sha3vsha3vss
To use antelope.ck library in your project it's best to use CMake, and configure the project to use the external ack project. e.g.: via FetchContent or copy the library folder to your project and point cmake to it with add_subdirectory. If only WASM implementation is desired configure your CMake project with ACK_NO_INTRINSICS=ON option before including ack library. This will omit specialized intrinsics (e.g. eosio::mod_exp) to be used by the library and software implementation will be used instead.
If configured correctly you should be able to add in your CMake project add_library(<your_project> ack) and include the antelope.ck library in your code: #include <ack/ack.hpp>.
Example:
#include <ack/ack.hpp>
// Verify RSA PKCS#1 v1.5 SHA-512 signature
auto pubkey = rsa_public_key( ras_modulus, rsa_exponent ); // or rsa_public_key_view(...)
auto md = eosio::sha512( msg, msg_len );
assert_rsa_sha512( pubkey, md, rsa_sig,
"failed to verify RSA PKCS#1 v1.5 SHA-512 signature"
);
// or with verify function
if ( !verify_rsa_sha512( pubkey, md, rsa_sig ) ) {
// Do something...
}
// Verify RSASSA-PSS MGF1 SHA-256 signature
auto pubkey = rsa_pss_public_key( ras_modulus, rsa_exponent, pss_salt_len ); // or rsa_pss_public_key_view(...)
auto md = eosio::sha256( msg, msg_len );
assert_rsa_pss_sha256( pubkey, md, rsapss_sig,
"Failed to verify RSASSA-PSS MGF1 SHA-256 signature"
);
// or with verify function
if ( !verify_rsa_pss_sha256( pubkey, md, rsapss_sig ) ) {
// Do something...
}
// Calculate SHA3-256
eosio::checksum256 mdsh3 = sha3_256( byte_data );
// Calculate fixed size SHAKE-128 hash
eosio::checksum160 mdshk128 = shake128_fixed<20>( byte_data );
// calculate var-long SHAKE-256 hash
bytes mdshk256 = shake256( byte_data, /*hash_len=*/16 );The library includes tests and example examples/helloack smart contract. To configure cmake to build example contract, define -DACK_BUILD_EXAMPLES=ON. For building tests configure cmake with -DACK_BUILD_TESTS=ON. Both options are enabled by default.
Example config & build:
1.) mkdir build
2.) cd build
3.) cmake -DACK_BUILD_EXAMPLES=ON -DACK_BUILD_TESTS=OFF ../
4.) make -j 4
The examples/helloack smart contract is uploaded to the Jungle 3 testnet, Jungle 4 and CryptoKylin testnet under the account helloeosiock.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.