HTTPS/SSL Support and Password Obfuscation Control

[gierwialo]

I recently bought a NanoKVM Pro PCI-E and wanted to connect to it over HTTPS from Python. Turns out the library didn't support SSL/TLS at all, so I added it. While testing, I ran into a weird authentication issue that led me down a rabbit hole...

"The Authentication Mystery"

When I tried connecting to my NanoKVM Pro (running Application v1.2.12, Image v1.0.13) over HTTPS, authentication kept failing with "Invalid username or password" - even though I was using the correct credentials!

After SSH'ing into the device and monitoring logs, I discovered the reason: the library was sending AES-256-CBC encrypted passwords, but my device expected plain text over HTTPS (it does bcrypt hashing server-side). The web UI was working fine because it sends passwords in plain text.

Turns out newer NanoKVM versions (Pro and Standard ≥2.1.6) switched to accepting plain text passwords over HTTPS, while older versions still need the client-side obfuscation.

Note: NanoKVM Pro uses different version numbering (1.x.x) than standard NanoKVM (2.x.x), which initially confused me - I thought v1.2.12 was ancient!

What I Added

1. SSL/TLS Support

Three new optional parameters for NanoKVMClient.__init__():

• verify_ssl: bool = True - Enable/disable SSL certificate verification

  • Secure by default
  • Set to False for self-signed certs (testing only)

• ssl_ca_cert: str | None = None - Path to custom CA certificate

  • For self-signed certificates or private CAs
  • Better than disabling verification entirely

Implementation details:

• Uses aiohttp.TCPConnector with SSL config
• Works automatically for both HTTP requests and WebSocket connections
• Validates certificate files before use
• Clear error messages via new NanoKVMSSLError exception

2. Password Obfuscation Control

One new parameter to handle the authentication differences:

• use_password_obfuscation: bool = True - Control password encryption
  • Default: True (backward compatible with older devices)
  • Set to False for modern NanoKVM with HTTPS
  • When True: Uses AES-256-CBC encryption (legacy behavior)
  • When False: Sends plain text (relies on HTTPS transport security)

Backward Compatibility

Everything is 100% backward compatible. Existing code works without changes:

# Old code still works perfectly
async with NanoKVMClient("http://kvm.local/api/") as client:
    await client.authenticate("user", "pass")

All new parameters have sensible defaults:

• verify_ssl=True - Secure by default
• use_password_obfuscation=True - Works with older devices

Testing

I tested everything with my actual NanoKVM Pro over HTTPS:

• Hardware: NanoKVM Pro PCI-E
• Software: Application v1.2.12, Image v1.0.13 (latest as of Feb 2026)
• Certificate: Let's Encrypt (valid TLS 1.3)
• HTTPS connection with certificate verification
• Authentication with plain text password (use_password_obfuscation=False)
• Device info retrieval (get_info, get_hardware, get_gpio)
• WebSocket over SSL (mouse control via wss://)

Usage Examples

NanoKVM with HTTPS (Recommended)

async with NanoKVMClient(
    "https://kvm.local/api/",
    use_password_obfuscation=False
) as client:
    await client.authenticate("username", "password")

Legacy NanoKVM with HTTP

async with NanoKVMClient(
    "http://kvm.local/api/",
    use_password_obfuscation=True  # This is the default
) as client:
    await client.authenticate("username", "password")

Self-Signed Certificates

# Option 1: Disable verification (testing only - not recommended!)
async with NanoKVMClient(
    "https://kvm.local/api/",
    verify_ssl=False,
    use_password_obfuscation=False
) as client:
    await client.authenticate("username", "password")

# Option 2: Custom CA certificate (better approach)
async with NanoKVMClient(
    "https://kvm.local/api/",
    ssl_ca_cert="/path/to/ca.pem",
    use_password_obfuscation=False
) as client:
    await client.authenticate("username", "password")

Technical Details

SSL Implementation

• Uses Python's ssl.create_default_context() for secure defaults
• TLS 1.3 support (protocol auto-negotiated)
• Validates certificate files before attempting connection
• Clear error messages for SSL config issues

Password Obfuscation

• When enabled: AES-256-CBC encryption using hardcoded EncryptSecretKey
• When disabled: Plain text over HTTPS (transport layer handles security)
• Server-side uses bcrypt for password storage (on modern versions)

Files Changed

• nanokvm/client.py - Main implementation (~150 lines added/modified)
• tests/test_ssl.py - New comprehensive SSL tests (~200 lines)
• README.md - Updated docs with HTTPS examples

Version Compatibility Guide

Based on my testing and research:

Modern devices (use plain text password):

• NanoKVM Pro (any version with HTTPS)
• NanoKVM Standard ≥2.1.6 (with bcrypt hashing)
• Any device with HTTPS enabled

→ Set use_password_obfuscation=False

Legacy devices (need obfuscation):

• NanoKVM Standard <2.1.6 (HTTP only)
• Any device using the old hardcoded EncryptSecretKey

→ Keep use_password_obfuscation=True (default)

Not sure which you have?

• If your device supports HTTPS → try use_password_obfuscation=False
• If authentication fails, toggle the parameter

My Test Setup

Device: NanoKVM Pro PCI-E
Software: Application v1.2.12, Image v1.0.13 (latest for Pro line)
Certificate: Let's Encrypt
Protocol: HTTPS with TLS 1.3
Authentication: Plain text password (use_password_obfuscation=False)
Result: Everything works perfectly for me ;-)

Feel free to comment and review what I've done :)

---

Review changes

Auto-Detection of Password Obfuscation Mode

Based on suggestion, the client now automatically detects whether the device needs obfuscated or plain text passwords — no manual configuration needed.

• use_password_obfuscation: bool | None = None - Changed from bool = True to Optional[bool]
  • None (default): Auto-detect — tries obfuscated first, falls back to plain text
  • True: Force obfuscation (legacy behavior)
  • False: Force plain text

How auto-detect works:

1. First attempt: obfuscated password (backward compatible with older devices)
2. If NanoKVMAuthenticationFailure → retry with plain text
3. If both fail → raise the exception from the second attempt

This means existing code works without changes and without the extra parameter:

# Just works — no need to know your NanoKVM version
async with NanoKVMClient("https://kvm.local/api/") as client:
    await client.authenticate("username", "password")

Other Review Fixes

• Removed NanoKVMSSLError — SSL exceptions (FileNotFoundError, ssl.SSLError) now propagate naturally from ssl.create_default_context() instead of being wrapped
• Async-safe SSL context creation — _create_ssl_context() is offloaded via asyncio.to_thread() since it performs file IO
• Flat test structure — all tests are plain async def test_* functions, no classes, consistent with the rest of the test suite

[puddly]

Thanks! I've left a few comments about the code.

Is the password obfuscation setting something we can autodetect? Possibly from the API version (if that's exposed unauthenticated) or just by trying both approaches?

[puddly]

Thanks! This looks good to me. Run pre-commit run --all-files to reformat the code and get CI passing.

@chiconws Home Assistant doesn't have a way to pin certificates to devices, it looks like the only choice during setup is to detect certificate validation errors during connection and present a new step in the config flow to allow users to opt into bypassing validation. Is this something you want to support?

[chiconws]

Yeah, I think we should support it, since there’s already a user request.

Because we can’t reliably check HTTPS state before authentication, I’d handle it in this order:

Try HTTP first; if it works, continue as normal
If HTTP fails, try HTTPS with certificate validation
If HTTPS fails due to cert validation, show a warning step in config flow and let the user explicitly opt into insecure TLS (verify_ssl=False)
Store that choice per config entry
So yes, support it, but never disable certificate validation silently.