initial scaffolding for SDK encryption

.github/workflows/ci.yml

@@ -4,10 +4,12 @@ on:
   push:
     branches:
       - main
+      - candidate-*
   pull_request:
     types: [opened, synchronize, reopened]
     branches:
       - main
+      - candidate-*
   workflow_dispatch:
 
 permissions:

examples/5_hello_world_rsa/README.md

@@ -0,0 +1,68 @@
+# Hello World with RSA Encryption Example
+
+This example demonstrates how to use RSA encryption with INTERSECT services.
+
+## Overview
+
+RSA encryption provides end-to-end encryption for messages between clients and services:
+- Clients encrypt requests using the service's public key
+- Services encrypt responses using the client's public key
+- Each party decrypts messages using their own private key
+
+## Files
+
+- `hello_service.py` - Service implementation with RSA encryption enabled
+- `hello_client.py` - Client implementation that sends RSA encrypted messages
+- `hello_service_schema.json` - Service schema defining available operations
+
+## Key Features
+
+1. **Automatic RSA Key Generation**:
+   - Both service and client automatically generate RSA key pairs internally
+   - No manual key management required
+   - Service automatically handles public key requests from clients
+
+2. **Transparent Encryption**:
+   - Simply set `encryption_scheme='RSA'` when sending messages
+   - INTERSECT SDK handles all encryption/decryption automatically
+   - Public key exchange happens automatically in the background
+
+## Running the Example
+
+1. Start the service:
+   ```bash
+   python -m examples.5_hello_world_rsa.hello_service
+   ```
+
+2. In another terminal, run the client:
+   ```bash
+   python -m examples.5_hello_world_rsa.hello_client
+   ```
+
+## Expected Output
+
+Client output:
+```
+Hello, hello_client!
+```
+
+## How It Works
+
+1. Client starts and generates its RSA key pair
+2. Client sends encrypted message to service (encryption_scheme='RSA')
+3. Client first fetches service's public key via `intersect_sdk.get_public_key`
+4. Client encrypts the request using service's public key
+5. Service receives encrypted request and decrypts it using its private key
+6. Service processes the request and generates a response
+7. Service fetches client's public key (if not cached)
+8. Service encrypts response using client's public key
+9. Client receives encrypted response and decrypts it using its private key
+10. Client prints the decrypted response
+
+## Security Notes
+
+- Each service and client automatically generates its own unique RSA key pair on startup
+- Private keys are managed internally by the SDK and never transmitted
+- Public keys are exchanged automatically via the INTERSECT messaging system
+- RSA encryption uses 2048-bit keys for strong security
+- No manual key management is required - the SDK handles everything automatically

examples/5_hello_world_rsa/__init__.py

@@ -0,0 +1 @@
+"""Init file for hello world RSA encryption example."""

examples/5_hello_world_rsa/hello_client.py

@@ -0,0 +1,80 @@
+"""
+Hello World Client with RSA Encryption
+
+This example demonstrates how to use RSA encryption when sending messages to INTERSECT services.
+The client will encrypt requests using the service's public key and decrypt responses using its own private key.
+"""
+
+import time
+
+from intersect_sdk import (
+    HierarchyConfig,
+    IntersectClient,
+    IntersectServiceConfig,
+)
+from intersect_sdk.shared_callback_definitions import IntersectDirectMessageParams
+
+"""
+step one: create IntersectServiceConfig
+
+Note: The client automatically generates an RSA key pair internally.
+You don't need to manually create or manage encryption keys.
+"""
+config = IntersectServiceConfig(
+    brokers=[
+        {
+            'username': 'intersect_username',
+            'password': 'intersect_password',
+            'port': 1883,
+            'protocol': 'mqtt5.0',
+        }
+    ],
+    hierarchy=HierarchyConfig(
+        organization='hello-organization',
+        facility='hello-facility',
+        system='hello-system',
+        subsystem='hello-subsystem-client',
+        service='hello-client',
+    ),
+)
+
+"""
+step two: set up callback and then instantiate client
+"""
+
+
+def user_callback(source: str, operation: str, has_error: bool, payload: dict) -> None:
+    if has_error:
+        print(f'Error from {source}: {payload}')
+    else:
+        print(payload)
+
+
+intersect_client = IntersectClient(
+    config.hierarchy,
+    config=config,
+)
+
+"""
+step three: start up client with user callback
+"""
+intersect_client.startup(user_callback=user_callback)
+
+"""
+step four: send message with RSA encryption
+Note the encryption_scheme='RSA' parameter
+"""
+message_params = IntersectDirectMessageParams(
+    destination='hello-organization.hello-facility.hello-system.hello-subsystem.hello-service',
+    operation='HelloExample.say_hello_to_name',
+    payload='hello_client',
+    encryption_scheme='RSA',  # Enable RSA encryption
+)
+
+intersect_client.send_message(message_params)
+time.sleep(3)
+
+"""
+step five: shut down client
+"""
+intersect_client.shutdown()

