Noise-C
 All Data Structures Files Functions Variables Typedefs Macros Groups Pages
Typedefs | Functions
HandshakeState API

Typedefs

typedef struct
NoiseHandshakeState_s 
NoiseHandshakeState
 Opaque object that represents a HandshakeState. More...
 

Functions

int noise_handshakestate_fallback (NoiseHandshakeState *state)
 Falls back to the "XXfallback" handshake pattern. More...
 
int noise_handshakestate_fallback_to (NoiseHandshakeState *state, int pattern_id)
 Falls back to another handshake pattern. More...
 
int noise_handshakestate_free (NoiseHandshakeState *state)
 Frees a HandshakeState object after destroying all sensitive material. More...
 
int noise_handshakestate_get_action (const NoiseHandshakeState *state)
 Gets the next action the application should perform for the handshake phase of the protocol. More...
 
NoiseDHStatenoise_handshakestate_get_fixed_ephemeral_dh (NoiseHandshakeState *state)
 Gets the DHState object that contains the local ephemeral keypair. More...
 
NoiseDHStatenoise_handshakestate_get_fixed_hybrid_dh (NoiseHandshakeState *state)
 Gets the DHState object that contains the local additional hybrid secrecy keypair. More...
 
int noise_handshakestate_get_handshake_hash (const NoiseHandshakeState *state, uint8_t *hash, size_t max_len)
 Gets the handshake hash value once the handshake ends. More...
 
NoiseDHStatenoise_handshakestate_get_local_keypair_dh (const NoiseHandshakeState *state)
 Gets the DHState object that contains the local static keypair. More...
 
int noise_handshakestate_get_protocol_id (const NoiseHandshakeState *state, NoiseProtocolId *id)
 Gets the protocol identifier associated with a HandshakeState object. More...
 
NoiseDHStatenoise_handshakestate_get_remote_public_key_dh (const NoiseHandshakeState *state)
 Gets the DHState object that contains the remote static public key. More...
 
int noise_handshakestate_get_role (const NoiseHandshakeState *state)
 Gets the role that a HandshakeState object is playing. More...
 
int noise_handshakestate_has_local_keypair (const NoiseHandshakeState *state)
 Determine if a HandshakeState has been configured with a local keypair. More...
 
int noise_handshakestate_has_pre_shared_key (const NoiseHandshakeState *state)
 Determine if a HandshakeState object has already been configured with a pre shared key. More...
 
int noise_handshakestate_has_remote_public_key (const NoiseHandshakeState *state)
 Determine if a HandshakeState has a remote public key. More...
 
int noise_handshakestate_needs_local_keypair (const NoiseHandshakeState *state)
 Determine if a HandshakeState still needs to be configured with a local keypair. More...
 
int noise_handshakestate_needs_pre_shared_key (const NoiseHandshakeState *state)
 Determine if a HandshakeState object requires a pre shared key. More...
 
int noise_handshakestate_needs_remote_public_key (const NoiseHandshakeState *state)
 Determine if a HandshakeState still needs to be configured with a remote public key before the protocol can start. More...
 
int noise_handshakestate_new_by_id (NoiseHandshakeState **state, const NoiseProtocolId *protocol_id, int role)
 Creates a new HandshakeState object by protocol identifier. More...
 
int noise_handshakestate_new_by_name (NoiseHandshakeState **state, const char *protocol_name, int role)
 Creates a new HandshakeState object by protocol name. More...
 
int noise_handshakestate_read_message (NoiseHandshakeState *state, NoiseBuffer *message, NoiseBuffer *payload)
 Reads a message payload using a HandshakeState. More...
 
int noise_handshakestate_set_pre_shared_key (NoiseHandshakeState *state, const uint8_t *key, size_t key_len)
 Sets the pre shared key for a HandshakeState. More...
 
int noise_handshakestate_set_prologue (NoiseHandshakeState *state, const void *prologue, size_t prologue_len)
 Sets the prologue for a HandshakeState. More...
 
int noise_handshakestate_split (NoiseHandshakeState *state, NoiseCipherState **send, NoiseCipherState **receive)
 Splits the transport encryption CipherState objects out of this HandshakeState object. More...
 
int noise_handshakestate_start (NoiseHandshakeState *state)
 Starts the handshake on a HandshakeState object. More...
 
int noise_handshakestate_write_message (NoiseHandshakeState *state, NoiseBuffer *message, const NoiseBuffer *payload)
 Writes a message payload using a HandshakeState. More...
 

