From edfb5639bb8ba42817855a81d56155d67de6ad4b Mon Sep 17 00:00:00 2001 From: Fabio Scotoni <34964387+fscoto@users.noreply.github.com> Date: Wed, 6 Mar 2019 15:29:56 +0100 Subject: [PATCH] Add kex man pages --- doc/man/man3/crypto_kex_x_1.3monocypher | 1 + doc/man/man3/crypto_kex_x_2.3monocypher | 1 + .../man3/crypto_kex_x_init_client.3monocypher | 229 +++++++++++++++ .../man3/crypto_kex_x_init_server.3monocypher | 1 + doc/man/man3/crypto_kex_xk1_1.3monocypher | 1 + doc/man/man3/crypto_kex_xk1_2.3monocypher | 1 + doc/man/man3/crypto_kex_xk1_3.3monocypher | 1 + doc/man/man3/crypto_kex_xk1_4.3monocypher | 1 + .../crypto_kex_xk1_init_client.3monocypher | 274 ++++++++++++++++++ .../crypto_kex_xk1_init_server.3monocypher | 1 + doc/man/man3/crypto_key_exchange.3monocypher | 6 + 11 files changed, 517 insertions(+) create mode 120000 doc/man/man3/crypto_kex_x_1.3monocypher create mode 120000 doc/man/man3/crypto_kex_x_2.3monocypher create mode 100644 doc/man/man3/crypto_kex_x_init_client.3monocypher create mode 120000 doc/man/man3/crypto_kex_x_init_server.3monocypher create mode 120000 doc/man/man3/crypto_kex_xk1_1.3monocypher create mode 120000 doc/man/man3/crypto_kex_xk1_2.3monocypher create mode 120000 doc/man/man3/crypto_kex_xk1_3.3monocypher create mode 120000 doc/man/man3/crypto_kex_xk1_4.3monocypher create mode 100644 doc/man/man3/crypto_kex_xk1_init_client.3monocypher create mode 120000 doc/man/man3/crypto_kex_xk1_init_server.3monocypher diff --git a/doc/man/man3/crypto_kex_x_1.3monocypher b/doc/man/man3/crypto_kex_x_1.3monocypher new file mode 120000 index 0000000..9220da8 --- /dev/null +++ b/doc/man/man3/crypto_kex_x_1.3monocypher @@ -0,0 +1 @@ +crypto_kex_x_init_client.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_kex_x_2.3monocypher b/doc/man/man3/crypto_kex_x_2.3monocypher new file mode 120000 index 0000000..9220da8 --- /dev/null +++ b/doc/man/man3/crypto_kex_x_2.3monocypher @@ -0,0 +1 @@ +crypto_kex_x_init_client.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_kex_x_init_client.3monocypher b/doc/man/man3/crypto_kex_x_init_client.3monocypher new file mode 100644 index 0000000..499485a --- /dev/null +++ b/doc/man/man3/crypto_kex_x_init_client.3monocypher @@ -0,0 +1,229 @@ +.Dd March 6, 2019 +.Dt CRYPTO_KEX_X_INIT_CLIENT 3MONOCYPHER +.Os +.Sh NAME +.Nm crypto_kex_x_init_client , +.Nm crypto_kex_x_init_server , +.Nm crypto_kex_x_1 , +.Nm crypto_kex_x_2 +.Nd one way key exchange for establishing secure channels +.Sh SYNOPSIS +.In monocypher.h +.Ft void +.Fo crypto_kex_x_init_client +.Fa "crypto_kex_ctx *ctx" +.Fa "uint8_t random_seed[32]" +.Fa "const uint8_t local_sk[32]" +.Fa "const uint8_t local_pk[32]" +.Fa "const uint8_t remote_pk[32]" +.Fc +.Ft void +.Fo crypto_kex_x_init_server +.Fa "crypto_kex_ctx *ctx" +.Fa "const uint8_t local_sk[32]" +.Fa "const uint8_t local_pk[32]" +.Fc +.Ft void +.Fo crypto_kex_x_1 +.Fa "crypto_kex_ctx *ctx" +.Fa "uint8_t session_key[32]" +.Fa "uint8_t msg1[80]" +.Fc +.Ft void +.Fo crypto_kex_x_2 +.Fa "crypto_kex_ctx *ctx" +.Fa "uint8_t session_key[32]" +.Fa "uint8_t remote_pk[32]" +.Fa "conts uint8_t msg1[80]" +.Fc +.Sh DESCRIPTION +These functions perform a key exchange between a +.Em client +and a +.Em server +to establish a secure channel. +The result of the key exchange is a +.Em session key +that is suitable for use with +.Xr crypto_lock 3monocypher . +The +.Em server +generates an X25519 secret key and its corresponding public +key ahead of time using +.Xr crypto_key_exchange_public_key 3monocypher +when the key exchange starts. +The +.Em client +does not need to know the +.Em server's +public key before performing the key exchange. +The +.Em client +initiates the key exchange. +.Pp +These functions differ from the +.Xr crypto_kex_xk1_init_client 3monocypher +functions in that the functions described in this page +.Em do not +authenticate the server's identity. +If you can share a server's public key with client applications ahead of +time, +always prefer +.Xr crypto_kex_xk1_init_client 3monocypher . +.Ss Key exchange as the client +When starting a new connection to the server, the client first reads +the server's public key from the network; +then it calls +.Fn crypto_client_x_init_client +to initialize a +.Vt crypto_kex_ctx . +The arguments to +.Fn crypto_client_x_init_client +are: +.Bl -tag -width Ds +.It Fa ctx +A pointer to a +.Vt crypto_kex_ctx . +.It Fa random_seed +32 randomly generated bytes. +See +.Xr intro 3monocypher +for advice about generating random bytes (use the operating system's +random number generator). +.It Fa local_sk +A 32-byte secret random number. +This should be different for every connection you make. +.It Fa local_pk +The public key corresponding to the +.Fa local_sk , +generated using +.Xr crypto_key_exchange_public_key 3monocypher . +If +.Dv NULL , +the public key will be generated for you. +.It Fa remote_pk +The public key of the server. +.El +.Pp +After creating initializing +.Fa ctx , +the client calls +.Fn crypto_kex_x_1 +to generate +.Fa msg1 +and the +.Fa session_key . +It proceeds to send +.Fa msg1 +to the server to complete the key exchange. +.Ss Key exchange as the server +When accepting a new connection from a client, the server first +generates a new secret key and sends the corresponding public key, +derived from the secret key using +.Xr crypto_key_exchange_public_key 3monocypher , +to the client. +It then calls +.Fn crypto_client_xk1_init_server +to initialize a +.Vt crypto_kex_ctx . +The arguments to +.Fn crypto_client_xk1_init_server +are identical to the arguments to +.Fn crypto_client_xk1_init_client , +except that the server does not need a +.Fa random_seed +and does not need to know a client's public key, +so no +.Fa remote_pk +can be specified. +.Pp +After initializing +.Fa ctx , +the server waits for the client to send +.Fa msg1 +and reads it from the network. +The server then calls +.Fn crypto_kex_x_2 +with +.Fa msg1 , +which yields +.Fa session_key +and +.Fa remote_pk , +the client's public key. +.Fn crypto_kex_x_2 +returns zero on success and -1 if the client's message mismatches the +key exchange until now. +.Em Always check the return value . +On success, this function also wipes the data in +.Fa ctx . +.Sh RETURN VALUES +.Fn crypto_kex_x_init_client , +.Fn crypto_kex_x_init_server +and +.Fn crypto_kex_x_1 +return nothing. +.PP +.Fn crypto_kex_x_2 +returns 0 on success or -1 if the messages were corrupt or mismatched the +server's identity. +Corruption can be caused by transmission errors, programmer error, or an +attacker's interference. +.Sh EXAMPLES +These examples use UNIX\(rg networking functions to keep the examples +concise, +but any kind of networking code will work. +It is assumed that the client and server have already established a +connection with each other. +.Pp +Client: +.Bd -literal -offset indent +crypto_kex_ctx client_ctx; /* key exchange context */ +uint8_t sk[32]; /* 32 random bytes ephemeral secret key */ +uint8_t their_pk[32]; /* the server's ephemeral public key */ +uint8_t seed[32]; /* 32 random bytes */ +uint8_t buf[80]; /* buffer for the key exchange messages */ +uint8_t session_key[32]; /* the resulting session key */ +int fd; /* the socket of the connection */ + +if (read(fd, their_pk, 32) != 32) + return -1; +/* (generate random bytes in seed and sk here) */ +crypto_kex_x_init_client(&client_ctx, seed, sk, NULL, their_pk); +crypto_kex_x_1(&client_ctx, session_key, buf); +if (write(fd, buf, 80) != 80) + return -2; +/* key exchange complete; + * send/receive messages encrypted with crypto_lock() now */ +.Ed +.Pp +Server: +.Bd -literal -offset indent +crypto_kex_ctx server_ctx; /* key exchange context */ +uint8_t sk[32]; /* 32 random bytes ephemeral secret key */ +uint8_t my_pk[32]; /* public key to sk */ +uint8_t their_pk[32]; /* the server's public key */ +uint8_t seed[32]; /* 32 random bytes */ +uint8_t buf[80]; /* buffer for the key exchange messages */ +uint8_t session_key[32]; /* the resulting session key */ +int fd; /* the socket of the connection */ + +/* (generate random bytes in sk here) */ +crypto_key_exchange_public_key(my_pk, sk); +if (write(fd, my_pk, 32) != 32) + return -1; +crypto_kex_x_init_server(&server_ctx, sk, my_pk); +if (read(fd, buf, 80) != 80) + return -2; +crypto_kex_1_2(&server_ctx, session_key, their_pk, buf); +/* key exchange complete; + * send/receive messages encrypted with crypto_lock() now */ +.Ed +.Sh SEE ALSO +.Xr crypto_key_exchange 3monocypher , +.Xr crypto_kex_xk1_init_client 3monocypher , +.Xr crypto_lock 3monocypher , +.Xr intro 3monocypher +.Sh STANDARDS +These functions are equivalent to an implementation of the X pattern +of the Noise protocol framework. diff --git a/doc/man/man3/crypto_kex_x_init_server.3monocypher b/doc/man/man3/crypto_kex_x_init_server.3monocypher new file mode 120000 index 0000000..9220da8 --- /dev/null +++ b/doc/man/man3/crypto_kex_x_init_server.3monocypher @@ -0,0 +1 @@ +crypto_kex_x_init_client.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_kex_xk1_1.3monocypher b/doc/man/man3/crypto_kex_xk1_1.3monocypher new file mode 120000 index 0000000..4d554a4 --- /dev/null +++ b/doc/man/man3/crypto_kex_xk1_1.3monocypher @@ -0,0 +1 @@ +crypto_kex_xk1_init_client.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_kex_xk1_2.3monocypher b/doc/man/man3/crypto_kex_xk1_2.3monocypher new file mode 120000 index 0000000..4d554a4 --- /dev/null +++ b/doc/man/man3/crypto_kex_xk1_2.3monocypher @@ -0,0 +1 @@ +crypto_kex_xk1_init_client.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_kex_xk1_3.3monocypher b/doc/man/man3/crypto_kex_xk1_3.3monocypher new file mode 120000 index 0000000..4d554a4 --- /dev/null +++ b/doc/man/man3/crypto_kex_xk1_3.3monocypher @@ -0,0 +1 @@ +crypto_kex_xk1_init_client.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_kex_xk1_4.3monocypher b/doc/man/man3/crypto_kex_xk1_4.3monocypher new file mode 120000 index 0000000..4d554a4 --- /dev/null +++ b/doc/man/man3/crypto_kex_xk1_4.3monocypher @@ -0,0 +1 @@ +crypto_kex_xk1_init_client.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_kex_xk1_init_client.3monocypher b/doc/man/man3/crypto_kex_xk1_init_client.3monocypher new file mode 100644 index 0000000..e43e02f --- /dev/null +++ b/doc/man/man3/crypto_kex_xk1_init_client.3monocypher @@ -0,0 +1,274 @@ +.Dd March 6, 2019 +.Dt CRYPTO_KEX_XK1_INIT_CLIENT 3MONOCYPHER +.Os +.Sh NAME +.Nm crypto_kex_xk1_init_client , +.Nm crypto_kex_xk1_init_server , +.Nm crypto_kex_xk1_1 , +.Nm crypto_kex_xk1_2 , +.Nm crypto_kex_xk1_3 , +.Nm crypto_kex_xk1_4 +.Nd interactive key exchange for establishing secure channels +.Sh SYNOPSIS +.In monocypher.h +.Ft void +.Fo crypto_kex_xk1_init_client +.Fa "crypto_kex_ctx *ctx" +.Fa "uint8_t random_seed[32]" +.Fa "const uint8_t local_sk[32]" +.Fa "const uint8_t local_pk[32]" +.Fa "const uint8_t remote_pk[32]" +.Fc +.Ft void +.Fo crypto_kex_xk1_init_server +.Fa "crypto_kex_ctx *ctx" +.Fa "uint8_t random_seed[32]" +.Fa "const uint8_t local_sk[32]" +.Fa "const uint8_t local_pk[32]" +.Fc +.Ft void +.Fo crypto_kex_xk1_1 +.Fa "crypto_kex_ctx *ctx" +.Fa "uint8_t msg1[32]" +.Fc +.Ft void +.Fo crypto_kex_xk1_2 +.Fa "crypto_kex_ctx *ctx" +.Fa "uint8_t msg2[48]" +.Fa "const uint8_t msg1[32]" +.Fc +.Ft int +.Fo crypto_kex_xk1_3 +.Fa "crypto_kex_ctx *ctx" +.Fa "uint8_t session_key[32]" +.Fa "uint8_t msg3[48]" +.Fa "const uint8_t msg2[48]" +.Fc +.Ft int +.Fo crypto_kex_xk1_4 +.Fa "crypto_kex_ctx *ctx" +.Fa "uint8_t session_key[32]" +.Fa "uint8_t remote_pk[32]" +.Fa "const uint8_t msg3[48]" +.Fc +.Sh DESCRIPTION +These functions perform a key exchange between a +.Em client +and a +.Em server +to establish a secure channel. +The result of the key exchange is a +.Em session key +that is suitable for use with +.Xr crypto_lock 3monocypher . +The +.Em server +must have generated an X25519 secret key and its corresponding public +key ahead of time using +.Xr crypto_key_exchange_public_key 3monocypher . +This key is also used by the client to verify the server's identity. +The +.Em client +must know the +.Em server's +public key before performing the key exchange. +The +.Em client +initiates the key exchange. +.Pp +These functions differ from the +.Xr crypto_kex_x_init_client 3monocypher +functions in that the functions described in this page authenticate a +server's identity. +.Ss Key exchange as the client +When starting a new connection to the server, the client first calls +.Fn crypto_client_xk1_init_client +to initialize a +.Vt crypto_kex_ctx . +The arguments to +.Fn crypto_client_xk1_init_client +are: +.Bl -tag -width Ds +.It Fa ctx +A pointer to a +.Vt crypto_kex_ctx . +.It Fa random_seed +32 randomly generated bytes. +See +.Xr intro 3monocypher +for advice about generating random bytes (use the operating system's +random number generator). +.It Fa local_sk +A 32-byte secret random number. +This should be different for every connection the client makes. +.It Fa local_pk +The public key corresponding to the +.Fa local_sk , +generated using +.Xr crypto_key_exchange_public_key 3monocypher . +If +.Dv NULL , +the public key will be generated for you. +.It Fa remote_pk +The public key of the server, which must be known to the client before +making a connection. +This is used to authenticate the server's identity. +.El +.Pp +After creating initializing +.Fa ctx , +the client calls +.Fn crypto_kex_xk1_1 +to generate +.Fa msg1 . +It proceeds to send +.Fa msg1 +to the server. +The client then reads +.Fa msg2 +from the server. +It calls +.Fn crypto_kex_xk1_3 , +which yields the +.Fa session_key +and +.Fa msg3 . +.Fn crypto_kex_xk1_3 +returns zero on success and -1 if the server's message mismatches the +key exchange until now. +.Em Always check the return value . +On success, this function also wipes the data in +.Fa ctx . +The client sends +.Fa msg3 +to the server to complete the key exchange. +.Ss Key exchange as the server +When accepting a new connection from a client, the server first calls +.Fn crypto_client_xk1_init_server +to initialize a +.Vt crypto_kex_ctx . +The arguments to +.Fn crypto_client_xk1_init_server +are identical to the arguments to +.Fn crypto_client_xk1_init_client , +except that the server does not know a client's public key yet, +so no +.Fa remote_pk +can be specified; +the server's +.Fa local_sk +and +.Fa local_pk +are generated ahead of time and known to the clients. +.Pp +After initializing +.Fa ctx , +the server waits for the client to send +.Fa msg1 +and reads it from the network. +The server then calls +.Fn crypto_kex_xk1_2 +with +.Fa msg1 , +which yields +.Fa msg2 . +.Fa msg2 +is sent to the client. +The server reads the client's response +.Fa ( msg3 ) +from the network and calls +.Fn crypto_kex_xk1_4 +with +.Fa msg3 , +which yields +.Fa session_key +and +.Fa remote_pk , +the client's public key. +.Fn crypto_kex_xk1_4 +returns zero on success and -1 if the client's message mismatches the +key exchange until now. +.Em Always check the return value . +On success, this function also wipes the data in +.Fa ctx . +.Sh RETURN VALUES +.Fn crypto_kex_xk1_init_client , +.Fn crypto_kex_xk1_init_server , +.Fn crypto_kex_xk1_1 +and +.Fn crypto_kex_xk1_2 +return nothing. +.Pp +.Fn crypto_kex_xk1_3 +and +.Fn crypto_kex_xk1_4 +return 0 on success or -1 if the messages were corrupt or mismatched the +server's identity. +Corruption can be caused by transmission errors, programmer error, or an +attacker's interference. +.Sh EXAMPLES +These examples use UNIX\(rg networking functions to keep the examples +readable, +but any kind of networking code will work. +It is assumed that the client and server have already established a +connection with each other. +.Pp +Client: +.Bd -literal -offset indent +crypto_kex_ctx client_ctx; /* key exchange context */ +uint8_t sk[32]; /* 32 random bytes ephemeral secret key */ +uint8_t their_pk[32]; /* the server's public key + * (known ahead of time) */ +uint8_t seed[32]; /* 32 random bytes */ +uint8_t buf[48]; /* buffer for the key exchange messages */ +uint8_t session_key[32]; /* the resulting session key */ +int fd; /* the socket of the connection */ + +/* (generate random bytes in seed and sk here) */ +crypto_kex_xk1_init_client(&client_ctx, seed, sk, NULL, their_pk); +crypto_kex_xk1_1(&client_ctx, buf); +if (write(fd, buf, 32) != 32) + return -1; +if (read(fd, buf, 48) != 48) + return -2; +if (crypto_kex_xk1_3(&client_ctx, session_key, buf, buf) != 0) + return -3; +if (write(fd, buf, 48) != 48) + return -4; +/* key exchange complete; + * send/receive messages encrypted with crypto_lock() now */ +.Ed +.Pp +Server: +.Bd -literal -offset indent +crypto_kex_ctx server_ctx; /* key exchange context */ +uint8_t sk[32]; /* 32 random bytes long-term secret key */ +uint8_t my_pk[32]; /* public key to sk */ +uint8_t their_pk[32]; /* the client's public key */ +uint8_t seed[32]; /* 32 random bytes */ +uint8_t buf[48]; /* buffer for the key exchange messages */ +uint8_t session_key[32]; /* the resulting session key */ +int fd; /* the socket of the connection */ + +/* (generate random bytes in seed here) */ +crypto_kex_xk1_init_server(&server_ctx, seed, sk, my_pk); +if (read(fd, buf, 32) != 32) + return -1; +crypto_kex_xk1_2(&server_ctx, buf, buf); +if (write(fd, buf, 48) != 48) + return -2; +if (read(fd, buf, 48) != 48) + return -3; +if (crypto_kex_xk1_4(&server_ctx, session_key, their_pk, buf) != 0) + return -4; +/* key exchange complete; + * send/receive messages encrypted with crypto_lock() now */ +.Ed +.Sh SEE ALSO +.Xr crypto_key_exchange 3monocypher , +.Xr crypto_kex_x_init_client 3monocypher , +.Xr crypto_lock 3monocypher , +.Xr intro 3monocypher +.Sh STANDARDS +These functions are equivalent to an implementation of the XK1 pattern +of the Noise protocol framework. diff --git a/doc/man/man3/crypto_kex_xk1_init_server.3monocypher b/doc/man/man3/crypto_kex_xk1_init_server.3monocypher new file mode 120000 index 0000000..4d554a4 --- /dev/null +++ b/doc/man/man3/crypto_kex_xk1_init_server.3monocypher @@ -0,0 +1 @@ +crypto_kex_xk1_init_client.3monocypher \ No newline at end of file diff --git a/doc/man/man3/crypto_key_exchange.3monocypher b/doc/man/man3/crypto_key_exchange.3monocypher index 313b1da..7285628 100644 --- a/doc/man/man3/crypto_key_exchange.3monocypher +++ b/doc/man/man3/crypto_key_exchange.3monocypher @@ -24,6 +24,12 @@ computes a shared key with your secret key and their public key. .Pp .Fn crypto_key_exchange_public_key deterministically computes the public key from a random secret key. +It is a medium-level primitive. +Prefer the +.Xr crypto_kex_xk1_init_client 3monocypher +and +.Xr crypto_kex_x_init_client 3monocypher +families of functions unless you have a specific reason not to. .Pp The arguments are: .Bl -tag -width Ds -- 2.47.3