Guide: How to Use Auth Library
It is a common task to write signature validation procedures in almost every lock script. Here we introduce a new library called
auth to complete this task.
The followings are PR and corresponding RFC:
We have provided a demo example illustrating how to use this library. Here are some basic steps of usage.
Step 1, include necessary header files.
#include "ckb_auth.h" // and some other library, e.g. #include "blake2b.h"
Step 2, Construct a
CkbEntryType and an
CkbEntryType entry; // code_hash can be hard-coded entry.code_hash = 0xAA; entry.code_hash = 0xBB; // ... entry.code_hash = 0xFF; entry.hash_type = 1; // type. possible value: 0(data), 1(type), 2(data1) entry.entry_category = 0; // via exec. possible value: 0(exec), 1(dynamic linking) CkbAuthType auth; auth.algorithm_id = 1; // AuthAlgorithmIdEthereum memcpy(auth.content, pubkey_hash, 20); // copy pubkey hash
The code above is to construct an entry with Ethereum style signature via exec. The
auth library is 1 (type) and code_hash is
0xAABB ....FF. Since
auth library is deployed beforehand, the
code_hash can be hard-coded.
Step 3, validate the signature using
auth variables provided above.
uint8_t msg32; generate_sighash_all(msg32, 32); return ckb_auth(&entry, &auth, lock_bytes_seg.ptr, lock_bytes_seg.size, msg32);
msg32 can be calculated from generate_sighash_all, a common convention in the CKB ecosystem. The 20-byte public key hash is provided by
lock_bytes_seg. That’s all. The returned code of
ckb_auth is the signature validation result.
It is possible to use Rust in the host script. Developers need to implement the function
ckb_auth in Rust by themself.
The cell location is denoted by
entry.hash_type. It is strongly recommended to set
hash_type to 1(type) or 2(data1). Don’t set it to 0(data) which will force the script to run in old ckb-vm before hard-fork. See more from the source code.
entry.entry_category can be 0(exec) or 1(dynamic linking). Here is some information about exec and dynamic linking. It is strongly recommended to use exec. The disadvantage of dynamic linking:
- Not secure enough
When a shared library is called from the host script, any code in the shared library can change any state in the host script.
- Taint memory
When a shared library is loaded into memory, the target memory can’t be re-used again: no writing is allowed anymore and the memory is tainted. The reason is that ckb-vm adopts W^X memory protection for security.
The disadvantage of exec:
- Not convenience
The invoked script can’t call functions in the host script. This is allowed in dynamic linking.
The Benefit of Using Auth Library
auth library is deployed separately, the code size for the host script will be reduced significantly. For example, a normal lock script with secp256k1 signature validation can take around 100K bytes. The
auth_demo which contains some functionality only takes 16K bytes. We can save a lot of money (CKBytes) to deploy scripts.
Normally it’s very difficult to optimize a cryptography algorithm library. With
auth library as a standalone library, developers don’t need to care about how to optimize the library.
Deployment on Testnet
An implementation of auth library above has been deployed to Pudge testnet:
It can be viewed on CKB explorer.
The reproducible build is supported to verify the deploy script. To build the deployed the script above, one can use the following steps:
$ git clone https://github.com/nervosnetwork/ckb-production-scripts $ cd ckb-production-scripts $ git checkout 9785769ded9404985531925d66043320af71adbf $ git submodule update --init --recursive $ make all-via-docker