Add APIs to deal with SSL CA Certificates

CHANGELOG.rst

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 The format is based on `Keep a Changelog <http://keepachangelog.com/>`_.
 
+====================
+ 5.2.3 - 2020-03-03
+====================
+
+Added
+_____
+
+* Added NoSQLHandleConfig.set_ssl_ca_certs() to allow the user to configure SSL
+  CA certificates, and NoSQLHandleConfig.get_ssl_ca_certs() to get the SSL CA
+  certificates setting.
+
 ====================
  5.2.2 - 2020-02-27
 ====================

CONTRIBUTING.rst

@@ -4,19 +4,18 @@ Contributing to the Oracle NoSQL Database Python SDK
 
 *Copyright (c) 2018, 2020, Oracle and/or its affiliates. All rights reserved.*
 
-Pull requests can be made under
-`The Oracle Contributor Agreement <https://www.oracle.com/technetwork/community/
-oca-486395.html>`_ (OCA).
+Pull requests can be made under `The Oracle Contributor Agreement <https://www.
+oracle.com/technetwork/community/oca-486395.html>`_ (OCA).
 
-For pull requests to be accepted, the bottom of
-your commit message must have the following line using your name and
-e-mail address as it appears in the OCA Signatories list::
+For pull requests to be accepted, the bottom of your commit message must have
+the following line using your name and e-mail address as it appears in the OCA
+Signatories list::
 
   Signed-off-by: Your Name <you@example.org>
 
 This can be automatically added to pull requests by committing with::
 
   git commit --signoff
 
-Only pull requests from committers that can be verified as having
-signed the OCA can be accepted.
+Only pull requests from committers that can be verified as having signed the OCA
+can be accepted.

README-DEV.rst

@@ -42,6 +42,14 @@ All tests require that your PYTHONPATH be set to the development tree:
  $ export PYTHONPATH=<path-to-nosql-python-sdk>/nosql-python-sdk/src:\
  $PYTHONPATH
 
+If using on-premise Oracle NoSQL database with security enabled, the certificate
+path can be specified through the REQUESTS_CA_BUNDLE environment variable:
+
+ $ export REQUESTS_CA_BUNDLE=<path-to-certificate>/certificate.pem:\
+ $REQUESTS_CA_BUNDLE
+
+Or use the API :func:`borneo.NoSQLHandleConfig.set_ssl_ca_certs` to specify it.
+
 Run Unit Tests
 --------------
 

README.rst

@@ -7,17 +7,17 @@ About
 
 This is the Python SDK for Oracle NoSQL Database. Python 2.7+ and 3.5+ are
 supported. The SDK provides interfaces, documentation, and examples to help
-develop Python applications that connect to the Oracle NoSQL
-Database Cloud Service, Oracle NoSQL Database and to the Oracle NoSQL
-Cloud Simulator (which runs on a local machine).
+develop Python applications that connect to the Oracle NoSQL Database Cloud
+Service, Oracle NoSQL Database and to the Oracle NoSQL Cloud Simulator (which
+runs on a local machine).
 
 In order to run the Oracle NoSQL Cloud Simulator, a separate download is
-necessary from the Oracle NoSQL OTN download page. Throughout the
-documentation the Oracle NoSQL Database Cloud Service and Cloud Simulator are
-referred to as the "cloud service" while the Oracle NoSQL Database is referred
-to as "on-premise." In the `API reference <https://nosql-python-sdk.readthedocs.
-io/en/latest/api.html>`_ classes and interfaces are noted if they are only
-relevant to a specific environment.
+necessary from the Oracle NoSQL OTN download page. Throughout the documentation,
+the Oracle NoSQL Database Cloud Service and Cloud Simulator are referred to as
+the "cloud service" while the Oracle NoSQL Database is referred to as
+"on-premise." In the `API reference <https://nosql-python-sdk.readthedocs.io/en/
+latest/api.html>`_ classes and interfaces are noted if they are only relevant to
+a specific environment.
 
 The on-premise configuration requires a running instance of the Oracle NoSQL
 database. In addition a running proxy service is required. See `Oracle NoSQL
@@ -27,9 +27,9 @@ server-downloads.html>`_ for downloads, and see `Information about the proxy
 database/19.3/admin&id=NSADM-GUID-C110AF57-8B35-4C48-A82E-2621C6A5ED72>`_ for
 proxy configuration information.
 
