SABER key distribution

Typedefs
typedef struct saber_st *	saber_t
	Saber algorithm instance handle. More...

Enumerations
enum	saber_parameterset_t { saber_classic , saber_lightsaber , saber_firesaber , saber_last }
	Possible saber parameters sets. More...

Functions
PQLR_API saber_t	saber_new (saber_parameterset_t parameterset)
	Creates saber instance initialized by parameterset. More...
PQLR_API void	saber_free (saber_t saber)
	Frees saber instance and all corresponding resources. More...
PQLR_API saber_t	saber_duplicate (const saber_t saber)
	duplicates context of saber algorithm More...
PQLR_API uint32_t	saber_get_initiator_public_length (saber_t saber)
	Obtains initiator's public key length for the current saber instance. More...
PQLR_API uint32_t	saber_get_initiator_secret_length (saber_t saber)
	Obtains initiator's secret key length for the current saber instance. More...
PQLR_API uint32_t	saber_get_ciphertext_length (saber_t saber)
	Obtains ciphertext (request) length for the current saber instance. More...
PQLR_API uint32_t	saber_get_shared_secret_length (saber_t saber)
	Obtains shared secret (key) length for the current saber instance. More...
PQLR_API pqlr_t	saber_to_pqlr (saber_t saber)
	Casts saber instance to pqlr instance. More...
PQLR_API void	saber_keygen (const saber_t saber, uint8_t *public_key, uint8_t *secret_key)
	Initial step of key distribution. Generates a key pair for key distribution initiator. More...
PQLR_API void	saber_key_encap (const saber_t saber, const uint8_t *public_key, uint8_t *ciphertext, uint8_t *session_key)
	Second step of key distribution. Encapsulates key on the responder side. More...
PQLR_API void	saber_key_decap (const saber_t saber, const uint8_t *secret_key, const uint8_t *ciphertext, uint8_t *session_key)
	Last step of key distribution. Decapsulates key on the initiator side. More...

Detailed Description

This module provides SABER algorithm implementation, which is finite state machine for secure distribution of secret between two counterparties. The distributed secret is theoretically tolerant to attacks performed by quantum computers. Entry point is saber_keygen

General usage

Key distribution algorithms consist of sequential function calls on two sides named initiator and responder.

1. Both sides call saber_new, algorithm context is initialized with chosen parameterset
2. Initiator calls saber_keygen, initiator's public and secret keys are generated
3. Initiator sends public key to responder
4. Responder calls saber_key_encap, gets encoded request, key
5. Responder sends request to initiator
6. Initiator calls saber_key_decap, gets key
7. Both sides have similar cryptographically secure key
8. If no more key distribution required resources must be made free on both side by newhope_free

Note

In client-server applications client can represent initiator side, whereas server represents responder side, or vice versa.

In order to use any SABER key distribution functions, add the following include:

#include <pqlr/saber/saber.h>

Example code is listed below:

#include <pqlr/saber/saber.h>
#include <stdint.h>
#include <stdlib.h>
#include <stdio.h>
 
void print_key(const char* message, uint8_t* key, uint32_t key_size)
{
    uint8_t i = 0;
    printf("%s", message);
 
    for (; i < key_size; ++i) {
        printf("%.2X", key[i]);
    }
    printf("\n");
}
 
 
int main(int argc, char* argv[])
{
    // saber internal context and parameters
    // Context should be initialized before usage
    saber_t saber = saber_new(saber_classic);
 
    // server side context
    uint8_t* public_key =
        (uint8_t*)malloc(saber_get_initiator_public_length(saber));
    uint8_t* secret_key =
        (uint8_t*)malloc(saber_get_initiator_secret_length(saber));
    uint8_t* server_side_key = (uint8_t*)calloc(
        saber_get_shared_secret_length(saber), sizeof(uint8_t));
 
    // client side context
    uint8_t* ciphertext = (uint8_t*)malloc(saber_get_ciphertext_length(saber));
    uint8_t* client_side_key = (uint8_t*)calloc(
        saber_get_shared_secret_length(saber), sizeof(uint8_t));
 
    // prepare server's secret and public keys
    saber_keygen(saber, public_key, secret_key);
 
    // ... public_key is transferred from server to client by insecure channel
 
    // generate secret key on the client side based on non encoded public_key
    // received from server, also generate non secret reply ciphertext
    // to be sent back to server
    saber_key_encap(saber, public_key, ciphertext, client_side_key);
 
    // ... ciphertext is transferred from client to server by insecure channel
 
    // generate secret key on the server side
    saber_key_decap(saber, secret_key, ciphertext, server_side_key);
 
    // client and server keys will be the same
    print_key(
        "Server side: ", server_side_key,
        saber_get_shared_secret_length(saber));
    print_key(
        "Client side: ", client_side_key,
        saber_get_shared_secret_length(saber));
 
    // Don't forget to free resources after use
    free(public_key);
    free(secret_key);
    free(server_side_key);
    free(client_side_key);
    free(ciphertext);
 
    saber_free(saber);
 
    return 0;
}

Typedef Documentation

saber_t

typedef struct saber_st* saber_t

Saber algorithm instance handle.

Note

It could be casted to pqlr_t instance linked to this handle

See also

saber_to_pqlr

Enumeration Type Documentation

