Design a set of user stories that address OSCAL document implementation and maintenance issues

[david-waltermire]

User Story:

As an OSCAL developer, I need clear requirements on how to address a number of OSCAL document implementation and maintenance issues. The OSCAL development team needs to collaborate on a generalized solution to the following problems that will work across OSCAL serialization formats:

• How to provide reference integrity for OSCAL documents that reference other OSCAL documents and external documentation? It must be possible to detect when the referenced document has changed. This may also include producing guidance on how to minimize such problems?

• How to identify the organization(s) and individual(s) that have a role in producing, reviewing, and maintaining an OSCAL document? This will inc;lude details on how a 3rd party might contact these parties?

  Some historic work has been done in this area (see Publication Characteristics #196).

• How to differentiate between:

  1. Each unique document (catalog, profile, or implementation) instance irrespective of how it is serialized (e.g., SP 800-53 rev4 updated on X date).?
  2. A given serialization of an OSCAL document (e.g.., SP 800-53 rev4 updated on 9/27/2018 published in JSON)?
  3. Different major revisions of a given publication (e.g., SP 800-53 rev4 vs rev5)?

  Issues Define a version/revision data element for catalogs and profiles #220 and ID conventions for OSCAL document #221 represent prior work in this area.

Goals:

The team will meet to design user stores with sufficient details to support future implementation of solutions to the 3 problems above.

Dependencies:

Describe any previous issues or related work that must be completed to start or complete this issue.

Acceptance Criteria

• New user stories are developed in a way that allows testing and acceptance of implemented solutions to ensure that each problem area is adequately addressed.
• Each developed user story must be standalone and able to be completed in a single 4 week sprint by a single individual.

[iMichaela]

9/26/2018

The team: @david-waltermire-nist @wendellpiez & @brianrufgsa & co will meet on Tu, Oct 2, @ 1:00 - 4:00 PM ET.

[brian-ruf]

SSP Modeling
SSP Sample XML Work

[david-waltermire]

From our Face-2-Face meeting on Tuesday (10/2/2018

---

User Story #1 and #2: Integrity of an OSCAL Document

• Need a user stories for how to sign and OSCAL document using XMLDSig for XML and JSON Web Signatures for JSON.

• See solution A below.

User Story: Ensuring the integrity of a referenced resource

GOAL: There is a need to preserve the underlying information of a reference in a way that ensures consistency in the meaning of any derived information that is linking to the referenced data.

• Assumption in OSCAL that OSCAL documents are linked instances of information and that this information is persistent and stable

  • A profile references a catalog or another profile
  • An implementation document references catalogs, profiles, and other implementation instances
  • Need to identify the specific instance being referenced, and if that has changed (either intentionally or accidentally)
  • Are changes authorized or unauthorized?
  • Is there a way to point to a newer version? Or how to find it?

• A resource can be an OSCAL document or any other externally referenced resource (e.g., a published PDF, an executable, a web page)

• How do we deal with different serializations (e.g., JSON, XML) of the same information?

• see solution A, also refinement 3 below.

User Story: Declaring the authoritative location of an OSCAL document

User Story: Declaring the authoritative location to find the latest revision of an OSCAL document

User Story: Declaring where to find alternative formats for a given OSCAL document

Solution A:

+-------------------+
| Signature of A    |
+-------------+--++ |
| Document A      | |
|            Hash | |   +------------+
| Linked data =========>| Document B |
+-----------------+-+   +------------+

Signature of A allows integrity verification of A.
The reference hash in A allows for integrity verification of the referenced document B.

Solution A-refinement-1:

Dealing with providing a link to the latest.

When https://canonical/location/of/b/v1 is published https://canonical/location/of/latest/b/instance points to it
When https://canonical/location/of/b/v2 is published https://canonical/location/of/latest/b/instance is updated to point to it

Solution A-refinement-2:

Dealing with providing a link to alternate serializations.

When https://canonical/location/of/b/v1 is published https://canonical/location/of/latest/b/instance points to it
When https://canonical/location/of/b/v2 is published https://canonical/location/of/latest/b/instance is updated to point to it

Solution A-refinement-3:

Multiple references to different serializations.

How do we identify if two references are to the same information in different serialization formats?

Solution A-refinement 4:

Determining how a hash was generated.

---

Two problems that need to be addressed:

1. For a given OSCAL artifact, we need to identify the organizations and/or individuals that had a role in producing, reviewing, publishing, and maintaining the artifact.
2. For an SSP, what organizations and/or individuals have a role in owning, operating, and authorizing the described system. These are the named roles in the SSP. Some are required roles required by a given process model, while others are system specific.

Goals:

• Define a generalized mechanism for declaring organizations and individuals. This must include information sufficient to allow for contacting a referenced organization or individual (e.g., address, phone, email).
• For all OSCAL artifacts, provide a means to associate specific organizations and individuals that have a role producing, reviewing, publishing, and maintaining the artifact.
• For specific types of OSCAL artifacts (e.g., system implementations/SSPs, assessment results, etc) provide a means to associate specific organizations and individuals that have a role in that artifact.
  • For system implementations roles include, but are not limited to: owning, operating, and authorizing the described system, Specific implementations may also need to define custom roles.
  • For assessments, the roles will need to identify who is performing the assessment for whom.

(SSP specific)

An example follows:

<artifact-roles>
  <role name="prepared-by" party-ref="BOB">
</artifact-roles>

(SSP specific)

---

800-53 rev4 published on 4/1/2016 in XML

1. OPTIONAL Unique Publication UUID (Same information set A)
2. REQUIRED Unique Instance UUID (content + format)

800-53 rev4 published on 4/1/2016 in JSON

1. Unique Publication UUID (Same information set A)
2. Unique Instance UUID (content + format)

800-53 rev4 published on 4/1/2016 updated on 10/2/2018 in XML

1. Unique Publication UUID (Same information set B)
2. Unique Instance UUID (content + format)

800-53 rev4 published on 4/1/2016 updated on 10/2/2018 in JSON

1. Unique Publication UUID (Same information set B)
2. Unique Instance UUID (content + format)

[wendellpiez]

For reference, NISO STS examples:

IETF RFC 8142 in STS XML
DIN EN ISO 13849-1:2008-12, English version, in STS XML

These are non-normative, as linked from https://www.niso-sts.org/Samples.html

Note in particular the <std-ref> element, as documented here.

[iMichaela]

10/4/2018

A meeting took place. There is good clarity on the first 2 bullets. @david-waltermire-nist will create user stories by the end of this sprint.
The final issue will be further discussed on Oct 9, during the meeting (@brianrufgsa @david-waltermire-nist @wendellpiez @iMichaela

[david-waltermire]

Created issues #245 and #249 for signing of JSON and XML artifacts to provide document-level integrity of OSCAL artifacts. Also created issue #250 which provides for referential integrity.

[david-waltermire]

Created issue #252 to address the documentation of organizational and individual artifact production metadata.

[david-waltermire]

Created issue #254 to address the differentiation of OSCAL artifacts.