Detailed Description

See the echo example for an overview of how to use this API.

Typedef Documentation

Opaque object that represents a HandshakeState.

Definition at line 33 of file handshakestate.h.

Function Documentation

int noise_handshakestate_fallback ( NoiseHandshakeState state)

Falls back to the "XXfallback" handshake pattern.

Parameters
stateThe HandshakeState object.
Returns
NOISE_ERROR_NONE on error.
NOISE_ERROR_INVALID_PARAM if state is NULL.
NOISE_ERROR_INVALID_STATE if the previous protocol has not been started or has not reached the fallback position yet.
NOISE_ERROR_INVALID_LENGTH if the new protocol name is too long.
NOISE_ERROR_NOT_APPLICABLE if the handshake pattern in the original protocol name is not compatible with "XXfallback".

This function is intended used to help implement the "Noise Pipes" protocol. It resets a HandshakeState object with the original handshake pattern (usually "IK"), converting it into an object with the handshake pattern "XXfallback". Information from the previous session such as the local keypair, the initiator's ephemeral key, the prologue value, and the pre-shared key, are passed to the new session.

Once the fallback has been initiated, the application can set new values for the handshake parameters if the values from the previous session do not apply. For example, the application may use a different prologue for the fallback than for the original session.

After setting any new parameters, the application calls noise_handshakestate_start() again to restart the handshake from where it left off before the fallback.

Note
This function reverses the roles of initiator and responder.
See Also
noise_handshakestate_start(), noise_handshakestate_fallback_to()

Definition at line 921 of file handshakestate.c.

int noise_handshakestate_fallback_to ( NoiseHandshakeState state,
int  pattern_id 
)

Falls back to another handshake pattern.

Parameters
stateThe HandshakeState object.
pattern_idThe identifier for the pattern to fallback to; e.g. NOISE_PATTERN_XX_FALLBACK, NOISE_PATTERN_NX_FALLBACK, etc.
Returns
NOISE_ERROR_NONE on error.
NOISE_ERROR_INVALID_PARAM if state is NULL.
NOISE_ERROR_INVALID_STATE if the previous protocol has not been started or has not reached the fallback position yet.
NOISE_ERROR_INVALID_LENGTH if the new protocol name is too long.
NOISE_ERROR_NOT_APPLICABLE if the handshake pattern in the original protocol name is not compatible with pattern_id.
NOISE_ERROR_NOT_APPLICABLE if pattern_id does not identify a fallback pattern.

This function is a generalization of the "Noise Pipes" protocol, allowing for other combinations of patterns to be used for the full handshake, abbreviated handshake, and fallback handshake. For example, "NX/NK/NXfallback", "XX/XK/XXfallback", etc.

This function resets a HandshakeState object with the original handshake pattern, and converts it into an object with the new handshake pattern_id. Information from the previous session such as the local keypair, the initiator's ephemeral key, the prologue value, and the pre-shared key, are passed to the new session.

Once the fallback has been initiated, the application can set new values for the handshake parameters if the values from the previous session do not apply. For example, the application may use a different prologue for the fallback than for the original session.

After setting any new parameters, the application calls noise_handshakestate_start() again to restart the handshake from where it left off before the fallback.

The new pattern may have greater key requirements than the original; for example changing from "NK" from "XXfallback" requires that the initiator's static public key be set. The application is responsible for setting any extra keys before calling noise_handshakestate_start().

Note
This function reverses the roles of initiator and responder.
See Also
noise_handshakestate_start(), noise_handshakestate_fallback()

Definition at line 973 of file handshakestate.c.

int noise_handshakestate_free ( NoiseHandshakeState state)

Frees a HandshakeState object after destroying all sensitive material.

Parameters
stateThe HandshakeState object to free.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state is NULL.
See Also
noise_handshakestate_new_by_id(), noise_handshakestate_new_by_name()

Definition at line 336 of file handshakestate.c.

int noise_handshakestate_get_action ( const NoiseHandshakeState state)

Gets the next action the application should perform for the handshake phase of the protocol.