saber_parameterset_t

enum saber_parameterset_t

Possible saber parameters sets.

Enumerator
saber_classic
saber_lightsaber
saber_firesaber
saber_last

Function Documentation

saber_duplicate()

PQLR_API saber_t saber_duplicate

(

const saber_t

saber

)

duplicates context of saber algorithm

Parameters

[in]

saber

instance to duplicate

See also

saber_t

Returns

new instance with duplicated context

saber_free()

PQLR_API void saber_free

(

saber_t

saber

)

Frees saber instance and all corresponding resources.

Parameters

[in]

saber

instance to free

See also

saber_t

saber_new

saber_get_ciphertext_length()

PQLR_API uint32_t saber_get_ciphertext_length

(

saber_t

saber

)

Obtains ciphertext (request) length for the current saber instance.

Parameters

[in]

saber

initialized saber instance

See also

saber_t

saber_new

Returns

ciphertext length

saber_get_initiator_public_length()

PQLR_API uint32_t saber_get_initiator_public_length

(

saber_t

saber

)

Obtains initiator's public key length for the current saber instance.

Parameters

[in]

saber

initialized saber instance

See also

saber_t

saber_new

Returns

initiator's public key length

saber_get_initiator_secret_length()

PQLR_API uint32_t saber_get_initiator_secret_length

(

saber_t

saber

)

Obtains initiator's secret key length for the current saber instance.

Parameters

[in]

saber

initialized saber instance

See also

saber_t

saber_new

Returns

initiator's secret key length

saber_get_shared_secret_length()

PQLR_API uint32_t saber_get_shared_secret_length

(

saber_t

saber

)

Obtains shared secret (key) length for the current saber instance.

Parameters

[in]

saber

initialized saber instance

See also

saber_t

saber_new

Returns

shared secret length

saber_key_decap()

PQLR_API void saber_key_decap	(	const saber_t	saber,
		const uint8_t *	secret_key,
		const uint8_t *	ciphertext,
		uint8_t *	session_key
	)

Last step of key distribution. Decapsulates key on the initiator side.

Parameters

[in]	saber	Saber algorithm context. If NULL, the fatal error occurs.
[in]	secret_key	Secret key buffer ( saber_keygen ). Must point to array of uint8_t with elements count at least saber_get_initiator_secret_length. If NULL, the fatal error occurs.
[in]	ciphertext	Encoded request from the responder. Must point to array of uint8_t, with elements count at least saber_get_ciphertext_length. If NULL, the fatal error occurs.
[out]	session_key	Distributed key, equal to the key to be obtained on the responder side. Must point to array of uint8_t, with elements count at least saber_get_shared_secret_length. If NULL, the fatal error occurs.

See also

saber_new

saber_keygen

saber_key_encap

saber_key_encap()

PQLR_API void saber_key_encap	(	const saber_t	saber,
		const uint8_t *	public_key,
		uint8_t *	ciphertext,
		uint8_t *	session_key
	)

Second step of key distribution. Encapsulates key on the responder side.

Parameters

[in]	saber	Saber algorithm context. If NULL, the fatal error occurs.
[in]	public_key	Public key buffer ( saber_keygen ). Must point to array of uint8_t with elements count at least saber_get_initiator_public_length. If NULL, the fatal error occurs.
[out]	ciphertext	Encoded request from the responder. Must point to array of uint8_t, with elements count at least saber_get_ciphertext_length. If NULL, the fatal error occurs.
[out]	session_key	Distributed key, equal to the key to be obtained on the initiator side. Must point to array of uint8_t, with elements count at least saber_get_shared_secret_length. If NULL, the fatal error occurs.

See also

saber_new

saber_keygen

saber_get_initiator_public_length

saber_get_ciphertext_length

saber_get_shared_secret_length

saber_t

saber_keygen()

PQLR_API void saber_keygen	(	const saber_t	saber,
		uint8_t *	public_key,
		uint8_t *	secret_key
	)

Initial step of key distribution. Generates a key pair for key distribution initiator.

Note

Called on initiator side.

Parameters

[in]	saber	Saber algorithm context. If NULL, the fatal error occurs.
[out]	public_key	Public key buffer. Must point to array of uint8_t with elements count at least saber_get_initiator_public_length. If NULL, the fatal error occurs.
[out]	secret_key	Secret key buffer. Must point to array of uint8_t with elements count at least saber_get_initiator_secret_length. If NULL, the fatal error occurs.

See also

saber_new

saber_get_initiator_public_length

saber_get_initiator_secret_length

saber_t

saber_new()

PQLR_API saber_t saber_new

(

saber_parameterset_t

parameterset

)

Creates saber instance initialized by parameterset.

Note

Called on both sides.

Parameters

[in]

parameterset

Saber configuration parameters set (see saber_parameterset_t for availible options).

See also

saber_parameterset_t

saber_t

saber_free

Returns

new saber instance or NULL if out of memory

saber_to_pqlr()

PQLR_API pqlr_t saber_to_pqlr

(

saber_t

saber

)

Casts saber instance to pqlr instance.

Parameters

[in]

saber

initialized saber instance

Note

this pqlr instance will be released by saber_free

See also

saber_t

pqlr_t

saber_free

Returns

operable pqlr instance or NULL if saber is NULL