signature.proto RawHistoryFolder

1// SPDX-License-Identifier: MIT
2
3syntax = "proto3";
4
5package ermite;
6
7import "google/protobuf/timestamp.proto";
8
9// SignatureFormat is the protocol of a commit signature.
10enum SignatureFormat {
11  // Not signed, or not set.
12  SIGNATURE_FORMAT_UNSPECIFIED = 0;
13  // Git SSH signature (gpg.format=ssh, "-----BEGIN SSH SIGNATURE-----").
14  SIGNATURE_FORMAT_SSH = 1;
15  // OpenPGP signature (gpg.format=openpgp, "-----BEGIN PGP SIGNATURE-----").
16  SIGNATURE_FORMAT_GPG = 2;
17  // X.509 (gpgsm) signature. Recognized, never verified.
18  SIGNATURE_FORMAT_X509 = 3;
19}
20
21// SignatureStatus is the outcome of checking the signature of a commit.
22enum SignatureStatus {
23  // The server did not check the commit (it could not be read).
24  SIGNATURE_STATUS_UNSPECIFIED = 0;
25  // The commit carries no signature.
26  SIGNATURE_STATUS_UNSIGNED = 1;
27  // Valid signature by a trusted key that is trusted for the committer email.
28  SIGNATURE_STATUS_VERIFIED = 2;
29  // Well-formed signature by a key the server does not trust.
30  SIGNATURE_STATUS_UNKNOWN_KEY = 3;
31  // The signature is malformed, does not match the commit, or uses a weak
32  // hash (SHA-1 and older).
33  SIGNATURE_STATUS_BAD_SIGNATURE = 4;
34  // Valid signature by a trusted key that is not trusted for the committer
35  // email.
36  SIGNATURE_STATUS_EMAIL_MISMATCH = 5;
37  // The OpenPGP key or signature had expired when the signature was made.
38  SIGNATURE_STATUS_EXPIRED = 6;
39  // The OpenPGP key is revoked.
40  SIGNATURE_STATUS_REVOKED = 7;
41  // The format is not verified by the server (X.509).
42  SIGNATURE_STATUS_UNSUPPORTED = 8;
43}
44
45// CommitVerification tells whether and how a commit is signed.
46message CommitVerification {
47  SignatureFormat format = 1;
48  SignatureStatus status = 2;
49  // Fingerprint of the signing key when the signature names one:
50  // "SHA256:<base64>" for SSH, upper-case hex for OpenPGP (the 16-digit
51  // issuer key id when the key is unknown).
52  string fingerprint = 3;
53  // KeyId is the id of the trusted key that matched; empty when none did.
54  string key_id = 4;
55  // KeyTitle is the title of the trusted key that matched.
56  string key_title = 5;
57}
58
59// TrustedKey is a public key whose signatures the server accepts for the
60// listed committer emails.
61message TrustedKey {
62  // Id is the key fingerprint: "SHA256:<base64>" for SSH, the primary key
63  // fingerprint in upper-case hex for OpenPGP.
64  string id = 1;
65  // Format is SIGNATURE_FORMAT_SSH or SIGNATURE_FORMAT_GPG.
66  SignatureFormat format = 2;
67  string title = 3;
68  // PublicKey is "<type> <base64>" for SSH, the armored public key for
69  // OpenPGP.
70  string public_key = 4;
71  // Emails are the committer emails the key may sign for, lower-case.
72  repeated string emails = 5;
73  google.protobuf.Timestamp created_at = 6;
74  // Builtin is true for the server's own signing key
75  // (ServerService.GetSigningKey): always trusted, cannot be removed.
76  bool builtin = 7;
77}
78
79// TrustedKeyService manages the keys commit signatures are checked against.
80// Servers that implement it list "commit_signatures" in
81// GetVersionResponse.features; their Commit messages then carry
82// verification.
83service TrustedKeyService {
84  // ListTrustedKeys lists the keys, the builtin key first. Any authenticated
85  // caller may.
86  rpc ListTrustedKeys(ListTrustedKeysRequest) returns (ListTrustedKeysResponse);
87  // AddTrustedKey adds a key. Owner only. invalid_argument for a key that
88  // does not parse, a private key, no or too many emails; already_exists for
89  // a key already listed; resource_exhausted beyond 100 keys.
90  rpc AddTrustedKey(AddTrustedKeyRequest) returns (AddTrustedKeyResponse);
91  // RemoveTrustedKey removes a key. Owner only. not_found for an unknown id;
92  // failed_precondition for the builtin key.
93  rpc RemoveTrustedKey(RemoveTrustedKeyRequest) returns (RemoveTrustedKeyResponse);
94}
95
96// ListTrustedKeysRequest is empty.
97message ListTrustedKeysRequest {}
98
99// ListTrustedKeysResponse lists every trusted key.
100message ListTrustedKeysResponse {
101  repeated TrustedKey keys = 1;
102}
103
104// AddTrustedKeyRequest describes the key to trust.
105message AddTrustedKeyRequest {
106  // Format is SIGNATURE_FORMAT_SSH or SIGNATURE_FORMAT_GPG.
107  SignatureFormat format = 1;
108  // Title is a label, 1 to 100 bytes.
109  string title = 2;
110  // PublicKey is an authorized_keys line for SSH, or an armored public key
111  // block for OpenPGP (at most 64 KiB).
112  string public_key = 3;
113  // Emails are the committer emails the key may sign for, 1 to 10.
114  repeated string emails = 4;
115}
116
117// AddTrustedKeyResponse returns the stored key.
118message AddTrustedKeyResponse {
119  TrustedKey key = 1;
120}
121
122// RemoveTrustedKeyRequest names the key to remove.
123message RemoveTrustedKeyRequest {
124  string id = 1;
125}
126
127// RemoveTrustedKeyResponse is empty.
128message RemoveTrustedKeyResponse {}