1 /*
2  * Copyright (c) 2003, 2019, 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 java.security;
27 
28 import javax.security.auth.Subject;
29 import javax.security.auth.login.LoginException;
30 import javax.security.auth.callback.CallbackHandler;
31 
32 /**
33  * This class defines login and logout methods for a provider.
34  *
35  * <p> While callers may invoke {@code login} directly,
36  * the provider may also invoke {@code login} on behalf of callers
37  * if it determines that a login must be performed
38  * prior to certain operations.
39  *
40  * @since 1.5
41  */
42 public abstract class AuthProvider extends Provider {
43 
44     @java.io.Serial
45     private static final long serialVersionUID = 4197859053084546461L;
46 
47     /**
48      * Constructs a provider with the specified name, version number,
49      * and information.
50      *
51      * @param name the provider name.
52      * @param version the provider version number.
53      * @param info a description of the provider and its services.
54      * @deprecated use {@link #AuthProvider(String, String, String)} instead.
55      */
56     @Deprecated(since="9")
AuthProvider(String name, double version, String info)57     protected AuthProvider(String name, double version, String info) {
58         super(name, Double.toString(version), info);
59     }
60 
61     /**
62      * Constructs a provider with the specified name, version string,
63      * and information.
64      *
65      * @param name the provider name.
66      * @param versionStr the provider version string.
67      * @param info a description of the provider and its services.
68      * @since 9
69      */
AuthProvider(String name, String versionStr, String info)70     protected AuthProvider(String name, String versionStr, String info) {
71         super(name, versionStr, info);
72     }
73 
74     /**
75      * Log in to this provider.
76      *
77      * <p> The provider relies on a {@code CallbackHandler}
78      * to obtain authentication information from the caller
79      * (a PIN, for example).  If the caller passes a {@code null}
80      * handler to this method, the provider uses the handler set in the
81      * {@code setCallbackHandler} method.
82      * If no handler was set in that method, the provider queries the
83      * <i>auth.login.defaultCallbackHandler</i> security property
84      * for the fully qualified class name of a default handler implementation.
85      * If the security property is not set,
86      * the provider is assumed to have alternative means
87      * for obtaining authentication information.
88      *
89      * @param subject the {@code Subject} which may contain
90      *          principals/credentials used for authentication,
91      *          or may be populated with additional principals/credentials
92      *          after successful authentication has completed.
93      *          This parameter may be {@code null}.
94      * @param handler the {@code CallbackHandler} used by
95      *          this provider to obtain authentication information
96      *          from the caller, which may be {@code null}
97      *
98      * @throws IllegalStateException if the provider requires configuration
99      * and {@link configure} has not been called
100      * @throws LoginException if the login operation fails
101      * @throws SecurityException if the caller does not pass a
102      *  security check for
103      *  {@code SecurityPermission("authProvider.name")},
104      *  where {@code name} is the value returned by
105      *  this provider's {@code getName} method
106      */
login(Subject subject, CallbackHandler handler)107     public abstract void login(Subject subject, CallbackHandler handler)
108         throws LoginException;
109 
110     /**
111      * Log out from this provider.
112      *
113      * @throws IllegalStateException if the provider requires configuration
114      * and {@link configure} has not been called
115      * @throws LoginException if the logout operation fails
116      * @throws SecurityException if the caller does not pass a
117      *  security check for
118      *  {@code SecurityPermission("authProvider.name")},
119      *  where {@code name} is the value returned by
120      *  this provider's {@code getName} method
121      */
logout()122     public abstract void logout() throws LoginException;
123 
124     /**
125      * Set a {@code CallbackHandler}.
126      *
127      * <p> The provider uses this handler if one is not passed to the
128      * {@code login} method.  The provider also uses this handler
129      * if it invokes {@code login} on behalf of callers.
130      * In either case if a handler is not set via this method,
131      * the provider queries the
132      * <i>auth.login.defaultCallbackHandler</i> security property
133      * for the fully qualified class name of a default handler implementation.
134      * If the security property is not set,
135      * the provider is assumed to have alternative means
136      * for obtaining authentication information.
137      *
138      * @param handler a {@code CallbackHandler} for obtaining
139      *          authentication information, which may be {@code null}
140      *
141      * @throws IllegalStateException if the provider requires configuration
142      * and {@link configure} has not been called
143      * @throws SecurityException if the caller does not pass a
144      *  security check for
145      *  {@code SecurityPermission("authProvider.name")},
146      *  where {@code name} is the value returned by
147      *  this provider's {@code getName} method
148      */
setCallbackHandler(CallbackHandler handler)149     public abstract void setCallbackHandler(CallbackHandler handler);
150 }
151