@@ -16,6 +16,70 @@ There are three ways to get into a workspace:
1616
1717Currently the first two will configure SSH but the third does not yet.
1818
19+ ## GPG Signature Verification
20+
21+ The Coder Gateway plugin starting with version * 2.22.0* implements a comprehensive GPG signature verification system to
22+ ensure the authenticity and integrity of downloaded Coder CLI binaries. This security feature helps protect users from
23+ running potentially malicious or tampered binaries.
24+
25+ ### How It Works
26+
27+ 1 . ** Binary Download** : When connecting to a Coder deployment, the plugin downloads the appropriate Coder CLI binary for
28+ the user's operating system and architecture from the deployment's ` /bin/ ` endpoint.
29+
30+ 2 . ** Signature Download** : After downloading the binary, the plugin attempts to download the corresponding ` .asc `
31+ signature file from the same location. The signature file is named according to the binary (e.g.,
32+ ` coder-linux-amd64.asc ` for ` coder-linux-amd64 ` ).
33+
34+ 3 . ** Fallback Signature Sources** : If the signature is not available from the deployment, the plugin can optionally fall
35+ back to downloading signatures from ` releases.coder.com ` . This is controlled by the ` fallbackOnCoderForSignatures `
36+ setting.
37+
38+ 4 . ** GPG Verification** : The plugin uses the BouncyCastle library shipped with Gateway app to verify the detached GPG
39+ signature against the downloaded binary using Coder's trusted public key.
40+
41+ 5 . ** User Interaction** : If signature verification fails or signatures are unavailable, the plugin presents security
42+ warnings
43+ to users, allowing them to accept the risk and continue or abort the operation.
44+
45+ ### Verification Process
46+
47+ The verification process involves several components:
48+
49+ - ** ` GPGVerifier ` ** : Handles the core GPG signature verification logic using BouncyCastle
50+ - ** ` VerificationResult ` ** : Represents the outcome of verification (Valid, Invalid, Failed, SignatureNotFound)
51+ - ** ` CoderDownloadService ` ** : Manages downloading both binaries and their signatures
52+ - ** ` CoderCLIManager ` ** : Orchestrates the download and verification workflow
53+
54+ ### Configuration Options
55+
56+ Users can control signature verification behavior through plugin settings:
57+
58+ - ** ` disableSignatureVerification ` ** : When enabled, skips all signature verification. This is useful for clients running
59+ custom CLI builds, or
60+ customers with old deployment versions that don't have a signature published on ` releases.coder.com ` .
61+ - ** ` fallbackOnCoderForSignatures ` ** : When enabled, allows downloading signatures from ` releases.coder.com ` if not
62+ available from the deployment
63+
64+ ### Security Considerations
65+
66+ - The plugin embeds Coder's trusted public key in the plugin resources
67+ - Verification uses detached signatures, which are more secure than attached signatures
68+ - Users are warned about security risks when verification fails
69+ - The system gracefully handles cases where signatures are unavailable
70+ - All verification failures are logged for debugging purposes
71+
72+ ### Error Handling
73+
74+ The system handles various failure scenarios:
75+
76+ - ** Missing signatures** : Prompts user to accept risk or abort
77+ - ** Invalid signatures** : Warns user about potential tampering and prompts user to accept risk or abort
78+ - ** Verification failures** : Prompts user to accept risk or abort
79+
80+ This signature verification system ensures that users can trust the Coder CLI binaries they download through the plugin,
81+ protecting against supply chain attacks and ensuring binary integrity.
82+
1983## Development
2084
2185To manually install a local build:
0 commit comments