Supporting Information

Specification Versioning

The OSCAL REST OPEN API Specification uses Semantic Versioning 2.0, which is summarized on the web site as follows:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Identifying Specification Version in Syntax

Methods for identifying the specification version number as part of the REST API syntax are being considered as part of this issue. Please review the issue and provide feedback on this important topic area.

Consistent with REST API best practices, candidate options include:

• URI Versioning: Including the version as part of the endpoint definition, such as GET {base-url}/1.0.0/catalog/{identifier}
• Header Versioning: Including the version in the HTTP headers.
• Body Versioning: Included in the request itself.

BASE Uniform Resource Locator (URL)

Consistent with REST API principles, the endpoints defined in the specification appended to the end of a base URL, which is defined by the implementation. A base URL may include just a host name, or a combination of host name and path.

The following are examples of valid base URLs:

• https://api.example.gov (Example: The complete syntax to fetch a list of catalogs would be GET https://api.example.gov/catalog)
• https://www.example.gov/api (Example: The complete syntax to fetch a list of catalogs would be GET https://www.example.gov/api/catalog)

Note that if URI Versioning is selected, the examples above would instead be GET https://api.example.gov/1.0.0/catalog and GET https://www.example.gov/api/1.0.0/catalog respectively.

# SECURITY CONSIDERATIONS

TLS 1.3 or Higher

Any server implementation of the API specification should enforce TLS 1.3 or higher for communication with API clients to ensure confidentiality of sensitive security information, as well as to ensure the integrity of all information exchanged. As of January 1, 2024, NIST SP 800-52r2 requires TLS 1.3 for U.S. Federal government systems.

TLS should be implemented using FIPS 140-2 or 140-3 validated cryptographic modules. This is required for U.S. Federal government systems.

Access Control

The implementation must enforce access control based on an asserted identity or access token as described in the OpenAPI Guide's Authentication and Authorization section, and only responds with content to which the asserted identity has access.

For example, if a user only has access to two out of six SSPs within the implementation, the GET /system-security-plan endpoint will only return the two SSP to which the user is granted access. The other SSPs are not included in the list. If the user attempts to directly GET an SSP for which they do not have access, the implementation would return either 401 Unauthorized or 404 Not Found , but would not return the unauthorized content.

NOTE: The decision as to whether this use case would return 401 or 404 is implementation specific. While 401 is the correct response, a common security practice is to return a 404 error so that a malicious user cannot know the difference between content that doesn't exist and content for which the user is not authorized.