feat(vmm-cli): create launch tickets and deploy with them

Signed-off-by: Kevin Wang <wy721@qq.com>

Author: kvinwang

docs/security/security-best-practices.md

@@ -52,6 +52,8 @@ Because `launch_token_hash` is public, a guessable token can be recovered offlin
 
 Also understand the protection boundary of this mechanism: the guest verifies the token before any keys are provisioned, which means the token must reach the guest through `user_config` — a channel the host can read. The requirement therefore stops parties who only know the public app-compose.json from launching the app, but once a host has hosted a deployment it learns the token and can later relaunch instances of that compose with substituted encrypted envs. Mitigations: generate a fresh token per deployment and remove stale compose hashes from the on-chain whitelist; if the token must stay secret from the host, use the app-layer `APP_LAUNCH_TOKEN` encrypted-env pattern above instead (its check necessarily runs after key provisioning).
 
+A KMS-level launch ticket closes that gap for apps governed by `DstackApp`: the contract owner requires a ticket (`setRequireLaunchTicket`) and allows the hashes of the tickets they issue (`addLaunchTicket`), and the KMS refuses keys and certificates to a CVM without an allowed ticket. The check runs in the KMS, so it does not depend on the guest OS, and a ticket is revoked on chain without changing the compose hash. It is orthogonal to `requirements.launch_token_hash`. The host still holds the ticket, so issue one per deployment and remove it when the host stops serving the app. See [launch tickets](../../dstack/kms/README.md#launch-tickets) and [vmm-cli](../vmm-cli-user-guide.md#launch-tickets).
+
 If you use dstack-vmm's built-in UI, the prelaunch script has already been automatically filled in for you:
 
 ![Prelaunch Script](../assets/prelaunch-script.png)

docs/vmm-cli-user-guide.md

@@ -293,6 +293,27 @@ Deploy your application with the compose file:
 - `--kms-url`: KMS server URL
 - `--gateway-url`: Gateway server URL
 - `--stopped`: Create VM in stopped state (requires dstack-vmm >= 0.5.4)
+- `--launch-ticket-file`: File holding the launch ticket the guest presents to the KMS (see below)
+
+#### Launch Tickets
+
+When the app's `DstackApp` contract requires a launch ticket, the KMS releases
+keys only to a CVM presenting a ticket whose hash the contract allows. Create a
+fresh ticket per deployment, allow its hash on chain, and deploy with it:
+
+```bash
+./vmm-cli.py launch-ticket new ./prod.ticket   # writes the ticket (mode 0600), prints its hash
+# addLaunchTicket(<hash>, "prod") on the DstackApp contract, then:
+./vmm-cli.py deploy ... --launch-ticket-file ./prod.ticket
+```
+
+`launch-ticket hash FILE` prints the hash of an existing ticket; `--kms` gives the
+hash for a KMS onboarding ticket (`addKmsLaunchTicket`) instead. `update
+--launch-ticket-file FILE` replaces the ticket of a VM and `update
+--no-launch-ticket` removes it. The VMM keeps the ticket and writes it to the
+guest's sys-config at every boot, but never returns it. The host holds the
+ticket, so remove its hash from the contract once that host stops serving the
+app. See [launch tickets](../dstack/kms/README.md#launch-tickets).
 
 #### Port Mapping
 

dstack/dstack-types/src/authorization.rs

@@ -63,3 +63,21 @@ pub fn check_launch_ticket(ticket: &str) -> Result<(), String> {
     Ok(())
 }
 
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Shared with vmm-cli's tests, which compute the hash the contracts allow.
+    #[test]
+    fn launch_ticket_hashes_are_domain_separated() {
+        let ticket = "t".repeat(32);
+        assert_eq!(
+            hex::encode(AuthorizationOperation::AppGetCert.launch_ticket_hash(&ticket)),
+            "8185a84114cfd5c0fb70e2233dee133cfa6467b58537ece8b27137828baabecc"
+        );
+        assert_eq!(
+            hex::encode(AuthorizationOperation::KmsImportKeys.launch_ticket_hash(&ticket)),
+            "a78c8aebf7e3ba7ead22d3e9e20827a53c89af8e61115a0e8c333b9e27f632ad"
+        );
+    }
+}

dstack/vmm/src/tests/test_vmm_cli.py

@@ -62,6 +62,35 @@ def test_kms_urls_are_sent_to_upgrade_app(self) -> None:
             ],
         )
 