-This project is open source and maintained by Oracle Corp. The home page for
-the project is `here <https://nosql-python-sdk.readthedocs.io/en/latest/
-index.html>`_
+This project is open source and maintained by Oracle Corp. The home page for the
+project is `here <https://nosql-python-sdk.readthedocs.io/en/latest/index.
+html>`_.
 
 ============
 Installation
@@ -442,5 +442,5 @@ License
 
 Copyright (C) 2018, 2020 Oracle and/or its affiliates. All rights reserved.
 
-This SDK is licensed under the Universal Permissive License 1.0. See
-`LICENSE <./LICENSE.txt>`_ for details
+This SDK is licensed under the Universal Permissive License 1.0. See `LICENSE
+<./LICENSE.txt>`_ for details.

THIRD_PARTY_LICENSES.txt

@@ -113,7 +113,7 @@ such third-party notices normally appear. The contents of the NOTICE file are
 for informational purposes only and do not modify the License. You may add Your
 own attribution notices within Derivative Works that You distribute, alongside
 or as an addendum to the NOTICE text from the Work, provided that such
-additional attribution notices cannot be construed as modifying the License. 
+additional attribution notices cannot be construed as modifying the License.
 
 You may add Your own copyright statement to Your modifications and may provide
 additional or different license terms and conditions for use, reproduction, or

docs/api/borneo.NoSQLHandleConfig.rst

@@ -26,6 +26,7 @@ NoSQLHandleConfig
       ~NoSQLHandleConfig.get_retry_handler
       ~NoSQLHandleConfig.get_sec_info_timeout
       ~NoSQLHandleConfig.get_service_url
+      ~NoSQLHandleConfig.get_ssl_ca_certs
       ~NoSQLHandleConfig.get_ssl_cipher_suites
       ~NoSQLHandleConfig.get_ssl_protocol
       ~NoSQLHandleConfig.get_table_request_timeout
@@ -38,6 +39,7 @@ NoSQLHandleConfig
       ~NoSQLHandleConfig.set_pool_maxsize
       ~NoSQLHandleConfig.set_retry_handler
       ~NoSQLHandleConfig.set_sec_info_timeout
+      ~NoSQLHandleConfig.set_ssl_ca_certs
       ~NoSQLHandleConfig.set_ssl_cipher_suites
       ~NoSQLHandleConfig.set_ssl_protocol
       ~NoSQLHandleConfig.set_table_request_timeout
@@ -61,6 +63,7 @@ NoSQLHandleConfig
    .. automethod:: get_retry_handler
    .. automethod:: get_sec_info_timeout
    .. automethod:: get_service_url
+   .. automethod:: get_ssl_ca_certs
    .. automethod:: get_ssl_cipher_suites
    .. automethod:: get_ssl_protocol
    .. automethod:: get_table_request_timeout
@@ -73,6 +76,7 @@ NoSQLHandleConfig
    .. automethod:: set_pool_maxsize
    .. automethod:: set_retry_handler
    .. automethod:: set_sec_info_timeout
+   .. automethod:: set_ssl_ca_certs
    .. automethod:: set_ssl_cipher_suites
    .. automethod:: set_ssl_protocol
    .. automethod:: set_table_request_timeout

docs/conf.py

@@ -2,8 +2,8 @@
 #
 # Configuration file for the Sphinx documentation builder.
 #
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
+# This file does only contain a selection of the most common options. For a full
+# list see the documentation:
 # http://www.sphinx-doc.org/en/master/config
 
 # -- Path setup --------------------------------------------------------------
@@ -33,9 +33,8 @@
 #
 # needs_sphinx = '1.0'
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
@@ -55,8 +54,8 @@
 # The master toctree document.
 master_doc = 'index'
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
+# The language for content autogenerated by Sphinx. Refer to documentation for a
+# list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
@@ -72,31 +71,30 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
+# The theme to use for HTML and HTML Help pages. See the documentation for a
+# list of builtin themes.
 #
 html_theme = "sphinx_rtd_theme"
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
+# further. For a list of options available for each theme, see the
 # documentation.
 #
 # html_theme_options = {}
 
 # Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
