[WIP] v1.7 - Cryptography WG

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+<!-- 
+Thank you for taking the time to develop and contribute a core enhancement or fix for a defect!
+
+We kindly request that you create pull requests only for things that have been discussed in a ticket first; exceptions may be made for spelling or grammar fixe.
+Read more about the process here: https://cyclonedx.org/participate/standardization-process/#working-model
+
+Please have the related ticket/issue ID ready. 
+If there is none, feel free to create a new ticket: https://github.com/CycloneDX/specification/issues/new/choose
+
+-->
+
+<!-- 
+
+Please provide a brief description of what this pull request intends to do and which ticket it fixes/closes.  
+Example: 
+> As discussed in ticket #485, this PR adds Streebog to the hash algorithm enum.
+>
+> fixes #485 
+
+In case this is for a spelling or grammar improvement, please provide a brief description.
+Example:
+> Fixe typo: color(AE) -> colour(BE)
+
+-->

.github/workflows/build_docs.yml

@@ -59,3 +59,21 @@ jobs:
         name: JSON-Schema-documentation
         path: docgen/json/docs
         if-no-files-found: error
+  docs_proto:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docgen/proto
+    steps:
+    - name: Checkout
+      # see https://github.com/actions/checkout
+      uses: actions/checkout@v4
+    - name: Generate Schema documentation
+      run: ./gen.sh
+    - name: Archive Schema documentation
+      # https://github.com/actions/upload-artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: PROTO-Schema-documentation
+        path: docgen/proto/docs
+        if-no-files-found: error

README.md

@@ -47,14 +47,24 @@ free, open source, and proprietary tools and solutions that support the CycloneD
 The following media types are officially registered with IANA:
 
 | Media Type | Format | Assignment |
