1 /* 2 * Copyright (C) 2020 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 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.api.errors.UnsupportedSigningFormatException; 16 import org.eclipse.jgit.transport.CredentialsProvider; 17 18 /** 19 * Creates GPG signatures for Git objects. 20 * 21 * @since 5.11 22 */ 23 public interface GpgObjectSigner { 24 25 /** 26 * Signs the specified object. 27 * 28 * <p> 29 * Implementors should obtain the payload for signing from the specified 30 * object via {@link ObjectBuilder#build()} and create a proper 31 * {@link GpgSignature}. The generated signature must be set on the 32 * specified {@code object} (see 33 * {@link ObjectBuilder#setGpgSignature(GpgSignature)}). 34 * </p> 35 * <p> 36 * Any existing signature on the object must be discarded prior obtaining 37 * the payload via {@link ObjectBuilder#build()}. 38 * </p> 39 * 40 * @param object 41 * the object to sign (must not be {@code null} and must be 42 * complete to allow proper calculation of payload) 43 * @param gpgSigningKey 44 * the signing key to locate (passed as is to the GPG signing 45 * tool as is; eg., value of <code>user.signingkey</code>) 46 * @param committer 47 * the signing identity (to help with key lookup in case signing 48 * key is not specified) 49 * @param credentialsProvider 50 * provider to use when querying for signing key credentials (eg. 51 * passphrase) 52 * @param config 53 * GPG settings from the git config 54 * @throws CanceledException 55 * when signing was canceled (eg., user aborted when entering 56 * passphrase) 57 * @throws UnsupportedSigningFormatException 58 * if a config is given and the wanted key format is not 59 * supported 60 */ 61 void signObject(@NonNull ObjectBuilder object, 62 @Nullable String gpgSigningKey, @NonNull PersonIdent committer, 63 CredentialsProvider credentialsProvider, GpgConfig config) 64 throws CanceledException, UnsupportedSigningFormatException; 65 66 /** 67 * Indicates if a signing key is available for the specified committer 68 * and/or signing key. 69 * 70 * @param gpgSigningKey 71 * the signing key to locate (passed as is to the GPG signing 72 * tool as is; eg., value of <code>user.signingkey</code>) 73 * @param committer 74 * the signing identity (to help with key lookup in case signing 75 * key is not specified) 76 * @param credentialsProvider 77 * provider to use when querying for signing key credentials (eg. 78 * passphrase) 79 * @param config 80 * GPG settings from the git config 81 * @return <code>true</code> if a signing key is available, 82 * <code>false</code> otherwise 83 * @throws CanceledException 84 * when signing was canceled (eg., user aborted when entering 85 * passphrase) 86 * @throws UnsupportedSigningFormatException 87 * if a config is given and the wanted key format is not 88 * supported 89 */ 90 public abstract boolean canLocateSigningKey(@Nullable String gpgSigningKey, 91 @NonNull PersonIdent committer, 92 CredentialsProvider credentialsProvider, GpgConfig config) 93 throws CanceledException, UnsupportedSigningFormatException; 94 95 }