Readme.md


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

# Matrix Client Library in C

This is a library implementing parts of the [Matrix](https://matrix.org/) [Client-Server API](https://spec.matrix.org/v1.8/client-server-api/).
It is written in C and supports sending and receiving of messages, including end-to-end encryption.
Device verification is also supported.

## Building

Building requires a C/C++ compiler and make.

To build the dependencies run `make deps`.
All dependencies are included in this repository.

To build any of the examples run `make out/examples/<example>`.

To use the library:
- Add `src/matrix.c` to compilation
- Add either `src/matrix_http_mongoose.c` or `src/matrix_http_esp32.c` to compilation
- Add `out/*.o` to compilation
- Add include path `src/`
- Add include path `ext/olm/include/`
- Add include path `ext/mjson/src/`
- Add include path `ext/mongoose/`

To build the example for the ESP32 start an ESP-IDF shell in esp32/esp_project or esp32/esp_project_riscv and run:
- `idf.py build`
- `idf.py flash`
- `idf.py monitor`

To use the library in an ESP-IDF project:
- Add the matrix and olm components (can be found in `esp32/esp_project/components/`)
- Add `wifi.c/.h` (can be found in `esp32/esp_project/main/`)
- Add `SET(CMAKE_CXX_FLAGS  "${CMAKE_CXX_FLAGS} -fpermissive")` to CMakeLists.txt
- Call `wifi_init("<SSID>", "<PASSWORD>")` before initializing the library

## Dependencies
[Mongoose](https://github.com/cesanta/mongoose)

[mjson](https://github.com/cesanta/mjson)

[Olm](https://gitlab.matrix.org/matrix-org/olm)

## Examples

### (De)Initialization
```
MatrixClient * client = (MatrixClient*)malloc(sizeof(MatrixClient));
MatrixClientInit(client);

MatrixHttpInit(&client->hc, SERVER);
MatrixClientSetUserId(client, USER_ID);

MatrixClientLoginPassword(client,
    "pscho",
    "Wc23EbmB9G3faMq",
    "Test1");

MatrixClientDeleteDevice(client);
    
MatrixHttpDeinit(&client->hc);
```

### Uploading keys
```
MatrixClientGenerateOnetimeKeys(client, 10);
MatrixClientUploadOnetimeKeys(client);
MatrixClientUploadDeviceKeys(client);
```

### Sending an encrypted message
```
MatrixMegolmOutSession * megolmOutSession;
MatrixClientNewMegolmOutSession(&client,
    ROOM_ID,
    &megolmOutSession);
printf("megolm session id: %.10s... key: %.10s...\n", megolmOutSession->id, megolmOutSession->key);

MatrixClientShareMegolmOutSession(&client,
    USER_ID,
    "ULZZOKJBYN",
    megolmOutSession);

MatrixClientSendEventEncrypted(&client,
    ROOM_ID,
    "m.room.message",
    "{\"body\":\"Hello\",\"msgtype\":\"m.text\"}");
```

### Verification
```
// Request an encrypted event to enable verification
STATIC char eventBuffer[1024];
MatrixClientGetRoomEvent(client,
    ROOM_ID,
    EVENT_ID,
    eventBuffer, 1024);

#define SYNC_BUFFER_SIZE 1024*10
STATIC char syncBuffer[SYNC_BUFFER_SIZE];
STATIC char nextBatch[1024];

while (! client->verified) {
    MatrixClientSync(client, syncBuffer, SYNC_BUFFER_SIZE, nextBatch, 1024);
}
```
MatrixClient * client = (MatrixClient*)malloc(sizeof(MatrixClient));
MatrixClientInit(client);

MatrixHttpInit(&client->hc, SERVER);
MatrixClientSetUserId(client, USER_ID);

MatrixClientLoginPassword(client,
    "pscho",
    "Wc23EbmB9G3faMq",
    "Test1");

MatrixClientDeleteDevice(client);
    
MatrixHttpDeinit(&client->hc);
MatrixClientGenerateOnetimeKeys(client, 10);
MatrixClientUploadOnetimeKeys(client);
MatrixClientUploadDeviceKeys(client);
MatrixMegolmOutSession * megolmOutSession;
MatrixClientNewMegolmOutSession(&client,
    ROOM_ID,
    &megolmOutSession);
printf("megolm session id: %.10s... key: %.10s...\n", megolmOutSession->id, megolmOutSession->key);

MatrixClientShareMegolmOutSession(&client,
    USER_ID,
    "ULZZOKJBYN",
    megolmOutSession);

MatrixClientSendEventEncrypted(&client,
    ROOM_ID,
    "m.room.message",
    "{\"body\":\"Hello\",\"msgtype\":\"m.text\"}");
// Request an encrypted event to enable verification
STATIC char eventBuffer[1024];
MatrixClientGetRoomEvent(client,
    ROOM_ID,
    EVENT_ID,
    eventBuffer, 1024);

#define SYNC_BUFFER_SIZE 1024*10
STATIC char syncBuffer[SYNC_BUFFER_SIZE];
STATIC char nextBatch[1024];

while (! client->verified) {
    MatrixClientSync(client, syncBuffer, SYNC_BUFFER_SIZE, nextBatch, 1024);
}