+# relative to this directory. They are copied after the builtin static files, so
+# a file named "default.css" will overwrite the builtin "default.css".
 # html_static_path = ['_static']
 html_static_path = []
 
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
+# Custom sidebar templates, must be a dictionary that maps document names to
+# template names.
 #
-# The default sidebars (for documents that don't match any pattern) are
-# defined by theme itself.  Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
-# 'searchbox.html']``.
+# The default sidebars (for documents that don't match any pattern) are defined
+# by theme itself. Builtin themes are using these templates by default:
+# ``['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']``.
 #
 # html_sidebars = {}
 
@@ -127,8 +125,8 @@
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
+# (source start file, target name, title, author,
+#  documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'NoSQLPythonSDK.tex',
      u'NoSQL Database Python SDK Documentation', u'Oracle', 'manual'),
@@ -146,8 +144,8 @@
 # -- Options for Texinfo output ----------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
+# (source start file, target name, title, author, dir menu entry, description,
+#  category)
 texinfo_documents = [
     (master_doc, 'NoSQLPythonSDK', u'NoSQL Database Python SDK Documentation',
      author, 'NoSQLPythonSDK', 'One line description of project.',
@@ -159,8 +157,8 @@
 # Bibliographic Dublin Core info.
 epub_title = project
 
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
+# The unique identifier of the text. This can be a ISBN number or the project
+# homepage.
 #
 # epub_identifier = ''
 

docs/installation.rst

@@ -237,7 +237,7 @@ the region **Regions.US_ASHBURN_1**. Information on regions can be found in
                 region = Regions.US_ASHBURN_1
 
                 # if using a specified credentials file
-                credentials_file=<path-to-your-credentials-file>
+                credentials_file = <path-to-your-credentials-file>
 
                 #
                 # Create an AuthorizationProvider
@@ -293,11 +293,21 @@ server-downloads.html>`_ for downloads, and see `Information about the proxy
 database/19.3/admin&id=NSADM-GUID-C110AF57-8B35-4C48-A82E-2621C6A5ED72>`_ for
 proxy configuration information.
 
-If running a secure store a user identity must be created in the store
-(separately) that has permission to perform the required operations of the
-application, such as manipulated tables and data. The identity is used in the
-:class:`borneo.kv.StoreAccessTokenProvider`. If the store is not secure an empty
-instance of :class:`borneo.kv.StoreAccessTokenProvider` is used. For example.
+If running a secure store, a certificate path should be specified through the
+REQUESTS_CA_BUNDLE environment variable:
+
+ $ export REQUESTS_CA_BUNDLE=<path-to-certificate>/certificate.pem:\
+ $REQUESTS_CA_BUNDLE
+
+Or :func:`borneo.NoSQLHandleConfig.set_ssl_ca_certs`.
+
+In addition, a user identity must be created in the store (separately) that has
+permission to perform the required operations of the application, such as
+manipulated tables and data. The identity is used in the
+:class:`borneo.kv.StoreAccessTokenProvider`.
+
+If the store is not secure, an empty instance of
+:class:`borneo.kv.StoreAccessTokenProvider` is used. For example:
 
 .. code-block:: pycon
 
@@ -317,7 +327,7 @@ instance of :class:`borneo.kv.StoreAccessTokenProvider` is used. For example.
   #
   # Create the AuthorizationProvider for a secure store:
   #
-  ap = StoreAccessTokenProvider(userName, password)
+  ap = StoreAccessTokenProvider(user_name, password)
 
   #
   # Create the AuthorizationProvider for a not secure store:
@@ -329,6 +339,11 @@ instance of :class:`borneo.kv.StoreAccessTokenProvider` is used. For example.
   #
   config = NoSQLHandleConfig(endpoint).set_authorization_provider(ap)
 
+  #
+  # set the certificate path if running a secure store
+  #
+  config.set_ssl_ca_certs(<ca_certs>)
+
   #
   # create a handle from the configuration object
   #