+    def test_launch_ticket_is_sent_and_removed(self) -> None:
+        """Send a replacement ticket, and an empty one to remove it."""
+        cli = VMM_CLI.VmmCLI("http://127.0.0.1:8080")
+        calls: list[tuple[str, dict]] = []
+        cli.rpc_call = lambda method, params=None: calls.append((method, params)) or {}
+
+        with contextlib.redirect_stdout(io.StringIO()):
+            cli.update_vm("vm-id", launch_ticket="t" * 32)
+            cli.update_vm("vm-id", launch_ticket="")
+
+        self.assertEqual(
+            [params["launch_ticket"] for _, params in calls], ["t" * 32, ""]
+        )
+
+
+class LaunchTicketTests(unittest.TestCase):
+    """Pin the hash the contracts allow; the KMS computes the same."""
+
+    def test_hash_is_domain_separated(self) -> None:
+        ticket = "t" * 32
+        self.assertEqual(
+            VMM_CLI.launch_ticket_hash(ticket, kms=False),
+            "0x8185a84114cfd5c0fb70e2233dee133cfa6467b58537ece8b27137828baabecc",
+        )
+        self.assertEqual(
+            VMM_CLI.launch_ticket_hash(ticket, kms=True),
+            "0xa78c8aebf7e3ba7ead22d3e9e20827a53c89af8e61115a0e8c333b9e27f632ad",
+        )
+
 
 class SealedEnvTests(unittest.TestCase):
     """Exercise signed recipient selection and SealedEnv compatibility."""
@@ -382,6 +411,7 @@ def test_create_update_and_update_env_send_only_the_negotiated_field(self):
             stopped=False,
             no_tee=False,
             annotation=None,
+            launch_ticket_file=None,
             disk_prealloc=None,
             simulated_tee=None,
             swap=None,

dstack/vmm/src/vmm-cli.py

@@ -12,6 +12,7 @@
 import json
 import os
 import re
+import secrets
 import socket
 import ssl
 import sys
@@ -501,6 +502,32 @@ def read_utf8(filepath: str) -> str:
         return f.read().decode("utf-8")
 
 
+def read_launch_ticket(filepath: str) -> str:
+    """Read a launch ticket file, ignoring surrounding whitespace."""
+    ticket = read_utf8(filepath).strip()
+    if not 32 <= len(ticket.encode()) <= 1024:
+        raise Exception("launch ticket must be 32 to 1024 bytes")
+    return ticket
+
+
+def launch_ticket_hash(ticket: str, kms: bool) -> str:
+    """The hash to allow on chain: sha256(domain || ticket)."""
+    domain = "dstack-kms-launch-ticket/v1:" if kms else "dstack-launch-ticket/v1:"
+    return "0x" + hashlib.sha256((domain + ticket).encode()).hexdigest()
+
+
+def cmd_launch_ticket(args) -> None:
+    """Create a launch ticket file, or print the hash of one."""
+    if args.launch_ticket_command == "new":
+        ticket = secrets.token_urlsafe(32)
+        fd = os.open(args.file, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(fd, "w") as f:
+            f.write(ticket + "\n")
+    else:
+        ticket = read_launch_ticket(args.file)
+    print(launch_ticket_hash(ticket, args.kms))
+
+
 class UnixSocketHTTPConnection(http.client.HTTPConnection):
     """HTTPConnection that connects to a Unix domain socket."""
 
@@ -1128,6 +1155,8 @@ def create_vm(self, args) -> None:
             "no_tee": args.no_tee,
             "annotations": args.annotation or {},
         }
