From bd915301e55afc8e9c9cb6ff351ef025c9cf6fdb Mon Sep 17 00:00:00 2001
From: Sai Medhini Reddy Maryada <117196660+saimedhi@users.noreply.github.com>
Date: Tue, 19 Mar 2024 12:16:06 -0700
Subject: [PATCH] Added guide for configuring ssl_assert_hostname (#694)

Signed-off-by: saimedhi <saimedhi@amazon.com>
---
 CHANGELOG.md  |  1 +
 guides/ssl.md | 36 +++++++++++++++++++++++++++++++++---
 2 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 57b845df..14891428 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Incorporated API generation into CI workflow and fixed 'generate' nox session ([#660](https://github.com/opensearch-project/opensearch-py/pull/660))
 - Added an automated api update bot for opensearch-py ([#664](https://github.com/opensearch-project/opensearch-py/pull/664)) 
 - Enhance generator to update changelog only if generated code differs from existing ([#684](https://github.com/opensearch-project/opensearch-py/pull/684))
+- Added guide for configuring ssl_assert_hostname ([#694](https://github.com/opensearch-project/opensearch-py/pull/694))
 ### Changed
 - Updated the `get_policy` API in the index_management plugin to allow the policy_id argument as optional ([#633](https://github.com/opensearch-project/opensearch-py/pull/633))
 - Updated the `point_in_time.md` guide with examples demonstrating the usage of the new APIs as alternatives to the deprecated ones. ([#661](https://github.com/opensearch-project/opensearch-py/pull/661))
diff --git a/guides/ssl.md b/guides/ssl.md
index 8ee73941..5b9267f2 100644
--- a/guides/ssl.md
+++ b/guides/ssl.md
@@ -1,7 +1,11 @@
 - [SSL](#ssl)
+    - [Establishing a Secure Connection](#establishing-a-secure-connection)
+    - [Verifying SSL against a Different Host](#verifying-ssl-against-a-different-host)
 
 # SSL
 
+## Establishing a Secure Connection
+
 ```python
 from opensearchpy import OpenSearch
 
@@ -10,7 +14,7 @@ port = 9200
 auth = ('admin', 'admin') # For testing only. Don't store credentials in code.
 
 # Provide a CA bundle if you use intermediate CAs with your root CA.
-# If this is not given, the CA bundle is is discovered from the first available
+# If this is not given, the CA bundle is discovered from the first available
 # following options:
 # - OpenSSL environment variables SSL_CERT_FILE and SSL_CERT_DIR
 # - certifi bundle (https://pypi.org/project/certifi/)
@@ -21,7 +25,7 @@ ca_certs_path = '/full/path/to/root-ca.pem'
 # client_cert_path = '/full/path/to/client.pem'
 # client_key_path = '/full/path/to/client-key.pem'
 
-# Create the client with SSL/TLS enabled, but hostname verification disabled.
+# Create the client with SSL/TLS enabled
 client = OpenSearch(
     hosts = [{'host': host, 'port': port}],
     http_compress = True, # enables gzip compression for request bodies
@@ -30,7 +34,33 @@ client = OpenSearch(
     # client_key = client_key_path,
     use_ssl = True,
     verify_certs = True,
-    ssl_assert_hostname = False,
+    ssl_assert_hostname = False, # Hostname verification is disabled here, but by default, it will remain enabled.
+    ssl_show_warn = False,
+    ca_certs = ca_certs_path
+)
+```
+When `ssl_assert_hostname` is set to None, verification is conducted using server hostname, effectively equivalent to not setting ssl_assert_hostname.
+
+
+## Verifying SSL against a different host
+
+When the server you’re connecting to presents a different certificate than the hostname, you can use ssl_assert_hostname:
+
+```python
+from opensearchpy import OpenSearch
+
+host = 'localhost'
+port = 9200
+auth = ('admin', 'admin')
+ca_certs_path = '/full/path/to/root-ca.pem'
+
+client = OpenSearch(
+    hosts = [{'host': host, 'port': port}],
+    http_compress = True, 
+    http_auth = auth,
+    use_ssl = True,
+    verify_certs = True,
+    ssl_assert_hostname = "ssl.com", # Indicate the host name to assert against. By default, it is equal to the server hostname.
     ssl_show_warn = False,
     ca_certs = ca_certs_path
 )