1 /*
2 * Copyright (C) 2021, Thomas Wolf <thomas.wolf@paranor.ch> and others
3 *
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Distribution License v. 1.0 which is available at
6 * https://www.eclipse.org/org/documents/edl-v10.php.
7 *
8 * SPDX-License-Identifier: BSD-3-Clause
9 */
10 package org.eclipse.jgit.lib;
11
12 import java.io.IOException;
13 import java.util.Date;
14
15 import org.eclipse.jgit.annotations.NonNull;
16 import org.eclipse.jgit.annotations.Nullable;
17 import org.eclipse.jgit.api.errors.JGitInternalException;
18 import org.eclipse.jgit.revwalk.RevObject;
19
20 /**
21 * A {@code GpgVerifier} can verify GPG signatures on git commits and tags.
22 *
23 * @since 5.11
24 */
25 public interface GpgSignatureVerifier {
26
27 /**
28 * Verifies the signature on a signed commit or tag.
29 *
30 * @param object
31 * to verify
32 * @param config
33 * the {@link GpgConfig} to use
34 * @return a {@link SignatureVerification} describing the outcome of the
35 * verification, or {@code null} if the object was not signed
36 * @throws IOException
37 * if an error occurs getting a public key
38 * @throws org.eclipse.jgit.api.errors.JGitInternalException
39 * if signature verification fails
40 */
41 @Nullable
42 SignatureVerification verifySignature(@NonNull RevObject object,
43 @NonNull GpgConfig config) throws IOException;
44
45
46 /**
47 * Verifies a given signature for given data.
48 *
49 * @param data
50 * the signature is for
51 * @param signatureData
52 * the ASCII-armored signature
53 * @return a {@link SignatureVerification} describing the outcome
54 * @throws IOException
55 * if the signature cannot be parsed
56 * @throws JGitInternalException
57 * if signature verification fails
58 */
59 public SignatureVerification verify(byte[] data, byte[] signatureData)
60 throws IOException;
61
62 /**
63 * Retrieves the name of this verifier. This should be a short string
64 * identifying the engine that verified the signature, like "gpg" if GPG is
65 * used, or "bc" for a BouncyCastle implementation.
66 *
67 * @return the name
68 */
69 @NonNull
70 String getName();
71
72 /**
73 * A {@link GpgSignatureVerifier} may cache public keys to speed up
74 * verifying signatures on multiple objects. This clears this cache, if any.
75 */
76 void clear();
77
78 /**
79 * A {@code SignatureVerification} returns data about a (positively or
80 * negatively) verified signature.
81 */
82 interface SignatureVerification {
83
84 // Data about the signature.
85
86 @NonNull
87 Date getCreationDate();
88
89 // Data from the signature used to find a public key.
90
91 /**
92 * Obtains the signer as stored in the signature, if known.
93 *
94 * @return the signer, or {@code null} if unknown
95 */
96 String getSigner();
97
98 /**
99 * Obtains the short or long fingerprint of the public key as stored in
100 * the signature, if known.
101 *
102 * @return the fingerprint, or {@code null} if unknown
103 */
104 String getKeyFingerprint();
105
106 // Some information about the found public key.
107
108 /**
109 * Obtains the OpenPGP user ID associated with the key.
110 *
111 * @return the user id, or {@code null} if unknown
112 */
113 String getKeyUser();
114
115 /**
116 * Tells whether the public key used for this signature verification was
117 * expired when the signature was created.
118 *
119 * @return {@code true} if the key was expired already, {@code false}
120 * otherwise
121 */
122 boolean isExpired();
123
124 /**
125 * Obtains the trust level of the public key used to verify the
126 * signature.
127 *
128 * @return the trust level
129 */
130 @NonNull
131 TrustLevel getTrustLevel();
132
133 // The verification result.
134
135 /**
136 * Tells whether the signature verification was successful.
137 *
138 * @return {@code true} if the signature was verified successfully;
139 * {@code false} if not.
140 */
141 boolean getVerified();
142
143 /**
144 * Obtains a human-readable message giving additional information about
145 * the outcome of the verification.
146 *
147 * @return the message, or {@code null} if none set.
148 */
149 String getMessage();
150 }
151
152 /**
153 * The owner's trust in a public key.
154 */
155 enum TrustLevel {
156 UNKNOWN, NEVER, MARGINAL, FULL, ULTIMATE
157 }
158 }