Skip to content

NETWORKING.md

Latest commit

 

History

History
286 lines (217 loc) · 13.9 KB

NETWORKING.md

File metadata and controls

286 lines (217 loc) · 13.9 KB
Raw

Network Transit Architecture & Corporate Proxy Integration

DiamTek Java Version Manager (JVM) treats network communication as an untrusted, high-latency boundary requiring strict cryptographic verification, zero-trust proxy negotiation, and atomic download mechanics.

Whether provisioning JDK runtimes across corporate WANs, traversing authenticating enterprise proxies, or validating asset digests through CDN edge nodes, DiamTek JVM guarantees that transit operations are resilient, transparent, and secure against Man-in-the-Middle (MitM) tampering.

🔍 Quick Jump

Network Architecture Overview

DiamTek JVM divides network transit into three strictly isolated, hardened processing layers:

flowchart TD
    subgraph Engine["DiamTek JVM Network Engine"]
        CLI["CLI Request: jvm install / jvm update"]
    end

    subgraph ProxyLayer["1. Proxy & Certificate Layer"]
        PEnv["Auto-Discovery: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY"]
        PAuth["Windows Auth: NTLM & Kerberos (DefaultNetworkCredentials)"]
        PCert["Trust Store: Windows Crypto API (LocalMachine\\Root, CurrentUser)"]
    end

    subgraph TransitLayer["2. Transit Validation & Retry Engine"]
        TRetry["Exponential Backoff with Jitter (429, 500, 502, 503, 504)"]
        TRedir["Open Redirect Validation (CWE-601 / CWE-918)"]
        TAllow["Domain Allowlist Filtering (Adoptium, Amazon, Microsoft, GitHub...)"]
    end

    subgraph StorageLayer["3. Content-Addressable Storage (CAS) & Verification"]
        SStream["Atomic Stream to .part File"]
        SHash["In-Memory SHA-256 Digest Computation"]
        SMatch["Comparison Against Manifest / API Digest"]
        SMove["Atomic Move to %LOCALAPPDATA%\\DiamTek\\JVM\\cache\\sha256\\"]
    end

    CLI --> PEnv
    PEnv --> PAuth
    PAuth --> PCert
    PCert -->|"TLS 1.2 / 1.3 Strict HTTPS"| TRetry
    TRetry --> TRedir
    TRedir --> TAllow
    TAllow -->|"Atomic Streaming"| SStream
    SStream --> SHash
    SHash --> SMatch
    SMatch --> SMove
Loading

Corporate Proxy Discovery & Configuration

In enterprise environments, outbound Internet access is frequently restricted through forward proxies requiring domain authentication.

Automatic Environment Discovery

DiamTek JVM automatically detects standard corporate proxy environment variables:

Variable Description Example
HTTP_PROXY Proxy URL for HTTP requests http://proxy.corp.internal:8080
HTTPS_PROXY Proxy URL for HTTPS requests http://proxy.corp.internal:8080
ALL_PROXY Universal fallback proxy URL http://proxy.corp.internal:8080
NO_PROXY Comma-separated domain/IP bypass list localhost,127.0.0.1,.corp.internal

Command-Line Overrides

For temporary sessions or specific automation scripts:

# Route through a specific corporate proxy
jvm install 21 --proxy "http://proxy.corp.internal:8080"

# Explicit proxy authentication
jvm install 21 --proxy "http://proxy.corp.internal:8080" --proxy-auth "DOMAIN\user:password"

Windows Integrated Authentication (NTLM / Kerberos)

Many enterprise proxies do not accept raw username/password combinations in URLs, instead requiring Windows Integrated Authentication. DiamTek JVM leverages .NET's native System.Net.CredentialCache.DefaultNetworkCredentials and System.Net.WebRequest.DefaultWebProxy, automatically passing the logged-in Windows domain identity (Kerberos ticket or NTLM challenge-response) to the proxy without exposing plaintext credentials.

Proxy Authentication Handshake Flow

sequenceDiagram
    autonumber
    participant JVM as DiamTek JVM
    participant Proxy as Corporate Authenticating Proxy
    participant Target as Upstream Mirror / CDN

    JVM->>Proxy: CONNECT target.host:443 (Initial Request)
    Proxy-->>JVM: 407 Proxy Authentication Required (Proxy-Authenticate: Negotiate, NTLM)
    Note over JVM: System.Net.CredentialCache.DefaultNetworkCredentials
    JVM->>Proxy: CONNECT target.host:443 (Proxy-Authorization: Negotiate <Kerberos/NTLM Token>)
    Proxy-->>JVM: 200 Connection Established
    JVM->>Target: TLS 1.2/1.3 Handshake & Download (Strict Domain Verification)
    Target-->>JVM: Secure Stream (.part staging)
Loading

Windows Certificate Store Integration (Corporate TLS Inspection)

The SSL Interception Problem

Security appliances (such as Zscaler, Palo Alto Networks, Netskope, or BlueCoat) perform deep packet inspection by intercepting outbound TLS handshakes, decrypting traffic, and resigning the connection using an internal corporate Root CA.

Traditional tools (curl, wget, native Java runtimes) fail immediately with certificate trust errors because their bundled trust stores do not include internal corporate certificates.

DiamTek JVM Native Solution

DiamTek JVM integrates directly with the native Windows Cryptography API:

  1. System Trust Inheritance: All certificates present in Cert:\LocalMachine\Root and Cert:\CurrentUser\Root (pushed by Active Directory Group Policy or Microsoft Intune) are automatically trusted by DiamTek JVM during download and verification.
  2. Revocation & Expiration Checking: Certificate revocation lists (CRL) and Online Certificate Status Protocol (OCSP) stapling are honored via the Windows Crypto API engine (CertVerifyCertificateChainPolicy).
  3. Automated JDK Trust Injection: Upon extracting any newly downloaded JDK, DiamTek JVM can synchronize corporate root certificates directly into the new JDK's $JAVA_HOME\lib\security\cacerts file, ensuring that subsequent developer builds (mvn, gradle, sbt) execute cleanly without PKIX path building failed errors.

