11---
2- Title : RBAC Key Identifier URI Specification
2+ Title : RBAC Catalyst Identifier URI Specification
33Category : Catalyst
44Status : Proposed
55Authors :
@@ -11,6 +11,8 @@ Created: 2025-01-05
1111License : CC-BY-4.0
1212---
1313
14+ <!-- cspell: words Fftx -->
15+
1416* [ Abstract] ( #abstract )
1517* [ Motivation: why is this CIP necessary?] ( #motivation-why-is-this-cip-necessary )
1618* [ Specification] ( #specification )
@@ -20,8 +22,7 @@ License: CC-BY-4.0
2022 * [ ` authority ` - ` host ` ] ( #authority---host )
2123 * [ List of defined hosts] ( #list-of-defined-hosts )
2224 * [ ` authority ` - ` userinfo ` ] ( #authority---userinfo )
23- * [ Lists of defined subnetwork ` userinfo ` values] ( #lists-of-defined-subnetwork-userinfo-values )
24- * [ Cardano] ( #cardano )
25+ * [ Example ` userinfo ` with a ` hostname ` ] ( #example-userinfo-with-a-hostname )
2526 * [ ` path ` ] ( #path )
2627* [ Reference Implementation] ( #reference-implementation )
2728* [ Test Vectors] ( #test-vectors )
@@ -33,39 +34,44 @@ License: CC-BY-4.0
3334
3435## Abstract
3536
36- Definition of a [ URI] which allows for RBAC keys used for different purposes to be easily and
37+ Definition of a [ URI] , which allows for RBAC keys used for different purposes to be easily and
3738unambiguously identified.
3839
3940## Motivation: why is this CIP necessary?
4041
41- There is a need to identify which Key from a RBAC registration was used to sign data.
42+ There is a need to identify which RBAC Registration is referenced,
43+ or which Key from a RBAC registration was used to sign data.
4244RBAC defines a universal keychain of different keys that can be used for different purposes.
4345They can be used not only for Signatures, but also Encryption.
4446
45- Therefore, there needs to be an unambiguous and easy to lookup identifier to signify which key was
46- used for a particular purpose.
47+ Sometimes all that is required is to identify the individual keychain.
48+ Other times a specific key on the chain needs to be referenced.
49+
50+ Therefore, there needs to be an unambiguous and easy to lookup identifier to signify which keychain,
51+ or key in a particular chain was used for a particular purpose.
4752
48- This document defines a [ URI] scheme to unambiguously define a particular key with reference to a
49- particular RBAC keychain.
53+ This document defines a [ URI] scheme to unambiguously define a keychain or a specific key within the keychain.
5054
5155## Specification
5256
5357### URI
5458
55- The RBAC Kid is formatted using a [ Universal Resource Identifier] .
59+ The Catalyst RBAC ID is formatted using a [ Universal Resource Identifier] .
5660Refer to [ RFC3986] for the specification of the URI format.
5761
5862### ` scheme `
5963
60- The [ scheme] ( https://datatracker.ietf.org/doc/html/rfc3986#section-3.1 ) ** MUST** be ` kid.catalyst-rbac ` ;
64+ The [ scheme] ( https://datatracker.ietf.org/doc/html/rfc3986#section-3.1 ) ** MUST** be ` id.catalyst ` .
65+
66+ When used as a Catalyst ID, where only catalyst IDs would be used, the scheme can be omitted.
6167
6268### ` authority `
6369
6470The [ authority] ( https://datatracker.ietf.org/doc/html/rfc3986#section-3.2 ) references the blockchain or network
6571the key was registered within.
6672
67- It is perfectly valid for a Kid to reference a different network than the place where the Key is used.
68- For example, a ` cardano ` KID can be used to post documents to ` IPFS ` .
73+ It is perfectly valid for an ID Uri to reference a different network than the place where the ID or Key is used.
74+ For example, a ` cardano ` ID can be used to post documents to ` IPFS ` .
6975Its purpose is to define WHERE the key was registered, and nothing more.
7076
7177The Authority will consist of a ` host ` and optional ` userinfo ` .
@@ -76,32 +82,45 @@ The [host](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2)
7682refers to the network type where the RBAC registration was made.
7783It ** IS NOT** resolvable with ** DNS** , and ** IS NOT** a public host name.
7884It is used as a decentralized network identifier.
79- The consumer of the ` KID ` must be able to resolve these host names.
85+ The consumer of the ` ID ` must be able to resolve these host names to known and supported blockchain networks.
86+
87+ The hostname may have one or more subdomains which could specify side-chains of a particular network,
88+ or test networks.
8089
8190##### List of defined hosts
8291
8392| ` host ` | Description |
8493| --- | --- |
8594| ` cardano ` | Cardano Blockchain |
95+ | ` preprod.cardano ` | Preprod Cardano Blockchain test network |
96+ | ` preview.cardano ` | Preview Cardano Blockchain test network |
8697| ` midnight ` | Midnight Blockchain |
8798| ` ethereum ` | Ethereum Blockchain |
8899| ` cosmos ` | Cosmos Blockchain |
89100
101+ This list is indicative of the host names that can be used, any hostname is valid provided it is
102+ capable of storing catalyst RBAC registration keychains.
103+
90104#### ` authority ` - ` userinfo `
91105
92- The [ userinfo] ( https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1 )
93- is used to distinguish a subnetwork from the primary main network.
94- The absence of ` userinfo ` is used to indicate the primary main network .
106+ The [ userinfo] is used to hold a user defined readable name that can be attached to the keychain.
107+ It may contain an optional ` nonce ` which is separated from the user's name by a ` : ` and replaces a
108+ traditional password used for HTTP basic authentication .
95109
96- ##### Lists of defined subnetwork ` userinfo ` values
110+ Because the name is not unique, and is provided by the user, it is informational only.
111+ A URI is identical, provided the hostname and path are the same, the [ userinfo] does not play
112+ a part in validating or finding the catalyst keychain being referenced.
97113
98- ###### Cardano
114+ The ` nonce ` part contained in the ` password ` component of the username * MUST* be an integer,
115+ and it is the number of seconds since 1970 UTC, when the Catalyst ID URI was generated.
99116
100- | ` userinfo ` | Description |
101- | --- | --- |
102- | ` preprod ` | Cardano Pre-Production Network |
103- | ` preview ` | Cardano Preview Network |
104- | 0x<hex_number> | Cardano network identified by this magic number in hex |
117+ Applications which use the ` nonce ` will define its use, anything that does not use the ` nonce ` will ignore it.
118+
119+ ##### Example ` userinfo ` with a ` hostname `
120+
121+ * ` anne@cardano ` - username ` anne ` no nonce.
122+ * ` blake:1737101079@midnight ` - username ` blake ` with nonce 1737101079.
123+ * ` :173710179@ethereum ` - no username with nonce 173710179.
105124
106125### ` path `
107126
@@ -115,13 +134,17 @@ The overall `path` specification is: `<initial role0 key>/<role>/<rotation>#encr
115134 * This does not change, even if the Initial Role 0 key is revoked.
116135 * This allows for an unambiguous identifier for the RBAC keychain.
117136 * It is not necessarily the key being identified.
118- * ` <role> ` - This is the Role number being used.
137+ * An example Role 0 Key is ` FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE `
138+ * ` <role> ` - * Optional* This is the Role number being used.
119139 * It is a positive number, starting at 0, and no greater than 65535.
120- * ` <rotation> ` - This is the rotation of the defined role key being identified.
140+ * If it is not defined, then its default value is 0.
141+ * If it is not defined, there can be no ` <rotation> ` part of the path following.
142+ * ` <rotation> ` - * Optional* This is the rotation of the defined role key being identified.
121143 * It starts at 0 for the first published key for the role, and increments by one for each subsequent published rotation.
122144 * This number refers to the published sequence of keys for the role in the RBAC registration keychain,
123145 not the index used in the key derivation.
124146 * It is positive and no greater than 65535.
147+ * If not present, it defaults to 0.
125148* ` #encrypt ` - [ Fragment] ( https://datatracker.ietf.org/doc/html/rfc3986#section-3.5 )
126149 disambiguates Encryption Public Keys from signing public keys.
127150 * Roles can have 1 active public signing key, and 1 active public encryption key.
@@ -134,26 +157,52 @@ The first implementation will be Catalyst Voices.
134157
135158## Test Vectors
136159
137- * ` kid.catalyst-rbac://cardano/<key>/0/0 `
160+ * ` id.catalyst://cardano/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE `
161+ * A Signing key registered on the Cardano Main network.
162+ * Role 0 - Rotation 0.
163+ * ` username ` - undefined.
164+ * ` nonce ` - undefined.
165+ * In this example, it is identical to ` FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/0/0 ` or
166+ ` FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/0 ` .
167+ * ` id.catalyst://cardano/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/0 `
168+ * A Signing key registered on the Cardano Main network.
169+ * Role 0 - Rotation 0.
170+ * ` username ` - undefined.
171+ * ` nonce ` - undefined.
172+ * In this example, it is identical to ` FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/0/0 ` or
173+ ` FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE ` .
174+ * ` id.catalyst://gary@cardano/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/0/0 `
138175 * A Signing key registered on the Cardano Main network.
139176 * Role 0 - Rotation 0.
140- In this example, it is exactly the same as the ` <key> ` .
141- * ` kid.catalyst-rbac://preprod@cardano/<key>/7/3 `
177+ * ` username ` - ` gary ` .
178+ * ` nonce ` - undefined.
179+ * In this example, it is identical to ` FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE ` or
180+ ` FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/0 ` .
181+ * ` id.catalyst://[email protected] /FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/7/3 ` 142182 * A Signing key registered on the Cardano pre-production network.
143183 * Role 7 - Rotation 3.
144- The Key for Role 7, and its third published rotation
184+ * ` username ` - ` faith `
185+ * ` nonce ` - undefined.
186+ * The Key for Role 7, and its third published rotation
145187 (i.e., the fourth key published, the first is the initial key, plus 3 rotations following it).
146- * ` kid .catalyst-rbac ://preprod@ cardano/<key> /2/0#encrypt`
188+ * ` id .catalyst://faith:173710179@preprod. cardano/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE /2/0#encrypt`
147189 * A Public Encryption key registered on the Cardano pre-production network.
148190 * Role 2 - Rotation 0.
149- The initially published Public Encryption Key for Role 2.
150- * ` kid.catalyst-rbac://midnight/<key>/0/1 `
191+ * ` username ` - ` faith `
192+ * ` nonce ` - 173710179.
193+ * The initially published Public Encryption Key for Role 2.
194+ * ` id.catalyst://:173710179@midnight/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/0/1 `
151195 * A Signing key registered on the Midnight Blockchain Main network
152196 * Role 0 - Rotation 1.
153- In this example, it is NOT the same as the ` <key> ` , as it identifies the first rotation after ` <key> ` .
154- * ` kid.catalyst-rbac://midnight/<key>/2/1#encrypt `
155- * A public encryption key registered on the Midnight Blockchain Main network.
197+ * ` username ` - undefined.
198+ * ` nonce ` - 173710179.
199+ * In this example, it is NOT the same as the ` FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE ` ,
200+ as it identifies the first rotation after ` FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE ` .
201+ * ` id.catalyst://midnight/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/2/1#encrypt `
202+ * A Public Encryption key registered on the Midnight Blockchain Main network.
156203 * Role 2 - Rotation 1.
204+ * ` username ` - undefined.
205+ * ` nonce ` - undefined.
157206
158207## Rationale: how does this CIP achieve its goals?
159208
@@ -178,3 +227,4 @@ This document is licensed under [CC-BY-4.0](https://creativecommons.org/licenses
178227[ Universal Resource Identifier ] : https://datatracker.ietf.org/doc/html/rfc3986
179228[ RFC3986 ] : https://datatracker.ietf.org/doc/html/rfc3986
180229[ Base64 URL ] : https://datatracker.ietf.org/doc/html/rfc4648#section-5
230+ [ userinfo ] : (https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1)
0 commit comments