It will be corrected and added later, once we integrate the latest Monokex.
+++ /dev/null
-crypto_kex_x_init_client.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_kex_x_init_client.3monocypher
\ No newline at end of file
+++ /dev/null
-.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).
+++ /dev/null
-crypto_kex_x_init_client.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_kex_xk1_init_client.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_kex_xk1_init_client.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_kex_xk1_init_client.3monocypher
\ No newline at end of file
+++ /dev/null
-crypto_kex_xk1_init_client.3monocypher
\ No newline at end of file
+++ /dev/null
-.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.
+++ /dev/null
-crypto_kex_xk1_init_client.3monocypher
\ No newline at end of file
projects / Monocypher.git / commitdiff