1 /*
2 * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.security.sasl;
27
28 import javax.security.auth.callback.CallbackHandler;
29
30 import java.util.Enumeration;
31 import java.util.Iterator;
32 import java.util.Map;
33 import java.util.Set;
34 import java.util.HashSet;
35 import java.util.Collections;
36 import java.security.InvalidParameterException;
37 import java.security.NoSuchAlgorithmException;
38 import java.security.Provider;
39 import java.security.Provider.Service;
40 import java.security.Security;
41
42 /**
43 * A static class for creating SASL clients and servers.
44 *<p>
45 * This class defines the policy of how to locate, load, and instantiate
46 * SASL clients and servers.
47 *<p>
48 * For example, an application or library gets a SASL client by doing
49 * something like:
50 *<blockquote><pre>
51 * SaslClient sc = Sasl.createSaslClient(mechanisms,
52 * authorizationId, protocol, serverName, props, callbackHandler);
53 *</pre></blockquote>
54 * It can then proceed to use the instance to create an authentication connection.
55 *<p>
56 * Similarly, a server gets a SASL server by using code that looks as follows:
57 *<blockquote><pre>
58 * SaslServer ss = Sasl.createSaslServer(mechanism,
59 * protocol, serverName, props, callbackHandler);
60 *</pre></blockquote>
61 *
62 * @since 1.5
63 *
64 * @author Rosanna Lee
65 * @author Rob Weltman
66 */
67 public class Sasl {
68 // Cannot create one of these
69 private Sasl() {
70 }
71
72 /**
73 * The name of a property that specifies the quality-of-protection to use.
74 * The property contains a comma-separated, ordered list
75 * of quality-of-protection values that the
76 * client or server is willing to support. A qop value is one of
77 * <ul>
78 * <li>{@code "auth"} - authentication only</li>
79 * <li>{@code "auth-int"} - authentication plus integrity protection</li>
80 * <li>{@code "auth-conf"} - authentication plus integrity and confidentiality
81 * protection</li>
82 * </ul>
83 *
84 * The order of the list specifies the preference order of the client or
85 * server. If this property is absent, the default qop is {@code "auth"}.
86 * The value of this constant is {@code "javax.security.sasl.qop"}.
87 */
88 public static final String QOP = "javax.security.sasl.qop";
89
90 /**
91 * The name of a property that specifies the cipher strength to use.
92 * The property contains a comma-separated, ordered list
93 * of cipher strength values that
94 * the client or server is willing to support. A strength value is one of
95 * <ul>
96 * <li>{@code "low"}</li>
97 * <li>{@code "medium"}</li>
98 * <li>{@code "high"}</li>
99 * </ul>
100 * The order of the list specifies the preference order of the client or
101 * server. An implementation should allow configuration of the meaning
102 * of these values. An application may use the Java Cryptography
103 * Extension (JCE) with JCE-aware mechanisms to control the selection of
104 * cipher suites that match the strength values.
105 * <BR>
106 * If this property is absent, the default strength is
107 * {@code "high,medium,low"}.
108 * The value of this constant is {@code "javax.security.sasl.strength"}.
109 */
110 public static final String STRENGTH = "javax.security.sasl.strength";
111
112 /**
113 * The name of a property that specifies whether the
114 * server must authenticate to the client. The property contains
115 * {@code "true"} if the server must
116 * authenticate the to client; {@code "false"} otherwise.
117 * The default is {@code "false"}.
118 * <br>The value of this constant is
119 * {@code "javax.security.sasl.server.authentication"}.
120 */
121 public static final String SERVER_AUTH =
122 "javax.security.sasl.server.authentication";
123
124 /**
125 * The name of a property that specifies the bound server name for
126 * an unbound server. A server is created as an unbound server by setting
127 * the {@code serverName} argument in {@link #createSaslServer} as null.
128 * The property contains the bound host name after the authentication
129 * exchange has completed. It is only available on the server side.
130 * <br>The value of this constant is
131 * {@code "javax.security.sasl.bound.server.name"}.
132 */
133 public static final String BOUND_SERVER_NAME =
134 "javax.security.sasl.bound.server.name";
135
136 /**
137 * The name of a property that specifies the maximum size of the receive
138 * buffer in bytes of {@code SaslClient}/{@code SaslServer}.
139 * The property contains the string representation of an integer.
140 * <br>If this property is absent, the default size
141 * is defined by the mechanism.
142 * <br>The value of this constant is {@code "javax.security.sasl.maxbuffer"}.
143 */
144 public static final String MAX_BUFFER = "javax.security.sasl.maxbuffer";
145
146 /**
147 * The name of a property that specifies the maximum size of the raw send
148 * buffer in bytes of {@code SaslClient}/{@code SaslServer}.
149 * The property contains the string representation of an integer.
150 * The value of this property is negotiated between the client and server
151 * during the authentication exchange.
152 * <br>The value of this constant is {@code "javax.security.sasl.rawsendsize"}.
153 */
154 public static final String RAW_SEND_SIZE = "javax.security.sasl.rawsendsize";
155
156 /**
157 * The name of a property that specifies whether to reuse previously
158 * authenticated session information. The property contains "true" if the
159 * mechanism implementation may attempt to reuse previously authenticated
160 * session information; it contains "false" if the implementation must
161 * not reuse previously authenticated session information. A setting of
162 * "true" serves only as a hint: it does not necessarily entail actual
163 * reuse because reuse might not be possible due to a number of reasons,
164 * including, but not limited to, lack of mechanism support for reuse,
165 * expiration of reusable information, and the peer's refusal to support
166 * reuse.
167 *
168 * The property's default value is "false". The value of this constant
169 * is "javax.security.sasl.reuse".
170 *
171 * Note that all other parameters and properties required to create a
172 * SASL client/server instance must be provided regardless of whether
173 * this property has been supplied. That is, you cannot supply any less
174 * information in anticipation of reuse.
175 *
176 * Mechanism implementations that support reuse might allow customization
177 * of its implementation, for factors such as cache size, timeouts, and
178 * criteria for reusability. Such customizations are
179 * implementation-dependent.
180 */
181 public static final String REUSE = "javax.security.sasl.reuse";
182
183 /**
184 * The name of a property that specifies
185 * whether mechanisms susceptible to simple plain passive attacks (e.g.,
186 * "PLAIN") are not permitted. The property
187 * contains {@code "true"} if such mechanisms are not permitted;
188 * {@code "false"} if such mechanisms are permitted.
189 * The default is {@code "false"}.
190 * <br>The value of this constant is
191 * {@code "javax.security.sasl.policy.noplaintext"}.
192 */
193 public static final String POLICY_NOPLAINTEXT =
194 "javax.security.sasl.policy.noplaintext";
195
196 /**
197 * The name of a property that specifies whether
198 * mechanisms susceptible to active (non-dictionary) attacks
199 * are not permitted.
200 * The property contains {@code "true"}
201 * if mechanisms susceptible to active attacks
202 * are not permitted; {@code "false"} if such mechanisms are permitted.
203 * The default is {@code "false"}.
204 * <br>The value of this constant is
205 * {@code "javax.security.sasl.policy.noactive"}.
206 */
207 public static final String POLICY_NOACTIVE =
208 "javax.security.sasl.policy.noactive";
209
210 /**
211 * The name of a property that specifies whether
212 * mechanisms susceptible to passive dictionary attacks are not permitted.
213 * The property contains {@code "true"}
214 * if mechanisms susceptible to dictionary attacks are not permitted;
215 * {@code "false"} if such mechanisms are permitted.
216 * The default is {@code "false"}.
217 *<br>
218 * The value of this constant is
219 * {@code "javax.security.sasl.policy.nodictionary"}.
220 */
221 public static final String POLICY_NODICTIONARY =
222 "javax.security.sasl.policy.nodictionary";
223
224 /**
225 * The name of a property that specifies whether mechanisms that accept
226 * anonymous login are not permitted. The property contains {@code "true"}
227 * if mechanisms that accept anonymous login are not permitted;
228 * {@code "false"}
229 * if such mechanisms are permitted. The default is {@code "false"}.
230 *<br>
231 * The value of this constant is
232 * {@code "javax.security.sasl.policy.noanonymous"}.
233 */
234 public static final String POLICY_NOANONYMOUS =
235 "javax.security.sasl.policy.noanonymous";
236
237 /**
238 * The name of a property that specifies whether mechanisms that implement
239 * forward secrecy between sessions are required. Forward secrecy
240 * means that breaking into one session will not automatically
241 * provide information for breaking into future sessions.
242 * The property
243 * contains {@code "true"} if mechanisms that implement forward secrecy
244 * between sessions are required; {@code "false"} if such mechanisms
245 * are not required. The default is {@code "false"}.
246 *<br>
247 * The value of this constant is
248 * {@code "javax.security.sasl.policy.forward"}.
249 */
250 public static final String POLICY_FORWARD_SECRECY =
251 "javax.security.sasl.policy.forward";
252
253 /**
254 * The name of a property that specifies whether
255 * mechanisms that pass client credentials are required. The property
256 * contains {@code "true"} if mechanisms that pass
257 * client credentials are required; {@code "false"}
258 * if such mechanisms are not required. The default is {@code "false"}.
259 *<br>
260 * The value of this constant is
261 * {@code "javax.security.sasl.policy.credentials"}.
262 */
263 public static final String POLICY_PASS_CREDENTIALS =
264 "javax.security.sasl.policy.credentials";
265
266 /**
267 * The name of a property that specifies the credentials to use.
268 * The property contains a mechanism-specific Java credential object.
269 * Mechanism implementations may examine the value of this property
270 * to determine whether it is a class that they support.
271 * The property may be used to supply credentials to a mechanism that
272 * supports delegated authentication.
273 *<br>
274 * The value of this constant is
275 * {@code "javax.security.sasl.credentials"}.
276 */
277 public static final String CREDENTIALS = "javax.security.sasl.credentials";
278
279 /**
280 * Creates a {@code SaslClient} using the parameters supplied.
281 *
282 * This method uses the
283 <a href="{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#Provider">JCA Security Provider Framework</a>, described in the
284 * "Java Cryptography Architecture API Specification & Reference", for
285 * locating and selecting a {@code SaslClient} implementation.
286 *
287 * First, it
288 * obtains an ordered list of {@code SaslClientFactory} instances from
289 * the registered security providers for the "SaslClientFactory" service
290 * and the specified SASL mechanism(s). It then invokes
291 * {@code createSaslClient()} on each factory instance on the list
292 * until one produces a non-null {@code SaslClient} instance. It returns
293 * the non-null {@code SaslClient} instance, or null if the search fails
294 * to produce a non-null {@code SaslClient} instance.
295 *<p>
296 * A security provider for SaslClientFactory registers with the
297 * JCA Security Provider Framework keys of the form <br>
298 * {@code SaslClientFactory.}<em>{@code mechanism_name}</em>
299 * <br>
300 * and values that are class names of implementations of
301 * {@code javax.security.sasl.SaslClientFactory}.
302 *
303 * For example, a provider that contains a factory class,
304 * {@code com.wiz.sasl.digest.ClientFactory}, that supports the
305 * "DIGEST-MD5" mechanism would register the following entry with the JCA:
306 * {@code SaslClientFactory.DIGEST-MD5 com.wiz.sasl.digest.ClientFactory}
307 *<p>
308 * See the
309 * "Java Cryptography Architecture API Specification & Reference"
310 * for information about how to install and configure security service
311 * providers.
312 *
313 * @implNote
314 * The JDK Reference Implementation additionally uses the
315 * {@code jdk.security.provider.preferred}
316 * {@link Security#getProperty(String) Security} property to determine
317 * the preferred provider order for the specified algorithm. This
318 * may be different than the order of providers returned by
319 * {@link Security#getProviders() Security.getProviders()}.
320 *
321 * @param mechanisms The non-null list of mechanism names to try. Each is the
322 * IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5").
323 * @param authorizationId The possibly null protocol-dependent
324 * identification to be used for authorization.
325 * If null or empty, the server derives an authorization
326 * ID from the client's authentication credentials.
327 * When the SASL authentication completes successfully,
328 * the specified entity is granted access.
329 *
330 * @param protocol The non-null string name of the protocol for which
331 * the authentication is being performed (e.g., "ldap").
332 *
333 * @param serverName The non-null fully-qualified host name of the server
334 * to authenticate to.
335 *
336 * @param props The possibly null set of properties used to
337 * select the SASL mechanism and to configure the authentication
338 * exchange of the selected mechanism.
339 * For example, if {@code props} contains the
340 * {@code Sasl.POLICY_NOPLAINTEXT} property with the value
341 * {@code "true"}, then the selected
342 * SASL mechanism must not be susceptible to simple plain passive attacks.
343 * In addition to the standard properties declared in this class,
344 * other, possibly mechanism-specific, properties can be included.
345 * Properties not relevant to the selected mechanism are ignored,
346 * including any map entries with non-String keys.
347 *
348 * @param cbh The possibly null callback handler to used by the SASL
349 * mechanisms to get further information from the application/library
350 * to complete the authentication. For example, a SASL mechanism might
351 * require the authentication ID, password and realm from the caller.
352 * The authentication ID is requested by using a {@code NameCallback}.
353 * The password is requested by using a {@code PasswordCallback}.
354 * The realm is requested by using a {@code RealmChoiceCallback} if there is a list
355 * of realms to choose from, and by using a {@code RealmCallback} if
356 * the realm must be entered.
357 *
358 *@return A possibly null {@code SaslClient} created using the parameters
359 * supplied. If null, cannot find a {@code SaslClientFactory}
360 * that will produce one.
361 *@exception SaslException If cannot create a {@code SaslClient} because
362 * of an error.
363 */
364 public static SaslClient createSaslClient(
365 String[] mechanisms,
366 String authorizationId,
367 String protocol,
368 String serverName,
369 Map<String,?> props,
370 CallbackHandler cbh) throws SaslException {
371
372 SaslClient mech = null;
373 SaslClientFactory fac;
374 Service service;
375 String mechName;
376
377 for (int i = 0; i < mechanisms.length; i++) {
378 if ((mechName=mechanisms[i]) == null) {
379 throw new NullPointerException(
380 "Mechanism name cannot be null");
381 } else if (mechName.length() == 0) {
382 continue;
383 }
384 String type = "SaslClientFactory";
385 Provider[] provs = Security.getProviders(type + "." + mechName);
386 if (provs != null) {
387 for (Provider p : provs) {
388 service = p.getService(type, mechName);
389 if (service == null) {
390 // no such service exists
391 continue;
392 }
393
394 fac = (SaslClientFactory) loadFactory(service);
395 if (fac != null) {
396 mech = fac.createSaslClient(
397 new String[]{mechanisms[i]}, authorizationId,
398 protocol, serverName, props, cbh);
399 if (mech != null) {
400 return mech;
401 }
402 }
403 }
404 }
405 }
406 return null;
407 }
408
409 private static Object loadFactory(Service service)
410 throws SaslException {
411 try {
412 /*
413 * Load the implementation class with the same class loader
414 * that was used to load the provider.
415 * In order to get the class loader of a class, the
416 * caller's class loader must be the same as or an ancestor of
417 * the class loader being returned. Otherwise, the caller must
418 * have "getClassLoader" permission, or a SecurityException
419 * will be thrown.
420 */
421 return service.newInstance(null);
422 } catch (InvalidParameterException | NoSuchAlgorithmException e) {
423 throw new SaslException("Cannot instantiate service " + service, e);
424 }
425 }
426
427
428 /**
429 * Creates a {@code SaslServer} for the specified mechanism.
430 *
431 * This method uses the
432 <a href="{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#Provider">JCA Security Provider Framework</a>,
433 * described in the
434 * "Java Cryptography Architecture API Specification & Reference", for
435 * locating and selecting a {@code SaslServer} implementation.
436 *
437 * First, it
438 * obtains an ordered list of {@code SaslServerFactory} instances from
439 * the registered security providers for the "SaslServerFactory" service
440 * and the specified mechanism. It then invokes
441 * {@code createSaslServer()} on each factory instance on the list
442 * until one produces a non-null {@code SaslServer} instance. It returns
443 * the non-null {@code SaslServer} instance, or null if the search fails
444 * to produce a non-null {@code SaslServer} instance.
445 *<p>
446 * A security provider for SaslServerFactory registers with the
447 * JCA Security Provider Framework keys of the form <br>
448 * {@code SaslServerFactory.}<em>{@code mechanism_name}</em>
449 * <br>
450 * and values that are class names of implementations of
451 * {@code javax.security.sasl.SaslServerFactory}.
452 *
453 * For example, a provider that contains a factory class,
454 * {@code com.wiz.sasl.digest.ServerFactory}, that supports the
455 * "DIGEST-MD5" mechanism would register the following entry with the JCA:
456 * {@code SaslServerFactory.DIGEST-MD5 com.wiz.sasl.digest.ServerFactory}
457 *<p>
458 * See the
459 * "Java Cryptography Architecture API Specification & Reference"
460 * for information about how to install and configure security
461 * service providers.
462 *
463 * @implNote
464 * The JDK Reference Implementation additionally uses the
465 * {@code jdk.security.provider.preferred}
466 * {@link Security#getProperty(String) Security} property to determine
467 * the preferred provider order for the specified algorithm. This
468 * may be different than the order of providers returned by
469 * {@link Security#getProviders() Security.getProviders()}.
470 *
471 * @param mechanism The non-null mechanism name. It must be an
472 * IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5").
473 * @param protocol The non-null string name of the protocol for which
474 * the authentication is being performed (e.g., "ldap").
475 * @param serverName The fully qualified host name of the server, or null
476 * if the server is not bound to any specific host name. If the mechanism
477 * does not allow an unbound server, a {@code SaslException} will
478 * be thrown.
479 * @param props The possibly null set of properties used to
480 * select the SASL mechanism and to configure the authentication
481 * exchange of the selected mechanism.
482 * For example, if {@code props} contains the
483 * {@code Sasl.POLICY_NOPLAINTEXT} property with the value
484 * {@code "true"}, then the selected
485 * SASL mechanism must not be susceptible to simple plain passive attacks.
486 * In addition to the standard properties declared in this class,
487 * other, possibly mechanism-specific, properties can be included.
488 * Properties not relevant to the selected mechanism are ignored,
489 * including any map entries with non-String keys.
490 *
491 * @param cbh The possibly null callback handler to used by the SASL
492 * mechanisms to get further information from the application/library
493 * to complete the authentication. For example, a SASL mechanism might
494 * require the authentication ID, password and realm from the caller.
495 * The authentication ID is requested by using a {@code NameCallback}.
496 * The password is requested by using a {@code PasswordCallback}.
497 * The realm is requested by using a {@code RealmChoiceCallback} if there is a list
498 * of realms to choose from, and by using a {@code RealmCallback} if
499 * the realm must be entered.
500 *
501 *@return A possibly null {@code SaslServer} created using the parameters
502 * supplied. If null, cannot find a {@code SaslServerFactory}
503 * that will produce one.
504 *@exception SaslException If cannot create a {@code SaslServer} because
505 * of an error.
506 **/
507 public static SaslServer
508 createSaslServer(String mechanism,
509 String protocol,
510 String serverName,
511 Map<String,?> props,
512 javax.security.auth.callback.CallbackHandler cbh)
513 throws SaslException {
514
515 SaslServer mech = null;
516 SaslServerFactory fac;
517 Service service;
518
519 if (mechanism == null) {
520 throw new NullPointerException("Mechanism name cannot be null");
521 } else if (mechanism.length() == 0) {
522 return null;
523 }
524
525 String type = "SaslServerFactory";
526 Provider[] provs = Security.getProviders(type + "." + mechanism);
527 if (provs != null) {
528 for (Provider p : provs) {
529 service = p.getService(type, mechanism);
530 if (service == null) {
531 throw new SaslException("Provider does not support " +
532 mechanism + " " + type);
533 }
534 fac = (SaslServerFactory) loadFactory(service);
535 if (fac != null) {
536 mech = fac.createSaslServer(
537 mechanism, protocol, serverName, props, cbh);
538 if (mech != null) {
539 return mech;
540 }
541 }
542 }
543 }
544 return null;
545 }
546
547 /**
548 * Gets an enumeration of known factories for producing {@code SaslClient}.
549 * This method uses the same algorithm for locating factories as
550 * {@code createSaslClient()}.
551 * @return A non-null enumeration of known factories for producing
552 * {@code SaslClient}.
553 * @see #createSaslClient
554 */
555 public static Enumeration<SaslClientFactory> getSaslClientFactories() {
556 Set<Object> facs = getFactories("SaslClientFactory");
557 final Iterator<Object> iter = facs.iterator();
558 return new Enumeration<SaslClientFactory>() {
559 public boolean hasMoreElements() {
560 return iter.hasNext();
561 }
562 public SaslClientFactory nextElement() {
563 return (SaslClientFactory)iter.next();
564 }
565 };
566 }
567
568 /**
569 * Gets an enumeration of known factories for producing {@code SaslServer}.
570 * This method uses the same algorithm for locating factories as
571 * {@code createSaslServer()}.
572 * @return A non-null enumeration of known factories for producing
573 * {@code SaslServer}.
574 * @see #createSaslServer
575 */
576 public static Enumeration<SaslServerFactory> getSaslServerFactories() {
577 Set<Object> facs = getFactories("SaslServerFactory");
578 final Iterator<Object> iter = facs.iterator();
579 return new Enumeration<SaslServerFactory>() {
580 public boolean hasMoreElements() {
581 return iter.hasNext();
582 }
583 public SaslServerFactory nextElement() {
584 return (SaslServerFactory)iter.next();
585 }
586 };
587 }
588
589 private static Set<Object> getFactories(String serviceName) {
590 HashSet<Object> result = new HashSet<Object>();
591
592 if ((serviceName == null) || (serviceName.length() == 0) ||
593 (serviceName.endsWith("."))) {
594 return result;
595 }
596
597 Provider[] provs = Security.getProviders();
598 Object fac;
599
600 for (Provider p : provs) {
601
602 Iterator<Service> iter = p.getServices().iterator();
603 while (iter.hasNext()) {
604 Service s = iter.next();
605 if (s.getType().equals(serviceName)) {
606 try {
607 fac = loadFactory(s);
608 if (fac != null) {
609 result.add(fac);
610 }
611 } catch (Exception ignore) {
612 }
613 }
614 }
615 }
616 return Collections.unmodifiableSet(result);
617 }
618 }