Metadata-Version: 2.4
Name: signing-tool
Version: 3.9.0
Summary: Laavat Signing Solution CLI Tool
Author-email: Laavat Oy <contact@laavat.com>
License: Copyright (c) 2026 Laavat Oy
        
        All rights reserved.
        
        This software is the proprietary work of Laavat Oy. Use, reproduction, or distribution of this software, in whole or in part, is prohibited without the express prior written permission of Laavat Oy.
        
Project-URL: Documentation, https://docs.laavat.io/democlient/usage/
Project-URL: Homepage, https://docs.laavat.io/
Keywords: signing,cli,pki,certificate,signing-tool,laavat
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSES/certifi.txt
License-File: LICENSES/configparser.txt
License-File: LICENSES/cryptography.txt
License-File: LICENSES/jwcrypto.txt
License-File: LICENSES/python-dateutil.txt
License-File: LICENSES/requests.txt
License-File: LICENSES/six.txt
License-File: LICENSES/urllib3.txt
Requires-Dist: certifi>=2017.4.17
Requires-Dist: python-dateutil>=2.1
Requires-Dist: six>=1.10
Requires-Dist: urllib3>=1.23
Requires-Dist: requests>=2.25.1
Requires-Dist: jwcrypto>=1.0
Requires-Dist: configparser>=5.0.2
Requires-Dist: cryptography>=3.4
Provides-Extra: dev
Requires-Dist: autopep8>=1.5.7; extra == "dev"
Requires-Dist: pycodestyle>=2.7.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# Laavat Signing Solution CLI Tool

> ℹ️ **Example client** — This is Laavat's reference signing client. It is provided as-is; you are responsible for evaluating its suitability and security for your own production environment before relying on it. Releases are published with verifiable provenance (see [Verifying the download](#verifying-the-download)).

The `signing-tool` package provides the Laavat Signing Solution command-line client.
It supports client registration, product management, image signing, secrets management, and more via the SaaS API.

## Installation

Install from PyPI when released:

```bash
pip install signing-tool
```

## Verifying the download

Releases on PyPI are published with [PEP 740 digital attestations](https://docs.pypi.org/attestations/), signed via [Sigstore](https://www.sigstore.dev/). The attestation provides a publicly verifiable, transparency-logged link proving that a given `signing-tool` artifact was built and published by Laavat's official GitLab CI pipeline for this project — it lets you detect a tampered or substituted artifact before you run it.

You can see the attestation on the release's PyPI page (under the file's "Provenance" / "Verified details"). To verify a downloaded artifact yourself:

```bash
python3 -m pip install pypi-attestations
# Verify a published file directly against PyPI (downloads the file and its
# attestation for you); pass the exact released filename after "pypi:":
python3 -m pypi_attestations verify pypi \
    --repository https://gitlab.com/laavat/laavat-product/architecture/dist \
    pypi:signing_tool-<version>-py3-none-any.whl
```

A successful verification confirms the artifact's provenance (who built it, from which repository). What it does **not** do: it is not a guarantee about the *contents* of the code (it is provenance, not a security audit of the source).

> The `verify` command above works against production PyPI. (Attestation verification of TestPyPI artifacts is not supported by the current `pypi-attestations` release.)

A [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) listing the package's dependencies is produced for each release: it is bundled inside the source distribution (`.tar.gz`) as `sbom.json`, and is also published as a per-version build artifact (`signing-tool-sbom.json`) by the release pipeline.

## Quick Start

Display help:

```bash
signing-tool --help
```

### Secure token input

**Do not pass the token literally** (`-t "$TOKEN"`) and **do not store it inline in a config file** — in both cases the secret is exposed (shell history, process listings such as `ps` / `/proc/<pid>/cmdline`, or plaintext on disk). The tool accepts curl-style references that keep the secret out of the command line; in order of preference:

- **`-t @/path/to/tokenfile`** *(recommended)* — read the token from a **file** (the tool warns if the file is group/world-readable; use `chmod 600`):

  ```bash
  signing-tool -c -t @/run/secrets/jwt -a https://app.laavat.io/<CustomerName>/api/v1 product getall
  ```

- **`-t @-`** — read the token from **stdin**:

  ```bash
  printf '%s' "$TOKEN" | signing-tool -c -t @- -a https://app.laavat.io/<CustomerName>/api/v1 product getall
  ```

In a configuration file, reference the token by file instead of inlining it (an inline `token =` still works but is deprecated and warns on use):