-| ------- | --------- | --------- |
-| application/vnd.cyclonedx+xml | XML | [IANA](https://www.iana.org/assignments/media-types/application/vnd.cyclonedx+xml) |
-| application/vnd.cyclonedx+json | JSON | [IANA](https://www.iana.org/assignments/media-types/application/vnd.cyclonedx+json) |
+|------------|--------|------------|
+| `application/vnd.cyclonedx+xml` | XML | [IANA](https://www.iana.org/assignments/media-types/application/vnd.cyclonedx+xml) |
+| `application/vnd.cyclonedx+json` | JSON | [IANA](https://www.iana.org/assignments/media-types/application/vnd.cyclonedx+json) |
+| `application/x.vnd.cyclonedx+protobuf` | Protocol Buffer | |
 
 Specific versions of CycloneDX can be specified by using the version parameter. For example: `application/vnd.cyclonedx+xml; version=1.6`.
 
-The officially supported media type for Protocol Buffer format is `application/x.vnd.cyclonedx+protobuf`.
 
+## Recognized file patterns
+
+The following file names are conventionally used for storing CycloneDX BOM files:
+* `bom.json` for JSON encoded CycloneDX BOM files.
+* `bom.xml` for XML encoded CycloneDX BOM files.
+
+Alternatively, files that match the glob pattern below are also recognized:
+* `*.cdx.json` for JSON encoded CycloneDX BOM files.
+* `*.cdx.xml` for XML encoded CycloneDX BOM files.
+
 
 ## Release History
 

docgen/json/gen.sh

@@ -7,7 +7,7 @@ DOCS_PATH="$THIS_PATH/docs"
 TEMPLATES_PATH="$THIS_PATH/templates"
 
 rm -f -R "$DOCS_PATH"
-mkdir -p "$DOCS_PATH/"{1.2,1.3,1.4,1.5,1.6}
+mkdir -p "$DOCS_PATH/"{1.2,1.3,1.4,1.5,1.6,1.7}
 
 # Check to see if generate-schema-doc is executable and is in the path. If not, install JSON Schema for Humans.
 if ! [ -x "$(command -v generate-schema-doc)" ]
@@ -45,8 +45,9 @@ generate () {
   sed -i -e "s/\${version}/$version/g" "$DOCS_PATH/$version/index.html"
 }
 
-generate 1.2
-generate 1.3
-generate 1.4
-generate 1.5
+generate 1.7
 generate 1.6
+generate 1.5
+generate 1.4
+generate 1.3
+generate 1.2

docgen/json/requirements.txt

@@ -1 +1 @@
-json-schema-for-humans==0.47
+json-schema-for-humans==1.3.4

docgen/json/templates/cyclonedx/base.html

@@ -40,12 +40,14 @@
                     v${version} (JSON)
                 </a>
                 <ul class="dropdown-menu" aria-labelledby="navbarScrollingDropdown">
+                    <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.7/json/">v1.7 (JSON)</a></li>
                     <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.6/json/">v1.6 (JSON)</a></li>
                     <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.5/json/">v1.5 (JSON)</a></li>
                     <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.4/json/">v1.4 (JSON)</a></li>
                     <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.3/json/">v1.3 (JSON)</a></li>
                     <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.2/json/">v1.2 (JSON)</a></li>
                     <li><hr class="dropdown-divider"/></li>
+                    <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.7/xml/">v1.7 (XML)</a></li>
                     <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.6/xml/">v1.6 (XML)</a></li>
                     <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.5/xml/">v1.5 (XML)</a></li>
                     <li><a class="dropdown-item" href="https://cyclonedx.org/docs/1.4/xml/">v1.4 (XML)</a></li>

docgen/json/templates/cyclonedx/content.html

@@ -60,17 +60,37 @@
         {%- endif -%}
 
         {# Enum and const #}
-        {%- if schema.kw_enum -%}
+        {%- if schema.kw_enum and schema.kw_meta_enum -%}
+            <div class="enum-value" id="{{ schema.kw_enum.html_id }}">
+                <h4>Must be one of:</h4>
+                <table class="table table-striped table-bordered">
+                    <thead class="thead-dark">
+                        <tr>
+                            <th class="text-nowrap" scope="col">Name</th>
+                            <th scope="col">Description</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                    {%- for enum_choice in schema.kw_enum.array_items -%}
+                        <tr>
+                            <td class="text-nowrap">
+                                <strong>{{ enum_choice.literal | python_to_json }}</strong>
+                            </td>
+                            <td>
+                                {{ (schema.enum_description(enum_choice.literal) | get_description_literal) }}
+                            </td>
+                        </tr>
+                    {%- endfor -%}
+                    </tbody>
+                </table>
+            </div>
+        {%- elif schema.kw_enum -%}
             <div class="enum-value" id="{{ schema.kw_enum.html_id }}">
             <h4>Must be one of:</h4>
             <ul class="list-group">
             {%- for enum_choice in schema.kw_enum.array_items -%}
                 <li class="list-group-item enum-item">
-                    {%- if schema.kw_meta_enum -%}<strong>{%- endif -%}
                     {{ enum_choice.literal | python_to_json }}
-                    {%- if schema.kw_meta_enum -%}</strong>
-                        : {{ (schema.enum_description(enum_choice.literal) | get_description_literal) }}
-                    {%- endif -%}
                 </li>
             {%- endfor -%}
             </ul>

docgen/json/templates/cyclonedx/schema_doc.css

@@ -4,32 +4,39 @@ body {
   margin: 0;
   padding: 0;
 }
+.navbar {
+    height: 90px;
+    padding: 0;
+}
 .navbar-inverse .navbar-nav>.open>a,
 .navbar-inverse .navbar-nav>.open>a:focus,
 .navbar-inverse .navbar-nav>.open>a:hover,
 .navbar-inverse {
-    background-color: #071525;
+    background-image: linear-gradient(269.12deg, rgba(232, 52, 82, 1) 0%, rgba(136, 38, 125, 1) 51.26%, rgba(52, 57, 175, 1) 100%);
 }
 .navbar-brand, .navbar-fixed-top {
-    padding: 0 15px 0 15px;
+    padding: 0 30px 0 30px;
 }
 .navbar-inverse .navbar-nav>li>a {
     color: #ffffff;
 }
 .site-header__logo img {
-    height: 50px;
+    height: 90px;
 }
 .version-selector {
     font-size: 1.2rem
 }
+.table .thead-dark th {
+    background-color: #323550;
+}
 .container {
     margin-right: auto;
     margin-left: auto;
     padding-left: 15px;
     padding-right: 15px;
 }
 .container-fluid {
-    padding: 15px 15px;
+    padding: 30px 30px;
 }
 .site-footer__copyright {
     text-align: center;
@@ -45,7 +52,7 @@ body {
     padding-left: 30px !important;
 }
 h1, h2, h3, h4, h5, h6 {
-    color:  #23527c;
+    color: rgb(52 57 175);
 }
 h1 {
     font-size: 36px;

docgen/proto/.gitignore

@@ -0,0 +1 @@
+/docs/

docgen/proto/gen.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+set -eu
+
+THIS_PATH="$(realpath "$(dirname "$0")")"
+SCHEMA_PATH="$(realpath "$THIS_PATH/../../schema")"
+DOCS_PATH="$THIS_PATH/docs"
+TEMPLATES_PATH="$THIS_PATH/templates"
+
+PROTOC_GEN_DOC_VERSION='1.5.1'
+
+# --
+
+rm -f -R "$DOCS_PATH"
+
+generate () {
+  version="$1"
+  title="CycloneDX v$version Protobuf Reference"
+  echo "Generating: $title"
+
+  OUT_DIR="$DOCS_PATH/$version/proto"
+  OUT_FILE="index.html"
+  mkdir -p "$OUT_DIR"
+
+  ## docs: https://github.com/pseudomuto/protoc-gen-doc
+  docker run --rm \
+    -v "${OUT_DIR}:/out" \
+    -v "${SCHEMA_PATH}:/protos:ro" \
+    -v "${TEMPLATES_PATH}:/templates:ro" \
+    "pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \
+      --doc_opt=/templates/html.tmpl,"$OUT_FILE" \
+      "bom-${version}.proto"
+
+  # fix file permissions
+  docker run --rm \
+    -v "${OUT_DIR}:/out" \
+    --entrypoint chown \
+    "pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \
+    "$(id -u):$(id -g)" -R /out
+
+  sed -i -e "s/\${quotedTitle}/\"$title\"/g" "$OUT_DIR/$OUT_FILE"
+  sed -i -e "s/\${title}/$title/g" "$OUT_DIR/$OUT_FILE"
+  sed -i -e "s/\${version}/$version/g" "$OUT_DIR/$OUT_FILE"
+}
+
+generate 1.7
+generate 1.6
+generate 1.5
+generate 1.4
+generate 1.3