PQLR  dev-1426-v1.4-474-b578073a
Postquantum Crypto Library by QAPP
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_encapsulate (const saber_t saber, const uint8_t *public_key, uint8_t *encoded_request, uint8_t *key)
 Second step of key distribution. Encapsulates key on the responder side. More...
 
PQLR_API void saber_decapsulate (const saber_t saber, const uint8_t *secret_key, const uint8_t *encoded_request, uint8_t *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_encapsulate, gets encoded request, key
  5. Responder sends request to initiator
  6. Initiator calls saber_decapsulate, 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:

Example code is listed below:

#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
// 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_encapsulate(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_decapsulate(saber, secret_key, ciphertext, server_side_key);
// client and server keys will be the same
print_key(
"Server side: ", server_side_key,
print_key(
"Client side: ", client_side_key,
// 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

Possible saber parameters sets.

Enumerator
saber_classic 
saber_lightsaber 
saber_firesaber 
saber_last 

Function Documentation

◆ saber_decapsulate()

PQLR_API void saber_decapsulate ( const saber_t  saber,
const uint8_t *  secret_key,
const uint8_t *  encoded_request,
uint8_t *  key 
)

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

Parameters
[in]saberSaber algorithm context. If NULL, the fatal error occurs.
[in]secret_keySecret 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]encoded_requestEncoded 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]keyDistributed 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_encapsulate

◆ saber_duplicate()

PQLR_API saber_t saber_duplicate ( const saber_t  saber)

duplicates context of saber algorithm

Parameters
[in]saberinstance to duplicate
See also
saber_t
Returns
new instance with duplicated context

◆ saber_encapsulate()

PQLR_API void saber_encapsulate ( const saber_t  saber,
const uint8_t *  public_key,
uint8_t *  encoded_request,
uint8_t *  key 
)

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

Parameters
[in]saberSaber algorithm context. If NULL, the fatal error occurs.
[in]public_keyPublic 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]encoded_requestEncoded 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]keyDistributed 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_free()

PQLR_API void saber_free ( saber_t  saber)

Frees saber instance and all corresponding resources.

Parameters
[in]saberinstance 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]saberinitialized 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]saberinitialized 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]saberinitialized 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]saberinitialized saber instance
See also
saber_t
saber_new
Returns
shared secret length

◆ 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]saberSaber algorithm context. If NULL, the fatal error occurs.
[out]public_keyPublic 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_keySecret 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]parametersetSaber 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]saberinitialized 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