+        if args.launch_ticket_file:
+            params["launch_ticket"] = read_launch_ticket(args.launch_ticket_file)
         if args.disk_prealloc:
             params["disk_prealloc"] = args.disk_prealloc
         if args.simulated_tee:
@@ -1277,6 +1306,7 @@ def update_vm(
         net_vhost_inherit: bool = False,
         net_queues: Optional[Union[int, str]] = None,
         annotations: Optional[Dict[str, str]] = None,
+        launch_ticket: Optional[str] = None,
     ) -> None:
         """Update multiple aspects of a VM in one command."""
         # Validate: --env-file requires --kms-url
@@ -1529,6 +1559,10 @@ def update_vm(
             upgrade_params["annotations"] = annotations
             updates.append(f"annotations ({len(annotations)})")
 
+        if launch_ticket is not None:
+            upgrade_params["launch_ticket"] = launch_ticket
+            updates.append("launch ticket" if launch_ticket else "launch ticket removed")
+
         if no_tee is not None:
             upgrade_params["no_tee"] = no_tee
             updates.append("TEE disabled" if no_tee else "TEE enabled")
@@ -2196,6 +2230,10 @@ def _patched_format_help():
         metavar="KEY=VALUE",
         help="Annotation for host-side tooling (can be repeated)",
     )
+    deploy_parser.add_argument(
+        "--launch-ticket-file",
+        help="File holding the launch ticket the guest presents to the KMS",
+    )
     deploy_parser.add_argument(
         "--disk-prealloc",
         choices=["off", "metadata", "falloc", "full"],
@@ -2476,6 +2514,31 @@ def _patched_format_help():
     annotations_group.add_argument(
         "--no-annotations", action="store_true", help="Remove all annotations"
     )
+    launch_ticket_group = update_parser.add_mutually_exclusive_group()
+    launch_ticket_group.add_argument(
+        "--launch-ticket-file", help="Replace the launch ticket with this file's"
+    )
+    launch_ticket_group.add_argument(
+        "--no-launch-ticket", action="store_true", help="Remove the launch ticket"
+    )
+
+    launch_ticket_parser = subparsers.add_parser(
+        "launch-ticket", help="Create launch tickets and print their on-chain hash"
+    )
+    launch_ticket_subparsers = launch_ticket_parser.add_subparsers(
+        dest="launch_ticket_command", required=True
+    )
+    for name, help_text in [
+        ("new", "Write a new random ticket to FILE"),
+        ("hash", "Print the hash of the ticket in FILE"),
+    ]:
+        sub = launch_ticket_subparsers.add_parser(name, help=help_text)
+        sub.add_argument("file", metavar="FILE")
+        sub.add_argument(
+            "--kms",
+            action="store_true",
+            help="A KMS onboarding ticket (addKmsLaunchTicket) rather than an app one",
+        )
 
     args = parser.parse_args()
 
@@ -2488,6 +2551,9 @@ def _patched_format_help():
         else:
             vmm_parser.print_help()
         return
+    if args.command == "launch-ticket":
+        cmd_launch_ticket(args)
+        return
 
     # Resolve the URL with auto-discovery
     url = resolve_vmm_url(instances, config, args.url)
@@ -2574,6 +2640,11 @@ def _patched_format_help():
             net_vhost_inherit=getattr(args, "net_vhost_inherit", False),
             net_queues=args.net_queues,
             annotations={} if args.no_annotations else args.annotation,
+            launch_ticket=(
+                ""
+                if args.no_launch_ticket
+                else args.launch_ticket_file and read_launch_ticket(args.launch_ticket_file)
+            ),
         )
     elif args.command == "kms":
         if not args.kms_action: