DataPower SSH Host Key Pinning

Overview

The DataPower Host Key Repository provides a mechanism for managing the pinned SSH host key fingerprint for a DataPower instance. This component is crucial for security, as it implements a "trust on first use" (TOFU) model to mitigate man-in-the-middle (MITM) attacks when establishing a connection to a DataPower instance.

The repository interacts directly with the s2r_datapower_instance database table to store, retrieve, and clear the ssh_host_key_fingerprint for a given instance. All operations are strictly scoped to the authenticated tenant, ensuring that one tenant cannot access or modify the host key information of another. This isolation is enforced in every database query.

This component is used by other parts of the platform that need to establish or verify secure connections to DataPower instances.

How it works

The repository ensures that an SSH host key fingerprint for a DataPower instance is captured on the first connection and remains immutable for subsequent connections, unless explicitly cleared. This is achieved through atomic, conditional database operations.

Tenant Isolation

Every database operation performed by this repository is filtered by the current tenant's scope. The source refers to this as AuditRepository.TENANT_SCOPE_SQL. This means that if an operation is attempted on a instanceId that does not belong to the active tenant, the database treats the record as if it does not exist. This design is fundamental to the platform's multi-tenancy and prevents data leakage or cross-tenant interference.

Pinning a Key

The pinIfAbsent method is responsible for pinning a key. It uses a conditional SQL UPDATE statement that only modifies the ssh_host_key_fingerprint column if its current value is NULL.

sequenceDiagram
    participant Caller
    participant Host Key Repository
    participant Database

    Caller->>Host Key Repository: pinIfAbsent(instanceId, "new-fingerprint")
    Note over Host Key Repository,Database: Executes UPDATE ... WHERE id = ? AND ssh_host_key_fingerprint IS NULL
    Host Key Repository->>Database: PIN_SQL(fingerprint, instanceId)
    alt Fingerprint was NULL (first pin)
        Database-->>Host Key Repository: 1 row updated
        Host Key Repository-->>Caller: return true
    else Fingerprint was already set (or instance not found)
        Database-->>Host Key Repository: 0 rows updated
        Host Key Repository-->>Caller: return false
    end

This atomic operation guarantees that even if multiple concurrent requests attempt to pin a key for the same new instance, only one will succeed. Subsequent attempts will find the column is no longer NULL and will result in zero rows updated, causing the method to return false.

Retrieving and Clearing a Key

• Retrieval: The findPinnedFingerprint method queries the database for the ssh_host_key_fingerprint. If the instance does not exist for the current tenant, the query returns no rows, and the method throws an IllegalArgumentException. If the key has not been pinned, the database returns NULL or an empty string, which the method normalizes to a null return value.
• Clearing: The clear method issues an SQL UPDATE to set the ssh_host_key_fingerprint back to NULL. This allows a new key to be pinned on a subsequent connection, which is necessary when a DataPower instance's host key has been intentionally rotated.

API Reference

The repository exposes a Java API for managing host key fingerprints.

findPinnedFingerprint(UUID instanceId)

Retrieves the pinned SSH host key fingerprint for a specific DataPower instance.

Returns:

• A String containing the pinned fingerprint.
• null if no fingerprint is currently pinned for the instance.

Throws:

• IllegalArgumentException: Thrown if the instanceId is not found or is not visible to the current tenant.

pinIfAbsent(UUID instanceId, String fingerprint)

Atomically pins the SSH host key fingerprint for an instance if and only if a fingerprint is not already present.

Returns:

• true if this call successfully stored the fingerprint.
• false if a fingerprint was already pinned or if the instance was not found for the current tenant.

Throws:

• IllegalArgumentException: Thrown if the provided fingerprint is null or blank.

clear(UUID instanceId)

Removes the pinned SSH host key fingerprint for a DataPower instance, allowing a new key to be pinned on the next connection.

Returns:

• true if the fingerprint was successfully cleared for an instance belonging to the current tenant.
• false if the instance was not found for the current tenant.

Troubleshooting

IllegalArgumentException on findPinnedFingerprint

• Cause: The provided instanceId does not exist in the database or does not belong to the currently authenticated tenant.
• Meaning: The system is "failing closed." It intentionally treats a missing instance and an instance belonging to another tenant identically to prevent information leakage. Do not treat this as an indication that you can pin a new key; it is a hard failure.

IllegalArgumentException on pinIfAbsent

• Cause: The fingerprint parameter was null or an empty/blank string.
• Meaning: A valid fingerprint string is required for the pinning operation.

pinIfAbsent returns false

• Cause: This indicates one of two conditions:
  1. A fingerprint was already pinned for the specified instanceId. The operation did not overwrite the existing value.
  2. The instanceId does not belong to the current tenant.
• Meaning: The state was not changed by this call.

clear returns false

• Cause: The instanceId does not correspond to an instance owned by the current tenant.
• Meaning: No record was found to update, so no change was made.

See Also

• DataPower Instance Management: This component is tightly coupled with the repository that manages the core records of DataPower instances.
• Auditing and Tenant Scoping: All operations are scoped by the platform's tenant isolation framework to ensure strict data separation.

All SOAP-to-REST docs