Parameters
stateThe HandshakeState object.
Returns
NOISE_ACTION_NONE if no action needs to be taken by the application because the protocol hasn't started yet.
NOISE_ACTION_WRITE_MESSAGE if the application is expected to write a new message payload for the next outgoing handshake message using noise_handshakestate_write_message().
NOISE_ACTION_READ_MESSAGE if the application is expected wait for an incoming handshake message from the remote party and then pass the message to noise_handshakestate_read_message() to extract the payload.
NOISE_ACTION_FAILED if the handshake has failed with an error. The application should destroy the HandshakeState by calling noise_handshakestate_free() and terminate the connection. If the application is using Noise Pipes, then it may be able to continue by calling noise_handshakestate_fallback() depending upon where in the protocol the failure occurred.
NOISE_ACTION_SPLIT if the handshake has finished successfully and the application should call noise_handshakestate_split() to obtain the CipherState objects for the data phase of the protocol.
NOISE_ACTION_COMPLETE if the handshake has finished successfully and noise_handshakestate_split() has been called.
See Also
noise_handshakestate_write_message(), noise_handshakestate_read_message(), noise_handshakestate_split(), noise_handshakestate_fallback()

Definition at line 1112 of file handshakestate.c.

NoiseDHState* noise_handshakestate_get_fixed_ephemeral_dh ( NoiseHandshakeState state)

Gets the DHState object that contains the local ephemeral keypair.

Parameters
stateThe HandshakeState object.
Returns
Returns a pointer to the DHState object for the local ephemeral keypair, or NULL if the system is out of memory or state is NULL.
Note
This function is intended for testing only. It can be used to establish a fixed ephemeral key for test vectors. This function should not be used in real applications.
See Also
noise_handshakestate_get_local_keypair_dh()

Definition at line 459 of file handshakestate.c.

NoiseDHState* noise_handshakestate_get_fixed_hybrid_dh ( NoiseHandshakeState state)

Gets the DHState object that contains the local additional hybrid secrecy keypair.

Parameters
stateThe HandshakeState object.
Returns
Returns a pointer to the DHState object for the local additional hybrid secrecy keypair, or NULL if the system is out of memory, state is NULL, or state does not support additional hybrid secrecy.
Note
This function is intended for testing only. It can be used to establish a fixed hybrid secrecy key for test vectors. This function should not be used in real applications.
See Also
noise_handshakestate_get_fixed_ephemeral_dh()

Definition at line 495 of file handshakestate.c.

int noise_handshakestate_get_handshake_hash ( const NoiseHandshakeState state,
uint8_t *  hash,
size_t  max_len 
)

Gets the handshake hash value once the handshake ends.

Parameters
stateThe HandshakeState object.
hashThe buffer to receive the handshake hash value.
max_lenThe maximum length of the hash buffer.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state or hash is NULL.
NOISE_ERROR_INVALID_STATE if the handshake has not successfully completed yet.

If max_len is greater than the length of the handshake hash, then the extra bytes will be filled with zeroes. If max_len is less than the length of the handshake hash, then the value will be truncated to the first max_len bytes. Handshake hashes are typically 32 or 64 bytes in length, depending upon the hash algorithm that was used during the protocol.

The handshake hash can be used to implement "channel binding". The value will be a unique identifier for the session.

Note
The handshake hash is generated from publicly-known values in the handshake. If the application needs a unique secret identifier, then it should combine the handshake hash with other randomly generated data that is sent encrypted during the session.
See Also
noise_handshakestate_split()

Definition at line 1760 of file handshakestate.c.

NoiseDHState* noise_handshakestate_get_local_keypair_dh ( const NoiseHandshakeState state)

Gets the DHState object that contains the local static keypair.

Parameters
stateThe HandshakeState object.
Returns
Returns a pointer to the DHState object for the local static keypair, or NULL if the handshake does not require a local static keypair.

The application uses the returned object to set the static keypair for the local end of the handshake if one is required.

See Also
noise_handshakestate_get_remote_public_key_dh()

Definition at line 418 of file handshakestate.c.

int noise_handshakestate_get_protocol_id ( const NoiseHandshakeState state,
NoiseProtocolId id 
)

Gets the protocol identifier associated with a HandshakeState object.

Parameters
stateThe HandshakeState object.
idReturn buffer for the protocol identifier, which consists of fields that identify the cipher algorithm, hash algorith, handshake pattern, etc.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state or id is NULL.

Definition at line 393 of file handshakestate.c.

NoiseDHState* noise_handshakestate_get_remote_public_key_dh ( const NoiseHandshakeState state)

Gets the DHState object that contains the remote static public key.

Parameters
stateThe HandshakeState object.
Returns
Returns a pointer to the DHState object for the remote static public key, or NULL if the handshake does not require a remote public key.

The application uses the returned object to set the public key for the remote end of the handshake if the key must be provided prior to the handshake. The returned object can also be used to obtain the public key value that was transmitted by the remote party during the handshake.

