enprot 0.4.2

Engyon Protected Text (EPT) — confidentiality processor and capability ledger
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

<!-- Copyright (c) 2018-2026 [Ribose Inc](https://www.ribose.com). -->
<!--
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->

# Code-signing certificate support (issue #40, deferred)

Issue #40 asks for "support usage with code-signing certificates"
issued by DigiCert. The use case is under-specified. This document
captures the four plausible interpretations and what each would mean
for enprot's design, so any future initiative has a starting point.

## The four interpretations

### 1. Sign the enprot binary itself

Authenticode on Windows, `codesign` on macOS, GPG elsewhere. This is
purely a release-engineering concern: the `deploy.yml` workflow would
add signing steps that consume a signing key (from a secrets store, an
HSM, or a hardware token) and produce signed artifacts. No Rust code
in enprot itself.

Scope: small. Release engineering only.

### 2. Sign the output files enprot produces

So downstream consumers can verify provenance. Open questions:

- **What signature format?** CMS (PKCS#7), JWS, PGP, or a custom
  "openpgp-like" container.
- **Where does the signature live?** A sidecar `.sig` file? An additional
  EPT directive like `<( SIGNED BY ... )>`? An HTTP `Signature:` header
  (when EPT is transmitted over HTTP)?
- **What's signed?** The whole output file, or each `BEGIN..END` segment
  separately?

Scope: medium. Needs a signature-format decision and integration with
the EPT markup model.

### 3. Cert private key as the encryption key

Replaces the password with the cert's private key (or PBKDF-derived
key from a value the cert attests to). This bridges enprot's
password-centric model to a PKI one. Probably surfaced as a new KDF
"alg" (e.g. `x509-cert`) that pulls the key from a cert handle (file,
keychain, PIV token).

Scope: medium-large. Depends on cert-source abstraction (file vs
keychain vs PKCS#11), which is platform-specific.

### 4. Encrypt-to-certificate (PKI envelope)

Like CMS / S/MIME: encrypt segments *to* a certificate's public key
instead of a password-derived symmetric key. The biggest of the four
because it pulls in X.509 parsing, ASN.1, key transport, and a new
markup shape.

Scope: large. Botan has the primitives; the design work is in the wire
format and UX.

## What enprot has today

- The `pbkdf:` and `cipher:` extfield wire format is symmetric-only.
- The `CryptoPolicy` trait + `SymmetricCipher` trait are the obvious
  extension points for any of (2), (3), or (4).
- No code in `src/` touches certificates or signing today.

## Why this is deferred

Each of the four interpretations is a meaningfully different feature.
Picking one without the issue's reporter confirming cuts off the
others. A scope discussion with the original reporter (or product
owner) is the right next step.

If you're driving this initiative:

1. Pick one of the four interpretations above.
2. Write a design doc (`docs/<chosen-interpretation>-design.md`)
   describing the wire format, cert source, and CLI surface.
3. Add a new `src/pki.rs` (or similar) module that doesn't disturb the
   existing symmetric path. The `SymmetricCipher` trait is the wrong
   abstraction for signing — add a parallel trait.

## Close-the-issue criteria

This issue should stay open (or be re-opened) until a specific
interpretation is chosen and has a tracking issue with a clear scope.