From cf3e2453024fe1b2b6690c44d117867caedc319e Mon Sep 17 00:00:00 2001 From: Tom Proctor Date: Mon, 6 Jun 2022 11:28:48 +0100 Subject: [PATCH] Add upgrade and config docs for MSSQL EKM Provider (#13859) --- .../docs/platform/mssql/configuration.mdx | 28 +++++++++++++ website/content/docs/platform/mssql/index.mdx | 4 +- .../docs/platform/mssql/installation.mdx | 13 +++--- .../docs/platform/mssql/troubleshooting.mdx | 16 ++----- .../content/docs/platform/mssql/upgrading.mdx | 42 +++++++++++++++++++ website/data/docs-nav-data.json | 8 ++++ 6 files changed, 90 insertions(+), 21 deletions(-) create mode 100644 website/content/docs/platform/mssql/configuration.mdx create mode 100644 website/content/docs/platform/mssql/upgrading.mdx diff --git a/website/content/docs/platform/mssql/configuration.mdx b/website/content/docs/platform/mssql/configuration.mdx new file mode 100644 index 000000000..2efd0e271 --- /dev/null +++ b/website/content/docs/platform/mssql/configuration.mdx @@ -0,0 +1,28 @@ +--- +layout: docs +page_title: Configure the Vault EKM Provider +description: Configuration options for the Vault EKM Provider for Microsoft SQL Server. +--- + +# Configuring the Vault EKM Provider + +Configuration is stored in a `config.json` file under ProgramData in a path that +mirrors the installation folder. This defaults to +`C:\ProgramData\HashiCorp\Transit Vault EKM Provider\config.json`. + +-> **Note:** If the Vault EKM Provider has already been installed, Microsoft + SQL Server needs to be restarted for configuration changes to take effect. + +The following options are supported: + +- `vaultApiBaseUrl` `(string: required)` - Address of Vault server, e.g. + `https://vault.example.com:8200` +- `enableTrace` `(bool: false)` - Enable trace logging. Logs are viewable from + the event viewer. See [troubleshooting](/docs/platform/mssql/troubleshooting) + for further details. +- `namespace` `(string: "")` - Set the Vault namespace to use. Applies to both + AppRole and Transit. +- `appRoleMountPath` `(string: "approle")` - Use this to specify the path to the + AppRole auth mount if it was set to a non-default path. +- `transitMountPath` `(string: "transit")` - Use this to specify the path to the + Transit mount if it was set to a non-default path. diff --git a/website/content/docs/platform/mssql/index.mdx b/website/content/docs/platform/mssql/index.mdx index 06c41637f..74a71e4b9 100644 --- a/website/content/docs/platform/mssql/index.mdx +++ b/website/content/docs/platform/mssql/index.mdx @@ -20,8 +20,8 @@ Keys (KEK) managed by Vault's [Transit][transit] secret engine using SQL Server' [transit]: https://www.vaultproject.io/docs/secrets/transit -See [installation](/docs/platform/mssql/installation) for help getting started -with the Vault EKM provider for SQL Server. +See [installation](/docs/platform/mssql/installation) and [configuration](/docs/platform/mssql/configuration) +for help getting started with the Vault EKM provider for SQL Server. ## Features diff --git a/website/content/docs/platform/mssql/installation.mdx b/website/content/docs/platform/mssql/installation.mdx index 85a1c8af9..a2692c60f 100644 --- a/website/content/docs/platform/mssql/installation.mdx +++ b/website/content/docs/platform/mssql/installation.mdx @@ -1,11 +1,14 @@ --- layout: docs -page_title: Install Vault EKM Provider +page_title: Install the Vault EKM Provider description: Installation steps for the Vault EKM Provider for Microsoft SQL Server. --- # Installing the Vault EKM Provider +This guide assumes you are installing the Vault EKM Provider for the first time. +For upgrade instructions, see [upgrading](/docs/platform/mssql/upgrading). + ## Prerequisites * Vault Enterprise server 1.9+ with a license for the Advanced Data Protection Key Management module @@ -31,9 +34,6 @@ The EKM provider requires AppRole auth and the Transit secret engine to be setup on the Vault server. The steps below can be used to configure Vault ready for the EKM provider to use it. --> **Note:** The first release of the Vault EKM provider does not support custom -mount paths or namespaces for the AppRole and Transit engines. - -> **Note:** rsa-2048 is currently the only supported key type. 1. Set up AppRole auth: @@ -95,8 +95,9 @@ The remaining steps are all run on the database server. 1. Download and run the latest Vault EKM provider installer from [releases.hashicorp.com](https://releases.hashicorp.com/vault-mssql-ekm-provider/) - 1. Enter your Vault server's address when prompted and complete the installer +1. If you need to configure non-default namespace or mount paths for your AppRole and + Transit engines, see [configuration](/docs/platform/mssql/configuration). ### Configure the EKM provider using SQL @@ -201,7 +202,7 @@ installation. ```sql SELECT * FROM sys.dm_database_encryption_keys; - SELECT (SELECT name FROM sys.databases WHERE database_id = k.database_id) as name, + SELECT (SELECT name FROM sys.databases WHERE database_id = k.database_id) as name, encryption_state, key_algorithm, key_length, encryptor_type, encryption_state_desc, encryption_scan_state_desc FROM sys.dm_database_encryption_keys k; diff --git a/website/content/docs/platform/mssql/troubleshooting.mdx b/website/content/docs/platform/mssql/troubleshooting.mdx index 8416630a1..7766e7d8d 100644 --- a/website/content/docs/platform/mssql/troubleshooting.mdx +++ b/website/content/docs/platform/mssql/troubleshooting.mdx @@ -1,10 +1,10 @@ --- layout: docs -page_title: Troubleshoot Vault EKM Provider +page_title: Troubleshoot the Vault EKM Provider description: Troubleshooting steps for the Vault EKM Provider for Microsoft SQL Server. --- -# Trobuleshooting the Vault EKM Provider +# Troubleshooting the Vault EKM Provider ## Check Windows Event Logs @@ -14,17 +14,7 @@ Logs from the Vault EKM provider will appear in Windows Event Viewer under ### Enable trace logging If the logs in the Event Viewer don't give enough information to help debug -your issue, you can enable trace logging. Find the provider's config file at -`config.json` in your install location, which defaults to -`C:\Program Files\HashiCorp\Transit Vault EKM Provider\`. Set `enableTrace` to -true, for example: - -```json -{ - "vaultApiBaseUrl": "http://vault.example.com:8200", - "enableTrace": true -} -``` +your issue, you can [enable trace logging](/docs/platform/mssql/configuration#enabletrace). Restart SQL Server for the config change to take effect, and you should see more detailed logs in the same section of Windows Event Viewer. diff --git a/website/content/docs/platform/mssql/upgrading.mdx b/website/content/docs/platform/mssql/upgrading.mdx new file mode 100644 index 000000000..8a083bd7f --- /dev/null +++ b/website/content/docs/platform/mssql/upgrading.mdx @@ -0,0 +1,42 @@ +--- +layout: docs +page_title: Upgrade the Vault EKM Provider +description: Upgrade steps for the Vault EKM Provider for Microsoft SQL Server. +--- + +# Upgrading the Vault EKM Provider + +~> **Note:** The upgrade process will put the database into maintenance mode and + require a restart. It is highly recommended to test this procedure in a + staging environment prior to running it on a production database. + +1. Disable the Vault EKM Provider, and verify it is marked disabled: + + ```sql + ALTER CRYPTOGRAPHIC PROVIDER TransitVaultProvider DISABLE; + SELECT * FROM sys.cryptographic_providers; + ``` + +1. Install the latest version from [releases.hashicorp.com][releases], following + the instructions in the installer. + 1. If you get a "Files in Use" prompt while running the installer, select + "Do not close applications. A reboot will be required", and restart + after the installation has completed. +1. Reload the provider DLL: + + ```sql + ALTER CRYPTOGRAPHIC PROVIDER TransitVaultProvider + FROM FILE = 'C:\Program Files\HashiCorp\Transit Vault EKM Provider\TransitVaultEKM.dll'; + ``` + +1. Now re-enable the Vault EKM Provider and verify it is both marked enabled + and the version reported matches the version of the installer: + + ```sql + ALTER CRYPTOGRAPHIC PROVIDER TransitVaultProvider ENABLE; + SELECT * FROM sys.cryptographic_providers; + ``` + +1. Finally, restart Microsoft SQL Server. + +[releases]: https://releases.hashicorp.com/vault-mssql-ekm-provider/ diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index d5a06681c..95b8ed57e 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1539,6 +1539,14 @@ "title": "Installation", "path": "platform/mssql/installation" }, + { + "title": "Configuration", + "path": "platform/mssql/configuration" + }, + { + "title": "Upgrading", + "path": "platform/mssql/upgrading" + }, { "title": "Troubleshooting", "path": "platform/mssql/troubleshooting"