diff --git a/docs/design/da-pki-revocation-design.md b/docs/design/da-pki-revocation-design.md index ce8eb9594..c7bd674e1 100644 --- a/docs/design/da-pki-revocation-design.md +++ b/docs/design/da-pki-revocation-design.md @@ -2,60 +2,34 @@ ## User Stories -1. Revocation of PAI +1. Revocation of a VID-scoped PAI - A Vendor with DCL write privilege can submit a transaction to publish the location of the CRL distribution point for a PAA associated with the Vendor ID. This information can be updated by the Vendor. + A Vendor with DCL write privilege can submit a transaction to publish the location of the CRL distribution point for a PAA associated with the Vendor ID. This information can be updated or deleted by the Vendor with the same Vendor ID. 2. Revocation of a DAC - A Vendor with DCL write privilege can submit a transaction to publish the location of the CRL distribution point for a PAI associated with the Vendor ID. This information can be updated by the Vendor. + A Vendor with DCL write privilege can submit a transaction to publish the location of the CRL distribution point for a PAI associated with the Vendor ID. This information can be updated or deleted by the Vendor with the same Vendor ID. +3. Revocation of a non-VID-scoped PAI -## Revocation Distribution Point Schema -The schema is the same as in `PR6360`. -However, the validation logic is proposed to be a bit different (see [Validation Logic](#validation-logic) and [Divergence](#divergence-from-pr6360)). - - -| Name | Type | Constraint | Mutable | Conformance | -|:---------------------|:--------|:--------------------|:--------|-------------| -| VendorID | uint16 | all | No | M | -| ProductID | uint16* | all | No | O (desc) | -| IsPAA | bool | all | No | M | -| Label | string | max 64 | No | M | -| CRLSignerCertificate | string | max 2048 | No | M | -| IssuerSubjectKeyID | string | max 64 | No | M | -| DataUrl | string | max 256 | Yes | M | -| DataFileSize | uint64 | desc | Yes | O | -| DataDigest | string | max 128 | Yes | O (desc) | -| DataDigestType | uint32 | all | Yes | O (desc) | -| RevocationType | uint32 | all | No | M | - -*: `PR6360` defines PID as `uint32` which is incorrect. PID must be `uint16` as in other places. - -## Divergence from PR6360 -1. No validation of `DataUrl` content. - If the content is invalid, it can be edited/removed by either owner Vendor or Trustees via Update and Delete commands. - - Such validation requires resolving an external URL, and this is a non-deterministic operation: - some nodes may resolve the URL successfully, but some nodes may not resolve it or be redirected to a different content. - Non-deterministic results of validation may cause a situation that on some nodes the transaction is considered as valid, - and on some nodes as invalid. That will break the consensus protocol and DCL won't be able to process write requests anymore. - An alternative option is to pass the whole content of `DataUrl` to the transaction, but it doesn't make a lot of sense because - 1. the content can be quite big (1 MB) - 2. there will be no guarantee that `DataUrl` actually points to the same content as passed + A Vendor Admin with DCL write privilege can submit a transaction to publish the location of the CRL distribution point for a non-VID scoped PAA. This information can be updated or deleted by any Vendor Admin account. -2. Validation of `CRLSignerCertificate`. If `CRLSignerCertificate` is a PAA, then it must be present on DCL (there must be a PAA on DCL with the same pem value). - If `CRLSignerCertificate` is a PAI, then it must be chained back to a valid PAA present on the ledger. -3. If `IssuerSubjectKeyID` is not equal to the `Subject Key Identifier` of `CRLSignerCertificate`, the transaction is considered invalid and rejected. - -4. If `RevocationType` is 1 (RFC5280 CRL), then `DataFileSize`, `DataDigest`, `DataDigestType` must be empty. - - Otherwise, it may cause confusion. Certificates to be revoked are added to the content of CRL URL without a need to send a transaction to the ledger. - So, someone may look at the DCL entry, see that a file size is specified, then go to the URL, and see that the actual size there is different. - It may cause a question if the data is valid, and why a different file size is in DCL. +## Revocation Distribution Point Schema -5. `ProductID` is expected to be `unit16`, not `unit32` as in other places. +| Name | Type | Constraint | Mutable | Conformance | +|:---------------------|:-------|:--------------------|:--------|-------------| +| VendorID | uint16 | all | No | M | +| ProductID | uint16 | all | No | O (desc) | +| IsPAA | bool | all | No | M | +| Label | string | max 64 | No | M | +| CRLSignerCertificate | string | max 2048 | Yes | M | +| IssuerSubjectKeyID | string | max 64 | No | M | +| DataUrl | string | max 256 | Yes | M | +| DataFileSize | uint64 | desc | Yes | O | +| DataDigest | string | max 128 | Yes | O (desc) | +| DataDigestType | uint32 | all | Yes | O (desc) | +| RevocationType | uint32 | all | No | M | ## A need for Proof-of-possession of `CRLSignerCertificate` key @@ -81,26 +55,30 @@ and DACs (leaf certificates) added to DCL if they are revoked in the CRL identif - Who can send: - - Vendor account - - `vid` field in the transaction (`VendorID`) must be equal to the Vendor account's VID - - `vid` field in the `CRLSignerCertificate` (for vendor-scoped PAAs and PAIs) must be equal to the Vendor account's VID + - Vendor account for VID-scoped `crlSignerCertificate` + - `vid` field in the transaction (`VendorID`) must be equal to the Vendor account's VID + - `vid` field in the `CRLSignerCertificate` must be equal to the Vendor account's VID + - Vendor Admin account for non-VID scoped `crlSignerCertificate` + - `vid` field must be absent in `CRLSignerCertificate` +- Validation of parameters: + - See [Validation](#validation-logic) section for details. - Parameters: - - vid: `uint16` - Vendor ID (positive non-zero) - - pid: `optional(uint16)` - Product ID (positive non-zero) + - vid: `uint16` - Vendor ID (positive non-zero). Must be the same as Vendor account's VID and `vid` field in the VID-scoped `CRLSignerCertificate`. + - pid: `optional(uint16)` - Product ID (positive non-zero). Must be empty if `IsPAA` is true. Must be equal to a `pid` field in `CRLSignerCertificate`. - isPAA: `bool` - True if the revocation information distribution point relates to a PAA - label: `string` - A label to disambiguate multiple revocation information partitions of a particular issuer. - - crlSignerCertificate: `string` - PEM encoded certificate (string or path to file containing data) - - issuerSubjectKeyID: `string` - crlSignerCertificate'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` - - dataUrl: `string` - The URL where to obtain the information in the format indicated by the RevocationType field + - crlSignerCertificate: `string` - The issuer certificate whose revocation information is provided in the distribution point entry, encoded in X.509v3 PEM format. The corresponding CLI parameter can contain either a PEM string or a path to a file containing the data. + - issuerSubjectKeyID: `string` - Uniquely identifies the PAA or PAI for which this revocation distribution point is provided. Must consist of even number of uppercase hexadecimal characters ([0-9A-F]), with no whitespace and no non-hexadecimal characters., e.g: `5A880E6C3653D07FB08971A3F473790930E62BDB`. + - dataUrl: `string` - The URL where to obtain the information in the format indicated by the RevocationType field. Must start with either `http` or `https`. - dataFileSize: `optional(uint64)` - Total size in bytes of the file found at the DataUrl. Must be omitted if RevocationType is 1. - - dataDigest: `optional(string)` - Digest of the entire contents of the associated file downloaded from the DataUrl. Must be omitted if RevocationType is 1. - - dataDigestType: `optional(uint32)` - The type of digest used in the DataDigest field from the list of [1, 7, 8, 10, 11, 12] (IANA Named Information Hash Algorithm Registry). + - dataDigest: `optional(string)` - Digest of the entire contents of the associated file downloaded from the DataUrl. Must be omitted if RevocationType is 1. Must be provided if and only if the `DataFileSize` field is present. + - dataDigestType: `optional(uint32)` - The type of digest used in the DataDigest field from the list of [1, 7, 8, 10, 11, 12] (IANA Named Information Hash Algorithm Registry). Must be provided if and only if the `DataDigest` field is present. - revocationType: `uint32` - The type of file found at the DataUrl for this entry. Supported types: 1 - RFC5280 Certificate Revocation List (CRL). - In State: - `pki/RevocationDistributionPoint/value/` -> list of Revocation Distribution Points - `pki/RevocationDistributionPoint/value///