Corporate TLS Interception & Trust Resolution Flow

sequenceDiagram
    autonumber
    participant App as DiamTek JVM Transit Engine
    participant Proxy as Corporate TLS Appliance (e.g. Zscaler)
    participant Upstream as Official JDK CDN (Adoptium/Oracle)
    participant CStore as Windows Cert Store (LocalMachine\Root)

    App->>Proxy: Outbound HTTPS Handshake
    Proxy->>Upstream: Connect to Upstream CDN
    Upstream-->>Proxy: Vendor TLS Certificate
    Proxy-->>App: Corporate Sub-CA Signed Certificate
    App->>CStore: Validate Cert Chain against Trusted Roots
    CStore-->>App: Valid Corporate CA Chain Confirmed
    Note over App: Secure TLS Connection Established Without Interruption
Loading

Content-Addressable Storage (CAS) Cache Architecture

To minimize network bandwidth, accelerate multi-project workflows, and support offline development, DiamTek JVM implements Content-Addressable Storage (CAS).

Cache Directory Topology

%LOCALAPPDATA%\DiamTek\JVM\cache\
├── sha256\
│   ├── d4\
│   │   └── d489b03126f5546ca337c75628b05e04cb2c48bf5ba2ea72d73347c61775f0a1.zip
│   └── 66\
│       └── 39\
│           └── 6639537e6b01e389a64765d78a87b3378be260ebcae1df676479f6e2467d130a.zip
├── metadata\
│   ├── adoptium-21.json
│   └── maven-3.9.9.json
└── tmp\
    └── download_a8f912c.part

Deduplication Across Projects & Tools

  1. Hash-Based Addressing: Files in the CAS are stored according to their SHA-256 digest (sha256\xx\<hash>.zip).
  2. Deduplication: If two developers or two different projects reference the exact same tool version, archive download is executed only once.
  3. Hardlink Optimization: When extracting or staging runtimes, DiamTek JVM utilizes NTFS hardlinks where appropriate to eliminate redundant disk consumption.

CAS Resolution & Deduplication Pipeline

flowchart TD
    Req["Request: Tool Version X (SHA-256: H)"] --> CalcPrefix["Compute CAS Path: sha256\\H[0..1]\\H.zip"]
    CalcPrefix --> CheckExists{"Archive exists in CAS?"}
    CheckExists -- Yes --> QuickExtract["Extract from CAS Cache (Zero Network Transit)"]
    CheckExists -- No --> Download["Stream from CDN to tmp\\download.part"]
    Download --> VerifyHash{"Computed SHA-256 == H?"}
    VerifyHash -- No --> Abort["Delete .part & Abort (CWE-494 / CWE-459)"]
    VerifyHash -- Yes --> StoreCAS["Atomic Move to CAS Path: sha256\\xx\\H.zip"]
    StoreCAS --> QuickExtract
Loading

Cache Telemetry & Maintenance

Developers and CI administrators can inspect and manage cache utilization:

# View disk consumption across JDKs, candidates, and CAS archives
jvm cache stats

# Remove obsolete archives or temporary staging artifacts
jvm cache prune

# Clear all cached archives (forces fresh downloads)
jvm cache clean

Resilient Transit & Atomic Download Mechanics

1. Atomic Staging Pipeline

Downloads are never written directly to their target destination:

  1. Data streams to an isolated temporary file with a .part extension in %LOCALAPPDATA%\DiamTek\JVM\cache\tmp\.
  2. The complete SHA-256 digest is calculated on-the-fly during the streaming read.
  3. Once the download completes, the calculated hash is compared against the expected digest.
  4. If valid, the file is atomically moved to its permanent location in cache\sha256\. If invalid or interrupted, the .part file is deleted immediately.

Atomic Staging Execution Flow

flowchart TD
    Req["Download Request"] --> Part["Stream to cache\\tmp\\download_{id}.part"]
    Part --> Calc["Calculate SHA-256 in real time"]
    Calc --> Comp{"Compare with expected SHA-256"}
    Comp -- Mismatch --> Del["Delete .part file immediately (CWE-494 / CWE-459)"]
    Del --> Err["Exit Code 5 (Checksum Mismatch)"]
    Comp -- Match --> Move["Atomic Move: cache\\tmp\\*.part -> cache\\sha256\\xx\\hash.zip"]
    Move --> Extract["Stage / Unpack to target directory"]
    Extract --> Junction["Repoint Directory Junction"]
Loading

2. Exponential Backoff with Jitter

For handling rate limits (e.g. GitHub Releases API 429 Too Many Requests) and transient network dropouts (500, 502, 503, 504):

$$\text{Delay} = \min\left(T_{\max}, T_{\text{base}} \times 2^{\text{attempt}}\right) \pm \text{Jitter}$$

DiamTek JVM retries transient failures up to 3 times before failing closed with actionable diagnostic guidance.

3. Open Redirect & Domain Allowlisting Defense (CWE-601 / CWE-918)

All URL redirects are validated before being followed. Target domains must match the strict allowlist of certified vendor CDN providers (Adoptium, Amazon AWS, Microsoft Azure CDN, GitHub Releases, Oracle, Azul, BellSoft, SAP, Alibaba). Any redirect to an unauthorized third-party domain or internal private IP (169.254.169.254, 10.0.0.0/8, 192.168.0.0/16) is blocked immediately.

← Back to Documentation Overview