Ginger Encrypted Uploader: Deprecated

Status: This tool is deprecated and no longer supported. Please migrate to using Ginger-j: https://github.com/spice-labs-inc/ginger-j

---

What this tool did

Took a JWT from the Spice Labs website, a PEM-encoded public key from the website, and a payload, then produced an encrypted ZIP and optionally uploaded it to a server. Encryption operations used OpenSSL. Written in Rust

Why it existed: To ensure data was encrypted client-side with a specific public key before it left your machine

---

When you might still reference it

• Auditing historical pipelines: to understand how older uploads were produced
• Reproducing a legacy bundle: to re-encrypt data to match an archived workflow
• Validating MIME checks that Ginger enforced before upload

For new work, use Ginger-j. It replaces this functionality and is actively maintained

---

Command-line reference

Synopsis:

ginger [OPTIONS]

Options:

• -z, --zipin <ZIPIN>: Path to a ZIP that contains the JWT, server address, and public key. If provided: takes precedence over --jwt, --key, and --server
• -j, --jwt <JWT>: JWT used to authenticate with the server. Ignored when --zipin is provided
• -k, --key <KEY>: File path to the public key PEM used for encryption. Ignored when --zipin is provided
• -s, --server <SERVER>: Server base URL to POST the result to. Ignored when --zipin is provided
• -p, --payload <PAYLOAD>: File or directory to upload. If a directory: contents are TARed prior to encryption
• -e, --encrypt-only: Encrypt only: do not upload
• --uuid <UUID>: Required when using --encrypt-only: supplies the UUID that would otherwise come from the JWT
• --comment-no-sensitive-info <COMMENT>: Plain-text comment embedded in the bundle. Do not include secrets
• -m, --mime-type <MIME>: MIME type for the upload. Shortcuts: de → application/vnd.info.deployevent, gr or bt → application/vnd.cc.bigtent
• --accept-alt-mime-type=true: Allow MIME types other than the two above
• -h, --help: Print help
• -V, --version: Print version

Built-in validations:

• Deploy Events: when -m de is used: all *.json files must contain valid Deploy Event JSON
• Artifact Dependency Graphs: when -m gr or -m bt is used: the payload must be a directory that includes at least one .grc, .grd, and .gri file

---

Practical examples

Replace paths and values with your own. Examples assume the binary is ginger in your PATH

1) Encrypt only with a provided UUID

ginger   --encrypt-only   --uuid 123e4567-e89b-12d3-a456-426614174000   --key /path/to/public_key.pem   --payload /path/to/data

2) Upload a Goat Rodeo ADG directory

ginger   --jwt "$(cat /path/to/jwt.txt)"   --server https://upload.example.com   --key /path/to/public_key.pem   --payload /path/to/adg-dir   --mime-type bt

3) Upload Deploy Event JSON

ginger   --jwt "$(cat /path/to/jwt.txt)"   --server https://upload.example.com   --key /path/to/public_key.pem   --payload /path/to/deploy-events   --mime-type de

4) Use a single ZIP bundle for JWT: server: and key

ginger   --zipin /path/to/ginger_auth_bundle.zip   --payload /path/to/data   --mime-type bt

The ZIP is expected to be generated by the Spice Labs website flow and to include the JWT: server address: and the PEM public key

---

Behavior notes

• --zipin is authoritative: it overrides --jwt, --key, and --server
• Directories are TARed before encryption: file paths inside the TAR are preserved
• Comments are stored in plain text: do not include secrets
• Exit status: 0 on success, non-zero on error

---

Common errors and fixes

• Missing UUID with --encrypt-only: add --uuid <UUID>
• Invalid Deploy Event JSON: fix the JSON or remove non-Deploy Event files when using --mime-type de
• ADG directory missing required files: ensure the directory contains at least one .grc, .grd, and .gri file when using --mime-type bt or gr
• Public key not PEM: provide a PEM-encoded public key to --key or in --zipin
• JWT expired or invalid: obtain a fresh JWT from the website and retry

---

Migration to Ginger-j

• Ginger-j provides maintained libraries and a CLI for encrypted upload workflows
• Start here: https://github.com/spice-labs-inc/ginger-j
• Map your use cases: encrypt-only: encrypted upload with JWT: and ADG or Deploy Event uploads
• Retire old jobs that call the deprecated ginger binary

---

Copyright and license

The contents of this repository are copyrighted by Spice Labs, Inc. and licensed under the Apache 2.0 license

Copyright 2025 Spice Labs, Inc. & Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.