NIST artifact signing

content/en/docs/private-platform/pmp-registry-sign.md

@@ -0,0 +1,115 @@
+---
+title: "Accessing Artifacts and Verifying the Signature"
+url: /private-mendix-platform/access-artifacts/
+description: "Documents the artifacts signing and verification for the Private Mendix Platform."
+weight: 21
+---
+
+## Introduction
+
+To satisfy various regulatory requirements, all container images, Helm charts and artifacts downloaded from the Private Mendix Platform download portal need to be signed. Private Mendix Platform stores them in the Mendix central OCI (Open Container Initiative) registry (`registry.mendix.com`).
+
+## Getting Access to the Mendix Central OCI Registry
+
+The Mendix central OCI registry uses Personal Access Token (PAT) for authentication, and only approved Private Mendix Platform customers can access it. To create your PAT, perform the following steps:
+
+1. Sign in to [Mendix](https://home.mendix.com/)
+2. Click **User Settings > Developer Settings > Personal Access Token**
+3. Click **New Token**
+4. In the **OCI registry** section, select `mx:registry:access`.
+5. Dependsing on what OCI tools you use, use a command like the following to log in to the registry. 
+
+    Most OCI tools store the credentials in a local `~/.docker/config.json` file. After logging in, you can use all tools without any further logins.
+
+    ```text
+    # docker for images
+    $ docker login -u pat -p ${YOUR_PAT} registry.mendix.com
+
+    # helm for helm charts
+    $ helm [command] --username pat --password ${YOUR_PAT} oci://registry.mendix.com/${HELM_CHART_PATH}:${HELM_CHART_VERSION}
+
+    # oras for any files
+    $ oras login -u pat -p ${YOUR_PAT} registry.mendix.com
+
+    # crane
+    $ crane auth login -u pat -p ${YOUR_PAT} registry.mendix.com
+
+    # cosign for signatature
+    $ cosign login -u pat -p ${YOUR_PAT} registry.mendix.com
+    ```
+
+## Artifacts Signing and Verification
+
+Private Mendix Platform uses cosign to sign OCI container images, Helm charts and any other artifacts stored in the Mendix central registry (`registry.mendix.com`). 
+
+Files stored in the Mendix CDN (`cdn.mendix.com`) are also signed, but with a different cosign subcommand.
+
+### Mendix Central Registry
+
+Private Mendix Platform images, Helm charts, and some other CLI tools are published to central registry in a Gitlab CI pipeline. According to the OCI spec, every artifacts is identified by its sha256 hash (image digest). The image's sha256 digest is based on the image contents and is validated by OCI registries. Uploading an image that does not match its sha256 digest is not possible  - the container registry will reject the upload.
+
+Firstly, a CI job builds a container image and records the resulting image's sha256 digest.
+
+After that, a follow-up signing job uses the following command to sign the image's sha256 digest with a Mendix private signing key:
+
+```text
+cosign sign --key "$COSIGN_PRIVATE_KEY" registry.mendix.com/${IMAGE_PATH}:${IMAGE_TAG}
+
+Any image signed this way can be verified by running below command (${IMAGE_TAG} can be the image’s sha256 digest or tag).
+
+cosign verify --key "$COSIGN_PUBLIC_KEY" registry.mendix.com/${IMAGE_PATH}:${IMAGE_TAG}
+```
+
+To obtain the public signing key, contact the Mendix Support team.
+
+Depending on the type of artifact, you can obtain them through commands such as the following:
+
+```text
+# docker for images
+$ docker pull registry.mendix.com/${IMAGE_PATH}:${IMAGE_TAG}
+
+# helm for helm charts
+$ helm [pull|install|upgrade] oci://registry.mendix.com/${HELM_CHART_PATH} --version ${HELM_CHART_VERSION}
+
+# oras for files
+$ oras pull registry.mendix.com/${PATH}:${TAG}
+
+# crane for all types
+$ crane pull registry.mendix.com/${PATH}:${TAG} ${LOCAL_FILE_NAME}
+```
+
+### CDN Files
+
+Some components, such as the Private Mendix Platform installer, are provided as downloadable packages in the Private Mendix Platform Download Portal. Those files are stored in the Mendix CDN. Any artifacts available on that portal are signed using the following command:
+
+```text
+cosign sign-blob --key "$COSIGN_PRIVATE_KEY" --bundle $FILE.sig https://cdn.mendix.com/$FILE
+```
+
+The `$FILE.sig` file is distributed together with any downloadable files and can be used to verify the signature by using the following command:
+
+```text
+cosign verify-blob --key "$COSIGN_PUBLIC_KEY" --bundle $FILE.sig https://cdn.mendix.com/$FILE
+```
+
+## Known Limitations
+
+* When Private Mendix Platform builds an image of an Mendix app, the image is not signed.
+
+    The build happens within the customer's secure environment. Mendix is only responsible for signing artifacts generated by Mendix.
+
+* The following artifacts downloaded from Private Mendix Platform are not signed through cosign:
+
+    * Studio Pro - This is signed through standard desktop software signing (that is, the standard signing process for Microsoft or Apple).
+    * Studio Pro patch files
+    * mxpc-cli
+
+* For bundles from the Private Mendix Platform download portal, the customer selects the components from the Private Mendix Platform download portal, and creates a new bundle. The bundle is created dynamically and is not signed when downloaded.
+
+## Read More
+
+* [Docker](https://www.docker.com/)
+* [Helm](https://helm.sh/)
+* [oras](https://github.com/oras-project/oras)
+* [crane](https://github.com/google/go-containerregistry)
+* [cosign](https://github.com/sigstore/cosign)