forked from msambartolomeo/TP-PROTOS
-
Notifications
You must be signed in to change notification settings - Fork 0
/
shoes-protocol.txt
294 lines (220 loc) · 11.6 KB
/
shoes-protocol.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
SHOES Protocol Version 1.0
1 Introduction
SHOES is a TCP-based protocol designed to obtain metrics from a server
and change its configuration at runtime. The name is derived from
"Should Establish" a connection. Inspired by SOCKS5 [RFC 1928],
it is a simple, reliable, and secure protocol for establishing a
connection to a server.
1.1 Considerations
Unless otherwise noted, the decimal numbers appearing in packet-format
diagrams represent the length of the corresponding field, in
octets. Where a given octet must take on a specific value, the
syntax X'hh' is used to denote the value of the single octet in that
field. When the word 'Variable' is used, it indicates that the
corresponding field has a variable length defined either by an
associated (one or two octet) length field, or by a data type field.
In addition, all fields which are larger than one octet are represented
in network byte order.
2 Authentication
Once the SHOES V1 server has started, and the client has selected the
Username/Password Authentication protocol, the Username/Password
negotiation begins. This begins with the client producing a
Username/Password request:
+-------+------+----------+------+----------+
| VER | ULEN | UNAME | PLEN | PASSWD |
+-------+------+----------+------+----------+
| X'01' | 1 | 1 to 255 | 1 | 1 to 255 |
+-------+------+----------+------+----------+
Where:
o VER The protocol version number, currently X'01'.
o ULEN The length of the username.
o UNAME The username.
o PLEN The length of the password.
o PASSWD The password.
The server verifies the supplied UNAME and PASSWD, and sends the
following response:
+-----+--------+
| VER | STATUS |
+-----+--------+
| 1 | 1 |
+-----+--------+
A STATUS field of X'00' indicates success. If the server returns a
failure (STATUS value other than X'00') status, the server MUST NOT close the
connection. The protocol allows for a client to prompt the user to try again
without terminating the connection. However, each specific client can decide
whether to allow this behaviour or not.
Other values defined in this version are:
o X'01' - General SHOES server failure.
o X'02' - Invalid protocol version.
o X'03' - Invalid username or password.
3 Requests
Once the authorization process has concluded, the client sends the
request details. Request formats vary depending on the type of
request. However, the following fields are present in any request:
o FMLY Family of the request.
o GET Requests X'00'
o PUT Requests X'01'
o CMD Identifies the command to be executed within
the family specified.
The following sections go into further detail on the different
request types. See section 4 for a description of the response
formats.
3.1 GET Requests
This type of requests are used to retrieve information from the
server. The information returned can be metrics that have been
collected from the server or information from the users that is
available.
GET Requests MUST NOT use the DATA field, it is not used and MUST
be empty.
The values currently defined for CMD in this family are:
o X'00' SERVER METRICS
o X'01' LIST USERS
o X'02' PASSWORD SPOOFING STATUS
Section 4.1 goes into greater details on how the responses
are formed.
3.2 PUT Requests
This type of requests are used to send information to the server,
adding or modifying the information that is available.
All the following requests MUST use the DATA field, and how it is
used is dependent on the CMD value.
The values currently defined for CMD in this family are:
o X'00' ADD USER
o X'01' REMOVE USER
o X'02' EDIT USER
o X'03' MODIFY BUFFER SIZE
o X'04' MODIFY PASSWORD SPOOFING STATUS
The requests formats are as follows:
3.2.1 ADD USER
+---------+---------+------+----------+------+----------+
| FMLY | CMD | ULEN | UNAME | PLEN | PASSWD |
+---------+---------+------+----------+------+----------+
| X'01' | X'00' | 1 | 1 to 255 | 1 | 1 to 255 |
+---------+---------+------+----------+------+----------+
The server will try to create a new user with the given UNAME
and PASSWD. If the user already exists, the server will return
a failure status.
3.2.2 REMOVE USER
+---------+---------+------+----------+
| FMLY | CMD | ULEN | UNAME |
+---------+---------+------+----------+
| X'01' | X'01' | 1 | 1 to 255 |
+---------+---------+------+----------+
The server will try to remove the user with the given UNAME.
If the user does not exist, the server will return a failure
status.
3.2.3 EDIT USER
+---------+---------+------+----------+------+----------+
| FMLY | CMD | ULEN | UNAME | PLEN | PASSWD |
+---------+---------+------+----------+------+----------+
| X'01' | X'02' | 1 | 1 to 255 | 1 | 1 to 255 |
+---------+---------+------+----------+------+----------+
The server will try to associate the given UNAME with the given PASSWD.
If the user does not exist, the server will return a failure status.
3.2.4 MODIFY BUFFER SIZE
+---------+---------+---------+
| FMLY | CMD | BUFSIZE |
+---------+---------+---------+
| X'01' | X'03' | 2 |
+---------+---------+---------+
Where BUFSIZE is a 2 octet integer representing the buffer size
in bytes. The server will try to modify the buffer size to the
given value. However, the server will not allow the buffer size
to be set to a value less than 512 bytes, or greater than 65536
bytes. If a value outside the allowed range is given, the server
will return a failure status and not modify the buffer size.
3.2.5 MODIFY PASSWORD SPOOFING STATUS
+---------+---------+------+
| FMLY | CMD | SET |
+---------+---------+------+
| X'01' | X'04' | 1 |
+---------+---------+------+
Where SET is a 1 octet integer representing the password spoofing
status. A value of X'00' indicates that the server should not
spoof passwords. A value of X'01' indicates that the server should
spoof passwords. If a value other than X'00' or X'01' is given,
the server will return a failure status and not modify the
password spoofing status.
4 Responses
As stated previous, the server will return a different format
depending on the command that was requested. The following sections
go into greater details on how the replies are formed.
However, all response formats begin with the STATUS field, which can
take the following values:
o X'00' Success
o X'01' General SHOES server failure
o X'02' FMLY not supported
o X'03' CMD not supported
o X'04' and X'05' CMD-specific failure status. See
the following sections for more details.
If the server returns a failure (STATUS value other than X'00'),
it MUST close the connection.
4.1 Responses to GET Requests
The response to a GET request contains the data the request asked for.
However, the data is not in a fixed format. The following sections
go into greater details on how the replies are formed.
It is important to note that GET requests will not return a CMD-specific
failure status.
4.1.1 SERVER METRICS
The server will return the following reply:
+--------+-------+-------+---------+
| STATUS | HCONN | CCONN | BTRANSF |
+--------+-------+-------+---------+
| 1 | 4 | 4 | 8 |
+--------+-------+-------+---------+
Where:
o STATUS Status of the request.
o HCONN Number of historic connections to the server.
o CCONN Number of current connections to the server.
o BTRANSF Number of bytes transferred by the server.
4.1.2 LIST USERS
The server will return the following reply:
+--------+--------+---------+----------+
| STATUS | UCOUNT | ULEN(n) | UNAME(n) |
+--------+--------+---------+----------+
| 1 | 1 | 1 | 1 to 255 |
+--------+--------+---------+----------+
Where:
o STATUS Status of the request.
o UCOUNT Number of users listed.
o ULEN(n) Length of the UNAME(n) field.
o UNAME(n) Username of the n-th user.
The "n" in the above example is only shown for illustration purposes so
that the reader understands the structure of the reply. If no users
are listed, the server will return a reply with a UCOUNT of 0. If there
is at least one user listed, the server will return a ULEN and a UNAME
value for each user.
4.1.3 PASSWORD SPOOFING STATUS
The server will return the following reply:
+--------+-------+
| STATUS | SPOOF |
+--------+-------+
| 1 | 1 |
+--------+-------+
Where:
o STATUS Status of the request.
o SPOOF Password spoofing status.
The field SPOOF contains one octet, which is either X'00' or X'01',
representing the password spoofing status as disabled or enabled,
respectively.
4.2 Responses to PUT Requests
The response to a PUT request contains the status of the request,
which will be used to determine if the request was successful.
In addition, responses to PUT requests can return a CMD-specific
failure status, indicating a failure specific to the command.
Therefore, a STATUS of X'04' indicates:
o ADD USER - The user already exists.
o REMOVE USER - The user does not exist.
o EDIT USER - The user does not exist.
o MODIFY BUFFER SIZE - The buffer size is out of range.
o MODIFY PASSWORD SPOOFING STATUS - The password spoofing
status is out of range.
In addition, a STATUS of X'05' indicates:
o ADD USER - The maximum number of users has been
reached.
See section 3.2 for more details in accepted values ranges for each
command.
5 Authors
The SHOES protocol was developed by:
o Juan Manuel Negro - 61225
o Mauro Daniel Sambartolomeo - 61279
o Agustín Omar Morantes - 61306