Module rings_core::session

Understanding Abstract Account and Session keypair in Rings Network

Rings network offers a unique mechanism to bolster security and abstract the user’s keypair through a feature known as session keypair. The fundamental concept behind session keypair is signing a generated keypair with a time period {ts, ttl} by user without access its private key in this program. This can be conceptualized as a contract stating, “I delegate to a keypair for the time period {ts, ttl}”.

In our terminology:

• I is Account.
• keypair is SessionSk.
• The time period {ts, ttl} is in SessionSk.session field.

The following is an example to build a SessionSk in Rust and use it to sign a message. It is not necessary to construct a secret_key in Rust. User may manually set account_type, account_entity, and session_sig, instead of provide secret key.

use rings_core::dht::Did;
use rings_core::session::SessionSkBuilder;

// We are generate an ethereum account for example.
// It's convenient because secp256k1 is also used in session_sk.
let user_secret_key = rings_core::ecc::SecretKey::random();
let user_secret_key_did: Did = user_secret_key.address().into();

// The account type is "secp256k1".
// The account entity is its address, also known as Did in rings network.
let account_type = "secp256k1".to_string();
let account_entity = user_secret_key_did.to_string();

let builder = SessionSkBuilder::new(account_entity, account_type);
let unsigned_proof = builder.unsigned_proof();

// Sign the unsigned proof with user's secret key.
let session_sig = user_secret_key.sign(&unsigned_proof).to_vec();
let builder = builder.set_session_sig(session_sig);

let session_sk = builder.build().unwrap();

// Check session_sk is valid. (The verify_self is already called in build().)
assert_eq!(session_sk.account_did(), user_secret_key_did);
assert!(session_sk.session().verify_self().is_ok());

// Sign a message with session_sk.
let msg = "hello world".as_bytes();
let msg_sig = session_sk.sign(msg).unwrap();
let msg_session = session_sk.session();

// Verify the message with session.
assert_eq!(msg_session.account_did(), user_secret_key_did);
assert!(msg_session.verify(msg, msg_sig).is_ok());

SessionSkBuilder, SessionSk is exported to wasm envirement. To build a SessionSk in javascript:

   // prepare auth & send to metamask for sign
   let sessionBuilder = SessionSkBuilder.new(account, 'eip191')
   let unsignedSession = sessionBuilder.unsigned_proof()
   const { signed } = await sendMessage(
     'sign-message',
     {
       auth: unsignedSession,
     },
     'popup'
   )
   const signature = new Uint8Array(hexToBytes(signed))
   sessionBuilder = sessionBuilder.set_session_sig(signature)
   let sessionSk: SessionSk = sessionBuilder.build()

See SessionSk and SessionSkBuilder for details.

Structs

• Session
  Session is used to verify the message. It’s serializable and can be attached to the message payload.
• SessionSk
  SessionSk holds the Session and its session private key. To prove that the message was sent by the Account of Session, we need to attach session and the signature signed by sk to the payload.
• SessionSkBuilder
  SessionSkBuilder is used to build a SessionSk.

Enums

• Account
  We will support as many protocols/algorithms as possible. Currently, it comprises Secp256k1, EIP191, BIP137, and Ed25519. We welcome any issues and PRs for additional implementations.