#include <stddef.h>
#include <stdint.h>
#include <sys/cdefs.h>

Include dependency graph for pairing_auth.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	__INTRODUCED_IN(__api_level) /* nothing */

Typedefs
typedef struct PairingAuthCtx	PairingAuthCtx

Functions
PairingAuthCtx *	pairing_auth_server_new (const uint8_t *pswd, size_t len) __INTRODUCED_IN(30)

PairingAuthCtx *	pairing_auth_client_new (const uint8_t *pswd, size_t len) __INTRODUCED_IN(30)

void	pairing_auth_destroy (PairingAuthCtx *ctx) __INTRODUCED_IN(30)

size_t	pairing_auth_msg_size (PairingAuthCtx *ctx) __INTRODUCED_IN(30)

void	pairing_auth_get_spake2_msg (PairingAuthCtx ctx, uint8_t out_buf) __INTRODUCED_IN(30)

bool	pairing_auth_init_cipher (PairingAuthCtx ctx, const uint8_t their_msg, size_t msg_len) __INTRODUCED_IN(30)

size_t	pairing_auth_safe_encrypted_size (PairingAuthCtx *ctx, size_t len) __INTRODUCED_IN(30)

bool	pairing_auth_encrypt (PairingAuthCtx ctx, const uint8_t inbuf, size_t inlen, uint8_t outbuf, size_t outlen) __INTRODUCED_IN(30)

size_t	pairing_auth_safe_decrypted_size (PairingAuthCtx ctx, const uint8_t buf, size_t len) __INTRODUCED_IN(30)

bool	pairing_auth_decrypt (PairingAuthCtx ctx, const uint8_t inbuf, size_t inlen, uint8_t outbuf, size_t outlen) __INTRODUCED_IN(30)

Macro Definition Documentation

◆ __INTRODUCED_IN

#define __INTRODUCED_IN ( __api_level ) /* nothing */

Typedef Documentation

◆ PairingAuthCtx

typedef struct PairingAuthCtx PairingAuthCtx

Function Documentation

◆ pairing_auth_client_new()

PairingAuthCtx * pairing_auth_client_new	(	const uint8_t *	pswd,
		size_t	len
	)

Creates a new PairingAuthCtx instance as the client.

Parameters

pswd	the shared secret the server and client use to authenticate each other. Will abort if null.
len	the length of the pswd in bytes. Will abort if 0.

Returns: a new PairingAuthCtx client instance. Caller is responsible for destroying the context via pairing_auth_destroy.

◆ pairing_auth_decrypt()

bool pairing_auth_decrypt	(	PairingAuthCtx *	ctx,
		const uint8_t *	inbuf,
		size_t	inlen,
		uint8_t *	outbuf,
		size_t *	outlen
	)

Decrypts input data and writes the decrypted data into a user-provided buffer.

IMPORTANT: This will abort if either pairing_auth_init_cipher was not called or pairing_auth_init_cipher failed.

Parameters

ctx	the PairingAuthCtx instance. Will abort if null.
inbuf	the buffer containing the data to decrypt. Will abort if null.
inlen	the size of inbuf in bytes. WIll abort if 0.
outbuf	the buffer to write the decrypted data to. Will abort if null.
outlen	the size of outbuf in bytes. See pairing_auth_safe_decrypted_size. Will abort if 0.

Returns: true if all the data was decrypted and written to outbuf, false otherwise.

◆ pairing_auth_destroy()

void pairing_auth_destroy ( PairingAuthCtx * ctx )

Destroys the PairingAuthCtx.

Parameters

ctx	the PairingAuthCtx instance to destroy. Will abort if null.

◆ pairing_auth_encrypt()

bool pairing_auth_encrypt	(	PairingAuthCtx *	ctx,
		const uint8_t *	inbuf,
		size_t	inlen,
		uint8_t *	outbuf,
		size_t *	outlen
	)

Encrypts input data and writes the encrypted data into a user-provided buffer.

IMPORTANT: This will abort if either pairing_auth_init_cipher was not called or pairing_auth_init_cipher failed.

Parameters

ctx	the PairingAuthCtx instance. Will abort if null.
inbuf	the buffer containing the data to encrypt. Will abort if null.
inlen	the size of inbuf in bytes. Will abort if 0.
outbuf	the buffer to write the encrypted data to. Will abort if null
outlen	the size of outbuf in bytes. See pairing_auth_safe_encrypted_size.

Returns: true if all the data was encrypted and written to outbuf, false otherwise.

