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

Jump to bottom

Profile Resolution 1.0.2 Updates #1172

Merged
merged 4 commits into from
Mar 17, 2022
Merged

Profile Resolution 1.0.2 Updates #1172

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1b45491
Specification changes, #1141 #1142 #1155
canb227 Mar 14, 2022
80ec218
Documentation updates
canb227 Mar 14, 2022
8e58819
Mapping documentation, UUID RFC reference
canb227 Mar 14, 2022
3919941
Apply suggestions from AJ's review
stephenbanghart Mar 17, 2022
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
Prev Previous commit
Apply suggestions from AJ's review 
Co-authored-by: Alexander Stein <[email protected]>
  • Loading branch information
@stephenbanghart @aj-stein-nist
stephenbanghart and aj-stein-nist committed Mar 17, 2022
commit 39199412647105dcf847796426458242d8d0a304
6 changes: 3 additions & 3 deletions src/metaschema/oscal_profile_metaschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@
<p>The value of the <code>href</code> can be an internet resource, or an internal reference using a fragment e.g. #fragment that points to a <code>back-matter</code>
<code>resource</code> in the same document.</p>
<!-- TODO: Add a link to "within the scope of the containing OSCAL document" to point to documentation of identification scopes" -->
<p>If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references the <code>id</code> value of a <code>resource</code> in the document's <code>back-matter</code>.</p>
<p>If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references the <code>uuid</code> value of a <code>resource</code> in the document's <code>back-matter</code>.</p>
<p>If an internet resource is used, the <code>href</code> value will be an absolute or relative URL pointing to the location of the referenced resource. A relative URL will be resolved relative to the location of the document containing the link.</p>
</remarks>
</define-flag>
Expand Down Expand Up @@ -93,7 +93,7 @@
<model>
<define-assembly name="combine">
<formal-name>Combination rule</formal-name>
<description>A Combine element defines how to combine multiple (competing) versions of the same control</description>
<description>A Combine element defines how to combine multiple (competing) versions of the same control.</description>
<define-flag name="method" as-type="string">
<formal-name>Combination method</formal-name>
<description>How clashing controls should be handled</description>
Expand All @@ -110,7 +110,7 @@
</constraint>
<remarks>
<p>Whenever combining controls from multiple (import) pathways, an issue arises of what to do with clashing invocations (multiple competing versions of a control). </p>
<p>This setting permits a profile designer to apply a rule for the resolution of such cases. In a well-designed profile (ex. one that uses mapping), such collisions would ordinarily be avoided, but this setting can be useful for defining what to do when it occurs.</p>
<p>This setting permits a profile designer to apply a rule for the resolution of such cases. In a well-designed profile (e.g. one that uses mapping), such collisions would ordinarily be avoided, but this setting can be useful for defining what to do when it occurs.</p>
<p>If no <code>combine</code> element appears, it is considered equivalent to providing a <code>combine</code> element with a <code>method</code> of value <q>keep</q>. </p>
</remarks>
</define-assembly>
Expand Down
8 changes: 4 additions & 4 deletions src/specifications/profile-resolution/profile-resolution-specml.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -289,14 +289,14 @@ profile:
<section id="internalref">
<head>Internal References</head>
<p>URI Fragments in OSCAL represent internal references to other OSCAL objects in the same document. These references follow the pattern of <code>#{{objectID}}</code>. For example, the URI Fragment <code>#param1</code> is referencing the Parameter with unique ID <code>param1</code>.</p>
<p><req level="must" id="req-internal">In the context of the Import Phase, internal references will only appear as a reference to a profile or catalog that is in the <src>resources</src> section of the source. When tools encounter such a reference, they MUST locate the object in <src>resources</src> with the matching ID value, and resolve the resource.
<p><req level="must" id="req-internal">In the context of the Import Phase, internal references will only appear as a reference to a profile or catalog that is in the <src>resources</src> section of the source. When tools encounter such a reference, they MUST locate the object in <src>resources</src> with the matching UUID value, and resolve the resource.
By OSCAL model requirements, a given <src>resource</src> can have zero to many <src>rlink</src> objects and zero to one <src>base64</src> objects; however, it must have at least one of the two present. Tools can assume that any of these each resolves to the same underlying OSCAL object, although potentially in different serialization formats.
For deterministic resolution of these backmatter OSCAL objects, tools need to adhere to the following requirements:
</req></p>
<ul>
<li><p><req level="may" id="req-internal-resolve1">Tools MAY use any of the <src>rlink</src> or <src>base64</src> objects present in the <src>resource</src>.</req> </p> </li>
<li><p><req level="may" id="req-internal-resolve2">Tools MAY verify that each above objects resolves to the same underlying OSCAL object. If there are OSCAL Model content differences between the resolved obejcts, the tool SHOULD provide a warning. </req></p> </li>
<li><p><req level="must" id="req-internal-resolve3">When a <src>rlink</src> is encountered and is to be resolved, it MUST be resolved by using a HTTP Client request to retrieve a Byte Stream. </req></p> </li>
<li><p><req level="may" id="req-internal-resolve2">Tools MAY verify that each above objects resolves to the same underlying OSCAL object. If there are OSCAL Model content differences between the resolved objects, the tool SHOULD provide a warning. </req></p> </li>
<li><p><req level="must" id="req-internal-resolve3">When a <src>rlink</src> is encountered and is to be resolved, it MUST be resolved by using a HTTP request to retrieve a byte stream. </req></p> </li>
<li><p><req level="must" id="req-internal-resolve4">When a <src>base64</src> is encountered and is to be resolved, it MUST be considered a Byte Stream.</req> </p> </li>
<li><p><req level="must" id="req-internal-resolve5">Regardless of its source, the Byte Stream MUST be decoded based on the algorithm defined in <a href="https://datatracker.ietf.org/doc/html/rfc4648"> Section 4 RFC 4648</a>. </req></p> </li>
</ul>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are wonderful additions, thanks Stephen! One that was discussed in general discussion of this work during the weekly Thursday status meeting was how explicit to be about processing the @media-type of the back-matter resource. Did you, Dave, and Wendell decide it was best to leave this out of the spec?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Providing strict requirements around it may be difficult, but some prose giving recommendations would probably be valuable.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm cool either way, I didn't know it was important to the requirements of the spec around the requirements, explicit or implict, for #1140. Since we will talk this over in the meeting in a few minutes, I am definitely ok with resolving and withdrawing the question.

I know it came up last week around this point: I didn't know what the result of the conversation about it was. I defer to Dave and Wendell about not being explicit.

Expand Down Expand Up @@ -1382,7 +1382,7 @@ control:
<p>The following requirements MUST be followed with regards to the Metadata section of the output catalog:</p>
<ul>
<li>
<p><req level="must" id="req-meta-uuid">The output catalog's metadata MUST have a unique top-level UUID (metadata:uuid). This UUID MAY be generated as seen fit by the tool, as long as it is reasonable to assume it is globally unique. It is RECOMMENDED that tools use a Version 4 UUID as specified in <a href="https://datatracker.ietf.org/doc/html/rfc4122">Section 4 of RFC 4122</a>.
<p><req level="must" id="req-meta-uuid">The output catalog's metadata MUST have a unique top-level UUID (metadata:uuid). This UUID MAY be generated as seen fit by the tool, as long as it is reasonable to assume it is globally unique. It is RECOMMENDED that tools use a Version 4 UUID as specified in <a href="https://datatracker.ietf.org/doc/html/rfc4122">Section 4 of RFC 4122</a>.
</req></p>
</li>
<li>
Expand Down