Merge pull request #61 from anima-wg/clarify-what-is-merging

change abstract and instroduction to explain merging better

draft-ietf-anima-rfc8366bis.md

@@ -112,27 +112,27 @@ informative:
 --- abstract
 
 
-This document defines a strategy to securely assign a pledge to an owner
-using an artifact signed, directly or indirectly, by the pledge's manufacturer.
+This document defines a strategy to securely assign a Pledge to an owner
+using an artifact signed, directly or indirectly, by the Pledge's manufacturer.
 This artifact is known as a "voucher".
 
 This document defines an artifact format as a YANG-defined JSON or CBOR document
 that has been signed using a variety of cryptographic systems.
 
 The voucher artifact is normally generated by
-the pledge's manufacturer (i.e., the Manufacturer Authorized Signing
+the Pledge's manufacturer (i.e., the Manufacturer Authorized Signing
 Authority (MASA)).
 
-This document updates RFC8366, merging a number of extensions into the YANG.
-The RFC8995 voucher request is also merged into this document.
+This document updates RFC8366, includes a number of desired extensions into the YANG.
+The voucher request defined in RFC8995 is also now included in this document, as well as other YANG extensions needed for variants of BRSKI/RFC8995.
 
 --- middle
 
 # Introduction {#introduction}
 
 This document defines a strategy to securely assign a candidate device
-(pledge) to an owner using an artifact signed, directly or indirectly,
-by the pledge's manufacturer, i.e., the Manufacturer Authorized
+(Pledge) to an owner using an artifact signed, directly or indirectly,
+by the Pledge's manufacturer, i.e., the Manufacturer Authorized
 Signing Authority (MASA).  This artifact is known as the "voucher".
 
 The voucher artifact is a JSON {{RFC8259}} document that
@@ -141,22 +141,27 @@ It may also be serialized to CBOR {{CBOR}}.
 It is encoded using the rules defined in {{!RFC7951}}, and
 is signed using (by default) a CMS structure {{RFC5652}}.
 
-The primary purpose of a voucher is to securely convey a
-certificate, the "pinned-domain-cert" (and constrained variations), that a pledge can
-use to authenticate subsequent interactions.
+The primary purpose of a voucher is to securely convey a trust anchor
+that a Pledge can use to authenticate subsequent interactions.
+The trust anchor may be in the form of a certificate, the "pinned-domain-cert", a hash of a certificate, or it might be a raw public key (in constrained variations).
 A voucher may be useful in several contexts, but the driving motivation
 herein is to support secure onboarding mechanisms.
-Assigning ownership is important to device onboarding mechanisms so that the pledge
-can authenticate the network that is trying to take control of it.
+Assigning ownership is important to device onboarding mechanisms so that the Pledge
+can authenticate the network that will control it.
 
-The lifetimes of vouchers may vary. In some onboarding protocols,
-the vouchers may include a nonce restricting them to a single use,
-whereas the vouchers in other onboarding protocols may have an
+{{RFC8366}} originally defined just the voucher artifact, leaving the Voucher Request artifiact that is important to BRSKI to be defined in {{BRSKI}}.
+This document includes both Voucher and Voucher-Request, and therefore updates {{BRSKI}}.
+
+YANG is not easily extended except by updating the YANG definition.
+Since {{RFC8366}} was written, the pattern is to publish YANG modules as two documents: one with only the YANG module, and the other one with usage, motivation and further explanation.
+This allows the YANG module to be updated without replacing all of the context.
+This document does not follow that pattern, but future updates are may update only the YANG.
+
+The lifetimes of vouchers may vary.
+In some onboarding protocols, the vouchers may include a nonce restricting them to a single use,  whereas the vouchers in other onboarding protocols may have an
 indicated lifetime.
 In order to support long lifetimes, this document recommends using short lifetimes with programmatic renewal, see {{renewal-over-revocation}}.
 
-This document only defines the voucher artifact, leaving it to other
-documents to describe specialized protocols for accessing it.
 Some onboarding protocols using the voucher artifact defined in
 this document include: {{ZERO-TOUCH}}, {{SECUREJOIN}}, and {{BRSKI}}.
 
@@ -169,14 +174,14 @@ This document uses the following terms:
   of a signed structure.
 
 Bootstrapping:
-: The process where a pledge component obtains cryptographic key material to identify
+: The process where a Pledge component obtains cryptographic key material to identify
    and trust future interactions within a specific domain network. Based on imprinted
    key material provided during manufacturing process (see imprinting).
 
 Domain:
 : The set of entities or infrastructure under common administrative
   control.
-  The goal of the onboarding protocol is to enable a pledge component to
+  The goal of the onboarding protocol is to enable a Pledge component to
   join a domain and obtain domain specific security credentials.
 
 Imprint:
@@ -201,7 +206,7 @@ Join Registrar (and Coordinator):
 
 MASA (Manufacturer Authorized Signing Authority):
 : The entity that, for the purpose of this document, issues and signs the
-  vouchers for a manufacturer's pledges.
+  vouchers for a manufacturer's Pledges.
   In some onboarding protocols, the MASA may have an Internet
   presence and be integral to the onboarding process, whereas in
   other protocols the MASA may be an offline service that has no