See Also
noise_handshakestate_get_local_keypair_dh()

Definition at line 439 of file handshakestate.c.

int noise_handshakestate_get_role ( const NoiseHandshakeState state)

Gets the role that a HandshakeState object is playing.

Parameters
stateThe HandshakeState object.
Returns
Returns one of NOISE_ROLE_INITIATOR or NOISE_ROLE_RESPONDER if state is non-NULL, or zero if state is NULL.

Definition at line 376 of file handshakestate.c.

int noise_handshakestate_has_local_keypair ( const NoiseHandshakeState state)

Determine if a HandshakeState has been configured with a local keypair.

Parameters
stateThe HandshakeState object.
Returns
Returns 1 if the state has already been configured with a local keypair, or 0 if the keypair is yet to be provided. Also returns zero if state is NULL.
See Also
noise_handshakestate_needs_local_keypair(), noise_handshakestate_get_local_keypair_dh()

Definition at line 685 of file handshakestate.c.

int noise_handshakestate_has_pre_shared_key ( const NoiseHandshakeState state)

Determine if a HandshakeState object has already been configured with a pre shared key.

Parameters
stateThe HandshakeState object.
Returns
Returns 1 if state has a pre shared key, zero if not.
See Also
noise_handshakestate_set_pre_shared_key(), noise_handshakestate_needs_pre_shared_key()

Definition at line 550 of file handshakestate.c.

int noise_handshakestate_has_remote_public_key ( const NoiseHandshakeState state)

Determine if a HandshakeState has a remote public key.

Parameters
stateThe HandshakeState object.
Returns
Returns 1 if the state has a remote public key, or 0 if the key is yet to be seen. Also returns zero if state is NULL.

A remote public key may either be provided ahead of time on the noise_handshakestate_get_remote_public_key_dh() object, or it may be provided by the remote party during the handshake.

See Also
noise_handshakestate_needs_remote_public_key(), noise_handshakestate_set_remote_public_key()

Definition at line 735 of file handshakestate.c.

int noise_handshakestate_needs_local_keypair ( const NoiseHandshakeState state)

Determine if a HandshakeState still needs to be configured with a local keypair.

Parameters
stateThe HandshakeState object.
Returns
Returns 1 if the state has not yet been configured with a local keypair, or 0 if the keypair has been provided or is not required at all. Also returns zero if state is NULL.

The application configures the local keypair on the object returned by noise_handshakestate_get_local_keypair_dh().

See Also
noise_handshakestate_has_local_keypair(), noise_handshakestate_get_local_keypair_dh()

Definition at line 663 of file handshakestate.c.

int noise_handshakestate_needs_pre_shared_key ( const NoiseHandshakeState state)

Determine if a HandshakeState object requires a pre shared key.

Parameters
stateThe HandshakeState object.
Returns
Returns 1 if state requires a pre shared key, zero if the pre shared key has already been supplied or it is not required.
See Also
noise_handshakestate_set_pre_shared_key(), noise_handshakestate_has_pre_shared_key()

Definition at line 531 of file handshakestate.c.

int noise_handshakestate_needs_remote_public_key ( const NoiseHandshakeState state)

Determine if a HandshakeState still needs to be configured with a remote public key before the protocol can start.

Parameters
stateThe HandshakeState object.
Returns
Returns 1 if the state has not yet been configured with a required remote public key, or 0 if the key has been provided or is not required at all. Also returns zero if state is NULL.

This function indicates that a remote public key must be supplied before the protocol starts. If it is possible for the remote public key to be provided by the remote party during the session, then the remote public key can be obtained at the end of the handshake using the noise_handshakestate_get_remote_public_key_dh() object.

See Also
noise_handshakestate_has_remote_public_key(), noise_handshakestate_get_remote_public_key_dh()

Definition at line 711 of file handshakestate.c.

int noise_handshakestate_new_by_id ( NoiseHandshakeState **  state,
const NoiseProtocolId protocol_id,
int  role 
)

Creates a new HandshakeState object by protocol identifier.

