diff --git a/CHANGELOG.md b/CHANGELOG.md index bd03010..9af5994 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased - add TLS support +- enable server certificate verification by default ## [v0.2.0](https://github.com/Mapepire-IBMi/mapepire-python/releases/tag/v0.2.0) - 2024-11-26 - replace `websocket-client` with `websockets` diff --git a/README.md b/README.md index a1c3a81..aecbed8 100644 --- a/README.md +++ b/README.md @@ -20,10 +20,12 @@ - [Setup](#setup) - [Install with `pip`](#install-with-pip) - [Server Component Setup](#server-component-setup) -- [Connection options](#connection-options) +- [Quick Start](#quick-start) +- [Other Connection options](#other-connection-options) - [1. Using the `DaemonServer` object](#1-using-the-daemonserver-object) - [2. Passing the connection details as a dictionary](#2-passing-the-connection-details-as-a-dictionary) - [3. Using a config file (`.ini`) to store the connection details](#3-using-a-config-file-ini-to-store-the-connection-details) + - [TLS Configuration](#tls-configuration) - [Usage](#usage) - [1. Using the `SQLJob` object to run queries synchronously](#1-using-the-sqljob-object-to-run-queries-synchronously) - [Query and run](#query-and-run) @@ -87,8 +89,34 @@ pip install mapepire-python ### Server Component Setup To use mapire-python, you will need to have the Mapepire Server Component running on your IBM i server. Follow these instructions to set up the server component: [Mapepire Server Installation](https://mapepire-ibmi.github.io/guides/sysadmin/) - -# Connection options +# Quick Start + +To get started with `mapepire-python`, you will need to setup a connection credentials for the Mapepire server. You can use a dictionary to store the connection details: + +```python +from mapepire_python import connect + +creds = { + "host": "SERVER", + "port": 8076, + "user": "USER", + "password": "PASSWORD", +} + +with connect(creds) as conn: + with conn.execute("select * from sample.employee") as cursor: + result = cursor.fetchone() + print(result) + +``` + +# Other Connection options + + > [!NOTE] + > TLS support as of version 0.3.0 is now available. Server certificate verification is enabled by default. To disable certificate verification, set the `ignoreUnauthorized` field to `True` in the connection details. + > - To update run `pip install -U mapepire-python` + > + > - More info TLS Configuration [here](#tls-configuration) There are three ways to configure mapepire server connection details using `mapepire-python`: @@ -107,8 +135,7 @@ creds = DaemonServer( host="SERVER", port="PORT", user="USER", - password="PASSWORD", - ignoreUnauthorized=True + password="PASSWORD" ) ``` @@ -122,8 +149,7 @@ creds = DaemonServer( host="SERVER", port="PORT", user="USER", - password="PASSWORD", - ignoreUnauthorized=True + password="PASSWORD" ) job = SQLJob(creds) @@ -174,6 +200,22 @@ job = SQLJob("./mapepire.ini", section="mapepire") The `section` argument is optional and allows you to specify a specific section in the `.ini` file where the connection details are stored. This allows you to store multiple connection details to different systems in the same file. If you do not specify a `section`, the first section in the file will be used. +## TLS Configuration + +Server certificate verification (`ssl.CERT_REQUIRED`) is enabled by default. To disable certificate verification, set the `ignoreUnauthorized` field to `True` in the connection details. + +get the server certificate: + +```python +from mapepire_python.data_types import DaemonServer +from mapepire_python.ssl import get_certificate + +creds = DaemonServer(host=server, port=port, user=user, password=password) +cert = get_certificate(creds) +print(cert) +``` + + # Usage diff --git a/mapepire_python/data_types.py b/mapepire_python/data_types.py index e8059e6..217f7c3 100644 --- a/mapepire_python/data_types.py +++ b/mapepire_python/data_types.py @@ -46,7 +46,7 @@ class DaemonServer: user: str password: str port: Optional[Union[str, int]] - ignoreUnauthorized: Optional[bool] = True + ignoreUnauthorized: Optional[bool] = False ca: Optional[Union[str, bytes]] = None diff --git a/tests/async_pool_test.py b/tests/async_pool_test.py index efc86c4..53adf0d 100644 --- a/tests/async_pool_test.py +++ b/tests/async_pool_test.py @@ -18,13 +18,7 @@ raise ValueError("One or more environment variables are missing.") -creds = DaemonServer( - host=server, - port=port, - user=user, - password=password, - ignoreUnauthorized=True, -) +creds = DaemonServer(host=server, port=port, user=user, password=password) @pytest.mark.asyncio diff --git a/tests/cl_test.py b/tests/cl_test.py index 0a3c771..63c60b1 100644 --- a/tests/cl_test.py +++ b/tests/cl_test.py @@ -14,13 +14,7 @@ raise ValueError("One or more environment variables are missing.") -creds = DaemonServer( - host=server, - port=port, - user=user, - password=password, - ignoreUnauthorized=True, -) +creds = DaemonServer(host=server, port=port, user=user, password=password) def test_simple(): diff --git a/tests/pep249_async_test.py b/tests/pep249_async_test.py index d19ee90..918fea3 100644 --- a/tests/pep249_async_test.py +++ b/tests/pep249_async_test.py @@ -19,13 +19,7 @@ raise ValueError("One or more environment variables are missing.") -creds = DaemonServer( - host=server, - port=port, - user=user, - password=password, - ignoreUnauthorized=True, -) +creds = DaemonServer(host=server, port=port, user=user, password=password) @pytest.mark.asyncio diff --git a/tests/pep249_test.py b/tests/pep249_test.py index 8a9be70..9dfa6e0 100644 --- a/tests/pep249_test.py +++ b/tests/pep249_test.py @@ -13,13 +13,7 @@ if not server or not user or not password: raise ValueError("One or more environment variables are missing.") -creds = DaemonServer( - host=server, - port=port, - user=user, - password=password, - ignoreUnauthorized=True, -) +creds = DaemonServer(host=server, port=port, user=user, password=password) def test_pep249(): diff --git a/tests/pooling_test.py b/tests/pooling_test.py index 5501262..53b2614 100644 --- a/tests/pooling_test.py +++ b/tests/pooling_test.py @@ -17,13 +17,7 @@ raise ValueError("One or more environment variables are missing.") -creds = DaemonServer( - host=server, - port=port, - user=user, - password=password, - ignoreUnauthorized=True, -) +creds = DaemonServer(host=server, port=port, user=user, password=password) @pytest.mark.asyncio diff --git a/tests/query_manager_test.py b/tests/query_manager_test.py index 09e3c4b..4f7570f 100644 --- a/tests/query_manager_test.py +++ b/tests/query_manager_test.py @@ -15,13 +15,7 @@ raise ValueError("One or more environment variables are missing.") -creds = DaemonServer( - host=server, - port=port, - user=user, - password=password, - ignoreUnauthorized=True, -) +creds = DaemonServer(host=server, port=port, user=user, password=password) def test_query_manager(): diff --git a/tests/simple_test.py b/tests/simple_test.py index 1859114..bed1b04 100644 --- a/tests/simple_test.py +++ b/tests/simple_test.py @@ -14,13 +14,7 @@ if not server or not user or not password: raise ValueError("One or more environment variables are missing.") -creds = DaemonServer( - host=server, - port=port, - user=user, - password=password, - ignoreUnauthorized=True, -) +creds = DaemonServer(host=server, port=port, user=user, password=password) def parse_sql_rc(message): diff --git a/tests/sql_test.py b/tests/sql_test.py index 5d9d987..442ae07 100644 --- a/tests/sql_test.py +++ b/tests/sql_test.py @@ -16,13 +16,7 @@ raise ValueError("One or more environment variables are missing.") -creds = DaemonServer( - host=server, - port=port, - user=user, - password=password, - ignoreUnauthorized=True, -) +creds = DaemonServer(host=server, port=port, user=user, password=password) def test_simple(): diff --git a/tests/tls_test.py b/tests/tls_test.py index 9a8e9d5..b0feef5 100644 --- a/tests/tls_test.py +++ b/tests/tls_test.py @@ -17,7 +17,7 @@ if not server or not user or not password: raise ValueError("One or more environment variables are missing.") -creds = DaemonServer(host=server, port=port, user=user, password=password, ignoreUnauthorized=False) +creds = DaemonServer(host=server, port=port, user=user, password=password) def test_get_cert():