Added initial documentation regarding protocol, signature and hints.

docs/HINTS.md

@@ -0,0 +1,22 @@
+# Hints Format
+
+**Currently this format is in experiment phase**
+
+We are trying to find the best solution to implement a solution which is able to provide metadata of known binary blocks which can match binaries previously seen with symbols.
+
+The current implementation might change with new the protocol versions.
+
+## Client side
+
+The **client** has to generate a hash of the section.
+
+1. Read and calculate the hash of a section using the physical size as size of the amount of data to be digested by the hash algorithm; in the silhouette client we use `blake3`.
+2. As part of the signature we also collect the the number of bytes read, the operating system name and the binary type (i.e. `elf`, `pe`, etc..) to make the signature more unique.
+3. As part of the request, each section data will contain also the physical base address for hints calculation purposes.
+
+## Server side
+
+On the `server` side we use the received data from the client to query a database and return the following info as response:
+
+ - Architecture bits (this is useful for some archs to distinguish between different modes, like `arm` which has `arm mode` and `thumb mode`)
+ - Physical address of the function pointed by the hint, calculated from the base address of the matched section hash provided in the request data.

docs/PROTOCOL.md

@@ -0,0 +1,11 @@
+# Rizin Silhouette Protocol
+
+The protocol implemented is quite simple on purpose to optimize the number of bytes sent and received by the server.
+
+1. Each packet always start with its size which is store in a a 32 bit unsigned word (big-endian)
+2. The packet is encoded using the protobuf format; the reason behind this is to compress as much as possible the data and make the transfer as fast as possible between client and server.
+3. The `client` will always send a pre-shared-key, the protocol version, the type of request (also known in the protocol as `route`) and the encoded data needed by the route.
+4. The `server` will close the connection without replying if the size of the packet exeeds the max size defined in the server settings.
+5. The `server` will always reply with a status code, and the encoded data linked to its status.
+
+For more information please check the `service.proto` file available in both client and server repository.

docs/SIGNATURES.md

@@ -0,0 +1,19 @@
+# Signature Format
+
+## Client side
+
+The **client** has to generate a masked pattern which is then hashed.
+
+1. Read the bytes from the function entry address to the highest basic block address in a linear way.
+2. The bytes read needs to be masked to remove any static address which might be embedded by one or multiple instructions.
+3. The masked bytes needs then to be hashed; in the silhouette client we use `blake3`, but potentially any hash function (like `md5`) can be used.
+4. As part of the signature we also collect the architecture name, bits and the number of bytes read to make the signature more unique.
+
+## Server side
+
+On the `server` side we use the received data from the client to query a database and return the following info as response:
+
+ - Symbol name (for example: `foo`; on Rizin/Cutter it will match to `sym.foo`).
+ - Function signature (for example: `int foo(double bar);`).
+ - Call convention (for example: `cdecl`, `fastcall`, etc..)
+ - Architecture bits (this is useful for some archs to distinguish between different modes, like `arm` which has `arm mode` and `thumb mode`)

src/service.proto

@@ -54,7 +54,7 @@ message Binary {
 message Signature {
   string arch = 1; // architecture name
   uint32 bits = 2; // architecture bits
-  uint32 length = 3; // function length
+  uint32 length = 3; // function digest length
   bytes digest = 4; // function digest of the masked bytes
 }