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- Run MongoDB.
25- Go to the folder /goCaptcha, and run:
26```
27./goCaptcha
28```
29It will show:
30```
31user@laptop:~/goCaptcha$ ./goCaptcha
32 goCaptcha started
33 dataset read
34 num of dataset categories: 4
35 server running
36 port: 3025
37```
38
39
40## 2 - How to make the petitions?
41
42### 2.1 - Get the captcha:
43```
44GET/ 127.0.0.1:3025/captcha
45```
46Server response:
47```json
48{
49 "id": "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
50 "imgs": [
51 "7cf6f630-e78f-469c-85dd-2d677996fea1.png",
52 "d4014318-f875-4b42-b704-4f5bf5e5e00c.png",
53 "2dd69b44-903d-4e78-bb7b-f8b07877c9e5.png",
54 "2954fc38-819d-40c9-ae3e-7b6fbb68ddbe.png",
55 "b060f58a-d44b-4e05-b466-92aa801a2aa1.png",
56 "1b838c46-b784-471e-b143-48be058c39a7.png"
57 ],
58 "question": "leopard",
59 "date": "1502274893"
60}
61```
62
63### 2.2 - User selects the images that fit in the 'question' parameter
64(in this case, 'leopard')
65
66The selection is stored in an array:
67```js
68 selection=[0,0,1,0,1,0];
69```
70Where the '1' are the images selected, in the images array order.
71
72### 2.3 - Post the answer. The answer contains the CaptchaId, and an array with the selected images
73```
74POST/ 127.0.0.1:3025/answer
75```
76Post example:
77```json
78{
79 "captchaid": "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
80 "selection": [0,0,1,0,1,0]
81}
82```
83Server response:
84```
85true
86```
87
88## 3 - How this works?
89
90### 3.1 - Server reads dataset
91First, server reads all dataset. Dataset is a directory with subdirectories, where each subdirectory contains images of one element.
92
93For example:
94```
95imgs/
96 leopard/
97 img01.png
98 img02.png
99 img03.png
100 ...
101 laptop/
102 img01.png
103 img02.png
104 ...
105 house/
106 img01.png
107 img02.png
108 ...
109```
110Then, stores all the filenames corresponding to each subdirectory. So, we have each image and to which element category is (the name of subdirectory).
111
112
113### 3.2 - Server generates captcha
114When server recieves a GET /captcha, generates a captcha, getting random images from the dataset.
115
116For each captcha generated, generates two mongodb models:
117```json
118Captcha Model
119{
120 "id" : "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
121 "imgs" : [
122 "7cf6f630-e78f-469c-85dd-2d677996fea1.png",
123 "d4014318-f875-4b42-b704-4f5bf5e5e00c.png",
124 "2dd69b44-903d-4e78-bb7b-f8b07877c9e5.png",
125 "2954fc38-819d-40c9-ae3e-7b6fbb68ddbe.png",
126 "b060f58a-d44b-4e05-b466-92aa801a2aa1.png",
127 "1b838c46-b784-471e-b143-48be058c39a7.png"
128 ],
129 "question" : "leopard"
130}
131```
132
133```json
134CaptchaSolution Model
135{
136 "id" : "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
137 "imgs" : [
138 "image_0022.jpg",
139 "image_0006.jpg",
140 "image_0050.jpg",
141 "image_0028.jpg",
142 "image_0119.jpg",
143 "image_0092.jpg"
144 ],
145 "imgssolution" : [
146 "camera",
147 "camera",
148 "laptop",
149 "crocodile",
150 "leopard",
151 "leopard"
152 ],
153 "question" : "leopard",
154 "date": "1502274893"
155}
156```
157Both models are stored in the MongoDB.
158
159The 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:
160```json
161{
162 "captchaid" : "881c6083-0643-4d1c-9987-f8cc5bb9d5b1",
163 "real" : "leopard/image_0092.jpg",
164 "fake" : "1b838c46-b784-471e-b143-48be058c39a7.png"
165}
166```
167When 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:
168```
169127.0.0.1:3025/image/1b838c46-b784-471e-b143-48be058c39a7.png
170```
171
172Captcha Model contains the captcha that server returns to the petition. And CaptchaSolution contains the solution of the captcha. Both have the same Id.
173
174
175### 3.3 - Server validates captcha
176When 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.
177
178If the selection is correct, returns 'true', if the selection is not correct, returns 'false'.
179
180
181## 4 - Security
182
183- If the captcha is resolved in less than 1 second, it's not valid.
184- If the captcha is resolved in more than 1 minute, it's not valid.
185- The images url, are UUIDs generated each time, in order to give different names for the images each time.