1 /*
2 * Copyright (C) 2018, 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.transport.sshd;
11
12 import java.io.IOException;
13 import java.security.GeneralSecurityException;
14
15 import org.eclipse.jgit.transport.URIish;
16
17 /**
18 * A {@code KeyPasswordProvider} provides passwords for encrypted private keys.
19 *
20 * @since 5.2
21 */
22 public interface KeyPasswordProvider {
23
24 /**
25 * Obtains a passphrase to use to decrypt an ecrypted private key. Returning
26 * {@code null} or an empty array will skip this key. To cancel completely,
27 * the operation should raise
28 * {@link java.util.concurrent.CancellationException}.
29 *
30 * @param uri
31 * identifying the key resource that is being attempted to be
32 * loaded
33 * @param attempt
34 * the number of previous attempts to get a passphrase; >= 0
35 * @return the passphrase
36 * @throws IOException
37 * if no password can be obtained
38 */
39 char[] getPassphrase(URIish uri, int attempt) throws IOException;
40
41 /**
42 * Define the maximum number of attempts to get a passphrase that should be
43 * attempted for one identity resource through this provider.
44 *
45 * @param maxNumberOfAttempts
46 * number of times to ask for a passphrase;
47 * {@link IllegalArgumentException} may be thrown if <= 0
48 */
49 void setAttempts(int maxNumberOfAttempts);
50
51 /**
52 * Gets the maximum number of attempts to get a passphrase that should be
53 * attempted for one identity resource through this provider. The default
54 * return 1.
55 *
56 * @return the number of times to ask for a passphrase; should be >= 1.
57 */
58 default int getAttempts() {
59 return 1;
60 }
61
62 /**
63 * Invoked after a key has been loaded. If this raises an exception, the
64 * original {@code error} is lost unless it is attached to that exception.
65 *
66 * @param uri
67 * identifying the key resource the key was attempted to be
68 * loaded from
69 * @param attempt
70 * the number of times {@link #getPassphrase(URIish, int)} had
71 * been called; zero indicates that {@code uri} refers to a
72 * non-encrypted key
73 * @param error
74 * {@code null} if the key was loaded successfully; otherwise an
75 * exception indicating why the key could not be loaded
76 * @return {@code true} to re-try again; {@code false} to re-raise the
77 * {@code error} exception; Ignored if the key was loaded
78 * successfully, i.e., if {@code error == null}.
79 * @throws IOException
80 * @throws GeneralSecurityException
81 */
82 boolean keyLoaded(URIish uri, int attempt, Exception error)
83 throws IOException, GeneralSecurityException;
84 }