Add NOC root certificate transactions design doc #529
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,101 @@ | ||||||
| # NOC Root Certificate Transactions Design | ||||||
|
|
||||||
| ## User Stories | ||||||
|
|
||||||
| ### 1. Add NOC Root Certificate | ||||||
| A Vendor with DCL write privilege can submit a transaction to add a NOC Root certificate associated with their Vendor ID. | ||||||
|
|
||||||
| ### 2. Revoke NOC Root Certificate | ||||||
| A Vendor with DCL write privilege can submit a transaction to revoke a NOC Root certificate associated with their Vendor ID. | ||||||
|
|
||||||
| ## Certificate Schema | ||||||
|
|
||||||
| To distinguesh NOC root certificates from others, an `isNOC` boolean field will be added to the [certificates](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/proto/pki/certificate.proto) schema | ||||||
|
|
||||||
| ## Transactions | ||||||
|
|
||||||
| ### 1. ADD_NOC_X509_ROOT_CERTIFICATE | ||||||
| This transaction adds a NOC Root Certificate owned by the Vendor. | ||||||
|
|
||||||
| - Who can send: Vendor account | ||||||
| - VID-scoped NOC Root Certificate: The `vid` field in the certificate's subject must be equal to the Vendor account's VID. | ||||||
| - Validation: | ||||||
| - The provided certificate must be a root certificate: | ||||||
| - `Issuer` == `Subject` | ||||||
| - `Authority Key Identifier` == `Subject Key Identifier` | ||||||
| - No existing certificate with the same `<Certificate's Issuer>:<Certificate's Serial Number>` combination. | ||||||
| - If certificates with the same `<Certificate's Subject>:<Certificate's Subject Key ID>` combination already exist: | ||||||
| - The sender must match the owner of the existing certificates. | ||||||
| - The signature (self-signature) and expiration date must be valid. | ||||||
| - Parameters: | ||||||
| - cert: `string` - The NOC Root Certificate, encoded in X.509v3 PEM format. Can be a PEM string or a file path. | ||||||
| - In State: | ||||||
| - `pki/ApprovedCertificates/value/<Subject>/<SubjectKeyID>` | ||||||
| - `pki/NOCRootCertificates/value/<VID>` | ||||||
| - CLI Command: | ||||||
| - `dcld tx pki add-noc-x509-root-cert --certificate=<string-or-path> --from=<account>` | ||||||
|
|
||||||
| ### 2. REVOKE_NOC_X509_ROOT_CERTIFICATE | ||||||
|
There was a problem hiding this comment. I think it's an open question how Revocation should work here.
Open Questions; for now assume Soft-delete (revoked certificates are moved to something like ...noc/revoked/... path (similar to common Root certs, but specific collection for NOC Roots). Do we need to put revoked NOC Root into a collection with other revoked Root certs? |
||||||
| This transaction revokes a NOC Root Certificate owned by the Vendor. | ||||||
|
|
||||||
| - Who can send: Vendor account | ||||||
| - VID-scoped NOC Root Certificate: The `vid` field in the certificate's subject must be equal to the Vendor account's VID. | ||||||
| - Validation: | ||||||
| - A NOC Root Certificate with the provided `subject` and `subject_key_id` must exist in the ledger. | ||||||
| - Parameters: | ||||||
| - subject: `string` - Base64 encoded subject DER sequence bytes of the certificate. | ||||||
| - subject_key_id: `string` - Certificate's `Subject Key Id` in hex string format, e.g., `5A:88:0E:6C:36:53:D0:7F:B0:89:71:A3:F4:73:79:09:30:E6:2B:DB`. | ||||||
| - In State: | ||||||
| - `pki/RevokedNOCRootCertificates/value/<subject>/<subject_key_id>` | ||||||
| - CLI Command: | ||||||
| - `dcld tx pki revoke-noc-x509-root-cert --subject=<base64 string> --subject-key-id=<hex string> --from=<account>` | ||||||
|
|
||||||
| ## Query | ||||||
|
There was a problem hiding this comment.
|
||||||
|
|
||||||
| To retrieve NOC certificates by Subject and Subject Key Identifier, use the [GET_X509_CERT](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_x509_cert) or [GET_ALL_SUBJECT_X509_CERTS](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_all_subject_x509_certs:) query. | ||||||
|
|
||||||
| ### GET_NOC_X509_ROOT_CERTS_BY_VID | ||||||
|
|
||||||
| Retrieve NOC Root Certificates associated with a specific VID. | ||||||
|
|
||||||
| - Who can send: Any account | ||||||
| - Parameters: | ||||||
| - vid: `uint16` - Vendor ID (positive non-zero) | ||||||
| - CLI Command: | ||||||
| - `dcld query pki get_noc_x509_root_certs --vid=<uint16>` | ||||||
| - REST API: | ||||||
| - GET `/dcl/pki/noc-root-certificates/{vid}` | ||||||
|
|
||||||
| ### GET_ALL_NOC_X509_ROOT_CERTS | ||||||
|
|
||||||
| Retrieve a list of all of NOC Root Certificates | ||||||
|
|
||||||
| - Who can send: Any account | ||||||
| - Parameters: | ||||||
| - Common pagination parameters | ||||||
| - CLI Command: | ||||||
| - `dcld query pki get_all_noc_x509_root_certs | ||||||
| - REST API: | ||||||
| - GET `/dcl/pki/noc-root-certificates` | ||||||
|
|
||||||
| ### GET_REVOKED_NOC_X509_ROOT_CERTS | ||||||
|
|
||||||
| Retrieve revoked NOC Root Certificates associated with a specific Subject and Subject Key Identifier. | ||||||
|
|
||||||
| - Who can send: Any account | ||||||
| - Parameters: | ||||||
| - subject: `string` - Base64 encoded subject DER sequence bytes of the certificate. | ||||||
| - subject_key_id: `string` - Certificate's `Subject Key Id` in hex string format, e.g., `5A:88:0E:6C:36:53:D0:7F:B0:89:71:A3:F4:73:79:09:30:E6:2B:DB`. | ||||||
| - CLI Command: | ||||||
| - `dcld query pki get_revoked_noc_x509_root_certs | ||||||
| - REST API: | ||||||
| - GET `/dcl/pki/revoked-noc-root-certificates/{subject}/{subject_key_id}` | ||||||
|
|
||||||
| ## Questions | ||||||
| - Should the vendor add a revocation distribution point for NOC certificates? | ||||||
| - Should the following queries return NOC Certificate? | ||||||
| - [GET_ALL_SUBJECT_X509_CERTS](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_all_subject_x509_certs) | ||||||
| - [GET_ALL_X509_ROOT_CERTS](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_all_x509_root_certs) | ||||||
| - [GET_ALL_X509_CERTS](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_all_x509_root_certs) | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| - Should an additional field be added to the certificate schema to distinguish NOC certificates from common PAAs/PAIs? | ||||||
| - Should a revoked NOC certificate be stored in the revoked list, or should it be completely removed? Additionally, if a NOC root certificate is revoked, should it be saved in the existing revocation list or in a separate list? | ||||||
|
There was a problem hiding this comment. Please add clarification here: should revoked Root NOC certificates be returned in the existing https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_all_revoked_x509_root_certs and https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_revoked_cert? |
||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Need to decide, if we want to distinguish NOC certificates from common PAAs/PAIs (for example when querying it by Subject+SubjectKeyId).
Open Questions; for now assume YES (needed).
For example, we can introduce a new field to the Certificate data model (https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/proto/pki/certificate.proto): bool NOC