◆ pairing_auth_get_spake2_msg()

void pairing_auth_get_spake2_msg	(	PairingAuthCtx *	ctx,
		uint8_t *	out_buf
	)

Writes the SPAKE2 message to exchange with the other party to |out_buf|.

This is guaranteed to write a valid message to |out_buf|. Use pairing_auth_msg_size to get the size the |out_buf| should be. The SPAKE2 messages will be used to initialize the cipher for encryption/decryption (see pairing_auth_init_cipher).

Parameters

ctx	the PairingAuthCtx instance. Will abort if null.
out_buf	the buffer the message is written to. The buffer is assumed to be have at least pairing_auth_msg_size size. Will abort if out_buf is null.

◆ pairing_auth_init_cipher()

bool pairing_auth_init_cipher	(	PairingAuthCtx *	ctx,
		const uint8_t *	their_msg,
		size_t	msg_len
	)

Processes the peer's |their_msg| and attempts to initialize the cipher for encryption.

You can only call this method ONCE with a non-empty |msg|, regardless of success or failure. On success, you can use the pairing_auth_decrypt and pairing_auth_encrypt methods to exchange any further information securely. On failure, this PairingAuthCtx instance has no more purpose and should be destroyed.

Parameters

ctx	the PairingAuthCtx instance. Will abort if null.
their_msg	the peer's SPAKE2 msg. See #pairing_auth_get_msg. Will abort if null.
msg_len	the length of their_msg in bytes. Will abort if 0.

Returns: true iff the client and server used the same password when creating the PairingAuthCtx. See https: *commondatastorage.googleapis.com/chromium-boringssl-docs/curve25519.h.html::SPAKE2 for more details on the SPAKE2 protocol.

◆ pairing_auth_msg_size()

size_t pairing_auth_msg_size ( PairingAuthCtx * ctx )

Returns the exact size of the SPAKE2 msg.

Use this size as the buffer size when retrieving the message via #pairing_auth_get_msg.

Parameters

ctx	the PairingAuthCtx instance. Will abort if null.

Returns: the size of the SPAKE2 message in bytes. This is guaranteed to be > 0.

◆ pairing_auth_safe_decrypted_size()

size_t pairing_auth_safe_decrypted_size	(	PairingAuthCtx *	ctx,
		const uint8_t *	buf,
		size_t	len
	)

Returns a safe buffer size for decrypting data of a certain size.

IMPORTANT: This will abort if either pairing_auth_init_cipher was not called or pairing_auth_init_cipher failed.

Parameters

ctx	the PairingAuthCtx instance. Will abort if null.
buf	the buffer containing the encrypted data. Will abort if null.
len	the size of the buf in bytes. Will abort if 0.

Returns: the minimum buffer size, in bytes, to hold a decrypted message of size len. See pairing_auth_decrypt for usage.

◆ pairing_auth_safe_encrypted_size()

size_t pairing_auth_safe_encrypted_size	(	PairingAuthCtx *	ctx,
		size_t	len
	)

Returns a safe buffer size for encrypting data of a certain size.

IMPORTANT: This will abort if either pairing_auth_init_cipher was not called or pairing_auth_init_cipher failed.

Parameters

ctx	the PairingAuthCtx instance. Will abort if null.
len	the size of the message wanting to encrypt in bytes.

Returns: the minimum buffer size, in bytes, to hold an encrypted message of size len. See pairing_auth_encrypt for usage.

◆ pairing_auth_server_new()

PairingAuthCtx * pairing_auth_server_new	(	const uint8_t *	pswd,
		size_t	len
	)

Creates a new PairingAuthCtx instance as the server.

Parameters

pswd	the shared secret the server and client use to authenticate each other. Will abort if null.
len	the length of the pswd in bytes. Will abort if 0.

Returns: a new PairingAuthCtx server instance. Caller is responsible for destroying the context via pairing_auth_destroy.

Macros

Typedefs

Functions

Macro Definition Documentation

◆ __INTRODUCED_IN

Typedef Documentation

◆ PairingAuthCtx

Function Documentation

◆ pairing_auth_client_new()

◆ pairing_auth_decrypt()

◆ pairing_auth_destroy()

◆ pairing_auth_encrypt()

◆ pairing_auth_get_spake2_msg()

◆ pairing_auth_init_cipher()

◆ pairing_auth_msg_size()

◆ pairing_auth_safe_decrypted_size()

◆ pairing_auth_safe_encrypted_size()

◆ pairing_auth_server_new()