doc(grpc): secure channels

Author: jorgepiloto

doc/source/how-to/generating-certificates.rst

@@ -0,0 +1,85 @@
+Generating certificates
+=======================
+
+With the release of Ansys product service packs adding enhanced security to
+gRPC communication, the PyAnsys ecosystem enables various transport modes for
+securing gRPC connections. Mutual TLS (mTLS) is one such mode that provides
+secure communication by requiring both the client and server to authenticate
+each other using digital certificates.
+
+.. important::
+
+    As a user,y ou are responsible for managing and securing your own certificates.
+
+`OpenSSL <https://www.openssl.org/>`__ can be used to generate the necessary
+certificates for mTLS. The following files are required for both the server and
+the client:
+
+.. table::
+   :widths: auto
+
+   ====== ======================= ==========================================
+   Side   Required Files           Purpose
+   ====== ======================= ==========================================
+   Server server.crt               Server identity
+          server.key               Server private key
+          ca.crt                   To verify client certificates
+   Client client.crt               Client identity
+          client.key               Client private key
+          ca.crt                   To verify server certificates
+   ====== ======================= ==========================================
+
+Generate a certificate authority
+--------------------------------
+
+.. code-block:: bash
+
+    # Generate private key for CA
+    openssl genrsa -out ca.key 4096
+
+    # Generate self-signed CA certificate
+    openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt \
+        -subj "/CN=MyRootCA"
+
+Generate the server certificate
+-------------------------------
+
+.. code-block:: bash
+
+    # Generate server private key
+    openssl genrsa -out server.key 4096
+
+    # Generate a certificate signing request (CSR) for the server
+    openssl req -new -key server.key -out server.csr \
+        -subj "/CN=localhost"
+
+    # Generate server certificate signed by the CA
+    openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
+        -out server.crt -days 365 -sha256
+
+Generate the client certificate
+-------------------------------
+
+.. code-block:: bash
+
+    # Generate client private key
+    openssl genrsa -out client.key 4096
+
+    # Generate a certificate signing request (CSR) for the client
+    openssl req -new -key client.key -out client.csr \
+        -subj "/CN=grpc-client"
+
+    # Generate client certificate signed by the CA
+    openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
+        -out client.crt -days 365 -sha256
+
+Verify certificates
+-------------------
+
+.. code-block:: bash
+
+    # Verify server certificate
+    openssl verify -CAfile ca.crt server.crt
+
+    # Verify client certificate
+    openssl verify -CAfile ca.crt client.crt

doc/source/how-to/grpc-api-packages.rst

@@ -276,6 +276,23 @@ underlying implementations.
 For each client library release, only a single gRPC API version should be wrapped
 to maintain a consistent API abstraction expectation for the supporting server instances.
 
+Securing connections
+~~~~~~~~~~~~~~~~~~~~
+
+It is possible to secure connections between the Python client library and the
+product servers.
+
+For developers, use the `cyberchannel`_ module provided in the
+`ansys-tools-common`_ to implement secure connections. This ensures compliance
+with the latest security standards defined by PyAnsys.
+
+For users, refer to the `certificates`_ section for creating and managing
+all necessary certificates for secure connections.
+
+.. _cyberchannel: https://tools.docs.pyansys.com/version/stable/user_guide/secure_grpc.html#the-cyberchannel-module
+.. _ansys-tools-common: https://tools.docs.pyansys.com
+.. _certificates: https://tools.docs.pyansys.com/version/0.3/user_guide/secure_grpc.html#generating-certificates-for-mtls
+
 Public versus private Python API package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/source/how-to/index.rst

@@ -122,6 +122,7 @@ and app APIs.
    contributing
    packaging
    grpc-api-packages
+   generating-certificates 
    logging
    documenting
    testing