SSL-PSK for PyMobileDevice3

Common errors

• fatal error: 'openssl/ssl.h' file not found

  cause During installation, the C extension for `sslpsk-pmd3` cannot find the OpenSSL header files required for compilation.
  fix Install OpenSSL development libraries on your system. For Debian/Ubuntu: `sudo apt-get install build-essential libssl-dev`. For macOS (with Homebrew): `brew install openssl@1.1` (or `openssl@3`) and ensure it's linked correctly (`brew link openssl@1.1 --force`).

• ERROR: Failed building wheel for sslpsk-pmd3

  cause This error typically indicates that the C extension failed to compile, often due to missing OpenSSL development headers, an unsupported Python version, or an incompatible compiler environment.
  fix Verify that you have OpenSSL development headers installed (see fix for 'openssl/ssl.h not found'). Also, ensure you are using a supported Python version (3.8-3.12). Check compiler toolchains if on Windows/macOS.

Warnings

• breaking Python 3.13 is not officially supported by sslpsk-pmd3. Attempts to install on Python 3.13 may lead to build failures.
  Fix: Use Python 3.8 to 3.12. Monitor GitHub for future 3.13+ support.
• gotcha Installing sslpsk-pmd3 from source may fail if OpenSSL development headers are not installed on your system, particularly on macOS or Linux.
  Fix: Ensure OpenSSL development headers are installed (e.g., `sudo apt-get install libssl-dev` on Debian/Ubuntu, `brew install openssl@1.1` or `openssl@3` and linking on macOS).
• deprecated The `ssl.wrap_socket()` function, which `sslpsk-pmd3`'s primary API emulates, is considered deprecated in upstream Python's `ssl` module since Python 3.2 (and 2.7.9) in favor of `SSLContext.wrap_socket()`. While `sslpsk-pmd3` still uses the `wrap_socket` pattern, for future compatibility and advanced features (like SNI), users of the underlying `sslpsk` might consider migrating to `SSLPSKContext` if available or planning for its adoption.
  Fix: For `sslpsk-pmd3`, continue using `sslpsk_pmd3.wrap_socket`. For general Python SSL usage, prefer `ssl.create_default_context().wrap_socket()` or similar `SSLContext`-based approaches.

Install

• pip install sslpsk-pmd3 Install latest version

Imports

• wrap_socket

  import sslpsk_pmd3
  ssl_sock = sslpsk_pmd3.wrap_socket(...)

  This is the primary method for wrapping sockets with PSK support as shown in sslpsk-pmd3's documentation. While upstream sslpsk3 recommends SSLPSKContext, sslpsk-pmd3's direct usage focuses on wrap_socket.

Quickstart

This client-side example demonstrates how to establish a TLS-PSK connection using `sslpsk_pmd3.wrap_socket`. It connects to a specified host and port, wraps the socket with a pre-shared key and client identity, sends a message, and receives a response. Ensure a compatible TLS-PSK server is running for this example to fully succeed. Environment variables are used for sensitive information like PSK and connection details.

import socket
import sslpsk_pmd3
import os

# Configuration from environment variables for security and flexibility
HOST = os.environ.get('PSK_HOST', '127.0.0.1')
PORT = int(os.environ.get('PSK_PORT', 6000))
PSK_KEY = os.environ.get('PSK_KEY', 'abcdef').encode('utf-8')
CLIENT_IDENTITY = os.environ.get('PSK_IDENTITY', 'client1').encode('utf-8')

def client_example(host, port, psk_key, client_identity):
    try:
        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        print(f"Attempting to connect to {host}:{port}...")
        sock.connect((host, port))
        print("Socket connected. Wrapping with TLS-PSK...")
        
        # Wrap the socket with TLS-PSK support
        # PROTOCOL_TLSv1_2 is a common, widely supported version.
        ssl_sock = sslpsk_pmd3.wrap_socket(
            sock,
            psk=psk_key,
            psk_identity=client_identity,
            ssl_version=sslpsk_pmd3.PROTOCOL_TLSv1_2
        )
        print("SSL socket wrapped. Sending data...")
        
        message = "Hello, TLS-PSK Server!\n"
        ssl_sock.sendall(message.encode())
        print(f"Client sent: {message.strip()}")
        
        received_data = ssl_sock.recv(1024).decode().strip()
        print(f"Client received: {received_data}")
        
    except ConnectionRefusedError:
        print(f"Error: Connection refused. Ensure a TLS-PSK server is running on {host}:{port}.")
    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        if 'ssl_sock' in locals() and ssl_sock:
            ssl_sock.shutdown(socket.SHUT_RDWR)
            ssl_sock.close()
        elif 'sock' in locals() and sock:
            sock.close()
        print("Connection closed.")

if __name__ == '__main__':
    print("This quickstart demonstrates client-side usage of sslpsk-pmd3.")
    print("A corresponding TLS-PSK server is required to fully execute this example.")
    print("You can configure host, port, key, and identity via PSK_HOST, PSK_PORT, PSK_KEY, PSK_IDENTITY environment variables.")
    print(f"Using defaults: Host={HOST}, Port={PORT}, PSK_KEY={'*' * len(PSK_KEY)}, PSK_IDENTITY={CLIENT_IDENTITY.decode()}")
    client_example(HOST, PORT, PSK_KEY, CLIENT_IDENTITY)