Parameters
statePoints to the variable where to store the pointer to the new HandshakeState object.
protocol_idThe protocol identifier as a set of algorithm identifiers.
roleThe role for the new object, either NOISE_ROLE_INITIATOR or NOISE_ROLE_RESPONDER.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if either state or protocol_id is NULL, or role is not one of NOISE_ROLE_INITIATOR or NOISE_ROLE_RESPONDER.
NOISE_ERROR_UNKNOWN_ID if the protocol_id is unknown.
NOISE_ERROR_INVALID_LENGTH if the full name corresponding to protocol_id is too long.
NOISE_ERROR_NOT_APPLICABLE if the combination of algorithm identifiers in protocol_id is not permitted.
NOISE_ERROR_NO_MEMORY if there is insufficient memory to allocate the new HandshakeState object.
See Also
noise_handshakestate_free(), noise_handshakestate_new_by_name()

Definition at line 257 of file handshakestate.c.

int noise_handshakestate_new_by_name ( NoiseHandshakeState **  state,
const char *  protocol_name,
int  role 
)

Creates a new HandshakeState object by protocol name.

Parameters
statePoints to the variable where to store the pointer to the new HandshakeState object.
protocol_nameThe name of the Noise protocol to use. This string must be NUL-terminated.
roleThe role for the new object, either NOISE_ROLE_INITIATOR or NOISE_ROLE_RESPONDER.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if either state or protocol_name is NULL, or role is not one of NOISE_ROLE_INITIATOR or NOISE_ROLE_RESPONDER.
NOISE_ERROR_UNKNOWN_NAME if the protocol_name is unknown.
NOISE_ERROR_NOT_APPLICABLE if the combination of algorithm identifiers in protocol_id is not permitted.
NOISE_ERROR_NO_MEMORY if there is insufficient memory to allocate the new HandshakeState object.
See Also
noise_handshakestate_free(), noise_handshakestate_new_by_id()

Definition at line 303 of file handshakestate.c.

int noise_handshakestate_read_message ( NoiseHandshakeState state,
NoiseBuffer message,
NoiseBuffer payload 
)

Reads a message payload using a HandshakeState.

Parameters
stateThe HandshakeState object.
messagePoints to the incoming handshake message to be unpacked.
payloadPoints to the buffer to fill with the message payload. This can be NULL if the application does not need the message payload.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state or message is NULL.
NOISE_ERROR_INVALID_STATE if noise_handshakestate_get_action() is not NOISE_ACTION_READ_MESSAGE.
NOISE_ERROR_INVALID_LENGTH if the size of message is incorrect for the type of handshake packet that we expect.
NOISE_ERROR_INVALID_LENGTH if the size of payload is too small to contain all of the payload bytes that were present in the message.
NOISE_ERROR_MAC_FAILURE if the message failed to authenticate, which terminates the handshake.
NOISE_ERROR_PUBLIC_KEY if an invalid remote public key is seen during the processing of this message.

If payload is NULL, then the message payload will be authenticated and then discarded, regardless of its length. If the application was expecting an empty payload and wants to verify that, then payload should point to a non-NULL zero-length buffer.

The mesaage and payload buffers must not overlap in memory.

The message buffer will be modified by this function to decrypt sub-components while it is being processed. The contents will be cleared just before the function exits to avoid leaking decrypted message data other than the payload.

See Also
noise_handshakestate_write_message(), noise_handshakestate_get_action()

Definition at line 1640 of file handshakestate.c.

int noise_handshakestate_set_pre_shared_key ( NoiseHandshakeState state,
const uint8_t *  key,
size_t  key_len 
)

Sets the pre shared key for a HandshakeState.

Parameters
stateThe HandshakeState object.
keyPoints to the pre shared key.
key_lenThe length of the key in bytes. This must be 32 to comply with the requirements from the Noise protocol specification.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state or key is NULL.
NOISE_ERROR_INVALID_LENGTH if key_len is not 32.
NOISE_ERROR_NOT_APPLICABLE if the protocol name does not begin with "NoisePSK".
NOISE_ERROR_INVALID_STATE if this function is called after the protocol has already started.
See Also
noise_handshakestate_start(), noise_handshakestate_set_prologue(), noise_handshakestate_needs_pre_shared_key(), noise_handshakestate_has_pre_shared_key()

Definition at line 579 of file handshakestate.c.

int noise_handshakestate_set_prologue ( NoiseHandshakeState state,
const void *  prologue,
size_t  prologue_len 
)

Sets the prologue for a HandshakeState.

Parameters
stateThe HandshakeState object.
prologuePoints to the prologue value.
prologue_lenThe length of the prologue value in bytes.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state or prologue is NULL.
NOISE_ERROR_INVALID_STATE if this function is called after the protocol has already started.
NOISE_ERROR_NO_MEMORY if there is insufficient memory to save the prologue value.

