Docs clarification for NOC certs (#587)

Added some clarification notes to docs and CLI commands that NOC Root == RCAC and NOC ICA == ICAC
zigbee-alliance · Aug 1, 2024 · 7bb5b6b · 7bb5b6b
1 parent 5d4f0fe
commit 7bb5b6b
Show file tree

Hide file tree

Showing 11 changed files with 56 additions and 55 deletions.
diff --git a/docs/transactions.md b/docs/transactions.md
@@ -1354,16 +1354,16 @@ Should be sent to trusted nodes only.
 
 ### E2E (NOC)
 
-#### ADD_NOC_ROOT
+#### ADD_NOC_ROOT (RCAC)
 
 **Status: Implemented**
 
-This transaction adds a NOC root certificate owned by the Vendor.
+This transaction adds a NOC root certificate (RCAC) owned by the Vendor.
 
 - Who can send
  - Vendor account
 - Parameters:
- - cert: `string` - The NOC Root Certificate, encoded in X.509v3 PEM format. Can be a PEM string or a file path.
+ - cert: `string` - The NOC Root Certificate (RCAC), encoded in X.509v3 PEM format. Can be a PEM string or a file path.
  - schemaVersion: `optional(uint16)` - Certificate's schema version to support backward/forward compatability(default 0)
 - In State:
  - `pki/ApprovedCertificates/value/<Subject>/<SubjectKeyID>`
@@ -1373,27 +1373,27 @@ This transaction adds a NOC root certificate owned by the Vendor.
 - CLI Command:
  - `dcld tx pki add-noc-x509-root-cert --certificate=<string-or-path> --from=<account>`
 - Validation:
- - the provided certificate must be a root certificate:
+ - the provided certificate must be a root certificate (RCAC):
  - `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 existing certificate must be NOC root certificate
+ - the existing certificate must be NOC root certificate (RCAC)
  - the sender's VID must match the `vid` field of the existing certificates.
  - the signature (self-signature) and expiration date must be valid.
 
-#### REVOKE_NOC_ROOT
+#### REVOKE_NOC_ROOT (RCAC)
 
 **Status: Implemented**
 
-This transaction revokes a NOC root certificate owned by the Vendor.
-Revoked NOC root certificates can be re-added using the [ADD_NOC_ROOT](#add_noc_root) transaction.
+This transaction revokes a NOC root certificate (RCAC) owned by the Vendor.
+Revoked NOC root certificates (RCACs) can be re-added using the [ADD_NOC_ROOT](#add_noc_root-(rcac)) transaction.
 
 Revocation works as a soft-delete, meaning that the certificates are not entirely removed but moved from the approved list to the revoked list.
 Revoked certificates can be retrieved by using the [GET_REVOKED_CERT](#get_revoked_cert) query.
 
 - 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.
+ - Vid field associated with the corresponding NOC root certificate (RCAC) on the ledger must be equal to the Vendor account's VID.
 - 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`.
@@ -1407,19 +1407,19 @@ Revoked certificates can be retrieved by using the [GET_REVOKED_CERT](#get_revok
 - CLI command:
  - `dcld tx pki revoke-noc-x509-root-cert --subject=<base64 string> --subject-key-id=<hex string> --serial-number=<string> --info=<string> --time=<int64> --revoke-child=<bool> --from=<account>`
 - Validation:
- - a NOC Root Certificate with the provided `subject` and `subject_key_id` must exist in the ledger.
+ - a NOC Root Certificate (RCAC) with the provided `subject` and `subject_key_id` must exist in the ledger.
 
-#### REMOVE_NOC_ROOT
+#### REMOVE_NOC_ROOT (RCAC)
 
 **Status: Implemented**
 
-This transaction completely removes the given NOC root certificate owned by the Vendor from the ledger.
-Removed NOC root certificates can be re-added using the [ADD_NOC_ROOT](#add_noc_root) transaction.
+This transaction completely removes the given NOC root certificate (RCAC) owned by the Vendor from the ledger.
+Removed NOC root certificates (RCACs) can be re-added using the [ADD_NOC_ROOT](#add_noc_root-(rcac)) transaction.
 
 - Who can send: Vendor account
  - Vid field associated with the corresponding NOC 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.
+ - a NOC Root Certificate (RCAC) 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`.
@@ -1429,11 +1429,11 @@ Removed NOC root certificates can be re-added using the [ADD_NOC_ROOT](#add_noc_
 
 
 
-#### ADD_NOC_ICA
+#### ADD_NOC_ICA (ICAC)
 
 **Status: Implemented**
 
-This transaction adds a NOC ICA certificate owned by the Vendor signed by a chain of certificates which must be
+This transaction adds a NOC ICA certificate (ICAC) owned by the Vendor signed by a chain of certificates which must be
 already present on the ledger.
 
 - Who can send: Vendor account
@@ -1461,12 +1461,12 @@ already present on the ledger.
 - CLI Command:
  - `dcld tx pki add-noc-x509-ica-cert --certificate=<string-or-path> --from=<account>`
 
-#### REVOKE_NOC_ICA
+#### REVOKE_NOC_ICA (ICAC)
 
 **Status: Implemented**
 
-This transaction revokes a NOC ICA certificate owned by the Vendor.
-Revoked NOC ICA certificates can be re-added using the [ADD_NOC_ICA](#add_noc_ica) transaction.
+This transaction revokes a NOC ICA certificate (ICAC) owned by the Vendor.
+Revoked NOC ICA certificates (ICACs) can be re-added using the [ADD_NOC_ICA](#add_noc_ica-(icac)) transaction.
 
 Revocation works as a soft-delete, meaning that the certificates are not entirely removed but moved from the approved list to the revoked list.
 Revoked certificates can be retrieved by using the [GET_REVOKED_CERT](#get_revoked_cert) query.
@@ -1487,17 +1487,17 @@ Revoked certificates can be retrieved by using the [GET_REVOKED_CERT](#get_revok
 - CLI command:
  - `dcld tx pki revoke-noc-x509-ica-cert --subject=<base64 string> --subject-key-id=<hex string> --serial-number=<string> --info=<string> --time=<int64> --revoke-child=<bool> --from=<account>`
 
-#### REMOVE_NOC_ICA
+#### REMOVE_NOC_ICA (ICAC)
 
 **Status: Implemented**
 
-This transaction completely removes the given NOC ICA owned by the Vendor from the ledger.
-Removed NOC ICA certificates can be re-added using the [ADD_NOC_ICA](#add_noc_ica) transaction.
+This transaction completely removes the given NOC ICA (ICAC) owned by the Vendor from the ledger.
+Removed NOC ICA certificates (ICACs) can be re-added using the [ADD_NOC_ICA](#add_noc_ica-(icac)) transaction.
 
 - Who can send: Vendor account
  - Vid field associated with the corresponding NOC certificate on the ledger must be equal to the Vendor account's VID.
 - Validation:
- - a NOC ICA Certificate with the provided `subject` and `subject_key_id` must exist in the ledger.
+ - a NOC ICA Certificate (ICAC) 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`.
@@ -1506,14 +1506,14 @@ Removed NOC ICA certificates can be re-added using the [ADD_NOC_ICA](#add_noc_ic
  - `dcld tx pki remove-noc-x509-ica-cert --subject=<base64 string> --subject-key-id=<hex string> --from=<account>`
 
 
-#### GET_NOC_ROOT_BY_VID
+#### GET_NOC_ROOT_BY_VID (RCACs)
 
 **Status: Implemented**
 
-Retrieve NOC root certificates associated with a specific VID.
+Retrieve NOC root certificates (RCACs) associated with a specific VID.
 
-Revoked NOC root certificates are not returned.
-Use [GET_ALL_REVOKED_NOC_ROOT](#get_revoked_noc_root) to get a list of all revoked NOC root certificates.
+Revoked NOC root certificates (RCACs) are not returned.
+Use [GET_ALL_REVOKED_NOC_ROOT](#get_all_revoked_noc_root-(rcacs)) to get a list of all revoked NOC root certificates (RCACs).
 
 - Who can send: Any account
 - Parameters:
@@ -1523,15 +1523,16 @@ Use [GET_ALL_REVOKED_NOC_ROOT](#get_revoked_noc_root) to get a list of all revok
 - REST API:
  - GET `/dcl/pki/noc-root-certificates/{vid}`
 
-#### GET_NOC_BY_VID_AND_SKID
+#### GET_NOC_BY_VID_AND_SKID (RCACs/ICACs)
 
 **Status: Implemented**
 
-Retrieve NOC (Root/ICA) certificates associated with a specific VID and subject key ID.
+Retrieve NOC (Root/ICA) certificates (RCACs/ICACs) associated with a specific VID and subject key ID.
 This request also returns the Trust Quotient (TQ) value of the certificate
 
 Revoked NOC certificates are not returned.
-Use [GET_ALL_REVOKED_NOC_ROOT](#get_revoked_noc_root) to get a list of all revoked NOC root certificates.
+Use [GET_ALL_REVOKED_NOC_ROOT](#get_all_revoked_noc_root-(rcacs)) to get a list of all revoked NOC root certificates.
+Use [GET_ALL_REVOKED_CERT](#get_all_revoked_certs) to get a list of all revoked certificates (including ICACs).
 
 - Who can send: Any account
 - Parameters:
@@ -1542,11 +1543,11 @@ Use [GET_ALL_REVOKED_NOC_ROOT](#get_revoked_noc_root) to get a list of all revok
 - REST API:
  - GET `/dcl/pki/noc-certificates/{vid}/{subject_key_id}`
 
-#### GET_NOC_ICA_BY_VID
+#### GET_NOC_ICA_BY_VID (ICACs)
 
 **Status: Implemented**
 
-Retrieve NOC ICA certificates associated with a specific VID.
+Retrieve NOC ICA certificates (ICACs) associated with a specific VID.
 
 Revoked certificates are not returned.
 Use [GET_ALL_REVOKED_CERT](#get_all_revoked_certs) to get a list of all revoked certificates.
@@ -1559,11 +1560,11 @@ Use [GET_ALL_REVOKED_CERT](#get_all_revoked_certs) to get a list of all revoked
 - REST API:
  - GET `/dcl/pki/noc-ica-certificates/{vid}`
 
-#### GET_REVOKED_NOC_ROOT
+#### GET_REVOKED_NOC_ROOT (RCAC)
 
 **Status: Implemented**
 
-Gets a revoked NOC root certificate by the given subject and subject key ID attributes.
+Gets a revoked NOC root certificate (RCAC) by the given subject and subject key ID attributes.
 
 Revocation works as a soft-delete, meaning that the certificates are not entirely removed but moved from the approved list to the revoked list.
 
@@ -1575,14 +1576,14 @@ Revocation works as a soft-delete, meaning that the certificates are not entirel
 - REST API:
  - GET `/dcl/pki/revoked-noc-root-certificates/{subject}/{subject_key_id}`
 
-#### GET_ALL_NOC_ROOT
+#### GET_ALL_NOC_ROOT (RCACs)
 
 **Status: Implemented**
 
-Retrieve a list of all of NOC root certificates.
+Retrieve a list of all of NOC root certificates (RCACs).
 
-Revoked NOC root certificates are not returned.
-Use [GET_ALL_REVOKED_NOC_ROOT](#get_revoked_noc_root) to get a list of all revoked NOC root certificates.
+Revoked NOC root certificates (RCACs) are not returned.
+Use [GET_ALL_REVOKED_NOC_ROOT](#get_all_revoked_noc_root-(rcacs)) to get a list of all revoked NOC root certificates (RCACs).
 
 - Who can send: Any account
 - Parameters:
@@ -1592,11 +1593,11 @@ Use [GET_ALL_REVOKED_NOC_ROOT](#get_revoked_noc_root) to get a list of all revok
 - REST API:
  - GET `/dcl/pki/noc-root-certificates`
 
-#### GET_ALL_NOC_ICA
+#### GET_ALL_NOC_ICA (ICACs)
 
 **Status: Implemented**
 
-Retrieve a list of all of NOC ICA certificates
+Retrieve a list of all of NOC ICA certificates (ICACs).
 
 Revoked certificates are not returned.
 Use [GET_ALL_REVOKED_CERT](#get_all_revoked_certs) to get a list of all revoked certificates.
@@ -1609,9 +1610,9 @@ Use [GET_ALL_REVOKED_CERT](#get_all_revoked_certs) to get a list of all revoked
 - REST API:
  - GET `/dcl/pki/noc-ica-certificates`
 
-#### GET_ALL_REVOKED_NOC_ROOT
+#### GET_ALL_REVOKED_NOC_ROOT (RCACs)
 
-Gets all revoked NOC root certificates.
+Gets all revoked NOC root certificates (RCACs).
 
 Revocation works as a soft-delete, meaning that the certificates are not entirely removed but moved from the approved list to the revoked list.
 

diff --git a/x/pki/client/cli/query_noc_certificates.go b/x/pki/client/cli/query_noc_certificates.go
@@ -15,7 +15,7 @@ import (
 func CmdListNocIcaCertificates() *cobra.Command {
  cmd := &cobra.Command{
  Use: "all-noc-x509-ica-certs",
- Short: "Gets all NOC ICA certificates",
+ Short: "Gets all NOC ICA certificates (ICACs)",
  RunE: func(cmd *cobra.Command, args []string) error {
  clientCtx := client.GetClientContextFromCmd(cmd)
 
@@ -49,7 +49,7 @@ func CmdShowNocIcaCertificates() *cobra.Command {
  var vid int32
  cmd := &cobra.Command{
  Use: "noc-x509-ica-certs",
- Short: "Gets NOC ICA certificates by VID",
+ Short: "Gets NOC ICA certificates (ICACs) by VID",
  Args: cobra.ExactArgs(0),
  RunE: func(cmd *cobra.Command, args []string) (err error) {
  clientCtx := client.GetClientContextFromCmd(cmd)

diff --git a/x/pki/client/cli/query_noc_certificates_by_vid_skid.go b/x/pki/client/cli/query_noc_certificates_by_vid_skid.go
@@ -17,7 +17,7 @@ func CmdShowNocCertificatesByVidAndSkid() *cobra.Command {
 
  cmd := &cobra.Command{
  Use: "noc-x509-certs",
- Short: "Gets NOC certificates by VID and Skid",
+ Short: "Gets NOC (Root/ICA) certificates (RCAC/ICAC) by VID and Skid",
  Args: cobra.ExactArgs(0),
  RunE: func(cmd *cobra.Command, args []string) (err error) {
  clientCtx := client.GetClientContextFromCmd(cmd)

diff --git a/x/pki/client/cli/query_noc_root_certificates.go b/x/pki/client/cli/query_noc_root_certificates.go
@@ -14,7 +14,7 @@ import (
 func CmdListNocRootCertificates() *cobra.Command {
  cmd := &cobra.Command{
  Use: "all-noc-x509-root-certs",
- Short: "Gets all NOC root certificates",
+ Short: "Gets all NOC root certificates (RCACs)",
  RunE: func(cmd *cobra.Command, args []string) error {
  clientCtx := client.GetClientContextFromCmd(cmd)
 
@@ -51,7 +51,7 @@ func CmdShowNocRootCertificates() *cobra.Command {
 
  cmd := &cobra.Command{
  Use: "noc-x509-root-certs",
- Short: "Gets NOC root certificates by VID",
+ Short: "Gets NOC root certificates (RCACs) by VID",
  Args: cobra.ExactArgs(0),
  RunE: func(cmd *cobra.Command, args []string) (err error) {
  clientCtx := client.GetClientContextFromCmd(cmd)

diff --git a/x/pki/client/cli/query_revoked_noc_root_certificates.go b/x/pki/client/cli/query_revoked_noc_root_certificates.go
@@ -15,7 +15,7 @@ import (
 func CmdListRevokedNocRootCertificates() *cobra.Command {
  cmd := &cobra.Command{
  Use: "all-revoked-noc-x509-root-certs",
- Short: "Gets all revoked noc root certificates",
+ Short: "Gets all revoked noc root certificates (RCACs)",
  RunE: func(cmd *cobra.Command, args []string) error {
  clientCtx := client.GetClientContextFromCmd(cmd)
 
@@ -56,7 +56,7 @@ func CmdShowRevokedNocRootCertificates() *cobra.Command {
 
  cmd := &cobra.Command{
  Use: "revoked-noc-x509-root-cert",
- Short: "Gets revoked noc root certificates " +
+ Short: "Gets revoked noc root certificates (RCACs)" +
  "by the given combination of subject and subject-key-id",
  Args: cobra.ExactArgs(0),
  RunE: func(cmd *cobra.Command, args []string) (err error) {

diff --git a/x/pki/client/cli/tx_add_noc_x_509_cert.go b/x/pki/client/cli/tx_add_noc_x_509_cert.go
@@ -22,7 +22,7 @@ func CmdAddNocX509IcaCert() *cobra.Command {
  )
  cmd := &cobra.Command{
  Use: "add-noc-x509-ica-cert",
- Short: "Adds NOC non-root certificate",
+ Short: "Adds NOC non-root certificate (ICAC)",
  Args: cobra.ExactArgs(0),
  RunE: func(cmd *cobra.Command, args []string) (err error) {
  clientCtx, err := client.GetClientTxContext(cmd)

diff --git a/x/pki/client/cli/tx_add_noc_x_509_root_cert.go b/x/pki/client/cli/tx_add_noc_x_509_root_cert.go
@@ -21,7 +21,7 @@ func CmdAddNocX509RootCert() *cobra.Command {
  )
  cmd := &cobra.Command{
  Use: "add-noc-x509-root-cert",
- Short: "Adds NOC root certificate",
+ Short: "Adds NOC root certificate (RCAC)",
  Args: cobra.ExactArgs(0),
  RunE: func(cmd *cobra.Command, args []string) (err error) {
  clientCtx, err := client.GetClientTxContext(cmd)

diff --git a/x/pki/client/cli/tx_remove_noc_x_509_ica_cert.go b/x/pki/client/cli/tx_remove_noc_x_509_ica_cert.go
@@ -18,7 +18,7 @@ var _ = strconv.Itoa(0)
 func CmdRemoveNocX509IcaCert() *cobra.Command {
  cmd := &cobra.Command{
  Use: "remove-noc-x509-ica-cert",
- Short: "Removes the given NOC ICA intermediate or leaf certificate.",
+ Short: "Removes the given NOC ICA intermediate or leaf certificate (ICAC).",
  Args: cobra.ExactArgs(0),
  RunE: func(cmd *cobra.Command, args []string) (err error) {
  clientCtx, err := client.GetClientTxContext(cmd)

diff --git a/x/pki/client/cli/tx_remove_noc_x_509_root_cert.go b/x/pki/client/cli/tx_remove_noc_x_509_root_cert.go
@@ -18,7 +18,7 @@ var _ = strconv.Itoa(0)
 func CmdRemoveNocX509RootCert() *cobra.Command {
  cmd := &cobra.Command{
  Use: "remove-noc-x509-root-cert",
- Short: "Removes the given NOC root certificate from the ledger.",
+ Short: "Removes the given NOC root certificate (RCAC) from the ledger.",
  Args: cobra.ExactArgs(0),
  RunE: func(cmd *cobra.Command, args []string) (err error) {
  clientCtx, err := client.GetClientTxContext(cmd)

diff --git a/x/pki/client/cli/tx_revoke_noc_root_x_509_cert.go b/x/pki/client/cli/tx_revoke_noc_root_x_509_cert.go
@@ -18,7 +18,7 @@ var _ = strconv.Itoa(0)
 func CmdRevokeNocX509RootCert() *cobra.Command {
  cmd := &cobra.Command{
  Use: "revoke-noc-x509-root-cert",
- Short: "Revokes the given noc root certificate. " +
+ Short: "Revokes the given noc root certificate (RCAC). " +
  "If revoke-child flag is set to true then all the noc certificates in the subtree signed by the revoked " +
  "certificate will be revoked as well.",
  Args: cobra.ExactArgs(0),

diff --git a/x/pki/client/cli/tx_revoke_noc_x_509_cert.go b/x/pki/client/cli/tx_revoke_noc_x_509_cert.go
@@ -18,7 +18,7 @@ var _ = strconv.Itoa(0)
 func CmdRevokeNocX509IcaCert() *cobra.Command {
  cmd := &cobra.Command{
  Use: "revoke-noc-x509-ica-cert",
- Short: "Revokes the given NOC intermediate or leaf certificate. " +
+ Short: "Revokes the given NOC intermediate or leaf certificate (ICAC). " +
  "If revoke-child flag is set to true then all the certificates in the subtree signed by the revoked " +
  "certificate will be revoked as well.",
  Args: cobra.ExactArgs(0),