Merge pull request #4228 from EnterpriseDB/Tech-Partner-Hashicorp-Tra…

…nsit-Secrets-Engine-Guide

Tech Partner Hashicorp Transit Secrets Engine Guide

advocacy_docs/partner_docs/HashicorpVaultTransitSecretsEngine/02-PartnerInformation.mdx

@@ -0,0 +1,12 @@
+---
+title: 'Partner Information'
+description: 'Details of the partner'
+
+---
+|       |   |
+| ----------- | ----------- |
+| **Partner Name**      |    Hashicorp    |
+| **Web Site**      |   https://www.hashicorp.com/   |
+| **Partner Product**   |   Vault Transit Secrets Engine    |
+| **Version**   |  Vault v1.13.3     |
+| **Product Description**      |  Hashicorp Vault is an identity-based secrets and encryption management system. Used in conjunction with EDB Postgres Advanced Server and EDB Postgres Extended Server, Hashicorp Vault Transit secrets engine allows Vault to handle cryptographic functions on data in-transit.   |

advocacy_docs/partner_docs/HashicorpVaultTransitSecretsEngine/03-SolutionSummary.mdx

@@ -0,0 +1,11 @@
+---
+title: 'Solution Summary'
+description: 'Explanation of the solution and its purpose'
+---
+
+Hashicorp Vault is an identity-based secrets and encryption management system. Used in conjunction with EDB Postgres Advanced Server versions 15.2 and above or EDB Postgres Extended Server versions 15.2 and above, it allows users to control access to encryption keys and certificates, as well as perform key management. Using Hashicorp Vault’s Transit secrets engine allows Vault to handle cryptographic functions on data in-transit.  Hashicorp Vault Transit secrets engine can be referred to as "encryption as a service".
+
+Hashicorp Vault’s primary use case for Transit secrets engine is to encrypt data from applications while simultaneously storing encrypted data in some primary data store. Hashicorp Vault Transit Secrets Engine can also generate hashes, sign and verify data and generate HMACs of data.  Hashicorp Vault Transit Secrets Engine can work with EDB Postgres Advanced Server and EDB Postgres Extended Server by securely storing the data key that is generated by `initdb`.  Normally the key, that lives in `pg_encryption/key.bin`, is stored in plaintext format, but using Hashicorp Vault Transit Secrets Engine as an external key store manages the data encryption key and provides further security to the key itself.
+
+The below image shows how Hashicorp Vault Transit Secrets Engine works to encrypt and decrypt data.
+    ![Hashicorp Vault Transit Secrets Engine Architecture](Images/HashicorpVaultTransitSecretsEngineArchitecture.png)

advocacy_docs/partner_docs/HashicorpVaultTransitSecretsEngine/04-ConfiguringTransitSecretsEngine.mdx

