lightning-bolts/61-credentials-issuance.md

Credential Issuance

This document specifies the Credentials Issuance protocol inside the Staking Credentials framework.

The messages data format, validation algorithms and implementation considerations are laid out.

This draft is version 0.0.1 of the Credential Issuance protocol.

Credentials Issuance

The Requester is sending a proof of scarce assets to the Issuer.

The Issuer is sending back an authentication of the scarce assets to the Requester.

+-------+						  +-------+
|	|						  |	  |
|	|						  |	  |
|	|--(1)--- request_credentials_authentication ---->|	  |
|   A   |						  |   B	  |
|	|						  |	  |
|	|<-(2)--- reply_credentials_authentication -------|	  |
|	|						  |	  |
|	|						  |	  |
+-------+						  +-------+

The request_credentials_authentication message

This message contains a proof of scarce asset for the credentials and a set of unsigned blinded credentials.

1. type: 37560 (request_credentials_authentication)
2. data:
   • [u32: session_id]
   • [point: issuance_pubkey]
   • [assetlen*byte: scarce_assets]
   • [credentiallen*byte: blinded_credentials]

Requirements

The sender:

• MUST set session_id to a pseudo-randomly generated 4-byte value.
• MUST set issuance_pubkey to a public key discovered from a credential_policy issued by the receiver.
• MUST NOT send scarce_assets if they have not been announced by a previous credential_policy issued by this node.
• MUST NOT send blinded_credentials of a format which not been previously announced by a credential_policy issued by this node.
• MUST set blinded_credentials to less than max_onion_size.

The receiver:

• if issuance_pubkey has not been announced or has been rotated: MUST reject this authentication request.
• if scarce_asset is not supported:
  • MUST reject this authentication request.
• if blinded_credentials format is not supported:
  • MUST reject this authentication request.
• if blinded_credentials size is equal or superior to max_onion_size:
  • MUST reject this authentication request.
• if the scarce_asset amount is not covering the quantity of blinded_credentials requested for signature as announced by credential_policy:
  • MUST reject this authentication request.

Rationale

The session id purpose is to enable concurrent authentication sessions where multiple set of credentials can be requested for authentication by the same Requester, and where the order of reception of concurrent request/reply is not guaranteed by the transport mechanism.

The Issuer should be able to perform independent validation of a scarce asset to counter-sign the blinded credentials, and therefore apply a risk management policy.

The Issuer should reject unknown blinded credentials as they cannot provide a valid authentication, if they do not support the underlying cryptosystem.

The onions containing the blinded credentials must be upper bounded in size to be transported over the Lightning onion routing infrastructure.

The Issuer should enforce the policy ratio between the scarce asset value and the quantity of credentials counter-signed, and therefore the Issuer risk management policy is respected.

The reply_credentials_authentication message

This message contains an issuance pubkey and a set of signatures for each credential from request_credentials_authentication.

1. type: 37561 (reply_request_credentials_authentication)
2. data:
   • [u32: session_id]
   • [point: issuance_pubkey]
   • [credentiallen*signature:credentials_signature]

Requirements

The sender:

• MUST set session_id to the received value in the corresponding request_credentials_authentication
• MUST set credentials_signatures to less than max_onion_size.
• MUST sort the credentials_signature in the order of reception of blinded_credentials in the corresponding request_credentials_authentication

The receiver:

• if credentials_signature size is equal or superior to max_onion_size:
  • MUST reject this authentication reply.
• if the issuance_pubkey is not matching the announced key in credentials_policy:
  • MUST reject this authentication reply.
  • MAY add this Issuer identity on a banlist.
• if the signatures are not valid for the blinded_credentials sent in the corresponding request_credentials_authentication:
  • MUST reject this authentication reply.

Rationale

The Requester should reject the reply if the issuance pubkey does not match the credential policy one. The issuance key might have been honestly rotated by the Issuer or the Requester might be under a deanonymization attack.

Implementations and Deployment Considerations

The credential signature request could constitute a CPU DoS vector, therefore the Issuer should either bound its incoming onions traffic or ensure the minimal proof of assets scores for an amount high-enough to deter an adversary.

The scarce assets validation performed should be scale up to ensure there is an economic proportion between the forgery cost and the credentials value. E.g, if on-chain transaction is a supported scarce asset, it should be confirmed with few blocks to avoid a 1-block reorg leading to a "free" dump of authenticated credentials.