@@ -211,7 +216,7 @@ malicious registrar:
 : An on-path active attacker that presents itself as a legitimate registrar, but which is in fact under the control of an attacker.
 
 Onboarding:
-: Onboarding describes the process to provide necessary operational data to pledge
+: Onboarding describes the process to provide necessary operational data to Pledge
   components and completes the process to bring a device into an operational state.
   This data may be configuration data, or also application specific cryptographic
   key material (application speciifc security credentials).
@@ -230,14 +235,14 @@ Registrar:
 : See join registrar.
 
 TOFU (Trust on First Use):
-: Where a pledge component makes no security decisions but rather simply
+: Where a Pledge component makes no security decisions but rather simply
   trusts the first domain entity it is contacted by.
   Used similarly to {{RFC7435}}.
   This is also known as the "resurrecting duckling" model.
 
 Voucher:
 : A short form for Voucher Artifact.  It refers to the signed statement
-  from the MASA service that indicates to a pledge
+  from the MASA service that indicates to a Pledge
   the cryptographic identity of the domain it should trust.
   When clarity is needed, it may be preceeded by the type of the signature, such as CMS, JWS or COSE.
 
@@ -261,27 +266,27 @@ Registrar Voucher Request (RVR):
 
 # Survey of Voucher Types
 
-A voucher is a cryptographically protected statement to the pledge
+A voucher is a cryptographically protected statement to the Pledge
 device authorizing a zero-touch "imprint" on the join registrar of the
 domain. The specific information a voucher provides is influenced by the
 onboarding use case.
 
 The voucher can impart the following information to
-the join registrar and pledge:
+the join registrar and Pledge:
 
 Assertion Basis:
 : Indicates the method that protects
   the imprint (this is distinct from the voucher signature that
   protects the voucher itself). This might include
   manufacturer-asserted ownership verification, assured
-  logging operations, or reliance on pledge endpoint behavior
+  logging operations, or reliance on Pledge endpoint behavior
   such as secure root of trust
   of measurement. The join registrar might use this information.
   Only some methods are normatively defined in this
   document. Other methods are left for future work.
 
 Authentication of Join Registrar:
-: Indicates how the pledge
+: Indicates how the Pledge
   can authenticate the join registrar.  This document defines
   a mechanism to pin the domain certificate, or a raw public key.
   Pinning a symmetric key, or "CN-ID" or "DNS-ID"
@@ -296,7 +301,7 @@ Anti-Replay Protections:
 A number of onboarding scenarios can be met using differing
 combinations of this information. All scenarios address the primary
 threat of an on-path active attacker (or MiTM) impersonating the registrar.
-This would gain control over the pledge device.
+This would gain control over the Pledge device.
 The following combinations are "types" of vouchers:
 
 |            | Assertion || Registrar ID || Validity |
@@ -313,7 +318,7 @@ Owner ID     |      |   X     | X          |  X            | X   |       |
 Bearer out-of-scope| X|       |   wildcard | wildcard      | optional|opt|
 |==
 
-NOTE: All voucher types include a 'pledge ID serial-number'
+NOTE: All voucher types include a 'Pledge ID serial-number'
       (not shown here for space reasons).
 
 Audit Voucher:
@@ -341,17 +346,17 @@ Ownership Audit Voucher:
   policy decisions and enforcement between the vendor and the owner.
 
 Ownership ID Voucher:
-: Named after inclusion of the pledge's CN-ID or DNS-ID within the
+: Named after inclusion of the Pledge's CN-ID or DNS-ID within the
   voucher. The MASA service mitigates a MiTM registrar by identifying
-  the specific registrar (via WebPKI) authorized to own the pledge.
+  the specific registrar (via WebPKI) authorized to own the Pledge.
 
 Bearer Voucher:
 : A Bearer Voucher is named after the inclusion of a registrar ID
   wildcard. Because the registrar identity is not indicated, this
   voucher type must be treated as a secret and protected from exposure
-  as any 'bearer' of the voucher can claim the pledge
+  as any 'bearer' of the voucher can claim the Pledge
   device. Publishing a nonceless bearer voucher effectively turns the
-  specified pledge into a "TOFU" device with minimal mitigation
+  specified Pledge into a "TOFU" device with minimal mitigation
   against MiTM registrars. Bearer vouchers are out of scope.
 
 # Changes since RFC8366
@@ -388,8 +393,8 @@ There are some difficulties with this approach: this document does not attempt t
 
 Three signature systems have been defined for vouchers and voucher-requests.
 
-{{!cBRSKI}} defines a mechanism that uses COSE {{RFC9052}}, with the voucher data encoded using {{I-D.ietf-core-sid}}.
-However, as the SID processe requires up-to-date YANG, the SID values for this mechanism are presented in this document.
+{{!cBRSKI}} defines a mechanism that uses COSE {{RFC9052}}, with the voucher data encoded using {{?RFC9254}}.
+However, as the SID process requires up-to-date YANG, the SID values for this mechanism are presented in this document.
 
 {{!jBRSKI}} defines a mechanism that uses JSON {{RFC8259}} and {{JWS}}.
 
