001: /*
002: * ====================================================================
003: * Copyright (c) 2004-2008 TMate Software Ltd. All rights reserved.
004: *
005: * This software is licensed as described in the file COPYING, which
006: * you should have received as part of this distribution. The terms
007: * are also available at http://svnkit.com/license.html
008: * If newer versions of this license are posted there, you may use a
009: * newer version instead, at your option.
010: * ====================================================================
011: */
012: package org.tmatesoft.svn.core.auth;
013:
014: import org.tmatesoft.svn.core.SVNErrorMessage;
015: import org.tmatesoft.svn.core.SVNException;
016: import org.tmatesoft.svn.core.SVNURL;
017: import org.tmatesoft.svn.core.io.SVNRepository;
018:
019: /**
020: * The <b>ISVNAuthenticationManager</b> is implemented by manager
021: * classes used by <b>SVNRepository</b> drivers for user authentication purposes.
022: *
023: * <p>
024: * When an <b>SVNRepository</b> driver is created, you should provide an
025: * authentication manager via a call to:
026: * <pre class="javacode">
027: * <span class="javakeyword">import</span> org.tmatesoft.svn.core.io.SVNRepository;
028: * <span class="javakeyword">import</span> org.tmatesoft.svn.core.auth.ISVNAuthenticationManager;
029: * ...
030: * SVNRepository repository;
031: * ISVNAuthenticationManager authManger;
032: * ...
033: *
034: * repository.setAuthenticationManager(authManager);
035: * ...</pre>
036: *
037: * <p>
038: * SVNKit provides a default authentication manager implementation - <b>org.tmatesoft.svn.core.internal.wc.DefaultSVNAuthenticationManager</b>.
039: * This manager has got the following features:
040: * <ul>
041: * <li> uses the auth storage from the default Subversion runtime configuration area;
042: * <li> may use the auth storage in the directory you specify;
043: * <li> uses the ssh, ssl & proxy options from the standard <i>config</i> and <i>servers</i> files;
044: * <li> stores credentials in the in-memory cache during runtime;
045: * </ul>
046: * You may also specify your own auth provider (<b>ISVNAuthenticationProvider</b>) to this default manager, it
047: * will be used along with those default ones, that implement the features listed above.
048: *
049: * <p>
050: * If using the https:// protocol and if no user's authentication provider implementation is set to the
051: * default manager, server certificates are accepted temporarily and therefore are not cached on the disk.
052: * To enable server CAs caching, a user should set an authentication provider implementation which
053: * {@link ISVNAuthenticationProvider#acceptServerAuthentication(SVNURL, String, Object, boolean) acceptServerAuthentication()}
054: * method must return {@link ISVNAuthenticationProvider#ACCEPTED}. That will switch on certificate on-the-disk caching.
055: *
056: * <p>
057: * How to get a default auth manager instance see {@link org.tmatesoft.svn.core.wc.SVNWCUtil}.
058: *
059: * @version 1.1.1
060: * @author TMate Software Ltd.
061: * @see org.tmatesoft.svn.core.io.SVNRepository
062: */
063: public interface ISVNAuthenticationManager {
064: /**
065: * A simple password credential kind (<span class="javastring">"svn.simple"</span>)
066: */
067: public static final String PASSWORD = "svn.simple";
068: /**
069: * An ssh credential kind (<span class="javastring">"svn.ssh"</span>)
070: */
071: public static final String SSH = "svn.ssh";
072: /**
073: * An ssl credential kind (<span class="javastring">"svn.ssl"</span>)
074: */
075: public static final String SSL = "svn.ssl";
076:
077: /**
078: * A simple username credential kind (<span class="javastring">"svn.username"</span>).
079: * Only usernames are cached/provided matched against an appropriate
080: * realms (which are repository UUIDs in this case). In particular this kind is
081: * used in <code>file:///</code> and <code>svn+ssh://</code> access schemes.
082: */
083: public static final String USERNAME = "svn.username";
084:
085: /**
086: * Sets a custom authentication provider that will provide user
087: * credentials for authentication.
088: *
089: * @param provider an authentication provider
090: */
091: public void setAuthenticationProvider(
092: ISVNAuthenticationProvider provider);
093:
094: /**
095: * Returns a proxy manager that keeps settings for that proxy
096: * server over which HTTP requests are send to a repository server.
097: *
098: * <p>
099: * A default auth manager uses proxy settings from the standard <i>servers</i>
100: * file.
101: *
102: * @param url a repository location that will be accessed
103: * over the proxy server for which a manager is needed
104: * @return a proxy manager
105: * @throws SVNException
106: */
107: public ISVNProxyManager getProxyManager(SVNURL url)
108: throws SVNException;
109:
110: /**
111: * Returns the SSL manager for secure interracting with a
112: * repository.
113: *
114: * <p>
115: * A default implementation of <b>ISVNAuthenticationManager</b> returns an
116: * SSL manager that uses CA and user certificate files specified in the
117: * standard <i>servers</i> file.
118: *
119: * <p>
120: * Even if the default manager's <b>getSSLManager()</b> method returns
121: * <span class="javakeyword">null</span> for the given <code>url</code>, a secure
122: * context will be created anymore, but, of course no user certificate files are provided
123: * to a server as well as server's certificates are not checked.
124: *
125: * @param url a repository location to access
126: * @return an appropriate SSL manager
127: * @throws SVNException
128: */
129: public ISVNSSLManager getSSLManager(SVNURL url) throws SVNException;
130:
131: /**
132: * Retrieves the first user credential.
133: *
134: * The scheme of retrieving credentials:
135: * <ul>
136: * <li>For the first try to authenticate a user to a repository (using the
137: * specifed realm) an <b>SVNRepository</b> driver calls
138: * <b>getFirstAuthentication()</b> and sends the retrieved credential.
139: * <li>If the credential is accepted, it may be stored. If not, the driver
140: * calls {@link #getNextAuthentication(String, String, SVNURL) getNextAuthentication()}
141: * and sends the next credential.
142: * <li>If the last credential was not accepted, the driver still tries to get the next
143: * credential for the same realm.
144: * </ul>
145: *
146: * <p>
147: * For each credential <code>kind</code> an implementor should return a kind-specific
148: * credential. The following table matches kinds to proper credential classes:
149: *
150: * <table cellpadding="3" cellspacing="1" border="0" width="60%" bgcolor="#999933">
151: * <tr bgcolor="#ADB8D9" align="left">
152: * <td><b>Credential Kind</b></td>
153: * <td><b>Credential Class</b></td>
154: * </tr>
155: * <tr bgcolor="#EAEAEA" align="left">
156: * <td>{@link #PASSWORD}</td><td>{@link SVNPasswordAuthentication}</td>
157: * </tr>
158: * <tr bgcolor="#EAEAEA" align="left">
159: * <td>{@link #SSH}</td><td>{@link SVNSSHAuthentication}</td>
160: * </tr>
161: * <tr bgcolor="#EAEAEA" align="left">
162: * <td>{@link #SSL}</td><td>{@link SVNSSLAuthentication}</td>
163: * </tr>
164: * <tr bgcolor="#EAEAEA" align="left">
165: * <td>{@link #USERNAME}</td><td>{@link SVNUserNameAuthentication}</td>
166: * </tr>
167: * </table>
168: *
169: * @param kind a credential kind
170: * @param realm a repository authentication realm
171: * @param url a repository location that is to be accessed
172: * @return the first try user credential
173: * @throws SVNException
174: */
175: public SVNAuthentication getFirstAuthentication(String kind,
176: String realm, SVNURL url) throws SVNException;
177:
178: /**
179: * Retrieves the next user credential if the first try failed.
180: *
181: * The scheme of retrieving credentials:
182: * <ul>
183: * <li>For the first try to authenticate a user to a repository (using the
184: * specifed realm) an <b>SVNRepository</b> driver calls
185: * {@link #getFirstAuthentication(String, String, SVNURL) getFirstAuthentication()} and
186: * sends the retrieved credential.
187: * <li>If the credential is accepted, it may be stored. If not, the driver
188: * calls <b>getNextAuthentication()</b> and sends the next credential.
189: * <li>If the last credential was not accepted, the driver still tries to get the next
190: * credential for the same realm.
191: * </ul>
192: *
193: * <p>
194: * For each credential <code>kind</code> an implementor should return a kind-specific
195: * credential. The following table matches kinds to proper credential classes:
196: *
197: * <table cellpadding="3" cellspacing="1" border="0" width="60%" bgcolor="#999933">
198: * <tr bgcolor="#ADB8D9" align="left">
199: * <td><b>Credential Kind</b></td>
200: * <td><b>Credential Class</b></td>
201: * </tr>
202: * <tr bgcolor="#EAEAEA" align="left">
203: * <td>{@link #PASSWORD}</td><td>{@link SVNPasswordAuthentication}</td>
204: * </tr>
205: * <tr bgcolor="#EAEAEA" align="left">
206: * <td>{@link #SSH}</td><td>{@link SVNSSHAuthentication}</td>
207: * </tr>
208: * <tr bgcolor="#EAEAEA" align="left">
209: * <td>{@link #SSL}</td><td>{@link SVNSSLAuthentication}</td>
210: * </tr>
211: * <tr bgcolor="#EAEAEA" align="left">
212: * <td>{@link #USERNAME}</td><td>{@link SVNUserNameAuthentication}</td>
213: * </tr>
214: * </table>
215: *
216: * @param kind a credential kind
217: * @param realm a repository authentication realm
218: * @param url a repository location that is to be accessed
219: * @return the next try user credential
220: * @throws SVNException
221: */
222: public SVNAuthentication getNextAuthentication(String kind,
223: String realm, SVNURL url) throws SVNException;
224:
225: /**
226: * Accepts the given authentication if it was successfully accepted by a
227: * repository server, or not if authentication failed. As a result the
228: * provided credential may be cached (authentication succeeded) or deleted
229: * from the cache (authentication failed).
230: *
231: * @param accepted <span class="javakeyword">true</span> if
232: * the credential was accepted by the server,
233: * otherwise <span class="javakeyword">false</span>
234: * @param kind a credential kind ({@link #PASSWORD} or {@link #SSH} or {@link #USERNAME})
235: * @param realm a repository authentication realm
236: * @param errorMessage the reason of the authentication failure
237: * @param authentication a user credential to accept/drop
238: * @throws SVNException
239: */
240: public void acknowledgeAuthentication(boolean accepted,
241: String kind, String realm, SVNErrorMessage errorMessage,
242: SVNAuthentication authentication) throws SVNException;
243:
244: /**
245: * Sets a specific runtime authentication storage manager. This storage
246: * manager will be asked by this auth manager for cached credentials as
247: * well as used to cache new ones accepted recently.
248: *
249: * @param storage a custom auth storage manager
250: */
251: public void setRuntimeStorage(ISVNAuthenticationStorage storage);
252:
253: /**
254: * Checks whether client should send authentication credentials to
255: * a repository server not waiting for the server's challenge.
256: *
257: * <p>
258: * In some cases it may be necessary to send credentials beforehand,
259: * not waiting until the server asks to do it itself. To achieve
260: * such behaviour an implementor should return <span class="javakeyword">true</span>
261: * from this routine.
262: *
263: * @return <span class="javakeyword">true</span> if authentication
264: * credentials are forced to be sent;<span class="javakeyword">false</span>
265: * when credentials are to be sent only in response to a server challenge
266: *
267: * @see #setAuthenticationForced(boolean)
268: */
269: public boolean isAuthenticationForced();
270:
271: /**
272: * Specifies the way how credentials are to be supplied to a
273: * repository server.
274: *
275: * @param forced <span class="javakeyword">true</span> to force
276: * credentials sending; <span class="javakeyword">false</span>
277: * to put off sending credentials till a server challenge
278: * @see #isAuthenticationForced()
279: */
280: public void setAuthenticationForced(boolean forced);
281:
282: /**
283: * Returns a connection timeout value.
284: *
285: * @param repository a repository access driver
286: * @return connection timeout value
287: * @since 1.1
288: */
289: public long getHTTPTimeout(SVNRepository repository);
290: }
|