goCaptcha/README.md
README.mdRaw
1# goCaptcha
2captcha server, with own datasets, to train own machine learning AI
3
4## 1 - How to use?
5### 1.1 - Frontend
6Insert this lines in the html file:
7```html
8 <link rel="stylesheet" href="goCaptcha.css">
9
10 <div id="goCaptcha"></div>
11
12 <script>//define the url where is placed the server of goCaptcha
13 var goCaptchaURL = "http://127.0.0.1:3025";
14 </script>
15 <script src="goCaptcha.js"></script>
16```
17
18It will place the goCaptcha box in the div:
19
20
21
22### 1.2 - Backend
23- Put dataset images in the folder 'imgs'.
24- Configure serverConfig.json:
25```json
26{
27 "serverIP": "127.0.0.1",
28 "serverPort": "3025",
29 "imgsFolder": "imgs",
30 "numImgsCaptcha": 9
31}
32```
33
34- Run MongoDB.
35- Go to the folder /goCaptcha, and run:
36```
37./goCaptcha
38```
39It will show:
40```
41user@laptop:~/goCaptcha$ ./goCaptcha
42 goCaptcha started
43 dataset read
44 num of dataset categories: 4
45 server running
46 port: 3025
47```
48
49
50## 2 - How to make the petitions?
51
52### 2.1 - Get the captcha:
53```
54GET/ 127.0.0.1:3025/captcha
55```
56Server response:
57```json
58{
59 "id": "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
60 "imgs": [
61 "7cf6f630-e78f-469c-85dd-2d677996fea1.png",
62 "d4014318-f875-4b42-b704-4f5bf5e5e00c.png",
63 "2dd69b44-903d-4e78-bb7b-f8b07877c9e5.png",
64 "2954fc38-819d-40c9-ae3e-7b6fbb68ddbe.png",
65 "b060f58a-d44b-4e05-b466-92aa801a2aa1.png",
66 "1b838c46-b784-471e-b143-48be058c39a7.png"
67 ],
68 "question": "leopard",
69 "date": "1502274893"
70}
71```
72
73### 2.2 - User selects the images that fit in the 'question' parameter
74(in this case, 'leopard')
75
76The selection is stored in an array:
77```js
78 selection=[0,0,1,0,1,0];
79```
80Where the '1' are the images selected, in the images array order.
81
82### 2.3 - Post the answer. The answer contains the CaptchaId, and an array with the selected images
83```
84POST/ 127.0.0.1:3025/answer
85```
86Post example:
87```json
88{
89 "captchaid": "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
90 "selection": [0,0,1,0,1,0]
91}
92```
93Server response:
94```
95true
96```
97
98## 3 - How this works?
99
100### 3.1 - Server reads dataset
101First, server reads all dataset. Dataset is a directory with subdirectories, where each subdirectory contains images of one element.
102
103For example:
104```
105imgs/
106 leopard/
107 img01.png
108 img02.png
109 img03.png
110 ...
111 laptop/
112 img01.png
113 img02.png
114 ...
115 house/
116 img01.png
117 img02.png
118 ...
119```
120Then, stores all the filenames corresponding to each subdirectory. So, we have each image and to which element category is (the name of subdirectory).
121
122
123### 3.2 - Server generates captcha
124When server recieves a GET /captcha, generates a captcha, getting random images from the dataset.
125
126For each captcha generated, generates two mongodb models:
127```json
128Captcha Model
129{
130 "id" : "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
131 "imgs" : [
132 "7cf6f630-e78f-469c-85dd-2d677996fea1.png",
133 "d4014318-f875-4b42-b704-4f5bf5e5e00c.png",
134 "2dd69b44-903d-4e78-bb7b-f8b07877c9e5.png",
135 "2954fc38-819d-40c9-ae3e-7b6fbb68ddbe.png",
136 "b060f58a-d44b-4e05-b466-92aa801a2aa1.png",
137 "1b838c46-b784-471e-b143-48be058c39a7.png"
138 ],
139 "question" : "leopard"
140}
141```
142
143```json
144CaptchaSolution Model
145{
146 "id" : "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
147 "imgs" : [
148 "image_0022.jpg",
149 "image_0006.jpg",
150 "image_0050.jpg",
151 "image_0028.jpg",
152 "image_0119.jpg",
153 "image_0092.jpg"
154 ],
155 "imgssolution" : [
156 "camera",
157 "camera",
158 "laptop",
159 "crocodile",
160 "leopard",
161 "leopard"
162 ],
163 "question" : "leopard",
164 "date": "1502274893"
165}
166```
167Both models are stored in the MongoDB.
168
169The Captcha Model 'imgs' parameter, are UUIDs generated to set 'random' names to images. The server stores into MongoDB the relation between the 'random' name of each image and the real path of the image:
170```json
171{
172 "captchaid" : "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
173 "real" : "leopard/image_0092.jpg",
174 "fake" : "1b838c46-b784-471e-b143-48be058c39a7.png"
175}
176```
177When the server recieves a petition to get an image, recieves the petition with the fake image name, then, gets the real path of the image, gets it and serves the image content under the fake image name:
178```
179127.0.0.1:3025/image/1b838c46-b784-471e-b143-48be058c39a7.png
180```
181
182Captcha Model contains the captcha that server returns to the petition. And CaptchaSolution contains the solution of the captcha. Both have the same Id.
183
184
185### 3.3 - Server validates captcha
186When server recieves POST /answer, gets the answer, search for the CaptchaSolution based on the CaptchaId in the MongoDB, and then compares the answer 'selection' parameter with the CaptchaSolution.
187
188If the selection is correct, returns 'true', if the selection is not correct, returns 'false'.
189
190
191## 4 - Security
192
193- If the captcha is resolved in less than 1 second, it's not valid.
194- If the captcha is resolved in more than 1 minute, it's not valid.
195- The images url, are UUIDs generated each time, in order to give different names for the images each time.
196- The ip of requested captcha and answered captcha petitions must be the same.