tools/*: update docs (man, readme, --help)

There was huge number of inconsistencies between documentation, helpers
and options parsing. Unified arguments and docs + package them.

Change-Id: Icf1097e2130882e4de831db21d3fb16603266229

CMakeLists.txt

@@ -360,6 +360,8 @@ if (BUILD_TOOLS AND NOT MSVC)
     install(FILES
         tools/dnc/dnc.1
         tools/dsh/dsh.1
+        tools/dvpn/dvpn.1
+        tools/dhtnet_crtmgr/dhtnet-crtmgr.1
     DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
 
     install(FILES README.md DESTINATION ${docdir})

tools/dhtnet_crtmgr/README.md

@@ -15,11 +15,11 @@ The DHTNet Certificate Manager is a command-line tool designed to manage certifi
 ## Option
 - `-h, --help`: Display this help message and then exit.
 - `-v, --version`: Show the version of the program.
-- `-p, --privatekey`: Provide the path to the private key as an argument.
-- `-c, --certificate`: Provide the path to the certificate  as an argument.
-- `-o, --output`: Provide the path where the generated certificate should be saved as an argument.
+- `-p, --privatekey [FILE]`: Provide the path to the private key as an argument.
+- `-c, --certificate [FILE]`: Provide the path to the certificate  as an argument.
+- `-o, --output [FOLDER]`: Provide the path where the generated certificate should be saved as an argument.
 - `-a, --identifier`: Display the user identifier.
-- `-n, --name`: Provide the name of the certificate to be generated.
+- `-n, --name [NAME]`: Provide the name of the certificate to be generated.
 - `-s, --setup`: Create an CA and an certificate.
 - `-i, --interactive`: Create certificate using interactive mode.
 

tools/dhtnet_crtmgr/dhtnet-crtmgr.1

@@ -0,0 +1,71 @@
+.TH DHTNET-CRTMGR 1 "July 2024"
+.SH NAME
+dhtnet-crtmgr \- DHTNet Certificate Manager
+.SH SYNOPSIS
+.B dhtnet-crtmgr
+[OPTIONS]...
+.SH DESCRIPTION
+\fBdhtnet-crtmgr\fR is a command-line utility designed to manage certificates for the DHTNet network.
+It enables users to generate, sign, and configure certificates for secure communication across the network.
+
+For easy setup and testing purpose, you can use \fBdhtner-crtmgr \-\-interactive\fR to generate a self-signed certificate for server and/or client.
+.SH OPTIONS
+
+.TP
+.B \-h, \-\-help
+Display help information and exit.
+
+.TP
+.B \-v, \-\-version
+Show program version.
+
+.TP
+.B \-i, \-\-interactive
+Generate a self-signed certificate interactively and edit configuration to use it.
+
+.TP
+.B \-a, \-\-identifier
+Print the identifier of the certificate in stdout. This identifier is the one used to reach node on DHT network.
+Require options \fB\-c\fR and \fB\-p\fR to be set.
+
+.TP
+.B \-s, \-\-setup
+Generate a CA and a certificate signed with this CA. Require \fB\-o\fR option. If used with \fB\-c\fR and \fB\-p\fR, will generate a certificate signed with the CA given by these options.
+
+Will create sub-folders \fICA\fR and \fIid\fR in the output folder given at \fB\-o\fR.
+
+.TP
+.B \-o, \-\-output \fIFOLDER\fR
+Define the output folder for the generated certificate.
+
+.TP
+.B \-c, \-\-certificate \fIFILE\fR
+Define the certificate file to use. Usually a \fI.crt\fR file.
+
+.TP
+.B \-p, \-\-privatekey \fIFILE\fR
+Define the private key file to use. Usually a \fI.pem\fR file.
+
+.TP
+.B \-n, \-\-name \fINAME\fR
+Define the name of the certificate. Will be used to generate \fINAME.crt\fR and \fINAME.pem\fR. Doesn't work with \fB\-s, \-\-setup\fR but must be used with \fB\-o, \-\-output\fR.
+
+.SH EXAMPLES
+
+Use interactive mode to generate a self-signed certificate:
+.B dhtnet-crtmgr \-\-interactive
+
+Generate a CA in \fIoutput_folder\fR:
+.B dhtnet-crtmgr \-\-name \fImy_ca\fB \-\-output \fIoutput_folder\fR
+
+Generate a key signed by previously generated CA:
+.B dhtnet-crtmgr \-\-certificate \fIoutput_folder/my_ca.crt\fB \-\-privateKey \fIoutput_folder/my_ca.pem\fB \-\-name \fImy_key\fB \-\-output \fIkeys_folder\fR
+
+Print the identifier of this newly generated key:
+.B dhtnet-crtmgr \-\-certificate \fIkeys_folder/my_key.crt\fB \-\-privateKey \fIkeys_folder/my_key.pem\fB \-\-identifier\fR
+
+.SH "SEE ALSO"
+.TP
+.BR dnc(1),
+.BR dsh(1),
+.BR dvpn(1)

tools/dhtnet_crtmgr/main.cpp

@@ -33,21 +33,21 @@ struct dhtnet_crtmgr_params
     bool help {false};
     bool version {false};
     std::filesystem::path ca {};
-    std::filesystem::path id {};
+    std::filesystem::path output {};
     std::filesystem::path privatekey {};
-    bool pkid {false};
+    bool identifier {false};
     std::string name {};
     bool setup {false};
     bool interactive {false};
 };
 static const constexpr struct option long_options[]
     = {{"help", no_argument, nullptr, 'h'},
        {"version", no_argument, nullptr, 'v'},
-       {"CA", required_argument, nullptr, 'c'},
-       {"id", required_argument, nullptr, 'o'},
+       {"certificate", required_argument, nullptr, 'c'},
+       {"output", required_argument, nullptr, 'o'},
        {"privatekey", required_argument, nullptr, 'p'},
        {"name", required_argument, nullptr, 'n'},
-       {"pkid", no_argument, nullptr, 'a'},
+       {"identifier", no_argument, nullptr, 'a'},
        {"setup", no_argument, nullptr, 's'},
        {"interactive", no_argument, nullptr, 'i'},
        {nullptr, 0, nullptr, 0}};
@@ -57,7 +57,7 @@ parse_args(int argc, char** argv)
 {
     dhtnet_crtmgr_params params;
     int opt;
-    while ((opt = getopt_long(argc, argv, "hasvi:c:o:p:n:", long_options, nullptr)) != -1) {
+    while ((opt = getopt_long(argc, argv, "hvasic:o:p:n:", long_options, nullptr)) != -1) {
         switch (opt) {
         case 'h':
             params.help = true;
@@ -69,13 +69,13 @@ parse_args(int argc, char** argv)
             params.ca = optarg;
             break;
         case 'o':
-            params.id = optarg;
+            params.output = optarg;
             break;
         case 'p':
             params.privatekey = optarg;
             break;
         case 'a':
-            params.pkid = true;
+            params.identifier = true;
             break;
         case 'n':
             params.name = optarg;
@@ -92,7 +92,7 @@ parse_args(int argc, char** argv)
         }
     }
 
-    if (params.id.empty() && !params.pkid && !params.help && !params.version && !params.interactive) {
+    if (params.output.empty() && !params.identifier && !params.help && !params.version && !params.interactive) {
         std::cerr << "Error: The path to save the generated certificate is not provided.\n Please specify the path using the -o option.\n";
         exit(EXIT_FAILURE);
     }
@@ -200,8 +200,8 @@ main(int argc, char** argv)
                 "\nOptions:\n"
                 "  -h, --help                Display this help message and then exit.\n"
                 "  -v, --version             Show the version of the program.\n"
-                "  -p, --privatekey [PATH]   Provide the path to the private key as an argument.\n"
-                "  -c, --certificate [PATH]  Provide the path to the certificate as an argument.\n"
+                "  -p, --privatekey [FILE]   Provide the path to the private key as an argument.\n"
+                "  -c, --certificate [FILE]  Provide the path to the certificate as an argument.\n"
                 "  -o, --output [FOLDER]     Provide the path where the generated certificate should be saved as an argument.\n"
                 "  -a, --identifier          Display the user identifier.\n"
                 "  -n, --name [NAME]         Provide the name of the certificate to be generated.\n"
@@ -215,7 +215,7 @@ main(int argc, char** argv)
         return EXIT_SUCCESS;
     }
     // check if the public key id is requested
-    if (params.pkid) {
+    if (params.identifier) {
         if (params.ca.empty() || params.privatekey.empty()) {
             fmt::print(stderr, "Error: The path to the private key and the certificate is not provided.\n Please specify the path for the private key and the certificate using the -p and -c options.\n");
             exit(EXIT_FAILURE);
@@ -355,22 +355,22 @@ main(int argc, char** argv)
                 }
             }
             params.setup = true;
-            params.id = folder;
+            params.output = folder;
         }
     }
 
     // check if the setup is requested
     if (params.setup) {
         // create CA  with name ca-server
-        std::filesystem::path path_ca = params.id / "CA";
+        std::filesystem::path path_ca = params.output / "CA";
         auto ca = dhtnet::generateIdentity(path_ca, "ca-server");
         if (!ca.first || !ca.second) {
             fmt::print(stderr, "Error: Could not generate CA.\n");
             return EXIT_FAILURE;
         }
         fmt::print("Generated CA in {}: {} {}\n", path_ca, "ca-server", ca.second->getId());
         // create identity with name id-server
-        std::filesystem::path path_id = params.id / "id";
+        std::filesystem::path path_id = params.output / "id";
         auto identity = dhtnet::generateIdentity(path_id, "id-server", ca);
         if (!identity.first || !identity.second) {
             fmt::print(stderr, "Error: Could not generate certificate.\n");
@@ -382,36 +382,36 @@ main(int argc, char** argv)
 
     if (params.ca.empty() || params.privatekey.empty()) {
         if (params.name.empty()) {
-            auto ca = dhtnet::generateIdentity(params.id, "ca");
+            auto ca = dhtnet::generateIdentity(params.output, "ca");
             if (!ca.first || !ca.second) {
                 fmt::print(stderr, "Error: Could not generate CA.\n");
                 return EXIT_FAILURE;
             }
-            fmt::print("Generated certificate in {}: {} {}\n", params.id, "ca", ca.second->getId());
+            fmt::print("Generated certificate in {}: {} {}\n", params.output, "ca", ca.second->getId());
         }else{
-            auto ca = dhtnet::generateIdentity(params.id, params.name);
+            auto ca = dhtnet::generateIdentity(params.output, params.name);
             if (!ca.first || !ca.second) {
                 fmt::print(stderr, "Error: Could not generate CA.\n");
                 return EXIT_FAILURE;
             }
-            fmt::print("Generated certificate in {}: {} {}\n", params.id, params.name, ca.second->getId());
+            fmt::print("Generated certificate in {}: {} {}\n", params.output, params.name, ca.second->getId());
         }
     }else{
         auto ca = dhtnet::loadIdentity(params.privatekey, params.ca);
         if (params.name.empty()) {
-            auto id = dhtnet::generateIdentity(params.id, "certificate", ca);
+            auto id = dhtnet::generateIdentity(params.output, "certificate", ca);
             if (!id.first || !id.second) {
                 fmt::print(stderr, "Error: Could not generate certificate.\n");
                 return EXIT_FAILURE;
             }
-            fmt::print("Generated certificate in {}: {} {}\n", params.id, "certificate", id.second->getId());
+            fmt::print("Generated certificate in {}: {} {}\n", params.output, "certificate", id.second->getId());
         }else{
-            auto id = dhtnet::generateIdentity(params.id, params.name, ca);
+            auto id = dhtnet::generateIdentity(params.output, params.name, ca);
             if (!id.first || !id.second) {
                 fmt::print(stderr, "Error: Could not generate certificate.\n");
                 return EXIT_FAILURE;
             }
-            fmt::print("Generated certificate in {}: {} {}\n", params.id, params.name, id.second->getId());
+            fmt::print("Generated certificate in {}: {} {}\n", params.output, params.name, id.second->getId());
         }
     }
     return EXIT_SUCCESS;

tools/dnc/README.md

@@ -10,24 +10,34 @@
 - Incorporates TURN (Traversal Using Relays around NAT) server support for effective NAT traversal.
 - Manages identities for enhanced security during DHT network interactions.
 
+## Connection Process
+
+1. **Launch Server and Share Public ID (Server-side):** The server must be launched, and its public ID (hash key) should be shared with the clients who want to connect to it.
+2. **Initiate Connection and Request Remote Socket (Client-side):** The client starts a peer-to-peer connection within the DHT network using the server's public ID and requests the server to open a socket at the specified `<ip>` and `<port>`.
+3. **Check Certificate:** If anonymous mode is off, the server verifies the client's certificate to ensure it matches the server’s CA. If anonymous mode is on, no certificate check is performed.
+4. **Authorize Request:** The server checks if the requested `<ip>:<port>` is authorized based on its rules.
+5. **Create Socket:**
+    - **If Authorized:** The server opens a socket at the specified `<ip>:<port>` and links it to the DHT socket.
+    - **If Not Authorized:** The server rejects the connection.
+
 ### Usage Options
 
 **dnc** supports a range of command-line arguments:
 
 - `-h, --help`: Display help information and exit.
 - `-v, --version`: Show the version of the program.
-- `-P, --port`: Define the port for socket creation.
-- `-i, --ip`: Define the IP address for socket creation.
+- `-P, --port [PORT]`: Define the port for socket creation.
+- `-i, --ip [IP]`: Define the IP address for socket creation.
 - `-l, --listen`: Launch the program in listening mode.
-- `-b, --bootstrap`: Set the bootstrap node.
-- `-t, --turn_host`: Define the TURN server host.
-- `-u, --turn_user`: Define the TURN server username.
-- `-w, --turn_pass`: Define the TURN server password.
-- `-r, --turn_realm`: Specify the TURN server realm.
-- `-c, --certificate`: Specify the Certificate.
-- `-p, --privateKey`: Provide a private key.
-- `-d, --configuration`: Define the dnc configuration with a YAML file path.
-- `-a, --anonymous_cnx`: Activate anonymous connection mode.
+- `-b, --bootstrap [ADDRESS]`: Set the bootstrap node.
+- `-t, --turn_host [ADDRESS]`: Define the TURN server host.
+- `-u, --turn_user [USER]`: Define the TURN server username.
+- `-w, --turn_pass [SECRET]`: Define the TURN server password.
+- `-r, --turn_realm [REALM]`: Specify the TURN server realm.
+- `-c, --certificate [FILE]`: Specify the Certificate.
+- `-p, --privateKey [FILE]`: Provide a private key.
+- `-d, --configuration [FILE]`: Define the dnc configuration with a YAML file path.
+- `-a, --anonymous`: Activate anonymous connection mode.
 - `-vv, --verbose`: Enable verbose mode.
 
 For additional options, use the `-d` flag with a YAML configuration file:
@@ -36,8 +46,10 @@ dnc -d <YAML_FILE> <PEER_IDENTIFIER>
 ```
 Note: If anonymous mode is off, the server's CA must be shared with the client.
 
+The authorized services `<ip>:<port>` can only be specified in the YAML configuration file. If none are specified, the server will accept all connections.
+
 ## Establishing SSH Connections
-To facilitate SSH connections to a remote device, dnc establishes a DHT network connection followed by socket creation on port 22, assuming an OpenSSH server is operational.
+To facilitate SSH connections to a remote device, dnc establishes a DHT network connection followed by socket creation on port 22 by default, assuming an OpenSSH server is operational.
 
 ### Prerequisites
 - **OpenSSH Installation**

tools/dnc/dnc.1

@@ -17,49 +17,64 @@ dnc \- Distributed Netcat
 .TP
 .B \- Manages identities for secure interactions.
 
-.SH "USAGE OPTIONS"
+.SH "OPTIONS"
+
 .TP
 .B \-h, \-\-help
 Display help information and exit.
+
 .TP
 .B \-v, \-\-version
 Show program version.
+
 .TP
-.B \-P, \-\-port
+.B \-P, \-\-port \fIPORT\fR
 Define the port for socket creation.
+
 .TP
-.B \-i, \-\-ip
+.B \-i, \-\-ip \fIADDRESS\fR
 Define the IP address for socket creation.
+
 .TP
 .B \-l, \-\-listen
 Launch in listening mode.
+
 .TP
-.B \-b, \-\-bootstrap
+.B \-b, \-\-bootstrap \fIADDRESS\fR
 Set the bootstrap node.
+
 .TP
-.B \-p, \-\-privateKey
-Provide a private key.
-.TP
-.B \-t, \-\-turn_host
+.B \-t, \-\-turn_host \fIADDRESS\fR
 Define the TURN server host.
+
 .TP
-.B \-u, \-\-turn_user
+.B \-u, \-\-turn_user \fIUSER\fR
 Define the TURN server username.
+
 .TP
-.B \-w, \-\-turn_pass
+.B \-w, \-\-turn_pass \fISECRET\fR
 Define the TURN server password.
+
 .TP
-.B \-r, \-\-turn_realm
+.B \-r, \-\-turn_realm \fIREALM\fR
 Specify the TURN server realm.
+
 .TP
-.B \-c, \-\-certificate
+.B \-p, \-\-privateKey \fIFILE\fR
+Provide a private key.
+
+.TP
+.B \-c, \-\-certificate \fIFILE\fR
 Specify the certificate.
+
 .TP
-.B \-d, \-\-dnc_configuration
+.B \-d, \-\-configuration \fIFILE\fR
 Define the dnc configuration with a YAML file path.
+
 .TP
-.B \-a, \-\-anonymous_cnx
+.B \-a, \-\-anonymous
 Activate anonymous connection mode.
+
 .TP
 .B \-vv, \-\-verbose
 Enable verbose mode.
@@ -88,5 +103,6 @@ To connect to a remote server:
 .SH "SEE ALSO"
 .TP
 .BR ssh(1),
-.BR netcat(1)
+.BR netcat(1),
+.BR dhtnet-crtmgr (1)