```ini
[service]
url = https://app.laavat.io/<CustomerName>/api/v1
token_file = /run/secrets/jwt
```

These forms integrate cleanly with CI secret managers, which expose secrets as files or on stdin. TLS verification is on by default; `--skipssl` disables it and is intended for local development only.

> A leading `@` is interpreted as a stdin/file reference (the curl convention). OAuth2/JWT tokens never start with `@`, but if you ever need a literal token that does, escape it as `\@token`.

### Recommended usage

Supply the token without exposing it on the command line (see [Secure token input](#secure-token-input)), and keep the rest of the settings in a configuration file referenced with `-n`.

A configuration file that references the token by file (the token itself is never stored in the config):

```ini
# test.ini
[service]
url = https://app.laavat.io/<CustomerName>/api/v1
token_file = /run/secrets/jwt
```

```bash
signing-tool -n test.ini product getall
```

Or pass everything on the command line, reading the token from stdin:

```bash
printf '%s' "$TOKEN" | signing-tool -c -t @- -a https://app.laavat.io/<CustomerName>/api/v1 product getall
```

> TLS verification is on by default. `--skipssl` disables it and is for local development only.

### Configuration file

The config file has a single `[service]` section:

| Key | Description |
|-----|-------------|
| `url` | API address, e.g. `https://app.laavat.io/<CustomerName>/api/v1` |
| `token_file` | Path to a file containing the token (preferred — keeps the secret out of the config) |
| `token` | The token. `token = @/path/to/file` reads it from a file; an inline literal token is **deprecated** and warns on use |
| `skipssl` | `True` disables TLS verification (local development only); defaults to `False` |

You can generate a config file with the `config-init` helper. Prefer `-t @/path/to/tokenfile` so it writes a `token_file =` reference (the secret stays out of the config); `-t @-` reads the token from stdin; a literal `-t <token>` is written inline and warns. The file is created owner-only (`0600`) on POSIX.

```bash
config-init -n test.ini -t @/run/secrets/jwt -a https://app.laavat.io/<CustomerName>/api/v1
signing-tool -n test.ini product getall
```

### Quick test

For a quick one-off command without setting up a config file, pipe the token in via stdin (`-t @-`) so it stays out of your shell history and process listings:

```bash
printf '%s' "$TOKEN" | signing-tool -c -t @- -a https://app.laavat.io/<CustomerName>/api/v1 product getall
```

> **Note:** Some commands are interactive and prompt for input: `escrow add`, `group add`, and the `escrow`, `group` and `product` approvals. They cannot read the token from stdin, so do **not** use `-t @-` / `token = @-` with them; supply the token via `-t @/path/to/file` or a `token`/`token_file` entry in a `-n` config file instead. They have no machine-readable form either, and refuse `--json`.

> **Output files:** exports of secret or verification material (`secrets get`/`getkeys`, certificates, CSRs, `product getpubkey`, fusemaps) never overwrite an existing file and fail instead. Re-fetchable outputs — the JSON from `product get -O`/`group get -O` and the signed artifact from `imagesigning get -O` — are refreshed in place on every run. Signed artifacts follow your umask (`0644` under the usual `022`); only exported key material is `0600`.

### What `imagesigning get` verifies

Two different questions, answered by two different digests:

| Check | Answers | Default |
|---|---|---|
| `modifiedSHA256` (automatic) | Did the artifact arrive intact? | Always on; refuses to install on mismatch or when the service reports no digest |
| `originalSHA256` (`--expect-input FILE`) | Was it signed over the bytes I still hold? | Off — you have to name the file |

The first cannot answer the second. Approval is a human step that can take days, and over that gap the build tree moves — a rebuild, another branch, a stale request id in a resume file — so a perfectly intact artifact can carry a signature over an input you no longer have.

```bash
signing-tool -n test.ini imagesigning get -I "$RID" --wait \
    --expect-input u-boot.bin -O u-boot.bin.signed
```

The input is checked before the download, so a mismatch costs nothing. `--expect-input` requires `-I`, and a request reporting no input digest — usually one that is not Ready yet — is an error rather than a silent pass. `--allow-unverified` downgrades both checks to warnings.

## Requirements

- Python 3.8 or newer
- **SigningService** — The signing-tool CLI depends on the SigningService API client library. This is automatically installed when you install `signing-tool` from PyPI

## Packaging

This package is configured for PyPI distribution using `pyproject.toml` and `setuptools`.
Read the `pyproject.toml` file for package metadata and published package configuration.
