From 8869c69759a7e83c7f1974745303df8a799fa7ce Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 8 May 2024 21:05:36 +0700 Subject: [PATCH] docs(CIPs): Move CIPs and submit them for review (#473) * chore: wip * Update 0005-flutter-app.md * Update 0005-flutter-app.md * Update 0005-flutter-app.md * Update 0005-flutter-app.md * Update 0005-flutter-app.md * Update 0005-flutter-app.md * Update 0005-flutter-app.md * Update 0005-flutter-app.md * Update 0005-flutter-app.md * Update 0005-flutter-app.md * Update 0005-flutter-app.md * docs(docs): Use latest docs builders and fix concepts page * docs(cips): Start drafting the CIPS for milestone 2 * docs(cips): More text for RBAC metadata draft * docs(cips): WIP updates to draft cip for role registration * docs(cips): define draft specification for a ULID cbor tag * docs(cips): Further WIP edits to RBAC * docs(cips): fix ulid spec binary encoding reference * docs(cips): Add a tag to the epoch time. * docs(cips): Add CBOR tag cip for ED25519-BIP32 Keys, Derivation paths and Signatures * docs(cips): Properly define the field tags to use where known, and clean up Stake Address specification. * docs(cips): Fix nonce so its reliable without needing blockchain data * docs(cips): updates * docs(docs): Add CDDL definition for POC x509 envelope metadata * fix(vscode): update vscode extension recommendations * docs(cips): rbac x509 envelope fix * docs(cips): wip updates to high level docs * docs(cips): Add overview of cardano transaction processign and data * docs(cips): update cardano block to be complete for clarity * docs(cips): fix layout engine * docs(cips): wip cddl for envelope metadata * docs(cips): Add cddl specs and diagrams for x509 rbac registration work * docs(cips): Add full transaction/metadata relationship diagram * refactor(cips): reorganize documentation ready for drafting descriptive prose about the formats and uses * docs(cips): add cip draft for catalyst roles using the x509-rbac standard * docs(cips): Add c509 cddl with restrictions and enhancements for plutus usage * docs(cips): Metadata envelope specification draft complete * Update docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> * Update docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> * Update docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> * Update docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> * Update docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> * Update docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> * Update docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> * Update docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> * docs(cips): Fix time and algorithm comments * build(frontend): Relax flutter/dart version requirements to last minor release * docs(cips): wip * fix(cips): rename draft x509 envelope CIP so its easier to identify * docs(cips): WIP updates to x509 roles * fix(cips): rename RBAC definition CIP draft so its easier to identify * docs(cips): x509 certificate registration format fully defined * docs(cips): Document the restricted plutus subset. * docs(cips): Add document detailing how CIP-30 is used to sign the transaction * fix(cips): remove trailing spaces * fix(cips): Fix line lengths * fix(cips): Correct spelling * fix(cips): spelling * fix(frontend): revert changes to flutter/dart versions * fix(frontend): more flutter/dart version corrections * fix(frontend): Revert flutter files to same as main branch * fix(frontend): revert more flutter .yml files to those in main * fix(cips): Fix links between files * docs(cips): Add catalyst specific role registration documentation * docs(spelling): fix spelling * docs(cips): Point to the new home of the RBAC CIPs. * fix(spelling): Fix corrupted spelling in project dictionary --------- Co-authored-by: minikin Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com> --- .config/dictionaries/project.dic | 2 +- .../cip-509C.md | 59 +-- .../cip-catalyst-roles.md | 353 +------------ .../x509-envelope-metadata/cip-509A.md | 231 +------- .../x509-rbac-signing-with-cip30/cip-x509D.md | 133 +---- .../cip-509B.md | 494 +----------------- 6 files changed, 21 insertions(+), 1251 deletions(-) diff --git a/.config/dictionaries/project.dic b/.config/dictionaries/project.dic index a1d66ad7135..1812da14af8 100644 --- a/.config/dictionaries/project.dic +++ b/.config/dictionaries/project.dic @@ -188,4 +188,4 @@ xcodeproj xctest xctestrun xcworkspace -yoroi +yoroi \ No newline at end of file diff --git a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/cip-509C.md b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/cip-509C.md index 698044be7c8..0ccab0a4ef5 100644 --- a/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/cip-509C.md +++ b/docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/cip-509C.md @@ -1,57 +1,6 @@ ---- -CIP: /? -Title: Restricted format for C509 compatibility with Plutus -Category: MetaData -Status: Proposed -Authors: - - Steven Johnson -Implementors: [] -Discussions: - - https://github.com/cardano-foundation/cips/pulls/? -Created: 2023-10-24 -License: CC-BY-4.0 ---- +# Restricted format for C509 compatibility with Plutus -## Abstract +## PERMANENTLY MOVED -Plutus can access metadatums that encode C509 certificates. -This specification documents the restricted feature set of those certificates. - -## Motivation: why is this CIP necessary? - -In order to keep complexity low, this specification details a set of restriction -on-top of a standard C509 certificate definition. -These restrictions help plutus support the important features of -x509 certificates in smart contracts on-chain. - -They also help reduce the amount of data stored on-chain. - -## Specification - -See [c509-cert-plutus-restricted.cddl](./c509-cert-plutus-restricted.cddl). -This is the formal specification which describes the requirements of on-chain x509 certificates. -ust include a CDDL schema in it's specification.--> - -## Rationale: how does this CIP achieve its goals? - -By clearly defining the feature set that plutus scripts can accept from C509 certificates it is easier for -script writers and certificate creators to produce interoperable certificates. - -## Path to Active - -This draft CIP requires extensive collaboration with multiple parties in order to arrive at a -correct and viable specification. - -It has been kept deliberately terse in order for that process to be as open and collaborative as possible. - -### Acceptance Criteria - -* General community consensus on the minimum standard needs to be agreed. - -### Implementation Plan - -## Copyright - -This CIP is licensed under [CC-BY-4.0] - -Code samples and reference material are licensed under [Apache 2.0] +* [New Home](https://github.com/input-output-hk/catalyst-CIPs/blob/x509-plutus-restricted-c509/CIP-XXXX/README.md) +* [CIP PR](https://github.com/cardano-foundation/CIPs/pull/812) diff --git a/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md b/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md index e953692dbc4..d1e0448592d 100644 --- a/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md +++ b/docs/src/catalyst-standards/draft-cips/project-catalyst-x509-role-defintions/cip-catalyst-roles.md @@ -1,351 +1,6 @@ ---- -CIP: /? -Title: Project Catalyst Role Registrations -Category: MetaData -Status: Proposed -Authors: - - Steven Johnson -Implementors: [] -Discussions: - - https://github.com/cardano-foundation/cips/pulls/? -Created: 2023-10-24 -License: CC-BY-4.0 ---- +# Project Catalyst Role Registrations -## Abstract +## PERMANENTLY MOVED -Project Catalyst requires better role registration and is utilizing x509 certificate RBAC for this purpose. -This document defines how that standard is applied to Project Catalyst role registrations. - -## Motivation: why is this CIP necessary? - -As the project catalyst dApp grew, -it became clear there was a need for an extensible and flexible Role based Access control system to support its needs. - -This CIP builds upon the x509 RBAC Specification CIPs and defines how they are used for Project Catalyst Roles. - -## Specification - -Project Catalyst defines 2 dApp ID's. - -| dApp ID | Role Group | -| --- | --- | -| `ca7a1457-ef9f-4c7f-9c74-7f8c4a4cfa6c` | Project Catalyst User Role Registrations | -| `ca7ad312-a19b-4412-ad53-2a36fb14e2e5` | Project Catalyst Admin Role Registrations | - -User Roles are self registered by individual users. -Admin roles are managed. - -We define these two RBAC Role Groups to allow them to be managed in an easier way. - -### Project Catalyst User Role Registrations - -The following user roles are defined: - -| Role ID | Role Description | -| -- | -- | -| 0 | Voter | -| 1 | Delegated Representative | -| 2 | Voter Delegation | -| 3 | Proposer | - -Further User roles will be added to this specification as those roles are defined. - -#### Voter Role - -Voters are the most basic role within Project Catalyst. -They can Vote and Comment on Proposals. -They MAY earn rewards for their participation, and MAY earn reputation. - -X509 registrations require a Role 0 registration. -Role 0 is the Basic Voter Role. - -The Role 0 registration certificate MUST be linked to AT LEAST ONE stake address on-chain. -It can be linked to multiple stake addresses, but they must all be witnessed in the transaction to be valid. - -The Voters Role 0 signing key from their certificate is also used by the voter to: - -1. Establish their identity to backend systems (Decentralized Authorization). -2. Sign votes in a Catalyst event. -3. Witness Comments made on proposals. - -The Certificate MUST be self signed. -Currently CA's are not supported for Catalyst User Roles. - -The Project Catalyst dApp generates a Public/Private key pair and creates the user Role 0 certificate, -associates it with their on-chain stake address, and signs the certificate. - -This allows each user to have full custody of their own Catalyst voting identity. -They may also change their Signing Key at any time by rolling their Role 0 certificate as described -in the x509 metadata specifications. - -In the initial implementation the Signing key used in the certificate MUST BE an ED25519 certificate. -No other kind of signature algorithm is allowed. - -#### Delegated Representative (dRep) - -A dRep is a registration that is made, which allows for voters to give their voting power to the dRep who -then votes on their behalf. - -dReps must register a simple signing key, it must be referenced to the first signing key in the simple key array. -dReps do not use certificates to manage their signing key. - -dReps may register a new Payment address, if they do not register a new payment address, the payment address -registered to Role 0 will be used for the dRep rewards. - -dReps MAY attach extra information to their registration: - -| Data Key | Information | -| -- | -- | -| 10 | Name | -| 11 | [ + URL Link to Profile ] | -| 12 | ADA Handle | - -#### Voter Delegation - -A Voter Delegation role assigns a voters voting power to a registered dRep. - -The dRep, will use the voters voting power, pooled with other delegations to vote on behalf of the voter. - -Delegation does not define a signing key, not an encryption key. - -Delegation roles ONLY contain a dApp specific data as defined here: - -| Data Key | Information | -| -- | -- | -| 10 | `[ + Delegation Record] / undefined` | -| 11 | Optional Time to live | -| 12 | Optional fund id | -| 13 | Optional purpose | - -##### Delegation Record - -Key 10 defines an array of Delegation records. - -The formal structure of the Delegation Record is defined as: - -```cddl -delegation_registration = [ + delegation_record ] / undefined - -delegation_record = ( - simple_delegation / - weighted_delegation -) - -simple_delegation = drep_key_hash -weighted_delegation = [ drep_key_hash, weight ] - -drep_key_hash = bytes .size 16 -weight = uint -``` - -* `delegation_registration` is either an array of delegation_records OR `undefined`. - `undefined` means that any previous delegation that was active is terminated. - The voter retains their voting power in this case. -* An individual `delegation_record` can be either a `simple_delegation` or a `weighted_delegation`. -* `simple_delegation` is just the hash of the drep voting key to be delegated to. - A weight of `1` is assumed if there are multiple delegations. -* `weighted_delegation` allows the weight to be defined, it is a positive integer. - Weight apportions a voters voting power between all dReps delegated to. - -Voting Power weighted apportionment is a function of the wights. -The total of the weights is added to give `total_weight`. -Each dRep get `voting power * (weight / total_weight)` worth of voting power from the delegation. -In the event there is any residual voting power, it is assigned to the final dRep in the list. - -##### Optional Time To Live - -This is a unit, and is the time expressed as seconds since 1970 UTC. -When this time is reached, the delegation is automatically cancelled, if it was not previously de-registered. - -Time To Live can be used to remove a delegation at any time. -However, if the Delegation has been used to vote before the Time to Live expired, the voter may not ALSO Vote. - -This allows the TTL to act as a safety. -For example, if the TTL is set to 10 days into a 15 day voting period, -then the dRep MUST vote within the first 10 days, after which they lose the delegation. -Having lost the delegation, the Voter may vote at any time in the final 5 days. -If however, the dRep voted in the first 10 days, the Voter may not vote in the last 5. -Even though they delegation expired. -That is because it is only valid to vote once on a proposal during a fund and the voter -already voted (via the valid, at the time, delegation). - -##### Optional Fund ID - -This is simply the ID of the fund. -It is a `uint`. -This defines the Fund for which the delegation is active. - -##### Optional Delegation Purpose - -This field can ONLY be defined if the `Fund ID` field is defined. - -The Purpose defines what the delegation is for. -For example, in Catalyst it is defined as the number of the challenge or category in the fund the delegation is used for. -The delegation in this case is only valid for this Purpose on the specified Fund. - -##### Multiple Delegations - -It is possible for a Voter to have multiple simultaneous delegations. -In this case, the most specific delegation that has not expired is the one that is used. - -For example, IF there is a delegation for Fund 15, Challenge 3, and no other delegations. -Then the voter can vote on every other challenge, except for Challenge 3 in that Fund. -Challenge 3 can be voted on by the dReps that were delegated. - -In another example, if a voter has a general delegation, but also a specific delegation for Fund 15, Challenge 3. -Then the general delegations can vote on behalf of the voter for any fund/challenge -EXCEPT for Fund 15, Challenge 3. -For Fund 15, Challenge 3 ONLY the specific delegations for the Challenge/Fund may vote for the voter. - -##### Validity - -The Fund may impose rules on the construction of a delegation. -The delegation will not be valid if it does not conform to those rules. -For example, the Fund can define that ALL delegations Must expire 10 days within a 15 day voting window. -In which case, for a delegation to be valid, the TTL MUST be set appropriately. - -This allows for great flexibility in how delegations work, but also allows fund specific rules to be created. -Without limiting the general usefulness of the registration format itself. - -#### Proposer Registration - -Registering as a proposer allows the registered entity to: - -1. Create and Edit their own proposals both anonymously and publicly. -2. Jointly Edit proposals with other registered proposers. -3. Respond to comments on public proposals. -4. Sign a proposal either singly or jointly for submission and consideration in a Catalyst Fund. -5. Be paid to a certified payment address if the proposal wins. - -Proposers MUST define a Proposers signature public key. -It must be a simple public key of the type ED25519, and it must reference the second signing key in the simple key array. - -The proposer registration may OPTIONALLY define an encryption key. -Currently only X25519 encryption is supported, and this must be a reference to the second or third key in the simple key array. -IF the key is an ED25519 key, the X25519 public key is derived from it. -Otherwise if the key is an X25519 key, it is used as specified. - -This allows the Propers signing key to also be used as a public encryption key. - -A Proposer may ONLY work on private encrypted proposals if they have a published public encryption key. -The proposer may change their public encryption key at any time by posting an update to their registration. - -Proposers MAY attach extra information to their registration: - -| Data Key | Information | -| -- | -- | -| 10 | Name | -| 11 | [ + URL Link to Profile ] | -| 12 | ADA Handle | - -If the proposers registration does not define a payment key, -the Role 0 payment key is used for the proposers payment key. - -Because the purpose of a Proposer is to earn funding from the Catalyst Fund, -A proposal registration is INVALID if it does not have an associated payment address. - -#### dApp purpose specific keys - -Project Catalyst defines the following data which can be declared globally in any registration. - -| Data Key | Information | -| -- | -- | -| 200 | Name | -| 201 | [ + URL Link to Profile ] | -| 202 | ADA Handle | - -If any of these data items is defined in a registration, -they will be used if the matching key is absent in either a dRep or Proposer registration. - -This allows for an individual that is both a dRep and a Proposer to share the same extended data about their registration. - -### Project Catalyst Admin Role Registrations - -| Role ID | Role Description | -| -- | -- | -| 0 | General Admin Role | - -#### General Admin Role - -Project Catalyst will register on-chain a registration for it's CA. -The CA will be associated with a known stake address. -The assignment of the CA to the known catalyst stake address establishes trust in the -Admin CA and ensures that other fraudulent CA's can not be registered. - -The Admin CA can then issue other certificates for admins. -It may also revoke them. -It can also create a 2nd layer of CA's to create Admin users. - -An example of the relationship between CA's and certificates is: - -![Certificate Chain](./images/certificate-chain.svg) - -The CA defined in this way, or the intermediate CA does not have any Admin privileges. - -Only End Entity Certificates have Admin privileges. -Initially all registered project catalyst admins have all admin privileges in the system. - -However, if required, an extension within the Role 0 certificate. -That is issued to theAdmin by the CA or intermediate CA. -Can define restrictions to the Admin role. -It is the responsibility of the CA to ensure the -permissions encoded in the admins Role 0 certificate are correct. - -The CA or Intermediate CA may revoke an admins certificate at any time. -They do so by publishing the Admins certificate hash in a revocation list signed by the CA. - -If an Admin user has their certificate revoked, they lose all Admin functionality. - -This system allows a trusted and verifiable CA to register administrators and prevents fraudulent admins being registered. - -Each Admin and CA must have a Stake Address associated with their registration certificate. - -Admins are Role 0, so their signing key is defined by their certificate. -They may also register an Encryption key by referencing a key at index 0 of the simple key list. - -The encryption key must be an X25519 public key if registered. - -Admin users must NOT register a payment key, and they have no other data associated with their role registration. - -### Special Roles not defined by x509 certificates - -There is one special role within project catalyst which is not defined by the -Role registration. - -An Unregistered Voter. - -#### Unregistered Voter - -Project Catalyst will have the concept of an UNREGISTERED voter. -A Voter may sign a vote with either their registered Voting Key, OR -They may sign it with their stake address. - -As long as the stake address is valid, then anyone with a wallet can vote. -Even if they have not registered as a catalyst voter. - -Alternatively a Voter who has a faulty registration or has lost their private voting -key may still vote in a fund with their Stake address signing their vote. -This acts as a fail safe in these cases. - -Regardless of which key is used to sign the vote, a voter may ONLY vote once per fund per proposal. -All possible voting signature keys are considered equivalent. - -Stake addresses may only be used for voting and can not be used for other functions assigned to Role 0. - -## Rationale: how does this CIP achieve its goals? - -## Path to Active - -### Acceptance Criteria - -### Implementation Plan - -## Copyright - -This CIP is licensed under [CC-BY-4.0] - -Code samples and reference material are licensed under [Apache 2.0] - -[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode -[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html +* [New Home](https://github.com/input-output-hk/catalyst-CIPs/blob/x509-catalyst-role-definitions/CIP-XXXX/README.md) +* [CIP PR](https://github.com/cardano-foundation/CIPs/pull/814) diff --git a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md index 4094c25ec8b..85ed9de4575 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md +++ b/docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/cip-509A.md @@ -1,229 +1,6 @@ ---- -CIP: /? -Title: x509 Replayability Protection Envelope -Category: MetaData -Status: Proposed -Authors: - - Steven Johnson -Implementors: [] -Discussions: - - https://github.com/cardano-foundation/cips/pulls/? -Created: 2023-10-24 -License: CC-BY-4.0 ---- +# x509 Replayability Protection Envelope -## Abstract +## PERMANENTLY MOVED -x509 Certificate metadata and related metadata within an x509 Registration/Update transaction must be -protected against replayability. - -## Motivation: why is this CIP necessary? - -x509 certificate registration necessarily references data within the transaction body that it is attached to. -Preventing replayability of the verbatim Auxiliary data attached to a transaction prevents the relationships -between those references being altered and closes a potential attack vector where an unrelated registration update -is attached to a different transaction. - -Rather than define an explicit issue with potential replayability of Metadata, we simply seek to prevent it -to close off a whole category of potential attacks. - -## Specification - -The [x509 Metadata Envelope CDDL] defines the technical specification of the Metadata Envelope. -The following description provides more information and context to that formal specification. -Where this description and that specification are in disagreement, the specification prevails. - -The metadata envelope has the following basic structure: - -![x509 Secure Metadata Envelope structure](images/metadata-envelope-structure.svg) - -The purpose of this data is to lock a particular set of Auxiliary data verifiably to its original transaction. -It can not be permitted to take teh Auxiliary data to another transaction and just attach it without it being detectable. - -Currently, this detection can NOT be done on-chain by ledger rules, and this metadata is designed to be processed -by off-chain processors of this information. - -### Detailed description of the fields in the metadata and their purpose - -The metadata is encoded as a CBOR map, and follows the [specification for the encoding of all Cardano metadata]. - -#### Key: 0 = Purpose - -Purpose is defined by the consuming dApp. -It allows dApps to have their own privately named and managed namespace for certificates. -The x509 specifications presented here do not define how certificates must be created. -Nor the purpose they are used for, that is within control of the dApp. -These specifications define a universal framework to implement such systems from. - -For each set of "Purposes" that a dapp has for role based access or off-chain identity to on-chain identity management -the dApp will define a V4 UUID. -There is no central repository of these, though a dApp may publish the ID it uses and what its used for. -The reason UUID V4 is chosen here is if properly chosen, they can be self assigned without fear of collision -with another dApp and eliminate the need for a central registry to manage them. - -A dApp can define multiple purposes to segment RBAC functions by class. -For example, Project Catalyst defines the following two Purposes: - -| UUID-V4 | Purpose | -| --- | --- | -| ca7a1457-ef9f-4c7f-9c74-7f8c4a4cfa6c | Project Catalyst User Role Registrations | -| ca7ad312-a19b-4412-ad53-2a36fb14e2e5 | Project Catalyst Admin Role Registrations | - -The reason in this case for having two purposes for the same application is to allow the rules -governing registration to be easier managed between the groups. -It also allows Admins to have a distinct identity when they are just users of the system. -dApps are free top have as many "purposes" defined as suits their goals. - -#### Key 1: txn-inputs-hash - -This is a hash of the transaction inputs field from the transaction this auxiliary data was original attached to. -This hash anchors the auxiliary data to a particular transaction, if the auxiliary data is moved to a new transaction -it is impossible for the txn-inputs-hash to remain the same, as UTXO's can only be spent once. - -This is a key to preventing replayability of the metadata, but is not enough by itself as it needs to be able to be -made immutable, such that any change to this field can be detected. - -#### Key 2: previous_transaction_id - -This is a 32 byte hash of the previous transaction in a chain of registration updates made by the same user. -The only registration which may not have it for a single user is their first. -Once their first registration is made, they may only update it. -Any subsequent update for that user that is not properly chained to the previous transaction will be ignored as invalid. - -The user is identified by their Role 0 key, which must be defined in the first registration. -The Role 0 key also includes a reference to an on-chain key, such as a stake key hash. -This is important to establish the verifiability of the link between the registrations and the transaction itself. - -#### Keys 10, 11 or 12 - x509 Chunked Data - -Except for the first registration, the chunked data is optional. -For example, if this metadata is simply being used to lock auxiliary data to a transaction there does not need to be -any actual role or certificate updates. - -The data required to register certificates or roles could be large. -The [specification for the encoding of all Cardano metadata] also introduces difficulties in encoding x509 certificates. - -The contents of the x509 RBAC Registration data stored in this key is documented separately. -Its exact contents are not important for this specification except to note, that it will always define at least: - -* 1 Role 0 signing key MUST always be defined. - * And that key MUST be associated with a on-chain key such as a stake address hash. -* The RBAC Data will have references to the transaction it is attached to, - and it can not be fully interpreted independent of the transaction. - -To save space and overcome the metadata encoding limitations, x509 RBAC data is preferable encoded as described: - -1. The x509 Role Registration Data is prepared and encoded with [dCBOR]. - This is the raw encoded registration data. -2. The raw encoded registration data is then compressed with [Brotli]. - This is the Brotli compressed registration data. -3. The raw encoded registration data is then compressed with [ZSTD]. - This is the ZSTD compressed registration data. -4. Which ever data is smallest, Raw, Brotli compressed or ZStd compressed is then cut into 64 byte chunks. - All chunks must contain 64 bytes except for the last which can contain the residual. -5. These chunks are then encoded in an array of 64 byte long byte strings. - The appropriate key is used to identify the compression used. - * 10 = Raw, no compression - * 11 = Brotli Compressed - * 12 = ZSTD Compressed - -Due to the potential size of x509 certificates compression is mandatory where it will reduce the space of the encoded data. -dApps can, if they choose, only support either Brotli or ZSTD and not trial compress the data. -However they must never store data compressed if the compressed size is larger than the raw size. -This can happen if the data is small and not very compressible, due to overhead in the codec data stream. - -The specification reserves keys 13-17 for future compression schemes. -Even though there are multiple keys defined, ONLY 1 may be used at a time. -There is only a single list of x509 chunks and the key is used to define the compression used only. - -ie, it is invalid to use key 10 and 12 at the same time in the same envelope. - -#### Key 99 - Validation Signature - -Key 99 contains the signature which can be verified with the signing key recorded against role 0. - -It is a signature over the [entire auxiliary data] that will be attached to the transaction. -This includes not only the transactions metadata, but all attached scripts. - -As the auxiliary data key 99 is part of the auxiliary data, we end up with a catch-22. -We can't sign the data because we do not know what data will be stored in the signature field. -To mitigate this problem, the size of the signature will be known in advanced, based on the signature algorithm. -When the unsigned auxiliary data is prepared, the appropriate storage for the signature is pre-allocated -in the metadata, and is set to 0x00's. - -The signature is calculated over this unsigned data, and the pre-allocated signature storage is replaced with the signature itself. - -This ensures that there is no alteration to the auxiliary data in form or structure. -Validating the signature then is as simple as: - -1. removing the signature data from the auxiliary data; -2. setting the storage for the signature back to 0, and; -3. validating the signature on the reconstructed unsigned auxiliary data. - -### Validating the Auxiliary Data is attached to the correct transaction - -The Transaction will have 3 pieces of information that must be validated to ensure the attached metadata -is carried with the correct transaction. - -1. The UTXO Inputs when hashed MUST == [Key 1 - Transaction Inputs Hash](#key-1-txn-inputs-hash) -2. The [auxiliary data hash] must equal the hash of the actual auxiliary data. - 1. This is likely always true as it would be validated by the ledger rules. -3. The [vkeywitness] set MUST include a signature over the transaction with the key associated with Role 0. - 1. Note: Role 0 may have multiple associated keys, in which case there must be a witness for all of them. - 2. A missing witness means it is not possible to validate the auxiliary data truly was built for this transaction. - -## Rationale: how does this CIP achieve its goals? - -This specification creates a signed set of interlocking data between a transaction and its auxiliary data. -The interlock is constructed to avoid any catch-22 in setting up a transaction and to minimize complexity. - -By signing off-chain data with an off-chain key, we simplify the process of signing auxiliary data, -this allows us to sign all the data in a way suitable to the needs of the method and not limited to any on-chain restrictions. - -The off-chain key is explicitly associated with an on-chain key, such that signing with the on-chain key over -the registration transaction provides proof that they two keys are related and can be used interchangeably, - -Once constructed in the way documented, the auxiliary data may not be posted in a different transaction without it being detected. - -It is not currently possible to detect this on-chain, as plutus does not have the necessary functionality to allow it -to inspect auxiliary data, except under very limited circumstances. -However, the purpose of this envelope is to ensure that off-chain construction of off -chain certificates and dApp role registration is secure. - -This specification meets that criteria. - -## Path to Active - -### Acceptance Criteria - - -### Implementation Plan - - -## References - -* [Cardano Metadata CDDL Specification][specification for the encoding of all Cardano metadata] -* [Cardano Auxiliary Data CDDL Specification][entire auxiliary data] -* [Cardano Transaction Auxiliary Data Hash Specification][auxiliary data hash] -* [Cardano vKeyWitness Specification][vkeywitness] -* [Deterministic CBOR Encoding][dCBOR] -* [Brotli Data Compression][Brotli] -* [ZSTD Data Compression][ZSTD] - -## Copyright - -This CIP is licensed under [CC-BY-4.0] - -Code samples and reference material are licensed under [Apache 2.0] - - -[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode -[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html -[x509 Metadata Envelope CDDL]: ./x509-envelope.cddl -[specification for the encoding of all Cardano metadata]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L511-L531 -[dCBOR]: https://datatracker.ietf.org/doc/draft-mcnally-deterministic-cbor/ -[Brotli]: https://github.com/google/brotli -[ZSTD]: https://github.com/facebook/zstd -[entire auxiliary data]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L521-L531 -[auxiliary data hash]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L60 -[vkeywitness]: https://github.com/IntersectMBO/cardano-ledger/blob/ab8d57cf43be912a336e872b68d1a2526c93dc6a/eras/conway/impl/cddl-files/conway.cddl#L436 +* [New Home](https://github.com/input-output-hk/catalyst-CIPs/blob/x509-envelope-metadata/CIP-XXXX/README.md) +* [CIP PR](https://github.com/cardano-foundation/CIPs/pull/810) diff --git a/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md b/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md index 561d042f0cc..f58671cf007 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md +++ b/docs/src/catalyst-standards/draft-cips/x509-rbac-signing-with-cip30/cip-x509D.md @@ -1,131 +1,6 @@ ---- -CIP: /? -Title: Preparing and Signing x509 Metadata -Category: MetaData -Status: Proposed -Authors: - - Steven Johnson -Implementors: [] -Discussions: - - https://github.com/cardano-foundation/cips/pulls/? -Created: 2023-10-24 -License: CC-BY-4.0 ---- +# Preparing and Signing x509 Metadata with CIP-30 - -# Role Based Access Control Registration +## PERMANENTLY MOVED -## Abstract - -This document defines how a dApp will use the wallet connect interfaces of CIP-30 to produce and sign -x509 registration transactions. - -## Motivation: why is this CIP necessary? - -The x509 certificate metadata CIPs are complex, and it is required to clearly document how they -can be produced using standard tooling. - -The primary motivation is that the registration can be produced with existing interfaces. - -Wallets MAY OPTIONALLY detect this registration format and display it in a more meaningful way to users. -But that is not required. - -The aim is to have broad interoperability with ALL wallets that already implement CIP-30. - -## Specification - -### Components of an individual transaction - -![Cardano Transaction Anatomy](./images/cardano-transaction.svg) - -### Creation and Signing procedure - -![Creation/Signing procedure](../x509-envelope-metadata/images/metadata-envelope-process.svg) - -### Wallet interaction - -CIP 30 defines two main functions. - -1. signData -2. signTransaction - -We deliberately do NOT use signData. -The reason is signData has limitations, primarily it can ONLY sign data with a single key. - -it is also incapable of creating data that can not be replayed across transactions, which is a requirement. - -Accordingly, the entire transaction is produced using `signTransaction`. - -Following the procedure described above, the prepared transaction and complete metadata -(which has been pre-signed with the role 0 keys of the user) are sent to the wallet to be signed. - -The Transaction MUST include where appropriate extra keys in `required signers` in the transaction to properly -link the off-chain role keys with on-chain keys. - -The wallet DOES NOT need to know that the metadata has this requirement, it simply sees the keys it needs to witness -the transaction with, and prompts the user to sign. - -#### Enhanced UX - -The Role registration metadata is general in form. - -A Wallet MAY elect to detect that it is signing a role registration and -present the data in a form which is easier for the user to reason through. - -It may also be aware of key supported dApps and provide even further information. -It can also perform both universal and dApp specific validity checks against the registration to ensure -it is properly structured by the dApp. - -However, the Wallet should simply WARN the user if it detects a problem, and not prevent the user from -signing the transaction. - -Once the wallet has signed the transaction, the dApp will have a fully signed role registration transaction and metadata. -It will be impossible for the dApp or anyone else to separate the metadata from the transaction and retain its validity. -It is impossible to replay the metadata on a new transaction and it retain validity. - -With the complete transaction properly signed, it can then be posted on-chain. - -### Posting the transaction - -Once the transaction has been properly constructed and signed, anyone with a copy of it can post it on-chain. - -it is recommended that dApps post the transaction to their own backend logic, which handles posting the data on-chain -vs posting the data on-chain through the wallet. - -The reason for this, is this affords the dApp backend the opportunity to -validate the registration data in its entirety before posting it on-chain. - -It is preferable to inform a user their registration is invalid or has problems -BEFORE they spend the ADA required to post the transaction, -and the only authoritive way this can be achieved is through the dApp. - -having validated the registration would be valid if posted on-chain, it is then posted by the dapp on-chain. - -Once the dApp sees the registration appear in the ledger, -it is now confirmed that not only was the registration valid, but that the transaction itself was valid, -properly spent valid UTXOs, etc. - -The dApp may cache registration data it received from users, -but it should never act on it until it has been seen validly posted on-chain. - -## Rationale: how does this CIP achieve its goals? - -This CIP defines wallet interactions and how CIP-30 is used to create and -post transactions that conform to the x509 metadata specification. - -## Path to Active - -### Acceptance Criteria - -### Implementation Plan - -## References - -## Copyright - -This CIP is licensed under [CC-BY-4.0] - -Code samples and reference material are licensed under [Apache 2.0] - -[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode -[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html +* [New Home](https://github.com/input-output-hk/catalyst-CIPs/blob/x509-rbac-signing-with-cip30/CIP-XXXX/README.md) +* [CIP PR](https://github.com/cardano-foundation/CIPs/pull/813) diff --git a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md index 6d02b8142d7..fbc705a4dcd 100644 --- a/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md +++ b/docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/cip-509B.md @@ -1,492 +1,6 @@ ---- -CIP: /? -Title: Role based Access Control Registration -Category: MetaData -Status: Proposed -Authors: - - Steven Johnson -Implementors: [] -Discussions: - - https://github.com/cardano-foundation/cips/pulls/? -Created: 2023-10-24 -License: CC-BY-4.0 / Apache 2.0 ---- +# x509 Role based Access Control Registration -## Abstract +## PERMANENTLY MOVED -dApps such as Project Catalyst need robust, secure and extensible means for users to register under various roles -and for the dApp to be able to validate actions against those roles with its users. - -While these Role based registrations are required for future functionality of Project Catalyst, they are also -intended to be generally useful to any dApp with User roles. - -## Motivation: why is this CIP necessary? - -CIP-36 contains a limited form of role registration limited to voters and dreps. - -However, Project Catalyst has a large (and growing) number of roles identified in the system, all of -which can benefit from on-chain registration. - -A non-exhaustive example list of the roles Project Catalyst needs to identify securely are: - -1. Proposers. -2. Co-Proposers. -3. Proposal Reviewers. -4. Voters. -5. Representative voters. -6. Tally committee members. -7. Administrators. -8. Audit committee members. - -Individual dApps may have their own unique list of roles they wish users to register for. -Roles are such that an individual user may hold multiple roles, one of the purposes of this -CIP is to allow the user to unambiguously assert they are acting in the capacity of a selected role. - -CIP-36 offers a "purpose" field, but offers no way to manage it, and offers no way to allow it to be used unambiguously. -The "purpose" field therefore is insufficient for the needs of identifying roles. - -CIP-36 also does not allow the voting key to be validated. -This makes it impossible to determine if the registration voting key is usable, and owned by the registering user, or has -been duplicated from another registration on-chain or is just a random number. - -It also offers no way to identify the difference between a voter registering for themselves, and a voter registering to be a dRep. - -These are some of the key reasons, CIP-36 is insufficient for future Project Catalyst needs. - -Registering for various roles and having role specific keys is generally useful for dApps, so while this CIP is -motivated to solve problems with Project Catalyst, it is also intended to be generally applicable to other dApps. - -There are a number of interactions with a user in a dApp like Catalyst which require authentication. -However forcing all authentication through a wallet has several primary disadvantages. - -* Wallets only are guaranteed to provide `signData` if they implement CIP30, and that only allows a single signature. -* There are multiple keys controlled by a wallet and its useful to ensure that all keys reflected are valid. -* Its equally important to ensure that registrations prove custody/ownership of certain on-chain identities, - such as registered stake address or drep registration. -* Metadata in a transaction is inaccessible to plutus scripts. -* Wallets could present raw data to be signed to the user, and that makes the UX poor because the user would have difficulty - knowing what they are signing. -* Wallets could be extended to recognize certain metadata and provide better UX but that shifts dApp UX to every wallet. -* Putting chain keys in metadata can be redundant if those keys are already in the transaction. -* Some authentication needs to change with regularity, such as authentication tokens to a backend service, - and this would require potentially excessive wallet interactions. - This would lower UX quality and could impact participation. - -The proposal here is to register dApp specific keys and identity, but strongly associate it with on-chain identity, -such as Stake Public Keys, Payment Keys and Drep Keys, such that off chain interactions can be fully authenticated, -and only on-chain interaction requires interaction with a Wallet. - -## Specification - -Role registration is encapsulated inside a [x509 Envelope](../x509-envelope-metadata/cip-509A.md) metadata record. -This enables the data to both be compressed, saving on-chain space and also to have more expressivity and -less restrictions vs raw on-chain metadata. - -This specification covers the general use of the x509 registration format and is not specific to any dApp. -dApps can utilize any subset of the features defined herein, and dApps define their own roles. - -In order to maintain a robust set of role registration capabilities Role registration involves: - -1. Creation of a root certificate for a user or set of users and associating it with an on-chain source of trust. -2. Obtaining for each user of a dapp, or a set of users, their root certificate. -3. Deriving role specific keys from the root certificate. -4. Optionally registering for those roles on-chain. -5. Signing and/or encrypting data with the root certificate or a derived key, or a certificate issued by a previously - registered root certificate. - -Effectively we map the blockchain as PKI (Public Key Infrastructure) and define the methods a dapp can use to exploit this PKI. - -### Mapping the PKI to Cardano - -A PKI consists of: - -* A certificate authority (CA) that stores, issues and signs the digital certificates; - * Each dApp *MAY* control its own CA, the user trusts the dApp as CA implicitly (or explicitly) by using the dApp. - * It is also permissible for root certificates to be self signed, effectively each user becomes their own CA. - * However all Certificates are associated with blockchain addresses, typically one or more Stake Public Key. - * A certificate could be associated with multiple Stake Addresses, Payment Addresses or DRep Public Keys, as required. - * A dApp may require that a well known public CA is used. - The chain of trust can extend off chain to centralized CAs. - * DAOs or other organizations can also act as a CA for their members. - * This is intentionally left open so that the requirements of the dApp can be flexibly accommodated. -* A registration authority (RA) which verifies the identity of entities requesting their digital certificates - to be stored at the CA; - * Each dApp is responsible for identifying certificates relevant for its use that are stored on-chain and are their own RA. - * The dApp may choose to not do any identifying. - * The dApp can rely on decentralized identity to verify identity in a trustless way. -* A central directory—i.e., a secure location in which keys are stored and indexed; - * This is the blockchain itself. - * As mentioned above, the chain of trust can extend off-chain to traditional Web2 CA's. -* A certificate management system managing things like the access to stored certificates or the delivery of the - certificates to be issued; - * This is managed by each dApp according to its requirements. -* A certificate policy stating the PKI's requirements concerning its procedures. - Its purpose is to allow outsiders to analyze the PKI's trustworthiness. - * This is also defined and managed by each dApp according to its requirements. - -### The role x.509 plays in this scheme - -We leverage the x.509 PKI primitives. -We intentionally take advantage of the significant existing code bases and infrastructure which already exists. - -#### Certificate formats - -x.509 certificates can be encoded in: - -* Binary DER format -* [CBOR Encoded X.509 Certificates][C509]. - -### Metadata Structure - -The formal definition of the x509 certificate payload is [here](./x509-roles.cddl). - -The format can be visualized as: - -![x509 Registration Format](./images/x509-roles.svg) - -### Metadata Encoding - -* The metadata will be encoded with [CBOR]. -* The [CBOR] metadata will be encoded strictly according to [CBOR - Core Deterministic Encoding Requirements]. -* There **MUST NOT** be any duplicate keys in a map. -* UTF-8 strings **MUST** be valid UTF-8. -* Tags **MUST NOT** be used unless specified in the specification. -* Any Tags defined in the specification are **REQUIRED**, and they **MUST** be present in the encoded data. - * Fields which should be tagged, but which are not tagged will be considered invalid. - -These validity checks apply only to the encoding and decoding of the metadata itself. -There are other validity requirements based on the role registration data itself. -Each dApp may have further validity requirements beyond those stated herein. - -### High level overview of Role Registration metadata - -At a high level, Role registration will collect the following data: - -1. An [optional list](#x509-certificate-lists) of DER format x509 certificates. -2. An [optional list](#x509-certificate-lists) of [CBOR Encoded X.509 Certificates][C509] -3. An [optional list](#simple-public-keys) list of tagged simple public keys. -4. An [optional certificate revocation](#certificate-revocation-list) set. -5. An [optional set](#role-definitions) of role registration data. -6. An [optional list](#dapp-specific-registration-data) of purpose specific data. - -### x509 Certificate Lists - -There can be two lists of certificates. -They are functionally identical and differ only in the format of the certificate itself. - -DER Format certificates are used when the only certificate source is a legacy off-chain certificate. -These are not preferred because they can be transcoded into c509 format, and are usually larger than their c509 equivalent. -However, it is recognized that legacy support for x509 DER format certificates is important, and they are supported. - -Preferably all certificates will either be uniquely encoded as c509 encoded certificates, -or will be transcoded from a DER format x509 certificate into it's c509 equivalent. - -The certificate lists are unsorted, and are simply a method of publishing a new certificate on-chain. - -The only feature about the certificate that impacts the role registration is that certificates -may embed references to on-chain keys. - -In the case where a certificate does embed a reference to an on-chain key, -the key SHOULD be present in the witness set of the transaction. -Individual dApps can strengthen this requirement to MUST. - -By including the Signature in the transaction, we are able to make a verifiable link between the -off-chain certificate and the on-chain identity. -This can not be forged. - -#### Plutus access to x509 certificates - -Plutus is currently incapable of reading any metadata attached to a transaction. -This specification allows for C509 encoded certificates to be present in the datum output of the transaction itself. -Any C509 certificates present in the metadatum of the transaction are considered to be part of the C509 -certificate list for the purposes of this specification. - -A C509 certificate in a metadatum that is to be included in the registration MUST be included in the C509 certificate list -as a reference. - -The reference defines the metadatum the C509 certificate can be found in the transaction, -and the offset in that metadatum where the certificate is located. -The Certificates MUST be in the same transaction as the Metadatum, it is not possible to refer to a certificate -embedded in metadatum in another transaction. - -Certificates in metadatum that are not linked in this way are ignored for the purpose of this specification. - -Transaction outputs at key 1 of the transaction can contain any number of arrays of certificates. -This is only limited by the transaction itself. - -### Simple Public Keys - -Rather than require full certificates, dApps can use simple public keys. -The simple public key list is for that purpose. -The list acts as an array, the index in the array is the offset of the key. - -CBOR allows for array elements to be skipped or marked as undefined. - -The actual set of simple public keys registered is the union set of all simple public keys registered on-chain. -This allows simple public keys to be securely rotated or removed from a registration. - -CBOR allows elements of an array to be skipped or marked as absent using [CBOR Undefined/Absent Tags]. - -An element in the array marked "undefined" (`0xf7`) is used to indicate that no change to that array position is to be made. -An element in the array marked "absent" (`0xd8 0x1f 0xf7`) is used to indicate that any key at this position is revoked. - -Using these two element we can define the array as the union of all arrays and keys can be freely altered or removed. - -Examples: - -```txt -[Key 1, Key 2, Key 3] + -[undefined, absent, undefined] -``` - -would result in: - -```txt -[Key 1, undefined, Key 3] -``` - -If this was followed with: - -```txt -[undefined, undefined, undefined, undefined, Key 5] -``` - -we would then have the resultant set of keys: - -```txt -[Key 1, undefined, Key 3, undefined, Key 5] -``` - -The latest key set is what is currently active for the role. - -These keys are usable to sign data for a role, but are not a replacement for certificates, and some roles may not allow their use. - -### Certificate Revocation List - -The certificate revocation list is used by an `issuer` of a certificate to revoke any certificate they have issued. -The certificate is considered revoked as soon as it appears in the revocation list. -If a self signed certificate is to be rolled, a registration will revoke the previously self signed certificate and -simultaneously register a new certificate. - -This ensures that the roles registered always have a valid certificate and allows registration to be dynamically updated. - -The revocation list is simply a list of blake2b-128 hashes of the certificate/s to be revoked. -Note, as stated above the only party that can revoke a certificate is the issuer, so the metadata must be posted by the issuer using -their own role 0 key. - -Any certificate that is revoked which was used to issue other certificates results in ALL certificates issued by the -revoked certificate also being revoked. - -### Role definitions - -Roles are defined in a list. -A user can register for any available role, and they can enrol in more than one role in a single registration transaction. - -The validity of the registration is as per the rules for roles defined by the dApp itself. - -Role registration data is further divided into: - -1. [A Role number](#role-number) -2. An [Optional reference](#reference-to-a-role-signing-key) to the roles signing key -3. An [Optional reference](#reference-to-a-role-encryption-key) to the roles encryption key -4. An [optional reference](#on-chain-payment-key-reference) to the on-chain payment key to use for the role. -5. And [an optional](#role-extended-data-keys) dApp defined set of role specific data. - -#### Role Number - -All roles, except for Role 0, are defined by the dApp. - -Role 0 is the primary role and is used to sign the metadata and declare on-chain/off-chain identity linkage. -All compliant implementations of this specification use Role 0 in this way. - -dApps can extend what other use cases Role 0 has, but it will always be used to secure the Role registrations. - -For example, in Catalyst Role 0 is a basic voters role. -Voters do not need to register for any other role to have basic interaction with project Catalyst. - -The recommendation is that Role 0 be used by dApps to give the minimum level of access the dApp requires and -other extended roles are defined as Role 1+. - -#### Reference to a role signing key - -Each role can optionally be used to sign data. -If the role is intended to sign data, the key it uses to sign must be declared in this field. -This is a reference to either a registered certificate for the identity posting the registration, -or one of the defined simple public keys. - -A dApp can define is roles allow the use of certificates, or simple public keys, or both. - -Role 0 MUST have a signing key, and it must be a certificate. -Simple keys can not be used for signing against Role 0. - -The reason for this is the Role 0 certificate MUST include a reference to the on-chain identity/s to be bound to the registration. -Simple public keys can not contain this reference, which is why they are not permissible for Role 0 keys. - -A reference to a key/certificate can be a cert in the same registration, or any previous registration. -If the certificate is revoked, the role is unusable for signing unless and until a new signing certificate -is registered for the role. - -#### Reference to a role encryption key - -A Role may require the ability to transfer encrypted data. -The registration can include the Public key use by the role to encrypt the roles data. -Due to the way public key encryption works, this key can only be used to send encrypted data to the holder of the public key. -However, when two users have registered public keys, -they can use them off-chain to perform key exchange and communicate privately between themselves. - -The Role encryption key must be a reference to a key that supports public key encryption, and not just a signing key. -If the key referenced does not support public key encryption, the registration is invalid. - -#### On-chain payment key reference - -Some dApps may require a user to register their payment key, so that they can be sent rewards, -or native tokens or nft's or for other use cases. - -Registrations like CIP-15/36 for catalyst include a payment key. -However, a fundamental problem with these metadata standards is there is no way to validate: - -1. The payment key declared is valid and capable of receiving payments. -2. That the entity posting the registration actually owns the payment key registered. - -It is important that payment keys be verifiable and provably owned to the registrar. - -A Payment key reference in this CIP solves this problem by only allowing a reference to either a transaction input or output. - -The reference is a simple signed integer. -If the integer is positive, then it is referencing the spent UTXO in the transaction Input at the same offset. -Because its is required to prove one can spend a UTXO to post the transaction, -the transaction itself proves that the Payment address being registered is both valid and owned by the registrar. - -If the reference is negative, then the payment key references a transaction output. -The value is negated to get the offset into the transaction output array. - -If the transaction output address IS also an input to the transaction, -then the same proof has already been attached to the transaction. - -However, if the transaction output is not also an input, the transaction MUST include the output address -in the required signers field, and the transaction must carry a witness proving the payment key is owned. - -This provides guarantees that the entity posting the registration has posted a valid payment address, and that they control it. - -If a payment address is not able to be validated, then the entire registration metadata is invalid. - -#### Role extended data keys - -Each dApp can declare that roles can have either mandatory or optional data items that can be posted with any role registration. - -Each role can have a different set of defined role registration data. -It is not required that all roles have the same data. - -As the role data is dApp specific, it is not detailed here. -Each dApp will need to produce a specification of what role specific data it requires, and how it is validated. - -### dApp specific registration data - -Each dApp can define data which is required for registration to the dApp. -This data can be defined as required or optional by the dApp. - -The data is global and applies to all roles registered by the same identity. - -This can include information such as ADA Handles, or reputation data associated with a registration. - -As this data is dApp specific it is not detailed here. - -### Registration validity - -Any registration metadata must be 100% valid, or the entire registration data set is rejected as invalid. - -For example, if three roles were registered, Role 0, 1 and 2. - -Role 0 is perfectly fine, as is Role 1. -However Role 2 has an error with the payment key. -None of the role registrations will take effect. - -### Optional fields - -As role registration is cumulative and each new registration for an entity on a dApp simply updates a previous -registration, then all fields are optional. - -The individual posting the registration need ONLY post the data that has changed or is being added. -This is intended to minimize the amount of on-chain data. -It does mean that a registration state can only be known by collecting all registration for an individual from the chain. - -### First Registration - -The very first registration must have the following features: - -1. It MUST have a certificate that is appropriately issued (either self signed or issued by a trusted CA). - 1. The certificate requirement is defined by each dApp. - 2. The certificate MUST link to at least 1 on-chain identity. - dApps define what the required identities are. - It is valid for a dApp to require multiple on-chain identities to be referenced. - However, general validity can be inferred by the presence or lack of a referenced on-chain identity. - 1. Either currently a Stake Address; or - 2. Another on-chain identity key (such as dRep). - 3. The transaction MUST be witnessed by ALL the Role 0 referenced on-chain identities. - 1. If the address is not a natural address to witness the transaction, it MUST be included in the - required signers field of the transaction. - And it must appear in the witness set. -2. It MUST have a Role 0 defined, that references the certificate. -3. It must be signed by the Role 0 certificate. - -Once the Role 0 certificate is registered, the entity is registered for the dApp. -Provided the dApp will accept the individuals registration. - -Other certificates DO NOT need to have references to the on-chain identity of the user. -However, if they do, they must be witnessed in the transaction to prove they are validly held and referenced. - -### De-registering - -Once a user has registered for Role 0, the only way they can de-register is to revoke their Role 0 key. -If the Role 0 key is revoked, and is not replaced in the same transaction with a new key, then all -registration data for that user is revoked. - -A user could then create a new registration with a new Role 0 certificate, -but they would also need to register for any Roles again. - -This is because if the Role 0 certificate is not immediately rolled over, then all role registrations are deemed terminated. - -It is also possible for a de-registration to cause a linked registration to use a new on-chain identity. - -For example, if the current Role 0 registration referenced Stake address 123, -and a new registration is posted that revokes the old cert, and posts a new cert referencing Stake address 456, -then the on-chain stake address identity will have changed from 123 to 456. - -Note: in the case of a CA revoked certificate, -the subject must have registered a new Role 0 certificate before the issuer revokes it. - -Otherwise, they will become de-registered when the issuer revokes their certificate, and they must then completely re-register. - -## Rationale: how does this CIP achieve its goals? - -## Path to Active - -* All related CIP's are implemented in a MVP implementation for Project Catalyst. -* All implementation details have been refined allowing unambiguous implementation for the MVP. -* Appropriate community driven feedback has occurred to allow the specification to mature. - -### Acceptance Criteria - -### Implementation Plan - -## References - -* [CC-BY-4.0] -* [Apache 2.0] -* [CBOR] -* [CBOR - Core Deterministic Encoding Requirements] -* [C509] -* [CBOR Undefined/Absent Tags] - -## Copyright - -This CIP is licensed under [CC-BY-4.0] - -Code samples and reference material are licensed under [Apache 2.0] - -[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode -[Apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0.html -[CBOR]: https://www.rfc-editor.org/rfc/rfc8949.html -[CBOR - Core Deterministic Encoding Requirements]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.1 -[C509]: https://datatracker.ietf.org/doc/html/draft-ietf-cose-cbor-encoded-cert-07 -[CBOR Undefined/Absent Tags]: https://github.com/svaarala/cbor-specs/blob/master/cbor-absent-tag.rst +* [New Home](https://github.com/input-output-hk/catalyst-CIPs/blob/x509-role-registration-metadata/CIP-XXXX/README.md) +* [CIP PR](https://github.com/cardano-foundation/CIPs/pull/811)