Merge pull request #2407 from OctopusDeploy/nelson/certificates

Update certificates section and fix broken retention icons

Author: steve-fenton-octopus

dictionary-octopus.txt

@@ -150,6 +150,7 @@ Itoa
 ITSM
 jjones
 jsondecode
+JSSE
 jwks
 keyrings
 keyserver

public/docs/deployments/certificates/certificate-list.png

@@ -3,7 +3,7 @@ layout: src/layouts/Default.astro
 pubDate: 2023-01-01
 modDate: 2024-08-02
 title: Retention policies
-icon: fa-broom
+icon: fa-solid fa-broom
 description: Retention policies allow you to specify the releases, packages and files you want to keep as well as the ones you want cleaned up.
 navOrder: 70
 hideInThisSectionHeader: true

public/docs/deployments/certificates/images/add-certificate.png

@@ -3,7 +3,7 @@ layout: src/layouts/Default.astro
 pubDate: 2023-01-01
 modDate: 2024-08-02
 title: Retention policy Tentacle cleanup and troubleshooting
-icon: fa-bug
+icon: fa-solid fa-bug
 description: Reviewing and troubleshooting why some files aren't cleaned up by Octopus retention policies.
 ---
 

public/docs/deployments/certificates/images/archive-certificate.png

@@ -1,13 +1,14 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2024-08-09
 title: Add a certificate to Octopus
+icon: fa-solid fa-lock
 description: Upload a X.509 certificate to be managed by Octopus Deploy
 navOrder: 10
 ---
 
-To add a certificate to Octopus, navigate to **Library ➜ Certificates ➜ Add Certificate**
+To add a certificate to Octopus, navigate to **Deploy ➜ Certificates ➜ Add Certificate**
 
 :::figure
 ![Add certificate](/docs/deployments/certificates/images/add-certificate.png)
@@ -16,7 +17,8 @@ To add a certificate to Octopus, navigate to **Library ➜ Certificates ➜ Add
 When selecting your certificate file for upload, it must be one of the [supported file-formats](/docs/deployments/certificates).
 
 :::div{.hint}
-**Security Recommendation: Scope your certificates to the appropriate Environments**
+**Security Recommendation: Scope your certificates to the appropriate environments**
+
 If your certificate contains a production private-key, it is strongly recommended to scope your certificate to the appropriate environment.
-This allows you to assign permissions based on Environments, ensuring that only users with appropriate permissions in the scoped Environments will be able to access the private-key.
+This allows you to assign permissions based on environments, ensuring that only users with appropriate permissions in the scoped environments will be able to access the private-key.
 :::

public/docs/deployments/certificates/images/certificate-chain-card.png

@@ -1,8 +1,9 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2024-08-09
 title: Archive and delete certificates
+icon: fa-solid fa-lock
 description: Archiving and Deleting certificates managed by Octopus Deploy
 navOrder: 100
 ---
@@ -15,7 +16,7 @@ Archiving a certificate will prevent it from being selected as the value of a va
 ![](/docs/deployments/certificates/images/archive-certificate.png)
 :::
 
-Archived certificates can be viewed by navigating to **Library ➜ Certificates ➜ View Archive**.
+Archived certificates can be viewed by navigating to **Deploy ➜ Certificates ➜ View Archive**.
 
 When a certificate is [replaced](/docs/deployments/certificates/replace-certificate), it is automatically archived if it is not already.
 
