From: Loup Vaillant Date: Fri, 4 Oct 2019 21:15:03 +0000 (+0200) Subject: Removed kex documentation X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=6163d8195a3acf2e143d20843a602fd5fb7671d5;p=Monocypher.git Removed kex documentation It will be corrected and added later, once we integrate the latest Monokex. --- diff --git a/doc/man/man3/crypto_kex_x_1.3monocypher b/doc/man/man3/crypto_kex_x_1.3monocypher deleted file mode 120000 index 9220da8..0000000 --- a/doc/man/man3/crypto_kex_x_1.3monocypher +++ /dev/null @@ -1 +0,0 @@ -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 deleted file mode 120000 index 9220da8..0000000 --- a/doc/man/man3/crypto_kex_x_2.3monocypher +++ /dev/null @@ -1 +0,0 @@ -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 deleted file mode 100644 index 85b0853..0000000 --- a/doc/man/man3/crypto_kex_x_init_client.3monocypher +++ /dev/null @@ -1,272 +0,0 @@ -.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_client_ctx *client_ctx" -.Fa "uint8_t random_seed[32]" -.Fa "const uint8_t client_sk[32]" -.Fa "const uint8_t client_pk[32]" -.Fa "const uint8_t server_pk[32]" -.Fc -.Ft void -.Fo crypto_kex_x_init_server -.Fa "crypto_kex_server_ctx *server_ctx" -.Fa "const uint8_t server_sk[32]" -.Fa "const uint8_t server_pk[32]" -.Fc -.Ft void -.Fo crypto_kex_x_1 -.Fa "crypto_kex_client_ctx *client_ctx" -.Fa "uint8_t session_key[32]" -.Fa "uint8_t msg1[80]" -.Fc -.Ft void -.Fo crypto_kex_x_2 -.Fa "crypto_kex_server_ctx *server_ctx" -.Fa "uint8_t session_key[32]" -.Fa "uint8_t client_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 -and the -.Em client -each generate a long-term X25519 secret key and its corresponding public -key ahead of time before the key exchange using -.Xr crypto_key_exchange_public_key 3monocypher . -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_xk1_init_client 3monocypher -functions in that the functions described in this page -can be used even if a server is offline (i.e. asynchronous -communication); they have lower security guarantees, see -.Sx SECURITY CONSIDERATIONS . -If you can, always prefer -.Xr crypto_kex_xk1_init_client 3monocypher . -.Pp -The arguments are: -.Bl -tag -width Ds -.It Fa client_ctx -A pointer to a -.Vt crypto_kex_client_ctx , -i.e. the context for the client. -.It Fa server_ctx -A pointer to a -.Vt crypto_kex_server_ctx , -i.e. the context for the server. -.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). -This argument is not constant because it is wiped after use. -.It Fa client_sk -A 32-byte secret random number. -This is a long-term secret used to identify the client. -.It Fa client_pk -The public key corresponding to the -.Fa client_sk , -generated using -.Xr crypto_key_exchange_public_key 3monocypher . -If -.Dv NULL , -the public key will be generated for you. -.It Fa server_sk -A 32-byte secret random number. -This is a long-term secret used to identify the server. -.It Fa server_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. -It must thus be known to the client before making a connection. -.It Fa msg1 -A 80-byte message, which is generated and sent by the client. -It is the only message in the key exchange. -.El -.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 initialise a -.Vt crypto_kex_client_ctx . -.Pp -After initialising -.Fa client_ctx , -the client calls -.Fn crypto_kex_x_1 -to generate -.Fa msg1 -and the -.Fa session_key ; -this function also wipes the data in -.Fa client_ctx . -The client 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 calls -.Fn crypto_client_xk1_init_server -to initialise a -.Vt crypto_kex_server_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 ; -no -.Fa client_pk -can be specified because the server authenticates clients -only once the handshake completes, -which is application logic and not part of the key exchange protocol. -.Pp -After initialising -.Fa server_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 client_pk , -the client's public key. -The server can use this to authenticate clients by their public key; -.Em if possible, always authenticate clients . -.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 . -This function also wipes the data in -.Fa server_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 *NIX 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_client_ctx client_ctx; /* key exchange context */ -uint8_t client_sk[32]; /* 32 random bytes long-term secret key */ -uint8_t server_pk[32]; /* the server's public key - * (known ahead of time) */ -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 seed) */ -crypto_kex_x_init_client(&client_ctx, seed, client_sk, NULL, - server_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 server_sk[32]; /* 32 random bytes long-term secret key */ -uint8_t server_pk[32]; /* public key to server_sk */ -uint8_t client_pk[32]; /* the client'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 */ - -crypto_kex_x_init_server(&server_ctx, server_sk, server_pk); -if (read(fd, buf, 80) != 80) - return -2; -crypto_kex_1_2(&server_ctx, session_key, client_pk, buf); - -/* authenticate client using client_pk now if possible */ - -/* 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. -.Sh HISTORY -The -.Fn crypto_kex_x_init_client , -.Fn crypto_kex_x_init_server , -.Fn crypto_kex_x_1 , -and -.Fn crypto_kex_x_2 -functions first appeared in Monocypher 2.1.0. -.Sh SECURITY CONSIDERATIONS -Unlike the -.Xr crypto_kex_xk1_init_client 3monocypher -family of functions, the functions described on this page suffer from a -number of security issues: -.Bl -tag -width Ds -.It Limited forward secrecy -If an attacker manages to steal the server's long-term secret key, -past messages may be recovered. -.It Replay attacks -The server does not send a random challenge in this. -.It Key compromise impersonation -If an attacker manages to steal the server's long-term secret key, -the attacker can impersonate -.Em any -client to that server; if client identity is tied to authorization, -this also means that authorization requirements can be bypassed. -.El -.Pp -The reason they are provided is because they work even if the other -party cannot respond to a key exchange immediately (e.g. if the server -may not always be available; consider something like crash dumps where -a program may be used temporarily in an offline environment). diff --git a/doc/man/man3/crypto_kex_x_init_server.3monocypher b/doc/man/man3/crypto_kex_x_init_server.3monocypher deleted file mode 120000 index 9220da8..0000000 --- a/doc/man/man3/crypto_kex_x_init_server.3monocypher +++ /dev/null @@ -1 +0,0 @@ -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 deleted file mode 120000 index 4d554a4..0000000 --- a/doc/man/man3/crypto_kex_xk1_1.3monocypher +++ /dev/null @@ -1 +0,0 @@ -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 deleted file mode 120000 index 4d554a4..0000000 --- a/doc/man/man3/crypto_kex_xk1_2.3monocypher +++ /dev/null @@ -1 +0,0 @@ -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 deleted file mode 120000 index 4d554a4..0000000 --- a/doc/man/man3/crypto_kex_xk1_3.3monocypher +++ /dev/null @@ -1 +0,0 @@ -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 deleted file mode 120000 index 4d554a4..0000000 --- a/doc/man/man3/crypto_kex_xk1_4.3monocypher +++ /dev/null @@ -1 +0,0 @@ -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 deleted file mode 100644 index ee18437..0000000 --- a/doc/man/man3/crypto_kex_xk1_init_client.3monocypher +++ /dev/null @@ -1,313 +0,0 @@ -.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_client_ctx *client_ctx" -.Fa "uint8_t random_seed[32]" -.Fa "const uint8_t client_sk[32]" -.Fa "const uint8_t client_pk[32]" -.Fa "const uint8_t server_pk[32]" -.Fc -.Ft void -.Fo crypto_kex_xk1_init_server -.Fa "crypto_kex_server_ctx *server_ctx" -.Fa "uint8_t random_seed[32]" -.Fa "const uint8_t server_sk[32]" -.Fa "const uint8_t server_pk[32]" -.Fc -.Ft void -.Fo crypto_kex_xk1_1 -.Fa "crypto_kex_client_ctx *client_ctx" -.Fa "uint8_t msg1[32]" -.Fc -.Ft void -.Fo crypto_kex_xk1_2 -.Fa "crypto_kex_server_ctx *server_ctx" -.Fa "uint8_t msg2[48]" -.Fa "const uint8_t msg1[32]" -.Fc -.Ft int -.Fo crypto_kex_xk1_3 -.Fa "crypto_kex_client_ctx *client_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_server_ctx *server_ctx" -.Fa "uint8_t session_key[32]" -.Fa "uint8_t client_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 -and the -.Em client -each generate a long-term X25519 secret key and its corresponding public -key ahead of time before the key exchange using -.Xr crypto_key_exchange_public_key 3monocypher . -These keys are also used by the by each party to verify the other -party'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 provide stronger -security guarantees, but also require the server to be able to respond -to a connection from a client immediately. -.Pp -The arguments are: -.Bl -tag -width Ds -.It Fa client_ctx -A pointer to a -.Vt crypto_kex_client_ctx , -i.e. the context for the client. -.It Fa server_ctx -A pointer to a -.Vt crypto_kex_server_ctx , -i.e. the context for the server. -.It Fa random_seed -32 randomly generated bytes. -The server and the client must -.Em each -generate a -.Fa random_seed . -See -.Xr intro 3monocypher -for advice about generating random bytes (use the operating system's -random number generator). -This argument is not constant because it is wiped after use. -.It Fa client_sk -A 32-byte secret random number. -This is a long-term secret used to identify the client. -.It Fa client_pk -The public key corresponding to the -.Fa client_sk , -generated using -.Xr crypto_key_exchange_public_key 3monocypher . -If -.Dv NULL , -the public key will be generated for you. -.It Fa server_sk -A 32-byte secret random number. -This is a long-term secret used to identify the server. -.It Fa server_pk -The public key of the server. -This is used to authenticate the server's identity. -It must thus be known to the client before making a connection. -.It Fa msg1 -A 32-byte message, which is generated and sent by the client. -It starts the actual key exchange. -.It Fa msg2 -A 48-byte message, which is generated and sent by the server. -.It Fa msg3 -A 48-byte message, which is generated and sent by the client. -This is the final message in the key exchange. -.El -.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 initialise a -.Vt crypto_kex_client_ctx . -After initialising -.Fa client_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 . -This function also wipes the data in -.Fa client_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 initialise a -.Vt crypto_kex_server_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 the client's public key yet, -so no -.Fa client_pk -can be specified because the server authenticates clients -once the handshake completes; the server's -.Fa server_sk -and -.Fa server_pk -are generated ahead of time and known to the clients. -.Pp -After initialising -.Fa server_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 client_pk , -the client's public key. -The server can use this to authenticate clients by their public key; -.Em if possible, always authenticate clients . -.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 . -This function also wipes the data in -.Fa server_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 *NIX 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_client_ctx client_ctx; /* key exchange context */ -uint8_t client_sk[32]; /* 32 random bytes long-term secret key */ -uint8_t server_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 here) */ -crypto_kex_xk1_init_client(&client_ctx, seed, client_sk, NULL, - server_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_server_ctx server_ctx; /* key exchange context */ -uint8_t server_sk[32]; /* 32 random bytes long-term secret key */ -uint8_t server_pk[32]; /* public key to server_sk */ -uint8_t client_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, server_sk, server_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, client_pk, buf) != 0) - return -4; - -/* authenticate client using client_pk now if possible */ - -/* 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. -.Sh HISTORY -The -.Fn crypto_kex_xk1_init_client , -.Fn crypto_kex_xk1_init_server , -.Fn crypto_kex_xk1_1 , -.Fn crypto_kex_xk1_2 , -.Fn crypto_kex_xk1_3 , -and -.Fn crypto_kex_xk1_4 -functions first appeared in Monocypher 2.1.0. diff --git a/doc/man/man3/crypto_kex_xk1_init_server.3monocypher b/doc/man/man3/crypto_kex_xk1_init_server.3monocypher deleted file mode 120000 index 4d554a4..0000000 --- a/doc/man/man3/crypto_kex_xk1_init_server.3monocypher +++ /dev/null @@ -1 +0,0 @@ -crypto_kex_xk1_init_client.3monocypher \ No newline at end of file