Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the NOC root certificate design based on discussion feedback #534

Merged
merged 3 commits into from
Jan 11, 2024
Merged

Update the NOC root certificate design based on discussion feedback #534

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bab12ae
Update the NOC root certificate design based on discussion feedback
akarabashov Jan 11, 2024
4640572
Add question about Trust Quotient to the NOC root design
akarabashov Jan 11, 2024
bdbe6c0
Update the NOC root certificate design based on PR feedback
akarabashov Jan 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 39 additions & 30 deletions docs/design/noc-root-cert-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,13 @@
## 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.
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.
A Vendor with DCL write privilege can submit a transaction to revoke a NOC root certificate associated with their Vendor ID.

### 3. Remove NOC Root Certificate
A Vendor with DCL write privilege can submit a transaction to remove a NOC root certificate associated with their Vendor ID. So that the Vendor can remove certificates that were added by mistake.

## Certificate Schema

Expand All @@ -15,48 +18,68 @@ To distinguesh NOC root certificates from others, an `isNOC` boolean field will
## Transactions

### 1. ADD_NOC_X509_ROOT_CERTIFICATE
This transaction adds a NOC Root Certificate owned by the Vendor.
This transaction adds a NOC root certificate owned by the Vendor.

ashcherbakov marked this conversation as resolved.
Show resolved Hide resolved
- 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.
- `vid` field in the transaction (`VendorID`) must be equal to the Vendor account's VID
- Validation:
- The provided certificate must be a root certificate:
ashcherbakov marked this conversation as resolved.
Show resolved Hide resolved
- `Issuer` == `Subject`
- `Authority Key Identifier` == `Subject Key Identifier`
- No existing certificate with the same `<Certificate's Issuer>:<Certificate's Serial Number>` combination.
ashcherbakov marked this conversation as resolved.
Show resolved Hide resolved
- 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 sender's VID must match the vid field of the existing certificates.
- No existing certificate with the same `<Certificate's Subject>:<Certificate's Subject Key ID>` combination already published by another vendor.
- 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.
- vid: `uint16` - Vendor ID (positive non-zero)
- In State:
- `pki/ApprovedCertificates/value/<Subject>/<SubjectKeyID>`
- `pki/ApprovedCertificatesBySubject/value/<Subject>`
- `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
This transaction revokes a NOC Root Certificate owned by the Vendor.
This transaction revokes a NOC root certificate owned by the Vendor.
Revoked NOC root certificates can be re-added using the `ADD_NOC_X509_ROOT_CERTIFICATE` transaction.

- 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.
- Vid field associated with the corresponding NOC root certificate on the ledger 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>`
- `pki/RevokedCertificates/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>`

### 3. REMOVE_NOC_X509_ROOT_CERTIFICATE
This transaction completely removes a NOC root certificate owned by the Vendor.
Removed NOC root certificates can be re-added using the `ADD_NOC_X509_ROOT_CERTIFICATE` transaction.

- Who can send: Vendor account
- Vid field associated with the corresponding NOC root certificate on the ledger 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`.
- CLI Command:
- `dcld tx pki remove-noc-x509-root-cert --subject=<base64 string> --subject-key-id=<hex string> --from=<account>`

## Query

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.

To retrieve a revoked NOC certificate by Subject and Subject Key Identifier, use the [GET_REVOKED_CERT](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_revoked_cert)

### GET_NOC_X509_ROOT_CERTS_BY_VID

Retrieve NOC Root Certificates associated with a specific VID.
Retrieve NOC root certificates associated with a specific VID.

- Who can send: Any account
- Parameters:
Expand All @@ -68,7 +91,7 @@ Retrieve NOC Root Certificates associated with a specific VID.

### GET_ALL_NOC_X509_ROOT_CERTS

Retrieve a list of all of NOC Root Certificates
Retrieve a list of all of NOC root certificates

- Who can send: Any account
- Parameters:
Expand All @@ -78,24 +101,10 @@ Retrieve a list of all of NOC Root Certificates
- 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_X509_CERT](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_x509_cert)
- Should an additional field be added to the certificate schema to distinguish NOC certificates from common PAAs/PAIs?
- Should a revoked NOC Root Certificate be stored in the revoked list, or should it be completely removed? Additionally, if a NOC Root Certificate is revoked, should it be returned in the existing [GET_ALL_REVOKED_X509_ROOT_CERTS](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_all_revoked_x509_root_certs) and [GET_REVOKED_CERT](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_revoked_cert) queries?
- Should a vendor be able to add multiple NOC root certificates with the same Subject and Subject Key Identifier combinations? If so, the vendor may want to remove a specific certificate from the list of certificates with the same Subject and Subject Key Identifier combinations.
- Should the VID parameter be added to the `ADD_NOC_X509_ROOT_CERTIFICATE` transaction?
- How should NOC root certificate be renewed with a new one?
- Should the `REMOVE_NOC_X509_ROOT_CERTIFICATE` transaction also delete revoked certificates?
- Should a user be able to retrieve all revoked NOC root certificates using the `GET_ALL_REVOKED_X509_NOC_ROOT_CERTS` transaction?
- In the `Joint Fabric Proposal` document, the concept of a `Trust Quotient (TQ)` is introduced as a future consideration. This concept requires adding `Add Trust` and `Revoke Trust` requests for NOCs in the DCL. Should the implementation of these requests be included in the scope of the current task?