@@ -0,0 +1,61 @@
+---
+title: 'Configuration'
+description: 'Walkthrough on configuring the integration'
+---
+
+Implementing Hashicorp Vault with EDB Postgres Advanced Server version 15.2 and above or EDB Postgres Extended Server version 15.2 and above, requires the following components:
+!!! Note
+    The EDB Postgres Advanced Server version 15.2 and above and EDB Postgres Extended Server version 15.2 and above, products will be referred to as EDB Postgres distribution.  The specific distribution type will be dependent upon customer need or preference.
+
+- EDB Postgres distribution (15.2 or later)
+- Hashicorp Vault v1.13.3
+
+## Prerequisites
+
+- A running EDB Postgres distribution
+- Hashicorp Vault installed and deployed per your VM environment
+
+## Enable Hashicorp Vault Transit Secrets Engine
+
+!!! Note
+    You have to set your environment variable with Hashicorp Vault. If you receive this error message “Get "https://127.0.0.1:8200/v1/sys/seal-status": http: server gave HTTP response to HTTPS client” you need to issue this in your command line `export VAULT_ADDR="http://127.0.0.1:8200`".
+
+1. After your Hashicorp Vault configuration is installed and deployed per the guidelines in the [Hashicorp documentation](https://developer.hashicorp.com/vault/tutorials/getting-started/getting-started-install), you will then need to enable the transit secrets engine.
+
+2. Assume root user.
+
+3. First set your two variables, your API address and token you receieved during installation and setup.
+```bash
+root@ip-172-31-50-151:/home/ubuntu# export VAULT_ADDR='http://127.0.0.1:8200'
+root@ip-172-31-50-151:/home/ubuntu# export VAULT_TOKEN="hvs.D9lfoRBZYtdJY2t3lG3f6yUa"
+```
+4. Before you enable the Transit Secrets Engine you can check your Vault Server status with `vault status`.
+```bash
+root@ip-172-31-50-151:/home/ubuntu# vault status
+Key             Value
+---             -----
+Seal Type       shamir
+Initialized     true
+Sealed          false
+Total Shares    1
+Threshold       1
+Version         1.13.3
+Build Date      2023-06-06T18:12:37Z
+Storage Type    inmem
+Cluster Name    vault-cluster-18a7ed39
+Cluster ID      83012ee7-18f0-9480-e8b6-3ff02c285ba2
+HA Enabled      false
+```
+
+5. Type `vault secrets enable transit`.
+```bash
+root@ip-172-31-50-151:/home/ubuntu# vault secrets enable transit
+Success! Enabled the transit secrets engine at: transit/
+```
+
+6. Next you will create your encryption key with an identifiable name. For example: `vault write -f transit/keys/pg-tde-master-1`
+```bash
+root@ip-172-31-50-151:/usr/lib/edb-pge/15/bin# vault write -f transit/keys/pg-tde-master-1
+Success! Data written to: transit/keys/pg-tde-master-1
+```
+7. You now have your encryption key set and are ready to export your WRAP and UNWRAP commands and initialize your database.

advocacy_docs/partner_docs/HashicorpVaultTransitSecretsEngine/05-UsingTransitSecretsEngine.mdx

@@ -0,0 +1,217 @@
+---
+title: 'Using'
+description: 'Walkthrough of example usage scenarios'
+---
+
+After you have configured Hashicorp Vault Transit Secrets Engine as stated in the Configuring section, you will be able to then encrypt your EDB Postgres distribution database.
+
+!!! Note
+    It is important to note that this doc is intended for versions 15.2 and above of EDB Postgres Advanced Server or versions 15.2 and above of EDB Postgres Extended Server as these versions support Transparent Data Encryption (TDE).
+
+After the Hashicorp Vault Transit secrets engine is configured and a user/machine has a Vault token with the proper permissions, this was configured during your install and setup of Transit Secrets Engine, it can use this secrets engine to encrypt a key.
+
+## Perform initdb for the Database
+
+After you have enabled Hashicorp Vault Transit Secrets Engine and created a key, you will be able to export the PGDATAKEYWRAPCMD and PGDATAKEYUNWRAPCMD to wrap and unwrap your encryption key and initialize your database.
+
+1. Login to your EDB Postgres distribution as the database superuser, for example `sudo su - enterprisedb`.
+
+2. Navigate to the `/bin` directory where your executables live. In our example it is `/usr/lib/edb-as/15/bin`.
+
+3. Type: `export PGDATAKEYWRAPCMD='base64 | vault write -field=ciphertext transit/encrypt/pg-tde-master-1 plaintext=- > %p'`
+
+4. Type: `export PGDATAKEYUNWRAPCMD='cat %p | vault write -field=plaintext transit/decrypt/pg-tde-master-1 ciphertext=- | base64 --decode'`
+
+```bash
+root@ip-172-31-50-151:/usr/lib/edb-pge/15/bin# su - enterprisedb
+
+enterprisedb@ip-172-31-50-151:~$ export PGDATAKEYWRAPCMD='base64 | vault write -field=ciphertext transit/encrypt/pg-tde-master-1 plaintext=- > %p'
+
+enterprisedb@ip-172-31-50-151:~$ export PGDATAKEYUNWRAPCMD='cat %p | vault write -field=plaintext transit/decrypt/pg-tde-master-1 ciphertext=- | base64 --decode'
+```
+5. Perform your initdb per your database requirements, for example: `./initdb -D dd12 -y`.
+
+6. If all is successful you should get an output that looks like this:
+```bash
+
+    enterprisedb@ip-172-31-46-134:/usr/lib/edb-as/15/bin$ ./initdb -D /var/lib/edb-as/15/dd12 -y
+The files belonging to this database system will be owned by user "enterprisedb".
+This user must also own the server process.
+The database cluster will be initialized with locale "C.UTF-8".
+The default database encoding has accordingly been set to "UTF8".
+The default text search configuration will be set to "english".
+Data page checksums are disabled.
+Transparent data encryption is enabled.
+creating directory /var/lib/edb-as/15/dd12 ... ok
+creating subdirectories ... ok
+selecting dynamic shared memory implementation ... posix
+selecting default max_connections ... 100
+selecting default shared_buffers ... 128MB
+selecting default time zone ... America/New_York
+creating configuration files ... ok
+setting up data encryption ... ok
+running bootstrap script ... usage: edb_tde_kmip_client.py [-h] [--pykmip-config-file FILENAME]
+                              [--pykmip-config-block NAME]
+                              [--in-file FILENAME] [--out-file FILENAME]
+                              --key-uid KEY_UID --variant {pykmip,thales}
+                              {decrypt,encrypt}
+edb_tde_kmip_client.py: error: argument --variant: invalid choice: 'pymip' (choose from 'pykmip', 'thales')
+2023-04-12 09:35:27 EDT FATAL:  unwrapped key is too small
+child process exited with exit code 1
+initdb: removing data directory "/var/lib/edb-as/15/dd12"
+enterprisedb@ip-172-31-46-134:/usr/lib/edb-as/15/bin$ export PGDATAKEYWRAPCMD='python3 /tmp/edb_tde_kmip_client.py encrypt --pykmip-config-file=/tmp/pykmip.conf --key-uid=nfTCV2Cp5sffhQuRrOVfgCUyu8qh9kwd --out-file=%p --variant=pykmip'
+enterprisedb@ip-172-31-46-134:/usr/lib/edb-as/15/bin$ export PGDATAKEYUNWRAPCMD='python3 /tmp/edb_tde_kmip_client.py decrypt --pykmip-config-file=/tmp/pykmip.conf --key-uid=nfTCV2Cp5sffhQuRrOVfgCUyu8qh9kwd --in-file=%p --variant=pykmip'
+enterprisedb@ip-172-31-46-134:/usr/lib/edb-as/15/bin$ 
+enterprisedb@ip-172-31-46-134:/usr/lib/edb-as/15/bin$ 
+enterprisedb@ip-172-31-46-134:/usr/lib/edb-as/15/bin$ 
+enterprisedb@ip-172-31-46-134:/usr/lib/edb-as/15/bin$ 
+enterprisedb@ip-172-31-46-134:/usr/lib/edb-as/15/bin$ ./initdb -D /var/lib/edb-as/15/dd12 -y
+The files belonging to this database system will be owned by user "enterprisedb".
+This user must also own the server process.
+The database cluster will be initialized with locale "C.UTF-8".
+The default database encoding has accordingly been set to "UTF8".
+The default text search configuration will be set to "english".
+Data page checksums are disabled.
+Transparent data encryption is enabled.
+creating directory /var/lib/edb-as/15/dd12 ... ok
+creating subdirectories ... ok
+selecting dynamic shared memory implementation ... posix
+selecting default max_connections ... 100
+selecting default shared_buffers ... 128MB
+selecting default time zone ... America/New_York
+creating configuration files ... ok
+setting up data encryption ... ok
+running bootstrap script ... ok
+performing post-bootstrap initialization ... ok
+creating edb sys ... ok
+loading edb contrib modules ...
+edb_redwood_bytea.sql 
+edb_redwood_date.sql 
+dbms_alert_public.sql 
+dbms_alert.plb 
+dbms_job_public.sql 
+dbms_job.plb 
+dbms_lob_public.sql 
+dbms_lob.plb 
+dbms_output_public.sql 
+dbms_output.plb 
+dbms_pipe_public.sql 
+dbms_pipe.plb 
+dbms_rls_public.sql 
+dbms_rls.plb 
+dbms_sql_public.sql 
+dbms_sql.plb 
+dbms_utility_public.sql 
+dbms_utility.plb 
+dbms_aqadm_public.sql 
+dbms_aqadm.plb 
+dbms_aq_public.sql 
+dbms_aq.plb 
+dbms_profiler_public.sql 
+dbms_profiler.plb 
+dbms_random_public.sql 
+dbms_random.plb 
+dbms_redact_public.sql 
+dbms_redact.plb 
+dbms_lock_public.sql 
+dbms_lock.plb 
+dbms_scheduler_public.sql 
+dbms_scheduler.plb 
+dbms_crypto_public.sql 
+dbms_crypto.plb 
+dbms_mview_public.sql 
+dbms_mview.plb 
+dbms_session_public.sql 
+dbms_session.plb 
+edb_bulkload.sql 
+edb_gen.sql 
+edb_objects.sql 
+edb_redwood_casts.sql 
+edb_redwood_strings.sql 
+edb_redwood_views.sql 
+utl_encode_public.sql 
+utl_encode.plb 
+utl_http_public.sql 
+utl_http.plb 
+utl_file.plb 
+edb_ht_public.sql 
+edb_ht.plb 
+utl_tcp_public.sql 
+utl_tcp.plb 
+utl_smtp_public.sql 
+utl_smtp.plb 
+utl_mail_public.sql 
+utl_mail.plb 
+utl_url_public.sql 
+utl_url.plb 
+utl_raw_public.sql 
+utl_raw.plb 
+commoncriteria.sql 
+edb_gen_redwood.sql 
+waitstates.sql 
+installing extension edb_dblink_libpq ... ok
+installing extension edb_dblink_oci ... ok
+snap_tables.sql 
+snap_functions.sql 
+dblink_ora.sql 
+sys_stats.sql 
+ok
+finalizing initial databases ... ok
+syncing data to disk ... ok
+initdb: warning: enabling "trust" authentication for local connections
+initdb: hint: You can change this by editing pg_hba.conf or using the option -A, or --auth-local and --auth-host, the next time you run initdb.
+Success. You can now start the database server using:
+    pg_ctl -D /var/lib/edb-as/15/dd12 -l logfile start
+
+```
+
+7. Start your database and navigate to your `/data` directory to view the postgresql.conf file to ensure that your `data_encryption_key_unwrap_command` that you set with your `export PGDATAUNWRAPCMD` is present under the Authentication section.
+```bash
+# - Authentication -
+
+#authentication_timeout = 1min		# 1s-600s
+#password_encryption = scram-sha-256	# scram-sha-256 or md5
+#db_user_namespace = off
+
+# GSSAPI using Kerberos
+#krb_server_keyfile = 'FILE:${sysconfdir}/krb5.keytab'
+#krb_caseins_users = off
+
+# - SSL -
+
+#ssl = off
+#ssl_ca_file = ''
+#ssl_cert_file = 'server.crt'
+#ssl_crl_file = ''
+#ssl_crl_dir = ''
+#ssl_key_file = 'server.key'
+#ssl_ciphers = 'HIGH:MEDIUM:+3DES:!aNULL' # allowed SSL ciphers
+#ssl_prefer_server_ciphers = on
+#ssl_ecdh_curve = 'prime256v1'
+#ssl_min_protocol_version = 'TLSv1.2'
+#ssl_max_protocol_version = ''
+#ssl_dh_params_file = ''
+#ssl_passphrase_command = ''
+#ssl_passphrase_command_supports_reload = off
+
+# - Data Encryption -
+
+data_encryption_key_unwrap_command = 'cat %p | vault write -field=plaintext transit/decrypt/pg-tde-master-1 ciphertext=- | base64 --decode'
+
+```
+## Encrypt Plaintext Data
+
+Hashicorp Vault Transit Secrets Engine can also encrypt some plaintext data.  However any plaintext data needs to be base64-encoded.  This is a requirement as Hashicorp Vault does not require that the plaintext data is "text", it could also be another type of file.
+
+```bash
+enterprisedb@ip-172-31-50-151:~$ export VAULT_TOKEN="hvs.D9lfoRBZYtdJY2t3lG3f6yUa"
+enterprisedb@ip-172-31-50-151:~$ vault write transit/encrypt/pg-tde-master-1 plaintext=$(echo "my secret data" | base64)
+Key            Value
+---            -----
+ciphertext     vault:v1:/laUa+i1RVs4kFDD+a6Dmm+mJvVuo8jW0JHWISlzEe/ur/nUlfswEyYShA==
+key_version    1
+```
+As an added note, Hashicorp Vault does not store any data, that is up to the database user.  For any more information on Hashicorp Vault Transit Secrets Engine visit the [Hashicorp](https://developer.hashicorp.com/vault/docs/secrets/transit) documentation.
+
+For more information on how TDE is incorporated with EDB Postgres Advanced Server and EDB Postgres Extended Server visit the [EDB Transparent Data Encryption](https://www.enterprisedb.com/docs/tde/latest/) documentation.
+

advocacy_docs/partner_docs/HashicorpVaultTransitSecretsEngine/06-CertificationEnvironment.mdx

@@ -0,0 +1,11 @@
+---
+title: 'Certification Environment'
+description: 'Overview of the certification environment'
+---
+
+|       |   |
+| ----------- | ----------- |
+| **Certification Test Date**      |   June 12, 2023       |
+| **EDB Postgres Advanced Server**  |    15.2   |
+| **EDB Postgres Extended Server**  |    15.2   |
+| **Hashicorp Vault**  |   v1.13.3   |

advocacy_docs/partner_docs/HashicorpVaultTransitSecretsEngine/07-Support.mdx

@@ -0,0 +1,26 @@
+---
+title: 'Support and Logging Details'
+description: 'Details of the support process and logging information'
+---
+
+## Support
+
+Technical support for the use of these products is provided by both EDB and Hashicorp.  A proper support contract is required to be in place at both EDB and Hashicorp.  A support ticket can be opened on either side to start the process.  If it is determined through the support ticket that resources from the other vendor is required, the customer should open a support ticket with that vendor through normal support channels.  This will allow both companies to work together to help the customer as needed.
+
+## Logging
+
+**EDB Postgres Advanced Server Logs:**
+
+Navigate to the `Data` directory in your chosen EDB Postgres Advanced Server instance and from here you can navigate to `log`, `current_logfiles` or you can navigate to the `postgresql.conf` file where you can customize logging options or enable `edb_audit` logs.
+
+**EDB Postgres Extended Server Logs**
+
+Navigate to the `Data` directory in your chosen EDB Postgres Extended Server instance and from here you can navigate to `log`, or you can navigate to the `postgresql.conf` file where you can customize logging options.  An example of the full path to view EDB Postgres Extended logs: `/var/lib/edb-pge/15/data/log`.
+
+** Hashicorp Vault Logs**
+
+Customers can use the `journalctl` function to call logs for Hashicorp Vault.  
+
+If you just want to view the Vault logs you can do so by entering `journalctl -ex -u vault` in the command line.
+
+If you want to view logs for a specific day and output those results to a `.txt` file you can do so by entering `journalctl -u vault -S today > vaultlog.txt` in the command line, adjusting the date to your needed date and the text title.

advocacy_docs/partner_docs/HashicorpVaultTransitSecretsEngine/index.mdx

@@ -0,0 +1,14 @@
+---
+title: 'Hashicorp Vault Transit Secrets Engine Implementation Guide'
+indexCards: simple
+directoryDefaults:
+  iconName: handshake
+---
+
+<p align="center">
+  <img  src="Images/PartnerProgram.jpg.png">
+</p>
+<h1 style="text-align: center;">EDB GlobalConnect Technology Partner Implementation Guide</h1>
+<h3 style="text-align: center;">Hashicorp Vault Transit Secrets Engine</h3>
+
+<p style="text-align: center;">This document is intended to augment each vendor’s product documentation in order to guide the reader in getting the products working together.  It is not intended to show the optimal configuration for the certified integration.</p>

src/pages/index.js

@@ -358,6 +358,9 @@ const Page = () => (
             <IndexCardLink to="/partner_docs/HashicorpVault">
               Hashicorp Vault
             </IndexCardLink>
+            <IndexCardLink to="/partner_docs/HashicorpVaultTransitSecretsEngine">
+              Hashicorp Vault Transit Secrets Engine
+            </IndexCardLink>
             <IndexCardLink to="/partner_docs/ImpervaDataSecurityFabric">
               Imperva Data Security Fabric
             </IndexCardLink>
@@ -380,9 +383,6 @@ const Page = () => (
             <IndexCardLink to="/partner_docs/HPE">
               HPE
             </IndexCardLink>
-            <IndexCardLink to="/partner_docs/ImpervaDataSecurityFabric">
-              Imperva Data Security Fabric
-            </IndexCardLink>
             <IndexCardLink to="/partner_docs/NutanixAHV">
               Nutanix AHV
             </IndexCardLink>