This function should be called immediately after noise_handshakestate_new_by_id() or noise_handshakestate_new_by_name() if there is a prologue for the session. If the function is not called, then the prologue will be assumed to be empty when the protocol starts.

See Also
noise_handshakestate_start(), noise_handshakestate_set_pre_shared_key()

Definition at line 619 of file handshakestate.c.

int noise_handshakestate_split ( NoiseHandshakeState state,
NoiseCipherState **  send,
NoiseCipherState **  receive 
)

Splits the transport encryption CipherState objects out of this HandshakeState object.

Parameters
stateThe HandshakeState object.
sendPoints to the variable where to place the pointer to the CipherState object to use to send packets from local to remote. This can be NULL if the application is using a one-way handshake pattern.
receivePoints to the variable where to place the pointer to the CipherState object to use to receive packets from the remote to local. This can be NULL if the application is using a one-way handshake pattern.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state is NULL.
NOISE_ERROR_INVALID_PARAM if both send and receive are NULL.
NOISE_ERROR_INVALID_STATE if the state has already been split or the handshake protocol has not completed successfully yet.
NOISE_ERROR_NO_MEMORY if there is insufficient memory to create the new CipherState objects.

Once a HandshakeState has been split, it is effectively finished and cannot be used for future handshake operations. If those operations are invoked, the relevant functions will return NOISE_ERROR_INVALID_STATE.

The send object should be used to protect messages from the local side to the remote side, and the receive object should be used to protect messages from the remote side to the local side.

If the handshake pattern is one-way, then the application should call noise_cipherstate_free() on the object that is not needed. Alternatively, the application can pass NULL to noise_handshakestate_split() as the send or receive argument and the second CipherState will not be created at all.

See Also
noise_handshakestate_get_handshake_hash()

Definition at line 1702 of file handshakestate.c.

int noise_handshakestate_start ( NoiseHandshakeState state)

Starts the handshake on a HandshakeState object.

Parameters
stateThe HandshakeState object.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state is NULL.
NOISE_ERROR_LOCAL_KEY_REQUIRED if a local keypair is required to start the protocol but one has not been provided yet.
NOISE_ERROR_REMOTE_KEY_REQUIRED if a remote public key is required to start the protocol but one has not been provided yet.
NOISE_ERROR_PSK_REQUIRED if a pre shared key is required to start the protocol but one has not been provided yet.
NOISE_ERROR_INVALID_STATE if the protocol handshake has already started.
NOISE_ERROR_NOT_APPLICABLE if an attempt was made to start a fallback handshake pattern without first calling noise_handshakestate_fallback() on a previous handshake.

This function is called after all of the handshake parameters have been provided to the HandshakeState object. This function should be followed by calls to noise_handshake_write_message() or noise_handshake_read_message() to process the handshake messages. The noise_handshakestate_get_action() function indicates the action to take next.

See Also
noise_handshake_write_message(), noise_handshake_read_message(), noise_handshakestate_get_action(), noise_handshakestate_fallback()

Definition at line 800 of file handshakestate.c.

int noise_handshakestate_write_message ( NoiseHandshakeState state,
NoiseBuffer message,
const NoiseBuffer payload 
)

Writes a message payload using a HandshakeState.

Parameters
stateThe HandshakeState object.
messagePoints to the message buffer to be populated with handshake details and the message payload.
payloadPoints to the message payload to be sent, which can be NULL if no payload is required.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state or message is NULL.
NOISE_ERROR_INVALID_STATE if noise_handshakestate_get_action() is not NOISE_ACTION_WRITE_MESSAGE.
NOISE_ERROR_INVALID_LENGTH if message is too small to contain all of the bytes that need to be written to it.

The message and payload buffers must not overlap in memory.

The following example demonstrates how to write a handshake message into the application's msgbuf array:

NoiseBuffer payload;
uint8_t payloadbuf[PAYLOAD_LEN];
// Format the message payload into "payloadbuf".
noise_buffer_set_input(payload, payloadbuf, sizeof(payloadbuf));
uint8_t msgbuf[MSGBUF_MAX];
NoiseBuffer message;
noise_buffer_set_output(message, msgbuf, sizeof(msgbuf));
err = noise_handshakestate_write_message(state, &message, &payload);
// Transmit the message.size bytes starting at message.data if no error.
See Also
noise_handshakestate_read_message(), noise_handshakestate_get_action()

Definition at line 1380 of file handshakestate.c.