docs: backport

docs/versioned_docs/version-1.2/features/attestation.md

@@ -28,7 +28,7 @@ The Marble uses this certificate to establish a TLS connection with the Coordina
 The Coordinator verifies the Marble's measurements contained in the quote against the manifest and makes sure the Marble's TLS certificate matches the quote.
 If all checks pass, the Marble is admitted into the cluster.
 
-The [Marble's TLS credentials](../features/secrets-management.md#certificates) are generated by the Coordinator and signed with the intermediate certificate.
+The Coordinator now generates new [Marble TLS credentials](../features/secrets-management.md#certificates) and signs them with the intermediate certificate.
 The Coordinator's certificate chain and the freshly generated Marble certificate are then delivered to the Marble.
 
 ![Marble deployment](../_media/marble_deployment.svg)

docs/versioned_docs/version-1.2/features/secrets-management.md

@@ -7,6 +7,7 @@ The generation and the management of cryptographic keys and certificates for Mar
 * [User-defined secrets](#user-defined-secrets)
 
 ## Symmetric keys
+
 MarbleRun allows you to define symmetric keys that are generated by the Coordinator and distributed to your Marbles.
 Such keys can either be shared among Marbles or individually generated for each instance.
 This is useful whenever data needs to leave the protected memory of your enclave, hence, needs to be encrypted. For example, when sharing data between multiple Marbles or storing data on the disk.
@@ -16,6 +17,7 @@ To pass the generated keys to your application, you can use a template placehold
 If you use one key throughout multiple Marbles, care has to be taken to not repeat nonces between Marbles when using shared keys with AES-GCM or similar encryption algorithms.
 
 ## Certificates
+
 Upon launch of a Marble, the Coordinator will generate TLS credentials for each new Marble in the form of a private key and a corresponding X.509 certificate. The certificate is signed with the Coordinator's intermediate CA. These TLS credentials represent [the notion of identity used for authentication in MarbleRun](../features/attestation.md). Marbles can use this certificate to establish secure communication channels with other Marbles and external clients (i.e., users of your app). Clients only need to verify the Coordinator's root CA once before they can securely communicate with any Marble, as is described in more detail in our [verification hands-on](../workflows/verification.md). By default, they're available to your application via the environment variables `MARBLE_PREDEFINED_MARBLE_CERTIFICATE_CHAIN` and `MARBLE_PREDEFINED_PRIVATE_KEY`. In addition, you can expose them via custom environment variables or files by defining template placeholders such as `{{ pem .MarbleRun.MarbleCert.Cert }}` or `{{ pem .MarbleRun.MarbleCert.Private }}` in the manifest.
 
 Next to the default credentials, you can use `Secrets` to define custom certificates in your manifest. These are also generated upon each launch of your Marble and signed by the Coordinator's intermediate CA. You can include them into environment variables or files via placeholders such as `{{ pem .Secrets.MySecretCertificate }}` in your manifest.

docs/versioned_docs/version-1.2/workflows/add-service.md

@@ -5,6 +5,7 @@ Adding a service to your application requires three steps, which are described i
 ## **Step 1:** Get your service ready for MarbleRun
 
 To get your service ready for MarbleRun, you need to rebuild it with one of the supported [runtimes](../features/runtimes.md):
+
 * [EGo](../building-marbles/ego.md)
 * [Edgeless RT](https://github.com/edgelesssys/marblerun/blob/master/samples/helloc%2B%2B)
 * [Gramine](../building-marbles/gramine.md)
@@ -29,6 +30,7 @@ Now that your service is ready, you need to make two types of entries in the man
 As is described in more detail in the [writing a manifest hands-on](../workflows/define-manifest.md#packages), the manifest contains a section `Packages`, in which allowed enclave software packages are defined.
 
 #### EGo / EdgelessRT
+
 To add an entry for your EGo / EdgelessRT service, run the `oesign` tool on the enclave file you built in the previous step as follows. (`oesign` is installed with [Edgeless RT](https://github.com/edgelesssys/edgelessrt).)
 
 ```bash
@@ -50,7 +52,6 @@ The tool's output is similar to the following.
 
 To add an entry for your Gramine service, run the `gramine-sgx-get-token` tool on the `.sig` file you built in the previous step as follows. (`gramine-sgx-get-token` is installed with [Gramine](https://github.com/gramineproject/gramine/).)
 
-
 ```bash
 gramine-sgx-get-token --sig hello.sig
 ```
@@ -91,7 +92,6 @@ ProductID (ISVPRODID)     : 1
 SecurityVersion (ISVSVN)  : 3
 ```
 
-
 Use `UniqueID` (i.e., `MRENCLAVE` in Intel SGX speak) or the triplet of `SignerID` (i.e., `MRSIGNER`), `SecurityVersion`, and `ProductID` to add an entry in the `Packages` section.
 
 ### **Step 2.2:** Define the parameters

docs/versioned_docs/version-1.2/workflows/define-manifest.md

@@ -332,7 +332,7 @@ When verifying certificates in this context, MarbleRun ignores their `issuer`, `
 Use OpenSSL to generate a compatible certificate.
 
 ```bash
-openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout admin_private.key -out admin_certificate.crt
+openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout admin_private.key -out admin_certificate.pem
 ```
 
 Use the following command to preserve newlines correctly:
@@ -415,6 +415,12 @@ The optional entry `RecoveryKeys` holds PEM-encoded RSA public keys that can be
 }
 ```
 
+:::note
+
+Setting multiple recovery keys enables [multi-party recovery](../features/recovery.md#multi-party-recovery): all parties must [perform the recovery steps](recover-coordinator.md#multi-party-recovery) to recover the Coordinator.
+
+:::
+
 You can generate this key with OpenSSL:
 
 ```bash

docs/versioned_docs/version-1.2/workflows/update-manifest.md

@@ -9,6 +9,7 @@ Updates play an important role in ensuring your software stays secure. To avoid
 To deploy an update, your user needs to have a [role assigned that contains the `UpdateSecurityVersion` action](define-manifest.md#roles).
 
 ### Defining an update manifest
+
 The update manifest format follows the original manifest's syntax, but it only contains packages with new `SecurityVersion` values.
 
 For example, the current `Packages` section of your original manifest looks like this:
@@ -173,4 +174,5 @@ Assume the following `Users` and `Roles` were defined in the manifest:
     ```
 
 ## Effects of an update
+
 When a manifest has been updated, the Coordinator will generate new certificates which your Marbles will receive upon the next startup. Also, if you are trying to launch Marbles based on packages containing the old `SecurityVersion`, they will refuse to run (unless you are running in SGX Simulation or non-Enclave mode). However, so far currently running Marbles will continue to run and will be able to authenticate each other, as long as they're still running. So if you need to enforce an update, make sure to kill the Marbles on your host and restart them.

docs/versioned_docs/version-1.3/features/attestation.md

@@ -28,7 +28,7 @@ The Marble uses this certificate to establish a TLS connection with the Coordina
 The Coordinator verifies the Marble's measurements contained in the quote against the manifest and makes sure the Marble's TLS certificate matches the quote.
 If all checks pass, the Marble is admitted into the cluster.
 
-The [Marble's TLS credentials](../features/secrets-management.md#certificates) are generated by the Coordinator and signed with the intermediate certificate.
+The Coordinator now generates new [Marble TLS credentials](../features/secrets-management.md#certificates) and signs them with the intermediate certificate.
 The Coordinator's certificate chain and the freshly generated Marble certificate are then delivered to the Marble.
 
 ![Marble deployment](../_media/marble_deployment.svg)

docs/versioned_docs/version-1.3/features/secrets-management.md

@@ -7,6 +7,7 @@ The generation and the management of cryptographic keys and certificates for Mar
 * [User-defined secrets](#user-defined-secrets)
 
 ## Symmetric keys
+
 MarbleRun allows you to define symmetric keys that are generated by the Coordinator and distributed to your Marbles.
 Such keys can either be shared among Marbles or individually generated for each instance.
 This is useful whenever data needs to leave the protected memory of your enclave, hence, needs to be encrypted. For example, when sharing data between multiple Marbles or storing data on the disk.
@@ -16,6 +17,7 @@ To pass the generated keys to your application, you can use a template placehold
 If you use one key throughout multiple Marbles, care has to be taken to not repeat nonces between Marbles when using shared keys with AES-GCM or similar encryption algorithms.
 
 ## Certificates
+
 Upon launch of a Marble, the Coordinator will generate TLS credentials for each new Marble in the form of a private key and a corresponding X.509 certificate. The certificate is signed with the Coordinator's intermediate CA. These TLS credentials represent [the notion of identity used for authentication in MarbleRun](../features/attestation.md). Marbles can use this certificate to establish secure communication channels with other Marbles and external clients (i.e., users of your app). Clients only need to verify the Coordinator's root CA once before they can securely communicate with any Marble, as is described in more detail in our [verification hands-on](../workflows/verification.md). By default, they're available to your application via the environment variables `MARBLE_PREDEFINED_MARBLE_CERTIFICATE_CHAIN` and `MARBLE_PREDEFINED_PRIVATE_KEY`. In addition, you can expose them via custom environment variables or files by defining template placeholders such as `{{ pem .MarbleRun.MarbleCert.Cert }}` or `{{ pem .MarbleRun.MarbleCert.Private }}` in the manifest.
 
 Next to the default credentials, you can use `Secrets` to define custom certificates in your manifest. These are also generated upon each launch of your Marble and signed by the Coordinator's intermediate CA. You can include them into environment variables or files via placeholders such as `{{ pem .Secrets.MySecretCertificate }}` in your manifest.

docs/versioned_docs/version-1.3/workflows/add-service.md

@@ -5,6 +5,7 @@ Adding a service to your application requires three steps, which are described i
 ## **Step 1:** Get your service ready for MarbleRun
 
 To get your service ready for MarbleRun, you need to rebuild it with one of the supported [runtimes](../features/runtimes.md):
+
 * [EGo](../building-marbles/ego.md)
 * [Edgeless RT](https://github.com/edgelesssys/marblerun/blob/master/samples/helloc%2B%2B)
 * [Gramine](../building-marbles/gramine.md)
@@ -29,6 +30,7 @@ Now that your service is ready, you need to make two types of entries in the man
 As is described in more detail in the [writing a manifest hands-on](../workflows/define-manifest.md#packages), the manifest contains a section `Packages`, in which allowed enclave software packages are defined.
 
 #### EGo / EdgelessRT
+
 To add an entry for your EGo / EdgelessRT service, run the `oesign` tool on the enclave file you built in the previous step as follows. (`oesign` is installed with [Edgeless RT](https://github.com/edgelesssys/edgelessrt).)
 
 ```bash
@@ -50,7 +52,6 @@ The tool's output is similar to the following.
 
 To add an entry for your Gramine service, run the `gramine-sgx-get-token` tool on the `.sig` file you built in the previous step as follows. (`gramine-sgx-get-token` is installed with [Gramine](https://github.com/gramineproject/gramine/).)
 
-
 ```bash
 gramine-sgx-get-token --sig hello.sig
 ```
@@ -91,7 +92,6 @@ ProductID (ISVPRODID)     : 1
 SecurityVersion (ISVSVN)  : 3
 ```
 
-
 Use `UniqueID` (i.e., `MRENCLAVE` in Intel SGX speak) or the triplet of `SignerID` (i.e., `MRSIGNER`), `SecurityVersion`, and `ProductID` to add an entry in the `Packages` section.
 
 ### **Step 2.2:** Define the parameters

docs/versioned_docs/version-1.3/workflows/define-manifest.md

@@ -332,7 +332,7 @@ When verifying certificates in this context, MarbleRun ignores their `issuer`, `
 Use OpenSSL to generate a compatible certificate.
 
 ```bash
-openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout admin_private.key -out admin_certificate.crt
+openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout admin_private.key -out admin_certificate.pem
 ```
 
 Use the following command to preserve newlines correctly:
@@ -415,6 +415,12 @@ The optional entry `RecoveryKeys` holds PEM-encoded RSA public keys that can be
 }
 ```
 
+:::note
+
+Setting multiple recovery keys enables [multi-party recovery](../features/recovery.md#multi-party-recovery): all parties must [perform the recovery steps](recover-coordinator.md#multi-party-recovery) to recover the Coordinator.
+
+:::
+
 You can generate this key with OpenSSL:
 
 ```bash

docs/versioned_docs/version-1.3/workflows/update-manifest.md

@@ -9,6 +9,7 @@ Updates play an important role in ensuring your software stays secure. To avoid
 To deploy an update, your user needs to have a [role assigned that contains the `UpdateSecurityVersion` action](define-manifest.md#roles).
 
 ### Defining an update manifest
+
 The update manifest format follows the original manifest's syntax, but it only contains packages with new `SecurityVersion` values.
 
 For example, the current `Packages` section of your original manifest looks like this:
@@ -173,4 +174,5 @@ Assume the following `Users` and `Roles` were defined in the manifest:
     ```
 
 ## Effects of an update
+
 When a manifest has been updated, the Coordinator will generate new certificates which your Marbles will receive upon the next startup. Also, if you are trying to launch Marbles based on packages containing the old `SecurityVersion`, they will refuse to run (unless you are running in SGX Simulation or non-Enclave mode). However, so far currently running Marbles will continue to run and will be able to authenticate each other, as long as they're still running. So if you need to enforce an update, make sure to kill the Marbles on your host and restart them.

docs/versioned_docs/version-1.4/features/attestation.md

@@ -28,7 +28,7 @@ The Marble uses this certificate to establish a TLS connection with the Coordina
 The Coordinator verifies the Marble's measurements contained in the quote against the manifest and makes sure the Marble's TLS certificate matches the quote.
 If all checks pass, the Marble is admitted into the cluster.
 
-The [Marble's TLS credentials](../features/secrets-management.md#certificates) are generated by the Coordinator and signed with the intermediate certificate.
+The Coordinator now generates new [Marble TLS credentials](../features/secrets-management.md#certificates) and signs them with the intermediate certificate.
 The Coordinator's certificate chain and the freshly generated Marble certificate are then delivered to the Marble.
 
 ![Marble deployment](../_media/marble_deployment.svg)

docs/versioned_docs/version-1.4/features/secrets-management.md

@@ -7,6 +7,7 @@ The generation and the management of cryptographic keys and certificates for Mar
 * [User-defined secrets](#user-defined-secrets)
 
 ## Symmetric keys
+
 MarbleRun allows you to define symmetric keys that are generated by the Coordinator and distributed to your Marbles.
 Such keys can either be shared among Marbles or individually generated for each instance.
 This is useful whenever data needs to leave the protected memory of your enclave, hence, needs to be encrypted. For example, when sharing data between multiple Marbles or storing data on the disk.
@@ -16,6 +17,7 @@ To pass the generated keys to your application, you can use a template placehold
 If you use one key throughout multiple Marbles, care has to be taken to not repeat nonces between Marbles when using shared keys with AES-GCM or similar encryption algorithms.
 
 ## Certificates
+
 Upon launch of a Marble, the Coordinator will generate TLS credentials for each new Marble in the form of a private key and a corresponding X.509 certificate. The certificate is signed with the Coordinator's intermediate CA. These TLS credentials represent [the notion of identity used for authentication in MarbleRun](../features/attestation.md). Marbles can use this certificate to establish secure communication channels with other Marbles and external clients (i.e., users of your app). Clients only need to verify the Coordinator's root CA once before they can securely communicate with any Marble, as is described in more detail in our [verification hands-on](../workflows/verification.md). By default, they're available to your application via the environment variables `MARBLE_PREDEFINED_MARBLE_CERTIFICATE_CHAIN` and `MARBLE_PREDEFINED_PRIVATE_KEY`. In addition, you can expose them via custom environment variables or files by defining template placeholders such as `{{ pem .MarbleRun.MarbleCert.Cert }}` or `{{ pem .MarbleRun.MarbleCert.Private }}` in the manifest.
 
 Next to the default credentials, you can use `Secrets` to define custom certificates in your manifest. These are also generated upon each launch of your Marble and signed by the Coordinator's intermediate CA. You can include them into environment variables or files via placeholders such as `{{ pem .Secrets.MySecretCertificate }}` in your manifest.

docs/versioned_docs/version-1.4/workflows/add-service.md

@@ -5,6 +5,7 @@ Adding a service to your application requires three steps, which are described i
 ## **Step 1:** Get your service ready for MarbleRun
 
 To get your service ready for MarbleRun, you need to rebuild it with one of the supported [runtimes](../features/runtimes.md):
+
 * [EGo](../building-marbles/ego.md)
 * [Edgeless RT](https://github.com/edgelesssys/marblerun/blob/master/samples/helloc%2B%2B)
 * [Gramine](../building-marbles/gramine.md)
@@ -29,6 +30,7 @@ Now that your service is ready, you need to make two types of entries in the man
 As is described in more detail in the [writing a manifest hands-on](../workflows/define-manifest.md#packages), the manifest contains a section `Packages`, in which allowed enclave software packages are defined.
 
 #### EGo / EdgelessRT
+
 To add an entry for your EGo / EdgelessRT service, run the `oesign` tool on the enclave file you built in the previous step as follows. (`oesign` is installed with [Edgeless RT](https://github.com/edgelesssys/edgelessrt).)
 
 ```bash
@@ -50,7 +52,6 @@ The tool's output is similar to the following.
 
 To add an entry for your Gramine service, run the `gramine-sgx-get-token` tool on the `.sig` file you built in the previous step as follows. (`gramine-sgx-get-token` is installed with [Gramine](https://github.com/gramineproject/gramine/).)
 
-
 ```bash
 gramine-sgx-get-token --sig hello.sig
 ```
@@ -91,7 +92,6 @@ ProductID (ISVPRODID)     : 1
 SecurityVersion (ISVSVN)  : 3
 ```
 
-
 Use `UniqueID` (i.e., `MRENCLAVE` in Intel SGX speak) or the triplet of `SignerID` (i.e., `MRSIGNER`), `SecurityVersion`, and `ProductID` to add an entry in the `Packages` section.
 
 ### **Step 2.2:** Define the parameters

docs/versioned_docs/version-1.4/workflows/define-manifest.md

@@ -334,7 +334,7 @@ When verifying certificates in this context, MarbleRun ignores their `issuer`, `
 Use OpenSSL to generate a compatible certificate.
 
 ```bash
-openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout admin_private.key -out admin_certificate.crt
+openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout admin_private.key -out admin_certificate.pem
 ```
 
 Use the following command to preserve newlines correctly:
@@ -417,6 +417,12 @@ The optional entry `RecoveryKeys` holds PEM-encoded RSA public keys that can be
 }
 ```
 
+:::note
+
+Setting multiple recovery keys enables [multi-party recovery](../features/recovery.md#multi-party-recovery): all parties must [perform the recovery steps](recover-coordinator.md#multi-party-recovery) to recover the Coordinator.
+
+:::
+
 You can generate this key with OpenSSL:
 
 ```bash