diff --git a/doc/rosenpass.1 b/doc/rosenpass.1 new file mode 100644 index 0000000..316a8c4 --- /dev/null +++ b/doc/rosenpass.1 @@ -0,0 +1,105 @@ +.Dd $Mdocdate$ +.Dt ROSENPASS 1 +.Os +.Sh NAME +.Nm rosenpass +.Nd builds post-quantum-secure VPNs +.Sh SYNOPSIS +.Nm +.Op COMMAND +.Op Ar OPTIONS ... +.Op Ar ARGS ... +.Sh DESCRIPTION +.Nm +performs cryptographic key exchanges that are secure against quantum-computers +and outputs the keys. +These keys can then be passed to various services such as wireguard or other +vpn services as pre-shared-keys to achieve security against attackers with +quantum computers. +.Pp +This is a research project and quantum computers are not thought to become +practical in less than ten years. +If you are not specifically tasked with developing post-quantum secure systems, +you probably do not need this tool. +.Ss COMMANDS +.Bl -tag -width Ds +.It Ar keygen private-key public-key +Generate a keypair to use in the exchange command later. +Send the public-key file to your communication partner and keep the private-key +file secret! +.It Ar exchange private-key public-key [ OPTIONS ] PEERS +Start a process to exchange keys with the specified peers. +You should specify at least one peer. +.Pp +It's +.Ar OPTIONS +are as follows: +.Bl -tag -width Ds +.It Ar listen [:] +Instructs +.Nm +to listen on the specified interface and port. +By default +.Nm +will listen on all interfaces and select a random port. +.It Ar verbose +Extra logging. +.El +.El +.Ss PEER +Each +.Ar PEER +is defined as follows: +.Qq peer public-key [endpoint [:]] [preshared-key ] [outfile ] [wireguard ] +.Pp +Providing a +.Ar PEER +instructs +.Nm +to exchange keys with the given peer and write the resulting PSK into the given +output file. +You must either specify the outfile or wireguard output option. +.Pp +The parameters of +.Ar PEER +are as follows: +.Bl -tag -width Ds +.It Ar endpoint [:] +Specifies the address where the peer can be reached. +This will be automatically updated after the first successful key exchange with +the peer. +If this is unspecified, the peer must initiate the connection. +.It Ar preshared-key +You may specify a pre-shared key which will be mixed into the final secret. +.It Ar outfile +You may specify a file to write the exchanged keys to. +If this option is specified, +.Nm +will write a notification to standard out every time the key is updated. +.It Ar wireguard +This allows you to directly specify a wireguard peer to deploy the +pre-shared-key to. +You may specify extra parameters you would pass to +.Qq wg set +besides the preshared-key parameter which is used by +.Nm . +This makes it possible to add peers entirely from +.Nm . +.El +.Sh EXIT STATUS +.Ex -std +.Sh SEE ALSO +.Xr rp 1 , +.Xr wg 1 +.Sh STANDARDS +This tool is the reference implementation of the Rosenpass protocol, written +by Karolin Varner, Benjamin Lipp, Wanja Zaeske, and Lisa Schmidt. +.Sh AUTHORS +Rosenpass was created by Karolin Varner, Benjamin Lipp, Wanja Zaeske, +Marei Peischl, Stephan Ajuvo, and Lisa Schmidt. +.Pp +This manual page was written by +.An Emil Engler +.Sh BUGS +The bugs are tracked at +.Lk https://github.com/rosenpass/rosenpass/issues .