Merge pull request #61 from Keyfactor/ab#72700

Ab#72700

Author: spbsoluble

CHANGELOG.md

@@ -1,3 +1,6 @@
+v1.8.1
+- Documentation changes including highlighting lack of HA support as well as a correction to the proper StorePath value for F5-CA-REST stores.
+
 v1.8.0
 - Add new custom field - Remove Chain on Add - to allow the removal of the certificate chain before adding/replacing a certificate on the F5 device.  Default = false.
 - Apply store password when replacing a certificate as well as adding (extension to change made in v1.6.0)

F5Client.cs

@@ -91,7 +91,9 @@ public void AddEntry(string partition, string name, string b64Certificate, strin
         {
             LogHandlerCommon.MethodEntry(logger, CertificateStore, "AddEntry");
             LogHandlerCommon.Trace(logger, CertificateStore, $"Processing certificate for partition '{partition}' and name '{name}'");
+            LogHandlerCommon.Trace(logger, CertificateStore, $"*** CERT CONTENTS: *** {b64Certificate}");
             byte[] entryContents = Convert.FromBase64String(b64Certificate);
+            LogHandlerCommon.Trace(logger, CertificateStore, $"*** AFTER CERT CONTENTS: ***");
             string password = PFXPassword;
             CertificateConverter converter = CertificateConverterFactory.FromDER(entryContents, password);
             X509Certificate2 certificate = converter.ToX509Certificate2(password);

README.md

@@ -31,24 +31,16 @@
 
 ## Overview
 
-The F5 Orchestrator supports three different types of certificates stores with the capabilities for each below:
-
-- CA Bundles
-  - Discovery
-  - Inventory*
-  - Management (Add and Remove)
-- Web Server Device Certificates
-  - Inventory*
-  - Management (Add, but replacement/renewal of existing certificate only) 
-- SSL Certificates
-  - Discovery
-  - Inventory*
-  - Management (Add and Remove)  
-
-*Special note on private keys: One of the pieces of information that Keyfactor collects during an Inventory job is whether or not the certificate stored in F5 has a private key.  The private key is NEVER actually retrieved by Keyfactor, but Keyfactor does track whether one exists.  F5 does not provide an API to determine this, so by convention, all CA Bundle certificates are deemed to not have private keys, while Web Server and SSL certificates are deemed to have them.  Any Management jobs adding (new or renewal) a certificate will renew without the private key for CA Bundle stores and with the private key for Web Server or SSL stores.
+The f5-rest-orchestrator orchestrator extension manages various types of certificates on a F5 Big IP device (version 15 or later).  TLS certificates, CA bundles, and the TLS certificate bound to the administrative website can all be managed with this integration within the scope described in the sections below.  One important note, this integration DOES NOT manage high availability (HA) failover between primary and secondary nodes.  If syncing between primary and secondary nodes is desired, this must either be handled within your F5 Big IP instance itself, or you can set up a Keyfactor Command certificate store for each node (primary and secondary) and manage each separately.
 
 The F5 Universal Orchestrator extension implements 3 Certificate Store Types. Depending on your use case, you may elect to use one, or all of these Certificate Store Types. Descriptions of each are provided below.
 
+- [F5 SSL Profiles REST](#F5-SL-REST)
+
+- [F5 WS Profiles REST](#F5-WS-REST)
+
+- [F5 CA Profiles REST](#F5-CA-REST)
+
 
 ## Compatibility
 
@@ -69,16 +61,18 @@ An administrator account must be set up in F5 to be used with this orchestrator
 
 ## Certificate Store Types
 
-To use the F5 Universal Orchestrator extension, you **must** create the Certificate Store Types required for your usecase. This only needs to happen _once_ per Keyfactor Command instance.
+To use the F5 Universal Orchestrator extension, you **must** create the Certificate Store Types required for your use-case. This only needs to happen _once_ per Keyfactor Command instance.
 
 The F5 Universal Orchestrator extension implements 3 Certificate Store Types. Depending on your use case, you may elect to use one, or all of these Certificate Store Types.
 
 ### F5-SL-REST
 
-
 <details><summary>Click to expand details</summary>
 
 
+The F5-SL-REST certificate store type manages F5 Big IP TLS certificates.  Renewals of bound certificates is supported, but adding new bindings for new or replacement certificates is not.
+
+
 
 
 #### Supported Operations
@@ -94,7 +88,7 @@ The F5 Universal Orchestrator extension implements 3 Certificate Store Types. De
 #### Store Type Creation
 
 ##### Using kfutil:
-`kfutil` is a custom CLI for the Keyfactor Command API and can be used to created certificate store types.
+`kfutil` is a custom CLI for the Keyfactor Command API and can be used to create certificate store types.
 For more information on [kfutil](https://github.com/Keyfactor/kfutil) check out the [docs](https://github.com/Keyfactor/kfutil?tab=readme-ov-file#quickstart)
    <details><summary>Click to expand F5-SL-REST kfutil details</summary>
 
@@ -176,16 +170,17 @@ the Keyfactor Command Portal
 
    ![F5-SL-REST Custom Fields Tab](docsource/images/F5-SL-REST-custom-fields-store-type-dialog.png)
 
-
    </details>
 </details>
 
 ### F5-WS-REST
 
-
 <details><summary>Click to expand details</summary>
 
 
+The F5-WS-REST certificate store type manages the TLS certificate bound to the F5 administration website.  While replacing the existing website certificate is supported, adding a new certificate if one is not already present is not due to F5 limitations.
+
+
 
 
 #### Supported Operations
@@ -201,7 +196,7 @@ the Keyfactor Command Portal
 #### Store Type Creation
 
 ##### Using kfutil:
-`kfutil` is a custom CLI for the Keyfactor Command API and can be used to created certificate store types.
+`kfutil` is a custom CLI for the Keyfactor Command API and can be used to create certificate store types.
 For more information on [kfutil](https://github.com/Keyfactor/kfutil) check out the [docs](https://github.com/Keyfactor/kfutil?tab=readme-ov-file#quickstart)
    <details><summary>Click to expand F5-WS-REST kfutil details</summary>
 
@@ -282,16 +277,17 @@ the Keyfactor Command Portal
 
    ![F5-WS-REST Custom Fields Tab](docsource/images/F5-WS-REST-custom-fields-store-type-dialog.png)
 
-
    </details>
 </details>
 
 ### F5-CA-REST
 
-
 <details><summary>Click to expand details</summary>
 
 
+The F5-CA-REST certificate store type manages F5 Big IP CA certificate bundles.  Only custom CA bundles are supported by this integration.  The default bundle "ca-bundle" under the "Common" partition is **not** supported, as F5's REST API endpoints will not return certificates from this bundle.
+
+
 
 
 #### Supported Operations
@@ -307,7 +303,7 @@ the Keyfactor Command Portal
 #### Store Type Creation
 
 ##### Using kfutil:
-`kfutil` is a custom CLI for the Keyfactor Command API and can be used to created certificate store types.
+`kfutil` is a custom CLI for the Keyfactor Command API and can be used to create certificate store types.
 For more information on [kfutil](https://github.com/Keyfactor/kfutil) check out the [docs](https://github.com/Keyfactor/kfutil?tab=readme-ov-file#quickstart)
    <details><summary>Click to expand F5-CA-REST kfutil details</summary>
 
@@ -388,7 +384,6 @@ the Keyfactor Command Portal
 
    ![F5-CA-REST Custom Fields Tab](docsource/images/F5-CA-REST-custom-fields-store-type-dialog.png)
 
-
    </details>
 </details>
 
@@ -460,12 +455,13 @@ The F5 Universal Orchestrator extension implements 3 Certificate Store Types, ea
 
     Click the Add button to add a new Certificate Store. Use the table below to populate the **Attributes** in the **Add** form.
 
-   | Attribute | Description |
-   | --------- | ----------- |
+   | Attribute | Description                                             |
+   | --------- |---------------------------------------------------------|
    | Category | Select "F5 SSL Profiles REST" or the customized certificate store name from the previous step. |
    | Container | Optional container to associate certificate store with. |
    | Client Machine | The server name or IP Address for the F5 device. |
    | Store Path | Enter the name of the partition on the F5 device you wish to manage. This value is case sensitive, so if the partition name is "Common", it must be entered as "Common" and not "common", |
+   | Store Password | Check "No Password" if you wish the private key of any added certificate to be set to Key Security Type "Normal". Enter a value (either a password or pointer to an installed PAM provider key for the password) to be used to encrypt the private key of any added certificate for Key Security Type of "Password". |
    | Orchestrator | Select an approved orchestrator capable of managing `F5-SL-REST` certificates. Specifically, one with the `F5-SL-REST` capability. |
    | PrimaryNode | Only required (and shown) if Primary Node Online Required is added and selected.  Enter the Host Name of the F5 device that acts as the primary node in a highly available F5 implementation. Please note that this value IS case sensitive. |
    | PrimaryNodeCheckRetryWaitSecs | Enter the number of seconds to wait between attempts to add/replace/renew a certificate if the node is inactive. |
@@ -501,6 +497,7 @@ The F5 Universal Orchestrator extension implements 3 Certificate Store Types, ea
    | Container | Optional container to associate certificate store with. |
    | Client Machine | The server name or IP Address for the F5 device. |
    | Store Path | Enter the name of the partition on the F5 device you wish to manage. This value is case sensitive, so if the partition name is "Common", it must be entered as "Common" and not "common", |
+   | Store Password | Check "No Password" if you wish the private key of any added certificate to be set to Key Security Type "Normal". Enter a value (either a password or pointer to an installed PAM provider key for the password) to be used to encrypt the private key of any added certificate for Key Security Type of "Password". |
    | Orchestrator | Select an approved orchestrator capable of managing `F5-SL-REST` certificates. Specifically, one with the `F5-SL-REST` capability. |
    | Properties.PrimaryNode | Only required (and shown) if Primary Node Online Required is added and selected.  Enter the Host Name of the F5 device that acts as the primary node in a highly available F5 implementation. Please note that this value IS case sensitive. |
    | Properties.PrimaryNodeCheckRetryWaitSecs | Enter the number of seconds to wait between attempts to add/replace/renew a certificate if the node is inactive. |
@@ -531,20 +528,17 @@ If a PAM provider was installed _on the Universal Orchestrator_ in the [Installa
    | --------- | ----------- |
    | ServerUsername | Login credential for the F5 device.  MUST be an Admin account. |
    | ServerPassword | Login password for the F5 device. |
-   | StorePassword | Password to use when reading/writing to store |
+   | StorePassword | Check "No Password" if you wish the private key of any added certificate to be set to Key Security Type "Normal". Enter a value (either a password or pointer to an installed PAM provider key for the password) to be used to encrypt the private key of any added certificate for Key Security Type of "Password". |
 
 Please refer to the **Universal Orchestrator (remote)** usage section ([PAM providers on the Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam)) for your selected PAM provider for instructions on how to load attributes orchestrator-side.
 > Any secret can be rendered by a PAM provider _installed on the Keyfactor Command server_. The above parameters are specific to attributes that can be fetched by an installed PAM provider running on the Universal Orchestrator server itself.
 
 </details>
 
 
-
 > The content in this section can be supplemented by the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store).
 
 
-
-
 </details>
 
 <details><summary>F5 WS Profiles REST (F5-WS-REST)</summary>
@@ -564,8 +558,8 @@ Please refer to the **Universal Orchestrator (remote)** usage section ([PAM prov
 
     Click the Add button to add a new Certificate Store. Use the table below to populate the **Attributes** in the **Add** form.
 
-   | Attribute | Description |
-   | --------- | ----------- |
+   | Attribute | Description                                             |
+   | --------- |---------------------------------------------------------|
    | Category | Select "F5 WS Profiles REST" or the customized certificate store name from the previous step. |
    | Container | Optional container to associate certificate store with. |
    | Client Machine | The server name or IP Address for the F5 device. |
@@ -640,12 +634,9 @@ Please refer to the **Universal Orchestrator (remote)** usage section ([PAM prov
 </details>
 
 
-
 > The content in this section can be supplemented by the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store).
 
 
-
-
 </details>
 
 <details><summary>F5 CA Profiles REST (F5-CA-REST)</summary>
@@ -665,12 +656,12 @@ Please refer to the **Universal Orchestrator (remote)** usage section ([PAM prov
 
     Click the Add button to add a new Certificate Store. Use the table below to populate the **Attributes** in the **Add** form.
 
-   | Attribute | Description |
-   | --------- | ----------- |
+   | Attribute | Description                                             |
+   | --------- |---------------------------------------------------------|
    | Category | Select "F5 CA Profiles REST" or the customized certificate store name from the previous step. |
    | Container | Optional container to associate certificate store with. |
    | Client Machine | The server name or IP Address for the F5 device. |
-   | Store Path | Enter the name of the partition on the F5 device you wish to manage. This value is case sensitive, so if the partition name is "Common", it must be entered as "Common" and not "common", |
+   | Store Path | Enter the name of the partition followed by the name of the bundle separated by a / (i.e. Common/BundleName). This value is case sensitive, so if the partition name is "Common/BundleName", it must be entered as "Common/BundleName" and not "common/bundlename", |
    | Orchestrator | Select an approved orchestrator capable of managing `F5-CA-REST` certificates. Specifically, one with the `F5-CA-REST` capability. |
    | PrimaryNode | Only required (and shown) if Primary Node Online Required is added and selected.  Enter the Host Name of the F5 device that acts as the primary node in a highly available F5 implementation. Please note that this value IS case sensitive. |
    | PrimaryNodeCheckRetryWaitSecs | Enter the number of seconds to wait between attempts to add/replace/renew a certificate if the node is inactive. |
@@ -704,7 +695,7 @@ Please refer to the **Universal Orchestrator (remote)** usage section ([PAM prov
    | Category | Select "F5 CA Profiles REST" or the customized certificate store name from the previous step. |
    | Container | Optional container to associate certificate store with. |
    | Client Machine | The server name or IP Address for the F5 device. |
-   | Store Path | Enter the name of the partition on the F5 device you wish to manage. This value is case sensitive, so if the partition name is "Common", it must be entered as "Common" and not "common", |
+   | Store Path | Enter the name of the partition followed by the name of the bundle separated by a / (i.e. Common/BundleName). This value is case sensitive, so if the partition name is "Common/BundleName", it must be entered as "Common/BundleName" and not "common/bundlename", |
    | Orchestrator | Select an approved orchestrator capable of managing `F5-CA-REST` certificates. Specifically, one with the `F5-CA-REST` capability. |
    | Properties.PrimaryNode | Only required (and shown) if Primary Node Online Required is added and selected.  Enter the Host Name of the F5 device that acts as the primary node in a highly available F5 implementation. Please note that this value IS case sensitive. |
    | Properties.PrimaryNodeCheckRetryWaitSecs | Enter the number of seconds to wait between attempts to add/replace/renew a certificate if the node is inactive. |
@@ -741,12 +732,9 @@ Please refer to the **Universal Orchestrator (remote)** usage section ([PAM prov
 </details>
 
 
-
 > The content in this section can be supplemented by the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store).
 
 
-
-
 </details>
 
 ## Discovering Certificate Stores with the Discovery Job

docsource/content.md

@@ -1,21 +1,6 @@
 ## Overview
 
-The F5 Orchestrator supports three different types of certificates stores with the capabilities for each below:
-
-- CA Bundles
-  - Discovery
-  - Inventory*
-  - Management (Add and Remove)
-- Web Server Device Certificates
-  - Inventory*
-  - Management (Add, but replacement/renewal of existing certificate only) 
-- SSL Certificates
-  - Discovery
-  - Inventory*
-  - Management (Add and Remove)  
-
-*Special note on private keys: One of the pieces of information that Keyfactor collects during an Inventory job is whether or not the certificate stored in F5 has a private key.  The private key is NEVER actually retrieved by Keyfactor, but Keyfactor does track whether one exists.  F5 does not provide an API to determine this, so by convention, all CA Bundle certificates are deemed to not have private keys, while Web Server and SSL certificates are deemed to have them.  Any Management jobs adding (new or renewal) a certificate will renew without the private key for CA Bundle stores and with the private key for Web Server or SSL stores.
-
+The f5-rest-orchestrator orchestrator extension manages various types of certificates on a F5 Big IP device (version 15 or later).  TLS certificates, CA bundles, and the TLS certificate bound to the administrative website can all be managed with this integration within the scope described in the sections below.  One important note, this integration DOES NOT manage high availability (HA) failover between primary and secondary nodes.  If syncing between primary and secondary nodes is desired, this must either be handled within your F5 Big IP instance itself, or you can set up a Keyfactor Command certificate store for each node (primary and secondary) and manage each separately.
 
 ## Requirements
 

docsource/f5-ca-rest.md

@@ -1 +1,3 @@
 ## Overview
+
+The F5-CA-REST certificate store type manages F5 Big IP CA certificate bundles.  Only custom CA bundles are supported by this integration.  The default bundle "ca-bundle" under the "Common" partition is **not** supported, as F5's REST API endpoints will not return certificates from this bundle.

docsource/f5-sl-rest.md

@@ -1 +1,3 @@
 ## Overview
+
+The F5-SL-REST certificate store type manages F5 Big IP TLS certificates.  Renewals of bound certificates is supported, but adding new bindings for new or replacement certificates is not. 

docsource/f5-ws-rest.md

@@ -1 +1,3 @@
 ## Overview
+
+The F5-WS-REST certificate store type manages the TLS certificate bound to the F5 administration website.  While replacing the existing website certificate is supported, adding a new certificate if one is not already present is not due to F5 limitations.