1 /*
2  * Copyright (c) 2006, 2013, 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 com.sun.net.httpserver;
27 import java.net.*;
28 import java.io.*;
29 import java.util.*;
30 
31 /**
32  * Authenticator represents an implementation of an HTTP authentication
33  * mechanism. Sub-classes provide implementations of specific mechanisms
34  * such as Digest or Basic auth. Instances are invoked to provide verification
35  * of the authentication information provided in all incoming requests.
36  * Note. This implies that any caching of credentials or other authentication
37  * information must be done outside of this class.
38  */
39 public abstract class Authenticator {
40 
41     /**
42      * Base class for return type from authenticate() method
43      */
44     public abstract static class Result {}
45 
46     /**
47      * Indicates an authentication failure. The authentication
48      * attempt has completed.
49      */
50     public static class Failure extends Result {
51 
52         private int responseCode;
53 
Failure(int responseCode)54         public Failure (int responseCode) {
55             this.responseCode = responseCode;
56         }
57 
58         /**
59          * returns the response code to send to the client
60          */
getResponseCode()61         public int getResponseCode() {
62             return responseCode;
63         }
64     }
65 
66     /**
67      * Indicates an authentication has succeeded and the
68      * authenticated user principal can be acquired by calling
69      * getPrincipal().
70      */
71     public static class Success extends Result {
72         private HttpPrincipal principal;
73 
Success(HttpPrincipal p)74         public Success (HttpPrincipal p) {
75             principal = p;
76         }
77         /**
78          * returns the authenticated user Principal
79          */
getPrincipal()80         public HttpPrincipal getPrincipal() {
81             return principal;
82         }
83     }
84 
85     /**
86      * Indicates an authentication must be retried. The
87      * response code to be sent back is as returned from
88      * getResponseCode(). The Authenticator must also have
89      * set any necessary response headers in the given HttpExchange
90      * before returning this Retry object.
91      */
92     public static class Retry extends Result {
93 
94         private int responseCode;
95 
Retry(int responseCode)96         public Retry (int responseCode) {
97             this.responseCode = responseCode;
98         }
99 
100         /**
101          * returns the response code to send to the client
102          */
getResponseCode()103         public int getResponseCode() {
104             return responseCode;
105         }
106     }
107 
108     /**
109      * called to authenticate each incoming request. The implementation
110      * must return a Failure, Success or Retry object as appropriate :-
111      * <p>
112      * Failure means the authentication has completed, but has failed
113      * due to invalid credentials.
114      * <p>
115      * Sucess means that the authentication
116      * has succeeded, and a Principal object representing the user
117      * can be retrieved by calling Sucess.getPrincipal() .
118      * <p>
119      * Retry means that another HTTP exchange is required. Any response
120      * headers needing to be sent back to the client are set in the
121      * given HttpExchange. The response code to be returned must be provided
122      * in the Retry object. Retry may occur multiple times.
123      */
authenticate(HttpExchange exch)124     public abstract Result authenticate (HttpExchange exch);
125 }
126