1 /*
2 * Copyright (C) 2018, Salesforce. 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 org.eclipse.jgit.annotations.NonNull;
13 import org.eclipse.jgit.annotations.Nullable;
14 import org.eclipse.jgit.api.errors.CanceledException;
15 import org.eclipse.jgit.lib.internal.BouncyCastleGpgSigner;
16 import org.eclipse.jgit.transport.CredentialsProvider;
17
18 /**
19 * Creates GPG signatures for Git objects.
20 *
21 * @since 5.3
22 */
23 public abstract class GpgSigner {
24
25 private static GpgSigner defaultSigner = new BouncyCastleGpgSigner();
26
27 /**
28 * Get the default signer, or <code>null</code>.
29 *
30 * @return the default signer, or <code>null</code>.
31 */
32 public static GpgSigner getDefault() {
33 return defaultSigner;
34 }
35
36 /**
37 * Set the default signer.
38 *
39 * @param signer
40 * the new default signer, may be <code>null</code> to select no
41 * default.
42 */
43 public static void setDefault(GpgSigner signer) {
44 GpgSigner.defaultSigner = signer;
45 }
46
47 /**
48 * Signs the specified commit.
49 *
50 * <p>
51 * Implementors should obtain the payload for signing from the specified
52 * commit via {@link CommitBuilder#build()} and create a proper
53 * {@link GpgSignature}. The generated signature must be set on the
54 * specified {@code commit} (see
55 * {@link CommitBuilder#setGpgSignature(GpgSignature)}).
56 * </p>
57 * <p>
58 * Any existing signature on the commit must be discarded prior obtaining
59 * the payload via {@link CommitBuilder#build()}.
60 * </p>
61 *
62 * @param commit
63 * the commit to sign (must not be <code>null</code> and must be
64 * complete to allow proper calculation of payload)
65 * @param gpgSigningKey
66 * the signing key to locate (passed as is to the GPG signing
67 * tool as is; eg., value of <code>user.signingkey</code>)
68 * @param committer
69 * the signing identity (to help with key lookup in case signing
70 * key is not specified)
71 * @param credentialsProvider
72 * provider to use when querying for signing key credentials (eg.
73 * passphrase)
74 * @throws CanceledException
75 * when signing was canceled (eg., user aborted when entering
76 * passphrase)
77 */
78 public abstract void sign(@NonNull CommitBuilder commit,
79 @Nullable String gpgSigningKey, @NonNull PersonIdent committer,
80 CredentialsProvider credentialsProvider) throws CanceledException;
81
82 /**
83 * Indicates if a signing key is available for the specified committer
84 * and/or signing key.
85 *
86 * @param gpgSigningKey
87 * the signing key to locate (passed as is to the GPG signing
88 * tool as is; eg., value of <code>user.signingkey</code>)
89 * @param committer
90 * the signing identity (to help with key lookup in case signing
91 * key is not specified)
92 * @param credentialsProvider
93 * provider to use when querying for signing key credentials (eg.
94 * passphrase)
95 * @return <code>true</code> if a signing key is available,
96 * <code>false</code> otherwise
97 * @throws CanceledException
98 * when signing was canceled (eg., user aborted when entering
99 * passphrase)
100 */
101 public abstract boolean canLocateSigningKey(@Nullable String gpgSigningKey,
102 @NonNull PersonIdent committer,
103 CredentialsProvider credentialsProvider) throws CanceledException;
104
105 }