@@ -414,8 +419,8 @@ The CMS structure MUST contain a 'signerInfo' structure, as
 described in Section 5.1 of {{RFC5652}}, containing the
 signature generated over the content using a private key
 trusted by the recipient.
-Normally, the recipient is the pledge and the signer is the MASA.
-In the Voucher Request, the signer is the pledge, or the Registrar.
+Normally, the recipient is the Pledge and the signer is the MASA.
+In the Voucher Request, the signer is the Pledge, or the Registrar.
 Within this document, the signer is assumed to be the MASA.
 
 Note that Section 5.1 of {{RFC5652}} includes a
@@ -425,8 +430,8 @@ Bootstrapping Remote Secure Key Infrastructures {{BRSKI}} registrar)
 that might need to evaluate the voucher in flight MUST be prepared for
 such an older format.
 No signaling is necessary, as the manufacturer knows the capabilities
-of the pledge and will use an appropriate format voucher for each
-pledge.
+of the Pledge and will use an appropriate format voucher for each
+Pledge.
 
 The CMS structure SHOULD also contain all of the certificates
 leading up to and including the signer's trust anchor certificate
@@ -438,16 +443,16 @@ The CMS structure MAY also contain revocation objects for any
 intermediate certificate authorities (CAs) between the
 voucher issuer and the trust anchor known to the recipient.
 However, the use of CRLs and other validity mechanisms is
-discouraged, as the pledge is unlikely to be able to perform
+discouraged, as the Pledge is unlikely to be able to perform
 online checks and is unlikely to have a trusted clock source.
 As described below, the use of short-lived vouchers and/or a
-pledge-provided nonce provides a freshness guarantee.
+Pledge-provided nonce provides a freshness guarantee.
 
 # Voucher Artifact {#voucher}
 
-The voucher's primary purpose is to securely assign a pledge to an
+The voucher's primary purpose is to securely assign a Pledge to an
 owner.
-The voucher informs the pledge which entity it should consider to be
+The voucher informs the Pledge which entity it should consider to be
 its owner.
 
 This document defines a voucher that is a JSON-encoded or CBOR-encoded instance of the
@@ -486,7 +491,7 @@ defined in {{RFC8259}}.
 
 The following example illustrates an ephemeral voucher (uses a nonce).
 The MASA generated this voucher using the 'logged' assertion type, knowing
-that it would be suitable for the pledge making the request.
+that it would be suitable for the Pledge making the request.
 
 
 ~~~~
@@ -505,7 +510,7 @@ that it would be suitable for the pledge making the request.
 The following example illustrates a non-ephemeral voucher (no nonce).
 While the voucher itself expires after two weeks, it presumably can
 be renewed for up to a year.   The MASA generated this voucher
-using the 'verified' assertion type, which should satisfy all pledges.
+using the 'verified' assertion type, which should satisfy all Pledges.
 
 
 ~~~~
@@ -607,7 +612,7 @@ The lifetimes of vouchers may vary.  In some onboarding protocols,
 the vouchers may be created and consumed immediately, whereas in other
 onboarding solutions, there may be a significant time delay between
 when a voucher is created and when it is consumed.
-In cases when there is a time delay, there is a need for the pledge
+In cases when there is a time delay, there is a need for the Pledge
 to ensure that the assertions made when the voucher was created are
 still valid.
 
@@ -628,12 +633,12 @@ is for the MASA to instead issue a short-lived voucher, where the
 (reflected in the 'last-renewal-date' field) to reissue the voucher again
 when needed.  Importantly, while issuing the initial voucher may incur
 heavyweight verification checks ("Are you who you say you are?" "Does the
-pledge actually belong to you?"), reissuing the voucher should be a
+Pledge actually belong to you?"), reissuing the voucher should be a
 lightweight process, as it ostensibly only updates the voucher's
 validity period.
 With this approach, there is
 only the one artifact, and only one code path is needed to process
-it; there is no possibility of a pledge choosing to skip the
+it; there is no possibility of a Pledge choosing to skip the
 revocation status check because, for instance, the OCSP Responder is
 not reachable.
 
@@ -642,17 +647,17 @@ voucher artifact does not restrict the ability to create long-lived
 voucher, if required; however, no revocation method is described.
 
 Note that a voucher may be signed by a chain of intermediate CAs
-leading up to the trust anchor certificate known by the pledge.  Even
+leading up to the trust anchor certificate known by the Pledge.  Even
 though the voucher itself is not revocable, it may still be revoked,
 per se, if one of the intermediate CA certificates is revoked.
 
 ## Voucher Per Pledge
 
 The solution described herein originally enabled a single voucher to
-apply to many pledges, using lists of regular expressions to represent
+apply to many Pledges, using lists of regular expressions to represent
 ranges of serial-numbers.  However, it was determined that blocking the
 renewal of a voucher that applied to many devices would be excessive
-when only the ownership for a single pledge needed to be blocked.
+when only the ownership for a single Pledge needed to be blocked.
 Thus, the voucher format now only supports a single serial-number
 to be listed.