1 /*******************************************************************************
2 * Copyright (c) 2012, 2014 Sonatype, Inc.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * Sonatype, Inc. - initial API and implementation
10 *******************************************************************************/
11 package org.eclipse.aether.repository;
12
13 import java.io.Closeable;
14 import java.io.File;
15 import java.util.Arrays;
16 import java.util.HashMap;
17 import java.util.Map;
18
19 import org.eclipse.aether.RepositorySystemSession;
20
21 /**
22 * A glorified map of key value pairs holding (cleartext) authentication data. Authentication contexts are used
23 * internally when network operations need to access secured repositories or proxies. Each authentication context
24 * manages the credentials required to access a single host. Unlike {@link Authentication} callbacks which exist for a
25 * potentially long time like the duration of a repository system session, an authentication context has a supposedly
26 * short lifetime and should be {@link #close() closed} as soon as the corresponding network operation has finished:
27 *
28 * <pre>
29 * AuthenticationContext context = AuthenticationContext.forRepository( session, repository );
30 * try {
31 * // get credentials
32 * char[] password = context.get( AuthenticationContext.PASSWORD, char[].class );
33 * // perform network operation using retrieved credentials
34 * ...
35 * } finally {
36 * // erase confidential authentication data from heap memory
37 * AuthenticationContext.close( context );
38 * }
39 * </pre>
40 *
41 * The same authentication data can often be presented using different data types, e.g. a password can be presented
42 * using a character array or (less securely) using a string. For ease of use, an authentication context treats the
43 * following groups of data types as equivalent and converts values automatically during retrieval:
44 * <ul>
45 * <li>{@code String}, {@code char[]}</li>
46 * <li>{@code String}, {@code File}</li>
47 * </ul>
48 * An authentication context is thread-safe.
49 */
50 public final class AuthenticationContext
51 implements Closeable
52 {
53
54 /**
55 * The key used to store the username. The corresponding authentication data should be of type {@link String}.
56 */
57 public static final String USERNAME = "username";
58
59 /**
60 * The key used to store the password. The corresponding authentication data should be of type {@code char[]} or
61 * {@link String}.
62 */
63 public static final String PASSWORD = "password";
64
65 /**
66 * The key used to store the NTLM domain. The corresponding authentication data should be of type {@link String}.
67 */
68 public static final String NTLM_DOMAIN = "ntlm.domain";
69
70 /**
71 * The key used to store the NTML workstation. The corresponding authentication data should be of type
72 * {@link String}.
73 */
74 public static final String NTLM_WORKSTATION = "ntlm.workstation";
75
76 /**
77 * The key used to store the pathname to a private key file. The corresponding authentication data should be of type
78 * {@link String} or {@link File}.
79 */
80 public static final String PRIVATE_KEY_PATH = "privateKey.path";
81
82 /**
83 * The key used to store the passphrase protecting the private key. The corresponding authentication data should be
84 * of type {@code char[]} or {@link String}.
85 */
86 public static final String PRIVATE_KEY_PASSPHRASE = "privateKey.passphrase";
87
88 /**
89 * The key used to store the acceptance policy for unknown host keys. The corresponding authentication data should
90 * be of type {@link Boolean}. When querying this authentication data, the extra data should provide
91 * {@link #HOST_KEY_REMOTE} and {@link #HOST_KEY_LOCAL}, e.g. to enable a well-founded decision of the user during
92 * an interactive prompt.
93 */
94 public static final String HOST_KEY_ACCEPTANCE = "hostKey.acceptance";
95
96 /**
97 * The key used to store the fingerprint of the public key advertised by remote host. Note that this key is used to
98 * query the extra data passed to {@link #get(String, Map, Class)} when getting {@link #HOST_KEY_ACCEPTANCE}, not
99 * the authentication data in a context.
100 */
101 public static final String HOST_KEY_REMOTE = "hostKey.remote";
102
103 /**
104 * The key used to store the fingerprint of the public key expected from remote host as recorded in a known hosts
105 * database. Note that this key is used to query the extra data passed to {@link #get(String, Map, Class)} when
106 * getting {@link #HOST_KEY_ACCEPTANCE}, not the authentication data in a context.
107 */
108 public static final String HOST_KEY_LOCAL = "hostKey.local";
109
110 /**
111 * The key used to store the SSL context. The corresponding authentication data should be of type
112 * {@link javax.net.ssl.SSLContext}.
113 */
114 public static final String SSL_CONTEXT = "ssl.context";
115
116 /**
117 * The key used to store the SSL hostname verifier. The corresponding authentication data should be of type
118 * {@link javax.net.ssl.HostnameVerifier}.
119 */
120 public static final String SSL_HOSTNAME_VERIFIER = "ssl.hostnameVerifier";
121
122 private final RepositorySystemSession session;
123
124 private final RemoteRepository repository;
125
126 private final Proxy proxy;
127
128 private final Authentication auth;
129
130 private final Map<String, Object> authData;
131
132 private boolean fillingAuthData;
133
134 /**
135 * Gets an authentication context for the specified repository.
136 *
137 * @param session The repository system session during which the repository is accessed, must not be {@code null}.
138 * @param repository The repository for which to create an authentication context, must not be {@code null}.
139 * @return An authentication context for the repository or {@code null} if no authentication is configured for it.
140 */
141 public static AuthenticationContext forRepository( RepositorySystemSession session, RemoteRepository repository )
142 {
143 return newInstance( session, repository, null, repository.getAuthentication() );
144 }
145
146 /**
147 * Gets an authentication context for the proxy of the specified repository.
148 *
149 * @param session The repository system session during which the repository is accessed, must not be {@code null}.
150 * @param repository The repository for whose proxy to create an authentication context, must not be {@code null}.
151 * @return An authentication context for the proxy or {@code null} if no proxy is set or no authentication is
152 * configured for it.
153 */
154 public static AuthenticationContext forProxy( RepositorySystemSession session, RemoteRepository repository )
155 {
156 Proxy proxy = repository.getProxy();
157 return newInstance( session, repository, proxy, ( proxy != null ) ? proxy.getAuthentication() : null );
158 }
159
160 private static AuthenticationContext newInstance( RepositorySystemSession session, RemoteRepository repository,
161 Proxy proxy, Authentication auth )
162 {
163 if ( auth == null )
164 {
165 return null;
166 }
167 return new AuthenticationContext( session, repository, proxy, auth );
168 }
169
170 private AuthenticationContext( RepositorySystemSession session, RemoteRepository repository, Proxy proxy,
171 Authentication auth )
172 {
173 if ( session == null )
174 {
175 throw new IllegalArgumentException( "repository system session missing" );
176 }
177 this.session = session;
178 this.repository = repository;
179 this.proxy = proxy;
180 this.auth = auth;
181 authData = new HashMap<String, Object>();
182 }
183
184 /**
185 * Gets the repository system session during which the authentication happens.
186 *
187 * @return The repository system session, never {@code null}.
188 */
189 public RepositorySystemSession getSession()
190 {
191 return session;
192 }
193
194 /**
195 * Gets the repository requiring authentication. If {@link #getProxy()} is not {@code null}, the data gathered by
196 * this authentication context does not apply to the repository's host but rather the proxy.
197 *
198 * @return The repository to be contacted, never {@code null}.
199 */
200 public RemoteRepository getRepository()
201 {
202 return repository;
203 }
204
205 /**
206 * Gets the proxy (if any) to be authenticated with.
207 *
208 * @return The proxy or {@code null} if authenticating directly with the repository's host.
209 */
210 public Proxy getProxy()
211 {
212 return proxy;
213 }
214
215 /**
216 * Gets the authentication data for the specified key.
217 *
218 * @param key The key whose authentication data should be retrieved, must not be {@code null}.
219 * @return The requested authentication data or {@code null} if none.
220 */
221 public String get( String key )
222 {
223 return get( key, null, String.class );
224 }
225
226 /**
227 * Gets the authentication data for the specified key.
228 *
229 * @param <T> The data type of the authentication data.
230 * @param key The key whose authentication data should be retrieved, must not be {@code null}.
231 * @param type The expected type of the authentication data, must not be {@code null}.
232 * @return The requested authentication data or {@code null} if none or if the data doesn't match the expected type.
233 */
234 public <T> T get( String key, Class<T> type )
235 {
236 return get( key, null, type );
237 }
238
239 /**
240 * Gets the authentication data for the specified key.
241 *
242 * @param <T> The data type of the authentication data.
243 * @param key The key whose authentication data should be retrieved, must not be {@code null}.
244 * @param data Any (read-only) extra data in form of key value pairs that might be useful when getting the
245 * authentication data, may be {@code null}.
246 * @param type The expected type of the authentication data, must not be {@code null}.
247 * @return The requested authentication data or {@code null} if none or if the data doesn't match the expected type.
248 */
249 public <T> T get( String key, Map<String, String> data, Class<T> type )
250 {
251 if ( key == null )
252 {
253 throw new IllegalArgumentException( "authentication data key missing" );
254 }
255 Object value;
256 synchronized ( authData )
257 {
258 value = authData.get( key );
259 if ( value == null && !authData.containsKey( key ) && !fillingAuthData )
260 {
261 if ( auth != null )
262 {
263 try
264 {
265 fillingAuthData = true;
266 auth.fill( this, key, data );
267 }
268 finally
269 {
270 fillingAuthData = false;
271 }
272 value = authData.get( key );
273 }
274 if ( value == null )
275 {
276 authData.put( key, value );
277 }
278 }
279 }
280
281 return convert( value, type );
282 }
283
284 private <T> T convert( Object value, Class<T> type )
285 {
286 if ( !type.isInstance( value ) )
287 {
288 if ( String.class.equals( type ) )
289 {
290 if ( value instanceof File )
291 {
292 value = ( (File) value ).getPath();
293 }
294 else if ( value instanceof char[] )
295 {
296 value = new String( (char[]) value );
297 }
298 }
299 else if ( File.class.equals( type ) )
300 {
301 if ( value instanceof String )
302 {
303 value = new File( (String) value );
304 }
305 }
306 else if ( char[].class.equals( type ) )
307 {
308 if ( value instanceof String )
309 {
310 value = ( (String) value ).toCharArray();
311 }
312 }
313 }
314
315 if ( type.isInstance( value ) )
316 {
317 return type.cast( value );
318 }
319
320 return null;
321 }
322
323 /**
324 * Puts the specified authentication data into this context. This method should only be called from implementors of
325 * {@link Authentication#fill(AuthenticationContext, String, Map)}. Passed in character arrays are not cloned and
326 * become owned by this context, i.e. get erased when the context gets closed.
327 *
328 * @param key The key to associate the authentication data with, must not be {@code null}.
329 * @param value The (cleartext) authentication data to store, may be {@code null}.
330 */
331 public void put( String key, Object value )
332 {
333 if ( key == null )
334 {
335 throw new IllegalArgumentException( "authentication data key missing" );
336 }
337 synchronized ( authData )
338 {
339 Object oldValue = authData.put( key, value );
340 if ( oldValue instanceof char[] )
341 {
342 Arrays.fill( (char[]) oldValue, '\0' );
343 }
344 }
345 }
346
347 /**
348 * Closes this authentication context and erases sensitive authentication data from heap memory. Closing an already
349 * closed context has no effect.
350 */
351 public void close()
352 {
353 synchronized ( authData )
354 {
355 for ( Object value : authData.values() )
356 {
357 if ( value instanceof char[] )
358 {
359 Arrays.fill( (char[]) value, '\0' );
360 }
361 }
362 authData.clear();
363 }
364 }
365
366 /**
367 * Closes the specified authentication context. This is a convenience method doing a {@code null} check before
368 * calling {@link #close()} on the given context.
369 *
370 * @param context The authentication context to close, may be {@code null}.
371 */
372 public static void close( AuthenticationContext context )
373 {
374 if ( context != null )
375 {
376 context.close();
377 }
378 }
379
380 }