@@ -24,9 +25,9 @@ When a certificate is [replaced](/docs/deployments/certificates/replace-certific
 Once a certificate has been archived, it can then be deleted.  
 
 :::div{.warning}
-This is a hard delete. Once deleted, a certificate and it's private key (if present) cannot be recovered.
+This is a hard delete. Once deleted, a certificate and its private key (if present) cannot be recovered.
 :::
 
 You will be prevented from deleting a certificate if it is the value of one or more variables. You can view a certificates usage on the 'Usage' tab of the certificate details page.
 
-Variables snap-shotted as part of a release will not prevent deleting a certificate. Attempting to deploy a release which references a deleted certificate will result in an error.
+Variables snapshotted as part of a release will not prevent deleting a certificate. Attempting to deploy a release which references a deleted certificate will result in an error.

public/docs/deployments/certificates/images/certificate-chain-details.png

@@ -1,13 +1,14 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2024-08-09
 title: Certificate chains
+icon: fa-solid fa-lock
 description: Manage certificate files containing a chain of certificates
 navOrder: 15
 ---
 
-Uploaded PFX or PEM files may contain a certificate-chain. i.e. A certificate with a private-key, plus one or more authority certificates.
+Uploaded PFX or PEM files may contain a certificate chain. i.e. A certificate with a private-key, plus one or more authority certificates.
 
 Certificates which contain a chain are indicated by a chain icon on the certificate card, as shown below:
 
@@ -23,7 +24,7 @@ The details page will show the details of all certificates in the chain:
 
 ## Importing certificate chains
 
-When a certificate-chain is imported to one of the Windows Certificate Stores (either via the [Import Certificate Step](/docs/deployments/certificates/import-certificate-step) or by using the Certificate in an IIS HTTPS Binding) the authority certificates will be automatically imported into the CA or Root stores (Root if the authority certificate is self-signed, CA otherwise as it is an intermediate authority).   
+When a certificate-chain is imported to one of the Windows Certificate Stores (either via the [Import Certificate Step](/docs/deployments/certificates/import-certificate-step) or by using the certificate in an IIS HTTPS Binding) the authority certificates will be automatically imported into the CA or Root stores (Root if the authority certificate is self-signed, CA otherwise as it is an intermediate authority).   
 
 _Note:_  Authority certificates will always be imported to the LocalMachine location, even if the subject certificate is imported to a user-specific location.
 This is because importing to the Root store for a specific user results in a security-prompt being displayed, which obviously doesn't work with automated deployments.   
@@ -36,8 +37,8 @@ When downloading a certificate containing a chain, the behavior depends on the f
 - `PFX`: The entire chain will be included in the exported file.
 - `DER`: Only the subject certificate will be included.  DER files never contain chains.
 - `PEM`: Download-dialog provides options to include:
-   - Primary Certificate.
-   - Primary and Chain Certificates.
-   - Chain Certificates Only.
+   - Primary Certificate
+   - Primary and Chain Certificates
+   - Chain Certificates Only
 
 ![Download Chain in PEM format dialog](/docs/deployments/certificates/images/download-pem-chain.png)

public/docs/deployments/certificates/images/certificate-variables-scoped.png

@@ -1,20 +1,19 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2024-08-09
 title: Export a certificate
+icon: fa-solid fa-lock
 description: Export a certificate managed by Octopus as a selected file-format
 navOrder: 60
 ---
 
-Certificates can be downloaded from the Octopus Portal to your local machine.  The certificate may be exported in any of the [supported file-formats](/docs/deployments/certificates), or exactly as it was originally uploaded.
+Certificates can be downloaded from Octopus to your local machine.  The certificate may be exported in any of the [supported file-formats](/docs/deployments/certificates), or exactly as it was originally uploaded.
 
 :::figure
 ![](/docs/deployments/certificates/images/download-certificate-btn.png)
 :::
 
-![](/docs/deployments/certificates/images/download-certificate-dialog.png)
-
 ## Private-keys
 
 If the certificate includes a private-key, then user requires the _Export certificate private-keys_ permission to download the certificate in a format which includes the private-key.

public/docs/deployments/certificates/images/download-certificate-btn.png

@@ -1,8 +1,9 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2024-04-23
+modDate: 2024-08-09
 title: Import certificate to Windows certificate store
+icon: fa-solid fa-lock
 description: The Import Certificate deployment step allows you to import a certificate managed by Octopus into one of the Windows Certificate Stores as part of a deployment process
 navOrder: 30
 ---

public/docs/deployments/certificates/images/download-certificate-dialog.png

@@ -1,14 +1,15 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2024-08-09
 title: Certificates
+icon: fa-solid fa-lock
 description: Manage X.509 certificates with Octopus Deploy
 navOrder: 80
 hideInThisSectionHeader: true
 ---
 
-X.509 certificates are a key component of many deployment processes. Octopus Deploy provides the ability to securely store and manage your certificates, and easily use them in your Octopus Projects.  
+X.509 certificates are a key component of many deployment processes. Octopus Deploy provides the ability to securely store and manage your certificates, and easily use them in your Octopus projects.  
 
 ## Supported certificate file formats
 
@@ -31,7 +32,7 @@ The following certificate formats are supported in Octopus Deploy:
 
 ## Configure subscriptions for expiry notifications
 
-[Octopus Subscriptions](/docs/administration/managing-infrastructure/subscriptions) can be used to configure notifications when certificates are close to expiry or have expired.
+[Subscriptions](/docs/administration/managing-infrastructure/subscriptions) can be used to configure notifications when certificates are close to expiry or have expired.
 
 There is a "Certificate expiry events" event-group, and three events:  
 
@@ -78,4 +79,4 @@ Note that certificates can not be selected directly when configuring a deploymen
 
 ## Learn more
 
-- [Lets Encrypt runbook examples](/docs/runbooks/runbook-examples/routine/lets-encrypt-renew-certificate).
+- [Let's Encrypt runbook examples](/docs/runbooks/runbook-examples/routine/lets-encrypt-renew-certificate).

public/docs/deployments/certificates/images/download-pem-chain.png

@@ -3,6 +3,7 @@ layout: src/layouts/Default.astro
 pubDate: 2023-01-01
 modDate: 2023-01-01
 title: Export a certificate to a Java KeyStore
+icon: fa-solid fa-lock
 description: Export a Java KeyStore from a certificate managed by Octopus.
 navOrder: 70
 ---

public/docs/deployments/certificates/images/import-certificate-step-edit.png

@@ -1,8 +1,9 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2024-08-09
 title: Replace a certificate
+icon: fa-solid fa-lock
 description: Replace a certificate managed by Octopus Deploy
 navOrder: 80
 ---
@@ -18,7 +19,3 @@ To replace a certificate, navigate to the certificate details page and click 'Re
 :::figure
 ![](/docs/deployments/certificates/images/replace-certificate-btn.png)
 :::
-
-Select the replacement certificate file and password (if required):
-
-![](/docs/deployments/certificates/images/replace-certificate-dialog.png)

public/docs/deployments/certificates/images/replace-certificate-btn.png

@@ -3,6 +3,7 @@ layout: src/layouts/Default.astro
 pubDate: 2023-01-01
 modDate: 2023-01-01
 title: Import certificates into Tomcat
+icon: fa-solid fa-lock
 description: Configure Tomcat with a certificate managed by Octopus.
 navOrder: 40
 ---
@@ -11,9 +12,9 @@ With the `Deploy a certificate to Tomcat` step, certificates managed by Octopus
 
 ## Prerequisites
 
-Before a certificate can be deployed to a Tomcat instance, the certificate itself must be uploaded to Octopus. [Add a Certificate to Octopus](/docs/deployments/certificates/add-certificate) provides instructions on how to add a new certificate to the Octopus library.
+Before a certificate can be deployed to a Tomcat instance, the certificate itself must be uploaded to Octopus. [Add a certificate to Octopus](/docs/deployments/certificates/add-certificate) provides instructions on how to add a new certificate to the Octopus library.
 
-Once uploaded, the certificate has to be referenced by a variable. [Certificate Variables](/docs/projects/variables/certificate-variables) provides instructions on how to define a certificate variable.
+Once uploaded, the certificate has to be referenced by a variable. [Certificate variables](/docs/projects/variables/certificate-variables) provides instructions on how to define a certificate variable.
 
 ## Deploying a certificate to Tomcat
 

public/docs/deployments/certificates/images/replace-certificate-dialog.png

@@ -1,8 +1,9 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2024-08-09
 title: Troubleshooting invalid certificates
+icon: fa-solid fa-lock
 description: How to troubleshoot invalid certificates that won't load in Octopus Deploy
 navOrder: 110
 ---
@@ -25,9 +26,9 @@ This error implies that the file being uploaded might be an SSH Key and not a va
 
 This error implies that a certificate violates the X.690 spec, section 8.3.2.
 
-If you receive this error when creating a deployment, please review the certificate's variables on the project, and try to view each one in **Library ➜ Certificates**. One of them will either fail to load, or show the message: `Invalid Certificate: This certificate was unable to be parsed and may be in an invalid format`. Please modify any references to use a new, valid certificate, and use the REST API to delete the certificate in question.
+If you receive this error when creating a deployment, please review the certificate's variables on the project, and try to view each one in **Deploy ➜ Certificates**. One of them will either fail to load, or show the message: `Invalid Certificate: This certificate was unable to be parsed and may be in an invalid format`. Please modify any references to use a new, valid certificate, and use the REST API to delete the certificate in question.
 
-This error may also appear on the variables page: `An error occurred on the mapping CertificateResource.CertificateDataFomat = Certificate.CertificateDataFormat [attempted value was (unknown)]: corrupted stream detected malformed integer`. Please review the certificates in  **Library ➜ Certificates** to find the invalid one, update any usages to use a new valid certificate, and delete the old certificate via the REST API.
+This error may also appear on the variables page: `An error occurred on the mapping CertificateResource.CertificateDataFormat = Certificate.CertificateDataFormat [attempted value was (unknown)]: corrupted stream detected malformed integer`. Please review the certificates in  **Deploy ➜ Certificates** to find the invalid one, update any usages to use a new valid certificate, and delete the old certificate via the REST API.
 
 Please see [BC-CSharp issue #156](https://github.com/bcgit/bc-csharp/issues/156) for further information.
 
@@ -41,7 +42,7 @@ This is the same root cause as the message above, however, it includes details a
 
 This can happen when certificates include extension data without specifying the certificate format of v3. If the version is omitted, then v1 is implied. Since only v3 certificates are allowed to have this additional data, this leads to an invalid certificate. Please see [BC-CSharp issue #158](https://github.com/bcgit/bc-csharp/issues/158) for further information.
 
-Please review the certificates in  **Library ➜ Certificates** to find the invalid one, update any usages to use a new valid certificate, and delete the old certificate via the REST API.
+Please review the certificates in  **Deploy ➜ Certificates** to find the invalid one, update any usages to use a new valid certificate, and delete the old certificate via the REST API.
 
 ### `Invalid certificate detected - Unable to parse certificate`
 

src/pages/docs/administration/retention-policies/index.mdx

@@ -3,6 +3,7 @@ layout: src/layouts/Default.astro
 pubDate: 2023-01-01
 modDate: 2024-04-10
 title: Import certificates into WildFly and JBoss EAP
+icon: fa-solid fa-lock
 description: Configure WildFly or JBoss EAP with a certificate managed by Octopus.
 navOrder: 50
 ---
@@ -11,7 +12,7 @@ With the `Configure certificate for WildFly or EAP` step, certificates managed b
 
 ## Prerequisites
 
-If a new KeyStore is to be created as part of the deployment, the certificate being deployed must be referenced by a variable. [Add a Certificate to Octopus](/docs/deployments/certificates/add-certificate/) provides instructions on how to add a new certificate to the Octopus library, and [Certificate Variables](/docs/projects/variables/certificate-variables) provides instructions on how to define a certificate variable.
+If a new KeyStore is to be created as part of the deployment, the certificate being deployed must be referenced by a variable. [Add a certificate to Octopus](/docs/deployments/certificates/add-certificate/) provides instructions on how to add a new certificate to the Octopus library, and [Certificate variables](/docs/projects/variables/certificate-variables) provides instructions on how to define a certificate variable.
 
 ## Common connection settings