examples/5_hello_world_rsa/hello_service.py

@@ -0,0 +1,86 @@
+"""
+Hello World Service with RSA Encryption
+
+This example demonstrates how to use RSA encryption with INTERSECT services.
+The service will encrypt responses to clients using the client's public key.
+"""
+
+import logging
+
+from intersect_sdk import (
+    HierarchyConfig,
+    IntersectBaseCapabilityImplementation,
+    IntersectService,
+    IntersectServiceConfig,
+    default_intersect_lifecycle_loop,
+    intersect_message,
+    intersect_status,
+)
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class HelloServiceCapabilityImplementation(IntersectBaseCapabilityImplementation):
+    """Capability implementation with RSA encryption support."""
+
+    intersect_sdk_capability_name = 'HelloExample'
+
+    @intersect_status()
+    def status(self) -> str:
+        """Basic status function which returns a hard-coded string."""
+        return 'Up'
+
+    @intersect_message()
+    def say_hello_to_name(self, name: str) -> str:
+        """Takes in a string parameter and says 'Hello' to the parameter!"""
+        return f'Hello, {name}!'
+
+
+if __name__ == '__main__':
+    """
+    Create a service with RSA encryption enabled.
+
+    The service automatically generates an RSA key pair internally.
+    When clients request RSA encryption, the service will:
+    1. Fetch the client's public key
+    2. Encrypt the response using the client's public key
+    3. The client decrypts using its private key
+    """
+
+    from_config_file = {
+        'brokers': [
+            {
+                'username': 'intersect_username',
+                'password': 'intersect_password',
+                'port': 1883,
+                'protocol': 'mqtt5.0',
+            }
+        ],
+        'hierarchy': {
+            'organization': 'hello-organization',
+            'facility': 'hello-facility',
+            'system': 'hello-system',
+            'subsystem': 'hello-subsystem',
+            'service': 'hello-service',
+        },
+    }
+
+    config = IntersectServiceConfig(**from_config_file)
+
+    """
+    step two: create instances of your capabilities, which you will inject into the service
+    """
+    capabilities = [HelloServiceCapabilityImplementation()]
+
+    """
+    step three: create the service using your capability and configuration
+    """
+    intersect_service = IntersectService(capabilities, config)
+
+    """
+    step four: utilize the default_intersect_lifecycle_loop function to manage startup,
+    the user lifecycle loop, and shutdown automatically. You must pass it the service
+    and a function containing your optional lifecycle code to execute.
+    """
+    default_intersect_lifecycle_loop(intersect_service)

examples/5_hello_world_rsa/hello_service_schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://raw.githubusercontent.com/INTERSECT-SDK/python-sdk/main/src/intersect_sdk/_internal/schema.schema.json",
+  "intersect_sdk_version": "0.8.0",
+  "name": "hello-organization.hello-facility.hello-system.hello-subsystem.hello-service",
+  "capabilities": [
+    {
+      "name": "HelloExample",
+      "functions": [
+        {
+          "name": "say_hello_to_name",
+          "parameters": {
+            "type": "string"
+          },
+          "returns": {
+            "type": "string"
+          }
+        }
+      ],
+      "encryption_schemes": [
+        "NONE",
+        "RSA"
+      ]
+    }
+  ]
+}