27 |
27 |
28 import java.util.Map; |
28 import java.util.Map; |
29 import javax.security.auth.callback.CallbackHandler; |
29 import javax.security.auth.callback.CallbackHandler; |
30 |
30 |
31 /** |
31 /** |
32 * An interface for creating instances of <tt>SaslServer</tt>. |
32 * An interface for creating instances of {@code SaslServer}. |
33 * A class that implements this interface |
33 * A class that implements this interface |
34 * must be thread-safe and handle multiple simultaneous |
34 * must be thread-safe and handle multiple simultaneous |
35 * requests. It must also have a public constructor that accepts no |
35 * requests. It must also have a public constructor that accepts no |
36 * argument. |
36 * argument. |
37 *<p> |
37 *<p> |
38 * This interface is not normally accessed directly by a server, which will use the |
38 * This interface is not normally accessed directly by a server, which will use the |
39 * <tt>Sasl</tt> static methods |
39 * {@code Sasl} static methods |
40 * instead. However, a particular environment may provide and install a |
40 * instead. However, a particular environment may provide and install a |
41 * new or different <tt>SaslServerFactory</tt>. |
41 * new or different {@code SaslServerFactory}. |
42 * |
42 * |
43 * @since 1.5 |
43 * @since 1.5 |
44 * |
44 * |
45 * @see SaslServer |
45 * @see SaslServer |
46 * @see Sasl |
46 * @see Sasl |
48 * @author Rosanna Lee |
48 * @author Rosanna Lee |
49 * @author Rob Weltman |
49 * @author Rob Weltman |
50 */ |
50 */ |
51 public abstract interface SaslServerFactory { |
51 public abstract interface SaslServerFactory { |
52 /** |
52 /** |
53 * Creates a <tt>SaslServer</tt> using the parameters supplied. |
53 * Creates a {@code SaslServer} using the parameters supplied. |
54 * It returns null |
54 * It returns null |
55 * if no <tt>SaslServer</tt> can be created using the parameters supplied. |
55 * if no {@code SaslServer} can be created using the parameters supplied. |
56 * Throws <tt>SaslException</tt> if it cannot create a <tt>SaslServer</tt> |
56 * Throws {@code SaslException} if it cannot create a {@code SaslServer} |
57 * because of an error. |
57 * because of an error. |
58 * |
58 * |
59 * @param mechanism The non-null |
59 * @param mechanism The non-null |
60 * IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5"). |
60 * IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5"). |
61 * @param protocol The non-null string name of the protocol for which |
61 * @param protocol The non-null string name of the protocol for which |
62 * the authentication is being performed (e.g., "ldap"). |
62 * the authentication is being performed (e.g., "ldap"). |
63 * @param serverName The fully qualified host name of the server to |
63 * @param serverName The fully qualified host name of the server to |
64 * authenticate to, or null if the server is not bound to any specific host |
64 * authenticate to, or null if the server is not bound to any specific host |
65 * name. If the mechanism does not allow an unbound server, a |
65 * name. If the mechanism does not allow an unbound server, a |
66 * <code>SaslException</code> will be thrown. |
66 * {@code SaslException} will be thrown. |
67 * @param props The possibly null set of properties used to select the SASL |
67 * @param props The possibly null set of properties used to select the SASL |
68 * mechanism and to configure the authentication exchange of the selected |
68 * mechanism and to configure the authentication exchange of the selected |
69 * mechanism. See the <tt>Sasl</tt> class for a list of standard properties. |
69 * mechanism. See the {@code Sasl} class for a list of standard properties. |
70 * Other, possibly mechanism-specific, properties can be included. |
70 * Other, possibly mechanism-specific, properties can be included. |
71 * Properties not relevant to the selected mechanism are ignored, |
71 * Properties not relevant to the selected mechanism are ignored, |
72 * including any map entries with non-String keys. |
72 * including any map entries with non-String keys. |
73 * |
73 * |
74 * @param cbh The possibly null callback handler to used by the SASL |
74 * @param cbh The possibly null callback handler to used by the SASL |
75 * mechanisms to get further information from the application/library |
75 * mechanisms to get further information from the application/library |
76 * to complete the authentication. For example, a SASL mechanism might |
76 * to complete the authentication. For example, a SASL mechanism might |
77 * require the authentication ID, password and realm from the caller. |
77 * require the authentication ID, password and realm from the caller. |
78 * The authentication ID is requested by using a <tt>NameCallback</tt>. |
78 * The authentication ID is requested by using a {@code NameCallback}. |
79 * The password is requested by using a <tt>PasswordCallback</tt>. |
79 * The password is requested by using a {@code PasswordCallback}. |
80 * The realm is requested by using a <tt>RealmChoiceCallback</tt> if there is a list |
80 * The realm is requested by using a {@code RealmChoiceCallback} if there is a list |
81 * of realms to choose from, and by using a <tt>RealmCallback</tt> if |
81 * of realms to choose from, and by using a {@code RealmCallback} if |
82 * the realm must be entered. |
82 * the realm must be entered. |
83 * |
83 * |
84 *@return A possibly null <tt>SaslServer</tt> created using the parameters |
84 *@return A possibly null {@code SaslServer} created using the parameters |
85 * supplied. If null, this factory cannot produce a <tt>SaslServer</tt> |
85 * supplied. If null, this factory cannot produce a {@code SaslServer} |
86 * using the parameters supplied. |
86 * using the parameters supplied. |
87 *@exception SaslException If cannot create a <tt>SaslServer</tt> because |
87 *@exception SaslException If cannot create a {@code SaslServer} because |
88 * of an error. |
88 * of an error. |
89 */ |
89 */ |
90 public abstract SaslServer createSaslServer( |
90 public abstract SaslServer createSaslServer( |
91 String mechanism, |
91 String mechanism, |
92 String protocol, |
92 String protocol, |
96 |
96 |
97 /** |
97 /** |
98 * Returns an array of names of mechanisms that match the specified |
98 * Returns an array of names of mechanisms that match the specified |
99 * mechanism selection policies. |
99 * mechanism selection policies. |
100 * @param props The possibly null set of properties used to specify the |
100 * @param props The possibly null set of properties used to specify the |
101 * security policy of the SASL mechanisms. For example, if <tt>props</tt> |
101 * security policy of the SASL mechanisms. For example, if {@code props} |
102 * contains the <tt>Sasl.POLICY_NOPLAINTEXT</tt> property with the value |
102 * contains the {@code Sasl.POLICY_NOPLAINTEXT} property with the value |
103 * <tt>"true"</tt>, then the factory must not return any SASL mechanisms |
103 * {@code "true"}, then the factory must not return any SASL mechanisms |
104 * that are susceptible to simple plain passive attacks. |
104 * that are susceptible to simple plain passive attacks. |
105 * See the <tt>Sasl</tt> class for a complete list of policy properties. |
105 * See the {@code Sasl} class for a complete list of policy properties. |
106 * Non-policy related properties, if present in <tt>props</tt>, are ignored, |
106 * Non-policy related properties, if present in {@code props}, are ignored, |
107 * including any map entries with non-String keys. |
107 * including any map entries with non-String keys. |
108 * @return A non-null array containing a IANA-registered SASL mechanism names. |
108 * @return A non-null array containing a IANA-registered SASL mechanism names. |
109 */ |
109 */ |
110 public abstract String[] getMechanismNames(Map<String,?> props); |
110 public abstract String[] getMechanismNames(Map<String,?> props); |
111 } |
111 } |