annotate src/net/sourceforge/jsocks/server/ServerAuthenticator.java @ 349:205ee2873330

update jsocks to 2011-03-19
author Carl Byington <carl@five-ten-sg.com>
date Fri, 01 Aug 2014 11:23:10 -0700
parents 0ce5cc452d02
children 72de889ecfe7
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
349
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
1 package socks.server;
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
2
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
3 import java.io.IOException;
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
4 import java.io.InputStream;
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
5 import java.io.OutputStream;
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
6 import java.net.Socket;
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
7 import java.net.DatagramPacket;
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
8 import net.sourceforge.jsocks.ProxyMessage;
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
9 import net.sourceforge.jsocks.UDPEncapsulation;
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
10
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
11 /**
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
12 Classes implementing this interface should provide socks server with
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
13 authentication and authorization of users.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
14 **/
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
15 public interface ServerAuthenticator{
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
16
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
17 /**
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
18 This method is called when a new connection accepted by the server.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
19 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
20 At this point no data have been extracted from the connection. It is
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
21 responsibility of this method to ensure that the next byte in the
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
22 stream after this method have been called is the first byte of the
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
23 socks request message. For SOCKSv4 there is no authentication data and
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
24 the first byte in the stream is part of the request. With SOCKSv5 however
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
25 there is an authentication data first. It is expected that implementaions
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
26 will process this authentication data.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
27 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
28 If authentication was successful an instance of ServerAuthentication
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
29 should be returned, it later will be used by the server to perform
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
30 authorization and some other things. If authentication fails null should
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
31 be returned, or an exception may be thrown.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
32
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
33 @param s Accepted Socket.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
34 @return An instance of ServerAuthenticator to be used for this connection
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
35 or null
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
36 */
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
37 ServerAuthenticator startSession(Socket s) throws IOException;
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
38
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
39 /**
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
40 This method should return input stream which should be used on the
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
41 accepted socket.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
42 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
43 SOCKSv5 allows to have multiple authentication methods, and these methods
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
44 might require some kind of transformations being made on the data.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
45 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
46 This method is called on the object returned from the startSession
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
47 function.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
48 */
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
49 InputStream getInputStream();
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
50 /**
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
51 This method should return output stream to use to write to the accepted
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
52 socket.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
53 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
54 SOCKSv5 allows to have multiple authentication methods, and these methods
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
55 might require some kind of transformations being made on the data.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
56 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
57 This method is called on the object returned from the startSession
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
58 function.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
59 */
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
60 OutputStream getOutputStream();
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
61
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
62 /**
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
63 This method should return UDPEncapsulation, which should be used
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
64 on the datagrams being send in/out.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
65 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
66 If no transformation should be done on the datagrams, this method
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
67 should return null.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
68 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
69 This method is called on the object returned from the startSession
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
70 function.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
71 */
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
72
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
73 UDPEncapsulation getUdpEncapsulation();
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
74
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
75 /**
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
76 This method is called when a request have been read.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
77 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
78 Implementation should decide wether to grant request or not. Returning
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
79 true implies granting the request, false means request should be rejected.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
80 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
81 This method is called on the object returned from the startSession
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
82 function.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
83 @param msg Request message.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
84 @return true to grant request, false to reject it.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
85 */
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
86 boolean checkRequest(ProxyMessage msg);
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
87
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
88 /**
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
89 This method is called when datagram is received by the server.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
90 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
91 Implementaions should decide wether it should be forwarded or dropped.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
92 It is expecteed that implementation will use datagram address and port
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
93 information to make a decision, as well as anything else. Address and
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
94 port of the datagram are always correspond to remote machine. It is
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
95 either destination or source address. If out is true address is destination
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
96 address, else it is a source address, address of the machine from which
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
97 datagram have been received for the client.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
98 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
99 Implementaions should return true if the datagram is to be forwarded, and
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
100 false if the datagram should be dropped.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
101 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
102 This method is called on the object returned from the startSession
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
103 function.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
104
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
105 @param out If true the datagram is being send out(from the client),
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
106 otherwise it is an incoming datagram.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
107 @return True to forward datagram false drop it silently.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
108 */
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
109 boolean checkRequest(DatagramPacket dp, boolean out);
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
110
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
111 /**
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
112 This method is called when session is completed. Either due to normal
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
113 termination or due to any error condition.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
114 <p>
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
115 This method is called on the object returned from the startSession
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
116 function.
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
117 */
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
118 void endSession();
205ee2873330 update jsocks to 2011-03-19
Carl Byington <carl@five-ten-sg.com>
parents: 0
diff changeset
119 }