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.internal.transport.sshd.auth;
11
12 import java.io.Closeable;
13
14 /**
15 * An {@code AuthenticationHandler} encapsulates a possibly multi-step
16 * authentication protocol. Intended usage:
17 *
18 * <pre>
19 * setParams(something);
20 * start();
21 * sendToken(getToken());
22 * while (!isDone()) {
23 * setParams(receiveMessageAndExtractParams());
24 * process();
25 * Object t = getToken();
26 * if (t != null) {
27 * sendToken(t);
28 * }
29 * }
30 * </pre>
31 *
32 * An {@code AuthenticationHandler} may be stateful and therefore is a
33 * {@link Closeable}.
34 *
35 * @param <ParameterType>
36 * defining the parameter type for {@link #setParams(Object)}
37 * @param <TokenType>
38 * defining the token type for {@link #getToken()}
39 */
40 public interface AuthenticationHandler<ParameterType, TokenType>
41 extends Closeable {
42
43 /**
44 * Produces the initial authentication token that can be then retrieved via
45 * {@link #getToken()}.
46 *
47 * @throws Exception
48 * if an error occurs
49 */
50 void start() throws Exception;
51
52 /**
53 * Produces the next authentication token, if any.
54 *
55 * @throws Exception
56 * if an error occurs
57 */
58 void process() throws Exception;
59
60 /**
61 * Sets the parameters for the next token generation via {@link #start()} or
62 * {@link #process()}.
63 *
64 * @param input
65 * to set, may be {@code null}
66 */
67 void setParams(ParameterType input);
68
69 /**
70 * Retrieves the last token generated.
71 *
72 * @return the token, or {@code null} if there is none
73 * @throws Exception
74 * if an error occurs
75 */
76 TokenType getToken() throws Exception;
77
78 /**
79 * Tells whether is authentication mechanism is done (successfully or
80 * unsuccessfully).
81 *
82 * @return whether this authentication is done
83 */
84 boolean isDone();
85
86 @Override
87 void close();
88 }